polydeukes 0.4.0 → 0.6.0

package/dist/docs/reference/covenant.md

@@ -13,6 +13,11 @@
 
 The judge. Everything that turns a declared promise into a verdict lives here.
 
+**This is the install unit for judgment.** An embedder that wants verdicts without the
+umbrella's surfaces installs this package and provides `@polydeukes/core` alongside it — core
+is a `peerDependency` here, so the vocabulary is shared rather than duplicated. The umbrella
+is what satisfies that peer for an ordinary consumer.
+
 | Unit | What it does |
 |---|---|
 | `runCovenant` wrapper | Runs a judge body, translates its non-blocking `1` into the blocking `2`, and logs every call. No covenant runs unmeasured |
@@ -24,20 +29,20 @@ The judge. Everything that turns a declared promise into a verdict lives here.
 
 ## Discipline families and meta-covenants
 
-**A `disciplines:` entry belongs to exactly one family**, decided by which predicate key it
-carries. The family determines what evidence the judgment needs — which is also what
-determines whether it can be judged on a given surface.
+**A `disciplines:` entry is one declaration** — `judge = relate ∘ extract` over the
+observation as a world. What the declaration's sources bind decides what evidence the
+judgment needs, which is also what decides whether it can be judged on a given surface.
 
-| Family | Key | Judges | Evidence needed |
-|---|---|---|---|
-| delta | `forbid` | Added-direction content of a file change. Existing debt is forgiven; only new occurrences break | File change |
-| path | `immutable` | Any change to a file that already exists — modification or deletion alike. Creation passes | File change |
-| command | `forbidCommand` | The command line itself | None |
-| context | `requirePrecedent` | Session history — was a qualifying call actually executed *before* this one | A transcript |
+| Sources | Judges | Evidence needed |
+|---|---|---|
+| the fixed names `target.path` · `pre` · `post` · `state` · `changes` | The change itself | A file change |
+| the fixed name `command` | The shell call's command line | A shell call — an Edit carries none |
+| `{ transcript: true }` | Session history — was a qualifying call actually executed *before* this one | A session |
+| `{ file: … }` · `{ sidecar: true }` | Another file, or the spawn-record channel | The surface's reader for it |
 
