omp-llm-role 1.0.0 → 1.2.0

package/README.md

@@ -48,6 +48,16 @@ omp plugin install omp-llm-role@gott50-plugins
   session actually booted on the previous `default` selector (an explicit
   `omp --model X` is never clobbered), and only on a real change. Disable with
   `activateDefaultOnEmptySession=false`.
+- **Provider in the model display.** When the live session model carries a
+  provider pin — a hand-set `providerPin`, or the automatic pin the
+  `providerPinning` capability writes — the status line's model segment shows
+  the route next to the model name, e.g. `DeepSeek V4.1 Flash @coreweave/fp8`.
+  The suffix is applied on session start, refreshed when a fallback switches the
+  model, and re-derived at the start of every turn, so it self-heals after omp
+  silently restores the primary model following a fallback cooldown. An unpinned
+  model's display is unchanged, and the suffix is display-only: it rides the
+  model object's `name`, so attribution, usage recording and model comparison
+  are unaffected.
 - **Surgical writes.** Only managed role lines, managed chain keys, and the
   plugin-managed `task.disabledAgents` names change; comments, blank lines and
   unknown keys stay byte-identical, and a no-change run writes nothing.
@@ -62,7 +72,7 @@ omp plugin install omp-llm-role@gott50-plugins
 | `smol` | Fast lightweight model: cheap and quick, still competent |
 | `slow` | Most capable model for hard problems; cost and speed as tiebreakers |
 | `vision` | Image understanding: vision index dominates |
-| `plan` | Planning: reasoning, math, long-context coherence |
+| `plan` | Planning: reasoning and long-context coherence, priced so the cheapest capable planner wins |
 | `commit` | Commit messages: cheap and fast with decent general quality |
 | `tiny` | Background tasks (titles, memory): cheapest and fastest wins |
 | `task` | Subagents: agentic + tool calling, moderate cost sensitivity |
@@ -110,6 +120,7 @@ Global knobs:
 | `writeFallbackChains` | `true` | Write per-role fallback chains into `config.yml` |
 | `fallbackChainDepth` | `2` | Fallback models per role chain |
 | `activateDefaultOnEmptySession` | `true` | Reapply the new `default` selector to an empty session's active model |
+| `errorReporting` | `off` | Opt-in reporting of **unexpected** plugin errors as GitHub issues on `Gott50/omp-llm-role`; one of `off`, `ask`, `auto` (see below) |
 
 Per-role knobs (`roles.<name>.*`):
 
@@ -120,10 +131,100 @@ Per-role knobs (`roles.<name>.*`):
 | `weights` | shipped set | Metric weights; must sum to 1.0 ± 0.01 |
 | `required` | shipped set | Eligibility gate (metrics a model must have); independent of weights |
 | `filters.image` | `false` (`vision`/`designer`: `true`) | Restrict the pool to image-capable models |
+| `filters.tools` | `false` | Restrict the pool to models with a tool-capable route |
+| `filters.minContextTokens` | `0` (off) | Drop routes whose endpoint context is below this (tokens) |
+| `filters.minOutputTokens` | `0` (off) | Drop routes whose endpoint output ceiling is below this (tokens) |
+| `filters.maxPriceUsdPerM` | `0` (off) | Drop a model whose thinking-adjusted blend exceeds this ($/M) |
 | `thinking` | shipped level | Thinking level appended to the selector (`off`…`max`, `auto`) |
