fix: the lint cluster, the cut's captures and the API adapter

.abcd/config/reading-presets.json

@@ -60,10 +60,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1090000,
-        "measured_tokens_est": 1074501,
-        "measured_bytes": 4136830,
-        "measured_at": "50152d62171899ff645bc614ad38ee55facc7c1d"
+        "tokens_est": 1130000,
+        "measured_tokens_est": 1115292,
+        "measured_bytes": 4293878,
+        "measured_at": "8fd646fa043cd76a9d839b69ac797e1b3de3d5af"
       }
     },
     "entailment": {
@@ -132,10 +132,10 @@
         "intent-projection"
       ],
       "window": {
-        "tokens_est": 360000,
-        "measured_tokens_est": 353700,
-        "measured_bytes": 1361748,
-        "measured_at": "50152d62171899ff645bc614ad38ee55facc7c1d"
+        "tokens_est": 370000,
+        "measured_tokens_est": 357546,
+        "measured_bytes": 1376554,
+        "measured_at": "8fd646fa043cd76a9d839b69ac797e1b3de3d5af"
       }
     },
     "comparative": {
@@ -216,10 +216,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1100000,
-        "measured_tokens_est": 1083537,
-        "measured_bytes": 4171618,
-        "measured_at": "50152d62171899ff645bc614ad38ee55facc7c1d"
+        "tokens_est": 1140000,
+        "measured_tokens_est": 1124328,
+        "measured_bytes": 4328666,
+        "measured_at": "8fd646fa043cd76a9d839b69ac797e1b3de3d5af"
       }
     }
   }

.abcd/development/brief/04-surfaces/01-ahoy.md

@@ -25,15 +25,16 @@ repo whose stamp says it is current.
 
 | Verb | Bucket | Status |
 |---|---|---|
+| `connect` | — | shipped |
 | `doctor` | — | shipped |
 | `install` | — | shipped |
 | `remote apply` | gate | shipped |
 | `uninstall` | — | shipped |
 
 
-Bare `/abcd:ahoy` shows read-only status and mutates nothing. Three read-only
-modes of the same act — the dry run, the identity check and the remote report —
-are flags on the bare verb rather than sub-verbs, one at a time, and the
+Bare `/abcd:ahoy` shows read-only status and mutates nothing. Four read-only
+modes of the same act — the dry run, the identity check, the remote report and
+the provider board — are flags on the bare verb rather than sub-verbs, one at a time, and the
 appendix lists them. A sub-verb is a distinct action, a flag a mode of the same
 one (itd-2609212130136102). For one release each
 mode's retired sub-verb spelling answers with its flag and exits non-zero, and
@@ -76,6 +77,17 @@ the table above is the sub-verb set, and the modes are the bare verb's flags.
   machine.** See below.
 - **The identity check** exits non-zero when the git commit identity does not
   match the repo's identity pin. Read-only, CLI-only, for an operator or CI.
+- **The provider board** explains the optional OpenAI-compatible
+  provider adapter (itd-2609081951381895): what an aggregator is, that abcd
+  would use one for decision models and cheap judgements pointed at it by name,
+  and that everything works without one, because with no provider configured
+  every delegated step runs on the host. It lists the providers configured on
+  this machine, whether each one's key resolves (never the key), the vendor
+  denylist in force, the roles and judgement types pointed at a provider, and
+  where a key can live, the keychain recommended in the prose and never as a
+  marked option. The bare board carries the same explanation as an optional,
+  advisory gap while no provider is configured.
+- **The provider setup** sets one provider up, and writes. See below.
 
 **Not built yet:** `destroy`, a nuclear uninstall that would remove the `.abcd/`
 namespace too (itd-10), as distinct from the uninstall's reversible behaviour.
@@ -104,6 +116,35 @@ the API host explicitly, so an ambient host variable cannot send the write to an
 endpoint the origin never named, and the call goes through the caller's own
 authenticated identity: abcd never holds a token.
 
