omp-llm-role 1.0.0 → 1.2.0

package/docs/dev/explorer.md

@@ -12,10 +12,12 @@ explorer never reimplements `value = q − λ·$/M`.
 | File | Role |
 |---|---|
 | `src/explorer/server.ts` | Zero-dependency `node:http` surface: static SPA + JSON API. Exports `createExplorerServer`, `ExplorerOpts`. |
-| `src/explorer/explain.ts` | Pure explanation layer (no I/O): rank rows with baseline deltas, per-model decomposition, inverse-cardinal targets. Exports `rankRows`, `explainModel`, `inverseCardinal`, `METRIC_META`, `WEIGHTABLE_METRICS`. |
-| `src/explorer/boot.ts` | Shared launcher: bind/port fallback, lock-file roles, browser open, close. Exports `startExplorer`, `EXPLORER_DEFAULT_PORT`, `ExplorerHandle`, `ExplorerBootOpts`. |
+| `src/explorer/explain.ts` | Pure explanation layer (no I/O): rank rows with baseline deltas, per-model decomposition, inverse-cardinal targets, and the keyed-catalog availability overlay. Exports `rankRows`, `explainModel`, `inverseCardinal`, `METRIC_META`, `WEIGHTABLE_METRICS`. |
+| `src/explorer/scopes.ts` | Scope resolution (no HTTP): the user-level scope, the registry's projects, and the session's project; the per-scope read; the dataset union. Exports `Scope`, `resolveScopes`, `defaultScopeId`, `resolveScope`, `readScopeRoles`, `unionRoles`. |
+| `src/explorer/boot.ts` | Shared launcher: bind/port fallback, scope resolution, browser open, close. Exports `startExplorer`, `EXPLORER_DEFAULT_PORT`, `ExplorerHandle`, `ExplorerBootOpts`. |
+| `src/project-registry.ts` | The global project registry (`llm-role-projects.json` in the agent dir): read/register/prune, atomic write. Exports `PROJECT_REGISTRY_FILE`, `readProjectRegistry`, `registerProject`. |
 | `src/role-settings.ts` | The one validated role write path (validate → merge → backup → atomic write). Exports `validateRole`, `mergeExport`, `writeRoleSettings`, `timestamp`. |
-| `web/app.js` | The SPA: renders and edits role defs, calls the API. No framework, no build step, no external requests. |
+| `web/app.js` | The SPA: renders and edits role defs, switches scopes, calls the API. No framework, no build step, no external requests. |
 | `src/extension.ts` | `/explore-roles`: in-process `startExplorer` (catalog from the live model registry), closed on `session_shutdown`. |
 
 ## HTTP surface (`src/explorer/server.ts`)
@@ -29,47 +31,80 @@ caller; no auth. Every handler is wrapped so a throw becomes a 500 JSON error
 ```ts
 type ExplorerOpts = {
   webDir: string;
-  lockPath: string;
-  // Fresh per call: rank (swapped by refresh) plus roles/universe re-read from
-  // the lock file, so a page reload after Export reflects the write.
-  getState(): {
+  // All known scopes, re-resolved per call so a project registered by another
+  // session appears without a restart.
+  listScopes(): Scope[];
+  // The scope a request should use: the requested id when known and present,
+  // else the default (session project when present, else user-level).
+  resolveScope(requestedId: string | null): Scope;
+  // Fresh per call: rank (swapped by refresh) plus the scope's roles/universe
+  // re-read from its lock file, so a page reload after Export reflects the write.
+  getState(scope: Scope): {
     rank: RankData;
     roles: Record<string, RoleDef>;
     universe: Record<string, UniverseEntry>;  // every known role, disabled included
     defaults: Record<string, RoleDef>;
+    availability: KeyAvailability;            // keyed-catalog overlay (re-derived on refresh)
   };
-  refresh(): Promise<void>;                   // re-runs loadRankData({ refresh: true }) and swaps rank
+  refresh(): Promise<void>;                   // re-runs loadRankData({ refresh: true, roles, extraMetrics }) and swaps rank
 };
 ```
 
+The server holds the active scope id as mutable state (alongside the mutable
+`rank`/`availability`); `activeScope` resolves it per request, persisting the
+fallback when the active scope became unavailable.
+
 Endpoints:
 
 | Method + path | Body | Response |
 |---|---|---|
 | `GET /` | — | `web/index.html` |
 | `GET /app.js`, `/style.css` | — | static asset (traversal-guarded) |
-| `GET /api/bootstrap` | — | `bootstrapPayload(opts)` |
+| `GET /api/bootstrap` | — | `bootstrapPayload(opts, activeScope)` |
+| `POST /api/scope` | `{scope}` | switch the active scope, then the bootstrap payload (404 unknown id, 409 non-present) |
 | `POST /api/rank` | `{role, def}` | `{eligible, lambda, derivedLambda, rows, errors}` |
 | `POST /api/explain` | `{role, def, modelId}` | `explainModel(...)` spread + `errors` |
