@orkestrel/scaffold 0.0.1

package/dist/host/claude/agents/scout.md

@@ -0,0 +1,35 @@
+---
+name: scout
+description: 'Fast read-only recon. Use FIRST on unfamiliar ground — before research, planning, or implementation — to map the terrain, which files matter, where things live, and what needs to be read or touched. Cheap and quick; never reads files end-to-end.'
+tools: Read, Grep, Glob
+model: sonnet
+effort: low
+---
+
+You are the **Scout** — the recon unit of this project's orchestration triad (see
+CLAUDE.md). Your job is to map terrain cheaply so no other agent wastes context on
+discovery. You are an Executor: do the work yourself, spawn nothing, return only
+the map.
+
+## Job
+
+1. Locate the relevant files and directories — glob/grep first; open a file only to
+   confirm relevance, and skim, never read end-to-end.
+2. Identify entry points, the contracts/types involved, the matching tests, and the
+   governing docs (AGENTS.md always; any guide that covers the area).
+3. Note shape and size — rough line counts, call-site counts, obvious hot spots.
+
+## Output contract — the Map
+
+Return ONLY this, compact (well under ~60 lines):
+
+- **Goal restated** — one line.
+- **Files that matter** — path + one-line role each, in read-first order.
+- **Off to the side** — related-looking paths that are NOT relevant, half a line why
+  (saves everyone else the detour).
+- **Pointers** — entry points, key symbols, matching test files, governing guide paths.
+- **Flags** — anything surprising (generated code, huge files, duplication), one
+  line each.
+
+No file contents. No analysis. No recommendations. If the terrain exceeds the
+budget, say which subarea needs its own scout pass instead of inflating the map.

package/dist/host/claude/agents/verifier.md

@@ -0,0 +1,34 @@
+---
+name: verifier
+description: 'Runs the authoritative quality gates — format, check, build, targeted tests — or the exact scoped gate set / evidence commands the dispatch names, and reports true pass/fail per gate with exact failure excerpts. Independent of every builder; its report is the source of truth for green. Never fixes anything.'
+tools: Read, Grep, Glob, Bash
+model: sonnet
+effort: low
+---
+
+You are the **Verifier** — the gate-runner of this project's orchestration triad
+(see CLAUDE.md). Independence is the point: no builder's self-report counts, yours
+does. You are an Executor: run the gates yourself, spawn nothing.
+
+## Job
+
+1. Run EXACTLY the commands the dispatch names, in order. The default authoritative
+   sweep, when the dispatch says so: `format` → `check` → `build` → the targeted
+   test project(s) it names. Never invent broader or narrower gates than dispatched.
+2. Evidence runs count as gates: when dispatched to reproduce a failure, run the
+   named command and capture its exact output — reproduce, capture, bisect
+   mechanically if told to; nothing more.
+3. Record each gate's TRUE outcome by exit code. A gate that "mostly passes" FAILED.
+4. On failure, capture the exact failing excerpt — trimmed to the failure, not the
+   noise — and the file:line it points to.
+
+## Output contract — the Gate Report
+
+- **Per gate** — command → PASS / FAIL (exit code) → on FAIL, the exact failure
+  excerpt plus the suspected owning file(s).
+- **Overall verdict** — GREEN only if every gate passed; otherwise the first place
+  to look.
+- **Anomalies** — cache weirdness, flakes on rerun, anything off — one line each.
+
+You never edit files and never "quick-fix" a failure — you report it. Return only
+the gate report, never your process.

package/dist/host/claude/settings.json

@@ -0,0 +1,26 @@
+{
+	"hooks": {
+		"SessionStart": [
+			{
+				"matcher": "startup|resume",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "\"$CLAUDE_PROJECT_DIR\"/scripts/deps.sh",
+						"timeout": 600
+					},
+					{
+						"type": "command",
+						"command": "\"$CLAUDE_PROJECT_DIR\"/scripts/ollama.sh",
+						"timeout": 600
+					},
+					{
+						"type": "command",
+						"command": "\"$CLAUDE_PROJECT_DIR\"/scripts/cursor.sh",
+						"timeout": 120
+					}
+				]
+			}
+		]
+	}
+}

