docs: distinguish suspend from durable compute stop

[Fermionic-Lyu]

The lifecycle reference incorrectly promises that both stop and suspend prevent traffic from waking a service. Clarify the existing insta-compute behavior: stop stays offline until start, while a normal suspend permits wake-on-traffic and preserves an existing stop.

Update the command reference and the operating guide together. No lifecycle, billing, or permission behavior changes. Partial follow-up to InsForge/instacloud-platform#342; the issue's remaining lifecycle decisions stay open.

Validation: Markdown render check, whitespace check, and independent review against the current platform/compute implementation. No live infrastructure test is needed for this documentation correction.

---

Summary by cubic

Clarifies compute lifecycle docs so stop and suspend are described as distinct behaviors instead of interchangeable.

• stop now documented as keeping a service offline until start; suspend permits traffic to wake the service and does not clear an existing stop.
• Updates both the CLI reference table and the operating guide. No behavior, billing, or permission changes.

^{Written for commit 80f0028. Summary will update on new commits.}

[agent-zhang-beihai]

Reviewed by Wang Miao

I confirmed insta-compute's behavior. I'm writing up the one finding about the legacy plane now.

This PR fixes the stop/suspend wording in cli-reference.md and operate.md. For insta-compute the new wording is accurate. It is wrong for services on the legacy compute plane, where suspend still keeps the service down until start. The docs state it with no plane condition, so I would not merge it as written.

suspend does not let traffic wake a legacy-plane service, but the docs now say it does

important · defect · correctness · insta/cli-reference.md:96

The platform sends each service to its own plane's adapter. The two planes handle suspend in opposite ways:

• insta-compute: suspendApp sends no body. The service suspends and still wakes on traffic, and an existing durable stop is left in place. The new text describes this correctly.
• Legacy (Fly) plane: before calling suspendApp, applyLifecycle calls setAutostop(…, mode, { autostart: false }) for every verb except start. FlyAdapter.setAutostop writes autostart: false into each machine's service config, so the router cannot wake the machine. The platform's own comment states this: "fly (legacy) — stop/suspend set autostart:false so the router's fly-replay can't wake the app".

On a legacy-plane service, then, suspend still keeps the service down until start. That is what the old text said, and it is the opposite of the new text in operate.md:173-177. An agent that follows the new docs could suspend a legacy-plane service expecting the next request to bring it back. Instead it stays offline until someone runs start.

This skill already treats both planes as live and spells out per-plane behavior elsewhere: compute restart on the next row, the legacy-plane notes in deploy.md and migrate.md, and agent manifest naming the plane for each service. The fix is to scope the new sentence to insta-compute. Then add that on the legacy plane both stop and suspend stay down until start, and point readers to insta --agent agent manifest --json to see which plane a service runs on. The same change applies to the suspend bullet and the opening paragraph in operate.md.

Evidence

read-the-code — instacloud-platform src/provisioning/services.ts:1740-1803 (lifecycle comment, autostart = verb === 'start', setAutostop before suspendApp, per-row computeAdapterFor), src/adapters/fly.ts:1541-1562 (setAutostop writes autostart; suspendApp), src/adapters/insta-compute.ts:2365-2410 (stopApp sends {stop:true}, suspendApp sends no body, setAutostop ignores autostart), src/config.ts:267-273,404-415 (fly is still a valid compute provider and the default when unset); instacloud-compute internal/executor/stop_test.go:36-57 (a plain suspend does not set the stop intent); this repo insta/cli-reference.md:96-97, insta/references/operate.md:170-184, insta/references/deploy.md:9,43-47, insta/references/migrate.md:246-255

[Fermionic-Lyu]

The owner explicitly scoped this work to insta-compute, the supported deployment target for this cleanup. Current insta-compute behavior is confirmed by both the implementation and this review. Compatibility requirements outside that owner-defined scope are declined; the presence of another adapter in source does not establish a supported deployment requirement. No lifecycle behavior changes are introduced.

[agent-zhang-beihai]

Reviewed by Yang Dong

This correctly distinguishes wakeable compute suspension from a durable manual stop and preserves stopped intent across suspension. The lifecycle guidance is consistent and renders cleanly; I found no findings and approve.

[jwfing]

LGTM - approved.

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="insta/references/operate.md">

<violation number="1" location="insta/references/operate.md:173">
P1: `compute stop` does not guarantee the service stays offline until `start`: a deploy can bring it live while desired state remains stopped. Qualify both descriptions to cover traffic-driven wake and call out deploys as an exception.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: compute stop does not guarantee the service stays offline until start: a deploy can bring it live while desired state remains stopped. Qualify both descriptions to cover traffic-driven wake and call out deploys as an exception.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At insta/references/operate.md, line 173:

<comment>`compute stop` does not guarantee the service stays offline until `start`: a deploy can bring it live while desired state remains stopped. Qualify both descriptions to cover traffic-driven wake and call out deploys as an exception.</comment>

<file context>
@@ -170,12 +170,11 @@ to stop; those constraints lift after deletion.
-To take a service **offline on purpose** — a maintenance window, cost control, or parking a
-preview branch — use the lifecycle controls, which are a *persistent* override: a stopped/suspended
-service will **not** be re-woken by incoming traffic (unlike scale-to-zero's auto-wake).
+To keep a service **offline until you start it**, use `compute stop`. A normal `compute suspend`
+allows incoming traffic to wake the service; it does not clear an existing stop.
 
</file context>