docs: CLI-first install flow + accuracy sweep (memory, tooling, API, error codes)

api-reference/introduction.mdx

@@ -21,23 +21,23 @@ curl https://api.agentsfleet.net/v1/workspaces/0198a7b0-3c2d-7f14-9a08-1b6e4d2f8
 Two kinds of bearer token are accepted:
 
 - **Tenant API key (`agt_t…`)** — long-lived, for programmatic and service-to-service callers (CI, cron, integrations, scripts). Create one in the dashboard under **Settings → API keys**; the raw value is shown once. This is the right credential for calling the API directly.
-- **User JWT** — short-lived (~15 min), for an interactive human. Mint one with `agentsfleet login`, a browser device flow with terminal-side verification. It can't be obtained by a bare API client — the flow needs the dashboard's browser leg — so for unattended access use a tenant API key.
+- **User JWT** — short-lived, for an interactive human. Mint one with `agentsfleet login`, a browser device flow with terminal-side verification. It can't be obtained by a bare API client — the flow needs the dashboard's browser leg — so for unattended access use a tenant API key.
 
 ## Errors
 
 All errors use RFC 7807 problem detail (`Content-Type: application/problem+json`):
 
 ```json
 {
-  "docs_uri": "https://docs.agentsfleet.net/api-reference/error-codes#UZ-WORKSPACE-001",
-  "title": "Workspace not found",
-  "detail": "No workspace with the given ID exists.",
-  "error_code": "UZ-WORKSPACE-001",
+  "docs_uri": "https://docs.agentsfleet.net/api-reference/error-codes#UZ-AGT-009",
+  "title": "Fleet not found",
+  "detail": "No fleet with the given ID exists in this workspace.",
+  "error_code": "UZ-AGT-009",
   "request_id": "0198a7b6-1f2a-7d53-8c94-2b7e5a1f9d40"
 }
 ```
 
-Error codes follow the `UZ-<DOMAIN>-NNN` scheme in the `error_code` field. Every response includes a `request_id` for tracing. See [Error codes](/api-reference/error-codes) for the full registry.
+Error codes follow the `UZ-<DOMAIN>-NNN` scheme in the `error_code` field. Every response includes a `request_id` for tracing. On `409 Conflict` responses the body may carry an extra `current_state` field naming the resource's blocking state (e.g. `paused`). See [Error codes](/api-reference/error-codes) for the full registry.
 
 ## Conventions
 

cli/agentsfleet.mdx

@@ -67,7 +67,7 @@ Removes local credentials (`~/.config/agentsfleet/credentials.json`) and aborts
 agentsfleet logout
 ```
 
-Does **NOT** revoke your active session token — JWTs are short-lived (~15 min) and expire on their own. Does **NOT** touch the `AGENTSFLEET_API_KEY` environment variable — if it's set, subsequent commands continue to authenticate with that key (it overrides a stored login) until you unset it.
+Does **NOT** revoke your active session token — JWTs are short-lived and expire on their own. Does **NOT** touch the `AGENTSFLEET_API_KEY` environment variable — if it's set, subsequent commands continue to authenticate with that key (it overrides a stored login) until you unset it.
 
 ### `agentsfleet auth status`
 
@@ -91,13 +91,13 @@ The probe result is one of `valid` (200 from the billing endpoint), `unauthorize
 
 ### `agentsfleet install --from <path>`
 