+| `providerPin` | `""` (unset) | Pin the role's requests to one OpenRouter provider route (`@<slug>`, may be tiered like `deepinfra/fp8`). The role is then priced and gated by that route — its billed price and p50 throughput, not the `1/price²` blend — and a model with no matching route is ineligible. A manual pin **overrides** the automatic pin the `providerPinning` capability would write |
+| `cacheHitRate` | `0` (off) | Assumed cache-hit rate (0–1) for the role's input tokens; each route's effective input price becomes `h·cacheRead + (1−h)·input` before the 3:1 billed blend and the thinking factor. The `1/price²` weight basis stays the **listed** input price (the router's sort key), so a cheap cache on a lightly-weighted route cannot dominate; a route with no cache-read price keeps its full input price. `0`/absent = off (byte-identical ranking) |
 | `lambda` | derived | Explicit λ ($ per quality point) override |
 | `locked` | `false` | Leave the role alone: rank it but never rewrite its selector or chain (explorer toggle) |
 
+**Capability flags** (`features.<id>` global, `roles.<role>.features.<id>` per
+role). One named flag per opt-in capability; turning it on applies the plugin's
+recommended settings for that capability to the role. Every individual knob
+stays settable, and an explicit knob always beats the flag. **Every flag ships
+OFF** — with no flags set, the resolved roles are byte-identical to the shipped
+defaults.
+
+| Flag | Recommended settings | What it buys |
+|---|---|---|
+| `endpointCeilings` | `filters.tools: true`, `filters.minOutputTokens: 16384` | Routes that cannot call tools and routes whose output ceiling is below 16 384 tokens leave the pool — a reasoning model is not cut off mid-thought |
+| `cachePricing` | `cacheHitRate: 0.5` | The role is priced on a cache-heavy agent loop's invoice (the endpoint's `cacheReadPrice` blended in) rather than the sticker price |
+| `providerPinning` | `preferOwnProvider: true`, `filters.preferredMinThroughput: 50` | Each request is bound to the model's **best provider route** — the max-value-for-money route (the `vfm` score, with a soft 50 tok/s floor that deprioritizes a pathologically slow route without dropping it) — the selector gains `@<slug>` — and the fallback chain carries the primary model on every gate-passing route except the pinned best, then each fallback model on every gate-passing route, so a down provider fails over to another provider of the same model before the chain switches models. The model is priced **and measured** on that route (its billed price and p50 throughput, so `q` moves too), falling back to the default blend only when it has no candidate route |
+| `costCap` | `filters.maxPriceUsdPerM: 10` | The priciest tail of the eligible pool leaves it, so the pick cannot be an expensive outlier |
+
+Precedence is one rule:
+
+```
+effective def = shipped default  ⊕  preset(enabled flags)  ⊕  explicit user keys
+```
+
+A flag is on when `roles.<role>.features.<id>` is present (it wins either way)
+and otherwise when the global `features.<id>` is `true` — so a per-role `false`
+beats a global `true`. The preset fills only knobs the role does not already
+set, and an explicit key is merged last, so it always wins. `providerPinning`'s
+recommended setting is a **soft per-model policy** (`preferOwnProvider`), not a
+hard `providerPin`: it prices a model on its **best route** (the max-`vfm` route
+— the value-for-money score, with the soft 50 tok/s floor — among the
+filter-passing, non-degraded, priced routes the account's
+allowed-providers whitelist permits) — the route's billed price
+**and** its p50 throughput, so `q` moves as well as `priceEff` — and never makes
+a model ineligible (the hard `providerPin` stays available by hand, and overrides
+the automatic choice). `minContextTokens` is deliberately **not** part of `endpointCeilings` —
+the complaint it would answer is an endpoint advertising a *fraction of the
+model's own window*, which an absolute token floor cannot express, so it stays a
+hand-set knob.
+
+The flags are settable from every role-authoring surface: `--feature <id,...>`
+(comma-separated) on `node src/cli/create-role.ts`, `/create-agent` and
+`/project-roles` (`--list-features` lists them on the first two), plus the
+explorer's Features panel. An
+unknown flag id or a non-boolean value aborts the run with the offending key and
+no write.
+
+**Error reporting (`errorReporting`).** This knob ships **`off`** — installing
+or upgrading the plugin never starts uploading anything. When something
+*genuinely unexpected* happens (a `/refresh-roles` or authoring command throws,
+or the updater hits an internal error), the plugin can file one structured
+report — the plugin version, runtime, platform, the command that failed, the
+error name/message/stack and a timestamp — as a GitHub issue on
+`Gott50/omp-llm-role`. The three values:
+
+- **`off`** — never files; behaviour is exactly today's (one warning line).
+- **`ask`** — shows you the exact text and files it only if you confirm. In a
+  session with no UI (`omp -p`, RPC, a subagent) it never uploads: it notifies a
+  prefilled new-issue URL instead, so you can submit it yourself.
+- **`auto`** — files without asking.
+
+The payload is redacted before it leaves the machine (your home directory → `~`,
+token-shaped strings → `<redacted>`) and carries **no** config contents, model
+selectors, prompts or history rows. Filing goes through the GitHub API when a
+token is available (`GITHUB_TOKEN` → `GH_TOKEN` → `gh auth token` — the token is
+never stored in a settings file); a token that cannot write issues here, or no
+token at all, falls through to a prefilled `…/issues/new` URL (opened in your
+browser, or printed). A repeated crash comments on the existing open issue
+instead of opening a new one, and the path is capped (one open issue per
+fingerprint, one creation per fingerprint per UTC day, 3 per day) so a crash
+loop cannot spam the tracker. Reporting is **best-effort**: a failure in it only
+adds one notification line and never affects the run it reports on. Expected
+environment conditions (no key budget, a concurrent refresh holding the lock,
+write conflicts, unavailable ranking data, invalid settings) are **never**
+reported. In project mode the project lock file's value applies.
+
+**Validation.** A run aborts (notify, no write) on: a weight ≤ 0, or a role's
+weights not summing to 1.0 ± 0.01; a `required` entry or a weighted metric
+outside the known-metric set; a `thinking` level outside
+`off|minimal|low|medium|high|xhigh|max|auto`; `switchMargin`/`priceSwitchFraction`
+outside `[0, 1]`; a non-boolean `enabled`; a `cacheHitRate` outside `[0, 1]`; a
+`providerPin` that is empty or
+contains `@`/`:` (the selector's own delimiters); an unknown capability id
+(global or per-role) or a non-boolean flag value; a non-boolean
+`preferOwnProvider`. `weights: null` opts a role out;
+the legacy `suffixes.*` keys are rejected with a migration hint (moved into
+`roles.<role>.thinking`).
+
 **Typed writes.** `omp plugin config set <plugin> <key> <value>` stores every
 value as a **string**, which the validator rejects for numbers/arrays/booleans,
 so it is only usable for string-valued keys. Write typed role defs with
@@ -144,10 +245,11 @@ with the offending role/key and no write.
 /create-agent <request> [options]       # agent + role + wiring (free text or flags)
 /create-agent --name <n> --purpose <text> [options]   # agent + role + wiring
 /remove-agent --name <n> [--scope user|project] [--lock PATH] [--yes] [--dry-run]   # delete an agent and its role
+/project-roles [--purpose <text>] [--roles <spec>] [--feature <id,...>] [--force] [--yes] [--dry-run] [--json]   # project-scoped role set
 
 # CLI
 node src/cli/llm-role-rank.ts [--top N] [--json] [--out FILE] [--refresh] [--all] [--url URL]
-node src/cli/create-role.ts --name <role> --weights m=w,... [--required m,...] [--thinking <level>] [--description <text>] [--image] [--lambda N] [--lock PATH] [--dry-run] [--json]
+node src/cli/create-role.ts --name <role> --weights m=w,... [--required m,...] [--thinking <level>] [--description <text>] [--image] [--lambda N] [--feature <id,...>] [--list-features] [--lock PATH] [--dry-run] [--json]
 node --test tests/
 ```
 
@@ -161,6 +263,9 @@ node --test tests/
 - `/remove-agent` — the inverse of `/create-agent`: deletes the agent `.md` and
   its role, then runs the updater in-process so `modelRoles.<n>` is dropped;
   refuses shipped default roles (see *Remove a specialist agent*).
+- `/project-roles` — discover the project's usecase from its own artifacts and
+  apply a project-scoped role set to `<cwd>/.omp/config.yml` (see *Project
+  roles*).
 - `src/cli/llm-role-rank.ts` — markdown report to stdout (per-role tables + suggested
   `modelRoles`). `--top N` rows per role (default 10); `--json` machine payload;
   `--out FILE` write instead of stdout; `--refresh` bypass both caches; `--all`
@@ -193,6 +298,25 @@ agent is ranked on WritingBench, Creative Writing v3, COLLIE and the other
 writing benchmarks, not just the one you named. Discovery is non-fatal and
 skippable with `--no-discover`; an explicit `--benchmarks` list wins over it.
 
+Discovery is **quality-gated**: each candidate is assessed on nine axes —
+coverage (share of the field carrying the metric), dispersion (does it separate
+models), provider composition, freshness, trust (the share of the payload's
+entries that are self-reported, so a mostly vendor-submitted source is flagged),
+modality (the catalog row's modality and the payload's multimodal share — an
+annotation, never a gate), maintenance (the catalog row's dataset age against
+a 12-month bar — an annotation, never a gate), provenance (the benchmark's
+owner and the source's own per-entry org mix, cross-checked against the
+composition axis — an annotation, never a gate) and cross-source (the zeroeval
+per-entry price/context against the plugin's own, flagging a divergence past a
+tolerance — an annotation, never a gate, and never a change to the `1/price²`
+blend) — and a discovered benchmark that
+fails a gating axis is dropped rather than folded in (a benchmark you name yourself is
+never dropped, only warned). The focus set is capped at three benchmarks so one
+keeps a decisive share. The report prints the nine signals and warns per below-bar
+axis, and warns when the new role's top pick is the same as the `default` role's
+(the role adds nothing). The agent file is written before the role, so a partial
+failure never leaves a dangling role.
+
 The flag form is equivalent and gives you the name explicitly:
 
 ```sh
@@ -206,7 +330,9 @@ validated role into the settings lock file, and runs the updater in-process so
 `modelRoles.review` lands in `config.yml` — nothing to remember. Options:
 `--archetype <id>`, `--weights m=w,...`, `--required`, `--thinking`, `--tools`,
 `--benchmarks m,...` (extra metrics to fold in; `--list-benchmarks` prints the
-weightable set, including any external benchmark in use), `--scope user|project`,
+weightable set, including any external benchmark in use), `--feature <id,...>`
+(comma-separated capability flags; `--list-features` prints the capability set),
+`--scope user|project`,
 `--body`/`--body-file`, `--force` (overwrite an existing agent file), `--yes`
 (accept a proposed benchmark source without prompting), `--no-discover` (skip
 catalog discovery), `--dry-run`, `--json`. In