-| `POST /api/export` | `{roles}` | `{ok:true, backupPath, roles}` or `{ok:false, errors}` |
-| `POST /api/refresh` | — | `await opts.refresh()` then the bootstrap payload |
+| `POST /api/export` | `{roles}` | `{ok:true, backupPath, roles, lockPath}` or `{ok:false, errors}` |
+| `POST /api/refresh` | — | `await opts.refresh()` (re-ranks and re-derives the availability overlay) then the bootstrap payload |
 
 - `bootstrapPayload` ships `roles` (resolved), `defaults` (`DEFAULT_ROLES`),
   `universe` (kind/enabled/locked + effective def per known role), `metrics`
   (`weightableMetrics`: the shipped keys plus any external metric a resolved role
   weights), `metricMeta` (`metricMetaFor`: `METRIC_META` plus a derived entry per
-  external metric), `levels` (`Object.keys(SUFFIX_LEVELS)`), `thinkingFactors`
+  external metric), `focusAssessments` (per role, the nine-axis assessment of its
+  focus metrics over the resolved dataset), `levels` (`Object.keys(SUFFIX_LEVELS)`), `thinkingFactors`
   (per-level billed-blend multiplier from the engine's own `thinkingPriceFactor`,
   so the UI readout cannot drift), `fetchedAt`, `modelCount`, `orMatched`,
-  `orPriced`, `lockPath`. Every request calls `getState()`, which re-reads the
-  lock file — so a page reload after Export shows the new roles, not the
-  boot-time snapshot.
+  `orPriced`, `lockPath` (the **active scope's** lock file), `scopes` (id, label,
+  kind, present per known scope), `activeScope` (the active scope id),
+  the active scope's global capability flags and the feature registry (the
+  `FEATURES` rows: id, label, description, recommended bundle, buys), so the SPA
+  can expand a posted def the same way the server does, and
+  `availability` (the keyed-catalog summary:
+  `{active, reason, publicCount, keyedCount, blockedCount, fetchedAt}`). Every
+  request calls `getState(scope)`, which re-reads that scope's lock file — so a
+  page reload after Export shows the new roles, not the boot-time snapshot.
+- `handleScope` validates the requested id against `listScopes()`: an unknown id
+  is a 404, a known-but-not-present one a 409; a valid switch sets the active
+  scope and returns the new payload.
 - `handleRank` baselines against `state.roles[role] ?? state.universe[role]?.def ??
   state.defaults[role]`: an enabled role against its resolved def, a disabled or
   lock-file-only role against its effective def, so selecting it still shows
