docs(m103): template-only install + two-tier template catalogue

api-reference/error-codes.mdx

@@ -159,15 +159,15 @@ Load-shedding on a saturated API instance — back off and retry.
 
 ## Fleet Bundle
 
-Import + snapshot of a Fleet Bundle (the SKILL.md/TRIGGER.md package behind a Fleet) via `POST /v1/workspaces/{workspace_id}/fleets/bundles/snapshots`.
+Onboarding a Fleet template (the SKILL.md/TRIGGER.md package behind a Fleet) and installing it. Onboard a template via `POST /v1/admin/fleet-templates` (platform tier) or `POST /v1/workspaces/{workspace_id}/fleet-templates` (your workspace's tenant tier); install one via `POST /v1/workspaces/{workspace_id}/fleets`.
 
 | Code | HTTP | Title | Common Causes |
 |---|---|---|---|
 | `UZ-BUNDLE-001` | 400 | Invalid Fleet Bundle | The supplied bundle is missing `SKILL.md` or contains unsafe, oversized, or malformed files. |
-| `UZ-BUNDLE-002` | 404 | Fleet Bundle not found | No Fleet Bundle snapshot matches the supplied `bundle_id` in this workspace. |
-| `UZ-BUNDLE-003` | 424 | Fleet Bundle credentials missing | Add the workspace credentials named in `missing_credentials` before installing this bundle. |
+| `UZ-BUNDLE-002` | 404 | Fleet Bundle not found | No installable template or stored snapshot matches the request in this workspace. The `platform_template_id`/`tenant_template_id` is unknown, or the template has not been onboarded yet. |
+| `UZ-BUNDLE-003` | 424 | Fleet Bundle credentials missing | Add the workspace credentials named in `missing_credentials` before installing this template. |
 | `UZ-BUNDLE-004` | 502 | Fleet Bundle fetch failed | The bundle source could not be fetched from GitHub — the repository may be missing or private, or GitHub may be unreachable. Verify the source reference and retry. |
-| `UZ-BUNDLE-005` | 503 | Fleet Bundle storage unavailable | Snapshot storage is not configured or is unavailable, so the validated bundle could not be stored. Retry later or contact the operator. |
+| `UZ-BUNDLE-005` | 503 | Fleet Bundle storage unavailable | Template object storage is not configured or is unavailable, so the onboarded bundle could not be stored. Retry later or contact the operator. |
 | `UZ-BUNDLE-006` | 429 | Too many Fleet Bundle imports in flight | This instance is at its concurrent import ceiling. Honor the `Retry-After` header and retry with backoff. |
 
 ## Integration grants

changelog.mdx

@@ -22,6 +22,36 @@ export const STAGE_SELF_MANAGED_M66 = "$0.0001";
   agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner.
 </Tip>
 
+<Update label="Jun 30, 2026" tags={["Breaking", "What's new", "API", "UI", "CLI"]}>
+  ## Bring your own Fleet templates
+
+  You can now onboard your own Fleet templates into your workspace, alongside the curated platform catalogue. The install gallery shows both — the platform templates and your workspace's own — and you install any of them by id. Templates are stored once, content-addressed, and shared across the fleets you spin up from them. Installing a fleet is now always "pick a template, install it"; the old "paste a local `SKILL.md`" and "import a GitHub repo at install" paths are gone.
+
+  ## Upgrading
+
+  - **Install is template-only.** `agentsfleet install --from <path>` (installing a new fleet from a local directory) has been removed. Install by id instead: `agentsfleet install --template <id>`. To run a fleet you authored yourself, onboard its `SKILL.md`/`TRIGGER.md` as a template first — through the dashboard or the onboarding API — then install it by id. To push local edits onto an **already-installed** fleet, use `agentsfleet fleet update <fleet_id> --from <path>` (unchanged). Upgrade the CLI and server together.
+  - **Fleet-create takes a template id, not a bundle.** `POST /v1/workspaces/{workspace_id}/fleets` now accepts exactly one of `{platform_template_id}` or `{tenant_template_id}` (plus an optional `name`). Raw `source_markdown`, the per-workspace `bundle_id`, and the github-import-at-create body are rejected. Onboard a template, then install it by id.
+  - **Bundle import/snapshot endpoints removed.** `POST /v1/workspaces/{workspace_id}/fleets/bundles/snapshots` and the snapshot-detail read no longer exist. Use the onboarding routes below.
+
+  ## What's new
+
+  - **Onboard templates into two tiers.** Onboard a template into the global platform catalogue or into your own workspace; workspace templates are visible only to your workspace.
+  - **One gallery, both tiers.** The dashboard install gallery unions the platform catalogue with your workspace's own templates, and never shows another workspace's templates.
+  - **Templates explain their credentials.** Gallery entries carry a description and per-credential "why this is needed" copy, so the install gate can tell you what each credential is for before you connect it.
+
+  ## API reference
+
+  - **`GET /v1/workspaces/{workspace_id}/fleet-templates`** — the workspace gallery: the platform catalogue plus this workspace's own templates. Each entry carries `id`, `name`, `description`, `visibility` (`"platform"` or `"tenant"`), `source_ref`, `requirements`, `required_credentials_reasons`, and support-file summaries — never an object-store key.
+  - **`POST /v1/admin/fleet-templates`** (scope `platform-template:write`) and **`POST /v1/workspaces/{workspace_id}/fleet-templates`** (scope `template:write` + workspace ownership) — onboard a template from a GitHub source into the platform or workspace tier. The canonical bundle is written to object storage keyed by content hash; the response is metadata only.
+  - **`POST /v1/workspaces/{workspace_id}/fleets`** — install body is now `{platform_template_id}` **or** `{tenant_template_id}`, plus an optional `name` so one template can back several fleets.
+  - **`UZ-BUNDLE-002`** now reads "No installable template or stored snapshot matches the request in this workspace."
+
+  ## CLI
+
+  - **`agentsfleet install --template <id>`** resolves the template in your workspace gallery and installs it by tier. The `--from <path>` option has been removed from `install`.
+  - **`agentsfleet fleet update <fleet_id> --from <path>`** (live-editing an installed fleet's instructions from a local directory) is unchanged.
+</Update>
+
 <Update label="Jun 30, 2026" tags={["What's new", "API"]}>
   ## Authorization is now scope-based
 

cli/agentsfleet.mdx

@@ -8,7 +8,7 @@ description: "Complete agentsfleet command reference."
 | Group | Commands |
 |-------|----------|
 | Authentication | `login`, `logout`, `auth status` |
-| Fleets (top-level) | `install --from`, `install --template`, `templates`, `list`, `status`, `stop`, `resume`, `kill`, `delete`, `logs`, `events`, `steer` |
+| Fleets (top-level) | `install --template`, `templates`, `list`, `status`, `stop`, `resume`, `kill`, `delete`, `logs`, `events`, `steer` |
 | Fleets (in-place update) | `fleet update --from` |
 | Credentials | `credential add`, `credential show`, `credential list`, `credential delete` |
 | Workspaces | `workspace add`, `workspace list`, `workspace use`, `workspace show`, `workspace credentials`, `workspace delete` |
@@ -89,32 +89,23 @@ The probe result is one of `valid` (200 from the billing endpoint), `unauthorize
 
 ## Fleets
 
-### `agentsfleet install --from <path>`
-
-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 ./my-fleet
-```
-
-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>`
 
-Install a fleet from the first-party template catalogue (browse it with `agentsfleet templates`) instead of a local directory. agentsfleet fetches the template's pinned source, validates it, prints a requirements preview (credentials, tools, network hosts), then creates the fleet.
+Install a fleet from your workspace gallery — the first-party platform catalogue plus your workspace's own onboarded templates. agentsfleet resolves the template by id, fetches its pinned `SKILL.md` + `TRIGGER.md`, prints a requirements preview (credentials, tools, network hosts), then creates the fleet in the active workspace. `install` takes exactly one source, `--template <id>`; there are no bare-name aliases and no local-directory install.
 
 ```bash
 agentsfleet install --template github-pr-reviewer
 agentsfleet install --template github-pr-reviewer --name pr-reviewer-frontend
 ```
 
-`--from` and `--template` are mutually exclusive — exactly one source per install. If the template ships no `TRIGGER.md`, a default API wake is generated and the result notes it.
+If the template ships no `TRIGGER.md`, a default API wake is generated and the result notes it.
+
+To run a fleet you wrote yourself, onboard its `SKILL.md` + `TRIGGER.md` as a template first — via the dashboard or the API (`POST /v1/admin/fleet-templates` for the platform tier, `POST /v1/workspaces/{workspace_id}/fleet-templates` for a workspace template) — then install it by id. Frontmatter is validated at onboard time. There is no CLI onboard command. See [Authoring a fleet](/fleets/authoring) and [Templates](/fleets/templates).
 
 | Flag | Default | Purpose |
 |------|---------|---------|
-| `--from <path>` | *(one source required)* | Install from a local directory containing `SKILL.md` + `TRIGGER.md`. |
-| `--template <id>` | *(one source required)* | Install from a catalogue template by id (see `agentsfleet templates`). |
-| `--name <name>` | *(SKILL.md `name:`)* | Override the fleet name so one bundle or template can back several fleets in a workspace. Without it, a second install of the same source collides with `UZ-AGT-006`. |
+| `--template <id>` | *(required)* | Install from a workspace-gallery template by id (browse the platform tier with `agentsfleet templates`). |
+| `--name <name>` | *(SKILL.md `name:`)* | Override the fleet name so one template can back several fleets in a workspace. Without it, a second install of the same template collides with `UZ-AGT-006`. |
 
 ### `agentsfleet templates`
 

cli/install.mdx

@@ -35,7 +35,7 @@ agentsfleet templates                          # browse the catalogue
 agentsfleet install --template github-pr-reviewer
 ```
 
-Or install a local bundle you authored with `agentsfleet install --from <path>` (see [Authoring a fleet](/fleets/authoring)).
+Authored your own `SKILL.md` + `TRIGGER.md`? Onboard it as a template (via the dashboard or the API), then install it by id with `agentsfleet install --template <id>`. To push local edits onto an already-installed fleet, use `agentsfleet fleet update <fleet_id> --from <path>`. See [Authoring a fleet](/fleets/authoring).
 
 <Tip>
   **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.

fleets/authoring.mdx

@@ -13,7 +13,7 @@ my-fleet/
 └── TRIGGER.md    # machine-readable config + deployment metadata
 ```
 
-`agentsfleet install <template>` scaffolds both. This page is the reference for authoring your own.
+Installing a [template](/fleets/templates) with `agentsfleet install --template <id>` gives you a fleet backed by both files. This page is the reference for authoring your own — which you then onboard as a template (dashboard or API) before installing by id.
 
 ## `SKILL.md` — fleet instructions
 
@@ -35,12 +35,12 @@ model: claude-sonnet-4-6           # optional, hint
 
 | Field | Required | Purpose |
 |---|---|---|
-| `name` | yes | Identity. Must equal `TRIGGER.md` `name:` (install rejects mismatch). |
+| `name` | yes | Identity. Must equal `TRIGGER.md` `name:` (onboarding rejects mismatch). |
 | `description` | yes | One-line summary. |
 | `version` | yes | Semver string. |
 | `when_to_use`, `tags`, `author`, `model` | no | Pass-through metadata. |
 
-Unknown top-level keys are accepted silently — drop in vendor-specific extras (`x-amp:`, etc.) without breaking install.
+Unknown top-level keys are accepted silently — drop in vendor-specific extras (`x-amp:`, etc.) without breaking onboarding.
 
 ### Body
 
@@ -130,7 +130,7 @@ 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 with `UZ-AGT-008` (invalid fleet config). 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 onboard time 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. |
@@ -186,17 +186,19 @@ A breach terminates the in-flight event cleanly and records a `budget_breach` en
 
 ## Validation
 
-`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
-```
+Authoring produces a template you **onboard** — through the dashboard or the API (`POST /v1/admin/fleet-templates` for the platform tier, `POST /v1/workspaces/{workspace_id}/fleet-templates` for a workspace template). Onboarding posts both files 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:
 
 ```
 UZ-AGT-011  SKILL.md and TRIGGER.md disagree on `name:`
   Suggestion: make the top-level name: identical in both files
 ```
 
+Once onboarded, install the template by id with `agentsfleet install --template <id>`. To re-parse and validate edits against an already-installed fleet, push them with `agentsfleet fleet update <fleet_id> --from <dir>` — the same parser runs and returns the same `UZ-AGT-*` codes.
+
+```bash
+agentsfleet fleet update 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --from ./my-fleet
+```
+
 ## Next
 
 <CardGroup cols={2}>

fleets/credentials.mdx

@@ -124,7 +124,7 @@ x-agentsfleet:
 
 At event delivery time the tool bridge fetches each named secret from the vault and substitutes it into the outbound HTTP call. The fleet never sees the resolved value.
 
-If a fleet references a credential that is not present in the vault when `agentsfleet install --from <path>` is called, install fails with a clear error listing the missing names.
+If a fleet references a credential that is not present in the vault when `agentsfleet install --template <id>` is called, install fails with a clear error listing the missing names.
 
 ## Rotation