-`when` is a trigger, not a family: it narrows a `requirePrecedent` entry and combines with
-nothing else. The writing guide for these entries — the four predicate forms, the two
-pitfalls — is [the configuration reference's `disciplines` section](./configuration.md#disciplines).
+The writing guide for these entries is [the configuration reference's `disciplines`
+section](./configuration.md#disciplines); the declaration grammar is the core's
+`algebra-declaration.schema.json`.
 
 **Three meta-covenants** protect the judging chain. They are covenants like any other; the
 vocabulary below applies to them unchanged.
@@ -58,7 +63,7 @@ the same word for the same event. How to read a row is in
 | `passed` | The call was judged and upheld the covenant |
 | `blocked` | The call was judged and broke it |
 | `witnessed` | A **blocked** verdict a human opened in person. Never silent, never a clean call |
-| `advised` | The commit surface at `enforce: advise` recorded a break without stopping it |
+| `advised` | A break recorded without stopping the call — the default for every discipline entry on both surfaces, and the commit surface's outcome under `adapters.git.enforce: advise` |
 | `skipped` | The call reached a registration that could not judge it. **Not a pass** — the recorded absence of a judgment |
 | `unattributed` | A protected entry's on-disk state moved and no judgment row explains it. **Not a verdict** — no call is blocked or passed by it; the session surface writes it after comparing state against a stored baseline |
 
@@ -86,18 +91,21 @@ No import. The umbrella assembles this package for both surfaces.
   not "nothing gets through" — it is that **no call passes unrecorded**. A new spelling
   landing in `skipped` is the declared limit showing itself. A pass with no row at all, or
   one recorded `passed` without a judgment, is the defect class.
-- **The context family cannot be judged without a session.** On the commit surface there is
-  none, so a matching `requirePrecedent` entry always records `skipped`. That is a permanent
+- **A declaration that reads the session cannot be judged without one.** On the commit
+  surface there is none, so a matching `precedent` (or any other transcript-reading)
+  declaration records `skipped` with the reason `supply-pass`. That is a permanent
   condition of that surface.
-- **The command family is absent from the commit surface, and absent without a row.**
-  `forbidCommand` entries are filtered out before compilation there, since a staged diff
-  carries no command line to judge. Unlike the context family this leaves nothing in
-  `.polydeukes/roi.log`, so the log cannot separate a command discipline that never
-  triggered from one that was never registered on that surface.
-- **An unjudgeable entry compiles to a skip registration** — routing intact, no body. A
-  pattern that does not compile skips the same way. Assembly therefore never throws: one
-  unresolvable entry cannot take down its siblings, the meta-covenants, and the valve,
-  which would leave no way to fix the config that caused it.
+- **A declaration scoped on `command` is absent from the commit surface, and absent without
+  a row.** A staged diff carries no command line, so no world such a declaration observes is
+  admitted there. This leaves nothing in `.polydeukes/roi.log`, so the log cannot separate a
+  command discipline that never triggered from one whose surface never observed a command.
+- **A declaration the compiler cannot resolve compiles to a skip registration** — routing
+  intact, no body: a step outside the registry, an argument outside a step's keys, a pattern
+  that does not compile, a mechanism whose shape the syntax does not fit. Assembly therefore
+  never throws: one unresolvable entry cannot take down its siblings, the meta-covenants, and
+  the valve, which would leave no way to fix the config that caused it. A source the world
+  lacks at judgment time is a different case — the declaration's own `supply` policy
+  disposes of it, and with no policy the body answers unjudgeable (exit 2), never upheld.
 - **Complete containment is a non-goal.** There are no blocklists here — enumerating bypass
   spellings is always one step behind, so the logic is inverted: a mention of a protected
   path blocks unless proven safe. Residual vectors such as indirect path computation are

package/dist/docs/reference/polydeukes.md

@@ -12,6 +12,11 @@ every other dependency in this repository runs one way, through the core alone.
 this page the consumer-facing surface: the four scoped packages are transitive dependencies
 you do not install and do not import.
 
+The judge and the two adapters take the core as a `peerDependency` rather than a dependency
+of their own, so they share one copy of the vocabulary instead of each carrying its own. The
+umbrella's ordinary dependency on the core is what satisfies that peer, which is why
+installing this one package is still all a consumer does.
+
 | Package | Reference | Owns |
 |---|---|---|
 | `@polydeukes/core` | [core](./core.md) | The protocol, the config schema, telemetry |
@@ -21,34 +26,51 @@ you do not install and do not import.
 
 ## Subcommands
 
-The bin is `pdks`, with `polydeukes` as an alias. There are no flags and no options
-anywhere: two subcommands take an exact two-word form, and `docs` takes an optional topic.
+The bin is `pdks`, with `polydeukes` as an alias. Every argument form is matched against a
+finite table: `covenant check` takes an optional domain flag, `init claude-code` and
+`init grok` are exact, `explain` takes one word, and `docs` takes an optional topic.
 
 ### `pdks covenant check`
 
-The commit-surface judgment runner, invoked from a pre-commit hook. It discovers the config
-at the working directory, collects the staging area through the git adapter, translates it
-into the covenant input IR, and dispatches it through the same judge bodies the session hook
-spawns.
+`pdks covenant check [--worktree | --range <base>..<head>]` — the commit-surface judgment
+runner. It discovers the config at the working directory,
+collects one observation of the repository through the git adapter, translates it into the
+covenant input IR, and dispatches it through the same in-process judges the session hook calls.
+Which observation is the domain flag's choice — the same violation receives the same verdict
+in all three:
+
+| Form | Domain | `pre` → `post` |
+|---|---|---|
+| `pdks covenant check` | The staging area — what a pre-commit hook judges | HEAD blob → staged blob |
+| `pdks covenant check --worktree` | The working tree, untracked (non-ignored) files included | HEAD blob → bytes on disk |
+| `pdks covenant check --range <base>..<head>` | Two refs; `<base>...<head>` reads from their merge-base, the PR reading | base blob → head blob |
+
+`--worktree` and `--range` are diagnostic calls — run them after a task, before a PR, or in
+CI. Only the staged form is a gate, so only it can prompt for the witness token; the other
+two report exit `2` without a prompt, since there is no commit for a human to open.
 
 | Situation | Result |
 |---|---|
-| Staged changes break nothing | exit `0` |
+| The domain's changes break nothing | exit `0` |
 | A staged change breaks a covenant, `enforce: block`, config has a `witness` block | Prompts once on `/dev/tty` for the witness token; an unanswered or wrong answer exits `2` |
 | The same, with no `witness` block in the config | exit `2` with no prompt — the valve is built from that block, so without it nothing can open a block |
-| A staged change breaks a covenant, `enforce: advise` | One advisory line on stderr, exit `0`, recorded `advised` |
-| Empty staging area | exit `0` — an explicit pass, not a skipped run |
+| A worktree or range change breaks a covenant, `enforce: block` | exit `2`, never a prompt |
+| A change breaks a covenant, `enforce: advise` | One advisory line on stderr, exit `0`, recorded `advised` |
+| Empty domain (nothing staged, a clean tree, identical refs) | exit `0` — an explicit pass, not a skipped run |
+| A range naming a ref git cannot resolve, or two refs with no merge-base | exit `2`, one `blocked` row |
+| `--range` without an argument, an argument without `..`, both flags at once, or an unknown flag | The usage line on stderr, exit `2` |
 | No config, more than one config, or an invalid one | exit `2` |
 | A judge body that cannot be loaded | exit `2` |
 
-Context-family disciplines (`requirePrecedent`) assemble here like any other entry, but this
-surface has no session to read: a match records `skipped` and the commit proceeds. That is a
-permanent condition of the commit surface, not a fault.
+Declarations that read the session (`precedent` and the other history mechanisms) assemble
+here like any other entry, but this surface has no session to read: a match records
+`skipped` and the commit proceeds. That is a permanent condition of the commit surface, not a
+fault.
 
 ### `pdks init claude-code`
 
 The session-surface installer. It proves that `polydeukes` resolves from the directory it
-was invoked in **before writing anything**, then creates five artifacts:
+was invoked in **before writing anything**, then creates six artifacts:
 
 | Artifact | Kind |
 |---|---|
@@ -56,6 +78,7 @@ was invoked in **before writing anything**, then creates five artifacts:
 | `.claude/settings.json` | Merged — the PreToolUse registration is added to whatever the file already carries |
 | `polydeukes.config.yaml` | Created — the starter policy, with a placeholder `languages` block |
 | `.claude/rules/polydeukes.md` | Created — tells the AI partner to ask [`pdks docs`](#pdks-docs-topic) instead of searching the web |
+| `.claude/skills/discipline-draft/SKILL.md` | Created — the classification procedure: a described problem becomes a config entry (judged at advise, or `draft: true`), and advised rows are consulted in the telemetry log |
 | `.gitignore` | Appended — one line for `.polydeukes/` |
 
 Nothing existing is overwritten: an artifact already present is reported as skipped and left
@@ -63,6 +86,22 @@ alone, so a re-run is a no-op. A precondition failure — the package not resolv
 coexisting config spellings, an unparseable settings file — writes zero files and exits `2`,
 never a half-wired tree.
 
+### `pdks init grok`
+
+The Grok session-surface installer. Same preflight and the same shared scaffold (config and
+the `.polydeukes/` ignore line). A Grok-only tree gets four artifacts (hook JSON, the grok
+delegator, config, ignore line) and no `.claude/` directory. The JSON registration carries
+`timeout` 60 (the host default is 5 seconds; a timed-out hook fails open). If
+`.claude/hooks/covenant-pretooluse.mjs` already exists, the JSON command points at that file
+so the host does not spawn two judges. A later run of either installer retargets an
+installer-generated grok-mjs command the same way, and the JSON matcher follows the
+`.claude/settings.json` entry for that command (Grok collapses two registrations only when
+command and matcher both match); a command pointed elsewhere is left alone.
+
+An already-open Grok session keeps the hook snapshot from start; reload from the Hooks tab
+(`r`) or start a new session. The witness valve does not open on Grok: the session log is
+ACP `updates.jsonl`, not Claude's JSONL.
+
 ### `pdks docs [topic]`
 
 The offline documentation reader. The guides and this reference layer ship inside the
@@ -96,29 +135,77 @@ the package.
 `pdks init claude-code` writes a discovery file that points an AI partner at this
 subcommand; see the artifact table above.
 
+### `pdks explain`
+
+The assembly reader. It loads the config at the working directory, assembles both surfaces'
+registration sets through the same functions the two judgment runners use, and prints them
+without judging — no judge thunk is called, no telemetry row is written, no transcript is
+read.
+
+```text
+pdks explain — polydeukes.config.yaml
+
+surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block
+  registrations 43 · declare 21 · skip 19 · meta 3 · draft 1
+  meta     self-mod                      paths 14 (common; includes the config file itself)
+  declare  covenant-vocabulary           added-only · change · empty nothing-added · scope target.path · include 1 · exclude 1 · sources 0 · valve — · why ✓
+  declare  pnpm-only                     forbidden-command · change · empty no-npm-mutation · scope command · include 0 · exclude 0 · sources 0 · valve — · why ✓
+  declare  manifest-needs-evidence       precedent · history · nonEmpty npm-view, context7 · scope target.path · include 1 · exclude 0 · sources 1 (transcript 1) · valve — · why ✓
+  skip     covenant-vocabulary           a shell write in scope whose result this layer cannot compute
+  ...
+surface: commit (git pre-commit) · enforce: advise · disciplines: advise unless enforce: block
+  registrations 24 · declare 22 · skip 1 · meta 1 · draft 1
+  declare  manifest-needs-evidence       precedent · history · nonEmpty npm-view, context7 · scope target.path · include 1 · exclude 0 · sources 1 (transcript 1) · valve — · why ✓
+  declare  sqlite-only-under-knowledge   naming · change · empty placed · scope target.path · include 1 · exclude 0 · sources 0 · valve — · why ✓
+```
+
+One line per registration, in the order the surface dispatches them. The kind column has
+four words: `meta` (the registrations protecting the judging chain — `self-mod`,
+`shell-mod`, and on the session surface `transcript-mod`), `declare` (a declaration entry,
+with its mechanism, axes and relations, its scope source, the sizes of its include and
+exclude lists, its sources, and whether it carries a valve and a `why`), `skip` (a
+registration that records `skipped` instead of judging, with the reason the compiler gave —
+the reason that otherwise reaches stderr only on a config fault), and `draft` (an unpromoted
+`draft: true` entry, shown on both surfaces since it belongs to neither). `registrations`
+counts `meta`, `declare`, and `skip`; `draft` is tallied apart because it never becomes a
+registration.
+The commit surface's header also names its `adapters.git.enforce` level, since an advising
+surface records the same table but blocks nothing.
+
+The session surface is rendered as the hook sees it under a normal payload — with a
+transcript present — so `transcript-mod` and the session-reading declarations appear as they
+do in a session; on the commit surface those declarations record `skipped` when matched,
+which is that surface's permanent condition.
+
+| Call | Result |
+|---|---|
+| `pdks explain` | Both surfaces on stdout, exit `0` |
+| `pdks explain <anything>` | The usage line on stderr, exit `2` |
+| no config, two configs, or an invalid one | `pdks explain: <reason>` on stderr, stdout at zero bytes, exit `2` |
+
 ### Any other argument form
 
-Anything that is not one of these forms writes
-`usage: pdks covenant check | pdks init claude-code | pdks docs [topic]` to stderr and
-exits `2`.
+Anything that is not one of these forms writes the usage line —
+`usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain |
+pdks init claude-code | pdks init grok | pdks docs [topic]` — to stderr and exits `2`.
 
 ## Exit codes
 
 Three codes exist, and they live at two layers. **What a consumer's hook observes is only
-`0` or `2`** — both composition roots return `Promise<{ exitCode: 0 | 2 }>`.
+`0` or `2`** — both composition roots resolve to a named outcome carrying `exitCode: 0 | 2`.
 
 | Code | Constant | Emitted by | Means |
 |---|---|---|---|
-| `0` | `EXIT_UPHOLD` | Judge body, wrapper, bin | The promise was upheld — the call or commit proceeds |
-| `1` | `EXIT_BREAK_NON_BLOCKING` | Judge body only | A break reported as a signal. The wrapper translates it — into `2` under `enforce: block`, into `0` + an `advised` row under `advise`. It never reaches the surface either way |
+| `0` | `EXIT_UPHOLD` | Judge outcome, wrapper, bin | The promise was upheld — the call or commit proceeds |
+| `1` | `EXIT_BREAK_NON_BLOCKING` | Judge outcome only | A break reported as a signal. The wrapper translates it — into `2` under `enforce: block`, into `0` + an `advised` row under `advise`. It never reaches the surface either way |
 | `2` | `EXIT_BREAK_BLOCKING` | Wrapper, bin, fail-closed paths | The call or commit is refused |
 
-The asymmetry is the protocol's responsibility boundary. A covenant body decides *whether* a
-promise was broken and says so with `0` or `1`; deciding what a break *costs* belongs to the
-wrapper, and that is the one place `enforce` is read. A body can therefore be run, tested, and
-reasoned about without knowing whether the surface it runs under blocks or advises. Only the
-verdict relaxes: every unjudgeable outcome — a body exit of `2` or higher, a signal death —
-stays `2` at either level.
+The asymmetry is the protocol's responsibility boundary. A judge decides *whether* a
+promise was broken and answers `0` or `1` in its outcome; deciding what a break *costs* belongs
+to the wrapper, and that is the one place `enforce` is read. A judge can therefore be run,
+tested, and reasoned about without knowing whether the surface it runs under blocks or advises.
+Only the verdict relaxes: every unjudgeable outcome — an outcome of `2` or higher, a throw
+from the judge — stays `2` at either level.
 
 **Everything unjudgeable resolves to `2`.** A missing config, an invalid one, an
 unparseable payload, a judge body that was never built — each fails closed. The one
@@ -135,7 +222,9 @@ This is the whole public API; the scoped packages are not part of it.
 **Type signature:**
 
 ```ts
-function loadConfig(rootDir: string): LoadedConfig;
+function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+
+type LoadConfigSpec = { rootDir: string };
 
 type LoadedConfig = {
   config: ResolvedConfig;  // protectedPaths already includes the config file itself
@@ -153,18 +242,27 @@ a silently unprotected project.
 **Type signature:**
 
 ```ts
-function runCovenantCheck(spec: CovenantCheckSpec): Promise<{ exitCode: 0 | 2 }>;
+function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;
+
+type CovenantCheckOutcome = { exitCode: 0 | 2 };
 
 type CovenantCheckSpec = {
-  repoRoot: string;                                  // config discovery and staged collection anchor here
+  repoRoot: string;                                  // config discovery and collection anchor here
   telemetryPath?: string;                            // overrides the config's log path
   covenantDist?: string;                             // overrides the resolved judge directory
   ttyPrompt?: (prompt: string) => string | null;     // the TTY valve seam
+  domain?: CheckDomain;                              // which observation to judge; absent = staged
 };
+
+type CheckDomain =
+  | { kind: 'staged' }
+  | { kind: 'worktree' }
+  | { kind: 'range'; base: string; head: string; ancestry?: 'merge-base' };
 ```
 
 The commit surface's composition root — what [`pdks covenant
-check`](#pdks-covenant-check) runs.
+check`](#pdks-covenant-check) runs. `ancestry: 'merge-base'` is the `<base>...<head>`
+reading; the adapter resolves the merge-base.
 
 `ttyPrompt` absent means a non-TTY environment, and the valve then has no way to open — an
 agent-spawned commit and a CI run reach the same state. The valve is a human at a terminal
@@ -175,7 +273,9 @@ or nothing.
 **Type signature:**
 
 ```ts
-function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<{ exitCode: 0 | 2 }>;
+function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;
+
+type ClaudeCodeHookOutcome = { exitCode: 0 | 2 };
 
 type ClaudeCodeHookSpec = {
   repoRoot: string;         // config discovery and discipline glob scoping anchor here
@@ -201,8 +301,8 @@ needs no second dependency.
 
 | Specifier | Carries |
 |---|---|
-| `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, `runClaudeCodeHook`, their spec types, `ResolvedConfig` |
-| `polydeukes/claude-code` | `runClaudeCodeHook` and `ClaudeCodeHookSpec` alone |
+| `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, their spec and outcome types, `ResolvedConfig`. The session hook lives on its own subpath below and nowhere else |
+| `polydeukes/claude-code` | `runClaudeCodeHook`, `ClaudeCodeHookSpec`, and `ClaudeCodeHookOutcome` alone |
 | `polydeukes/schema.json` | The config JSON Schema, copied from the core at build time |
 
 The generated hook delegator imports the subpath, not the barrel. ESM imports are eager, so

package/dist/docs/troubleshooting.md

@@ -29,7 +29,10 @@ Discovery looks for exactly these, in this order: `polydeukes.config.yaml`,
 defaults — silent defaults would mean silently unprotected.
 
 **Recovery.** Restore the file from git. On the session path,
-`pnpm exec pdks init claude-code` recreates the missing artifacts; on the commit path the
+`pnpm exec pdks init claude-code` or `pdks init grok` recreates files that
+are absent. An existing grok JSON is not rewritten except when its `command`
+still names the grok delegator and a Claude delegator is on disk — then that
+command is retargeted and the matcher follows the settings entry. On the commit path the
 config is hand-written — the [install guide](./installation.md)'s commit-surface section
 has a starting point.
 
@@ -58,6 +61,30 @@ empty `languages` block, the schema's one required entry.
 **Recovery.** Fix the named key in the named file. The error is specific on purpose — no
 rewrite-and-hope needed.
 
+## A Grok session does not pick up a newly installed hook
+
+**Symptom.** `pdks init grok` reported created files, but this session's tool calls still
+leave no telemetry row.
+
+**Cause.** Grok loads hooks at session start. An already-open session keeps that snapshot.
+
+**Recovery.** Press `r` in the Hooks tab, or start a new session. The witness valve also
+does not open on Grok — a block is recovered from another terminal or the commit-surface TTY.
+
+## One Grok tool call leaves two telemetry rows
+
+**Symptom.** In a tree wired for both Claude Code and Grok, every `write` or
+`run_terminal_command` in a Grok session appends two rows to `.polydeukes/roi.log`,
+milliseconds apart.
+
+**Cause.** Grok reads `.claude/settings.json` as well as `.grok/hooks/*.json` and collapses
+the two registrations only when `command` and `matcher` are both identical. A grok JSON
+whose matcher differs from the settings entry spawns the judge a second time.
+
+**Recovery.** Make the grok JSON's `matcher` the same string as the settings entry that
+registers the same command. Re-running either installer does it: every grok entry that
+names the Claude hook takes the settings entry's matcher.
+
 ## `pdks init claude-code` refuses to run
 
 **Symptom.** The installer prints an install command and exits 2 without creating anything.
@@ -144,16 +171,18 @@ that *cannot judge* (missing or invalid config, an unresolvable judge) still exi
 
 ## `skipped` rows on the commit surface
 
-**Symptom.** A `requirePrecedent` discipline that judges normally in sessions always lands
-as `skipped` on commits.
+**Symptom.** A `precedent` declaration that judges normally in sessions always lands as
+`skipped` on commits.
 
-**Cause.** Context-family disciplines judge *session history* — was the required step
-actually executed before this change. A commit has no session to read, so the entry
-assembles as a skip registration: routing intact, no judge body. When its scope matches a
-staged change it records `skipped` with the entry's id and proceeds.
+**Cause.** A declaration that reads the session judges *session history* — was the required
+step actually executed before this change. A commit has no session to read, so the
+declaration's own `supply: { session: 'pass' }` takes over: when its scope matches a staged
+change it records `skipped` with the reason `supply-pass` and the entry's id, and proceeds.
 
 **Recovery.** None needed — this is a declared condition of the surface, not a defect. The
-row is the point: a gate that did nothing says so in the data. A context-family entry is
+row is the point: a gate that did nothing says so in the data. `pdks explain` shows the
+same fact before any commit: the entry appears under the commit surface with its
+`transcript` source, which that surface never supplies. Such a declaration is
 really a session-surface tool — on a project that wires only the commit surface, such an
 entry only ever buys telemetry, so declare it where an AI partner's session exists to be
 judged. The row appears only when the entry's scope actually matched, so an unrelated

package/dist/docs-query.d.ts

@@ -1,23 +1,23 @@
 /**
- * `queryDocs` — the offline documentation query (DOCS-02 §3-b/§3-c/§3-d).
+ * `queryDocs` — the offline documentation query.
  *
  * The bundled English guides, answered from the installed version. An AI partner that
  * searches the web gets whatever release the internet indexed; this returns the document
  * that shipped with the code doing the judging, with no network at all.
  *
- * The domain is the five topics below and nothing else (§3-c). An unknown topic throws
- * instead of resolving to something near it: an answer to a question we never mapped is
+ * The domain is the five topics below and nothing else. An unknown topic throws instead of
+ * resolving to something near it: an answer to a question we never mapped is
  * indistinguishable from a real one by the time it reaches a reader.
  *
- * Every failure throws (§3-b) so the bin can leave stdout at zero bytes and exit 2. Text
- * written halfway is read as the document and quoted as the document — the same direction
- * the judging surface fails in, for the same reason.
+ * Every failure throws so the bin can leave stdout at zero bytes and exit 2. Text written
+ * halfway is read as the document and quoted as the document — the same direction the
+ * judging surface fails in, for the same reason.
  */
-/** The finite query domain (§3-c) — the topic list `pdks docs` prints with no argument. */
+/** The finite query domain — the topic list `pdks docs` prints with no argument. */
 export declare const TOPICS: readonly ['install', 'config', 'discipline', 'covenant', 'witness'];
 /**
  * The body of one section of `markdown`: from the line equal to `heading` up to just before
- * the next heading of the same or a higher level, returned verbatim (§3-d).
+ * the next heading of the same or a higher level, returned verbatim.
  *
  * `heading` is matched by exact string equality. A document that renames its heading kills
  * the query here rather than letting a normalizing matcher hand back a neighbouring section
@@ -36,10 +36,10 @@ export type QueryDocsSpec = {
     topic?: string;
 };
 /**
- * Answer one documentation query (§3-b).
+ * Answer one documentation query.
  *
  * With no topic the result is the listing — how an AI discovers what it may ask at all.
- * With one, it is the §3-c section body followed by the bundled reference to read next.
+ * With one, it is the mapped section body followed by the bundled reference to read next.
  */
 export declare function queryDocs(spec: QueryDocsSpec): {
     text: string;

package/dist/docs-query.js

@@ -1,23 +1,23 @@
 /**
- * `queryDocs` — the offline documentation query (DOCS-02 §3-b/§3-c/§3-d).
+ * `queryDocs` — the offline documentation query.
  *
  * The bundled English guides, answered from the installed version. An AI partner that
  * searches the web gets whatever release the internet indexed; this returns the document
  * that shipped with the code doing the judging, with no network at all.
  *
- * The domain is the five topics below and nothing else (§3-c). An unknown topic throws
- * instead of resolving to something near it: an answer to a question we never mapped is
+ * The domain is the five topics below and nothing else. An unknown topic throws instead of
+ * resolving to something near it: an answer to a question we never mapped is
  * indistinguishable from a real one by the time it reaches a reader.
  *
- * Every failure throws (§3-b) so the bin can leave stdout at zero bytes and exit 2. Text
- * written halfway is read as the document and quoted as the document — the same direction
- * the judging surface fails in, for the same reason.
+ * Every failure throws so the bin can leave stdout at zero bytes and exit 2. Text written
+ * halfway is read as the document and quoted as the document — the same direction the
+ * judging surface fails in, for the same reason.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-/** The finite query domain (§3-c) — the topic list `pdks docs` prints with no argument. */
+/** The finite query domain — the topic list `pdks docs` prints with no argument. */
 export const TOPICS = ['install', 'config', 'discipline', 'covenant', 'witness'];
-/** The §3-c mapping, as data: which document answers a topic, and what to read next. */
+/** The mapping, as data: which document answers a topic, and what to read next. */
 const TOPIC_MAP = {
     install: {
         sections: [{ file: 'installation.md' }],
@@ -55,7 +55,7 @@ function headingLevel(line) {
 }
 /**
  * The body of one section of `markdown`: from the line equal to `heading` up to just before
- * the next heading of the same or a higher level, returned verbatim (§3-d).
+ * the next heading of the same or a higher level, returned verbatim.
  *
  * `heading` is matched by exact string equality. A document that renames its heading kills
  * the query here rather than letting a normalizing matcher hand back a neighbouring section
@@ -101,7 +101,7 @@ export function extractSection(markdown, heading) {
     if (start === -1) {
         throw new Error(`heading not found: ${heading}`);
     }
-    // A section that closes the document ends at end of file; the §3-c map points at one.
+    // A section that closes the document ends at end of file; the topic map points at one.
     return lines.slice(start).join('\n');
 }
 function readSection(docsRoot, section) {
@@ -115,10 +115,10 @@ function readSection(docsRoot, section) {
     return section.heading === undefined ? markdown : extractSection(markdown, section.heading);
 }
 /**
- * Answer one documentation query (§3-b).
+ * Answer one documentation query.
  *
  * With no topic the result is the listing — how an AI discovers what it may ask at all.
- * With one, it is the §3-c section body followed by the bundled reference to read next.
+ * With one, it is the mapped section body followed by the bundled reference to read next.
  */
 export function queryDocs(spec) {
     if (spec.topic === undefined) {

package/dist/explain.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `pdks explain` — render both surfaces' assembled registration sets without judging.
+ *
+ * This module calls the composition roots' OWN assembly functions and renders what they
+ * return, so it reports the table the judgment uses rather than a second opinion about it.
+ *
+ * It never dispatches, never writes telemetry or a baseline, and never opens a transcript
+ * file — the session assembly receives core's `noopTranscript`, which answers queries with
+ * nothing and reads no disk. Every failure throws: an answer that cannot be given is never
+ * given halfway.
+ */
+/** `explain` input — the repository whose config is read. */
+export type ExplainSpec = {
+    repoRoot: string;
+};
+/**
+ * Read the config at `repoRoot`, assemble both surfaces, and render them.
+ *
+ * The session assembly is given a transcript path, so its `transcript-mod` registration
+ * exists here exactly as it does under a normal hook payload — the path is never read,
+ * because the injected transcript is the no-op one.
+ */
+export declare function explain(spec: ExplainSpec): Promise<{
+    text: string;
+}>;