-  deltas rather than an empty baseline.
-- `handleExport` calls `writeRoleSettings(opts.lockPath, body.roles)` and
-  returns its result verbatim.
+  deltas rather than an empty baseline. It passes `state.availability` to
+  `rankRows`, so every row carries its `key` badge (usable/blocked/unknown) with
+  no extra call. **`handleRank`/`handleExplain` expand the posted def** with the
+  active scope's global flags (`expandFeatures(def, …)`) *before*
+  `rankRows`/`explainModel`: the handlers rank the client's def verbatim, while
+  the Δ baseline is the resolved def (`state.roles[role]`), so without the
+  expansion the preview would omit the preset the baseline includes and every
+  row's Δ would be a lie. The posted def is the **authored** def (flags + explicit
+  keys); the expansion is applied only for the ranking call, never persisted.
+- `handleExport` validates every dirty role first — `validateRole` plus a
+  **provider-pin check**: a `providerPin` that matches no route in the loaded
+  dataset is rejected (`role "<name>": provider pin "<slug>" matches no route in
+  the loaded dataset`) before any write, so an exported role cannot carry an
+  unroutable pin. It then calls `writeRoleSettings(activeScope.lockPath,
+  body.roles)` and returns its result verbatim plus the written `lockPath`.
 - Unknown `/api/*` → 404; wrong method → 405; non-API non-GET → 405.
 - `readBody` caps at `MAX_BODY = 1 MiB` (413); `readJson` → 400 on invalid JSON.
 - `serveStatic` resolves against `webDir` and rejects traversal (`full` must be
@@ -89,48 +124,91 @@ Pure, no I/O; all ranking math is delegated to `src/engine.ts`.
   declared?)`** merges the shipped table with a derived entry per external metric.
 - **`weightableMetrics(extra?)`** — the shipped keys plus any external metric in
   `extra`; exactly what the validator accepts.
-- **`rankRows(def, models, baseline)`** — `rankRole(def, models)` +
+- **`rankRows(def, models, baseline, availability?)`** — `rankRole(def, models)` +
   `paretoFrontier`, annotating each row with `baselineRank`/`delta`
   (`baselineRank − rank`; positive = moved up) against the effective role's
   ranking. Rows carry `priceEff` (the thinking-adjusted price the ranking
   penalized), `parts`, `missing` (weighted non-price metrics whose raw value is
-  null), and `frontier`.
+  null), `frontier`, and `key` — the availability overlay verdict
+  (`usable`/`blocked`/`unknown`), orthogonal to `missing` and to the eligibility
+  gates. `availability` is optional and pure (no I/O); omitted or inactive ⇒
+  every row reads `unknown`.
 - **`inverseCardinal(metric, t)`** — inverse of `cardinalMetric` for the "what
   would it take" targets: `index` → `t*80 − 20`; `throughput` → `10 * 30**t`
   (null outside `[0,1]`, because the forward transform clamps); everything else
   (benchmark, percentile, price) → identity. See *Open defect* below for the
   `gpqa` exception.
-- **`explainModel(def, models, modelId, roleName)`** — the full decomposition, or
-  the eligibility gates it failed (same gates `rankRole` applies, same order:
-  missing required, image filter, no billed price). On success: `contributions`
+- **`explainModel(def, models, modelId, roleName, availability?)`** — the full
+  decomposition, or the eligibility gates it failed (same gates `rankRole`
+  applies, same order: missing required, image filter, no billed price). On
+  success: `contributions`
   (raw → cardinal `t` → renormalized weight → contribution → share of `q`, with
-  a `fillNote` when the value is a capability fill), `cost` (`priceEff`, billed
-  price, λ, penalty, `q`, `value`), `gapAbove`/`gapToTop`/`above`, `closing` (the
+  a `fillNote` when the value is a capability fill), `cost` (`priceEff`, the
+  cache-adjusted billed price, λ, penalty, `q`, `value`), `role.cacheHitRate`,
+  `gapAbove`/`gapToTop`/`above`, `closing` (the
   per-metric raw target that would close the gap, via `inverseCardinal`, with
-  unreachable/extrapolated notes), and `dominators` (models both cheaper and at
-  least as good on `q`, top 3). It mirrors `rankRole`'s capability fill so the
-  contributions sum exactly to `q`.
+  unreachable/extrapolated notes), `dominators` (models both cheaper and at
+  least as good on `q`, top 3), `ownProvider` (true when the model was priced on
+  the soft best route rather than the blend), `autoPin` (the provider slug the
+  updater would write — `bestRoute(model, def)?.providerSlug`, the max-`vfm`
+  route (scoring.md, *Route ordering*), when the role sets
+  `preferOwnProvider` and carries no manual `providerPin`, else `null`), and the
+  availability overlay `key`/`keyReason`
+  (the same verdict as `rankRows`, plus the reason it reads that way). It mirrors
+  `rankRole`'s capability fill so the contributions sum exactly to `q`.
 
 ## Shared boot path (`src/explorer/boot.ts`)
 
 `startExplorer(opts: ExplorerBootOpts): Promise<ExplorerHandle>` — the one
 launcher `/explore-roles` uses.
 
-- `EXPLORER_DEFAULT_PORT = 5177`; `listen` binds `127.0.0.1` and resolves the
+- `EXPLORER_DEFAULT_PORT = 5177`; `listen` binds the loopback address and resolves the
   actual port. A permanent `error` listener is attached before `listen`, so a
   post-listen socket error is logged instead of becoming an uncaughtException
   (which would tear down the whole omp session). `EADDRINUSE` → retry on port 0
   (OS-assigned).
-- Roles come from the **user-level** lock file only:
-  `readPluginSettingsMap({ global: lockPath, project: null })` keeps any
-  project-anchor file out of the merge. `resolveSettings` → `settings.roles`
-  (the resolved set = what the plugin does today); `roleUniverse(raw, roles)`
-  adds the roles it knows but does not rank (shipped opt-ins, lock-file-only
-  roles). `getState()` re-runs this read on **every** request, so a page reload
+- **Scopes** (`src/explorer/scopes.ts`). A scope is a role-config source: the
+  user-level scope (`lockPath`, default `PLUGIN_SETTINGS_PATH`), or one project
+  where `/project-roles` was used. `resolveScopes({ userLockPath, cwd, registryDir })`
+  returns the user-level scope, the registry's projects (most recently used
+  first), and the session's project when `cwd` has a project role config (a
+  project lock with a non-empty `omp-llm-role` settings entry — the updater's own
+  `resolveProjectDir` test) — included immediately, before the registry records
+  it. A scope id is `user` or `project:<root>`; `present` is whether the lock
+  file exists (the user scope is always available — Export creates it). The
+  default active scope is the session's project when present, else user-level.
+  `listScopes()` re-resolves on **every** request, so a project registered by
+  another session appears without a restart.
+- **Per-scope read.** `readScopeRoles(scope, userLockPath)` reads the user-level
+  lock file for the user scope, and the project lock merged **over** the
+  user-level lock for a project scope — the exact read the updater performs, so
+  the explorer and the plugin agree. `resolveSettings` → `settings.roles` (the
+  resolved set = what the plugin does today); `roleUniverse(raw, roles)` adds the
+  roles it knows but does not rank (shipped opt-ins, lock-file-only roles).
+  `getState(scope)` re-runs this read on **every** request, so a page reload
   after Export reflects the write instead of the state at boot.
+- **Dataset union.** The host loads the ranking data through `unionRoles(scopes,
+  userLockPath)` — the union of every known scope's resolved roles — plus the
+  shipped keys (`loadRankData({ roles, extraMetrics: Object.keys(KNOWN_METRICS) })`),
+  so the dataset carries every metric any scope weights — including a generic
+  llm-stats benchmark (`bench:<id>`) that only a project role pulls in. Loading
+  with no roles (`loadRankData({})`) fetches declared sources only, so a role
+  weighting an undeclared benchmark would rank on a dataset missing that metric
+  and the explorer would disagree with the updater. `extraMetrics` also forces
+  the `website`/`writing` fetches even when no role weights them. The union is
+  what keeps a scope switch free (one fetch) and is asserted as a pure call over
+  temp lock files, not through the injected `rank` fixture.
 - `enrichThinkingLevels(rank.models, opts.catalog)` gates the thinking price
-  factor on the omp catalog; `refresh()` re-runs `opts.reload(true)` and
-  re-enriches.
+  factor on the omp catalog; `refresh()` re-runs `opts.reload(true)`,
+  re-enriches, and — when `opts.reloadAvailability` is supplied — re-derives the
+  availability overlay.
+- `opts.availability` is the boot-time keyed-catalog overlay; `getState(scope)`
+  returns it on every request, so `/api/rank` and `/api/explain` annotate rows
+  without a second fetch. It is scope-independent and carried across switches
+  unchanged. `/explore-roles` builds it in-process from the session's OpenRouter
+  key (`ctx.modelRegistry.getApiKeyForProvider("openrouter")`) via
+  `fetchKeyAvailability`; a missing key or a failed fetch is `unavailable`
+  (best-effort — the explorer still boots).
 - `unref` (extension only) detaches the server from the event loop so a
   short-lived `omp -p` run cannot hang.
 - `open` launches the default browser on macOS (`execFile("open", [url])`).
@@ -146,7 +224,8 @@ The one validated role write path, shared by the explorer's Export,
 - `mergeExport(existing, dirty)` → `{lock}` or `{error}`. Preserves `plugins` and
   every sibling settings key. Writes each dirty role as **flat dotted keys**
   (`roles.<name>.weights.<metric>`, `.description`, `.enabled`, `.locked`,
-  `.required`, `.thinking`, `.lambda`, `.filters.image`) because omp's
+  `.required`, `.thinking`, `.providerPin`, `.cacheHitRate`, `.lambda`,
+  `.filters.image`) because omp's
   `/settings` Plugins tab shallow-merges the settings object and does not
   flatten nested objects — a nested `roles` object would render as schema
   defaults. A pre-existing nested entry for a dirty role is deleted, so an older
@@ -166,10 +245,40 @@ server-side; the client only renders and edits role defs. Model names come from
 a scraped third-party site, so the DOM is built with
 `textContent`/`createElement` only (the `el()` helper).
 
-- **Boot**: `boot()` → `GET /api/bootstrap` → fills `state` (`universe`,
-  `effective` = each entry's `def`, `defs` = a structuredClone of it, `defaults`,
-  `metrics`, `metricMeta`, `levels`, `thinkingFactors`, `lockPath`), wires the
-  filter/topn/export/copy/download controls, and selects the first role.
+- **Boot**: `boot()` → `GET /api/bootstrap` → `applyBootstrap(data)`, which fills
+  `state` (`scopes`, `activeScope`, `universe`, `effective` = each entry's `def`,
+  `defs` = a structuredClone of it, `defaults`, `metrics`, `metricMeta`,
+  `focusAssessments`, `levels`, `thinkingFactors`, `lockPath`, `availability`),
+  renders the header/roles/table, and selects the previously selected role when
+  the new scope has it, else the first role. `boot()` then wires the
+  filter/topn/hide-key-blocked/export/copy/download controls.
+- **Scope switcher**: the header renders a `#scope` `<select>` from
+  `state.scopes` (the user-level scope plus every known project); a scope whose
+  lock file is gone is `disabled` with a reason `title`. Changing the selection
+  confirms first when there are unsaved edits (mirroring Refresh), then
+  `POST /api/scope {scope}` and `applyBootstrap` on the returned payload — so
+  every panel (universe, per-scope effective/edited defs, role tabs, editor,
+  table, meta, lock path) reflects the new scope, and dirty tracking is per
+  scope. The header names the active scope and its lock file path.
+- **Focus table**: the editor renders a `table.focus` for the role's weighted
+  benchmark/percentile metrics (`focusMetricsOf`), one row per metric with the
+  nine signals from `focusAssessments[role]` (coverage, dispersion, composition,
+  freshness, trust, modality, maintenance, provenance, cross-source). A below-bar cell is warned (tint + glyph), `unknown` is muted —
+  never green. A metric the editor just added reads "not assessed" until the edit
+  is **Exported and the page reloaded** (the payload is computed over the resolved
+  definition, and the editor's in-memory edit is discarded by a plain reload).
+- **Features panel**: the editor renders one **tri-state** control per capability
+  (inherit / on / off) from the bootstrap payload's feature registry, showing the
+  recommended bundle and the effective values. A value the preset filled (rather
+  than an explicit key) is marked as **derived**, so authored and derived are
+  distinguishable. Toggling a control edits the role's `features.<id>` (the
+  tri-state's *inherit* leaves the key absent, so the global flag applies) and
+  re-ranks; the individual
+  per-knob fields the preset fills stay editable, and an explicit value wins over
+  the flag. **Export writes the flag**, never the expanded knobs — `dirtyRoles()`
+  is unchanged (it already compares the authored def against the authored
+  baseline), so a role whose only change is a flag exports just
+  `roles.<name>.features.<id>`.
 - **Recompute**: `selectRole` → `renderRoles`/`renderEditor`/`renderExplain` +
   `recompute()`. `recompute()` → `POST /api/rank {role, def}` → `state.rows`,
   `lambda`, `derivedLambda`, `errors`; re-renders the table and readouts, and
@@ -177,10 +286,29 @@ a scraped third-party site, so the DOM is built with
   changes call `scheduleRecompute()` (120 ms debounce).
 - **Explain**: `selectModel(id)` → `POST /api/explain {role, def, modelId}` →
   `renderExplain()` (composition table, cost line, "why not higher",
-  dominators).
+  dominators, and the availability line). The cost line appends `· best route`
+  when the model was priced on the soft best route (`ownProvider`), and a
+  **pin line** shows the pin in force: `pin: <slug> (manual)` when the edited def
+  carries a `providerPin`, else `auto pin: <slug>` from the explanation's
+  `autoPin` (read-only — the manual field is the only way to set one).
+- **Provider pin field**: the editor renders a text input for
+  `roles.<role>.providerPin` (a tiered slug like `deepinfra/fp8` is kept
+  verbatim; empty clears the key, resuming the automatic choice). It is the
+  manual override of the auto-pin; Export rejects a slug that matches no route in
+  the loaded dataset (see *Export path*).
+- **Availability overlay**: each row's `key` renders as a three-state badge in
+  the `key` column; the **hide key-blocked** checkbox beside the filter/top-n
+  controls drops `blocked` rows from the table (a client-side filter — the
+  ranking and Export are untouched); the header shows the allowlist size
+  (`keyedCount`/`publicCount`). The explain panel repeats the verdict and its
+  reason. When `availability.reason !== "active"` every badge reads `unknown`
+  and the tooltip/hint names OpenRouter → Settings → **"Filter the model catalog
+  for API keys"** — the explorer never guesses.
 - **Dirty tracking**: `dirtyRoles()` compares `JSON.stringify(defs[role])` to
   `effective[role]`; only dirty roles are sent to `POST /api/export`. On success
