feat: centralize fleet model selection in a role-based index

.agents/skills/bootstrap-diagnostics/SKILL.md

@@ -37,7 +37,7 @@ When any diagnostic needs captain attention, report the plain consequence and re
   This is the only sanctioned firstmate-initiated git write to the primary, and it is a non-destructive branch switch that strands nothing.
 - `STARTUP_MEMORY_BUDGET: invalid config/startup-memory-budget - <reason>` - the visible startup-memory budget is not a safe one-line positive decimal file; do not infer the default or propagate it.
   Correct the local primary file, then rerun session start so the normal convergence path can deliver the validated value to secondmate homes.
-- `CREW_DISPATCH: invalid config/crew-dispatch.json - <reason>` - the optional dispatch profile file exists but failed low-cost bootstrap validation; stop profile-based dispatch, report the actionable error, and require correction of the malformed schema, unverified harness name, or invalid harness/effort pair rather than falling back around it or selecting a bad profile.
+- `CREW_DISPATCH: invalid config/crew-dispatch.json - <reason>` - the optional dispatch profile file exists but failed low-cost bootstrap validation; stop profile-based dispatch, report the actionable error, and require correction of the malformed schema, unverified harness name, invalid harness/effort pair, or a [model index](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson) failure such as a malformed index, unconfigured role, or retired id rather than falling back around it or selecting a bad profile.
 - `FLEET_SYNC: <repo>: skipped: <reason>` - a benign one-off skip (offline, no origin, local-only); bootstrap continued, investigate only if it blocks work.
   A skip can also report the bounded fleet-refresh timeout (`FM_FLEET_SYNC_BOOTSTRAP_TIMEOUT`, or a fleet-size-aware default with a 20 second floor); a timeout never blocks startup.
   `skipped: registry entry does not resolve to a delivery posture` is the one skip that is not one-off: the clone is left alone on every bootstrap until `data/projects.md` is corrected, so run the printed `bin/fm-project-mode.sh <repo>` to read the refusal and fix the entry.

.agents/skills/harness-adapters/references/common/dispatch.md

@@ -5,15 +5,11 @@ Load this with the selected tool reference for dispatch, start, or adapter verif
 ## Resolution
 
 Use the router's detection and safety sections for static crew and secondmate harness resolution and all explicit overrides.
