ytdb-slate 0.6.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # ytdb-slate
 
-[![CI status](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml/badge.svg?branch=main)](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml)
+[![CI status](https://github.com/JetBrains/ytdb-slate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/JetBrains/ytdb-slate/actions/workflows/ci.yml)
 
 Slate is a thread-weaving orchestration extension for the [pi coding agent](https://pi.dev).
 
@@ -57,6 +57,14 @@ Slate can ride through model API outages. The opt-in `modelFailover` map in `.pi
 
 Slate can pick the model and the effort level per dispatched action rather than running every action on whatever model the orchestrator happens to be on. `router.models` in `.pi/slate.json` (trusted projects only) is a closed list of `provider/id` specs. Each action uses its `model` and `effort` arguments when present. Otherwise, it uses the thread's base model and a level DERIVED for the model it routes to. That level is the lowest one with a capability measurement, never a fixed default. The list is empty by default. An empty list disables candidate-list enforcement, base seeding, effort derivation, and the router's window, billing, and substitution paths. Per-action `model` and `effort` arguments stay active on both router states. Slate always checks an explicit effort against pi's vocabulary, and against the ladder of the model it routes to whenever it has that model's profile data. An action that omits `model` plans for the thread's pre-router pin, and a thread with no pin gives it no plan target. An action that omits `effort` resolves no level. In both cases the worker session returns to what it opened on. [`docs/model-routing.md`](docs/model-routing.md) holds the full contract, including the known cases where the model or level that runs differs. Only models Slate ships a benchmark profile for can be routed to; entries pi cannot serve, or has no profile for, are dropped with a warning naming them.
 
+Router startup warnings have two classes. One class is a configuration fault. It reports project configuration that Slate ignored or dropped. A configuration fault also covers problems the user can stop by adding a model, credential, or failover entry.
+
+The addition must go into their project configuration or pi credentials. Removing the model named by a warning does not meet this second test. Slate always shows configuration faults.
+
+The other class is a model data note. It reports shipped research data that project configuration cannot correct. Slate hides those notes by default.
+
+With this repository's six-model list and pi's stock registry, Slate hides eleven notes. Slate shows one discoverability line instead. A local registry override can change that count. The line names the hidden warning count and the `router.showWarnings` setting. A hidden note can still affect which model runs an action.
+
 What the code enforces is deliberately narrower than what the routing data advises. The dispatch guards refuse an unlisted model, a level off the target model's ladder and a level the provider rejects outright; they warn about — and mark — an unmeasured level, refusing it only when `router.allowUnmeasuredEffort` is `false`; and the context-window guard substitutes a wider listed model instead of ever blocking an action. The obligations that come from the profile data itself — keeping review and gate actions on measured levels, and honoring a REFUSE such as `anthropic/claude-fable-5`'s for zero-data-retention work — are stated in the doctrine for the orchestrator to honor; they are **not** code-enforced guards. Full semantics: the `router.*` rows in [Configuration](#configuration) and the shipped [`docs/model-routing.md`](docs/model-routing.md) — if they disagree, that document wins.
 
 ## Optional writing guidance
@@ -69,6 +77,8 @@ The option has prompt cost. Each orchestrator system prompt contains the doctrin
 
 The shipped CLI checks plain files, JSONL records, and unified diffs. See [`docs/writing-guidance.md`](docs/writing-guidance.md) for its rules, limits, output, and command examples.
 
+Set `writing.remind` to `true` to add context-paced reminders after eligible tool results. Context-paced means Slate waits for configured context growth between reminders. The reminders are hidden from the normal TUI. They repeat five writing requirements and the scope exclusion before the next assistant response. This option remains off unless `writing.check` is also `true`.
+
 ## Install
 
 Install into a project (pinned, project-scoped — recorded in `.pi/settings.json`):
@@ -95,12 +105,15 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `workerPromptDocs` | string[] | `[]` | Project markdown files whose **contents** are appended to every worker-thread system prompt. |
 | `workflow.draftPRs` | boolean | `false` | Enable umbrella draft-PR publishing for tracks. |
 | `writing.check` | boolean | `false` | Add the writing doctrine rule, per-turn status, and worker guidance. An absent option is silently off. A malformed `writing` value, or a non-boolean `check` value, warns and defaults to off. Unknown `writing` keys warn and are ignored. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
+| `writing.remind` | boolean | `false` | Send a hidden reminder after an eligible tool result. All gates must pass: orchestrator mode, project trust, `writing.check`, this option, no pause, cadence or handoff force, and one-per-round control. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
+| `writing.remindPercent` | number | `10` | Set cadence as a percentage of Slate's current effective context budget. The value must be finite and in `(0, 100]`. The interval has an 8,192-token floor and no cap. A handoff force bypasses this threshold. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
 | `doctrineExtraPath` | string | — | Project markdown whose **content** is appended to the orchestrator doctrine (project-specific workflow additions). |
 | `reviewPerspectivesPath` | string | — | Project review charters, each declaring its own finding-ID prefix. The doctrine references this **path**; the orchestrator reads the file alongside the shipped review rules. |
 | `modelFailover` | object (string → string) | — (empty, failover off) | Map of `provider/id` → equal-quality alternative model; on a model API failure the affected site retries once on the mapped model (worker/orchestrator sites only after pi's own retries are exhausted; episode compression has no pi retry loop). Read once at session start — see [`docs/model-failover.md`](docs/model-failover.md). |
 | `preserveGlobalModelDefault` | boolean | `true` | Put pi's global model defaults (`defaultProvider`, `defaultModel`, `defaultThinkingLevel`) back after a Slate-initiated model switch — orchestrator failover and handoff adoption — so the switch stays session-scoped. `false` turns that restore off at both sites (the switches themselves are unaffected), leaving each one persisted in pi's global settings. Best-effort: Slate reverts only a value its own switch produced, and can stand down or give up — limits in [`docs/model-failover.md`](docs/model-failover.md). |
 | `router.models` | string[] | `[]` (empty — routing off) | Closed list of models (`provider/id`) an action may use. Empty or absent means the router is OFF. Slate enforces no candidate list, seeds no thread base, derives no effort level, and runs no router-only window, billing, or substitution path. Per-action `model` and `effort` arguments stay active on both router states. Slate still checks explicit effort against pi's vocabulary and the routed model's ladder when it has that model's profile data. An action that omits `model` plans for the thread's pre-router pin, and a thread with no pin gives it no plan target. An action that omits `effort` resolves no level. In both cases the worker session returns to what it opened on. The known cases where the model or level that runs differs are listed in [`docs/model-routing.md`](docs/model-routing.md). A listed model becomes routable only if Slate has its benchmark profile, pi registers it, and credentials are configured. Slate drops other entries with a warning. If all entries drop, routing turns off with one summary warning. Slate reads and resolves the list once per session. See [`docs/model-routing.md`](docs/model-routing.md). |
 | `router.allowUnmeasuredEffort` | boolean | `true` | What happens when an explicitly requested effort level is on the target model's ladder but has no capability measurement in Slate's profiles: `true` dispatches it with a ⚠ notice and marks the episode `(unmeasured level)`; `false` refuses the dispatch. Either way a level that is off the model's ladder, or one the provider rejects outright, is refused, and a level Slate DERIVES for an action is always a measured one. |
+| `router.showWarnings` | boolean | `false` | Reveal model data notes about Slate's shipped routing research. Configuration faults are never hidden. See [`docs/model-routing.md`](docs/model-routing.md). |
 
 Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point them at markdown files that actually exist in **your** project):
 
@@ -112,7 +125,11 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
   "orchestratorPromptDocs": ["docs/agents/orchestrator-guidelines.md"],
   "workerPromptDocs": ["docs/agents/thread-guidelines.md"],
   "workflow": { "draftPRs": true },
-  "writing": { "check": true },
+  "writing": {
+    "check": true,
+    "remind": false,
+    "remindPercent": 10
+  },
   "doctrineExtraPath": "docs/agents/workflow-additions.md",
   "reviewPerspectivesPath": "docs/agents/review-perspectives.md",
   "modelFailover": { "anthropic/claude-sonnet-5": "openai/gpt-5.2" },
@@ -120,6 +137,8 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
 }
 ```
 
+Older Slate releases warn about these reminder keys and ignore them. Use a Slate release whose documentation includes these keys.
+
 > **Silent skip:** the project-file keys fail silently — no error is shown. For the content-injected keys (`orchestratorPromptDocs`, `workerPromptDocs`, `doctrineExtraPath`) a missing, unreadable, or empty file is skipped and nothing is injected. For `reviewPerspectivesPath` the pointer is omitted only when the file is missing — the file is not read at injection time, so an unreadable or empty file is still cited. Verify your paths after copying the example.
 
 **Worker extensions (`workerExtensions`).** By default worker threads load no extensions. This key is a list of regex patterns that select extensions the **host session has already loaded** and load them into every worker too. Each pattern is matched **unanchored** (unlike `contextBudget.overrides`, which is anchored) against a load unit's recorded source spec (e.g. `npm:pi-web-search@1.3.1`), its load-unit path, or the entry path of any tool that unit contributes, so a bare package name matches:
@@ -158,7 +177,7 @@ In orchestrator mode, Slate appends a short **doctrine** (a block of numbered ru
 - `docs/model-failover.md` — the opt-in `modelFailover` map (**reference documentation** — unlike the entries above it is not workflow doctrine and is not cited by the doctrine)
 - `docs/context-budget.md` — the orchestrator `contextBudget`: defaults, per-model overrides, the window clamp, and the pricing rationale (also **reference documentation**, not cited by the doctrine)
 - `docs/writing-guidance.md` — the optional writing convention, `writing.check` behavior, status line, and checker CLI
-- `docs/model-routing.md` — action-level model routing: the two `router` keys, how a model becomes routable, how an omitted effort level resolves, the dispatch guards, and the warnings a first routed session emits. Unlike the two entries above it **is** cited by the doctrine, by absolute path, but only while the routing rule renders — it is the extra embedded path that appears with the rule, the fourth normally and the fifth when `workflow.draftPRs` is also on, which the size arithmetic in `docs/context-budget.md` accounts for. The routable model list itself is never read from this file: the rule renders it live from the session's own resolution, because that set depends on your registry and credentials.
+- `docs/model-routing.md` — the action-level model routing reference. It covers the three `router` keys, model eligibility, omitted effort, and dispatch guards. It also covers first-session warnings. The doctrine cites this absolute path only while the routing rule renders. This path is fourth normally and fifth when `workflow.draftPRs` is on. The rule renders the live list because it depends on the session registry and credentials.
 
 Project-specific additions layer on top — they extend, not replace, the shipped doctrine — via two distinct mechanisms:
 

package/docs/context-budget.md

@@ -108,6 +108,32 @@ Rationale: the clamp guarantees the pause fires before pi's
 auto-compaction and leaves room to write the handoff brief; the
 half-window floor keeps small-window models usable.
 
+## Writing-reminder cadence
+
+The effective budget also sets the optional hidden writing-reminder cadence.
+When `writing.check` and `writing.remind` are both true, Slate computes:
+
+```
+interval = max(8192, floor(effectiveBudget × remindPercent / 100))
+```
+
+`remindPercent` defaults to 10 and accepts a finite value in `(0, 100]`. The
+context-window clamp therefore shortens the cadence on a model whose configured
+budget does not fit. Slate checks the cadence after tool results. One reminder
+slot can fire after each assistant response.
+
+A successful handoff adoption sets `forceNext`. The next eligible tool result
+then bypasses token cadence and missing usage. It does not bypass trust,
+orchestrator mode, `writing.check`, `writing.remind`, or pause gates. Slate
+commits the cadence mark only when pi starts delivery of the custom message.
+
+The current hidden message is 320 ASCII characters, including its `[slate]`
+header, five reminder requirements, blank separator, and scope exclusion. That
+is about 80 tokens at four characters per token. This count is for the exact
+rendered production string, without JSONL framing or provider-role overhead. The
+message enters conversation context only when a reminder fires. Later requests
+resend it with the rest of the conversation.
+
 ## Compaction policy
 
 In orchestrator mode, for budget-driven configs only: a
@@ -150,34 +176,36 @@ construction and makes the arithmetic one multiplication:
 `doctrine-budget` in `verification/resolver-checks.mjs` is the
 definition of record for this convention and its enforced bounds.
 This table is a measured snapshot, not a second authority. It uses
-the same real shipped-profile fixture as that check; the six-model
-rows use the six configured models in this repository's documented
-example. Every row states its full basis, because router state,
-model count, `draftPRs`, and `writing.check` each move the number:
+the same shipped-profile fixture as that check. The six-model rows
+use the six models in this repository's `.pi/slate.json`. Every row
+states its full basis, because router state, model count, `draftPRs`,
+and `writing.check` each move the number. Rows with the same fixture
+and basis must agree with `verification/README.md`. A different basis
+must be named instead of presented as the same measurement:
 
 | router | models | `draftPRs` | `writing.check` | paths | portable | lines |
 | --- | --- | --- | --- | --- | --- | --- |
 | off | — | off | off | 3 | 1,929 | 38 |
-| off | — | off | on | 4 | 2,683 | 53 |
+| off | — | off | on | 4 | 2,999 | 60 |
 | off | — | on | off | 4 | 1,948 | 38 |
-| off | — | on | on | 5 | 2,702 | 53 |
-| on | 6 configured | off | off | 4 | 3,879 | 58 |
-| on | 6 configured | off | on | 5 | 4,633 | 73 |
-| on | 6 configured | on | off | 5 | 3,898 | 58 |
-| on | 6 configured | on | on | 6 | 4,652 | 73 |
+| off | — | on | on | 5 | 3,018 | 60 |
+| on | `.pi/slate.json` six | off | off | 4 | 3,879 | 58 |
+| on | `.pi/slate.json` six | off | on | 5 | 4,949 | 80 |
+| on | `.pi/slate.json` six | on | off | 5 | 3,898 | 58 |
+| on | `.pi/slate.json` six | on | on | 6 | 4,968 | 80 |
 | on | all 9 shipped | off | off | 4 | 4,434 | 61 |
-| on | all 9 shipped | off | on | 5 | 5,188 | 76 |
+| on | all 9 shipped | off | on | 5 | 5,504 | 83 |
 | on | all 9 shipped | on | off | 5 | 4,453 | 61 |
-| on | all 9 shipped | on | on | 6 | 5,207 | 76 |
+| on | all 9 shipped | on | on | 6 | 5,523 | 83 |
 
 An untrusted project reads the first row whatever its `slate.json`
 says: no project config is loaded, so no optional rule renders. Line
 counts do not vary with the install path. Enabling `draftPRs` costs
 19 portable characters plus one embedded path. Enabling
-`writing.check` costs 754 portable characters, adds 15 lines to the
-whole doctrine, and adds one embedded path; considered alone, the
-writing rule is 754 portable characters / 16 lines because its
-leading newline becomes the separator when appended.
+`writing.check` costs 1,070 portable characters, adds 22 lines to the
+whole doctrine, and adds one embedded path. Considered alone, the
+writing rule is 1,070 portable characters / 23 lines. Its leading
+newline becomes the separator when appended.
 
 Two parts of the block grow with configuration rather than with the
 path:
@@ -191,20 +219,56 @@ path:
   legend adds a one-off clause per marker it has to explain, so
   growth is not only the sum of new rows.
 - The worker-extension rule grows per whitelisted extension and per
-  tool that extension contributes, so it has no fixed size; one
+  tool that extension contributes, so it has no fixed size. One
   extension contributing two tools measured 373 portable characters
   / 7 lines.
 
-Against a 256,000-token budget none of this is material. At four
-characters per token as a rough estimate (no tokenizer was run, and
-the routing table is denser than prose), the portable block ranges
-from about 482 tokens at the baseline to about 1,302 with all nine
-models, `draftPRs`, and writing enabled. That is close to half a
-percent of the default budget at the largest measured configuration,
-though it is re-sent on every request rather than paid once. It is
-listed here because it is context Slate itself puts in front of the
-model on every turn, and because it is the number to check before
-assuming the budget's headroom is all conversation.
+The table above isolates the shipped rules. Two representative bases include
+worker extensions and support verification decisions:
+
+| basis | models | worker extensions | paths | portable | lines | rough tokens |
+| --- | ---: | --- | ---: | ---: | ---: | ---: |
+| current `.pi/slate.json` dogfood config | 6 | real 2 units / 4 tools | 6 | 5,884 | 90 | ≈1,471 |
+| stable maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 6 | 6,870 | 93 | ≈1,718 |
+
+The dogfood row uses `workflow.draftPRs: true`, `writing.check: true`, and the
+six models in `.pi/slate.json`. Its extension basis is
+`pi-smart-fetch@0.3.12` plus `pi-web-search@1.3.1`. Those packages resolve to two
+units and four tools. Their worker-extension rule is 916 portable characters /
+11 lines. Raw size remains symbolic: `portable + 6 × length(installed docs
+directory)`. No maintainer checkout path belongs in this shipped document.
+
+The stable maximal row uses all nine shipped profiles, draft PRs, and writing.
+Its direct post-resolution worker fixture has two units and four tools. Unit
+labels are 128 characters. Tool names are 64 characters. Descriptions are 140
+characters.
+
+Those are the renderer caps. The fixture uses safe ASCII letters. It is
+independent of installed extension labels, descriptions, versions and other
+prose. The worker rule measures 1,347 characters against its 1,600-character
+verification budget.
+
+`doctrine-budget` caps that representative maximal doctrine at 7,200 portable
+characters. The measured 6,870 leaves 330 characters, or 4.6 percent of the
+7,200-character bound. A positive control adds one capped tool
+and three copies of the largest measured model row. It measures 7,634 portable
+characters and exceeds the bound by 434. These figures are verification budgets,
+never runtime limits. Arbitrary user extension rosters can exceed them.
+
+The exact values are maintenance tripwires. A deliberate doctrine wording,
+requirement roster, renderer cap, or fixture change requires a fresh render
+through `doctrine-budget`. Update its exact expectations and every published
+figure in the same commit. Keep the positive control steps unchanged unless the
+fixture design itself changes.
+
+Against a 256,000-token context budget, these blocks remain small. At four
+characters per token as a rough estimate, the shipped-rule table ranges from
+about 482 tokens to about 1,381 tokens. The current dogfood basis is about 1,471
+tokens. The representative maximum is about 1,718 tokens, or 0.67 percent of the
+default budget.
+
+No tokenizer was run, and tables are denser than prose. The block is re-sent on every request rather than paid once. These figures show how
+much headroom Slate consumes before conversation content.
 
 ### Worker writing preamble
 
@@ -317,9 +381,8 @@ number.
   compaction can land in the same cycle and the handoff brief is
   written from compacted context — episodes and thread state survive
   on disk, so handoff still functions.
-- The doctrine sizes above cover the shipped rules only. A project
-  that also injects `doctrineExtraPath` or `orchestratorPromptDocs`,
-  or whitelists worker extensions, pays for those on top in the same
-  always-loaded position, and Slate measures none of it against the
-  budget separately — it simply arrives as context the budget then
-  has less room for.
+- The doctrine sizes above cover the stated fixtures only. A project that
+  injects `doctrineExtraPath` or `orchestratorPromptDocs` pays for those on top.
+  A larger worker-extension roster also adds context beyond the representative
+  fixtures. Slate imposes no runtime doctrine-size limit. This content simply
+  leaves less room under the context budget.

package/docs/model-routing.md

@@ -199,7 +199,7 @@ opened on. M7 and E6 are known cases in which it does not.
 
 `router` lives in `.pi/slate.json` and, like the rest of that file,
 is honored **only in trusted projects** — an untrusted project loads
-no project config, so the router stays off. There are exactly two
+no project config, so the router stays off. There are exactly three
 keys:
 
 ```json
@@ -213,7 +213,8 @@ keys:
       "anthropic/claude-opus-5",
       "anthropic/claude-fable-5"
     ],
-    "allowUnmeasuredEffort": true
+    "allowUnmeasuredEffort": true,
+    "showWarnings": false
   }
 }
 ```
@@ -222,6 +223,7 @@ keys:
 | --- | --- | --- | --- |
 | `models` | array of `"provider/id"` strings | `[]` | the closed candidate list; empty or absent = router OFF |
 | `allowUnmeasuredEffort` | boolean | `true` | `false` turns an evidence gap from a warning into a refusal |
+| `showWarnings` | boolean | `false` | `true` shows model data notes in addition to the always-visible configuration faults |
 
 Validation, all of it at session start so a broken list surfaces
 before a dispatch is refused by it:
@@ -237,6 +239,9 @@ before a dispatch is refused by it:
   entries in the same list still apply.
 - A non-boolean `allowUnmeasuredEffort` is warned about and treated
   as `true`.
+- A non-boolean `showWarnings` is warned about as a configuration
+  fault and treated as `false`. The fault remains visible despite
+  that fallback.
 
 The config is read once, at session start. Editing `slate.json`
 mid-session takes effect only in a new pi session.
@@ -249,24 +254,54 @@ the credentials pi actually has configured. Resolution happens once
 per session, lazily at the first consultation, and the answer is
 then frozen for that session.
 
-| what happens | outcome | warning |
-| --- | --- | --- |
-| entry is not a canonical `provider/id` | dropped | names the entry and the defect |
-| no profile in Slate's model profiles | dropped | "has no benchmark data … excluding it from routing" |
-| two entries resolve to the same profile (an alias or a case variant) | first kept, second dropped | names both spellings and the profile |
-| the same spec listed twice | first kept | none (silent) |
-| pi's model registry does not know it | dropped | "routing there could only produce billed failures" |
-| pi has no usable credentials configured for it | dropped | same wording, credentials variant |
-| every entry dropped | router turns OFF | one summary line naming the count |
-| no usable input price for today's date | kept, ordered last | "its cost cannot be compared" |
-| no usable effort ladder in the profile | kept | "every explicit effort level for it will read as off-ladder" |
-| profile's context window differs from the registry's | kept (registry value used) | see [Expected first-session warnings](#expected-first-session-warnings) |
-| profile names unknown routing-critical fields | kept | "routing decisions for it are provisional", naming the fields |
-| no `modelFailover` entry for a candidate | kept | one aggregate line naming every uncovered candidate |
-
-Every warning is emitted at most once per session and reaches the
-same channel as the other config warnings: a UI notification when a
-UI is attached, the console otherwise.
+The class test has two independent conditions. A warning is a
+**configuration fault** when EITHER condition holds:
+
+1. Slate ignored or dropped part of the user's configuration.
+2. The user can stop the warning by ADDING something to their own
+   project config or pi credentials, such as a model, credential or
+   failover entry. This differs from only removing the model named
+   by the warning.
+
+Every other warning is a **model data note**. The single-part test
+that asks only whether a user can stop a warning does not partition
+the classes: removing a dropped `router.models` entry can silence its
+warning, but removal is not the ADD remedy in condition 2. Condition
+1 catches every silently ignored or dropped config value first.
+
+| what happens | outcome | warning fragment | class |
+| --- | --- | --- | --- |
+| entry is not a canonical `provider/id` | dropped | "It is not a canonical \"provider/id\" model spec. Reason:" | configuration fault |
+| no profile in Slate's model profile table | dropped | "has no entry in slate's model profile table" | configuration fault |
+| two entries resolve to the same profile (an alias or a case variant) | first kept, second dropped | "name the same profiled model" | configuration fault |
+| the same spec is listed twice | first kept | none (silent) | — |
+| pi's model registry does not know it | dropped | "is not in pi's model registry. Slate drops it from routing." | configuration fault |
+| pi has no usable credentials configured for it | dropped | "has no usable credentials configured in pi. Slate drops it from routing." | configuration fault |
+| every entry is dropped | router turns OFF | "survived validation. The warnings above name each dropped entry" | configuration fault |
+| no usable input price exists for today's date | kept, ordered last | "Slate cannot compare its cost with the other models." | model data note |
+| no usable effort ladder exists in the profile | kept | "Such a level passes through to pi, which clamps it" | model data note |
+| profile context window differs from the registry window | kept, registry value used | "differs between two sources" | model data note |
+| the first profile names unknown routing-critical fields | kept | "picks models from a research table shipped inside slate" | model data note |
+| a profile names unknown routing-critical fields | kept | "model fact that slate could not trace to a source" or "model facts that slate could not trace to a source" | model data note |
+| a reportable profile/registry context-window divergence exists, the registry figure is not the profile's recorded known-divergence figure, and the registry figure equals the model's own long-context billing threshold | kept | "context window equal to the model's own long-context billing threshold" | model data note |
+| no `modelFailover` entry exists for a candidate | kept | "routable models have no modelFailover entry" | configuration fault |
+| every configured candidate is marked non-preferred | cheapest candidate becomes the base | "profiles mark every configured model as one it must never pick by itself" | configuration fault |
+| resolution throws | router turns OFF | "routing is disabled. The router could not resolve its model list" | configuration fault |
+
+Every warning is emitted at most once per session. The complete
+resolution retains every warning regardless of display filtering.
+With `router.showWarnings: true`, every warning reaches the same
+channel as the other config warnings: a UI notification when a UI is
+attached, the console otherwise. With the default `false`, every
+configuration fault still reaches that channel and model data notes
+do not.
+
+When at least one note is hidden, Slate emits one discoverability
+line after resolution. It gives the hidden warning count, names
+`router.showWarnings`, and says that a hidden warning can affect
+which model runs an action. The count is warnings, not physical
+display lines: one warning can wrap across several lines. No
+discoverability line appears when nothing was hidden.
 
 Half a list is still a routing policy, so partial drops leave the
 router ON. Nothing surviving is not a policy: the router turns OFF
@@ -463,60 +498,78 @@ model's ladder is unreadable.
 
 ## Expected first-session warnings
 
-**A batch of warnings on the first routed session is expected UX,
-not a bug.** With a six-model list on a stock pi install, resolution
-emits eleven lines, broken down below. They are not repeated: every
-warning fires at most once per session, and the resolution is frozen
-after the first consultation.
-
-In orchestrator mode that first consultation is the DOCTRINE BUILD,
+The stock count below is a render over this repository's
+`.pi/slate.json`, the shipped profile table, and the provider data
+inside the pinned pi 0.83.0 package. It does not read the live model
+registry. The packaged OpenAI data at
+`@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai/dist/providers/data/openai.json`
+reports a **272,000-token** context window for
+`openai/gpt-5.6-luna`, `openai/gpt-5.6-terra` and
+`openai/gpt-5.6-sol`. The packaged Anthropic data reports 1,000,000
+for each configured Anthropic model. The render treated all six as
+authenticated, matching this repository's configured-auth state.
+
+The shipped profiles record 1,050,000 tokens for those three OpenAI
+models. Each stock registry value therefore produces a context-window
+divergence note. The same 272,000-token value equals each model's
+long-context billing threshold, so one aggregate billing-pattern note
+also fires.
+
+Resolution emits **11 warnings: 0 configuration faults and 11 model
+data notes**. The default `router.showWarnings: false` therefore
+shows **0 of those warnings** and one discoverability line. That line
+begins `slate: there are 11 hidden warnings in the model router.`
+Enabling the option shows all 11 warnings and no discoverability
+line. Each warning fires at most once per session, and the resolution
+is frozen after the first consultation.
+
+| warnings | class | condition keys | why | shown by default |
+| --- | --- | --- | --- | --- |
+| 1 | model data note | `w3-explainer` | explains the shipped research table before the first unknown-data warning | 0 |
+| 6 | model data note | one `w3:string:<JSON spec>` for each configured model | each profile names model facts with no traced source, or conflicting figures with no adjudication | 0 |
+| 3 | model data note | one `w1:string:<JSON spec>` for each configured OpenAI model | each stock registry window differs from its profile window | 0 |
+| 1 | model data note | `w1-billing-pattern` | aggregates the three registry windows that equal their models' billing thresholds | 0 |
+| **11** | **all model data notes** | — | stock measured total | **0 warnings; 1 discoverability line** |
+
+The stock emission order is:
+
+1. `w1:string:"openai/gpt-5.6-luna"`
+2. `w3-explainer`
+3. `w3:string:"openai/gpt-5.6-luna"`
+4. `w1:string:"openai/gpt-5.6-terra"`
+5. `w3:string:"openai/gpt-5.6-terra"`
+6. `w1:string:"openai/gpt-5.6-sol"`
+7. `w3:string:"openai/gpt-5.6-sol"`
+8. `w3:string:"anthropic/claude-sonnet-5"`
+9. `w3:string:"anthropic/claude-opus-5"`
+10. `w3:string:"anthropic/claude-fable-5"`
+11. `w1-billing-pattern`
+
+This count depends on pi's registry data and any local registry
+override. This machine's `~/.pi/agent/models.json` overrides the
+three OpenAI windows to 1,050,000 tokens. A live render here therefore
+suppresses the three divergence notes and the billing-pattern note,
+leaving **7 model data notes**. That seven-note result describes this
+machine, not a stock install.
+
+The configured failover map covers all six candidates, so the
+failover-coverage condition does not fire in either render. Preferred
+candidates remain in the list, so the non-preferred-base condition
+does not fire either.
+
+In orchestrator mode the first consultation is the DOCTRINE BUILD,
 not a dispatch: the orchestrator's system prompt carries the
-routable model table, and it is assembled when your first message
-starts a turn. So the whole batch can arrive in a session where you
-typed nothing but "hi" and dispatched nothing at all — that is the
-router reading its inputs for the session, not a dispatch
-misfiring. (Outside orchestrator mode no doctrine is built, so the
-first dispatch triggers it instead. The config-shape warnings above
-land earlier still, at session start.)
-
-The breakdown:
-
-| lines | class | why |
-| --- | --- | --- |
-| 6 | unknown routing data | each of the six profiles names routing-critical fields with no traced value, or with two published values and no adjudication, so routing decisions for them are provisional |
-| 3 | context-window divergence | the three `openai/gpt-5.6-*` models — see below |
-| 1 | billing-pattern note | one aggregate line naming those three models |
-| 1 | failover coverage | one aggregate line, when `modelFailover` covers none of them |
-
-The window divergence is real, and both sides are stated without
-adjudication. On a stock install pi's registry reports **272,000**
-tokens for `openai/gpt-5.6-luna`, `-terra` and `-sol`, while their
-profiles record **1,050,000** (with the profile's asOf date in the
-same line). Routing uses the REGISTRY figure — that is a fact about
-this code, and it is stated as such — but which figure is factually
-correct is not established by the router: it sees two numbers and no
-provenance for either.
-
-The registry's 272,000 is also exactly those models' long-context
-BILLING threshold, so one further line says so once, naming all
-three: a window equal to its own threshold would leave the
-long-context price tier unreachable, which is the
-billing-row-restated-as-a-capacity pattern. That is suggestive, not
-proof, which is why it is a pointer and not a verdict.
-
-**Why Slate does not "fix" this by changing its own number.** The
-research pass that produced this table explicitly withdrew 272,000
-as a capacity figure: in the source it appears only inside a pricing
-row, as a boundary on input tokens. Restating it as a window is the
-fabrication that pass caught and corrected. Editing the profile to
-match the registry would silence the warning by asserting something
-the evidence does not support, and would suppress a divergence that
-is currently true. The honest options are the two you already have:
-leave it (routing uses the registry number, which is the
-conservative one) or raise the registry window deliberately in pi's
-custom-models file, after which the warning stops on its own —
-`context-budget.md` documents that opt-in and the billing
-consequences of running above the threshold.
+routable model table, and it is assembled when the first message
+starts a turn. Outside orchestrator mode the first dispatch triggers
+resolution instead. Config-shape warnings land earlier, at session
+start.
+
+A hidden warning can still alter which model runs an action. Context-
+window divergence is the concrete case, and the stock registry emits
+three such hidden notes for this list. Routing uses the registry
+window, and that value drives the context-window substitution guard.
+`router.showWarnings` changes display only; it does not change the
+resolution or the guard input.
 
 ## What the router does NOT enforce