-  the client updates `effective` for the written roles.
+  the client updates `effective` for the written roles and the status names the
+  written lock file. The state is rebuilt from the payload on a scope switch, so
+  dirty tracking is per scope.
 - **Deep-merge parking**: `dropWeight(metric)` parks an inherited metric (one
   the shipped default weights) at `EPSILON = 0.001` instead of deleting the key
   — the plugin deep-merges over `DEFAULT_ROLES`, so the default's weight would
@@ -191,8 +319,9 @@ a scraped third-party site, so the DOM is built with
   re-rendered tables and editors need no per-node wiring. Metric and role
   tooltips are built from the bootstrap payload (`METRIC_META` / role
   descriptions), not duplicated in the client.
-- **Refresh**: `onRefresh()` confirms, then `POST /api/refresh` → re-renders the
-  header meta and recomputes.
+- **Refresh**: `onRefresh()` confirms, then `POST /api/refresh` →
+  `applyBootstrap` on the returned payload (the scope list is re-resolved, so a
+  project registered by another session appears).
 
 ## Open defect
 

package/docs/dev/quirks.md

@@ -1,9 +1,11 @@
 # Quirks
 
 Debugging-only oddities and gotchas that are **not** contracts. If a fact is a
-contract the implementation MUST satisfy, it belongs in [spec.md](spec.md); if it
-is user-facing, it belongs in [`../../README.md`](../../README.md). This file is
-the home for the things that only bite someone changing or debugging the code.
+contract the implementation MUST satisfy, it belongs in the topic doc that owns
+it ([`architecture.md`](architecture.md), [`scoring.md`](scoring.md),
+[`writes-and-state.md`](writes-and-state.md), …); if it is user-facing, it
+belongs in [`../../README.md`](../../README.md). This file is the home for the
+things that only bite someone changing or debugging the code.
 
 ## Data sources and joins
 