+### The provider setup
+
+The setup takes the provider's name, its base URL, its first allowlist (every
+model it may serve) and where its key lives. It verifies the provider with one
+call to the first model listed and, only when that call succeeds, writes the key
+and then the provider block, both under `~/.abcd/`: the key into the owner-only
+`credentials.json`, the block (base URL, the key's name, the models) into
+`config.json`. A failed verification writes nothing. Nothing reaches the
+repository or the harness's settings. Every fault the configuration read would
+refuse (a denylisted or malformed model, a base URL that is plain HTTP to
+another machine, a provider already configured, a key name already holding a
+different value) is refused before the call, so a setup that cannot finish is
+never billed.
+
+The key arrives on stdin and nowhere else. A flag would leave it in the process
+listing and the shell history, the install prompter echoes every answer into its
+transcript, a host's question tool would put it in an agent's context, and a
+terminal would echo it as it is typed, so stdin from a terminal is refused. For
+the same reason the walkthrough is this sub-verb, which the person runs with the
+key piped in, rather than a question the install pass asks: declining is not
+running it, and changes nothing.
+
+Of the three homes a key may live in, the setup builds the abcd-only one. The
+environment-variable-or-external-tool home and the platform keychain arrive with
+the credential store (itd-2609221017023290); asked for either, the setup refuses
+naming it. A fourth answer, no key, sets up a local server that takes none.
+No delegating verb sends a step to a configured provider until provider dispatch
+lands (spc-2609251028149555), and both the board and the setup say so.
+
 ## What abcd manages — repos and `~/.abcd/`
 
 abcd manages exactly one kind of folder, a **repository**, and keeps one
@@ -129,7 +170,11 @@ user-scope directory for machine-local state.
   inbox/                         reports managed repositories filed back to abcd,
                                  <received-stamp>-<sender-key>.md; promoted/ keeps
                                  the ones filed as captures (itd-2609221656361680)
-  config.json                    machine config defaults (a later phase)
+  config.json                    the machine layer of the layered configuration,
+                                 read-only except for the provider blocks
+                                 (oracle.api.<provider>) the provider setup writes,
+                                 and the only file a provider block may sit in;
+                                 that write holds .config.json.lock beside it
   memory/                        user-scope memory (personal, cross-project — a later
                                  phase; the shipped store is repo-scope .abcd/memory/)
   sources/                       the local sources corpus /abcd:ingest and /abcd:consult
@@ -139,9 +184,12 @@ user-scope directory for machine-local state.
                                  extreme-load), read-only; abcd never creates it
                                  (itd-2609231434459890)
   credentials.json               external credentials by name (a hosting token for
-                                 setting up a site), mode 0600, read-only; abcd never
-                                 creates it. The interim source the credential store
-                                 replaces (itd-2609221017023290)
+                                 setting up a site, a provider's key), mode 0600;
+                                 only the provider setup writes it, one new name at
+                                 a time, never replacing a stored value, holding
+                                 .credentials.json.lock beside it across the read
+                                 and the write. The interim source the credential
+                                 store replaces (itd-2609221017023290)
   rules.json                     the machine's rule conventions, the user layer
                                  between the bundled domains and each repo's
                                  .abcd/rules.json, read-only; abcd never creates it
@@ -536,14 +584,26 @@ _Generated from the command tree; a drift test fails `go test` when this appendi
 
 ### `abcd ahoy`
 
-Sub-verbs: `abcd ahoy doctor`, `abcd ahoy install`, `abcd ahoy remote`, `abcd ahoy uninstall`.
+Sub-verbs: `abcd ahoy connect`, `abcd ahoy doctor`, `abcd ahoy install`, `abcd ahoy remote`, `abcd ahoy uninstall`.
 
 | Flag | Type |
 |---|---|
 | `--dry-run` | bool |
 | `--identity` | bool |
+| `--providers` | bool |
 | `--remote` | bool |
 
+### `abcd ahoy connect`
+
+Sub-verbs: none.
+
+| Flag | Type |
+|---|---|
+| `--base-url` | string |
+| `--home` | string |
+| `--key` | string |
+| `--model` | stringArray |
+
 ### `abcd ahoy doctor`
 
 Sub-verbs: none.

.abcd/development/brief/04-surfaces/04-launch.md

@@ -75,9 +75,10 @@ checked-out tree, into an existing directory. Bound to the tag being released,
 it refuses (exit 1) unless the committed catalog pins exactly that archive's
 address and digest, and unless that address lies under the releasing
 repository's own release downloads for the tag — removing the archive on either
