docs(architecture): sync install-flow to CLI-first template catalogue (retire skill onboarding)

[indykish]

Summary

The user-facing install wedge moved from the host-agent markdown skill (/agentsfleet-install-platform-ops, npx skills add agentsfleet/skills) to the agentsfleet CLI + the M94 fleet-bundle template catalogue (#438). These architecture docs still described the skill-orchestrated install; this aligns them with the shipped CLI path and the docs-repo rewrite (agentsfleet/docs#106).

What changed (docs/architecture/** only)

• user_flow.md §8.0 — reframed "the wedge surface" from the skill to the CLI + template catalogue (install --template / --from). Added a transitional note: the substrate calls (doctor, credential add, install --from, steer, the gh webhook registration) are unchanged — only the orchestration moved from the skill to the CLI + the user. §8.2.1 bootstrap drops npx skills add; §8.2.2 / §8.7 reattribute the doctor / credential / install / webhook-register / frontmatter steps. The §8.0 anchor is kept (#80-the-wedge-surface); the README.md link was updated to match.
• scenarios/01_default_install.md — rewrote the install half (mermaid, §1 / §1.1 steps, §3.1 terminal transcript, §4 takeaway) to the CLI + bundle flow. The §2 execution back-half (webhook → lease → billing → runner) is unchanged.
• scenarios/02_self_managed.md — the self-managed install fork is now attributed to the bundle's frontmatter sentinels; the overlay rule (model:"" / context_cap_tokens:0 → inherit at lease time) is unchanged.
• high_level.md, README.md, scenarios/README.md, billing_and_provider_keys.md, data_flow.md — install-skill → CLI / bundle terminology.

Not changed

• Memory architecture (capabilities.md §4, runner_fleet.md §Selection policy, direction.md) was already correct — no workspace category, "selected, not searched", core-pinned hydration, 72h daily prune, no vector search. The docs-repo memory page was aligned to it in docs: consolidate operator and contributor docs (M13_002) #106; no architecture change was needed.

Verification

Docs-only .md change: pre-commit gitleaks ✅ (harness-verify + lint lanes skip — no source surface touched); pre-push runs no test lanes.

Out of scope (separate handoffs)

The agentsfleet.dev installer (ui/agentsfleet.dev/dist/install.sh) and the website (ui/packages/website) still ship the skill flow — handoffs written for both.

🤖 Generated with Claude Code

Greptile Summary

This docs-only PR syncs docs/architecture/** to the shipped CLI-first install flow, retiring the skill-orchestrated wedge (/agentsfleet-install-platform-ops / npx skills add) in favour of the agentsfleet CLI plus the M94 template catalogue.

• user_flow.md §8.0–§8.2 is the core change: the wedge surface is reframed from a host-agent SKILL.md to direct CLI commands (install --template / --from), a transitional note acknowledges the prior approach, and all "install-skill" phrasing is replaced throughout.
• scenarios/01_default_install.md is fully rewritten for the CLI path — new mermaid diagram, revised install steps, and a new terminal transcript replacing the skill-driven walkthrough; the execution back-half (webhook → lease → billing → runner) is untouched.
• scenarios/02_self_managed.md, billing_and_provider_keys.md, data_flow.md, high_level.md, README.md, and scenarios/README.md each receive small, consistent terminology substitutions.

Confidence Score: 5/5

Safe to merge — all changes are documentation only with no source or schema surface touched.

Every changed file is a markdown doc under docs/architecture/. The rewrite is coherent and internally consistent; the two findings are wording gaps that won't break anything at runtime.

user_flow.md §8.0.1 (one unreplaced 'The skill' sentence) and scenarios/01_default_install.md §1.1 step 6 (HMAC self-verify failure-mode gap).

Important Files Changed

Filename	Overview
docs/architecture/user_flow.md	Major §8.0 / §8.2 rewrite retiring the skill wedge in favor of CLI + template catalogue; §8.0.1 has one unreplaced 'The skill' reference directly below the rewritten §8.0.
docs/architecture/scenarios/01_default_install.md	Install half fully rewritten to CLI + bundle flow; HMAC self-verify demoted from mandatory step to optional parenthetical with no failure-mode guidance and no trace in the sequence diagram or terminal transcript.
docs/architecture/scenarios/02_self_managed.md	Self-managed fork attribution moved from skill to bundle frontmatter sentinels; overlay rule and everything after §3 is unchanged.
docs/architecture/README.md	Table descriptions and anchor link updated to drop skill reference; straightforward and consistent.
docs/architecture/billing_and_provider_keys.md	Three targeted substitutions replacing 'install-skill' with CLI terminology; no semantic changes.
docs/architecture/data_flow.md	Two small terminology swaps ('user / install-skill' → 'user / agentsfleet CLI'; 'install-skill forwards' → 'user forwards'); correct.
docs/architecture/high_level.md	Single-line update replacing skill invocation reference with CLI + template catalogue; clean.
docs/architecture/scenarios/README.md	One-line table update removing 'install-skill writes' phrasing; consistent with the scenario rewrite.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Op as User (laptop)
    participant CLI as agentsfleet CLI
    participant API as agentsfleetd-api
    participant Runner as agentsfleet-runner
    participant GH as GitHub

    Note over Op,CLI: Bootstrap (once per machine)
    Op->>CLI: curl install + agentsfleet login (Clerk OAuth)
    Op->>CLI: agentsfleet doctor --json
    CLI->>API: GET /v1/me + workspace binding
    API-->>CLI: health OK

    Note over Op,CLI: Per-fleet install
    Op->>CLI: agentsfleet templates (browse catalogue)
    Op->>CLI: install --template id OR --from local/bundle/
    CLI->>API: "POST /v1/workspaces/{ws}/fleets"
    API->>API: "XGROUP CREATE fleet:{id}:events"
    API-->>CLI: "{ fleet_id, webhook_urls }"

    Op->>GH: gh api repos/.../hooks (HMAC secret + webhook URL)
    GH-->>Op: "{ id, active: true }"

    Op->>CLI: "agentsfleet steer {id} morning health check"
    CLI->>API: "POST /steer → XADD fleet:{id}:events"
    Runner->>API: POST /v1/runners/me/leases
    Runner-->>Op: streams steer response

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"}}}%%
sequenceDiagram
    participant Op as User (laptop)
    participant CLI as agentsfleet CLI
    participant API as agentsfleetd-api
    participant Runner as agentsfleet-runner
    participant GH as GitHub

    Note over Op,CLI: Bootstrap (once per machine)
    Op->>CLI: curl install + agentsfleet login (Clerk OAuth)
    Op->>CLI: agentsfleet doctor --json
    CLI->>API: GET /v1/me + workspace binding
    API-->>CLI: health OK

    Note over Op,CLI: Per-fleet install
    Op->>CLI: agentsfleet templates (browse catalogue)
    Op->>CLI: install --template id OR --from local/bundle/
    CLI->>API: "POST /v1/workspaces/{ws}/fleets"
    API->>API: "XGROUP CREATE fleet:{id}:events"
    API-->>CLI: "{ fleet_id, webhook_urls }"

    Op->>GH: gh api repos/.../hooks (HMAC secret + webhook URL)
    GH-->>Op: "{ id, active: true }"

    Op->>CLI: "agentsfleet steer {id} morning health check"
    CLI->>API: "POST /steer → XADD fleet:{id}:events"
    Runner->>API: POST /v1/runners/me/leases
    Runner-->>Op: streams steer response

Loading

_{Reviews (3): Last reviewed commit: "ci: re-trigger required checks on curren..." | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentsfleet-agents-dev	Ready	Preview, Comment	Jun 22, 2026 6:30am
agentsfleet-app	Ready	Preview, Comment	Jun 22, 2026 6:30am
agentsfleet-website	Ready	Preview, Comment	Jun 22, 2026 6:30am