@@ -27,6 +29,28 @@ the home for the things that only bite someone changing or debugging the code.
 - **`index_*` scores are interval-scale** (observed −16..+60, can be negative);
   the fixed affine anchors (−20→0, +60→1) handle it.
 
+## Availability
+
+- **The probe's disqualifying 404 is narrow.** `probeModel` blocks a model only
+  on the exact "No allowed providers are available for the selected model …" 404;
+  every other failure (5xx, timeout, unknown model) counts as usable and stays in
+  omp's runtime-fallback domain. The account's allowed-providers whitelist is
+  enforced per serving endpoint, so the **org prefix is not a valid filter**:
+  aggregator-org models (`deepseek/*`, `z-ai/*`, `inclusionai/*`) run via
+  whitelisted third-party endpoints while `openai/*` and `anthropic/*` fail on
+  first-party-only routing.
+
+## Capability fill
+
+- **The fill can invert against the covered field.** The capability fill
+  (`CAPABILITY_FILL`, 0.195) is the percentile implied by the *uncovered*
+  cohort's mean general index, which sits above the bottom of the covered
+  field — so a covered model in the bottom ~8% of the field scores *below* a
+  model with no Design Arena data at all. Measured 2026-10-03: 4 of the 51
+  covered in-pool models (24 of 121 across all models). This is a
+  debugging-only oddity, not a contract; the fill is deliberately conservative
+  and a regression fill was rejected (see the `applyDesignPercentiles` comment).
+
 ## The 1/price² blend
 
 - **The blend renormalizes throughput over the routes that have p50 data**,