package/dist/host/dotfiles/editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = tab
+indent_size = 4
+
+[*.{json,jsonc,yaml,yml}]
+indent_style = tab
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+

package/dist/host/dotfiles/gitattributes

@@ -0,0 +1,3 @@
+# Enforce LF line endings everywhere — prevents CRLF/LF churn on Windows
+* text=auto eol=lf
+

package/dist/host/dotfiles/gitignore

@@ -0,0 +1,40 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+tmp
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment variables (keep secret)
+.env
+.env.*
+!.env.example
+
+# Test screenshots (generated by vitest browser mode)
+tests/**/__screenshots__/
+
+# Playwright
+test-results/
+playwright-report/
+
+# Model files
+*.gguf

package/dist/host/dotfiles/oxfmtrc.json

@@ -0,0 +1,18 @@
+{
+	"$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxfmt/configuration_schema.json",
+	"endOfLine": "lf",
+	"semi": false,
+	"singleQuote": true,
+	"trailingComma": "all",
+	"printWidth": 100,
+	"useTabs": true,
+	"tabWidth": 2,
+	"overrides": [
+		{
+			"files": ["*.json", "*.jsonc"],
+			"options": {
+				"trailingComma": "none"
+			}
+		}
+	]
+}

package/dist/host/dotfiles/oxlintignore

@@ -0,0 +1,20 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Cache
+.cache/
+.eslintcache
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

package/dist/host/dotfiles/oxlintrc.json

@@ -0,0 +1,58 @@
+{
+	"$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
+	"plugins": ["import", "vitest"],
+	"rules": {
+		"@typescript-eslint/no-explicit-any": "error",
+		"@typescript-eslint/no-non-null-assertion": "error",
+		"@typescript-eslint/no-unused-vars": [
+			"error",
+			{
+				"argsIgnorePattern": "^_",
+				"varsIgnorePattern": "^_",
+				"caughtErrorsIgnorePattern": "^_",
+				"ignoreRestSiblings": true
+			}
+		],
+		"@typescript-eslint/consistent-type-imports": [
+			"error",
+			{
+				"prefer": "type-imports",
+				"fixStyle": "separate-type-imports"
+			}
+		],
+
+		"import/no-default-export": "error",
+		"import/extensions": "off",
+		"import/no-unassigned-import": ["error", { "allow": ["**/*.css", "**/*.scss"] }],
+
+		"no-var": "error",
+		"prefer-const": "error",
+		"no-debugger": "error",
+		"no-underscore-dangle": "warn",
+
+		"vitest/warn-todo": "off"
+	},
+	"categories": {
+		"correctness": "error",
+		"suspicious": "warn",
+		"pedantic": "off",
+		"perf": "off",
+		"style": "off",
+		"restriction": "off"
+	},
+	"overrides": [
+		{
+			"files": ["*.config.ts", "*.config.js"],
+			"rules": {
+				"import/no-default-export": "off"
+			}
+		},
+		{
+			"files": ["*.vue"],
+			"rules": {
+				"import/no-default-export": "off",
+				"no-unused-expressions": "off"
+			}
+		}
+	]
+}

package/dist/host/dotfiles/prettierignore

@@ -0,0 +1,5 @@
+# oxfmt (and prettier) read this file by default. Keep generated / minified
+# artifacts out of the formatter so a tree-wide `npm run format` never rewrites them.
+
+# Build output (also gitignored, listed for explicitness).
+dist/

package/dist/host/github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: ci.yml
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Install Ollama
+        run: curl -fsSL https://ollama.com/install.sh | sh
+
+      - name: Start Ollama
+        run: |
+          sudo systemctl stop ollama
+          OLLAMA_ORIGINS="*" OLLAMA_HOST="127.0.0.1:11434" nohup ollama serve > /dev/null 2>&1 &
+          for i in $(seq 1 30); do
+            if curl -sf http://127.0.0.1:11434/api/tags > /dev/null 2>&1; then
+              echo "Ollama is ready"
+              break
+            fi
+            echo "Waiting for Ollama... ($i/30)"
+            sleep 1
+          done
+      - name: Pull models
+        run: ollama pull qwen3.5:2b-q4_K_M
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Lint
+        run: npm run lint:check
+
+      - name: Typecheck
+        run: npm run check
+
+      - name: Typecheck src
+        run: npm run check:src
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test