-`config/crew-dispatch.json` can override that static default for one crewmate or scout with concrete harness, model, and effort axes.
+`config/crew-dispatch.json` can override that static default for one crewmate or scout with a profile under the [dispatch configuration contract](../../../docs/configuration.md#crew-dispatch-profiles-configcrew-dispatchjson).
 For a profile array, load `quota-array-dispatch` after establishing harness and provider facts here.
 When the opt-in `bin/fm-dispatch-resolve.sh` is on, its `clear` answer already names the concrete axes; `docs/configuration.md` "Typed dispatch resolution" owns that contract.
 
-`../secondmate-provisioning/SKILL.md` owns inherited local material.
-Its harness consequence is that a secondmate's workers receive literal `config/crew-harness` and `config/crew-dispatch.json`, while the primary-only `config/secondmate-harness` is never inherited because secondmates do not spawn secondmates.
-A concrete crew value such as `codex` carries that runtime into the secondmate home.
-Unset or `default` carries no concrete value, so its workers use that home's own or detected harness rather than the primary's effective crew harness.
-The inherited dispatch file applies the same best-fit profiles there.
+[`secondmate-provisioning`](../secondmate-provisioning/SKILL.md) owns inherited harness defaults and routing configuration.
 
 ## Skill advice at intake
 
@@ -24,7 +20,7 @@ Follow [advisory skill selection](../../../docs/configuration.md#advisory-skill-
 ## Owners
 
 `../../../bin/fm-spawn.sh` owns launch, autonomy, concrete flags, task-kind compatibility, and worker turn-end wiring.
-Natural-language rules stay with firstmate, while scripts receive concrete axes.
+Natural-language rules stay with firstmate; model references follow the [fleet model-index contract](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson).
 
 `../../../bin/fm-busy-lib.sh` owns semantic busy trust.
 Composer shapes, glyphs, placeholders, popups, rendered delivery signals, and the `empty` / `pending` / `pending-unproven` / `unknown` decision belong only to `../../../bin/fm-composer-lib.sh`.

.agents/skills/harness-adapters/references/common/model-and-effort.md

@@ -5,7 +5,7 @@ Add `references/common/dispatch.md` for configured profile precedence.
 
 ## Axes and precedence
 
-`../../../bin/fm-spawn.sh` accepts concrete `--harness`, `--model`, and `--effort` values selected at intake; scripts never parse natural-language dispatch rules.
+`../../../bin/fm-spawn.sh` accepts model and effort values selected at intake, including the role references defined by the [fleet model index](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson); scripts never parse natural-language dispatch rules.
 The tool reference records verified flags, accepted values, omission behavior, and discovery.
 
 Effort precedence is a per-task captain instruction, then applicable dispatch profile or secondmate pin, then the fallback below.
@@ -34,10 +34,10 @@ Establish it from the tool's discovery surface and `quota-axi auth --json` per-p
 ## Discovery
 
 Treat model and provider knowledge as current discovery, not a permanent namespace or mapping.
-Use the selected tool reference's authoritative surface in the current authenticated environment because availability changes by version, account, and configuration.
+Use the selected tool reference's authoritative surface in the effective worker's authenticated environment because availability changes by version, account, and configuration.
 
 For an unfamiliar namespace, establish support and provider identity from that harness's CLI help, model listing, or current documentation.
-An account-reaching listing that omits a model is concrete unsupported evidence; block the candidate and quote it.
+Catalog verdicts follow the [fleet model-index evidence boundary](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson).
 An unreachable surface establishes nothing; report uncertainty instead of a verdict.
 
 For a matched profile array, return to `quota-array-dispatch` only after establishing every candidate's harness support, provider relationship, and uncertainty.

.agents/skills/harness-adapters/references/harness/agy.md

@@ -19,7 +19,7 @@ Verified as a CREWMATE and SCOUT adapter only; `../../../bin/fm-spawn.sh` refuse
 | Autonomy | `--dangerously-skip-permissions` auto-approves tool calls for the run. |
 | Marker | None; a live TUI carries no `AGY_*` or `ANTIGRAVITY_*` variable. |
 | Resume | `--continue` and `--conversation` exist but carry no verified pane-resume contract; use deterministic relaunch. |
-| Model | `--model <id>` with the bare catalog id from `agy models` (for example `gemini-3.8-flash-high`); `bin/fm-spawn.sh` refuses a requested id a reachable listing omits. The listing is a remote fetch, so the probe runs stdin-detached under the shared hard bound and an unreachable or hung listing launches unvalidated with a notice. |
+| Model | `--model <id>` uses a bare id from `agy models`; native non-entry literals refuse when a reachable listing omits the id and launch with a notice when it is unreachable, while indexed selections follow the [fleet model-index contract](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson). |
 | Effort | `--effort low\|medium\|high`; `xhigh` and `max` stay in task metadata under the record-and-omit contract. |
 | Composer | Borderless bare `>` row, which the shared classifier reads as `unknown` under the dead-shell rule, never `empty`; steering confirms delivery through native agent-state and the delivery footer instead, the cursor precedent. |
 

.agents/skills/harness-adapters/references/harness/omp.md

@@ -14,9 +14,9 @@ Cross-harness provider and credential identity is owned by `references/common/mo
 | Exit command | `/quit` (`/exit` and `/q` are aliases). |
 | Interrupt | Single Escape; the composer is left empty, no clear key. |
 | Skill invocation | No separate verified form beyond normal command behavior; use natural language when the exact command is uncertain. |
-| Model flag | `--model <provider>/<id>` (fuzzy patterns are accepted by omp but bypass Firstmate's pre-launch check). |
+| Model flag | `--model <provider>/<id>`; omp also accepts fuzzy patterns. Firstmate selection follows the [fleet model-index contract](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson), and native non-entry validation is owned by [`fm-spawn.sh --help`](../../../bin/fm-spawn.sh). |
 | Effort flag | `--thinking <off\|minimal\|low\|medium\|high\|xhigh\|max\|auto>`, a superset of the shared vocabulary, so every level including `max` maps straight across. |
-| Model discovery | `omp models [--json]` lists built-in and auto-discovered providers only; extension-registered providers such as `claude-bridge` never appear, so those models pass through the spawn unvalidated with a stderr notice. `omp usage` shows provider windows; `quota-axi` covers the `claude` provider when the bridge is in use. |
+| Model discovery | `omp models [--json]` lists built-in and auto-discovered providers only; extension-registered providers such as `claude-bridge` never appear. `omp usage` shows provider windows; `quota-axi` covers the `claude` provider when the bridge is in use. |
 | Marker | None of omp's own (verified: `PI_CODING_AGENT` absent from the binary, no `PI_CODING_AGENT_DIR` or `OMP_PROFILE` in the default profile). `FM_OMP_HARNESS=omp` is Firstmate's launch marker; ancestry matches the exact process name `omp`. |
 | Composer | See [`fm-spawn.sh --help`](../../../bin/fm-spawn.sh) for the composer posture pin; busy text is `Working…` (U+2026), the only spelling the omp busy regex accepts (the three-dot form its headless `-p` mode writes never reaches a supervised pane), with the status row's braille spinner plus elapsed cell as the second signal; box-shape support and overlay live-reload evidence are recorded in [omp box composer through Herdr](../../../docs/verification/runtime-backends.md#2026-10-06-omp-box-composer-through-herdr). |
 | Autonomy | Approval and unattended-session posture are owned by [`fm-spawn.sh --help`](../../../bin/fm-spawn.sh). |

.agents/skills/operational-home-layout/SKILL.md

@@ -25,7 +25,8 @@ config/claude-permission-mode  optional one-token permission posture for every C
 config/claude-launcher  optional Claude worker launcher; see docs/configuration.md "Claude launcher" for selection, proxy requirements, and inheritance
 config/compact-adviser  optional worker compact-adviser policy; LOCAL, gitignored; see docs/configuration.md "Compact adviser setting" for its format, defaults, and inheritance
 config/claude-account config/pi-account  optional per-home worker account pin for Claude and Pi launches; LOCAL, gitignored, not inherited; absent keeps today's ambient account; present refuses a launch unless the pinned account resolves and is signed in (section 4 owns the refusal rule); see docs/configuration.md "Worker account pin"
-config/crew-dispatch.json  optional crewmate dispatch profiles; LOCAL, gitignored; firstmate-maintained but human-editable natural-language rules that choose a per-task harness/model/effort profile (section 4). Inherited by secondmate homes
+config/crew-dispatch.json  optional crewmate dispatch profiles; LOCAL, gitignored, firstmate-maintained but human-editable; see docs/configuration.md "Crew dispatch profiles" for selection and secondmate-provisioning for inheritance
+config/model-index.json  optional fleet model index; see docs/configuration.md "Fleet model index"
 config/secondmate-harness  harness the PRIMARY uses to launch SECONDMATE agents, optionally followed by a model and effort token on the same line ("<harness> [<model>] [<effort>]"; section 4); LOCAL, gitignored; absent or "default" harness falls back to config/crew-harness then firstmate's own. The primary's own setting; NOT inherited into secondmate homes (secondmates do not spawn secondmates)
 config/backlog-backend  backlog backend override; LOCAL, gitignored; absent or "tasks-axi" = the configured tasks-axi backend, "manual" = force routine backlog updates to hand-editing; inherited by secondmate homes (section 10)
 config/backend  runtime session-provider backend override for new tasks; LOCAL, gitignored; absent = falls through to runtime auto-detection (the runtime firstmate itself is executing inside), then tmux; tmux is the verified reference backend (docs/tmux-backend.md), herdr has its own required CI lane (docs/herdr-backend.md), while zellij, orca, and cmux remain experimental with no dedicated real-backend CI lane (docs/zellij-backend.md, docs/orca-backend.md, docs/cmux-backend.md) - herdr and cmux can also be selected by runtime auto-detection, zellij and orca never are (always explicit), and codex-app is not accepted; see docs/codex-app-backend.md; inherited by secondmate homes under the primary-authoritative contract in secondmate-provisioning

.agents/skills/quota-array-dispatch/SKILL.md

@@ -38,6 +38,8 @@ It never removes this skill's authority, and its `ambiguous`, `escalate`, and `e
 
 ## Read the default TOON
 
+Resolve configured candidates under the [fleet model-index contract](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson) before applying this procedure.
+
 Start each intake by running `quota-axi` once with no `--json`, and reuse that TOON for every candidate.
 Post-consolidation quota-axi (the floor owned by `bin/fm-quota-axi-lib.sh`) puts `spendPriority` in the default `quota[]` block beside `effectivePercentRemaining`, `runway`, `confidence`, `limitedBy`, and `resetsAt`.
 Sparse `exhaustion[]` carries finite-runway seconds only for `projected_exhaustion` and `exhausted_now`.
@@ -66,8 +68,8 @@ It cannot override a hard-gate failure, and it is never hidden inside a new comp
 Outside those documented mappings, deterministic shell must not infer a provider family or credential store from a harness, model, or source name.
 You establish the remaining relations yourself, in the open, from the candidate's own authoritative catalog (`harness-adapters` owns the per-harness discovery surface) plus the one intake snapshot.
 
-Confirm the catalog lists the candidate's model and record the provider family it reports.
-A model the catalog does not list is concrete contradictory evidence: block that candidate and quote the catalog result.
+Read the candidate's model-support and provider evidence from its authoritative discovery surface, and record unavailable evidence as uncertainty.
+Apply the [fleet model-index catalog-evidence boundary](../../../docs/configuration.md#fleet-model-index-configmodel-indexjson) before treating an omitted model as contradictory evidence; block a proven-unsupported candidate and quote the authoritative catalog result.
 Apply quota at the granularity the vendor actually supplies.
 A provider-level or `all_models`/`all_products` scope bounds every model you established in that family within the candidate's matched account, including one with no window of its own.
 A named-model or named-product scope is an additional bound for that model alone.