@@ -87,7 +111,24 @@ the home for the things that only bite someone changing or debugging the code.
 - **`api.zeroeval.com/leaderboard/benchmarks/<id>` is case- and
   separator-sensitive**: `alpacaeval-2.0` returns 200, `alpacaeval-2_0` and
   `ALPACAEVAL-2.0` return 404. The declaration's `fetch.url` must carry the raw
-  id exactly as the site spells it.
+  id exactly as the site spells it. The generic path normalizes the id to the
+  metric key (`deepswe-1.1` → `bench:deepswe-1_1`), so the updater's metric-key
+  fallback would fetch the normalized (404-ing) URL; the declaration
+  `catalogBenchmarkDeclaration` builds at discovery/authoring time is what
+  carries the raw id, and without it the metric is dead weight.
+- **A capability-filled generic benchmark bypasses the coverage gate.** The
+  generic llm-stats source (`genericBenchmarkSource` / `llmStatsBenchmarkDeclaration`)
+  declares `fill: 0.195`, and `focusCoverageOk` returns `ok` for any metric whose
+  `metricFill > 0` — so a `bench:<id>` metric with 1 covered model reports
+  `coverage.status = "ok"` and is rejected (if at all) on dispersion,
+  composition or freshness, never on coverage. Measured 2026-10-06: `bench:supergpqa`
+  covers 20/400 (5.0%) and still reports `status=ok`. The coverage floor only
+  binds fill-0 metrics. Do not read `coverage.status = "ok"` as "well covered".
+- **The per-benchmark endpoint caps `entries` at 20** (`BENCHMARK_ENTRY_CAP`),
+  regardless of `limit`/`offset`/`page`/`per_page`, so a generic `bench:<id>`
+  metric can never load more and no pagination loop helps. `total_models` still
+  reports the full set, so `loaded < total` marks a capped load and the coverage
+  count is the loadable count, never the catalog's `model_count`.
 
 ## Runtime
 
@@ -105,6 +146,22 @@ the home for the things that only bite someone changing or debugging the code.
   update (or a `link` to a changed tree), a session that was already running
   still executes the module it loaded at start; a write from that stale code can
   revert a newer write. Restart the session after updating the plugin.
+- **omp's restore-to-primary is silent to extensions.** After a fallback
+  cooldown, omp restores the primary model at prompt admission
+  (`#maybeRestoreRetryFallbackPrimary`) with **no** session event, and
+  `model_changed` is not delivered to extensions — so a display derived from the
+  fallback events alone would keep the fallback's provider pin after a restore.
+  The provider display (`src/provider-display.ts`) therefore re-derives the pin
+  from the live model on `turn_start`, which *is* extension-delivered and fires
+  after the restore. The same re-derive covers a manual `/model` change (with a
+  one-turn lag). The primary and a fallback may be the same registry object
+  (same model id, different route), so the strip-then-append is idempotent and
+  reads the pin from the live model's routing block, never a cached value.
+  `retry_fallback_applied`/`retry_fallback_succeeded` are also emitted for
+  **advisor** fallbacks, where only the advisor's model changes and the session
+  model is untouched, so the event's selector is trusted only when it names the
+  live session model (`liveModelIsSelector`); otherwise the pin is re-derived
+  from the live model's routing block.
 - **Testing a registered slash command needs `--mode rpc` or a TUI** — `omp -p`
   (print mode) sends a leading `/name` as a *prompt* to the model, so the handler
   never runs and `ctx.ui.notify` is a no-op anyway. RPC mode does dispatch them:
@@ -113,6 +170,22 @@ the home for the things that only bite someone changing or debugging the code.
   stderr; `get_available_commands` confirms registration. Verified this way for
   `/create-agent` and `/explore-roles` (omp 18.4.8).
 
