gcf-aif-ext 0.2.0

package/node_modules/cnlp-kit/README.md

@@ -0,0 +1,242 @@
+# CNLP-Kit
+
+**CNL-P** — *Controlled Natural Language for Prompts*. A format for documents an agent has to
+read precisely: agent skills, decision records, repository guides, review checklists, and the
+documentation of a library the agent writes code against. It replaces prose with `key:` blocks,
+so a reader stops inferring which sentence is intent, which is policy, and which is a step.
+
+This repository is the format itself — the standard, the profiles, and the checker that holds
+them — with no tie to any project, language or agent runtime.
+
+- **`cnlp-format.md`** — the standard. Read it first with `npx cnlp print format`; nothing else makes sense before it.
+- **`profiles/`** — one profile per kind of document. A profile declares values, never rules.
+- **`src/cnlp.js`** — the checker. Node builtins only, no dependencies.
+- **`bin/cnlp.js`** — the `cnlp` command.
+
+## Install it
+
+Node >= 22.14, and no runtime dependency of any kind — the checker is builtins only, which is what
+lets any repository run it.
+
+```
+npm i -g cnlp-kit      # cnlp on your PATH; the same line upgrades it
+npm i -D cnlp-kit      # a pinned version, for a repository whose CI runs the check
+```
+
+Take the global one to work on a repository you do not want to add a dependency to, and the
+dev-dependency wherever the check has to be reproducible. Both can hold at once: `npx cnlp` inside a
+project with the local install runs that version rather than the global one.
+
+## Use it
+
+Two commands. The first one installs **and** updates:
+
+```
+cnlp init      # config, profiles directory, and the skills for the agents you pick
+cnlp check     # holds every document the corpus names to its profile
+```
+
+`cnlp init` asks once which agents to write skills for — Claude Code, Codex — and remembers the
+answer in `cnlp.config.json`. Run it again after every upgrade of the package: the skills are
+versioned with the standard they teach, so `init` replaces every copy with the installed version.
+Nothing else about your config moves on that second run.
+
+- `--agents claude-code,codex` skips the menu, for a script.
+- With no terminal to draw a menu in — Git Bash under MinTTY, or CI — it repeats the choice the
+  config records, and installs for every agent when there is no config yet.
+- `cnlp check` reports skills left behind by an upgrade, and its exit code stays the corpus's own
+  answer: a stale copy is not a defect in a document.
+
+On the first run `cnlp init` also looks at what the repository already has — `AGENTS.md`,
+`CLAUDE.md`, `skills/*/SKILL.md`, `docs/adr/*.md`, `docs/references/*.md`, `docs/docsets/*/…` — and
+writes a corpus entry for each layout that matches a file, naming the count it found. Nothing is
+guessed from content: a decision record filed under `docs/references/` reads as a reference until
+you say otherwise. Edit the entries it wrote, or add your own:
+
+```json
+{
+  "profiles": "cnlp/profiles",
+  "corpus": [
+    { "profile": "skill",     "glob": "skills/*/SKILL.md" },
+    { "profile": "reference", "glob": "docs/references/*.md" },
+    { "profile": "guide",     "glob": "AGENTS.md" }
+  ]
+}
+```
+
+`profiles` is optional and names a directory of your own profiles. A profile there resolves
+**before** the packaged one of the same name, which is how a project adds its own vocabulary:
+copy `profiles/skill.md` into it and fill `custom_sections:`.
+
+`cnlp init` also prints the block to paste into `AGENTS.md`, `CLAUDE.md` or whatever file your
+agent reads. Three lines, and they are the rules no skill announces: an installed skill states
+its own task in its description, and a standing rule answers to no task description. It prints
+rather than writes: your agent file is yours.
+
+### Convert documentation you already have
+
+Run `cnlp init`, then the `cnlp-migrate` skill over the
+directory — `/cnlp-migrate docs/` in Claude Code, or read the body and follow it. It works on
+any kind of document, not one: it groups what it finds by kind, reads the packaged profile nearest
+each kind, and writes a new profile for a kind none of them fits — a new kind of document is one
+profile and no change to the checker.
+
+It does not start by rewriting. First it inventories the vocabulary your documents already use and
+fills `custom_sections:` in a **local** copy of each profile, so the format bends to your words
+before a single body moves. Then, per document, it lists the source's rules, rewrites the body, ticks
+each rule against the result, and names anything in the result that has no origin in the source.
+A contradiction it finds in the prose is reported, never resolved silently — that decision is yours.
+
+### Document a library or a framework
+
+Run the `cnlp-docset` skill against whatever you found, and name a directory to write into. The
+set is a folder of markdown and nothing else — **no config file, no dependency, no project around
+it** — and `cnlp check <dir>` reads it by path:
+
+```sh
+cnlp check ./nanoid-docset     # 12 file(s) conform
+```
+
+That is the producing side. **Adopting** a set is the other half and a separate act: a repository
+that will hold one among its own documents runs `cnlp init`, adds the `docsets` key and the four
+corpus entries shown under [Document sets](#document-sets), and checks it with everything else from
+then on.
+
+**Hand it any mix of sources.** A library arrives differently every time: a repository you can clone,
+a specification, a documentation site with no readable source, a pile of markdown someone collected,
+a vendor dump written for an agent. The skill ranks what you give it by what a source can prove —
+declarations first, then a machine-readable spec, then published prose, then the library's own
+examples, then a derived agent file — and takes each capability's contract from the strongest source
+that states it. What the set rests on lands in `identity:` `derived_from:`, so a reader can tell a
+page written from a signature from one written from prose, and the skill will not quietly write a
+prose claim as though it came from a declaration.
+
+It builds in the order that keeps a half-finished set honest: the closed catalog of every public
+capability first, every record at `status: source`, so the set itself says what has no page yet; then
+the type names of one running example; then `canonical_use:`, one whole working program in the index;
+then the concept, API and task pages. `cnlp check` resolves every reference and reports any page no
+other page reaches. `cnlp docs` is the single command you point your agent at.
+
+### The commands
+
+| | |
+|---|---|
+| `cnlp init [<dir>] [--agents <a,b>]` | install or update: config, profiles directory, skills for the agents you pick |
+| `cnlp check [<dir>] [--config <path>]` | hold every document to its profile: a directory read by path, or every corpus entry of the config. Exit non-zero on any issue |
+| `cnlp docs [<set>]` | write every document set's index, in reading order |
+| `cnlp print [<doc>] [--path]` | write the standard, or a profile, to stdout |
+| `cnlp scaffold <profile> <data.json>` | write a document from data, in the blocks and forms the profile declares |
+| `cnlp diff <profile> <doc> <data.json>` | report what moved between a document and a fresh read of its sources |
+
+## The ownership rule
+
+> The package owns the standard, the checker, the generic profiles **and the skills**.
+> The project owns its `cnlp.config.json`, its `custom_sections`, and any local profile.
+> **Nothing the project writes is ever overwritten.**
+
+The line falls between the two. A skill is generated from this package and versioned with the
+standard it teaches, so `cnlp init` replaces every installed copy on every run — editing a copy
+under `.claude/skills/` is editing a file the next upgrade discards. To change what the kit does in
+your project, edit a local profile or the config, which no command here ever rewrites: on a second
+run `init` touches only the `agents` key it wrote itself.
+
+This is the whole design. The format previously travelled as a zip of files copied into a
+target repository, where the corpus was configured by editing constants at the top of a file
+the next unpack would overwrite. One consumer got stranded 2 versions behind because upgrading
+meant a three-way merge. A package boundary is what makes upgrading a version bump.
+
+## The profiles that ship
+
+| Profile | The document it shapes |
+|---|---|
+| `profile` | a profile — the profile of a profile, checked against itself |
+| `skill` | an agent `SKILL.md` body |
+| `adr` | an architecture decision record |
+| `guide` | a repository guide such as `AGENTS.md` |
+| `reference` | a checklist or protocol a skill loads by path |
+| `docset` | the index of a library's documentation — one whole working program, and the closed list of what the library offers |
+| `concept` | one model the API pages of that library rest on |
+| `api` | one capability: its symbols, its contract, and one example |
+| `task` | one outcome in steps, with the example that composes several calls |
+
+The last four are one kind of document set: the documentation of one library, written so a
+reader loads a page at a time rather than a file that holds everything. See below.
+
+`skill`, `guide` and `reference` ship with `custom_sections: - none`: the vocabulary is yours,
+and the inventory step of `cnlp-migrate` is where it comes from. `adr` declares its own closed
+block list and no custom section, because an ADR block outside that list is prose looking
+for a home.
+
+Severity is the caller's. The checker returns issues; `cnlp check` treats every issue as an
+error. A project that gates on a lifecycle status — a warning while a decision is a draft, an
+error once it is accepted — applies that policy in its own validator, calling `bodyIssues`
+directly.
+
+## Document sets
+
+A **document set** is a directory of documents written to be read a page at a time, where one
+page sends the reader to another instead of restating it. §9 of the standard defines them: a
+page id is `<set>:<name>`, a bare name is local, a prefixed one crosses into another set, and
+`page:`, `by:` and `docset:` are the only forms a reference takes.
+
+The index is not a table of contents. It carries `canonical_use:` — one complete working
+program using every load-bearing element of the library — so the common case is written from
+the index with no other page open, and `walkthrough:` names the page owning each part of it.
+Its `catalog:` is the closed list: a capability with no page of its own keeps its line and says
+where to read the source instead, so a reader can always tell absence from omission.
+
+Point the config at them and §9 turns on:
+
+```json
+{
+  "docsets": "docs/docsets",
+  "corpus": [
+    { "profile": "docset",  "glob": "docs/docsets/*/index.md" },
+    { "profile": "concept", "glob": "docs/docsets/*/concepts/*.md" },
+    { "profile": "api",     "glob": "docs/docsets/*/api/*.md" },
+    { "profile": "task",    "glob": "docs/docsets/*/tasks/*.md" }
+  ]
+}
+```
+
+`docsets` names the directory whose immediate subdirectories are one set each. With the key
+present, `cnlp check` also resolves every reference, reports any that names no file, and
+reports any page no other page reaches. Without it a project has no document set and nothing
+about its run changes.
+
+`npx cnlp docs` writes the index of every set present, the overridden set first — so a library
+and the integration package that corrects it arrive together, and loading the second is not an
+action anyone can forget. That command is what a project points its agent at.
+
+Two worked sets live in `examples/`: a C# ECS framework and its engine integration.
+They are the corpus that proves the four profiles, they are checked by the same `cnlp check` as
+everything else, and they do not ship — `files:` in `package.json` names neither. `docs/DOCSETS.md`
+records why the design is what it is and which file holds each decision as a rule.
+
+## Without Node
+
+The checker is a convenience; the standard is the authority. A repository with no Node
+runtime holds its profiles by review against `cnlp-format.md` and sets `enforcement:`
+accordingly. Nothing else changes.
+
+## What is deliberately not here yet
+
+- **the half of an intra-block grammar that is a line *shape*.** `record_values:` closes a
+  record key to a vocabulary, which took the two rules that failed open — `status` and
+  `relation` — off this list. What a profile still cannot declare is the form of a line: the
+  canonical verb a step opens with, the keys a `status` implies, and §9's rule that a name
+  reaches exactly one page. Those want an `item_pattern:` key, and a project needing one today
+  writes a test of its own.
+- **a checker for three of §9's rules.** A fact stated on one page of a set is not restated on
+  another, a set has one running example, and a name routes to exactly one page. All three are
+  rules a review holds; §9 says so rather than implying the checker reaches them.
+- **a declarative severity policy.** Today `enforcement:` states the severity in prose and
+  nothing reads it.
+- **a language-neutral conformance corpus.** Until it exists, "any technology" means any
+  technology that can read the standard, not any technology that can check it.
+- **`profiles/plan.md`.** It is the acceptance test for the three above: if adding it costs
+  one file and no code change, the generalization held.
+
+`quality-rules.md` is a seed, not part of the standard: a rubric to prune and copy into the
+skills that carry one. It travels with a byte-identity test you write yourself — without that
+test the copies drift and the rubric stops being shared.

package/node_modules/cnlp-kit/bin/cnlp.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// cnlp — check a project's documents against their profiles, and print the documents that
+// ship here. `print` is how anything outside this package reaches the standard: it lives
+// inside node_modules, which is not a path a document can name and expect a reader to find.
+
+import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { PACKAGE_ROOT, recordDrift, renderBody, resolveDoc } from '../src/cnlp.js';
+import { AGENTS, CONFIG_NAME, STAMP_NAME, checkProject, configForPath, docsetsOf, findConfig, profileFor, proposeCorpus, readConfig, readingOrder, skillDrift, skillsDirFor } from '../src/config.js';
+
+const USAGE = `cnlp — the CNL-P checker
+
+  cnlp init [<dir>] [--agents <a,b>]   install or update this kit in a project
+  cnlp check [<dir>] [--config <path>] check a directory of documents, or every corpus entry
+  cnlp docs [<set>]                    write the index of every document set, or of one
+  cnlp print [<doc>] [--path]          write a shipped document to stdout, or its path
+  cnlp scaffold <profile> <data>       write a document from a JSON file, in the profile's shape
+  cnlp diff <profile> <doc> <data>     report what moved between a document and a fresh read
+
+  <doc> is "format" for the standard, or a profile name such as "skill".
+  <a,b> is a comma list of ${AGENTS.map((a) => a.value).join(', ')}.
+`;
+
+// The starter carries `docsets` because a key absent from it reads as a capability that does not
+// exist: a project would have to find §9 to learn that a document set is available at all. The
+// corpus here is the fallback: `init` writes what it found instead, when it found anything.
+const STARTER = {
+  profiles: 'cnlp/profiles',
+  docsets: 'docs/docsets',
+  corpus: [{ profile: 'skill', glob: 'skills/*/SKILL.md' }],
+};
+
+const VERSION = JSON.parse(await readFile(fileURLToPath(new URL('package.json', PACKAGE_ROOT)), 'utf8')).version;
+
+const argv = process.argv.slice(2);
+const VALUE_FLAGS = ['--config', '--agents', '--out'];
+const flag = (name) => argv.includes(name);
+const value = (name) => {
+  const at = argv.indexOf(name);
+  return at >= 0 ? argv[at + 1] : undefined;
+};
+const positional = argv.filter((a, i) => !a.startsWith('--') && !VALUE_FLAGS.includes(argv[i - 1]));
+
+const fail = (message) => {
+  console.error(message);
+  process.exit(1);
+};
+
+// A terminal menu, from node:readline and nothing else — a dependency here would be a dependency
+// in every repository that installs the kit. A run with no terminal to draw in gets no menu and no
+// prompt: the caller resolves the choice before asking, and this is never reached.
+function multiSelect(message, choices, checked) {
+  const selected = new Set(choices.map((c, i) => (checked.includes(c.value) ? i : -1)).filter((i) => i >= 0));
+  let cursor = 0;
+  const render = (first) => {
+    if (!first) process.stdout.write(`\x1b[${choices.length + 1}A`);
+    process.stdout.write(`\x1b[2K${message}\n`);
+    choices.forEach((c, i) => {
+      process.stdout.write(`\x1b[2K${i === cursor ? '>' : ' '} ${selected.has(i) ? '[x]' : '[ ]'} ${c.label}\n`);
+    });
+  };
+  readline.emitKeypressEvents(process.stdin);
+  process.stdin.setRawMode(true);
+  render(true);
+  return new Promise((resolve) => {
+    const done = (out) => {
+      process.stdin.removeListener('keypress', onKey);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      resolve(out);
+    };
+    const onKey = (_str, key) => {
+      if (!key) return;
+      if (key.name === 'up' || key.name === 'down') {
+        cursor = (cursor + (key.name === 'up' ? -1 : 1) + choices.length) % choices.length;
+        render(false);
+      } else if (key.name === 'space') {
+        if (selected.has(cursor)) selected.delete(cursor);
+        else selected.add(cursor);
+        render(false);
+      } else if (key.name === 'return') {
+        done(choices.filter((_, i) => selected.has(i)).map((c) => c.value));
+      } else if (key.ctrl && key.name === 'c') {
+        done([]);
+        process.exit(0);
+      }
+    };
+    process.stdin.on('keypress', onKey);
+  });
+}
+
+const [command] = positional;
+
+if (!command || flag('--help') || flag('-h')) {
+  console.log(USAGE);
+  // An asked-for usage is a success; a missing command is not.
+  process.exit(flag('--help') || flag('-h') ? 0 : 1);
+}
+
+if (command === 'check') {
+  // A path names what to check and needs no config: a document set produced for somebody else is
+  // a folder of markdown, and asking it to carry a config makes the tool homestead in its output.
+  const target = positional[1];
+  const configPath = target ? null : (value('--config') ?? findConfig());
+  if (!target && !configPath) {
+    fail(`no ${CONFIG_NAME} found here or above ${process.cwd()} — name a directory to check, or run \`cnlp init\` to write a config`);
+  }
+  let result;
+  let config;
+  try {
+    config = target ? await configForPath(target) : await readConfig(configPath);
+    result = await checkProject(config);
+  } catch (e) {
+    fail(e.message);
+  }
+  // Paths below are relative to a root the caller never named, so name it once.
+  if (target) console.log(`reading ${config.corpus.length} entr(ies) under ${config.root}`);
+  for (const { file, line, message } of result.issues) {
+    console.error(`${file}:${line}: ${message}`);
+  }
+  // A skill copy is versioned with the standard it teaches, so one left behind by an upgrade
+  // instructs an agent in rules this version changed. It is not a defect in a document the corpus
+  // names, so it reports and does not decide the exit code.
+  for (const { dir, held } of await skillDrift(config.root, config.agents, VERSION)) {
+    const from = held ? `are from ${held}` : 'carry no version';
+    console.error(`${path.relative(config.root, dir) || dir}: skills ${from}, this package is ${VERSION} — run \`cnlp init\``);
+  }
+  if (result.issues.length) {
+    fail(`\n${result.issues.length} issue(s) in ${result.checked.length} file(s)`);
+  }
+  console.log(`${result.checked.length} file(s) conform`);
+  process.exit(0);
+}
+
+// The entry point an agent is pointed at. It writes every active index in 1 run, so loading a
+// companion is not a second action anybody can forget: a companion states which pages of the set
+// it extends stop holding, and a reader who never loaded it writes against the wrong page.
+if (command === 'docs') {
+  const configPath = value('--config') ?? findConfig();
+  if (!configPath) {
+    fail(`no ${CONFIG_NAME} found here or above ${process.cwd()} — run \`cnlp init\` to write one`);
+  }
+  let sets;
+  let config;
+  try {
+    config = await readConfig(configPath);
+    sets = await docsetsOf(config);
+  } catch (e) {
+    fail(e.message);
+  }
+  const wanted = positional[1];
+  if (wanted && !sets.has(wanted)) {
+    fail(`no document set named ${JSON.stringify(wanted)} — this project carries ${[...sets.keys()].sort().join(', ') || 'none'}`);
+  }
+  const order = wanted ? [sets.get(wanted)] : readingOrder(sets);
+  if (order.length === 0) {
+    fail(`${config.docsets}/ holds no document set — a set is a subdirectory with an index.md`);
+  }
+  for (const set of order) {
+    process.stdout.write(`===== docset: ${set.name} (${set.index}) =====\n\n${set.raw}\n`);
+  }
+  process.exit(0);
+}
+
+if (command === 'print') {
+  const doc = positional[1] ?? 'format';
+  let abs;
+  try {
+    abs = resolveDoc(doc);
+  } catch (e) {
+    fail(e.message);
+  }
+  if (!existsSync(abs)) fail(`no such document: ${doc}`);
+  if (flag('--path')) console.log(abs);
+  else process.stdout.write(await readFile(abs, 'utf8'));
+  process.exit(0);
+}
+
+// The mechanical half of authoring: a profile already declares the block order and the form of
+// each one, so emitting a document from data needs no knowledge of what kind of document it is.
+// What it will not do is fill a block the data does not carry — `cnlp check` reporting that block
+// as missing is the list of what the author still owes, and a placeholder would hide it.
+async function profileAndData(name, dataPath) {
+  if (!existsSync(dataPath)) fail(`no such file: ${dataPath}`);
+  const configPath = value('--config') ?? findConfig();
+  let profilesDir = null;
+  if (configPath) {
+    try {
+      ({ profilesDir } = await readConfig(configPath));
+    } catch (e) {
+      fail(e.message);
+    }
+  }
+  try {
+    return { profile: await profileFor(name, profilesDir), data: JSON.parse(await readFile(dataPath, 'utf8')) };
+  } catch (e) {
+    return fail(`${dataPath}: ${e.message}`);
+  }
+}
+
+if (command === 'scaffold') {
+  const [, name, dataPath] = positional;
+  if (!name || !dataPath) fail('usage: cnlp scaffold <profile> <data.json> [--out <path>]');
+  const { profile, data } = await profileAndData(name, dataPath);
+  let out;
+  try {
+    out = renderBody(data, profile);
+  } catch (e) {
+    fail(`${dataPath}: ${e.message}`);
+  }
+  const target = value('--out');
+  if (target) {
+    await mkdir(path.dirname(path.resolve(target)), { recursive: true });
+    await writeFile(target, out);
+    console.log(`wrote ${target} — run \`cnlp check\` for the blocks it still owes`);
+  } else process.stdout.write(out);
+  process.exit(0);
+}
+
+// A document states what its sources said at 1 revision, and nothing in the document reports that
+// the sources moved. Re-read them, hand the fresh data here, and what changed is named rather than
+// left for a reader to hit. Audit and refresh are the same comparison: this reports, and the author
+// decides which pages to rewrite.
+if (command === 'diff') {
+  const [, name, docPath, dataPath] = positional;
+  if (!name || !docPath || !dataPath) fail('usage: cnlp diff <profile> <document.md> <data.json>');
+  if (!existsSync(docPath)) fail(`no such file: ${docPath}`);
+  const { profile, data } = await profileAndData(name, dataPath);
+  let drift;
+  try {
+    drift = recordDrift(await readFile(docPath, 'utf8'), data, profile);
+  } catch (e) {
+    fail(e.message);
+  }
+  for (const { block, id, change } of drift) console.error(`${docPath}: ${block}: ${id}: ${change}`);
+  if (drift.length === 0) console.log(`${docPath} matches what the sources state now`);
+  process.exit(drift.length === 0 ? 0 : 1);
+}
+
+// Install and update are 1 command, because a project wants neither half alone: a config with no
+// skills gives an agent no instructions, and skills with no config give the checker no corpus.
+if (command === 'init') {
+  const dir = path.resolve(positional[1] ?? '.');
+  const at = path.join(dir, CONFIG_NAME);
+  const existing = existsSync(at) ? JSON.parse(await readFile(at, 'utf8')) : null;
+
+  // First hit wins: the flag a script passes, then the menu, then the choice already recorded,
+  // then every agent. A run with no terminal never reaches the menu and never stops to ask.
+  const named = value('--agents')?.split(',').map((a) => a.trim()).filter(Boolean);
+  for (const a of named ?? []) {
+    if (!AGENTS.some((known) => known.value === a)) {
+      fail(`unknown agent ${JSON.stringify(a)} — this kit knows ${AGENTS.map((k) => k.value).join(', ')}`);
+    }
+  }
+  // A recorded empty list is a choice — "install for no agent" — and repeats like any other.
+  const recorded = Array.isArray(existing?.agents) ? existing.agents : null;
+  let agents = named;
+  if (!agents && process.stdin.isTTY) {
+    agents = await multiSelect('Install the skills for which agents? (up/down move, space toggles, enter confirms)', AGENTS, recorded ?? []);
+  }
+  if (!agents) agents = recorded ?? AGENTS.map((a) => a.value);
+
+  await mkdir(path.join(dir, 'cnlp', 'profiles'), { recursive: true });
+  // A project that deleted its docsets key deleted the directory with it; recreating it here
+  // would undo that choice on the very next update run.
+  const docsets = existing ? existing.docsets : STARTER.docsets;
+  if (docsets) await mkdir(path.join(dir, docsets), { recursive: true });
+
+  let exampleCorpus = false;
+  if (existing) {
+    // The corpus is the one thing the project owns here, so an update rewrites the agent list
+    // and nothing else. Rereading the layout would undo every glob its author edited.
+    await writeFile(at, `${JSON.stringify({ ...existing, agents }, null, 2)}\n`, 'utf8');
+    console.log(`updated  ${at}`);
+  } else {
+    // Read the layout before writing the corpus: a starter naming files a project does not have
+    // makes `cnlp check` fail on the first run, and the operator edits before ever seeing it pass.
+    const found = await proposeCorpus(dir);
+    const config = { ...STARTER, agents, corpus: found.length ? found.map(({ profile, glob }) => ({ profile, glob })) : STARTER.corpus };
+    await writeFile(at, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    for (const { profile, glob, files } of found) {
+      console.log(`found    ${String(files).padStart(3)} file(s) for "${profile}"  ${glob}`);
+    }
+    if (!found.length) {
+      exampleCorpus = true;
+      console.log('found    no document this kit already knows the layout of — the corpus written is an example to edit');
+    }
+    console.log(`written  ${at}`);
+  }
+
+  // A skill is generated from this package and versioned with the standard it teaches, so every
+  // copy is replaced on every run: a copy left behind teaches rules a later version changed. Edit
+  // a profile or the config to change what the kit does here, never a copied skill.
+  const from = fileURLToPath(new URL('skills/', PACKAGE_ROOT));
+  const skills = (await readdir(from)).sort();
+  for (const agent of agents) {
+    const to = skillsDirFor(dir, agent);
+    await mkdir(to, { recursive: true });
+    for (const name of skills) {
+      const target = path.join(to, name);
+      const action = existsSync(target) ? 'updated' : 'written';
+      await rm(target, { recursive: true, force: true });
+      await cp(path.join(from, name), target, { recursive: true });
+      console.log(`${action}  ${target}`);
+    }
+    await writeFile(path.join(to, STAMP_NAME), `${VERSION}\n`, 'utf8');
+  }
+  if (!agents.length) console.log('no agent selected — no skill installed');
+
+  // An example corpus names files this project does not have, and `cnlp check` refuses a glob
+  // matching no file — so the next step it prints is the edit, never a run that fails.
+  if (exampleCorpus) {
+    console.log(`\nNext: edit the corpus in ${CONFIG_NAME} to name your documents, then run \`cnlp check\`.`);
+  } else {
+    console.log('\nNext: run `cnlp check` to see where the corpus stands.');
+  }
+  console.log('Re-run `cnlp init` after every upgrade of this package: it is what brings the skill');
+  console.log('copies to the installed version.');
+  console.log('A project documenting no library deletes "docsets" and that directory.');
+  // Printed and not written: an agent file is a file the project owns, and its content is a
+  // decision about how that project's agent works. The operator pastes it where their agent reads.
+  // 3 lines and not 5: an installed skill announces its own task through its description, so the
+  // block states only what a skill cannot — a standing rule answers to no task description.
+  console.log(`\nPaste this into AGENTS.md, CLAUDE.md, or whatever file your agent reads:\n
+- the CNL-P standard is the authority on document form: read it with \`npx cnlp print format\`
+- run \`npx cnlp check\` before a commit that touches a document the corpus names
+- load a library's documentation with \`npx cnlp docs\`, which writes every set's index in reading order`);
+  process.exit(0);
+}
+
+fail(`unknown command ${JSON.stringify(command)}\n\n${USAGE}`);