package/dist/host/guides/src/guide.md

@@ -0,0 +1,312 @@
+# Guide
+
+> A zero-dependency guides-parity toolkit: `Guide` extracts a markdown guide's documented
+> surface, method groups, links, and test links; `Source` reflects the same shapes from a
+> consumer-supplied file inventory via pure text scanners (no filesystem, no TypeScript
+> compiler API); a small set of pure comparison helpers (`missingSymbols`, `findMissing`,
+> `resolveLink`, …) reduce every guides-parity check to `expect([]).toEqual([])`
+> (AGENTS §22). Source: [`src/core`](../../src/core). Surfaced through the `@src/core` barrel.
+
+The doctrine: a guide is a contract, not prose. `createGuide(markdown)` parses a guide's
+source once (via `@orkestrel/markdown`) into a `GuideInterface` — its `## Surface` identifiers
+(kind-tagged), its `## Methods` interface/method groups, every link, and its `## Tests`
+links, each cached at construction. `createSource({ files, module })` builds a
+`SourceInterface` that reflects the SAME two shapes — exported symbols and interface/class
+methods — by scanning a consumer-gathered file inventory with plain-text line scanners
+(`exportsFrom`, `declarationBody` + `memberMethods`), never touching disk itself. A
+guides-parity test then asserts these two views agree in both directions: nothing documented
+is phantom, nothing exported is undocumented. `parseManifest` reads a `guides/README.md`'s
+`## By concept` table into the list of `{ concept, spec, source, tests }` entries a suite
+iterates to run this check once per documented concept.
+
+## Surface
+
+### Types
+
+The manifest/extraction shapes every check is built from, from [`types.ts`](../../src/core/types.ts).
+
+| Name              | Kind      | Shape                                                                                                                                             |
+| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ExportKind`      | type      | `'type' \| 'interface' \| 'const' \| 'function' \| 'class'` — the declaration kind half of a symbol's bijection key.                              |
+| `SurfaceSymbol`   | interface | `{ name, kind }` — one documented / exported symbol.                                                                                              |
+| `GuideModule`     | type      | `string \| readonly string[]` — one source directory, or several for a layer guide spanning multiple directories.                                 |
+| `ManifestEntry`   | interface | `{ concept, spec, source, tests }` — one `## By concept` manifest row, paths normalized to workspace root.                                        |
+| `MethodGroup`     | interface | `{ interface, methods }` — one `#### \`Interface\`` block's documented method names, in table order.                                              |
+| `GuideInterface`  | interface | `{ sections, surface, methods, links, tests, patterns }` — the structured, pure view over one parsed guide. See [`## Methods`](#methods).         |
+| `SourceInterface` | interface | `{ exports, methods, exists, hidden, examples }` — the reflected source truth a guide's surface is checked against. See [`## Methods`](#methods). |
+| `SourceOptions`   | interface | `{ files, module }` — the construction input for a `Source`: a consumer-supplied file inventory plus the module scope to reflect.                 |
+| `DeclarationHead` | interface | `{ text, end }` — a declaration head joined into one line (across an oxfmt-wrapped signature) plus the index of the line ending in `{`.           |
+
+### Constants
+
+The section-heading keys and external-link schemes every extractor and link check is keyed
+on, from [`constants.ts`](../../src/core/constants.ts).
+
+| Name               | Kind  | Behavior                                                                                                                        |
+| ------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `SURFACE`          | const | `'Surface'` — the `## Surface` heading text.                                                                                    |
+| `METHODS`          | const | `'Methods'` — the `## Methods` heading text.                                                                                    |
+| `TESTS`            | const | `'Tests'` — the `## Tests` heading text.                                                                                        |
+| `MANIFEST`         | const | `'By concept'` — the `## By concept` manifest heading text.                                                                     |
+| `EXTERNAL_SCHEMES` | const | `readonly string[]` — `['http:', 'https:', 'mailto:', 'tel:']`; a link with one of these prefixes is never filesystem-resolved. |
+
+### Helpers
+
+Pure, total leaves from [`helpers.ts`](../../src/core/helpers.ts) — the building blocks
+`parsers.ts`'s extractors and a consumer's parity test both reach for directly.
+
+| Name             | Kind     | Signature                                                                                                 | Behavior                                                                                                                                                          |
+| ---------------- | -------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `moduleDirs`     | function | `(module: GuideModule) => readonly string[]`                                                              | Normalizes a `GuideModule` scope to its directory list — a single string becomes a one-element list.                                                              |
+| `moduleKeys`     | function | `(files: Readonly<Record<string, string>>, module: GuideModule) => readonly string[]`                     | The file inventory's keys belonging to a `GuideModule` scope: `.ts` files under a scope directory, excluding that directory's `index.ts` and `*.test.ts`; sorted. |
+| `symbolKey`      | function | `(symbol: SurfaceSymbol) => string`                                                                       | The bijection key for a surface symbol — `${kind} ${name}` — so a symbol comparison diffs (name, kind) pairs, not names alone.                                    |
+| `findMissing`    | function | `(names: readonly string[], source: readonly string[]) => readonly string[]`                              | The names present in `names` but absent from `source` — the set-difference behind a both-directions bijection assertion.                                          |
+| `missingSymbols` | function | `(symbols: readonly SurfaceSymbol[], source: readonly SurfaceSymbol[]) => readonly string[]`              | The `symbolKey` set-difference between two symbol lists.                                                                                                          |
+| `isExternalLink` | function | `(href: string) => boolean`                                                                               | Whether a link `href` should be skipped by guides-parity link checks — an external scheme (`EXTERNAL_SCHEMES`) or a bare `#` anchor.                              |
+| `resolveLink`    | function | `(from: string, target: string) => string`                                                                | Resolves a relative link `target` against `from` and normalizes the result, purely (no `node:path`).                                                              |
+| `firstCode`      | function | `(nodes: readonly InlineNode[]) => string \| undefined`                                                   | The first code-span value found by descending an inline node list, following into `emphasis` / `link` children.                                                   |
+| `identifierOf`   | function | `(code: string) => string`                                                                                | The identifier prefix of a code-span text — everything before its first `<`, trimmed (strips generic-parameter annotation).                                       |
+| `kindIndex`      | function | `(table: TableNode) => number \| undefined`                                                               | The index of a table's `Kind` column, found by its header text so it survives column reordering.                                                                  |
+| `cellLinks`      | function | `(cell: readonly InlineNode[]) => readonly string[]`                                                      | The link hrefs found within one table cell's inline content, in walk order.                                                                                       |
+| `findUnexampled` | function | `(names: readonly string[], fences: readonly string[], examples: readonly string[]) => readonly string[]` | The names with no fence mention (word boundary) and no `@example` membership — the EX check's core comparison.                                                    |
+| `fenceImports`   | function | `(fence: string) => readonly { specifier: string, names: readonly string[] }[]`                           | Parses a fence's `import` statements into per-specifier imported identifier names — the FI check's core comparison.                                               |
+
+### Parsers
+
+The guide/manifest extraction pipeline, from [`parsers.ts`](../../src/core/parsers.ts) —
+the orchestration `Guide` composes out of `helpers.ts`'s leaves.
+
+| Name              | Kind     | Signature                                                                              | Behavior                                                                                                                                                 |
+| ----------------- | -------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `exportsFrom`     | function | `(source: string) => readonly SurfaceSymbol[]`                                         | The module-scope exports declared in one file's source text, deduped by (kind, name); a generator export scans as `function`.                            |
+| `hiddenFrom`      | function | `(source: string) => readonly SurfaceSymbol[]`                                         | The module-scope declarations LACKING the `export` keyword — the export-discipline (AGENTS §5) mirror of `exportsFrom`, same five-kind grammar.          |
+| `joinHead`        | function | `(lines: readonly string[], start: number) => DeclarationHead \| undefined`            | Joins a declaration head starting at `start` into one space-separated line, consuming lines until the first ending in `{`.                               |
+| `declarationBody` | function | `(source: string, keyword: 'class' \| 'interface', name: string) => readonly string[]` | The body lines of the named `export class` / `export interface` declaration in one file's source text.                                                   |
+| `memberMethods`   | function | `(lines: readonly string[]) => readonly string[]`                                      | The declared callable-member names in a declaration body — plain / `async` / generator / optional; getters, setters, `static`, `#` privates never count. |
+| `sectionBlocks`   | function | `(document: MarkdownDocument, heading: string) => readonly BlockNode[]`                | The block nodes under a named `##` heading, up to the next `##`-or-higher heading (or the document's end).                                               |
+| `extractSurface`  | function | `(document: MarkdownDocument) => readonly SurfaceSymbol[]`                             | Every `## Surface` identifier: each table's rows union every backticked H3 entity heading, deduped by `symbolKey`.                                       |
+| `extractMethods`  | function | `(document: MarkdownDocument) => readonly MethodGroup[]`                               | One `MethodGroup` per documented behavioral interface in `## Methods` — an H4 code span sets the interface, the following table lists its methods.       |
+| `extractLinks`    | function | `(document: MarkdownDocument) => readonly string[]`                                    | Every link href in the guide document, including table cells — a full, depth-first AST walk.                                                             |
+| `extractTests`    | function | `(document: MarkdownDocument) => readonly string[]`                                    | The relative test links declared under `## Tests`.                                                                                                       |
+| `examplesFrom`    | function | `(source: string) => readonly string[]`                                                | The exported functions in one file's source text whose immediately preceding JSDoc block carries `@example`.                                             |
+| `exampleMethods`  | function | `(lines: readonly string[]) => readonly string[]`                                      | The `exampleMethods`-flavored `memberMethods` — callable-member names in a declaration body whose preceding JSDoc carries `@example`.                    |
+| `extractPatterns` | function | `(document: MarkdownDocument) => readonly string[]`                                    | Every fenced `ts` code block's body text anywhere in the guide document — a full AST walk.                                                               |
+| `parseManifest`   | function | `(markdown: string, base: string) => readonly ManifestEntry[]`                         | Parses a `## By concept` manifest table into `ManifestEntry` rows, resolving Spec / Source / Tests links against `base`.                                 |
+
+### Shapers
+
+Declarative `ContractShape` values (from `@orkestrel/contract`) from
+[`shapers.ts`](../../src/core/shapers.ts) — every documented data type here is
+non-recursive, so each shapes directly.
+
+| Name                 | Kind  | Builds                                                                              |
+| -------------------- | ----- | ----------------------------------------------------------------------------------- |
+| `surfaceSymbolShape` | const | The shape of a `SurfaceSymbol` — `{ name: string, kind: ExportKind }`.              |
+| `methodGroupShape`   | const | The shape of a `MethodGroup` — `{ interface: string, methods: readonly string[] }`. |
+| `manifestEntryShape` | const | The shape of a `ManifestEntry` — `source` accepting a single directory or several.  |
+
+### Validators
+
+Total from-unknown guards composed from `@orkestrel/contract` combinators, from
+[`validators.ts`](../../src/core/validators.ts).
+
+| Name              | Kind  | Narrows to / Tests | Behavior                                                                 |
+| ----------------- | ----- | ------------------ | ------------------------------------------------------------------------ |
+| `isExportKind`    | const | `value: unknown`   | `true` when `value` is one of the five documented `ExportKind` literals. |
+| `isSurfaceSymbol` | const | `value: unknown`   | `true` when `value` is a well-formed `SurfaceSymbol`.                    |
+| `isMethodGroup`   | const | `value: unknown`   | `true` when `value` is a well-formed `MethodGroup`.                      |
+| `isManifestEntry` | const | `value: unknown`   | `true` when `value` is a well-formed `ManifestEntry`.                    |
+
+### Factories
+
+From [`factories.ts`](../../src/core/factories.ts).
+
+| Name                          | Kind     | Signature                                     | Behavior                                                                         |
+| ----------------------------- | -------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
+| `createGuide`                 | function | `(source: string) => GuideInterface`          | Creates a structured `GuideInterface` view over one guide's markdown source.     |
+| `createSource`                | function | `(options: SourceOptions) => SourceInterface` | Creates a pure `SourceInterface` over a consumer-supplied file inventory.        |
+| `createSurfaceSymbolContract` | function | `() => ContractInterface<SurfaceSymbol>`      | Compiles `surfaceSymbolShape` into a guard / parser / schema / generator bundle. |
+| `createMethodGroupContract`   | function | `() => ContractInterface<MethodGroup>`        | Compiles `methodGroupShape` into a guard / parser / schema / generator bundle.   |
+| `createManifestEntryContract` | function | `() => ContractInterface<ManifestEntry>`      | Compiles `manifestEntryShape` into a guard / parser / schema / generator bundle. |
+
+### `Guide`
+
+The implementing class of `GuideInterface`, from [`Guide.ts`](../../src/core/Guide.ts). A
+stateful, structured view over one parsed guide: parses `source` once via
+`@orkestrel/markdown` and never touches the filesystem — `Guide` has no notion of "where"
+the guide came from, only its markdown text. Every accessor returns the same cached,
+readonly array on every call. See [`## Methods`](#methods) for its public call-signature
+surface.
+
+### `Source`
+
+The implementing class of `SourceInterface`, from [`Source.ts`](../../src/core/Source.ts). A
+pure reflection over a consumer-supplied file inventory (root-relative path → file text) plus
+a module scope — reflects exported symbols (`exportsFrom`) and interface/class methods
+(`declarationBody` + `memberMethods`) with text-only line scanners, never the TypeScript
+compiler API or the filesystem. `exports()` is computed once on first access and cached; the
+consumer gathers `files` however their environment allows (`node:fs` in a Node script,
+`import.meta.glob` in a browser/vitest run). See [`## Methods`](#methods) for its public
+call-signature surface.
+
+## Methods
+
+The public methods of each behavioral interface — one table per type, keyed by its
+backticked name (AGENTS §22).
+
+#### `GuideInterface`
+
+| Method     | Returns                    | Behavior                                                                                    |
+| ---------- | -------------------------- | ------------------------------------------------------------------------------------------- |
+| `sections` | `readonly string[]`        | The `##` heading names, in document order — the non-vacuousness guard for section presence. |
+| `surface`  | `readonly SurfaceSymbol[]` | Every `## Surface` identifier + kind — table rows union backticked entity headings.         |
+| `methods`  | `readonly MethodGroup[]`   | One `MethodGroup` per documented behavioral interface in `## Methods`.                      |
+| `links`    | `readonly string[]`        | Every link href in the guide, including table cells.                                        |
+| `tests`    | `readonly string[]`        | The relative test links declared under `## Tests`.                                          |
+| `patterns` | `readonly string[]`        | Every fenced `ts` code block's body text, whole document.                                   |
+
+#### `SourceInterface`
+
+| Method     | Returns                    | Behavior                                                                                                   |
+| ---------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `exports`  | `readonly SurfaceSymbol[]` | Every module-scope export, including type-only, by (name, kind).                                           |
+| `methods`  | `readonly string[]`        | The call-signature members of the `class` / `interface` named `name`.                                      |
+| `exists`   | `boolean`                  | Whether a workspace-root-relative path exists in the inventory.                                            |
+| `hidden`   | `readonly SurfaceSymbol[]` | Every module-scope declaration LACKING `export` (AGENTS §5).                                               |
+| `examples` | `readonly string[]`        | The exported functions (or, given `name`, the members of `name`) whose preceding JSDoc carries `@example`. |
+
+## The extraction model
+
+`Guide` parses a guide's markdown once (via `@orkestrel/markdown`'s `createMarkdown`) and
+caches five projections at construction — `sections`, `surface`, `methods`, `links`, `tests`
+— so every accessor is a cheap array return, not a re-parse. `extractSurface` scopes to the
+`## Surface` section (`sectionBlocks`) and unions two sources of identifiers: every table's
+column-0 code span (kind read from the column whose header text is `Kind`, located
+positionally so it survives reordering) and every backticked H3 entity heading (a class
+documented outside a table, kind fixed to `'class'`). `extractMethods` scopes to
+`## Methods`: an H4 whose first code span sets the current interface name, and the very next
+table becomes that interface's `MethodGroup`. Both extractors normalize every identifier
+through `identifierOf`, stripping a generic-parameter annotation (`` `WidgetInterface<T>` ``
+→ `WidgetInterface`) so the bijection key is always the bare name. `extractLinks` walks the
+whole AST for every `link` node (table cells included); `extractTests` does the same walk
+scoped to the `## Tests` section only.
+
+`Source` never parses markdown or touches disk — it scans a consumer-supplied file
+inventory's TEXT with regex-based line scanners. `exportsFrom` matches
+`^export (?:async )?(function\*?|class|const|interface|type) (\w+)` per line, deduped by
+(kind, name). `declarationBody` locates a named `export class` / `export interface` head
+(joining an oxfmt-wrapped signature via `joinHead` until a line ends in `{`), then collects
+body lines to the column-0 `}`. `memberMethods` matches
+`^\t(?:async )?\*?(\w+)(<[^>]*>)?\??\(` against those body lines — plain / `async` /
+generator / optional methods count; getters, setters, `static` members, and `#` privates
+never match (their keyword or sigil breaks the `name(` shape), and `constructor` is filtered
+out of `Source.methods`. `moduleKeys` scopes the inventory to one `GuideModule`'s `.ts`
+files, excluding each scope directory's own `index.ts` and any `*.test.ts` file. `hiddenFrom`
+runs the mirror-image scan — the same five-kind grammar, but only lines LACKING the `export`
+keyword — so `Source.hidden()` mechanically asserts AGENTS §5's export-discipline rule and
+catches a hidden declaration the surface bijection alone would never see (it never appears as
+an export, so it never shows up as a missing Surface row either).
+
+## The check catalog
+
+Every guides-parity check reduces to `expect([]).toEqual([])`, paired with a non-vacuousness
+guard so a renamed heading fails loudly instead of passing on an empty extraction:
+
+- **SB — Surface bijection (kind folded in).** `guide.surface()` vs `source.exports()`,
+  `missingSymbols` both directions over `symbolKey` — a symbol may drift in neither name nor
+  kind. Guard: `guide.surface().length > 0`.
+- **MB — Methods bijection + class-no-extra.** Per `MethodGroup`, its `methods` vs
+  `source.methods(group.interface)`, `findMissing` both directions; then, by the
+  `XInterface → X` naming convention, `findMissing(source.methods('X'), group.methods)` must
+  also be empty — the implementing class exposes no undocumented public method. Guard:
+  `group.methods.length > 0`.
+- **LI — Link integrity.** `guide.links()`, dropping `isExternalLink` hrefs, `resolveLink`
+  the rest against the guide's own path, keep those failing `source.exists`.
+- **TE — Tests-link existence.** `guide.tests()`, `resolveLink` + `source.exists`, keep the
+  missing.
+- **NV — Non-vacuousness.** `parseManifest` yields at least one entry; each guide's
+  `surface()` and every `MethodGroup` is non-empty — the guard behind every other check.
+- **EX — Examples presence.** A documented symbol "has an example" when its bare name
+  appears (word boundary) in any of `guide.patterns()`'s fence bodies, OR its source
+  JSDoc carries an `@example` block (`source.examples()` / `source.examples(name)`).
+  Applies to every `function`-kind `Surface` symbol and every `MethodGroup` member.
+  Presence-only — fence and JSDoc CONTENT are never checked. `findUnexampled` is the
+  comparison. Guard: the SB/MB extractions this check reuses already prove non-vacuous.
+- **FI — Fence-import reality.** Every `import { ... } from 'specifier'` in a
+  `guide.patterns()` fence, for a SELF specifier (this repo's own package name / path
+  alias), imports only names that exist in `source.exports()`. `fenceImports` parses the
+  statement; `findMissing` diffs the imported names against `source.exports()`'s names.
+
+## The pure file-inventory model
+
+Neither `Guide` nor `Source` ever imports `node:fs` or any other I/O primitive — `Source`'s
+construction input (`SourceOptions.files`) is a plain `Readonly<Record<string, string>>` the
+CONSUMER gathers however their runtime allows: a recursive `node:fs` walk in a Node vitest
+run, `import.meta.glob('/**/*.ts', { eager: true, query: '?raw', import: 'default' })` in a
+browser/vitest run, or a static bundle in any other environment. This keeps the package
+itself environment-agnostic while every check still runs against real, on-disk truth in the
+consumer's own test.
+
+## Patterns
+
+### Construct a `Guide` from markdown text
+
+```ts
+import { createGuide } from '@orkestrel/guide'
+
+const guide = createGuide('## Surface\n\n| Name | Kind |\n| --- | --- |\n| `X` | class |')
+guide.surface() // [{ name: 'X', kind: 'class' }]
+guide.sections() // ['Surface']
+```
+
+### Construct a `Source` from an inline files record
+
+```ts
+import { createSource } from '@orkestrel/guide'
+
+const source = createSource({
+	files: {
+		'src/core/Guide.ts': 'export class Guide {}\n',
+		'src/core/types.ts': 'export interface GuideInterface {\n\tsections(): void\n}\n',
+	},
+	module: 'src/core',
+})
+source.exports() // [{ name: 'Guide', kind: 'class' }, { name: 'GuideInterface', kind: 'interface' }]
+source.methods('GuideInterface') // ['sections']
+source.exists('src/core/Guide.ts') // true
+```
+
+### The bijection assertion shape
+
+```ts
+import { createGuide, createSource, missingSymbols } from '@orkestrel/guide'
+
+const guide = createGuide('## Surface\n\n| Name | Kind |\n| --- | --- |\n| `Guide` | class |')
+const source = createSource({
+	files: { 'src/core/Guide.ts': 'export class Guide {}\n' },
+	module: 'src/core',
+})
+
+// Every check collapses to an empty-array assertion, both directions.
+missingSymbols(source.exports(), guide.surface()) // [] — every export is documented
+missingSymbols(guide.surface(), source.exports()) // [] — every documented symbol is real
+```
+
+## Tests
+
+- [`tests/src/core/helpers.test.ts`](../../tests/src/core/helpers.test.ts) — `moduleDirs` / `moduleKeys` / `symbolKey` / `findMissing` / `missingSymbols` / `isExternalLink` / `resolveLink` / `firstCode` / `identifierOf` / `kindIndex`.
+- [`tests/src/core/parsers.test.ts`](../../tests/src/core/parsers.test.ts) — `exportsFrom` / `joinHead` / `declarationBody` / `memberMethods` / `sectionBlocks` / `extractSurface` / `extractMethods` / `extractLinks` / `extractTests` / `parseManifest`, incl. entity-heading surface and multi-dir Source cells.
+- [`tests/src/core/validators.test.ts`](../../tests/src/core/validators.test.ts) — `isExportKind` / `isSurfaceSymbol` / `isMethodGroup` / `isManifestEntry`.
+- [`tests/src/core/shapers.test.ts`](../../tests/src/core/shapers.test.ts) — per-shape guard exactness, JSON Schema essentials, seeded generate round-trips, parse rebuilds.
+- [`tests/src/core/factories.test.ts`](../../tests/src/core/factories.test.ts) — `createGuide` / `createSource` + the compiled symbol/group/manifest contracts.
+- [`tests/src/core/Guide.test.ts`](../../tests/src/core/Guide.test.ts) — `Guide`'s five cached projections, constructed once, called repeatedly.
+- [`tests/src/core/Source.test.ts`](../../tests/src/core/Source.test.ts) — `Source`'s pure reflection against an in-memory fixture inventory, incl. `memberMethods` on every excluded shape (getters, setters, `static`, `#` privates, `constructor`).
+- [`tests/guides/src/parity.test.ts`](../../tests/guides/src/parity.test.ts) — the drop-in guides-parity suite, run against THIS repo's own `guides/README.md` manifest — the self-dogfooding acceptance criterion.
+
+## See also
+
+- `AGENTS.md` (workspace root) — the rules; §22 documentation-as-contracts.
+- `PROPOSAL.md` (workspace root) — the design proposal this package implements; §5 the check catalog, §6 the drop-in, §7 source-scanning fidelity.
+- [`README.md`](../README.md) — the guides index.
+- [`markdown.md`](markdown.md) — the dependency mirror for `@orkestrel/markdown`, the AST/parse layer `Guide` and `Source` are built on.
+</content>