+## Repository plumbing
+
+- **The https credential cannot *introduce* a workflow change.** `origin` is
+  https and its credential is a `gh` OAuth token with scopes
+  `admin:public_key, gist, read:org, repo` — no `workflow` — so a push that adds
+  or modifies `.github/workflows/*` is rejected ("refusing to allow an OAuth App
+  to create or update workflow … without `workflow` scope"), and the REST
+  contents API is rejected the same way. The check is a diff against the ref's
+  base, not a property of the ref: a new branch or tag whose commit already
+  contains the workflow, with `main` also containing it, pushes fine over https
+  (verified 2026-10-08). So only the commit that lands a workflow edit needs the
+  SSH route — `git push git@github.com:Gott50/omp-llm-role.git main` — and
+  because that bypasses the `origin` remote it leaves `refs/remotes/origin/main`
+  stale, which makes `scripts/release.ts cut` refuse ("HEAD is not origin/main")
+  until `git fetch origin` runs.
+
 ## Historical
 
 - **Bare roles were priced as if thinking were free** (fixed 2026-09-30).

package/docs/dev/releasing.md

@@ -2,8 +2,57 @@
 
 `version` in `package.json` is the release switch — bump it, commit, then
 publish through any channel (same tree, no build step). The repo is public
-(flipped 2026-10-02), so the git and marketplace URLs below resolve; the npm
-channel is not published yet — see Status.
+(flipped 2026-10-02) and 1.0.0 is published to npm (2026-10-03), so all three
+channel URLs below resolve — see Status.
+
+## When to bump, and to what
+
+The version is a **release switch, not a per-commit counter**: bump it once per
+published batch, at release cut. The trigger is the scope of `CHANGELOG.md`'s
+`## [Unreleased]` section — what actually landed. An empty `## [Unreleased]`
+owes no release; a non-empty one owes exactly one bump. Unimplemented open
+issues (the GitHub tracker) never decide the number.
+
+Pick the number with SemVer over the plugin's **public surface**: the plugin
+settings (`roles.*`, `filters.*`, …), the commands (`/refresh-roles`,
+`/explore-roles`, `/create-agent`, `/remove-agent`), the `config.yml` write
+contract (`modelRoles`, `retry.fallbackChains`, `task.disabledAgents`), the CLI
+flags, the shipped roles/agents, and the three install channels.
+
+- **PATCH** (`1.0.x`) — a fix with no public-interface and no shipped-role
+  behavior change (crash fix, cache parse fix, doc-only correction).
+- **MINOR** (`1.x.0`) — any additive, backward-compatible change: a new optional
+  setting, metric, role, agent, command or flag. **Ranking-output changes are
+  minor too** (weights, price basis, sources): a ranking is data-dependent
+  output, not a versioned interface, so a reweight or re-basis is minor even
+  though every pick may move.
+- **MAJOR** (`x.0.0`) — anything that invalidates an existing config or breaks
+  an existing caller: removing or renaming a public setting; changing an
+  existing setting's meaning so a previously valid config behaves differently;
+  changing the `config.yml` patch shape, selector or chain format
+  incompatibly; dropping an install channel or renaming the package; requiring
+  a manual migration.
+- **Corner case.** Making a declared-but-inert setting start enforcing its
+  documented capability is a MINOR fix, not a MAJOR break — provided the key is
+  not renamed and no shipped role sets it.
+
+## How to cut a release
+
+The cut is one command, `scripts/release.ts` — its subcommands, the lockstep
+set, the refusals and the tag→publish contract are in [`ci.md`](ci.md). The
+policy above decides the number; the script applies it:
+
+```sh
+node scripts/release.ts due                 # is a release owed? (exit 1 = no)
+node scripts/release.ts cut minor --dry-run # review the target version + changelog diff
+node scripts/release.ts cut minor           # bump, cut, commit, push, tag
+```
+
+`cut` bumps the four lockstep version fields, renames `## [Unreleased]` and
+inserts a fresh one, rewrites the footer link refs, regenerates the committed
+report, commits, pushes `main` and pushes the tag. The tag push publishes to npm
+over OIDC and creates the GitHub Release — there is no local `npm publish` step
+and no token. Verify the channels per "Install-route verification".
 
 ## Channels
 
@@ -35,7 +84,27 @@ src, web, agents, skills,
 docs/dev, docs/llm-role-rankings.md
 ```
 
-Caches and tests stay out. Gate: `node --test tests/`.
+Caches, tests and `.githooks` stay out. Gate: `node --test tests/` (the
+pre-commit hook and CI both run it — see [`ci.md`](ci.md)).
+
+## Changelog rules
+
+`CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and is the source of truth for the release scope.
+
+- Every **user-visible** change gets a line under `## [Unreleased]`, in the
+  section that fits (`Added` / `Changed` / `Fixed` / `Removed`; add
+  `Deprecated` / `Security` only when needed).
+- **User-visible** = a user or maintainer would notice: ranking or config
+  output, the settings surface, shipped roles/agents, commands, install routes,
+  a contract or prompt version marker, or a doc fact that changed with the
+  behavior. Internal-only work (refactors, tests, formatting, a
+  `docs/dev`-only policy or research note) gets no entry.
+- One entry per change: bold lead phrase, then what changed and why; end with
+  `(issue #N)` / `(PR #N)` when one exists.
+- Land the entry in the same commit as the change (see `AGENTS.md`).
+- Never write a `## [<version>]` heading outside a release cut; never reword or
+  move entries when cutting — rename the heading and keep them verbatim.
 
 ## Install-route verification
 
@@ -47,17 +116,61 @@ path, plus `marketplace update` + `upgrade` to a bumped catalog version), and
 
 ## Status
 