@@ -253,6 +379,32 @@ By hand, the same two artifacts:
 2. Delete the agent file: `rm ~/.omp/agent/agents/review.md`.
 3. Wire it: `/refresh-roles` in a session.
 
+## Project roles
+
+`/project-roles` discovers a project's usecase from its own artifacts (README,
+package.json, AGENTS.md, docs listing, git log, file tree) and applies a
+**project-scoped** role set — the roles the project needs, with agents authored
+for the new ones — to `<cwd>/.omp/config.yml`:
+
+```sh
+/project-roles
+/project-roles --purpose "a Python data pipeline repo" --dry-run
+/project-roles --roles "data=build pipelines,-vision,default"
+```
+
+It prints the plan (kept / dropped / added roles, each new role's archetype,
+weights, focus benchmarks and top pick) before writing. `--purpose` overrides the
+discovered usecase; `--roles` overrides the role set (`-name` drops a shipped
+role, `name` keeps or adds one, `name=purpose` adds a new role); `--dry-run`
+writes nothing; without `--force` an existing project role config is refused.
+
+When a project carries its own `omp-llm-role` settings entry, the updater scopes
+the whole run to `<cwd>/.omp` — the config, the state/history/lock files and the
+day gate — so the project's `modelRoles` are refreshed independently of the
+global `~/.omp/agent/config.yml`, which is never written in project mode. A
+successful apply registers the project, so the explorer's **scope switcher**
+lists it (see below).
+
 ## Explorer
 
 `/explore-roles` in omp boots a loopback-only web UI