-Reads `SKILL.md` and `TRIGGER.md` from `<path>`, validates them, and uploads to the active workspace. The two markdown files are the configuration; the `agentsfleet-install-platform-ops` host-agent skill is what generates them under `.agentsfleet/<fleet>/` in your repo. The `--from` flag is required — there are no bare-name template aliases.
+Reads `SKILL.md` and `TRIGGER.md` from `<path>`, validates them server-side, and uploads to the active workspace. `SKILL.md` is required; `TRIGGER.md` is optional (a default API wake is generated when it's absent). `install` needs exactly one source — `--from <path>` or `--template <id>`; there are no bare-name aliases.
 
 ```bash
-agentsfleet install --from ~/.config/agentsfleet/samples/platform-ops
+agentsfleet install --from ./my-fleet
 ```
 
-The `samples/` directory ships with `agentsfleet` and contains the flagship `platform-ops` sample. The host-agent install skill (`/agentsfleet-install-platform-ops`) drives this command under the hood. See [Quickstart](/quickstart) and [Templates](/fleets/templates).
+For a curated, ready-to-run fleet, use `agentsfleet install --template <id>` instead (browse with `agentsfleet templates`). See [Quickstart](/quickstart) and [Templates](/fleets/templates).
 
 ### `agentsfleet install --template <id>`
 
@@ -132,7 +132,7 @@ Prints a table of template id, name, and required credentials. Pass `--json` for
 Re-parse `SKILL.md` and `TRIGGER.md` from a local bundle and `PATCH` them onto an existing fleet — the in-place counterpart to `install`. Use it to roll a configuration change onto an already-registered fleet without re-creating it.
 
 ```bash
-agentsfleet fleet update 01900000-0000-7000-8000-000000000001 --from ~/.config/agentsfleet/samples/platform-ops
+agentsfleet fleet update 01900000-0000-7000-8000-000000000001 --from ./my-fleet
 ```
 
 | Flag | Default | Purpose |

cli/install.mdx

@@ -25,21 +25,23 @@ description: "Install the agentsfleet CLI."
   </Step>
 </Steps>
 
-## Fleet Skills
+## Install a fleet
 
-The `agentsfleet-install-platform-ops` skill is the guided install UX driven from a host agent (Claude Code, Amp, Codex CLI, OpenCode). Add the skills with one command:
+With the CLI installed, sign in and install a fleet from the template catalogue:
 
 ```bash
-npx skills add agentsfleet/skills
+agentsfleet login                              # browser approval + verification code
+agentsfleet templates                          # browse the catalogue
+agentsfleet install --template github-pr-reviewer
 ```
 
-This symlinks the `/agentsfleet-*` slash commands from the public [`agentsfleet/skills`](https://github.com/agentsfleet/skills) repo into every supported host's skill directory it detects on your machine — invoke `/agentsfleet-install-platform-ops` in your agent and you’re set. Pass `--host=<claude|amp|codex|opencode>` to target a single host instead of every detected one.
+Or install a local bundle you authored with `agentsfleet install --from <path>` (see [Authoring a fleet](/fleets/authoring)).
 
 <Tip>
-  **No global install?** `curl -fsSL https://agentsfleet.dev | bash` installs `agentsfleet` and the skill together in one command (requires Node — it runs npm under the hood). Run `curl -fsSL https://agentsfleet.dev` without `| bash` to read it first.
+  **One-line bootstrap.** `curl -fsSL https://agentsfleet.dev | bash` installs the `agentsfleet` CLI (it runs npm under the hood — Node required). Run `curl -fsSL https://agentsfleet.dev` without `| bash` to read it first.
 </Tip>
 
-The skill drives `agentsfleet install --from`, `agentsfleet credential`, `agentsfleet steer`, `agentsfleet logs`, and the doctor preflight under the hood. See [Quickstart](/quickstart) for the end-to-end flow.
+See [Quickstart](/quickstart) for the end-to-end flow from a cold machine.
 
 ## Verify installation
 
@@ -63,4 +65,4 @@ agentsfleet doctor
 | `workspace_selected` | The local config has a `current_workspace_id`. Auto-populated by `agentsfleet login` from your signup-provisioned default workspace; can also be set or replaced by `agentsfleet workspace add` / `workspace use`. |
 | `workspace_binding_valid` | The resolved auth token can read the selected workspace's fleets — i.e. it is bound to the right tenant. Reports a failed check (rather than aborting) when no token is present. |
 
-Pass `--json` for the structured `{ ok, api_url, checks: [...] }` envelope. Run it before any install — host-agent skills depend on this preflight. For the tenant's inference posture and free-trial window, use [`agentsfleet tenant provider show`](/cli/agentsfleet#tenant-provider).
+Pass `--json` for the structured `{ ok, api_url, checks: [...] }` envelope. Run it before installing a fleet to confirm connectivity and workspace selection. For the tenant's inference posture and free-trial window, use [`agentsfleet tenant provider show`](/cli/agentsfleet#tenant-provider).

fleets/authoring.mdx

@@ -36,7 +36,7 @@ model: claude-sonnet-4-6           # optional, hint
 | Field | Required | Purpose |
 |---|---|---|
 | `name` | yes | Identity. Must equal `TRIGGER.md` `name:` (install rejects mismatch). |
-| `description` | yes | One-line summary, ≤200 chars. |
+| `description` | yes | One-line summary. |
 | `version` | yes | Semver string. |
 | `when_to_use`, `tags`, `author`, `model` | no | Pass-through metadata. |
 
@@ -130,14 +130,14 @@ Validation under this block is rigid: an unknown subkey is rejected with a typo
 
 | Subkey | Required | Purpose |
 |---|---|---|
-| `triggers[]` | yes | Array of 1–8 trigger entries. The singular `trigger:` shape is rejected at install (`ERR_AGENTSFLEET_INVALID_CONFIG: use "triggers:" (array)`). Entries are unique on the `(type, source)` tuple; at most one `cron` entry. |
+| `triggers[]` | yes | Array of 1–8 trigger entries. The singular `trigger:` shape is rejected at install with `UZ-AGT-008` (invalid fleet config). Entries are unique on the `(type, source)` tuple; at most one `cron` entry. |
 | `triggers[].type` | yes | One of `webhook` \| `cron` \| `api`. See the table below. |
 | `triggers[].source` | per type | Required for `webhook`. Carries the upstream label (e.g. `github`, `slack`, `linear`) and selects the per-trigger URL `…/v1/webhooks/{fleet_id}/{source}` — see [Webhooks](/fleets/webhooks). |
 | `triggers[].events` | optional | Per-webhook event whitelist (1–16 entries, ≤64 chars each). Omit to accept every event the source delivers. |
 | `triggers[].signature.secret_ref` | optional | Vault key whose value verifies webhook signatures (first-class providers). |
 | `tools` | yes | Non-empty list of tool names from the [Tools catalogue](/fleets/tools). |
 | `credentials` | optional | Vault key names the fleet reads at event time. |
-| `network.allow` | yes | Outbound hostname allowlist enforced by the sandbox. |
+| `network.allow` | optional | Outbound hostname allowlist enforced by the sandbox. Omit it (or the whole `network:` block) for an empty allowlist — `http_request` then has no permitted hosts. |
 | `budget.daily_dollars` | yes | Rolling 24-hour dollar ceiling. |
 | `budget.monthly_dollars` | optional | Calendar-month dollar ceiling. |
 
@@ -157,7 +157,7 @@ A fleet can declare up to eight triggers and wake on any of them — e.g. one we
 
 The `tools:` list is the explicit allowlist of tools the fleet may invoke. A compromised or jailbroken fleet cannot reach outside this list.
 
-23 tools are user-callable today, grouped by category — network (`http_request`, `web_search`, `web_fetch`), memory (`memory_store`/`recall`/`list`/`forget`), cron (`cron_add`/`list`/`remove`/`update`/`run`/`runs`), fleet orchestration (`delegate`, `spawn`, `schedule`), browser, git, file edits, and stateless utilities. **See [Tools catalogue](/fleets/tools) for every tool with its purpose and use cases.**
+The runner exposes 32 built-in tools — network (`http_request`, `web_search`, `web_fetch`, `pushover`), memory (`memory_store`/`recall`/`list`/`forget`), cron (`cron_add`/`list`/`remove`/`update`/`run`/`runs`), fleet orchestration (`delegate`, `spawn`, `schedule`), browser, git, `shell` and the file tools, and stateless utilities. The list is deny-by-default — declare only what the fleet needs. **See [Tools catalogue](/fleets/tools) for every tool with its purpose and use cases.**
 
 ### Credentials
 
@@ -180,23 +180,21 @@ A breach terminates the in-flight event cleanly and records a `budget_breach` en
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `RuntimeKeysOutsideBlock` at install | `tools:`, `credentials:`, etc. at the top of TRIGGER.md | Indent them under `x-agentsfleet:`. |
-| `UnknownRuntimeKey` at install | Typo in a runtime subkey (e.g. `crendentials:` instead of `credentials:`) | Fix the spelling, or remove the key. Validation under `x-agentsfleet:` is strict. |
-| `name_mismatch` at install | SKILL.md and TRIGGER.md disagree on `name:` | One identity per bundle. Make both top-level `name:` values equal. |
-| `MissingRequiredField` for SKILL.md | `name`, `description`, or `version` missing from SKILL.md frontmatter | All three are required at the top level. |
+| `UZ-AGT-008` (invalid fleet config) | A runtime key (`tools:`, `credentials:`, `network:`, …) at the top of TRIGGER.md instead of nested; a typo'd subkey under `x-agentsfleet:`; a singular `trigger:`; or a malformed `name:` | Nest runtime keys under `x-agentsfleet:`, fix the spelling, use the `triggers:` array, and keep `name:` kebab-case (`^[a-z0-9-]+$`, 1–64 chars). Validation under `x-agentsfleet:` is strict — unknown subkeys are rejected. |
+| `UZ-AGT-011` (name mismatch) | SKILL.md and TRIGGER.md disagree on top-level `name:` | One identity per bundle. Make both `name:` values equal. |
+| Missing `name` / `description` / `version` in SKILL.md | A required frontmatter field is absent | All three are required at the top level of `SKILL.md`. |
 
 ## Validation
 
-`agentsfleet install --from <dir>` reads both files and posts them to the server, which runs the same parser the runtime uses. Errors are returned with the field at fault.
+`agentsfleet install --from <dir>` reads both files and posts them to the server, which runs the same parser the runtime uses — there is no separate local lint step. Errors come back as a `UZ-AGT-*` wire code with a suggestion.
 
 ```bash
 agentsfleet install --from ./my-fleet
 ```
 
 ```
-✗ install rejected: name_mismatch
-  SKILL.md name: platform-ops-fleet
-  TRIGGER.md name: platform-ops-zombe    ← typo
+UZ-AGT-011  SKILL.md and TRIGGER.md disagree on `name:`
+  Suggestion: make the top-level name: identical in both files
 ```
 
 ## Next

fleets/credentials.mdx

@@ -41,13 +41,20 @@ JSON
 
 The command POSTs to `/v1/workspaces/{workspace_id}/credentials` with the JSON body. Values are encrypted at rest; only the tool bridge can decrypt them when servicing an outbound call.
 
+<Note>
+  The vault stores any JSON object and does **not** validate field names. Shapes like `github` → `{api_token, webhook_secret}` or `slack` → `{bot_token}` are conventions your `SKILL.md` and `http_request` calls rely on — not a server-enforced schema. Keep the field names consistent with what your fleet expects.
+</Note>
+
 The default behaviour is **skip-if-exists** — passing the same name twice is a no-op. Use `--force` to overwrite an existing credential (rotation).
 
 Exit codes:
 
 - `0` — stored (or skip-if-exists).
-- `1` — no workspace selected, or API error.
-- `2` — missing `<name>`, missing `--data`, or invalid JSON.
+- `1` — not authenticated (re-run `agentsfleet login`).
+- `2` — network error reaching the API.
+- `3` — the API rejected the credential (e.g. `UZ-VAULT-001` empty / not an object, `UZ-VAULT-002` too large).
+- `4` — missing `<name>` or `--data`.
+- `5` — local config error, or `--data` input that isn't readable JSON.
 
 ## Listing credentials
 

fleets/install.mdx

@@ -6,7 +6,7 @@ description: "What `agentsfleet install --from <path>` does and how to invoke it
 `agentsfleet install --from <path>` is how you bring a fleet up. It reads `SKILL.md` and `TRIGGER.md` from the directory you point at, validates them, and uploads to your active workspace. **Install is the deploy** — there's no separate `up` step.
 
 ```bash
-agentsfleet install --from ~/.config/agentsfleet/samples/platform-ops
+agentsfleet install --from ./platform-ops
 ```
 
 ```
@@ -16,25 +16,20 @@ agentsfleet install --from ~/.config/agentsfleet/samples/platform-ops
     github: https://api.agentsfleet.net/v1/webhooks/0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71/github
 ```
 
-One URL is printed per declared `webhook` trigger in `TRIGGER.md`, keyed by `triggers[].source`. The host-agent install skill consumes this map and registers each URL on the upstream provider via the user's own `gh` (or equivalent) CLI — no paste-into-GitHub step. See [Quickstart](/quickstart) for the guided flow, or [Webhooks](/fleets/webhooks) if you maintain the upstream hook by hand.
+One URL is printed per declared `webhook` trigger in `TRIGGER.md`, keyed by `triggers[].source`. Register each URL on its upstream provider — on GitHub, **Settings → Webhooks** (or `gh api -X POST repos/<owner>/<repo>/hooks …`). See [Webhooks](/fleets/webhooks) for the signature config the platform expects.
 
 Re-running against the same workspace is safe — running it twice has the same effect as running it once. Your edits to `SKILL.md` / `TRIGGER.md` replace the previous version on the next event.
 
-## Two ways to invoke
+## Install from the catalogue instead
 
-Most users don't run `agentsfleet install --from` directly. They drive the install from a host agent (Claude Code, Amp, Codex CLI, OpenCode) via the `/agentsfleet-install-platform-ops` slash command. Add the skills with `npx skills add agentsfleet/skills`, which symlinks `/agentsfleet-*` into every supported host's skill directory it detects. Then invoke the slash command in your host agent:
+To start from a curated, ready-to-run fleet rather than a local directory, install a [template](/fleets/templates) by id:
 
+```bash
+agentsfleet templates                          # browse the catalogue
+agentsfleet install --template github-pr-reviewer
 ```
-/agentsfleet-install-platform-ops
-```
-
-<Tip>
-  **No global install?** `curl -fsSL https://agentsfleet.dev | bash` installs `agentsfleet` and the skill together in one command (requires Node — it runs npm under the hood). Run `curl -fsSL https://agentsfleet.dev` without `| bash` to read it first.
-</Tip>
-
-The slash command asks three gating questions (Slack channel, production branch glob, optional cron schedule), registers the webhook via your existing `gh` CLI, and prints a per-trigger registration summary at the end. See [Quickstart](/quickstart) for the full walkthrough.
 
-Power users and scripted setups call `agentsfleet install --from <path>` directly — the same flow as the slash command, minus the gating questions and the auto-registration.
+`--from` and `--template` are mutually exclusive — exactly one source per install. See [Quickstart](/quickstart) for the end-to-end walkthrough from a cold machine.
 
 For the self-managed provider posture, see [`agentsfleet tenant provider`](/cli/agentsfleet#tenant-provider).
 
@@ -43,8 +38,11 @@ For the self-managed provider posture, see [`agentsfleet tenant provider`](/cli/
 | Code | Meaning |
 |---|---|
 | `0` | Installed (or updated). |
-| `1` | No workspace selected, or API error. |
-| `2` | Missing `--from`, invalid path, or schema rejection. |
+| `1` | Not authenticated. |
+| `2` | Network error reaching the API. |
+| `3` | The API rejected the bundle (schema validation, name clash, etc.). |
+| `4` | Missing or invalid argument (e.g. no `--from`/`--template`). |
+| `5` | Bad local bundle (path missing, no `SKILL.md`). |
 
 ## See also