-- **Repo public** (2026-10-02). `Gott50/omp-llm-role` was flipped from private
-  to public; `main` is pushed (`cc120bb`).
-- **git + marketplace verified against the real URLs** (2026-10-02, omp
-  18.4.10, throwaway `HOME`s): `omp plugin install github:Gott50/omp-llm-role`
-  and `omp plugin marketplace add Gott50/omp-llm-role` +
-  `omp plugin install omp-llm-role@gott50-plugins` both installed 1.0.0, and
-  each post-install session run wrote `modelRoles` + `retry.fallbackChains`
-  into that HOME's `config.yml` and landed the three daily caches in the
-  installed copy.
-- **npm not published.** `omp-llm-role` is unclaimed on the registry
-  (`npm view omp-llm-role version` → 404) and no npm credential exists on the
-  workstation (`~/.npmrc` absent, keychain empty). Publish needs an
-  interactive `npm login` (or an automation token) first; then
-  `npm publish` from the repo root and `npm view omp-llm-role version` → `1.0.0`.
+- **CI/CD landed 2026-10-08** (`fa7e546`, docs follow-ups `4f78ce2`, `1d20ef9`,
+  `9244fdc`, `3c0125a`): every pull request and every `main` push runs the suite
+  on GitHub (verified green on PR #57 and on the `main` pushes), and a `v*` tag
+  push publishes to npm over OIDC and creates the GitHub Release. The guard was
+  verified with a negative control — tag `v0.0.1` against version `1.1.0` failed
+  in `notes` before any publish.
+- **1.1.0 published by CD 2026-10-09** (run 37897647817,
+  `gh workflow run ci.yml --ref v1.1.0`): the guard and the npm floor passed,
+  `npm publish` completed over OIDC trusted publishing with a provenance
+  attestation (`npm audit signatures`: 0 invalid, 0 missing), and the GitHub
+  Release was created with the 1.1.0 CHANGELOG section as its body
+  (`https://github.com/Gott50/omp-llm-role/releases/tag/v1.1.0`). Verified:
+  `dist-tags.latest` = `1.1.0`, npm's `gitHead` = `4f78ce2` (the tag's commit),
+  `_npmUser` = `GitHub Actions` carrying the trusted-publisher OIDC config, the
+  provenance statement in the transparency log at
+  `https://search.sigstore.dev/?logIndex=3159690884`, and the tarball is 56
+  files / 308.4 kB. The `v1.1.0` tag was repointed to
+  `4f78ce2` first — its original commit predates the workflow file, so the
+  dispatch was rejected (see [`ci.md`](ci.md)).
+- **npm route smoke-tested for 1.1.0** (2026-10-09, omp 18.8.6, throwaway
+  `HOME`, cwd outside the real home tree): `omp plugin install omp-llm-role`
+  installed 1.1.0 from the registry (`omp plugin doctor`: 4 ok, 0 warnings,
+  0 errors) and the post-install session run (`omp -p "say ok"` with
+  `OPENROUTER_API_KEY` from `omp token openrouter`) wrote `modelRoles`
+  (9 roles), `retry.fallbackChains` and `task.disabledAgents: [designer]` into
+  that HOME's `config.yml`, landed `llm-role-state.json` +
+  `llm-role-history.jsonl`, and answered.
+- **1.1.0 cut 2026-10-08** (`c013918`, tagged `v1.1.0` — repointed to `4f78ce2`,
+  see the publish bullet). `package.json` and
+  `.omp-plugin/marketplace.json` bumped in lockstep (plus `package-lock.json`
+  via `npm install --package-lock-only` — the repo keeps it in lockstep, see
+  `8811309`), `## [Unreleased]` renamed to `## [1.1.0] - 2026-10-08`, and the
+  report regenerated (407 models, matched 155/407, priced 153;
+  `docs/dev/current-state.md` refreshed to the same measurement).
+- **git + marketplace channels live and verified** (2026-10-08, omp 18.4.12,
+  throwaway `HOME`s, cwd outside the real home tree):
+  `omp plugin install github:Gott50/omp-llm-role` installed 1.1.0
+  (`omp plugin doctor`: 4 ok, 0 warnings, 0 errors), and
+  `omp plugin marketplace add Gott50/omp-llm-role` +
+  `omp plugin install omp-llm-role@gott50-plugins` installed 1.1.0 into
+  `…/cache/plugins/gott50-plugins___omp-llm-role___1.1.0`. Both routes then
+  passed the post-install session smoke (`omp -p "say ok"` with
+  `OPENROUTER_API_KEY` from `omp token openrouter`): the installed 1.1.0 wrote
+  `modelRoles` (9 roles), `retry.fallbackChains` and
+  `task.disabledAgents: [designer]` into that HOME's `config.yml`, landed
+  `llm-role-state.json` + `llm-role-history.jsonl`, and the session answered.
+- **1.0.0 on all three channels** (2026-10-03): `omp-llm-role@1.0.0` on npm
+  (`dist-tags.latest` = `1.0.0`), tagged `v1.0.0` at `fe98b76` (npm's
+  `gitHead`); all three routes verified end-to-end against the real URLs
+  (omp 18.4.12, throwaway `HOME`s) — each post-install session run wrote
+  `modelRoles` + `retry.fallbackChains` into that HOME's `config.yml` and
+  landed the three daily caches in the installed copy.
+- **Stray registry placeholder.** The registry also carries a `0.0.0-stage`
+  version ("Temporary package placeholder for staged publishing", 334 B,
+  published 2026-10-03). It is not from this tree and does not affect installs
+  (`latest` is `1.1.0`).
+- **Next release: one owed.** `## [Unreleased]` carries the CI/CD entry; the
+  number comes from the Unreleased scope, not from the open issues.