-refusal, so nothing unpinned can be published. `auto-release.yml` runs it on the
-pushed commit before the tag is made, and the release workflow runs it again on
-the tagged commit, each run bound to the repository the workflow runs in. Bound
+refusal, so nothing unpinned can be published. The release workflow runs it in
+its `verify` job, which the tag job needs, so on the `auto-release` path a
+refusal leaves no tag; its release job runs it again on the tagged commit before
+it publishes, each run bound to the repository the workflow runs in. Bound
 to the pin, the render leaves the dirty-tree gate to it — a payload file that
 differs from the commit changes the digest and refuses; unbound, it runs the
 gate, and an uncommitted change refuses the render.

.abcd/development/brief/04-surfaces/05-intent.md

@@ -440,11 +440,12 @@ Both the press-release intent and the frozen PRD are immutable input artefacts p
 
 ## 6. Acceptance gates and bidirectional link verification
 
-`internal/core/lint` (cross-cutting; its shipped wiring is the docs currency lint and the `cmd/record-lint` gate) is the record-lint over the committed intent tree — it does not run inside planning; the acceptance-criteria refusal at plan time is the intent package's own `hasAcceptanceCriteria` check (`internal/core/intent`). The armed record-lint rules that bear on the intent tree are `intent_lifecycle` (the directory/kind/`spec_id` invariants and the `status:`-key ban below), `intent_impact_valid` (the `impact:` field's legal value set), `persona_registry` (press-release quote attributions resolve to the persona roster), `record_schema` (the `itd` store's filename↔id agreement, and `superseded_by` handle validity with two-way agreement across stores), `record_provenance` (the `origin`/`production_mode` disclosure pair and the `related_issues` back-edge), `spec_lifecycle` and `spec_id_unique` (the itd↔spc bidirectional agreement below), and `delivery_state` (no CHANGELOG delivery entry, under `Added` or `Changed`, cites an intent still sitting in `drafts/`). The `IL0xx` codes per [`05-internals/06-lint.md`](../05-internals/06-lint.md) are plan-time design, a later phase.
+`internal/core/lint` (cross-cutting; its shipped wiring is the docs currency lint and the `cmd/record-lint` gate) is the record-lint over the committed intent tree — it does not run inside planning; the acceptance-criteria refusal at plan time is the intent package's own `hasAcceptanceCriteria` check (`internal/core/intent`). The armed record-lint rules that bear on the intent tree are `intent_lifecycle` (the directory/kind/`spec_id` invariants and the `status:`-key ban below), `intent_impact_valid` (the `impact:` field's legal value set), `intent_sota` (a `planned/` intent carries a non-empty `## SOTA` declaration, armed at warn), `persona_registry` (press-release quote attributions resolve to the persona roster), `record_schema` (the `itd` store's filename↔id agreement, and `superseded_by` handle validity with two-way agreement across stores), `record_provenance` (the `origin`/`production_mode` disclosure pair and the `related_issues` back-edge), `spec_lifecycle` and `spec_id_unique` (the itd↔spc bidirectional agreement below, and the buckets' agreement: a planned intent has an open spec, and a shipped intent has none left open), and `delivery_state` (no CHANGELOG delivery entry, under `Added` or `Changed`, cites an intent still sitting in `drafts/`). The `IL0xx` codes per [`05-internals/06-lint.md`](../05-internals/06-lint.md) are plan-time design, a later phase.
 
 The invariants below are the contract the tree is held to, and each names what holds it. A bullet marked **(convention)** is practice the corpus follows by hand, with no shipped check behind it:
 
 - **Acceptance criteria present and well-formed** (per the itd-1 discipline): an intent cannot be planned without a `## Acceptance Criteria` section carrying at least one Given-When-Then bullet. The block is at plan time, not in the record-lint: the refusal is the intent package's own `hasAcceptanceCriteria` check on a draft, plus the `acceptance_criteria` row of the readiness gate. Everything in `planned/` and `shipped/` has therefore passed it. The two buckets the plan step never crosses are held by hand and are **(convention)**: a draft still on the bench may carry none, and so may a discipline, whose route into `disciplines/` does not run through planning at all. Both are true of this corpus today — four bench drafts and seven of the fourteen disciplines carry no section. No record-lint rule reads it, so a committed intent that lost one still passes the gate.
