unknown-knowledge 2.1.0

package/cli/lib/generate-wrappers.js

@@ -0,0 +1,162 @@
+/**
+ * Platform wrapper generation (KK-18, PRD §6/§9.2) — the second half of the
+ * init copy layer: thin pointer files at each selected agent platform's
+ * conventional path, aiming the platform at <root>/protocol/AGENTS.md. Like
+ * copy-payload.js this is the ENGINE only; the multi-select prompt is
+ * KK-19's, callers pass the chosen platform ids.
+ *
+ * The registry is DATA, not code: the `platforms:` section of
+ * cli/kit.manifest.yaml (id → { name, template, target, mode }). Adding a
+ * platform later = adding a manifest entry (+ a template under
+ * payload/wrappers/ if the generic pointer doesn't fit). Templates live in
+ * payload/ under the same D-007 constructional guards as copy sources;
+ * targets are CLIENT-REPO-ROOT-relative conventional paths (dotted dirs
+ * allowed — the §6 never-dotted rule governs the seeded root only).
+ * Wrappers duplicate nothing: protocol/AGENTS.md stays the single source of
+ * truth; a wrapper is a few pointer lines rendered from its template with
+ * `{{root}}` replaced by the seeded root name.
+ *
+ * Collision policy (§6), per the registry's `mode`:
+ *   shared    — ecosystem-shared instruction files (root AGENTS.md,
+ *               .github/copilot-instructions.md). Fresh file → created
+ *               holding just the sentinel block. Existing file without
+ *               sentinels → APPENDED between sentinel markers, existing
+ *               content byte-preserved. Existing well-formed sentinel block
+ *               → content REPLACED WITHIN the sentinels (the idempotent
+ *               choice: re-generation converges instead of refusing, and a
+ *               root rename updates the pointer in place). Malformed
+ *               sentinels (unbalanced/reversed/multiple) → skip-and-report,
+ *               never guess.
+ *   dedicated — single-tool files (CLAUDE.md, GEMINI.md, .cursor rule).
+ *               Created if absent; an existing file is the user's own —
+ *               skip-and-report, never clobbered.
+ * Symlinked targets are skipped, never written through (D-007 posture).
+ *
+ * Deterministic by construction: pure render of template x root name,
+ * platforms processed sorted, no wall-clock reads. Skips are REPORTED
+ * results, not errors — a partial wrapper set never fails the seed.
+ */
+import { lstatSync, mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { DEFAULT_ROOT, loadManifest, validateRootName } from './copy-payload.js';
+
+export const SENTINEL_BEGIN = '<!-- unknown-knowledge:begin -->';
+export const SENTINEL_END = '<!-- unknown-knowledge:end -->';
+
+/** Refuse unknown platform ids against the manifest registry (pre-seed check). */
+export function assertKnownPlatforms(manifest, ids) {
+  const known = Object.keys(manifest.platforms).sort();
+  for (const id of ids) {
+    if (!known.includes(id)) {
+      throw new Error(`unknown platform ${JSON.stringify(id)} — manifest defines: ${known.join(', ') || '(none)'}`);
+    }
+  }
+}
+
+/** Pure template render: {{root}} → seeded root name; leftovers are a template bug. */
+function renderTemplate(text, rootName, templateRel) {
+  const out = text.replaceAll('{{root}}', rootName);
+  const leftover = out.match(/\{\{[a-z0-9-]+\}\}/);
+  if (leftover) throw new Error(`wrapper template ${templateRel}: unresolved placeholder ${leftover[0]}`);
+  return out;
+}
+
+function sentinelBlock(body) {
+  return `${SENTINEL_BEGIN}\n${body.trimEnd()}\n${SENTINEL_END}\n`;
+}
+
+/** lstat that treats absence as null (a dangling symlink still counts as present). */
+function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+const countOf = (text, needle) => text.split(needle).length - 1;
+
+/** §6 shared-file policy: sentinel-append / replace-within-sentinels, never clobber. */
+function writeShared(targetAbs, body) {
+  const block = sentinelBlock(body);
+  const stat = lstatOrNull(targetAbs);
+  if (stat === null) {
+    mkdirSync(dirname(targetAbs), { recursive: true });
+    writeFileSync(targetAbs, block);
+    return { action: 'created' };
+  }
+  if (stat.isSymbolicLink()) {
+    return { action: 'skipped', reason: 'target is a symlink — wrappers are never written through links' };
+  }
+  const text = readFileSync(targetAbs, 'utf8');
+  const begins = countOf(text, SENTINEL_BEGIN);
+  const ends = countOf(text, SENTINEL_END);
+  if (begins === 0 && ends === 0) {
+    const sep = text.length === 0 ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+    writeFileSync(targetAbs, `${text}${sep}${block}`);
+    return { action: 'appended' };
+  }
+  if (begins === 1 && ends === 1 && text.indexOf(SENTINEL_BEGIN) < text.indexOf(SENTINEL_END)) {
+    const start = text.indexOf(SENTINEL_BEGIN);
+    let after = text.indexOf(SENTINEL_END) + SENTINEL_END.length;
+    if (text[after] === '\n') after += 1; // the block carries its own trailing newline
+    writeFileSync(targetAbs, text.slice(0, start) + block + text.slice(after));
+    return { action: 'replaced' };
+  }
+  return {
+    action: 'skipped',
+    reason: `existing sentinel markers are malformed (expected exactly one ${SENTINEL_BEGIN} before one ${SENTINEL_END}) — resolve the file by hand, then re-add the pointer`,
+  };
+}
+
+/** §6 dedicated-file policy: create if absent; an existing file is never touched. */
+function writeDedicated(targetAbs, body, rootName) {
+  if (lstatOrNull(targetAbs) !== null) {
+    return {
+      action: 'skipped',
+      reason: `already exists — dedicated wrapper targets are never overwritten (§6); add the pointer yourself: read ${rootName}/protocol/AGENTS.md before working`,
+    };
+  }
+  mkdirSync(dirname(targetAbs), { recursive: true });
+  writeFileSync(targetAbs, body);
+  return { action: 'created' };
+}
+
+/**
+ * Generate wrappers for the selected platforms into targetDir (the client
+ * repo root — wrapper targets are root-relative conventional paths, NOT
+ * inside the seeded kit dir).
+ *
+ * @param {object} options
+ * @param {string} options.kitRoot   kit repo root (holds payload/ + cli/)
+ * @param {string} options.targetDir client repo root receiving the wrappers
+ * @param {string} [options.rootName] seeded kit dir name the pointers cite
+ * @param {string[]} [options.platforms] selected registry ids
+ * @param {string} [options.manifestPath] override, for tests
+ * @returns {Array<{ platform: string, name: string, target: string, mode: string,
+ *                   action: 'created'|'appended'|'replaced'|'skipped', reason?: string }>}
+ */
+export function generateWrappers({ kitRoot, targetDir, rootName = DEFAULT_ROOT, platforms = [], manifestPath }) {
+  validateRootName(rootName);
+  const manifest = loadManifest(kitRoot, manifestPath);
+  assertKnownPlatforms(manifest, platforms);
+  if (!existsSync(resolve(targetDir))) {
+    throw new Error(`target dir ${resolve(targetDir)} does not exist`);
+  }
+
+  const results = [];
+  for (const id of [...new Set(platforms)].sort()) {
+    const spec = manifest.platforms[id];
+    const templateAbs = resolve(manifest.payloadRoot, spec.template);
+    if (!existsSync(templateAbs)) {
+      throw new Error(`platforms.${id}: template ${spec.template} missing from payload/ — the registry and the payload tree have drifted`);
+    }
+    const body = renderTemplate(readFileSync(templateAbs, 'utf8'), rootName, spec.template);
+    const targetAbs = join(resolve(targetDir), spec.target);
+    const outcome = spec.mode === 'shared'
+      ? writeShared(targetAbs, body)
+      : writeDedicated(targetAbs, body, rootName);
+    results.push({ platform: id, name: spec.name, target: spec.target, mode: spec.mode, ...outcome });
+  }
+  return results;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "unknown-knowledge",
+  "version": "2.1.0",
+  "description": "Free OSS kit that stands up self-improving knowledge-base + ontology structures in any codebase: three governed YAML stores, a deterministic engine, and an agent protocol.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doterodesign/unknown-knowledge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/doterodesign/unknown-knowledge/issues"
+  },
+  "homepage": "https://github.com/doterodesign/unknown-knowledge#readme",
+  "type": "module",
+  "bin": {
+    "unknown-knowledge": "cli/init.js"
+  },
+  "files": [
+    "cli/",
+    "payload/",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.js\"",
+    "lint": "node scripts/lint.js",
+    "acceptance": "node acceptance/run.js"
+  },
+  "dependencies": {
+    "js-yaml": "^5.4.1"
+  }
+}

