docs: explain when app background work stops

apps/dashboard/src/components/apps/app-activation.tsx

@@ -10,9 +10,16 @@ import type { AppSummary } from '#queries/apps.ts';
  */
 export function AppActivation({ app }: { app: AppSummary }) {
   return (
-    <div className="flex items-center justify-between gap-4">
-      <span className="text-muted-foreground">Activation</span>
-      <span>{activationSummary(app)}</span>
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center justify-between gap-4">
+        <span className="text-muted-foreground">Activation</span>
+        <span>{activationSummary(app)}</span>
+      </div>
+      {app.activation === 'on-request' && (
+        <p className="text-muted-foreground text-xs">
+          Background work pauses during sleep. Activation isn’t configurable for now.
+        </p>
+      )}
     </div>
   );
 }

apps/dashboard/src/components/deploy/deploy-dialog-content.tsx

@@ -79,6 +79,6 @@ export function DeployDialogContent({
 
 function describeDeploy(newApp: boolean): string {
   return newApp
-    ? 'The binary is uploaded to the store, then released as what the app runs.'
+    ? 'New apps sleep after five minutes without incoming traffic. Background jobs and timers do not run while asleep; activation cannot currently be changed.'
     : 'The app is released again with whatever this leaves it set to. A binary replaces the one it runs; without one, it keeps it.';
 }

apps/www/public/llms.txt

@@ -66,8 +66,11 @@ listen on it, on `0.0.0.0`.
 
 One microVM per app: no horizontal scaling, no load balancing. A deploy stops the old VM before
 starting the new one, so it is a few seconds of downtime rather than blue/green. An app sleeps
-after five minutes idle and wakes on the next request in ~120 ms. It fits a single-binary app that
-owns its own state; it does not fit anything that has to be several machines.
+after five minutes without incoming traffic and wakes on the next request in ~120 ms.
+Background jobs, timers, scheduled emails and outbound polling do not run while it sleeps.
+Owners cannot change activation through the CLI, API or dashboard. Apps that need background
+work to run on schedule are not currently a fit. It fits a single-binary app that owns its own
+state; it does not fit anything that has to be several machines.
 
 ## Links
 

packages/cli/src/commands/apps/update.ts

@@ -10,7 +10,7 @@ import { updateApp } from '#lib/update.ts';
 
 export const command = defineCommand('apps update', {
   description:
-    'Change how the app starts and run it again on the binary it already has. Nothing is uploaded, and whatever no flag names is left as it is.',
+    'Change how the app starts and run it again on the binary it already has. Nothing is uploaded, and whatever no flag names is left as it is. Activation cannot currently be changed: on-request apps sleep without incoming traffic, and background jobs and timers do not run while asleep.',
   options: {
     args: {
       schema: z.string().optional(),

packages/cli/src/commands/run/[command].ts

@@ -80,6 +80,12 @@ export const command = defineCommand('run [command]', {
       ? await completeOptions({ api, options: given, binarySource, args })
       : given;
 
+    if (resolved.app === undefined) {
+      ui.step(
+        'New apps sleep after five minutes without incoming traffic. Background jobs and timers do not run while asleep; activation cannot currently be changed.',
+      );
+    }
+
     emit(await deploy({ ...resolved, api, ui, binary, args, detach }));
   },
 });

skills/deploy-to-nibrun/SKILL.md

@@ -232,6 +232,10 @@ nib apps update --app my-app --extra-public-port --env 'ANNOUNCED_IP=${NIBRUN_PU
 
 Worth saying out loud before recommending it:
 
+- **New apps sleep after five minutes without incoming traffic.** The next request wakes them.
+  Background jobs, timers, scheduled emails and outbound polling do not run while an app sleeps,
+  and outbound work does not keep it awake. Owners cannot change activation through the CLI, API
+  or dashboard. An app that needs background work to run on schedule is not currently a fit.
 - **One microVM per app, one size.** No horizontal scaling, no load balancing, no resizing.
 - **A deploy is a replace.** The old VM is stopped before the new one starts, because they share
   one volume — so there are a few seconds of downtime, and no blue/green or canary.