+- **A planned intent declares the state of the art** (per [sota-per-intent](../../principles/sota-per-intent.md)): a `## SOTA` section naming the existing alternatives, each one's rough maturity, and the path taken. `intent_sota` flags a `planned/` intent with no such section, or with a heading and nothing under it, at warn severity — the warn-first rung of a ratchet whose next rung is blocker once the planned bucket is back-filled. It judges presence, not the path's spelling, and reads neither `drafts/` (not yet shaped) nor `shipped/` (history, most of it older than the principle).
 - **`kind` is set on intents in `planned/`, `shipped/`, `disciplines/`, and `superseded/`.** Intents in `drafts/` may have `kind: null`. The shipped plan step neither infers a kind nor asks for one: it writes `standalone` wherever the draft left the field null, so `standalone` is what an unstated kind becomes. **A later phase** replaces that default with the proposal the user confirms or overrides (§ 1, "Later phase — plan grows a PRD-freeze front end and multi-kind dispatch"). What the record lint holds meanwhile is the value set per bucket: a draft's kind must be null, `standalone` or `bundle-member`, and a planned or shipped record's must be one of the latter two, non-null (`intent_lifecycle`).
 - **`kind: bundle-member` requires a `bundle:` field** pointing to a bundle ID; *all* members of a bundle reference the same bundle ID, and bundles are bidirectional in their members' frontmatter. **(convention)** No shipped lint reads `bundle`: `intent_lifecycle` knows `bundle-member` only as a legal `kind` value. **Exception for superseded bundle-members:** intents in `superseded/` with `kind_at_supersession: bundle-member` carry `bundle: null` AND `bundle_at_supersession: <bundle-id>` (preserves the bundle the intent was part of when retired, while signalling the bundle is no longer active). **(convention)** `bundle_at_supersession` appears in no shipped code either.
 - **Bundle invariant: all members belong to the same phase.** Planning several intents at once (multi-arg, kind=bundle-member) hard-blocks promotion when the proposed members are scoped to different phases. Lint code `IL011`. Resolution: re-scope into one phase or downgrade one member to `kind: standalone`. See § 1 "Bundle invariant" for the canonical statement and the worked example (`intent-capture-discipline` retirement on 2026-05-07).
@@ -618,9 +619,12 @@ agent and refuses the override. A step no configured provider can serve at its
 tier goes to the harness with the tier named in its request, and one stderr line
 says so. The receipt is a `route` member in the JSON and a `route:` line in the
 text, carrying `tier_asked`, `connection_tried`, `connection_used`,
-`fallback_reason`, `override`, `settings_sent` and `model_reported`, the last
-read from the payload's own `model` field (a reading's `instrument.model`) and
-empty when the payload names none. A routing table that cannot be read, an
+`fallback_reason`, `override`, `settings_sent`, `model_reported` and
+`provider_call`. `model_reported` is read from the payload's own `model` field (a
+reading's `instrument.model`) and empty when the payload names none;
+`provider_call` names the provider, the model asked for and the model it
+reported when a provider adapter answered the step, and is null on the harness
+leg. A routing table that cannot be read, an
 override naming an agent this invocation does not dispatch, a tier outside
 `local`, `economy`, `frontier` and `host-decides`, or a connection this machine
 has not configured exits 2 before anything is written. With no table accepted

.abcd/development/brief/04-surfaces/08-abcd.md

@@ -117,7 +117,8 @@ when reports from managed repositories wait in the user account's inbox, the tex
 render carries an `inbox:` line — `3 report(s) from 2 managed repositories` — and
 the JSON an `inbox` object with `reports` and `senders`. It is the same count the
 session-start greeting says ([`29-report.md`](29-report.md)); it names no sender,
-and it is absent when nothing waits.
+and it is absent when nothing waits. An inbox that cannot be counted has no row:
+one line on stderr names the refusal instead.
 
 **The oracle lines** (itd-2609170822093401, spc-2609180535002478) show the
 model-tier routing once a table is accepted, at the repository