docs(fleets): correct lifecycle/status to wire truth, de-dup install

[indykish]

What

Adversarial audit of the fleets docs against ground truth — the agentsfleet daemon (Zig), the CLI, and public/openapi.json — scoped to three end-user journeys: install a fleet, learn about a fleet, run the guided fleet (= installing a catalogue template; there is no separate "built-in/guided" feature in code).

Fixes

#	File	Fix	Evidence
F3	running.mdx	status sample alive → active	cli fleet.ts:108 prints raw z.status; enum has no alive
F4	overview.mdx	lifecycle rebuilt to real statuses + added paused (steer → UZ-AGT-012, webhook → 200 {"ignored":"fleet_paused"}); dropped invented Processing/Deleted statuses	config_types.zig, error_entries.zig
F5	running.mdx	status output → real key-value shape (no ID column/border)	fleet.ts printSection+printKeyValue
F6	running.mdx	documented steer interactive session (> prompt, exit 130, stdin pipe)	lib/repl.ts
F7	templates.mdx	default API wake states $1.00/day budget	create.zig:29
F8	running.mdx	replaced duplicated install section + exit-code table with a pointer to fleets/install	de-duplication
—	overview.mdx, templates.mdx	cross-linked Quickstart as the guided first run	—

Verified-correct, left untouched

The adversarial pass also cleared (and thus protected) several claims a scout pass had wrongly flagged:

• install/running exit-code tables match the CLI EXIT_CODE map exactly (1=auth, 2=net, 3=server, 4=validation, 5=config).
• UZ-BUNDLE-003 pre-install credential gate is real (create.zig:154 ensureBundleCredentials); UZ-AGT-006, UZ-WH-001 real.
• integration-requests / workspaces/{id}/events already present in docs.json.

Out of scope (flagged, not dropped)

• Event statuses (received/processed/fleet_error/gate_blocked) and approval-gate lifecycle have no user-facing concept page — follow-up candidate.
• Runner registration (operator plane) is correctly absent from the end-user fleets docs.

Verification

npx mintlify validate ✓ · npx mintlify broken-links ✓ · gitleaks ✓. Net −5 lines.

🤖 Generated with Claude Code

Greptile Summary

This PR corrects the fleets documentation against daemon ground truth: status values (alive → active), the status command output shape, and the lifecycle diagram — dropping invented Processing/Deleted states and adding the real server-set paused state. It also de-duplicates the install section in running.mdx with a pointer to /fleets/install, documents the interactive steer REPL session, and cross-links the Quickstart from both overview.mdx and templates.mdx.

• overview.mdx: Lifecycle rebuilt with real status enum (active, paused, stopped, killed); mermaid diagram updated; paused state described with its server-only semantics, error codes (UZ-AGT-012, 200 {\"ignored\":\"fleet_paused\"}), and auto-resume behaviour.
• running.mdx: Status sample corrected to key-value shape; duplicated install block replaced with a cross-reference; interactive steer session (> prompt, Ctrl-C exits 130, stdin pipe) documented.
• templates.mdx: $1.00/day default-API-wake budget cap added for --template installs; Quickstart tip inserted at the top.

Confidence Score: 5/5

Safe to merge — all changes are documentation corrections backed by CLI and daemon source evidence; no logic or configuration is affected.

The changes replace invented status names and UI shapes with values verified against the daemon source and CLI. The de-duplication and cross-linking are mechanical and low-risk. The one minor omission (missing budget-cap note in the local-bundle path) is a docs inconsistency only, with no runtime impact.

fleets/templates.mdx — the $1.00/day budget cap note is present for --template installs but absent from the --from local-bundle description.

Important Files Changed

Filename	Overview
fleets/overview.mdx	Lifecycle section rebuilt with real status values (active/paused/stopped/killed), paused state added with correct server-only semantics, mermaid diagram updated to match; Quickstart card added to What's next.
fleets/running.mdx	Install section de-duplicated with pointer to /fleets/install; status output corrected to key-value shape with active replacing alive; interactive steer session documented.
fleets/templates.mdx	Quickstart tip added, $1.00/day default-API-wake budget cap documented for --template installs; same cap omitted from the --from local-bundle path description, creating a minor inconsistency.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Install["agentsfleet install\n(--from or --template)"] --> Active["active\nwebhook live"]
    Active -->|"event: run then exit"| Active
    Active -->|"rate limit / circuit breaker\n(server-set)"| Paused["paused\nUZ-AGT-012 / 200 fleet_paused"]
    Paused -->|"auto-resume or\nagentsfleet resume"| Active
    Active -->|"agentsfleet stop"| Stopped["stopped\nreversible"]
    Stopped -->|"agentsfleet resume"| Active
    Active -->|"agentsfleet kill"| Killed["killed\nterminal"]
    Stopped -->|"agentsfleet kill"| Killed
    Killed -->|"agentsfleet delete"| Deleted(["deleted\nrow removed"])

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart LR
    Install["agentsfleet install\n(--from or --template)"] --> Active["active\nwebhook live"]
    Active -->|"event: run then exit"| Active
    Active -->|"rate limit / circuit breaker\n(server-set)"| Paused["paused\nUZ-AGT-012 / 200 fleet_paused"]
    Paused -->|"auto-resume or\nagentsfleet resume"| Active
    Active -->|"agentsfleet stop"| Stopped["stopped\nreversible"]
    Stopped -->|"agentsfleet resume"| Active
    Active -->|"agentsfleet kill"| Killed["killed\nterminal"]
    Stopped -->|"agentsfleet kill"| Killed
    Killed -->|"agentsfleet delete"| Deleted(["deleted\nrow removed"])

Loading

Comments Outside Diff (1)

1. fleets/running.mdx, line 8 (link)

   Stale --from <path> reference in intro paragraph

   The overview sentence still reads `install --from <path>` brings a fleet up, but the dedicated install section now covers both --from and --template. A reader scanning this line first gets the impression only --from exists, which contradicts the section body added a few lines below.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: fleets/running.mdx
   Line: 8
   
   Comment:
   **Stale `--from <path>` reference in intro paragraph**
   
   The overview sentence still reads `` `install --from <path>` brings a fleet up ``, but the dedicated install section now covers both `--from` and `--template`. A reader scanning this line first gets the impression only `--from` exists, which contradicts the section body added a few lines below.
   
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

_{Reviews (2): Last reviewed commit: "docs(fleets): address greptile review on..." | Re-trigger Greptile}

[indykish]

Addressed all four review points in f4506a0:

1. Stale --from in intro — intro now reads install (from a local --from <path> or a catalogue --template), matching the section body.
2. agentsfleet list unverified — confirmed it's a real verb (cli/src/program/cli-tree-fleet.ts:163, documented at cli/agentsfleet.mdx) and linked it to /cli/agentsfleet#agentsfleet-list.
3. Binary name formatting — backticked agentsfleet in the steer note.
4. Item 5 formatting — changed to delete for consistency with items 1–4; the intro already clarifies deleted is not a status value.

mintlify broken-links (incl. the new anchor) + gitleaks: clean.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentsfleet	🔴 Failed	–	Jun 24, 2026, 4:55 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.