package/payload/adapter-fixtures/README.md

@@ -0,0 +1,53 @@
+# adapter-fixtures — the sample/expected pairs for format adapters
+
+One directory per format, each carrying a `sample.<ext>` document and the
+`EXPECTED.yaml` intermediate representation the adapter must produce from it.
+The shape is deliberately IDENTICAL to the extractor-kind pairs — sample plus
+expectation, pinned by kit CI — because these fixtures do the same double
+duty: they are the runnable gate, and they are the authoring template a client
+imitates when drafting an adapter for a format the kit does not ship (D-005:
+only vendored, versioned, test-covered code ever runs).
+
+Every sample is adversarial-but-adaptable on purpose: reflowed paragraphs,
+code whose indentation is content, entities, nested block elements, PDF
+kerning arrays and escapes. Gnarly input that stays INSIDE the envelope.
+Out-of-envelope shapes (a `.docx` submission, an encrypted PDF, a scanned page
+with no text) are NOT here: those hard-error by design, so there is no IR to
+expect from them.
+
+`EXPECTED.yaml` fields: `format` + `file` + `adapter` (the versioned name, e.g.
+`md@1`) + `hash` (FNV-1a over the sample's bytes) + `blocks`. Each block is
+`kind` + `text` + `locator`, plus `level` on headings.
+
+**Order is contract.** Extractor pairs compare value SETS (§3.5, order is
+presentation); adapter pairs compare an ORDERED SEQUENCE, because the IR
+preserves document order and everything downstream reads it that way.
+
+**Locators** are per-format, and each is deterministic:
+
+| format | locator | meaning |
+|--------|---------|---------|
+| md, txt, html | `{ line, endLine }` | 1-based inclusive lines in the sample |
+| pdf | `{ page, object }` | 1-based page ordinal, then text-operation ordinal within that page's content stream |
+
+A PDF has no lines to point at, so it gets the coordinates it actually has.
+
+## Authoring a new adapter
+
+1. Add a versioned entry to `ADAPTERS` in `engine/lib/format-adapters.js`: a
+   pure `adapt(source) -> Block[]`, lexical only — no client-code execution,
+   no subprocess, no network, no eval (D-014).
+2. Declare its envelope in the module doc comment, and make everything outside
+   that envelope a HARD ERROR that names what was encountered. Never a partial
+   parse: a document reported as covered when half of it was never read is the
+   false-all-clear failure class (D-005/D-012), and it is worse than no
+   coverage at all.
+3. Ship a pair here, and pin it in the kit's tests the way the shipped four
+   are pinned.
+
+**Versioning.** Bump an adapter's version when the same input would produce
+different IR bytes (a new block kind, a changed locator scheme, different
+splitting or ordering) — maps built under different versions are not
+comparable, and the version is what says so. Do not bump for a widened
+envelope that leaves previously-accepted input byte-identical. A bump updates
+the fixture pair in the same commit.

package/payload/adapter-fixtures/html/EXPECTED.yaml

@@ -0,0 +1,50 @@
+# Expected IR for sample.html — the html@1 adapter (UCS-1153).
+#
+# Locators are 1-based inclusive line numbers, derived from the byte offsets of
+# each element's open and close tags.
+#
+# What this pair pins: <script> and <style> bodies NEVER reach the IR (they are
+# code and presentation, and feeding CSS to a lexicon would manufacture matches
+# from selectors) — note that the sample's style block contains the word
+# "settled" and its script contains it too, yet neither appears below; inline
+# markup inside a block is stripped to text; the five XML entities decode
+# (&amp; -> &, &lt;not&gt; -> <not>); a <p> nested inside an <li> closes the
+# list item, so the item is emitted once, not twice; <pre> keeps its newlines;
+# and table cells are joined with the same " | " separator the md adapter uses,
+# so a table row means the same thing whatever format it arrived in.
+#
+# D-014: this adapter never executes anything. No DOM is built, no script runs,
+# no resource is fetched. The document is bytes.
+format: html
+file: sample.html
+adapter: html@1
+hash: fnv1a64:062e49c39e1bf5c1
+blocks:
+  - kind: heading
+    level: 1
+    text: Font licensing onboarding
+    locator: {line: 11, endLine: 11}
+  - kind: paragraph
+    text: The foundry must expose a CDN endpoint and a self-hosted fallback. Render budget is 400ms & measured end-to-end.
+    locator: {line: 13, endLine: 14}
+  - kind: list-item
+    text: CDN endpoint, TLS only
+    locator: {line: 22, endLine: 22}
+  - kind: paragraph
+    text: Self-hosted fallback for offline
+    locator: {line: 23, endLine: 23}
+  - kind: code
+    text: |-
+      foundry:
+        name: typeco
+        timeout-ms: 400
+    locator: {line: 26, endLine: 28}
+  - kind: table-row
+    text: Field | Meaning
+    locator: {line: 31, endLine: 31}
+  - kind: table-row
+    text: pending | license requested, <not> granted
+    locator: {line: 32, endLine: 32}
+  - kind: paragraph
+    text: Page the design-ops rotation when the CDN degrades for more than ninety seconds.
+    locator: {line: 35, endLine: 36}

package/payload/adapter-fixtures/html/sample.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <title>Font licensing onboarding</title>
+  <style>h1 { color: rebeccapurple; content: "granted"; }</style>
+</head>
+<body>
+  <!-- Adapter fixture — html. Adversarial-but-adaptable: script and style
+       bodies that must never reach the IR, inline markup inside blocks,
+       XML entities, a nested block element, and a table. -->
+  <h1>Font licensing onboarding</h1>
+
+  <p>The foundry must expose a <strong>CDN</strong> endpoint and a
+     self-hosted fallback. Render budget is 400ms &amp; measured end-to-end.</p>
+
+  <script>
+    // Executing this would be a D-014 violation. It is discarded as text.
+    document.title = "granted";
+  </script>
+
+  <ul>
+    <li>CDN endpoint, TLS only</li>
+    <li><p>Self-hosted fallback for offline</p></li>
+  </ul>
+
+  <pre>foundry:
+  name: typeco
+  timeout-ms: 400</pre>
+
+  <table>
+    <tr><th>Field</th><th>Meaning</th></tr>
+    <tr><td>pending</td><td>license requested, &lt;not&gt; granted</td></tr>
+  </table>
+
+  <blockquote>Page the design-ops rotation when the CDN degrades for more
+  than ninety seconds.</blockquote>
+</body>
+</html>

package/payload/adapter-fixtures/md/EXPECTED.yaml

@@ -0,0 +1,65 @@
+# Expected IR for sample.md — the md@1 adapter (UCS-1153).
+#
+# Ordered blocks with kinds and source locators. Order is CONTRACT here (unlike
+# the extractor pairs, whose values are sets): the IR preserves document order,
+# and a coverage map reads it that way. Locators are 1-based inclusive line
+# numbers into the ORIGINAL sample, so a reader can open the file at the line.
+#
+# What this pair pins beyond the happy path: a paragraph reflowed from three
+# source lines onto one block (its locator keeps the full span), fenced code
+# whose newlines and indentation SURVIVE (whitespace is semantic in code, so it
+# is never flattened), all three list markers, the table delimiter row dropped
+# as presentation, and the trailing hashes of a closed ATX heading stripped.
+format: md
+file: sample.md
+adapter: md@1
+hash: fnv1a64:261b6b2f06931422
+blocks:
+  - kind: heading
+    level: 1
+    text: Font licensing onboarding
+    locator: {line: 1, endLine: 1}
+  - kind: paragraph
+    text: 'Adapter fixture — markdown. Adversarial-but-adaptable on purpose: a paragraph wrapped across several source lines, a fenced code block whose indentation is content, both list markers, a table, and a heading with trailing hashes.'
+    locator: {line: 3, endLine: 5}
+  - kind: heading
+    level: 2
+    text: Foundry requirements
+    locator: {line: 7, endLine: 7}
+  - kind: paragraph
+    text: The foundry must expose a CDN endpoint and a self-hosted fallback. Render budget is four hundred milliseconds end-to-end, measured from request to paint.
+    locator: {line: 9, endLine: 11}
+  - kind: list-item
+    text: CDN endpoint, TLS only
+    locator: {line: 13, endLine: 13}
+  - kind: list-item
+    text: Self-hosted fallback for offline
+    locator: {line: 14, endLine: 14}
+  - kind: list-item
+    text: Trial license before production
+    locator: {line: 15, endLine: 15}
+  - kind: paragraph
+    text: 'Configuration lives in one block:'
+    locator: {line: 17, endLine: 17}
+  - kind: code
+    text: |-
+      foundry:
+        name: typeco
+        timeout-ms: 400
+    locator: {line: 19, endLine: 23}
+  - kind: table-row
+    text: Field | Meaning
+    locator: {line: 25, endLine: 25}
+  - kind: table-row
+    text: '`pending` | license requested, not granted'
+    locator: {line: 27, endLine: 27}
+  - kind: table-row
+    text: '`granted` | license final'
+    locator: {line: 28, endLine: 28}
+  - kind: heading
+    level: 3
+    text: Escalation
+    locator: {line: 30, endLine: 30}
+  - kind: paragraph
+    text: Page the design-ops rotation when the CDN degrades for more than ninety seconds.
+    locator: {line: 32, endLine: 32}

package/payload/adapter-fixtures/md/sample.md

@@ -0,0 +1,32 @@
+# Font licensing onboarding
+
+Adapter fixture — markdown. Adversarial-but-adaptable on purpose: a paragraph
+wrapped across several source lines, a fenced code block whose indentation is
+content, both list markers, a table, and a heading with trailing hashes.
+
+## Foundry requirements ##
+
+The foundry must expose a CDN endpoint and a self-hosted fallback. Render
+budget is four hundred milliseconds end-to-end, measured from request to
+paint.
+
+- CDN endpoint, TLS only
+* Self-hosted fallback for offline
+1. Trial license before production
+
+Configuration lives in one block:
+
+```yaml
+foundry:
+  name: typeco
+  timeout-ms: 400
+```
+
+| Field | Meaning |
+|-------|---------|
+| `pending` | license requested, not granted |
+| `granted` | license final |
+
+### Escalation
+
+Page the design-ops rotation when the CDN degrades for more than ninety seconds.

package/payload/adapter-fixtures/pdf/EXPECTED.yaml

@@ -0,0 +1,45 @@
+# Expected IR for sample.pdf — the pdf@1 adapter (UCS-1153).
+#
+# LOCATOR SCHEME differs from the text formats, because a PDF is not line-
+# addressable: { page, object } is the 1-based page ordinal in document order
+# plus the 1-based ordinal of the text-showing operation within that page's
+# content stream. Both derive from content-stream order, never from object
+# numbering or enumeration order, so they are stable for identical bytes.
+#
+# The sample is hand-crafted by scripts/make-pdf-fixture.js so this expectation
+# is genuinely reviewable rather than checked against an opaque binary. It
+# exercises exactly the pdf@1 envelope: page 1 is an UNCOMPRESSED stream using
+# Tj and a TJ kerning array (whose fragments join into one block), with an
+# escaped paren \( and an octal \050 both decoding to literal parens; page 2 is
+# a FLATEDECODE stream (inflated with node:zlib — stdlib decompression, never
+# execution) using the ' (next-line-and-show) operator and a hex <...> string.
+#
+# Every kind here is a paragraph: PDF has no paragraph or heading concept, and
+# clustering text by coordinates to invent one would be a guess. One text-
+# showing operation, one block, one locator.
+format: pdf
+file: sample.pdf
+adapter: pdf@1
+hash: fnv1a64:0a290a783b026774
+blocks:
+  - kind: paragraph
+    text: Font licensing onboarding
+    locator: {page: 1, object: 1}
+  - kind: paragraph
+    text: The foundry must expose a CDN endpoint and a self-hosted fallback.
+    locator: {page: 1, object: 2}
+  - kind: paragraph
+    text: Render budget is 400ms (end-to-end), measured from request to paint.
+    locator: {page: 1, object: 3}
+  - kind: paragraph
+    text: Pending (not granted) is a distinct state.
+    locator: {page: 1, object: 4}
+  - kind: paragraph
+    text: Escalation
+    locator: {page: 2, object: 1}
+  - kind: paragraph
+    text: Page the design-ops rotation when the CDN degrades for more than ninety seconds.
+    locator: {page: 2, object: 2}
+  - kind: paragraph
+    text: Foundry credentials are sandboxed.
+    locator: {page: 2, object: 3}

package/payload/adapter-fixtures/txt/EXPECTED.yaml

@@ -0,0 +1,31 @@
+# Expected IR for sample.txt — the txt@1 adapter (UCS-1153).
+#
+# Every block is a paragraph. That is the whole point of this pair: plain text
+# carries no marked-up structure, and the adapter INVENTS NONE. The sample
+# deliberately tempts a heuristic parser twice — a four-space-indented run that
+# a markdown adapter would call code, and an ALL-CAPS line that looks like a
+# heading — and both stay paragraphs. Guessed structure would put sections in a
+# coverage map that the document never had.
+format: txt
+file: sample.txt
+adapter: txt@1
+hash: fnv1a64:4c921cb8fa2f2059
+blocks:
+  - kind: paragraph
+    text: Font licensing onboarding
+    locator: {line: 1, endLine: 1}
+  - kind: paragraph
+    text: 'Adapter fixture — plain text. Plain text carries no marked-up structure, so every block is a paragraph: the adapter invents no headings and no code, and this sample is shaped to tempt it into doing both.'
+    locator: {line: 3, endLine: 5}
+  - kind: paragraph
+    text: This line is indented four spaces. A markdown adapter would call it code. The txt adapter calls it prose, because plain text has no code fences and guessing would manufacture structure the document never had.
+    locator: {line: 7, endLine: 9}
+  - kind: paragraph
+    text: FOUNDRY REQUIREMENTS
+    locator: {line: 11, endLine: 11}
+  - kind: paragraph
+    text: The line above is shouting, and a heuristic adapter would promote it to a heading. It stays a paragraph. Degraded structure, identical process — the coverage map is bounded by content richness, and this is the honest floor.
+    locator: {line: 13, endLine: 15}
+  - kind: paragraph
+    text: Render budget is four hundred milliseconds end-to-end, measured from request to paint.
+    locator: {line: 17, endLine: 18}

package/payload/adapter-fixtures/txt/sample.txt

@@ -0,0 +1,18 @@
+Font licensing onboarding
+
+Adapter fixture — plain text. Plain text carries no marked-up structure, so
+every block is a paragraph: the adapter invents no headings and no code, and
+this sample is shaped to tempt it into doing both.
+
+    This line is indented four spaces. A markdown adapter would call it code.
+    The txt adapter calls it prose, because plain text has no code fences and
+    guessing would manufacture structure the document never had.
+
+FOUNDRY REQUIREMENTS
+
+The line above is shouting, and a heuristic adapter would promote it to a
+heading. It stays a paragraph. Degraded structure, identical process — the
+coverage map is bounded by content richness, and this is the honest floor.
+
+Render budget is four hundred milliseconds end-to-end, measured from request
+to paint.

package/payload/docs/README.md

@@ -0,0 +1,102 @@
+# unknown-knowledge — this repo's knowledge base
+
+This directory was seeded once by the [unknown-knowledge](https://github.com/doterodesign/unknown-knowledge)
+kit and is now yours (D-001): three YAML stores that map the system
+(`ontology/`, `knowledge/`, `decisions/`), a deterministic engine that checks
+the map (`engine/`), and the agent protocol that runs the loop (`protocol/`).
+There is no service, no runtime, and no update channel — everything is files
+in this repo, branched and merged by your normal PRs.
+
+One idea governs everything here: **the map is never the fact.** Stores hold
+claims and pointers; your source files hold facts. The engine's job is to
+diff the two and say exactly where they disagree.
+
+> Commands run from the **repo root** with this directory at its default
+> name `unknown-knowledge/`; substitute your chosen name if it differs.
+
+## What you own vs. what was vendored
+
+Everything is client-owned after seeding; the zone map in
+`kit.manifest.yaml` records what an uninstall or audit needs to know — which
+paths arrived from the kit and which your own loop produced.
+
+| Zone | Paths | Meaning |
+|---|---|---|
+| seeded | `engine/`, `protocol/`, `schemas/`, `templates/`, `kit.manifest.yaml` | vendored at init: engine code, schemas, protocol markdown. Protocol conduct policy is explicitly yours to edit (see `docs/boundaries.md`) |
+| client | `ontology/`, `knowledge/`, `decisions/`, `logs/`, `survey-scope.yaml` | your team's data. The kit shipped only empty scaffolding here; everything else was written by your loop |
+
+## Running the gates
+
+The engine is plain Node (≥ 22, no build step) with one library
+dependency, `js-yaml`, resolved from your repo like any other package: if
+your repo does not already carry it, run `npm install --save-dev js-yaml`
+once.
+
+The blocking-grade checks all take `--root` as the **repo root** and share
+one exit-code contract: 0 = clean, 1 = findings/quarantines, 2 = the check
+never ran. **A check that never ran is a blocking defect, never a silent
+pass** — treat exit 2 as a stop, not a shrug.
+
+```
+node unknown-knowledge/engine/validate.js --root .          # structure: ids, refs, pointers
+node unknown-knowledge/engine/validate-values.js --root .   # enumerated values vs. source
+node unknown-knowledge/engine/preflight.js --root .         # store health + per-concept verdicts
+```
+
+`engine/audit.js` is different in kind — advisory (never blocking). It
+proposes draft concepts for anchors the map does not cover yet; a human
+reviews every draft. Run it on the steward cadence, never as a gate
+(`docs/steward-guide.md`).
+
+## How the loop works
+
+The runtime contract — `RESOLVE → PREFLIGHT → GATHER → ACT → RECORD` — lives
+in [`protocol/AGENTS.md`](protocol/AGENTS.md). That file is the single
+source of truth for how agents navigate the stores, what a verdict obliges,
+and when findings get appended; start every integration question there. The
+procedures live in the skills under `protocol/skills/`, referenced by name
+(D-019): `/knowledge-bootstrap` (first population), `/knowledge-reflect`
+(consolidating findings into reviewed fixes), `/kb-build` (cited knowledge
+writes), `/knowledge-audit` (the loop's heartbeat report).
+
+## Extractor fixtures and later stacks (D-009)
+
+Extractor fixtures for the stacks selected at init are included under
+`engine/tests`. If you adopt another stack later, you author your own pack
+from the included template (`templates/new-kind/`, plus the fixture
+authoring README seeded beside the packs) — there is no update channel. The
+governed path for teaching the engine a new anchor shape is
+`protocol/new-kind-pipeline.md`.
+
+## CI
+
+Session-level preflight is a sufficient gate for a small team, not for
+hundreds of engineers. At team scale, wire the validators into CI — copyable
+templates and the PR drift-attribution recipe are in
+[`docs/ci-wiring.md`](docs/ci-wiring.md). Init never wires CI for you
+(D-006).
+
+## Version stamp and license
+
+`kit-version` in `kit.manifest.yaml` records the kit version that seeded
+this directory — a birth certificate, not a dependency pin (D-021): it says
+which schema revision, extractor-kind set, and fixture vintage the seed was
+born with, and implies no update channel. The vendored code is Apache-2.0
+(D-020); the seeded `LICENSE` and `NOTICE` carry the terms and the
+attribution. Your stores and logs are your own content, not the kit's.
+
+## Uninstalling
+
+Delete this directory and remove the thin per-platform wrapper files init
+generated at their conventional paths (e.g. under `.claude/`) — that is the
+whole uninstall; nothing else in your repo belongs to the kit. Before you
+delete, mind the zone map above: `ontology/`, `knowledge/`, `decisions/`,
+`logs/`, and `survey-scope.yaml` are your team's data, and `logs/` in
+particular is the recorded history of where your map and your code
+disagreed — export what you want to keep first.
+
+## Further reading
+
+- [`docs/ci-wiring.md`](docs/ci-wiring.md) — CI templates + PR drift attribution (D-012)
+- [`docs/steward-guide.md`](docs/steward-guide.md) — the steward role, cadence, CODEOWNERS, hygiene recipes
+- [`docs/boundaries.md`](docs/boundaries.md) — what the kit guarantees, and what it will never catch