@@ -260,6 +412,15 @@ By hand, the same two artifacts:
 `@slow`?" and "what happens if I care more about price than agents?" without
 editing source and re-running the CLI.
 
+- **Scope switcher** — the header lists every role-config source: the
+  **user-level** scope, plus every project where `/project-roles` was used (the
+  plugin records each project root in a small global registry, and the current
+  session's project is listed immediately). The explorer opens on the session's
+  project when the cwd has a project role config, else user-level. Switching
+  re-reads that scope's roles and universe from disk and points **Export** at
+  that scope's lock file — a project scope resolves as the project lock merged
+  over the user-level lock, exactly what the updater ranks. A project whose lock
+  file is gone is shown disabled. Switching with unsaved edits asks first.
 - **Role tabs** — every role the plugin knows: the nine omp built-in roles, the
   shipped opt-in `designer`, and any role present only in the lock file. Each
   tab is tinted by provenance — `default` (omp built-in), `plugin` (shipped but
@@ -307,12 +468,30 @@ The plugin keeps only models the OpenRouter key can actually run:
 - **Tier/budget gate** — paid keys with budget get billed variants, free or
   exhausted keys get `:free` variants, `:batch` never. Every candidate must
   resolve in omp's catalog.
-- **Probe verification** — on top of the gate, every candidate is verified with
-  a one-token completion probe, because the account's OpenRouter
-  **allowed-providers privacy whitelist** is invisible to the key and catalog
-  endpoints and a real request's 404 is the only reliable signal. Blocked
-  candidates are excluded from selection and chains; a role with no clean
-  candidate is left untouched.
+- **Keyed-catalog fast path** — when the account's OpenRouter setting **"Filter the
+  model catalog for API keys"** is on, the key-authenticated `GET /api/v1/models` is a
+  per-key allowlist: allowed candidates skip the probe and key-blocked candidates are
+  pruned from the walk. With the setting off (or the fetch failing) the plugin falls
+  back to the probe walk below — no abort.
+- **Probe verification** — the fallback: every candidate is verified with a one-token
+  completion probe, because the account's OpenRouter **allowed-providers privacy
+  whitelist** is invisible to the key endpoint and the unauthenticated catalog, and a
+  real request's 404 is the only reliable signal. Blocked candidates are excluded from
+  selection and chains; a role with no clean candidate is left untouched.
+- **Allowed-providers whitelist** — the account's OpenRouter **allowed-providers
+  privacy whitelist** (openrouter.ai/settings/privacy) is learned once per run (a
+  canary request that bills no tokens) and every model's route pool is narrowed to
+  allowed providers before ranking, so a pin or a fallback hop is never written on a
+  provider the account cannot use. The run notes `OpenRouter allowed-providers
+  whitelist active — N providers; M routes pruned` (or `… whitelist: no whitelist`).
+  With no whitelist set — or when the harvest fails — nothing changes.
+- **Explorer key marking** — the explorer overlays every ranked model with a
+  **usable** / **key-blocked** / **unknown** badge derived from the
+  key-authenticated `GET /api/v1/models` (the account setting **"Filter the model
+  catalog for API keys"** makes it a per-key allowlist). A **hide key-blocked**
+  toggle drops blocked rows, and when the setting is off every badge reads
+  *unknown* with a hint naming the OpenRouter setting. The mark is read-only: it
+  never edits roles, reorders ranks or changes an Export.
 
 ## Caveats
 
@@ -320,10 +499,21 @@ The plugin keeps only models the OpenRouter key can actually run:
   occupying its share of the denominator, so weight sparse metrics as
   differentiators, never as `required` gates. `website`, `writing` and
   `long_context` are capability-filled (0.195) instead, so absence is not a
-  penalty for them.
+  penalty for them — with one residual inversion: the fill sits above the bottom
+  of the covered field, so a covered model in the bottom of the field can still
+  score below a model with no data (see
+  [docs/dev/quirks.md](docs/dev/quirks.md)).
 - **Provider whitelist.** The account's allowed-providers whitelist blocks many
   models, so the report's #1 and the written selector can differ — judge weights
-  on the reachable pool.
+  on the reachable pool. The updater prunes *routes* to the whitelist (see
+  Availability), but the report has no token and is not whitelist-aware.
+- **Provider pinning opts out of auto-Exacto.** A `providerPin` — or the
+  automatic pin the `providerPinning` capability writes — puts a trailing
+  `@<slug>` on the selector, which omp applies as OpenRouter
+  `provider: { only: [slug] }` routing. `only` is exclusive, so a pinned role's
+  requests bypass OpenRouter's automatic Exacto tool routing (which routes tool
+  calls by tool-call correctness) and run on the pinned route. Pin only where you
+  know the endpoint you want; leave tool-heavy roles on the default routing.
 - **Model concentration.** The cheapest pick concentrates on one vendor; the
   fallback chains mitigate it.
 
@@ -334,6 +524,6 @@ MIT — see [LICENSE](LICENSE).
 ## Documentation
 
 Maintainer docs (architecture, data sources, scoring, writes/state, explorer
-internals, releasing, agent authoring, the normative spec) live in
+internals, releasing, agent authoring, testing) live in
 [docs/dev/README.md](docs/dev/README.md); release history is in
 [CHANGELOG.md](CHANGELOG.md).

package/agents/designer.md

@@ -1,8 +1,8 @@
 ---
 name: designer
-description: UI/UX specialist for design implementation, review, visual refinement
+description: MUST be used for UI/UX design implementation, review, and visual refinement.
 model: "@designer, @default"
-tools: [read, bash, edit, ast_grep, ast_edit, ask, debug, ida, eval, github, glob, grep, find, lsp, checkpoint, rewind, context_notes, new_context, security_scan, task, wait, todo, web_search, write, memory_edit, retain, recall, reflect, learn, manage_skill]
+tools: [read, grep, glob, find, edit, write, bash, ast_grep, ast_edit, eval, lsp, web_search, ask, todo, task, wait, checkpoint, rewind]
 ---
 
 Implement/review UI designs; edit files, create components, run commands as needed.
@@ -30,6 +30,7 @@ Design system: foundation; UI without one becomes inconsistent. Four phases, in
 3. Implement states: loading, empty, error, disabled, hover, focus.
 4. Verify accessibility: contrast, focus rings, semantic HTML.
 5. Test responsive behavior.
+6. Render and inspect: start the project's dev server (or open the built page), open the route in the browser via `eval` (`browser.open`), `screenshot` it, and check the project's actual breakpoints, both light and dark themes, and focus states. The `browser` facade is an Eval prelude, not an agent tool, so it cannot appear in `tools:` — the instruction lives here in the body.
 
 ## Review
 1. Read reviewed files.
@@ -56,7 +57,7 @@ Design system: foundation; UI without one becomes inconsistent. Four phases, in
 - Same spacing everywhere: no rhythm; monotony
 - Center-aligning everything: left alignment with asymmetry feels more designed
 - Modals for everything: lazy, rarely best
-- Overused fonts: Inter, Roboto, Open Sans, system defaults
+- Overused fonts when the project has no type system: Inter, Roboto, Open Sans, system defaults.
 - Pure black (`#000`) or white (`#fff`): ALWAYS tint neutrals
 - Gray text on colored backgrounds: use a background shade instead
 - Bounce/elastic easing: dated, tacky; use exponential easing (`ease-out-quart`/`expo`)

package/docs/dev/README.md

@@ -4,6 +4,18 @@ Maintainer docs for the omp-llm-role plugin. `README.md` is for people *using*
 the plugin; everything here is for people *changing* it. A fact has exactly one
 home — if it is here, it is not in the README.
 
+## Development setup
+
+Clone, then install the dev dependency and wire the commit gate:
+
+```sh
+npm install
+git config core.hooksPath .githooks
+```
+
+`.githooks/pre-commit` refuses staged `cache/` paths (daily UTC caches,
+regenerated on every run) and runs the test suite (`node --test tests/`).
+
 ## Where to start
 
 | If you are changing… | Read |
@@ -14,9 +26,10 @@ home — if it is here, it is not in the README.
 | a config write, the state/history/lock files, or the write gate | [writes-and-state.md](writes-and-state.md) |
 | the explorer surface (server, explain layer, SPA) | [explorer.md](explorer.md) |
 | the dated numbers (matched/priced/eligible counts, per-role leaders) | [current-state.md](current-state.md) |
-| a release (version bump, npm/git/marketplace channels) | [releasing.md](releasing.md) |
+| a release (version bump, SemVer, CHANGELOG rules, npm/git/marketplace channels) | [releasing.md](releasing.md) |
+| the CI workflow, the release script, or the tag→publish contract | [ci.md](ci.md) |
 | the agent `.md` contract (frontmatter, routing, read-only rules) | [agent-authoring.md](agent-authoring.md) |
-| a normative decision (what the plugin MUST do) | [spec.md](spec.md) |
+| the test suite or a verification scenario | [testing.md](testing.md) |
 | a debugging-only oddity (a quirk, not a contract) | [quirks.md](quirks.md) |
 
 ## The docs
@@ -41,14 +54,38 @@ home — if it is here, it is not in the README.
 - **[current-state.md](current-state.md)** — the dated snapshot:
   matched/priced/eligible counts, per-role leaders, and the open defects.
   Refresh it with each run.
-- **[releasing.md](releasing.md)** — the release switch (`package.json`
-  `version`), the npm/git/marketplace channels, the tarball `files` whitelist,
-  and the install-route verification.
+- **[releasing.md](releasing.md)** — when and how to bump the version (the
+  `package.json` release switch, the SemVer surface), how to cut a release,
+  the CHANGELOG entry rules, the npm/git/marketplace channels, the tarball
+  `files` whitelist, and the install-route verification.
+- **[ci.md](ci.md)** — the GitHub Actions pipeline: the `test`/`release` jobs
+  and their triggers, the tag→publish contract, the one-time trusted-publisher
+  registration, the `scripts/release.ts` subcommands and refusals, and how to
+  verify the pipeline.
 - **[agent-authoring.md](agent-authoring.md)** — the agent `.md` contract:
   frontmatter (`model: "@<role>, @default"`, `tools:`), the routing
   description, read-only classification, and where agents are discovered.
-- **[spec.md](spec.md)** — the normative spec: the confirmed decisions, the
-  verified ground truth, and the contracts the implementation MUST satisfy.
+- **[testing.md](testing.md)** — the test-suite seam map (which test file covers
+  which scenario) and the live checks that need a real omp session.
 - **[quirks.md](quirks.md)** — debugging-only oddities and gotchas that are not
   contracts (e.g. Node type-stripping not typechecking, stale in-process plugin
   code).
+
+## Research notes
+
+External material that informs (but does not bind) the design. Not contracts.
+
+- **[../research/agentic-engineering-benchmarks.md](../research/agentic-engineering-benchmarks.md)**
+  — IndyDevDan's "top 5 agentic-engineering benchmarks" video, mapped onto the
+  project's coverage/collinearity rules; records the two axes the project lacks
+  (guardrails, hallucination), the missing agentic categories, and the
+  per-task-vs-$/M cost gap. Source transcript alongside it
+  (`agentic-engineering-benchmarks.transcript.txt`).
+- **[../research/openrouter-endpoint-routing.md](../research/openrouter-endpoint-routing.md)**
+  — Kai's "OpenRouter is quietly giving nerfed AI models" video, mapped onto the
+  project's OpenRouter data model; confirms the `1/price²` blend, argues
+  quantization labels are not a quality signal, and records the per-endpoint
+  capability ceilings (context, max output, tool support) the project now uses as
+  role filters (issue #18), the opt-in cache-read pricing (issue #30) and
+  provider pinning, and the remaining declared-rate-vs-measured-hit gap. Source
+  transcript alongside it (`openrouter-endpoint-routing.transcript.txt`).

package/docs/dev/agent-authoring.md

@@ -128,10 +128,68 @@ effect on the next session.
   `src/benchmark-discovery.ts`) and folds them in. The resolved benchmark
   labels are given to the architect (and, on the template path, listed in the
   body's `<criteria>`), so the agent's rubric names the benchmark its model was
-  chosen on.
+  chosen on. Discovery is **quality-gated**: the pre-fetch catalog gate is
+  count-only, and the handler then probe-fetches each selected candidate's source
+  and assesses the joined pool on nine axes (`assessFocusMetric`: coverage,
+  dispersion, composition, freshness, trust, modality, maintenance, provenance,
+  cross-source — see scoring.md). A
+  **discovered** candidate below-bar on any gating axis is dropped non-fatally
+  with a reason naming the axis; a **user-named** metric is never dropped — it is
+  annotated and warned. The
+  focus set is capped at `FOCUS_METRIC_CAP` (3) so one benchmark keeps a decisive
+  share. The report prints the nine signals and warns per below-bar axis;
+  `--dry-run` and `--json` carry the same signal. The agent file is written **before** the role,
+  so a partial failure leaves a harmless agent (its `@<name>, @default` chain
+  falls back to `@default`) rather than a dangling role; a failed role write
+  rolls the agent file back — restoring the prior file on a `--force` re-create,
+  else removing the new one — so a retry needs no `--force` and the user's prior
+  agent is never destroyed. A malformed architect response is retried once (a
+  parse failure only — a `run()` failure propagates immediately, since a second
+  session would fail the same way), and the final error carries the raw architect
+  output so the failure surfaces what the architect actually said. The step-3
+  benchmark prompt previews the request's
+  resolved weights (`resolveRole`), so the "already in this role's weights"
+  marker appears live.
+- **Capability flags on `/create-agent`.** `--feature <id,...>` (comma-separated)
+  sets the new role's `features.<id>` so it starts from the plugin's recommended
+  settings for that capability; `--list-features` prints each capability id, the
+  settings it applies and what it buys, without creating anything. An unknown id
+  fails with a non-zero exit and no write. The archetype table
+  (`src/role-archetypes.ts`) carries an optional `features` list the architect
+  may *propose*, but **no archetype auto-applies a flag** — a role gets a flag
+  only when the user asks for it. `create-role.ts` exposes the same
+  `--feature`/`--list-features` surfaces, and `/project-roles` takes `--feature`
+  (its help points at `/create-agent --list-features`).
+- **`/project-roles`** (in-session) discovers the project's usecase from its own
+  artifacts through the profile architect, then authors an agent per new role
+  **into the project scope** (`<cwd>/.omp/agents/`) and writes the project's
+  `modelRoles` to `<cwd>/.omp/config.yml`. The agents are ordinary `.md` files
+  under the project dir, discovered by omp's nearest-project lookup (project >
+  user > plugin) and by `discoverAgentPins`.
 - **The shipped skill** — the hand-driven workflow, for bodies that need real
   authoring rather than the archetype scaffold.
 
+### The vendored architect prompt
+
+`src/prompts/agent-creation-architect.md` is copied verbatim from omp 18.4.8's
+`/agents` hub prompt (the SDK subpath it lives under does not resolve from the
+extension loader, so the plugin ships its own copy). Its first line carries the
+source version, and `ARCHITECT_PROMPT_VERSION` (`src/architect-provenance.ts`,
+re-exported by `src/agent-architect.ts`) holds the same value. `tests/architect-provenance.test.ts`
+asserts the two agree and that this document names the same version, so an omp
+upgrade that changes the prompt surfaces as a test failure rather than silent
+drift.
+
+**Re-sync procedure** (after an omp upgrade):
+
+1. Read the installed omp's agent-creation architect prompt (the `/agents` hub's
+   system prompt) and diff it against `src/prompts/agent-creation-architect.md`.
+2. If it changed, replace the body of the asset, keeping the header comment's
+   version current.
+3. Bump `ARCHITECT_PROMPT_VERSION` to the new omp version.
+4. Update the version named in this section.
+5. Run `node --test tests/architect-provenance.test.ts`.
+
 ## Removal
 
 The `/remove-agent` command deletes an agent **and** its role definition: