polydeukes 0.0.1 → 0.4.0

package/dist/docs/reference/polydeukes.md

@@ -0,0 +1,215 @@
+# `polydeukes` — the umbrella
+
+**English** · [한국어](./polydeukes.ko.md)
+
+> Alpha. Everything below is read from the shipped package — the `pdks` bin, the barrel, and
+> the exports map. For the procedures that use these, see [installation](../installation.md)
+> and [troubleshooting](../troubleshooting.md).
+
+The umbrella is the only package you install. It carries the core, the judge, and both
+adapters as its own dependencies, and it is the only package allowed to assemble them —
+every other dependency in this repository runs one way, through the core alone. That makes
+this page the consumer-facing surface: the four scoped packages are transitive dependencies
+you do not install and do not import.
+
+| Package | Reference | Owns |
+|---|---|---|
+| `@polydeukes/core` | [core](./core.md) | The protocol, the config schema, telemetry |
+| `@polydeukes/covenant` | [covenant](./covenant.md) | The judge — dispatcher, disciplines, meta-covenants, the valve |
+| `@polydeukes/adapter-claude-code` | [adapter-claude-code](./adapter-claude-code.md) | Session surface — PreToolUse payloads → input IR |
+| `@polydeukes/adapter-git` | [adapter-git](./adapter-git.md) | Commit surface — staged diffs → input IR |
+
+## 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.
+
+### `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.
+
+| Situation | Result |
+|---|---|
+| Staged 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 |
+| 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.
+
+### `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:
+
+| Artifact | Kind |
+|---|---|
+| `.claude/hooks/covenant-pretooluse.mjs` | Created — a delegator that loads the judge from the installed package |
+| `.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 |
+| `.gitignore` | Appended — one line for `.polydeukes/` |
+
+Nothing existing is overwritten: an artifact already present is reported as skipped and left
+alone, so a re-run is a no-op. A precondition failure — the package not resolving, two
+coexisting config spellings, an unparseable settings file — writes zero files and exits `2`,
+never a half-wired tree.
+
+### `pdks docs [topic]`
+
+The offline documentation reader. The guides and this reference layer ship inside the
+package, so the answer comes from the installed version rather than from the network.
+
+| Call | Result |
+|---|---|
+| `pdks docs` | The topic list on stdout, exit `0` |
+| `pdks docs <topic>` | That topic's section, followed by a `See also:` line, exit `0` |
+| `pdks docs <unknown>` | The known topics named on stderr, exit `2` |
+| `pdks docs a b` | The usage line on stderr, exit `2` |
+
+| Topic | Answers from |
+|---|---|
+| `install` | [installation](../installation.md), in full |
+| `config` | [the configuration reference](./configuration.md), in full |
+| `discipline` | [the configuration reference](./configuration.md) — the `disciplines` section |
+| `covenant` | [configuration](../configuration.md) — What enforcement looks like |
+| `witness` | [the configuration reference](./configuration.md)'s `witness` section, then [troubleshooting](../troubleshooting.md)'s valve section |
+
+**Every failure leaves stdout at zero bytes.** A missing bundled document, a heading the
+document no longer carries, an unknown topic — each names what was missing on stderr and
+exits `2`. A partially written answer is one an agent reads as the document and quotes
+onward, so there is no such state.
+
+The bundle carries the English text only. Answers are returned verbatim, so the
+`[한국어](./X.ko.md)` link at the top of each document points at a mirror that lives in the
+[repository](https://github.com/huskyhoochu/polydeukes/tree/main/docs) rather than inside
+the package.
+
+`pdks init claude-code` writes a discovery file that points an AI partner at this
+subcommand; see the artifact table above.
+
+### 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`.
+
+## 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 }>`.
+
+| 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 |
+| `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.
+
+**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
+direction that stays open is measurement: a telemetry write that fails never changes a
+verdict.
+
+## Programmatic surface
+
+The barrel (`import … from 'polydeukes'`) exports six symbols plus one re-exported type.
+This is the whole public API; the scoped packages are not part of it.
+
+### `loadConfig`
+
+**Type signature:**
+
+```ts
+function loadConfig(rootDir: string): LoadedConfig;
+
+type LoadedConfig = {
+  config: ResolvedConfig;  // protectedPaths already includes the config file itself
+  configPath: string;      // rootDir-relative path of the discovered file
+};
+```
+
+Discovers exactly one `polydeukes.config` file (`.yaml`, `.yml`, or `.json`) directly under
+`rootDir`. **Every failure branch throws** — none found, more than one found, a parse error,
+a schema violation. There are no silent defaults, because a silently defaulted config means
+a silently unprotected project.
+
+### `runCovenantCheck`
+
+**Type signature:**
+
+```ts
+function runCovenantCheck(spec: CovenantCheckSpec): Promise<{ exitCode: 0 | 2 }>;
+
+type CovenantCheckSpec = {
+  repoRoot: string;                                  // config discovery and staged 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
+};
+```
+
+The commit surface's composition root — what [`pdks covenant
+check`](#pdks-covenant-check) runs.
+
+`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
+or nothing.
+
+### `runClaudeCodeHook`
+
+**Type signature:**
+
+```ts
+function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<{ exitCode: 0 | 2 }>;
+
+type ClaudeCodeHookSpec = {
+  repoRoot: string;         // config discovery and discipline glob scoping anchor here
+  rawPayload?: string;      // absent means read fd 0 — the hook's real stdin
+  telemetryPath?: string;
+  covenantDist?: string;
+};
+```
+
+The session surface's composition root — what the generated hook delegator calls. Reach it
+through the [`polydeukes/claude-code`](#subpaths) subpath rather than the barrel.
+
+**Neither composition root throws.** An uncaught rejection would exit the delegator
+non-blocking, which is the cheapest bypass there is, so both resolve their failures into
+`{ exitCode: 2 }` with a telemetry record instead.
+
+### `ResolvedConfig`
+
+Re-exported from [`@polydeukes/core`](./core.md) so a consumer reading `loadConfig`'s result
+needs no second dependency.
+
+## Subpaths
+
+| Specifier | Carries |
+|---|---|
+| `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, `runClaudeCodeHook`, their spec types, `ResolvedConfig` |
+| `polydeukes/claude-code` | `runClaudeCodeHook` and `ClaudeCodeHookSpec` 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
+importing the barrel would load the commit-surface runner — and the git adapter behind it —
+on every session tool call that will never use them. The subpath is the session surface's
+own entry point, and the barrel is for programmatic consumers.
+
+`polydeukes/schema.json` is for code that reads the schema. A `$schema` line names the file
+path instead — an editor reads that string statically, so no module resolver runs on it. Both
+spellings are in [configuration.md's IDE section](../configuration.md#ide-support).

package/dist/docs/troubleshooting.md

@@ -0,0 +1,160 @@
+# Troubleshooting Polydeukes
+
+**English** · [한국어](./troubleshooting.ko.md)
+
+> Alpha. Nine states cover what ships today — five ways a fail-closed system refuses to
+> proceed, and four things worth knowing when a judgment surprises you. Each entry is
+> symptom → cause → recovery.
+
+This is the guide layer for recovery: the fail-closed states, reading verdicts, and the
+witness valve.
+
+The one principle behind half of this page: **a gate that cannot judge blocks rather than
+guesses.** A missing config, an ambiguous config, an invalid config, an installer that
+cannot prove resolution, and a judge that cannot be loaded all fail closed, because a dead
+gate that waves things through is the cheapest bypass of all. The recovery is never to
+disable the gate — it is to give it back what it needs to judge. And run that recovery
+**from your own terminal**: inside a session the repair commands are judged by the very
+gate they repair, and while no config is loaded there is no witness valve to open.
+
+## Every call is blocked and there is no config
+
+**Symptom.** On the session surface, every editing tool call and shell command exits 2;
+on the commit surface, every `pdks covenant check` run does. The error says no Polydeukes
+config was found and names the three candidate filenames.
+
+**Cause.** The surface is wired but config discovery found nothing at the project root.
+Discovery looks for exactly these, in this order: `polydeukes.config.yaml`,
+`polydeukes.config.yml`, `polydeukes.config.json`. A missing config never silently loads
+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
+config is hand-written — the [install guide](./installation.md)'s commit-surface section
+has a starting point.
+
+## More than one config file
+
+**Symptom.** Every call exits 2 with an error naming two (or three) config files at once.
+
+**Cause.** Two spellings coexist — say a `polydeukes.config.yaml` created next to a
+project's existing `.yml`. Ambiguity never picks a winner.
+
+**Recovery.** Keep exactly one file and delete the others. If both have content, merge by
+hand first — the loader will not choose for you.
+
+## The config is invalid
+
+**Symptom.** Every call exits 2 with an error naming the offending file — and, for schema
+violations, the exact key.
+
+**Cause.** One of: a YAML parse error; a custom YAML tag (rejected even though the parser
+cannot execute it — config data stays uncomputable by contract); an unknown key (a typo
+like `protectedPath:` is rejected with the full field path — with one open ground: an
+adapter namespace's *name* is not validated, so `adapters.gti:` for `adapters.git:` loads
+clean and its entries are simply never read; that one spelling you check yourself); or an
+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.
+
+## `pdks init claude-code` refuses to run
+
+**Symptom.** The installer prints an install command and exits 2 without creating anything.
+
+**Cause.** Preflight: before writing any file, the installer proves the `polydeukes`
+package resolves from the target project root. A hook generated without that would block
+every call through its own fail-closed catch — an uneditable tree. The usual trigger is
+running via a one-off `npx` without installing, or running in the wrong directory (it
+installs where it is invoked).
+
+**Recovery.** `pnpm add -D polydeukes` in the project you meant, then re-run from that
+root. Zero files were written, so there is no partial state to clean up.
+
+## The judge cannot be loaded
+
+**Symptom.** Every call exits 2 with `covenant hook failed closed: Cannot find package
+'polydeukes'` — or an error naming a judge-body file that does not exist.
+
+**Cause.** The hook is wired but the package it delegates to is gone or incomplete: the
+dependency was removed, the tree is a fresh clone that was never installed, or (in a
+source clone of this repository) the judge's build output is missing. The installer's
+preflight prevents *wiring* a project into this state, but nothing prevents a wired
+project from entering it later.
+
+**Recovery.** From your own terminal, reinstall the dependency (`pnpm install`, or
+`pnpm add -D polydeukes` if it was removed). In a source clone, run the build. The hook
+file itself needs no repair — it is a delegator, and it recovers the moment the package
+resolves again.
+
+## Reading a verdict
+
+**Symptom.** Something was blocked (or passed) and you want to know what the record says.
+
+**Cause.** Not a failure — this is the measurement working. Every judgment appends exactly
+one record to the telemetry log (`.polydeukes/roi.log` by default, `telemetry.logPath` to
+move it).
+
+**Recovery.** Read the last lines and the six-word vocabulary:
+
+| Word | Means |
+|---|---|
+| `passed` | Judged, upheld the covenant. |
+| `blocked` | Judged, broke it. The call did not run. |
+| `witnessed` | A blocked verdict a human opened in person. Never silent. |
+| `advised` | Commit surface at `advise` level: a break recorded without stopping the commit. |
+| `skipped` | A registration matched but could not judge — **the recorded absence of a judgment, not a pass.** |
+| `unattributed` | A protected entry changed on disk and no judgment explains it — **an observation, not a verdict.** Nothing was blocked; the write already happened. |
+
+An `unattributed` row names the entry, not the file inside it. Rebuilding a protected `dist`
+without a judged call producing one is expected — it says a write reached that entry outside
+the session's view, which is exactly what the row is for.
+
+## Opening a blocked call — the witness
+
+**Symptom.** A call you and your agent agree should proceed was blocked, and you want it
+through without editing the policy.
+
+**Cause.** The valve exists for exactly this, and it sits *after* the verdict — only a
+judgment that actually blocked can be witnessed open.
+
+**Recovery.** Type the token from your config's `witness:` block so it stands **alone on
+the first line** of a conversation message. The window holds for `ttlMinutes`, then
+blocking resumes on its own. Three things that do not work, by design: quoting or
+mentioning the token mid-sentence (invocation is first-line-standalone only); witnessing a
+call that was never blocked (the valve is consulted only after a block); and the agent
+typing the token for itself (only human-authored messages count — the defence is
+provenance, not secrecy). Every allowance lands as one `witnessed` row.
+
+## A blocked commit
+
+**Symptom.** `git commit` stops at a prompt asking a human to witness a staged protected
+change — or, from an agent, the commit simply fails with exit 2.
+
+**Cause.** The commit surface at the default `block` level judges the staged diff, and its
+valve is a TTY prompt. An agent-spawned commit has no TTY, so for it the valve is not even
+assembled — a terminal-holding human is the pass condition, not a workaround.
+
+**Recovery.** Run the commit from your own terminal and answer the prompt with the full
+token — one answer covers that whole commit. If you want the commit surface to measure
+without stopping, set `adapters.git.enforce: advise`: verdicts are then recorded as
+`advised` and the commit proceeds with one advisory line on stderr. At either level a run
+that *cannot judge* (missing or invalid config, an unresolvable judge) still exits 2 —
+`advise` relaxes the verdict, never the gate's integrity.
+
+## `skipped` rows on the commit surface
+
+**Symptom.** A `requirePrecedent` discipline 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.
+
+**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
+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
+commit records nothing.

package/dist/docs-query.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `queryDocs` — the offline documentation query (DOCS-02 §3-b/§3-c/§3-d).
+ *
+ * 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
+ * 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.
+ */
+/** The finite query domain (§3-c) — 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).
+ *
+ * `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
+ * with full confidence.
+ *
+ * Both scans — for the start and for the boundary — run outside code fences. `#` lines
+ * inside a fence are content: the guides really carry them, and a fence-blind scanner cuts
+ * the answer at one of those lines while still looking like a success.
+ */
+export declare function extractSection(markdown: string, heading: string): string;
+/** `queryDocs` input — the bundle to read from, and which topic to answer. */
+export type QueryDocsSpec = {
+    /** Root of the bundled documents (`dist/docs`), the only tree read here. */
+    docsRoot: string;
+    /** ABSENT lists the topics; anything not in {@link TOPICS} throws, empty string included. */
+    topic?: string;
+};
+/**
+ * Answer one documentation query (§3-b).
+ *
+ * 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.
+ */
+export declare function queryDocs(spec: QueryDocsSpec): {
+    text: string;
+};

package/dist/docs-query.js

@@ -0,0 +1,138 @@
+/**
+ * `queryDocs` — the offline documentation query (DOCS-02 §3-b/§3-c/§3-d).
+ *
+ * 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
+ * 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.
+ */
+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. */
+export const TOPICS = ['install', 'config', 'discipline', 'covenant', 'witness'];
+/** The §3-c mapping, as data: which document answers a topic, and what to read next. */
+const TOPIC_MAP = {
+    install: {
+        sections: [{ file: 'installation.md' }],
+        seeAlso: 'reference/polydeukes.md',
+    },
+    config: {
+        sections: [{ file: 'reference/configuration.md' }],
+        seeAlso: 'reference/core.md',
+    },
+    discipline: {
+        sections: [{ file: 'reference/configuration.md', heading: '## `disciplines`' }],
+        seeAlso: 'reference/covenant.md',
+    },
+    covenant: {
+        sections: [{ file: 'configuration.md', heading: '## What enforcement looks like' }],
+        seeAlso: 'reference/polydeukes.md',
+    },
+    witness: {
+        sections: [
+            { file: 'reference/configuration.md', heading: '## `witness`' },
+            { file: 'troubleshooting.md', heading: '## Opening a blocked call — the witness' },
+        ],
+        seeAlso: 'reference/covenant.md',
+    },
+};
+/** A fenced block opens and closes on a line whose trimmed form starts with the marker. */
+const FENCE = /^(?:`{3,}|~{3,})/;
+/** An ATX heading, and its level in the capture. */
+const HEADING = /^(#{1,6}) /;
+function isTopic(value) {
+    return TOPICS.includes(value);
+}
+function headingLevel(line) {
+    return HEADING.exec(line)?.[1].length ?? 0;
+}
+/**
+ * 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).
+ *
+ * `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
+ * with full confidence.
+ *
+ * Both scans — for the start and for the boundary — run outside code fences. `#` lines
+ * inside a fence are content: the guides really carry them, and a fence-blind scanner cuts
+ * the answer at one of those lines while still looking like a success.
+ */
+export function extractSection(markdown, heading) {
+    const lines = markdown.split('\n');
+    const level = headingLevel(heading);
+    let openMarker;
+    let start = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (FENCE.test(trimmed)) {
+            // Opener and closer are both compared trimmed. An indented fence closed by a strict
+            // bare-marker test would stay open to end of file, and every heading after it would
+            // silently stop being a heading — the guides carry a two-space-indented one.
+            if (openMarker === undefined) {
+                openMarker = trimmed[0];
+            }
+            else if (trimmed[0] === openMarker) {
+                openMarker = undefined;
+            }
+            continue;
+        }
+        if (openMarker !== undefined) {
+            continue;
+        }
+        if (start === -1) {
+            if (line === heading) {
+                start = i;
+            }
+            continue;
+        }
+        if (headingLevel(line) > 0 && headingLevel(line) <= level) {
+            return lines.slice(start, i).join('\n');
+        }
+    }
+    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.
+    return lines.slice(start).join('\n');
+}
+function readSection(docsRoot, section) {
+    const path = join(docsRoot, section.file);
+    if (!existsSync(path)) {
+        // Named, never swallowed into empty text: a silently incomplete bundle would otherwise
+        // reach a reader as the document itself.
+        throw new Error(`bundled document missing: ${section.file}`);
+    }
+    const markdown = readFileSync(path, 'utf-8');
+    return section.heading === undefined ? markdown : extractSection(markdown, section.heading);
+}
+/**
+ * Answer one documentation query (§3-b).
+ *
+ * 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.
+ */
+export function queryDocs(spec) {
+    if (spec.topic === undefined) {
+        return { text: `Polydeukes docs:\n${TOPICS.map((t) => `  pdks docs ${t}`).join('\n')}\n` };
+    }
+    if (!isTopic(spec.topic)) {
+        throw new Error(`unknown docs topic '${spec.topic}' — known topics: ${TOPICS.join(', ')}`);
+    }
+    const entry = TOPIC_MAP[spec.topic];
+    const body = entry.sections.map((section) => readSection(spec.docsRoot, section)).join('\n');
+    // Resolved against the bundle, not printed as the bare relative name. A reader given
+    // `reference/core.md` has to guess where the bundle lives before it can open anything, and
+    // this line is the only way most of the reference layer is reached at all. A path a file-read
+    // tool can take is the difference between a pointer and a dead end, and a dead end sends the
+    // reader back to the web search this command replaces.
+    return { text: `${body}\nSee also: ${join(spec.docsRoot, entry.seeAlso)}\n` };
+}

package/dist/index.d.ts

@@ -1,8 +1,27 @@
 /**
- * Polydeukes — a harness framework for developing alongside an AI coding partner.
+ * Polydeukes — a development discipline framework for building alongside an AI
+ * coding partner.
  *
- * Pre-alpha. This package currently reserves the name and exposes only version
- * metadata; the core, guard, ledger, kb, and verify modules are in design.
+ * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
+ * `pdks` CLI entry point. It owns the config discovery loader (CONFIG-03) and both
+ * surfaces' composition roots — `runCovenantCheck` for the commit surface and
+ * `runClaudeCodeHook` for the session one — because assembly needs an adapter and the
+ * covenant package at once, which no sibling is allowed to depend on. The covenant,
+ * ledger, memory, and verify modules live in their own `@polydeukes/*` packages.
+ *
+ * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
+ * here would be instantiated by every consumer of any other export — which is exactly how
+ * the session adapter ended up on the commit surface's load path (PR #46 review). Keep
+ * definitions in their own modules and let importers reach them directly.
+ *
+ * The mirror of that coupling is closed as of DIST-02. `exports` publishes `./claude-code`
+ * alongside `"."`, and both delegators — this repository's and the one `pdks init
+ * claude-code` generates — enter through it, so a session call no longer instantiates
+ * `covenant-check.js` or `@polydeukes/adapter-git`. The window DIST-01 §3-d declared (a
+ * workspace missing only that dist failing closed with no telemetry row) is gone with it.
  * See https://github.com/huskyhoochu/polydeukes
  */
-export declare const version = "0.0.1";
+export type { ResolvedConfig } from '@polydeukes/core';
+export { type ClaudeCodeHookSpec, runClaudeCodeHook } from './claude-code-hook.js';
+export { type CovenantCheckSpec, runCovenantCheck } from './covenant-check.js';
+export { type LoadedConfig, loadConfig } from './load-config.js';

package/dist/index.js

@@ -1,8 +1,26 @@
 /**
- * Polydeukes — a harness framework for developing alongside an AI coding partner.
+ * Polydeukes — a development discipline framework for building alongside an AI
+ * coding partner.
  *
- * Pre-alpha. This package currently reserves the name and exposes only version
- * metadata; the core, guard, ledger, kb, and verify modules are in design.
+ * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
+ * `pdks` CLI entry point. It owns the config discovery loader (CONFIG-03) and both
+ * surfaces' composition roots — `runCovenantCheck` for the commit surface and
+ * `runClaudeCodeHook` for the session one — because assembly needs an adapter and the
+ * covenant package at once, which no sibling is allowed to depend on. The covenant,
+ * ledger, memory, and verify modules live in their own `@polydeukes/*` packages.
+ *
+ * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
+ * here would be instantiated by every consumer of any other export — which is exactly how
+ * the session adapter ended up on the commit surface's load path (PR #46 review). Keep
+ * definitions in their own modules and let importers reach them directly.
+ *
+ * The mirror of that coupling is closed as of DIST-02. `exports` publishes `./claude-code`
+ * alongside `"."`, and both delegators — this repository's and the one `pdks init
+ * claude-code` generates — enter through it, so a session call no longer instantiates
+ * `covenant-check.js` or `@polydeukes/adapter-git`. The window DIST-01 §3-d declared (a
+ * workspace missing only that dist failing closed with no telemetry row) is gone with it.
  * See https://github.com/huskyhoochu/polydeukes
  */
-export const version = '0.0.1';
+export { runClaudeCodeHook } from './claude-code-hook.js';
+export { runCovenantCheck } from './covenant-check.js';
+export { loadConfig } from './load-config.js';

package/dist/init-claude-code.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `initClaudeCode` — the session-surface installer (DIST-02 §3-a/§3-b/§3-g).
+ *
+ * One command wires a project into the session surface: prove the package resolves, run the
+ * shared project-side scaffold ({@link scaffoldProject}), then add what this distribution
+ * path owns — the delegator hook file, its `.claude/settings.json` registration, and the
+ * discipline file that tells an agent the docs query exists (DOCS-02 §3-e).
+ *
+ * Preflight comes first and nothing is written before it clears (§5-d invariant 2). A
+ * generated hook whose import can never resolve blocks every call through its own
+ * fail-closed catch, and a tree that also has no config and no valve to open cannot be
+ * edited back into shape from inside the session — the brick §3-g exists to prevent.
+ *
+ * Nothing existing is overwritten (§5-d invariant 1). The settings file in particular is
+ * merged, never replaced: a consumer's other PreToolUse registrations and permissions are
+ * live configuration, and replacing them would disarm every other tool they wired.
+ */
+import { type ScaffoldReport } from './scaffold-project.js';
+/** `initClaudeCode` input (DIST-02 §3-g) — the target tree and the preflight seam. */
+export type InitClaudeCodeSpec = {
+    /** Project root to install into — every write below is relative to it. */
+    projectRoot: string;
+    /**
+     * §3-g preflight seam: throws when the package cannot be resolved from the given root.
+     * ABSENT uses the real resolution, anchored at that root and nowhere else — anchoring it
+     * at the installer's own module would answer for the installer's install graph rather
+     * than the target project's, which is precisely the case that must fail.
+     */
+    resolvePolydeukes?: (projectRoot: string) => void;
+};
+/**
+ * Install the session surface into `spec.projectRoot` (DIST-02 §3-a), skipping whatever is
+ * already there and reporting both halves per artifact.
+ *
+ * Throws before any write when the package cannot be resolved from that root (§3-g) or when
+ * two config spellings already coexist there (§3-a third disposition) — both leave zero
+ * files. Translating a throw into exit 2 with the install command is the bin's job.
+ */
+export declare function initClaudeCode(spec: InitClaudeCodeSpec): ScaffoldReport;