gcf-aif-ext 0.5.1 → 0.5.2

package/README.md

@@ -50,6 +50,11 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
 
 On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
 
+### 0.5.2
+
+- Bundles `cnlp-kit` 3.9, so `gcf design check` and the commit gate accept a bullet written in Cyrillic alone.
+- With `cnlp-kit` 3.9 or later, the `AGENTS.md` block between `<!-- gcf:start -->` and `<!-- gcf:end -->` is a marked region that the project's guide profile does not shape: the `custom_sections` entries 0.5.1 asked for are no longer needed. Update the `cnlp-kit` your project runs `npx cnlp check` with.
+
 ### 0.5.1
 
 - A provenance record `assumed: q-NNN` must name a record still in `gcf/open-questions.md` (M9). A D2 record lives until its `until:` fires; once the human confirms the value, cite `answer: q-NNN` instead and remove it. After updating, run `ai-factory gcf design check`: every citation of a removed question blocks the commit gate until it is rewritten.

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/systems-doc.js

@@ -9,11 +9,15 @@ import { scalarIn } from './design.js';
 
 const NONE_LINE = '- none: no item of this subsystem has collapsed yet';
 
+/**
+ * The raw lines of a `key:` block. `prose`, not `lines`: cnlp-kit 3.9 blanks HTML comments in
+ * `lines`, and upsertBlock rewrites the block from these — a `gcf:allow` pragma must survive.
+ */
 export function blockLines(body, key) {
-  const { lines, sections } = parseBlocks(body);
+  const { prose, sections } = parseBlocks(body);
   const at = sections.find((s) => s.key === key);
 
-  return at ? itemsOf(lines, at.line).map((i) => i.text) : [];
+  return at ? itemsOf(prose, at.line).map((i) => i.text) : [];
 }
 
 /**

package/node_modules/cnlp-kit/CHANGELOG.md

@@ -4,6 +4,213 @@ The format has its own version from here on. It used to be stamped with the rele
 an ADR extension, which made a breaking change to the format invisible inside that project's
 patch release.
 
+## 3.9.1
+
+### Added
+
+- **`cnlp --version`** writes the version of the installed package, alone on 1 line, and exits 0.
+  Before it the only answer was `npm ls cnlp-kit`, and `--version` printed the usage and exited 1.
+
+## 3.9.0
+
+An agent file that several tools write into could not pass the check. Each tool keeps its own block
+between `<!-- <name>:start -->` and `<!-- <name>:end -->`, and `cnlp check` read the marker as an
+item of the block above it and the tool's keys as unknown blocks of the file. Neither the tool nor
+the project could fix that honestly: moving a marker moves the issue to another block, and naming a
+tool's keys in `custom_sections:` breaks §7, which keeps that block for content that is not a rule.
+
+### Changed
+
+- **§3: an HTML comment is markup, not structure.** A line that is 1 whole comment, and every line
+  of a comment that runs over several, is no item of the block above it and no section key. A line
+  carrying text beside a comment is still read, a comment that never closes hides nothing, and the
+  §4 and §5 line rules still read comment text, because an agent reads the raw file.
+- **§3: a marked region belongs to the tool that wrote it.** The lines between
+  `<!-- <name>:start -->` and `<!-- <name>:end -->` are not shaped by the file's profile: no key in
+  them is unknown, repeated or out of order, no heading in them is unknown, and nothing in them
+  supplies a block the profile requires. §4 and §5 still hold on every line. An end closes the
+  latest start of its own name; a start with no end marks nothing, so it cannot exempt the rest of
+  a file.
+- **`cnlp check` lists every region it did not shape**, by file, line range and name, the way it
+  lists the files the lexicon did not reach: a region is an exemption any author can write.
+- **A page reference inside a region is not resolved**, and does not reach a page. It belongs to
+  the tool's own corpus, not to this one.
+- **`parseBlocks` changed what it returns.** `lines`, which `itemsOf` and every structural check
+  read, now blanks comments and regions as well as fences. `prose` is new: it blanks fences only,
+  and the lexicon reads it. `regions` is new: `{ name, line, end }` for each marked region.
+
+### Fixed
+
+- **A reported line is a line of the file.** `parseBlocks` stripped the frontmatter, so every line
+  number in a document carrying one counted from the end of it: an issue on line 13 of a skill read
+  as line 10. The frontmatter is now blanked in place, so `<file>:<line>` opens the line it names.
+
+## 3.8.1
+
+2 things a consumer of a produced set ran into. A registry that keeps a pre-release as
+`2.0.0-[rc]` could not check it by path, and `identity:` `version:` had no stated shape, so the
+kit's own skill wrote `0.9.2, read at commit a741e91` where a tool comparing versions expects `0.9.2`.
+
+### Fixed
+
+- **`cnlp check <dir>` reads a set whose directory names carry `[`, `*` or `?`.** `configForPath`
+  put the directory names into the corpus glob as they were, so `2.0.0-[rc]` read as a character
+  class that matches no directory, and the set was reported as holding no document. Each name now
+  goes in as a glob matching only itself. A `{` still opens a brace set: `fs.glob` offers no escape
+  for it, and a set directory named with braces needs a config.
+
+### Changed
+
+- **`profiles/docset.md`: `version:` opens with the version alone.** The `identity:` note says so,
+  and why: a tool comparing the version reads it up to the first comma. Anything after that comma
+  stays a note for a reader, which is the shape `examples/dragonecs-unity` already has.
+- **`skills/cnlp-docset/SKILL.md`, step 4:** it records the version alone in `version:`, then a comma
+  and the revision, instead of leaving the 2 to be written in any order. An installed copy of the
+  skill reports as stale until `cnlp init` runs again.
+
+## 3.8.0
+
+A set that crosses into a companion could not be checked on its own. `configForPath(dir)` built a
+corpus of the 1 set it was pointed at, so `cnlp check examples/dragonecs-unity` reported 14
+references that resolve the moment both sets are read together, and a registry keeping sets as
+`<set>/<version>/` had no root holding both at all.
+
+### Added
+
+- **`configForPath(dir, { name, companions })`.** `name` names the checked set when its directory
+  does not; `companions` is a list of `{ name, dir }`, each a set whose pages resolve references and
+  whose files are never checked. The returned config always carries `companions` (absolute dirs,
+  `[]` when none) and `rename`, so a caller detects a kit that ignores the option by the field's
+  absence. A name that is empty or carries `:`, `/` or `\`, a companion with no `index.md`, a
+  companion named like the checked set or named twice, a companion that is the checked set's own
+  directory, and either option on a directory that is not 1 set each fail with the fix. The checked
+  directory is read by its spelling on disk, so a path typed in another case does not read the set
+  as its own sibling.
+- **`cnlp check <dir> --name <set> --companion <set>=<dir>`.** `--companion` repeats and splits at
+  its first `=`. Each companion prints `resolving against <name> at <dir>`: a caller passing
+  companions detects an executable older than 3.8.0 by that line's absence, so its wording is kept
+  stable. Both flags fail with a config run, which already reads every set under its root, and in
+  the `--flag=value` form, which would otherwise be ignored and print no `resolving` line. A value
+  flag followed directly by another flag now reads as having no value, for every value flag.
+- **`linkIssues(docs, docsets, { context, rename })` and `setSizes(docs, docsets, rename)`.** A
+  companion's pages resolve a `page:` or `by:` value, its name resolves a `docset:` value, and its
+  references count toward reach; its own references and its unreached pages are never reported,
+  and it is in no count. A call with 2
+  arguments behaves as before.
+
+### Changed
+
+- **A set checked by path resolves against the sets beside it.** When `<dir>` holds an `index.md`
+  and its name is the directory's name, every sibling directory holding an `index.md` joins as a
+  companion. `cnlp check <set>` and `configForPath(<set>)` report fewer issues where a sibling answers
+  a reference; `cnlp check examples/dragonecs-unity` and `examples/dragonecs` both conform now. An
+  explicit companion of the same name wins over a sibling.
+- **`cnlp check <dir>` prints its `reading` line before the check runs**, with the `resolving` lines
+  after it, so a check that throws still says what it was reading.
+- **`cnlp-format.md` §9** says a directory checked by path reaches the reference rules with no
+  config, and that a set checked on its own resolves against its companions.
+- **`skills/cnlp-docset/SKILL.md`**: a new step 16 names the sets a crossing reaches that do not sit
+  beside the output directory, and step 17 passes each as `--companion`. The old steps 16 to 19 are
+  17 to 20. An installed copy of the skill reports as stale until `cnlp init` runs again.
+
+## 3.7.0
+
+The upgrade path reached the skills and nothing else. A project holds 2 more copies of what this
+package declares — a local profile, and the block `cnlp init` prints for an agent file — and both
+are files the project owns, so neither can be overwritten on an upgrade. They are reported instead.
+
+### Added
+
+- **`cnlp check` names a local profile the packaged one has outgrown.** `profileDrift` in
+  `src/config.js` reads the copy and the packaged profile of the same name and reports what the
+  package declares and the copy does not: a section, its form, a record key, a required block, a
+  heading, a frontmatter field, the mood. What a copy adds is the vocabulary it was copied for and
+  is never reported, so a filled `custom_sections:` stays silent. Until now `profileFor` preferred
+  the copy and said nothing about its age: a profile copied at 3.1 held the corpus to a declaration
+  3 versions old, and the run reported it conformant.
+- **`cnlp check` names an agent file carrying an earlier copy of the pasted block.** The block is 1
+  value now — `AGENT_BLOCK` in `src/config.js` — read by the `init` that prints it and by the check
+  that watches it. `agentBlockDrift` reads `AGENTS.md` and `CLAUDE.md` at the project root and finds
+  the copy by its own opening bullet, the one naming `npx cnlp print format`. A file that never took
+  the block stays silent. It answers half of `docs/BACKLOG.md` item 9: the copy is watched, writing
+  it is still open.
+
+Both are reports and not issues, like the stale-skill line: a copy the project owns is not a defect
+in a document the corpus names, and neither decides the exit code.
+
+## 3.6.0
+
+A bug report from a project writing its corpus in Russian. The item rule read an ASCII letter, so
+every bullet of every non-Latin script reported as an item carrying no word, and the fix is 1
+character class. What the report turned up behind it is the release: the checker was answering
+`conform` over a corpus half of §5 never touched.
+
+### Fixed
+
+- **An item states its claim in a letter of any script.** `§5`'s "the item carries no word" rule read
+  `/[a-z]/i`, which reports every bullet written in Cyrillic, Greek, Hebrew or a CJK script and
+  passes the moment the line names a Latin identifier. It reads `/\p{L}/u` now. What the rule was
+  written for — `- 4`, `- —`, `- ...`, the residue of a mechanical split — is rejected unchanged,
+  because a digit and a punctuation mark are letters in no script.
+
+### Added
+
+- **`cnlp check` names the files the §5 word rules did not reach.** Every word list in §5 — the deny
+  list, the spelled thresholds, the open limits, the comparatives, the light verbs, the passive — is
+  English. Against a body in another script they raise no false issue; they silently match nothing,
+  which made a run report a conformant corpus over rules that never ran. `lexiconApplies` in
+  `src/cnlp.js` decides it from the prose — the line with its section key, its heading marker and its
+  quoted spans taken off, so this format's own English vocabulary and a Latin identifier do not
+  count as English prose — and `bin/cnlp.js` prints the count and the paths. It is a report and not
+  an issue: nothing in such a file is wrong, and the exit code does not change.
+
+### Changed
+
+- **`§5` states that its word rules are English**, which rules still hold for a document in another
+  script — §3 block forms, §4 line rules, quoted text — and that the checker reports the coverage it
+  lost rather than staying silent about it.
+
+## 3.5.0
+
+The first release shaped by a measurement rather than by a reading. `docs/PROBE-behaviour.md` holds
+the run: 4 arms, 14 tasks, 5 repetitions, against a falsifier committed before the first cell. A
+document set halved the wrong-call rate against the library's own documentation, 7% against 16%, and
+beat an arm carrying all 19 documentation pages and the whole declaration surface in context — 3.3
+times the tokens for more wrong calls, not fewer.
+
+Nothing here changes the standard or a checker rule. The run produced 1 loss and 1 cost, and each
+gets the smallest answer that fits it.
+
+The cost: a set is dearer per question than the documentation it replaces, 22172 tokens a call
+against 19236, and the difference is the index. A reader loads the index to answer any question and
+a page to answer 1, so those are different kinds of cost, and nothing in the kit made the split
+visible to whoever was growing one of them.
+
+The loss: on 1 task of 14 the set scored worse than the prose. The task wanted the `Scene` value a
+load returned; the set documents the manager's lookup members in full, because `catalog:` is closed
+and they are part of the library, and the agent went looking a scene up instead. A task page's
+preference lost to an API page's completeness, and nothing ranks them. That is `docs/BACKLOG.md`
+item 10, left open on purpose: 1 task in 1 set does not buy a vocabulary.
+
+### Added
+
+- **`cnlp check` reports each set's index bytes against its page bytes**, as
+  `<set>: index N B fixed, M page(s) K B on demand`. `checkProject` computes it from the documents
+  it has already read, so the report costs no second read, and `bin/cnlp.js` prints it. It is a
+  report and not a rule: the numbers say nothing about what a set may weigh.
+- **A step in `skills/cnlp-docset/SKILL.md`** for the 1 rule the run turned up that no check reaches:
+  a member a task page steers a reader away from carries that in its own `pitfalls:`. Step 18; the
+  old step 18 is 19.
+
+### Changed
+
+- **`profiles/docset.md` `read_protocol:` states what the index costs.** The index is the cost of
+  every question and a page the cost of 1. It is a value rather than a rule, so it sits in the
+  profile, and §6 keeps it in exactly 1 note.
+- **`docs/DOCSETS.md` carries what the probe measured about behaviour**, including the result the
+  totals hide: both reading arms averaged 4.4 turns, and on the task whose contract no documentation
+  page carries, the documentation arm read *more* than anywhere else and still failed every run.
+
 ## 3.4.1
 
 A record-list of multi-key records read as a wall. The only boundary between 2 records was a line

package/node_modules/cnlp-kit/README.md

@@ -46,6 +46,9 @@ Nothing else about your config moves on that second run.
   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.
+- **An upgrade reaches the skills and nothing else, because nothing else is the package's to
+  rewrite.** A local profile and the pasted agent-file block are files you own, so `cnlp check`
+  reports what each one is missing against the installed version and leaves both where they are.
 
 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
@@ -66,7 +69,11 @@ you say otherwise. Edit the entries it wrote, or add your own:
 
 `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:`.
+copy `profiles/skill.md` into it and fill `custom_sections:`. The copy is yours and no command
+here rewrites it, so `cnlp check` names what the packaged profile declares and the copy does not
+— a section, a form, a record key, a required block — which is how an upgrade reaches a file it
+must not overwrite. What the copy adds is the vocabulary it was copied for, and is never
+reported.
 
 `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
@@ -94,9 +101,27 @@ set is a folder of markdown and nothing else — **no config file, no dependency
 it** — and `cnlp check <dir>` reads it by path:
 
 ```sh
-cnlp check ./nanoid-docset     # 12 file(s) conform
+cnlp check ./nanoid-docset
+# 12 file(s) conform
+# nanoid-docset: index 5603 B fixed, 11 page(s) 25778 B on demand
 ```
 
+The 2 sizes are reported apart because they are different costs. A reader loads the index to answer
+any question and a page to answer 1, so an index that grows is paid on every question.
+
+**Checking 1 set of a pair.** A set that extends another names it in `companions:` or `overrides:`,
+and its references cross into it. Checked by path, a set resolves those against the sets beside it,
+so `cnlp check examples/dragonecs-unity` conforms on its own. A companion kept elsewhere is named,
+and a set whose directory is a version rather than its name is named too:
+
+```sh
+cnlp check docsets/dragonecs-unity/0.9.2 --name dragonecs-unity --companion dragonecs=docsets/dragonecs/1.1.17
+# reading 4 entr(ies) under …/docsets
+# resolving against dragonecs at …/docsets/dragonecs/1.1.17
+```
+
+A companion is read to resolve a reference and never checked: its own defects are not this run's.
+
 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
@@ -111,6 +136,10 @@ that states it. What the set rests on lands in `identity:` `derived_from:`, so 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.
 
+`identity:` `version:` opens with the version alone, and the revision the pages were read at follows
+a comma — `version: 0.9.2, read at commit a741e91`. A tool that compares the set against the version
+a project resolves, such as a registry or a version-guard test, reads up to that first comma.
+
 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;
@@ -122,11 +151,12 @@ other page reaches. `cnlp docs` is the single command you point your agent at.
 | | |
 |---|---|
 | `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 check [<dir>] [--config <path>] [--name <set>] [--companion <set>=<dir>]` | hold every document to its profile: a directory read by path, or every corpus entry of the config. A set read by path resolves its references against the sets beside it and the companions you name. Reports each set's index bytes against its page bytes, names any file the §5 word rules did not reach and any marked region its profile did not shape, and names a local profile or a pasted agent-file block left behind by an upgrade. 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 |
+| `cnlp --version` | write the version of the installed package, alone on 1 line |
 
 ## The ownership rule
 
@@ -167,6 +197,13 @@ and the inventory step of `cnlp-migrate` is where it comes from. `adr` declares
 block list and no custom section, because an ADR block outside that list is prose looking
 for a home.
 
+The §5 word rules are English — the deny list, the spelled thresholds, the open limits, the
+comparatives, the light verbs, the passive are lists of English words. A document written in
+another script matches none of them, so it is held to the rules that read shape — block forms,
+line rules, quoted text — and `cnlp check` names it rather than reporting a corpus as conformant
+against rules that never ran. The check reads script and not language, so a Latin-script document
+in another language still reads as English to it.
+
 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`

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

@@ -9,16 +9,19 @@ 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';
+import { AGENTS, AGENT_BLOCK, CONFIG_NAME, STAMP_NAME, agentBlockDrift, checkProject, configForPath, docsetsOf, findConfig, profileDrift, 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
+             [--name <set>] [--companion <set>=<dir>]...
+                                       name the set <dir> holds, and the sets it crosses into
   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
+  cnlp --version                       write the version of this package
 
   <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(', ')}.
@@ -36,12 +39,18 @@ const STARTER = {
 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 VALUE_FLAGS = ['--config', '--agents', '--out', '--name', '--companion'];
 const flag = (name) => argv.includes(name);
 const value = (name) => {
   const at = argv.indexOf(name);
-  return at >= 0 ? argv[at + 1] : undefined;
+  return at >= 0 ? valueAt(at + 1) : undefined;
 };
+// A flag right after a flag is no value: `--name --companion x=y` would name the set `--companion`.
+function valueAt(i) {
+  return argv[i]?.startsWith('--') ? undefined : argv[i];
+}
+// A flag that repeats: `value` returns the first occurrence only.
+const values = (name) => argv.flatMap((a, i) => (a === name ? [valueAt(i + 1)] : []));
 const positional = argv.filter((a, i) => !a.startsWith('--') && !VALUE_FLAGS.includes(argv[i - 1]));
 
 const fail = (message) => {
@@ -94,6 +103,12 @@ function multiSelect(message, choices, checked) {
 
 const [command] = positional;
 
+// The version alone on stdout, so a script compares it without parsing a sentence.
+if (flag('--version')) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
 if (!command || flag('--help') || flag('-h')) {
   console.log(USAGE);
   // An asked-for usage is a success; a missing command is not.
@@ -108,16 +123,39 @@ if (command === 'check') {
   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`);
   }
+  const name = value('--name');
+  const companionUsage = 'usage: cnlp check <dir> [--name <set>] [--companion <set>=<dir>]...';
+  // `--companion=a=b` read as no flag at all would print no `resolving` line, which a caller reads
+  // as an executable older than 3.8.0: refuse the form instead of ignoring it.
+  if ((flag('--name') && !name) || argv.some((a) => /^--(name|companion)=/.test(a))) fail(companionUsage);
+  // The first `=` splits the value, so a dir may carry `=` and a Windows drive letter.
+  const companions = values('--companion').map((v) => {
+    const cut = v?.indexOf('=') ?? -1;
+    if (cut <= 0 || cut === v.length - 1) fail(`--companion ${v ?? ''}: expected <set>=<dir>
+${companionUsage}`);
+    return { name: v.slice(0, cut), dir: v.slice(cut + 1) };
+  });
+  if (!target && (flag('--name') || companions.length)) {
+    fail('--name and --companion apply to a <dir>: a config run already reads every set under its root');
+  }
   let result;
   let config;
   try {
-    config = target ? await configForPath(target) : await readConfig(configPath);
-    result = await checkProject(config);
+    config = target ? await configForPath(target, { name, companions }) : await readConfig(configPath);
   } catch (e) {
     fail(e.message);
   }
-  // Paths below are relative to a root the caller never named, so name it once.
+  // Paths below are relative to a root the caller never named, so name it once. Printed before the
+  // check runs, so a caller seeing no `resolving` line concludes an old executable, not a crash.
   if (target) console.log(`reading ${config.corpus.length} entr(ies) under ${config.root}`);
+  // The wording is a contract: a caller passing companions detects an executable older than 3.8.0
+  // by this line's absence. Keep it stable.
+  for (const c of config.companions ?? []) console.log(`resolving against ${c.name} at ${c.dir}`);
+  try {
+    result = await checkProject(config);
+  } catch (e) {
+    fail(e.message);
+  }
   for (const { file, line, message } of result.issues) {
     console.error(`${file}:${line}: ${message}`);
   }
@@ -128,10 +166,35 @@ if (command === 'check') {
     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\``);
   }
+  // A copied profile and a pasted agent block are the 2 artifacts an upgrade cannot reach: the
+  // project owns both, so neither is overwritten and both are reported. Like a stale skill, a copy
+  // left behind is not a defect in a document the corpus names, and it decides no exit code.
+  for (const { file, profile, missing } of await profileDrift(config)) {
+    console.error(`${file}: the packaged ${profile} profile declares ${missing.join(', ')}, which this copy does not — compare them with \`npx cnlp print ${profile} --path\``);
+  }
+  for (const name of await agentBlockDrift(config.root)) {
+    console.error(`${name}: carries an earlier copy of the block \`cnlp init\` prints — paste the block that run ends with`);
+  }
+  // Every word list in §5 is English, so a body in another script matches none of them. Reporting
+  // which files the lexicon never reached is the difference between a partial check and a check
+  // that claims to be whole.
+  if (result.foreign.length) {
+    console.log(`${result.foreign.length} file(s) carry no English prose — the §5 word rules (deny list, thresholds, limits, comparatives, nominalizations, passive) did not apply to them`);
+    for (const rel of result.foreign) console.log(`  ${rel}`);
+  }
+  if (result.regions.length) {
+    console.log(`${result.regions.length} marked region(s) the file's profile did not shape — the §4 and §5 line rules read them`);
+    for (const r of result.regions) console.log(`  ${r.file}:${r.line}-${r.end}: ${r.name}`);
+  }
   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`);
+  // A reader loads the index to answer any question and a page to answer 1, so an author sees
+  // which of the 2 they are growing. `profiles/docset.md` states why they are different costs.
+  for (const set of result.sets) {
+    console.log(`${set.name}: index ${set.indexBytes} B fixed, ${set.pages} page(s) ${set.pageBytes} B on demand`);
+  }
   process.exit(0);
 }
 
@@ -324,10 +387,8 @@ if (command === 'init') {
   // 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`);
+  console.log(`\nPaste this into AGENTS.md, CLAUDE.md, or whatever file your agent reads:\n`);
+  console.log(AGENT_BLOCK.join('\n'));
   process.exit(0);
 }
 

package/node_modules/cnlp-kit/cnlp-format.md

@@ -124,6 +124,22 @@ never carries sub-bullets to hold a second thought — that is two bullets.
 document, not CNL-P sections. Anything reading this format skips fenced regions before
 looking for section keys.
 
+**An HTML comment is markup, not structure.** A line that is 1 whole `<!-- … -->` comment, and
+every line of a comment opening a line and running over several, is not an item of the block above
+it and not a section key. A line carrying text beside a comment carries that text, and is read. A
+comment that never closes hides nothing, because it would otherwise hide the rest of the file. §4
+and §5 still read comment text: the rendered file hides it, and an agent reads the raw file.
+
+**A marked region belongs to the tool that wrote it.** A file several tools write into gives each
+tool its own lines between `<!-- <name>:start -->` and `<!-- <name>:end -->`, so the tool finds and
+rewrites its own block and leaves the rest alone. `<name>` is ASCII letters, digits, `_`, `.` and
+`-`. The file's profile does not shape a region: its keys and headings are not the file's blocks, so
+none of them is unknown, repeated or out of order, and nothing in it supplies a block the profile
+requires. §4 and §5 still hold on every line of it — a region is exempt from the file's shape, not
+from its language. An end closes the latest start of its own name. A start with no end marks
+nothing, because it would otherwise exempt the rest of the file. The checker lists every region it
+did not shape, because a region is an exemption any author can write.
+
 **An empty block.** A required block with nothing in it carries `- none` and the reason:
 `- none: no alternative was viable at this scale`. That single line is the whole content and
 replaces the form the block would otherwise take, so a record-list or a keyed-block says it
@@ -166,6 +182,14 @@ A block whose content is a fenced region is not empty — the fence is opaque, n
 - A short concrete verb over an abstract one.
 - Define a specialized term once, then reuse it verbatim.
 
+**The word rules are English, and a check says when they did not run.** The 7 bullets above hold
+in any language. Every table and every list below is a list of English words — the deny-list, the
+spelled thresholds, the open limits, the comparatives, the light verbs, the passive — so a body
+written in another script matches none of them and is held only to the rules that read shape:
+§3 block forms, §4 line rules, and the quoted-text rule below. The checker reports every such file
+by name, because a corpus reported as conformant against rules that never ran is worse than a
+corpus nobody checked.
+
 **`check the corpus` and `run the check` are 2 terms.** One term per concept fixes which word names a
 thing; one part of speech fixes which job that word does — here the action, and the program that
 performs the action. Keep the part of speech the term already carries and rename the other use:
@@ -443,9 +467,18 @@ The rules a checker holds:
 - every document except a set's `index` is the target of at least 1 reference. A page nothing
   reaches is a page nobody reads, and it goes stale unobserved.
 
-**The checker reads this only when a project says where its sets live**, with a `docsets` key in
-`cnlp.config.json` naming the directory whose immediate subdirectories are one set each. A project
-with no such key has no document set, and none of this applies to it.
+**The checker reads this only where it knows a set lives**: a project names the directory whose
+immediate subdirectories are one set each with a `docsets` key in `cnlp.config.json`, and a
+directory checked by path is a set, or the root of several, by the `index.md` it holds. A project
+with no such key and no such directory has no document set, and none of this applies to it.
+
+**A set checked on its own resolves its crossings against its companions**: the sets the caller
+names, and the sets beside it. A reference into `toolkit` from a set that extends it resolves
+when `toolkit` is a companion. A companion is read to resolve a reference and is never checked: a
+reference inside it is not reported, and a page of it nothing reaches is not reported, but a
+reference from it into the checked set counts as reaching that page. The sets beside a set join
+only when its name is the name of its directory; a set named apart from its directory sits in a
+layout whose neighbours are not sets, and the caller names every companion.
 
 The rules a review holds. They are the same kind of rule as the four above and no checker reaches
 them, the way §5 splits the enforced half of a limit from the reviewed half:

package/node_modules/cnlp-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cnlp-kit",
-  "version": "3.4.1",
+  "version": "3.9.1",
   "description": "CNL-P — a format for documents an agent has to read precisely. The standard, its profiles, and the checker that holds them.",
   "type": "module",
   "license": "MIT",

package/node_modules/cnlp-kit/profiles/docset.md

@@ -1,103 +1,103 @@
----
-name: docset
-description: The CNL-P profile of a docset index — the entry page of a library's agent documentation, and the closed list of what that library offers.
----
-
-format: cnlp-format.md
-
-mood: imperative
-
-headings:
-- none: an index is one flat run of blocks, and the file name carries the title
-
-frontmatter_fields:
-- none: an index is read by path, so it carries no routing contract to restate
-
-lexicon_exempt:
-- none: an index has no frontmatter, so nothing is exempt
-
-sections:
-- key: identity
-  form: keyed-block
-  required: yes
-  record_keys: library, version, source
-  optional_record_keys: derived_from
-  note: the library covered and the revision it was read at; derived_from names what the pages were written from, because a page written from prose carries less weight than one written from a signature
-
-- key: purpose
-  form: bullet-list
-  required: yes
-  note: what the library does, and the kind of task a reader reaches for it with
-
-- key: read_protocol
-  form: numbered-list
-  required: yes
-  note: how to walk this docset: the common case is written from `canonical_use:`, a page opens for any call whose contract the reader lacks, and a step telling the reader to stop reading is the defect
-
-- key: install
-  form: bullet-list
-  required: no
-  note: how a project takes the dependency; delete the block when the docset covers a dependency the project already carries
-
-- key: canonical_use
-  form: keyed-block
-  required: yes
-  record_keys: shows
-  note: 1 complete working use of the library, carrying every load-bearing element; a reader holding only the index writes the common case from this block, and an index without one is a table of contents, which is enough for nothing
-
-- key: walkthrough
-  form: record-list
-  required: yes
-  record_keys: part, page
-  note: each part of `canonical_use:` and the page owning its detail; a record and not a comment inside the fence, because a fence is opaque and a link inside one reaches no reader and no check
-
-- key: concepts
-  form: record-list
-  required: yes
-  record_keys: page, does
-  note: the models a reader holds before any page reads correctly; a record and not a line, so every link in a docset is a `page:` value and a resolver guesses at none of them
-
-- key: tasks
-  form: record-list
-  required: yes
-  record_keys: page, does
-  note: the goals a reader arrives with; a catalog keyed on capability routes a reader holding a symbol and leaves one holding a goal to guess
-
-- key: catalog
-  form: record-list
-  required: yes
-  record_keys: capability, does, status
-  optional_record_keys: page, read, instead, fingerprint
-  record_values: status = covered, source, avoid
-  note: "every capability the library offers, in 1 record each; status is covered, source or avoid, and a symbol absent here is a symbol the library lacks; fingerprint changes when the source does, so a record without one cannot report drift"
-
-- key: excluded
-  form: bullet-list
-  required: yes
-  note: a whole region the docset leaves out, with the reason; a region named in neither this block nor the catalog reads as an omission nobody decided
-
-- key: companions
-  form: record-list
-  required: yes
-  record_keys: docset, when, owns
-  note: another docset covering what this library does not; `when:` is "always" once its index carries `overrides:`, since a reader loading it on demand misses the correction; "- none" when the library stands alone
-
-- key: overrides
-  form: record-list
-  required: no
-  record_keys: page, by, reason
-  note: "a page of another docset that stops holding once this package is present, and the page here that replaces it; `page:` names the foreign page and carries its docset prefix, `by:` names the local one and carries none"
-
-- key: version_notes
-  form: bullet-list
-  required: no
-  note: what changed in the covered version, for a reader arriving from an older one
-
-custom_sections:
-- none: a project fills this from the vocabulary its own docsets already use
-
-enforcement:
-- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
-- any issue is an error: an index routes every other page, so a wrong index misroutes the whole docset
-- `npx cnlp check` resolves every `page:`, `by:` and `docset:` value once the project declares `docsets:`
-- `npx cnlp check` holds `status` to covered, source and avoid; what a status implies — a `read:` on source, an `instead:` on avoid — is caught by review
+---
+name: docset
+description: The CNL-P profile of a docset index — the entry page of a library's agent documentation, and the closed list of what that library offers.
+---
+
+format: cnlp-format.md
+
+mood: imperative
+
+headings:
+- none: an index is one flat run of blocks, and the file name carries the title
+
+frontmatter_fields:
+- none: an index is read by path, so it carries no routing contract to restate
+
+lexicon_exempt:
+- none: an index has no frontmatter, so nothing is exempt
+
+sections:
+- key: identity
+  form: keyed-block
+  required: yes
+  record_keys: library, version, source
+  optional_record_keys: derived_from
+  note: the library covered and the revision it was read at; `version:` opens with the version alone, as a tool reads it up to the first comma; derived_from names the sources, because prose carries less weight than a signature
+
+- key: purpose
+  form: bullet-list
+  required: yes
+  note: what the library does, and the kind of task a reader reaches for it with
+
+- key: read_protocol
+  form: numbered-list
+  required: yes
+  note: the index is the cost of every question and a page the cost of 1: the common case is written from `canonical_use:`, a page opens for a contract the reader lacks, and a step that stops the reader is the defect
+
+- key: install
+  form: bullet-list
+  required: no
+  note: how a project takes the dependency; delete the block when the docset covers a dependency the project already carries
+
+- key: canonical_use
+  form: keyed-block
+  required: yes
+  record_keys: shows
+  note: 1 complete working use of the library, carrying every load-bearing element; a reader holding only the index writes the common case from this block, and an index without one is a table of contents, which is enough for nothing
+
+- key: walkthrough
+  form: record-list
+  required: yes
+  record_keys: part, page
+  note: each part of `canonical_use:` and the page owning its detail; a record and not a comment inside the fence, because a fence is opaque and a link inside one reaches no reader and no check
+
+- key: concepts
+  form: record-list
+  required: yes
+  record_keys: page, does
+  note: the models a reader holds before any page reads correctly; a record and not a line, so every link in a docset is a `page:` value and a resolver guesses at none of them
+
+- key: tasks
+  form: record-list
+  required: yes
+  record_keys: page, does
+  note: the goals a reader arrives with; a catalog keyed on capability routes a reader holding a symbol and leaves one holding a goal to guess
+
+- key: catalog
+  form: record-list
+  required: yes
+  record_keys: capability, does, status
+  optional_record_keys: page, read, instead, fingerprint
+  record_values: status = covered, source, avoid
+  note: "every capability the library offers, in 1 record each; status is covered, source or avoid, and a symbol absent here is a symbol the library lacks; fingerprint changes when the source does, so a record without one cannot report drift"
+
+- key: excluded
+  form: bullet-list
+  required: yes
+  note: a whole region the docset leaves out, with the reason; a region named in neither this block nor the catalog reads as an omission nobody decided
+
+- key: companions
+  form: record-list
+  required: yes
+  record_keys: docset, when, owns
+  note: another docset covering what this library does not; `when:` is "always" once its index carries `overrides:`, since a reader loading it on demand misses the correction; "- none" when the library stands alone
+
+- key: overrides
+  form: record-list
+  required: no
+  record_keys: page, by, reason
+  note: "a page of another docset that stops holding once this package is present, and the page here that replaces it; `page:` names the foreign page and carries its docset prefix, `by:` names the local one and carries none"
+
+- key: version_notes
+  form: bullet-list
+  required: no
+  note: what changed in the covered version, for a reader arriving from an older one
+
+custom_sections:
+- none: a project fills this from the vocabulary its own docsets already use
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: an index routes every other page, so a wrong index misroutes the whole docset
+- `npx cnlp check` resolves every `page:`, `by:` and `docset:` value once the project declares `docsets:`
+- `npx cnlp check` holds `status` to covered, source and avoid; what a status implies — a `read:` on source, an `instead:` on avoid — is caught by review

package/node_modules/cnlp-kit/skills/cnlp-docset/SKILL.md

@@ -51,7 +51,7 @@ workflow:
 1. run `npx cnlp print format` and read it in full, §9 included: it states what a page reference is, and which of its rules a review holds rather than the checker
 2. read the `docset`, `concept`, `api` and `task` profiles through `npx cnlp print <name>`: their `note:` keys carry the reason behind each block, and the rules and the values are read together
 3. list every source the operator supplied and name the weight each one carries: the strongest weight in that list bounds what every page below claims, so report it before writing anything
-4. run the clone or the install command each source needs, at a fixed revision, and record the library, the version and the revision in `identity:`
+4. run the clone or the install command each source needs, at a fixed revision, and record the library in `identity:`, and in `version:` the version alone, then a comma and the revision
 5. fill `derived_from:` in `identity:` with those sources and their weights, so a reader tells a set written from declarations from a set written from prose
 6. list every capability of the library, taking each one from the strongest source that states it: a source at weight 3 or below covers what its author chose to cover, so a capability it omits is a capability still to find
 7. fill `catalog:` with 1 record per capability, every one at `status: source`, `read:` naming where to read it — the file, or the document and the anchor inside it
@@ -63,9 +63,11 @@ workflow:
 13. write 1 task page per goal a reader arrives with, and put the multi-call composition there
 14. update each catalog record to `covered` as its page lands, and fill `excluded:` with every whole region the set leaves out, each with its reason
 15. fill `companions:` when another package extends this library, and `overrides:` when this package corrects a page of the set it extends
-16. run `npx cnlp check <output_directory>` and fix what it reports: it resolves every reference in the set, and reports a page no other page reaches
-17. read the finished set for the rules no check reaches: 1 fact stated on 1 page, 1 running example across the set, 1 page per routed name, and the keys a status implies
-18. report the capabilities covered, the ones left at `source`, the weight the set rests on, and any defect the reading turned up in the library itself
+16. name every set `companions:` or `overrides:` names that does not sit beside `<output_directory>`, and the directory holding it: the check resolves a crossing only against a set it can read
+17. run `npx cnlp check <output_directory>`, with `--companion <set>=<dir>` for each set step 16 named, and fix what it reports: it resolves every reference in the set, and reports a page no other page reaches
+18. read the finished set for the rules no check reaches: 1 fact stated on 1 page, 1 running example across the set, 1 page per routed name, and the keys a status implies
+19. read each task page against the API pages it sends a reader to: a member the task steers away from carries that in its own `pitfalls:`, because a full API page otherwise outvotes a task page's preference
+20. report the capabilities covered, the ones left at `source`, the weight the set rests on, and any defect the reading turned up in the library itself
 
 invocation:
 - Claude Code: `/cnlp-docset <sources> <output-directory>`, once this folder sits in `.claude/skills/`

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

@@ -29,21 +29,57 @@ export const HARD_LIMIT = 250; // §4: 150 is the target, 250 is compound whatev
 
 const FORMS = new Set(['scalar', 'bullet-list', 'numbered-list', 'record-list', 'keyed-block']);
 const KEY = /^([a-z][a-z0-9_]*):(.*)$/;
+/** §3: a line that is 1 whole comment. `<!-- a --> - item` carries an item, and is read. */
+const COMMENT = /^\s*<!--(?:(?!-->).)*-->\s*$/;
+/** §3: the markers of a region another tool writes into the file. */
+const REGION = /^\s*<!--\s*([\w.-]+):(start|end)\s*-->\s*$/;
 
 /**
- * Body split into lines, top-level `key:` sections and `##` headings, with fenced regions
- * blanked — §3: a fence is opaque, its contents are data and never section keys.
- * Leading frontmatter is stripped when present. Line numbers are 1-based within the body.
+ * Body split into lines, top-level `key:` sections and `##` headings. §3: a fence is blanked in
+ * both `lines` and `prose`, because its contents are data. An HTML comment and a marked region are
+ * blanked in `lines` only, which is the shape the profile reads: both stay in `prose`, which the
+ * lexicon reads, because an agent reads the raw file. Leading frontmatter is blanked when
+ * present. Line numbers are 1-based within the file.
  */
 export function parseBlocks(raw) {
-  const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+  // Blanked, not removed: a reported line is a line of the file, frontmatter included.
+  const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, (m) => '\n'.repeat(m.split('\n').length - 1));
+  const source = body.split(/\r?\n/);
+  // A comment that never closes hides nothing: it would otherwise exempt the rest of the file.
+  const lastClose = source.findLastIndex((l) => l.includes('-->'));
   let fenced = false;
+  let comment = false;
   const fences = []; // 1-based line numbers a fence covered: blanked, but not absent
-  const lines = body.split(/\r?\n/).map((l, i) => {
+  const marks = [];
+  const hidden = new Map(); // 0-based line -> what is left of it once its comment is taken off
+  const prose = source.map((l, i) => {
+    if (comment) {
+      const end = l.indexOf('-->');
+      if (end >= 0) comment = false;
+      hidden.set(i, end < 0 ? '' : l.slice(end + 3));
+      return l;
+    }
     if (/^\s*```/.test(l)) { fenced = !fenced; fences.push(i + 1); return ''; }
     if (fenced) { fences.push(i + 1); return ''; }
+    const mark = l.match(REGION);
+    if (mark) marks.push({ name: mark[1], end: mark[2] === 'end', at: i });
+    if (COMMENT.test(l)) hidden.set(i, '');
+    else if (/^\s*<!--/.test(l) && !l.includes('-->') && i < lastClose) { comment = true; hidden.set(i, ''); }
     return l;
   });
+  // An end closes the latest start of its own name, so regions of 2 names never cancel each other.
+  // A start with no end marks nothing, and an end with no start is a comment like any other.
+  const regions = [];
+  const open = new Map();
+  for (const m of marks) {
+    if (!m.end) open.set(m.name, m.at);
+    else if (open.has(m.name)) {
+      regions.push({ name: m.name, line: open.get(m.name) + 1, end: m.at + 1 });
+      open.delete(m.name);
+    }
+  }
+  const inRegion = (i) => regions.some((r) => i + 1 > r.line && i + 1 < r.end);
+  const lines = prose.map((l, i) => (inRegion(i) ? '' : hidden.get(i) ?? l));
   const sections = [];
   const headings = [];
   lines.forEach((l, i) => {
@@ -51,7 +87,8 @@ export function parseBlocks(raw) {
     if (key) sections.push({ key: key[1], value: key[2].trim(), line: i + 1 });
     if (/^##\s/.test(l)) headings.push({ text: l.trim(), line: i + 1 });
   });
-  return { lines, sections, headings, fences: new Set(fences) };
+  // A fence inside a region is the region's content, not content of the block above the region.
+  return { lines, prose, sections, headings, fences: new Set(fences.filter((n) => !inRegion(n - 1))), regions };
 }
 
 /** Lines of a section: everything up to the next top-level key or `##` heading. */
@@ -202,7 +239,7 @@ export async function loadProfile(name, opts) {
  * about the document as a whole.
  */
 export function bodyIssues(raw, profile) {
-  const { lines, sections, headings, fences } = parseBlocks(raw);
+  const { lines, prose, sections, headings, fences } = parseBlocks(raw);
   const issues = [];
   const at = (line, message) => issues.push({ line, message });
   const byKey = new Map(profile.sections.map((s) => [s.key, s]));
@@ -271,7 +308,8 @@ export function bodyIssues(raw, profile) {
     issues.push(...formIssues(key, spec, items));
   }
 
-  issues.push(...lexiconIssues(lines, profile.mood));
+  // A region is exempt from the file's shape, not from the language: the lexicon reads it.
+  issues.push(...lexiconIssues(prose, profile.mood));
   return issues.sort((a, b) => a.line - b.line);
 }
 
@@ -502,7 +540,9 @@ export function lexiconIssues(lines, mood = '') {
     // A converted document is where these 2 turn up: a mechanical split reads an ordinal as a
     // sentence and leaves `- 4` behind, and cutting a line to the hard limit lands mid-span.
     const item = l.match(/^\s*(?:[-*]|\d+\.)\s+(.*)$/);
-    if (item && !/[a-z]/i.test(item[1])) issues.push({ line, message: 'the item carries no word — it states no claim' });
+    // Any script's letter, not an ASCII one: the rule rejects an item made of digits and
+    // punctuation, and a body written in Cyrillic or CJK states its claims in letters too.
+    if (item && !/\p{L}/u.test(item[1])) issues.push({ line, message: 'the item carries no word — it states no claim' });
     for (const [name, open, close] of UNCLOSED) {
       const n = (l.match(open) || []).length;
       if (close ? n !== (l.match(close) || []).length : n % 2) {
@@ -531,4 +571,26 @@ export function lexiconIssues(lines, mood = '') {
   return issues;
 }
 
+/**
+ * Whether the §5 lexicon reaches a document. Every word list in §5 — the deny list, the spelled
+ * thresholds, the open limits, the comparatives, the light verbs, the passive — is English, so a
+ * body written in another script matches none of them and would report clean against rules that
+ * never ran. The prose decides it, which is the line with its section key, its heading marker and
+ * its quoted spans taken off: a key is this format's own vocabulary and English in every document,
+ * and a Russian line naming `CombatFeature.cs` is still a Russian line.
+ * ponytail: this reads script, not language — a German or a Spanish body reads as English here, and
+ * only its reader can say otherwise.
+ */
+export function lexiconApplies(raw) {
+  const prose = raw
+    .replace(/```[\s\S]*?```/g, ' ')
+    .split(/\r?\n/)
+    .filter((l) => !/^\s*#/.test(l))
+    .map((l) => unquoted(l).replace(/^\s*(?:[-*]\s+|\d+\.\s+)?[a-z][a-z0-9_]*:/, ' '))
+    .join('\n');
+  const letters = prose.match(/\p{L}/gu) ?? [];
+  const latin = letters.filter((c) => /[a-z]/i.test(c)).length;
+  return latin * 2 >= letters.length;
+}
+
 export { FORMS };

package/node_modules/cnlp-kit/src/config.js

@@ -4,9 +4,9 @@
 // inside a file the next upgrade overwrote.
 
 import { existsSync } from 'node:fs';
-import { glob, readdir, readFile } from 'node:fs/promises';
+import { glob, readdir, readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
-import { bodyIssues, loadProfileAt, pageRefs, resolveDoc } from './cnlp.js';
+import { bodyIssues, lexiconApplies, loadProfileAt, pageRefs, parseBlocks, resolveDoc } from './cnlp.js';
 
 export const CONFIG_NAME = 'cnlp.config.json';
 
@@ -124,24 +124,48 @@ export function readingOrder(sets) {
   return out;
 }
 
+/** `pageIdOf`, with the set renamed when the caller named it apart from its directory. */
+const renamedIdOf = (rel, docsets, rename) => {
+  const id = pageIdOf(rel, docsets);
+  return id && { ...id, docset: rename[id.docset] ?? id.docset };
+};
+
 /**
  * §9 reference conformance across a corpus, which is the 1 check no single document can make.
  * `docs` is every file already read, so this adds no read of its own.
+ *
+ * `context` holds the pages of companion sets as `{ set, page, raw }`: they resolve references and
+ * are never checked. Their id comes with them rather than from a path, because a companion may sit
+ * outside the root, in a folder named by a version rather than by its set.
  */
-export function linkIssues(docs, docsets) {
+export function linkIssues(docs, docsets, { context = [], rename = {} } = {}) {
   const pages = new Map();
   const sets = new Set();
   for (const { rel } of docs) {
-    const id = pageIdOf(rel, docsets);
+    const id = renamedIdOf(rel, docsets, rename);
     if (!id) continue;
     pages.set(`${id.docset}:${id.page}`, rel);
     sets.add(id.docset);
   }
+  const known = new Set(pages.keys());
+  for (const { set, page } of context) {
+    known.add(`${set}:${page}`);
+    sets.add(set);
+  }
 
   const issues = [];
   const reached = new Set();
+  // A companion's references are not this run's to report, but they count toward reach: a page of
+  // an integration set is reached only from the companion that overrides it.
+  for (const { set, page, raw } of context) {
+    for (const ref of pageRefs(raw)) {
+      if (ref.key === 'docset') continue;
+      const qualified = ref.target.includes(':') ? ref.target : `${set}:${ref.target}`;
+      if (qualified !== `${set}:${page}`) reached.add(qualified);
+    }
+  }
   for (const { rel, raw } of docs) {
-    const from = pageIdOf(rel, docsets);
+    const from = renamedIdOf(rel, docsets, rename);
     if (!from) continue;
     const self = `${from.docset}:${from.page}`;
     for (const ref of pageRefs(raw)) {
@@ -157,7 +181,7 @@ export function linkIssues(docs, docsets) {
       if (ref.key === 'by' && ref.target.includes(':')) {
         issues.push({ file: rel, line: ref.line, message: `"by: ${ref.target}" carries a document set prefix — a "by:" value names a page of this set` });
       }
-      if (!pages.has(qualified)) {
+      if (!known.has(qualified)) {
         issues.push({ file: rel, line: ref.line, message: `page "${qualified}" does not resolve to a file under ${docsets}/` });
       } else if (qualified !== self) {
         reached.add(qualified);
@@ -217,6 +241,85 @@ export async function skillDrift(root, agents, version) {
   return out;
 }
 
+/**
+ * The standing rules `cnlp init` hands an operator to paste into the file their agent reads. 1
+ * value and not a string inside the command, because `cnlp check` reads it too: a pasted copy is a
+ * copy that goes stale, and nothing else in the project records that it was taken.
+ */
+export const AGENT_BLOCK = [
+  '- 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",
+];
+
+// The 2 files an agent reads by convention, which are the 2 the corpus proposal below already
+// knows. The block is pasted by hand, so nothing records which file took it.
+const AGENT_FILES = ['AGENTS.md', 'CLAUDE.md'];
+
+/**
+ * The agent files carrying a copy of `AGENT_BLOCK` from an earlier version. A bullet naming
+ * `npx cnlp print format` is the block's own opener and is what finds the copy.
+ * ponytail: that phrase is the anchor — a version that stops naming it loses the watch on every
+ * copy already pasted, and the answer then is markers written into the file.
+ */
+export async function agentBlockDrift(root) {
+  const out = [];
+  for (const name of AGENT_FILES) {
+    const at = path.join(root, name);
+    if (!existsSync(at)) continue;
+    const lines = (await readFile(at, 'utf8')).split(/\r?\n/).map((l) => l.trimEnd());
+    const start = lines.findIndex((l) => /^-\s.*`npx cnlp print format`/.test(l));
+    if (start < 0) continue; // the project never took the block
+    if (lines.slice(start, start + AGENT_BLOCK.length).join('\n') !== AGENT_BLOCK.join('\n')) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * The local profiles a packaged profile of the same name has outgrown. A project copies a packaged
+ * profile to fill its own `custom_sections`, and `profileFor` reads the copy from then on: an
+ * upgrade moves the original underneath it, and the check reports a conformant corpus against a
+ * declaration this package has since changed. What a copy adds is the vocabulary it was copied for
+ * and is never drift; what the packaged profile declares and the copy does not is.
+ */
+export async function profileDrift(config) {
+  const out = [];
+  if (!config.profilesDir) return out;
+  for (const name of [...new Set(config.corpus.map((e) => e.profile))].sort()) {
+    const local = path.join(config.profilesDir, `${name}.md`);
+    const packagedAt = resolveDoc(name);
+    if (!existsSync(local) || !existsSync(packagedAt) || path.resolve(packagedAt) === path.resolve(local)) continue;
+    const packaged = await loadProfileAt(packagedAt);
+    const mine = await loadProfileAt(local);
+    const byKey = new Map(mine.sections.map((s) => [s.key, s]));
+    const missing = [];
+    for (const want of packaged.sections) {
+      const has = byKey.get(want.key);
+      if (!has) {
+        missing.push(`section "${want.key}"`);
+        continue;
+      }
+      if (has.form !== want.form) missing.push(`section "${want.key}" as a ${want.form}`);
+      if (want.required && !has.required) missing.push(`section "${want.key}" as required`);
+      for (const k of want.recordKeys) {
+        if (!has.recordKeys.includes(k)) missing.push(`record key "${want.key}.${k}"`);
+      }
+    }
+    for (const h of packaged.headings) {
+      if (!mine.headings.includes(h)) missing.push(`heading "${h}"`);
+    }
+    for (const f of packaged.frontmatterFields) {
+      if (!mine.frontmatterFields.includes(f)) missing.push(`frontmatter field "${f}"`);
+    }
+    if (packaged.mood && packaged.mood !== mine.mood) missing.push(`mood "${packaged.mood}"`);
+    // Forward slashes, like every other path this reports: the checker names a file the same way
+    // on every platform.
+    const rel = path.relative(config.root, local).split(path.sep).join('/');
+    if (missing.length) out.push({ profile: name, file: rel, missing });
+  }
+  return out;
+}
+
 // The layouts a corpus entry is usually written for. `cnlp init` keeps the ones that match a file,
 // so a project adopting the format starts from its own layout rather than from an example of one.
 // ponytail: path convention only, never content — a decision record filed under docs/references
@@ -272,21 +375,69 @@ export async function proposeCorpus(root) {
  * An entry matching no file is dropped here, which a written config is right to refuse: a glob a
  * project typed and no file answers is a mistake, and a glob this function guessed is a folder the
  * set does not have yet.
+ *
+ * 1 set checked alone still resolves its crossings: `companions` names the sets it crosses into,
+ * each `{ name, dir }`, and the sets beside it join as companions named by their directories. A
+ * companion is read to resolve a reference and never checked. `name` names the checked set when
+ * its directory does not, as in a layout of `<set>/<version>/`.
  */
-export async function configForPath(dir) {
-  const abs = path.resolve(dir);
-  if (!existsSync(abs)) throw new Error(`no such directory: ${dir}`);
+export async function configForPath(dir, { name, companions: named = [] } = {}) {
+  if (!existsSync(path.resolve(dir))) throw new Error(`no such directory: ${dir}`);
+  // The spelling on disk, not the one typed: on a case-insensitive disk `DragonECS-Unity` would
+  // otherwise miss its own directory among the siblings and read itself as a companion.
+  const abs = await realpath(path.resolve(dir));
+  if (!Array.isArray(named)) throw new Error(`companions is a list of { name, dir }, found ${JSON.stringify(named)}`);
   let root;
   let docsets = null;
   let corpus;
-  if (existsSync(path.join(abs, 'index.md'))) {
+  const oneSet = existsSync(path.join(abs, 'index.md'));
+  // A root check already reads every set under it, and a project has no single set to name.
+  if (!oneSet && (name !== undefined || named.length)) {
+    throw new Error(`${abs} is not 1 document set — a name and companions apply to a directory holding an index.md`);
+  }
+  const base = path.basename(abs);
+  const setName = name ?? base;
+  const companions = [];
+  if (oneSet) {
+    if (name !== undefined) checkSetName(name, 'the checked set');
+    for (const c of named) {
+      checkSetName(c.name, 'a companion');
+      if (!c.dir) throw new Error(`companion "${c.name}" names no dir — give the directory of 1 document set`);
+      if (!existsSync(path.resolve(c.dir))) throw new Error(`companion "${c.name}": no such directory: ${path.resolve(c.dir)}`);
+      const at = await realpath(path.resolve(c.dir));
+      // The checked set read again under another name would reach its own pages through the copy.
+      if (at === abs) throw new Error(`companion "${c.name}" is the checked set itself — name another set`);
+      if (!existsSync(path.join(at, 'index.md'))) {
+        throw new Error(`companion "${c.name}": ${at} holds no index.md — name the directory of 1 document set`);
+      }
+      if (c.name === setName) throw new Error(`companion "${c.name}" carries the name of the checked set — name it apart`);
+      if (companions.some((o) => o.name === c.name)) throw new Error(`companion "${c.name}" is named twice — name each set once`);
+      companions.push({ name: c.name, dir: at });
+    }
+    // A set is present because a project vendors it, so the sets beside it are its companions.
+    // A name apart from the directory means no flat layout: the siblings there are other versions
+    // of the same set, and reading them as sets would resolve nothing.
+    // ponytail: a sibling's name is its directory's and is not held to `checkSetName`; a directory
+    // carrying ":" is possible only off Windows, and it would print as a set nobody can reference.
+    if (setName === base) {
+      const parent = path.dirname(abs);
+      for (const entry of (await readdir(parent, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        const at = path.join(parent, entry.name);
+        if (!entry.isDirectory() || entry.name === base || !existsSync(path.join(at, 'index.md'))) continue;
+        // An explicit companion wins, by name or by directory: 1 set is read once.
+        if (companions.some((o) => o.name === entry.name || o.dir === at)) continue;
+        companions.push({ name: entry.name, dir: at });
+      }
+    }
+  }
+  if (oneSet) {
     root = path.dirname(path.dirname(abs));
     docsets = path.basename(path.dirname(abs));
-    corpus = docsetCorpus(`${docsets}/${path.basename(abs)}`);
+    corpus = docsetCorpus(`${globLiteral(docsets)}/${globLiteral(base)}`);
   } else if (await holdsASet(abs)) {
     root = path.dirname(abs);
     docsets = path.basename(abs);
-    corpus = docsetCorpus(`${docsets}/*`);
+    corpus = docsetCorpus(`${globLiteral(docsets)}/*`);
   } else {
     // Neither shape: fall back to the layouts `cnlp init` already knows, so pointing at a project
     // reads the same as pointing at a set.
@@ -301,7 +452,29 @@ export async function configForPath(dir) {
   if (kept.length === 0) {
     throw new Error(`${abs} holds no document this kit knows the layout of — a document set is an index.md beside concepts, api and tasks`);
   }
-  return { path: null, root, profilesDir: null, docsets, corpus: kept, agents: [] };
+  // `companions` is always present, `[]` included: a caller tells a kit that ignores the option
+  // from a set that failed by this field's absence.
+  const rename = setName === base ? {} : { [base]: setName };
+  return { path: null, root, profilesDir: null, docsets, corpus: kept, agents: [], companions, rename };
+}
+
+/** A set name keys every page id, and `:` separates `<set>:<name>`, so a name carrying it reads as a page. */
+function checkSetName(name, whose) {
+  if (typeof name !== 'string' || name === '' || /[:/\\]/.test(name)) {
+    throw new Error(`${JSON.stringify(name)} is no name for ${whose} — a set name is not empty and carries no ":", "/" or "\\"`);
+  }
+}
+
+/**
+ * A directory name as a glob that matches only itself. The corpus is a glob, and a set in
+ * `2.0.0-[rc]` otherwise reads as a character class that matches no directory, which reports
+ * the set as holding no document. A class of 1 character is the escape `fs.glob` honours: it
+ * reads `\` as a separator on Windows.
+ * ponytail: a `{` still opens a brace set, which no escape reaches through `fs.glob`; a set
+ * directory named with braces needs a config instead of a path.
+ */
+function globLiteral(name) {
+  return name.replace(/[[*?]/g, (c) => `[${c}]`);
 }
 
 /** Whether an immediate subdirectory carries an index.md, which is what makes a directory a root. */
@@ -329,10 +502,40 @@ export async function filesFor(entry, root) {
  * Run every corpus entry. Returns the files checked and the issues found, each carrying the
  * project-relative path it came from. Severity is the caller's: an issue is an issue here.
  */
+/**
+ * The bytes a document set costs a reader, split by when they are paid. The index is loaded to
+ * answer any question and a page is loaded to answer 1, so the 2 numbers are different kinds of
+ * cost, and an author trimming the wrong one saves a reader nothing.
+ *
+ * Computed from the documents the caller has already read, so this adds no read of its own.
+ */
+export function setSizes(docs, docsets, rename = {}) {
+  const sets = new Map();
+  for (const { rel, raw } of docs) {
+    const id = renamedIdOf(rel, docsets, rename);
+    if (!id) continue;
+    const set = sets.get(id.docset) ?? { name: id.docset, indexBytes: 0, pages: 0, pageBytes: 0 };
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (id.page === 'index') set.indexBytes += bytes;
+    else {
+      set.pages += 1;
+      set.pageBytes += bytes;
+    }
+    sets.set(id.docset, set);
+  }
+  return [...sets.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
 export async function checkProject(config) {
   const issues = [];
   const checked = [];
   const docs = [];
+  // A document the §5 word lists never reach. It is not an issue — nothing in it is wrong — but a
+  // run that says nothing about it reports a conformant corpus over rules that never ran.
+  const foreign = [];
+  // §3: a marked region the file's profile did not shape. Reported for the same reason: a run that
+  // names no exemption reads as a check of every line, and a region is an exemption anybody can write.
+  const regions = [];
   for (const entry of config.corpus) {
     const files = await filesFor(entry, config.root);
     if (files.length === 0) {
@@ -343,10 +546,25 @@ export async function checkProject(config) {
       const raw = await readFile(path.join(config.root, rel), 'utf8');
       checked.push(rel);
       docs.push({ rel, raw });
+      if (!lexiconApplies(raw)) foreign.push(rel);
+      for (const r of parseBlocks(raw).regions) regions.push({ file: rel, ...r });
       for (const issue of bodyIssues(raw, profile)) issues.push({ file: rel, ...issue });
     }
   }
+  // A config from `readConfig` carries neither field: it already reads every set under its root.
+  const rename = config.rename ?? {};
+  // A companion's pages resolve references and are counted nowhere: the run reports on the set it
+  // was pointed at. `docsetCorpus` is the 1 place the shape of a set is written, so it is read here too.
+  const context = [];
+  for (const { name, dir } of config.companions ?? []) {
+    for (const entry of docsetCorpus('.')) {
+      for (const rel of await filesFor(entry, dir)) {
+        const page = rel.split(path.sep).join('/').slice(0, -3);
+        context.push({ set: name, page, raw: await readFile(path.join(dir, rel), 'utf8') });
+      }
+    }
+  }
   // §9 is the 1 rule that needs the whole corpus, so it runs once over the files already read.
-  if (config.docsets) issues.push(...linkIssues(docs, config.docsets));
-  return { checked, issues };
+  if (config.docsets) issues.push(...linkIssues(docs, config.docsets, { context, rename }));
+  return { checked, issues, foreign, regions, sets: config.docsets ? setSizes(docs, config.docsets, rename) : [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "README.md"
   ],
   "dependencies": {
-    "cnlp-kit": "^3.1.3",
+    "cnlp-kit": "^3.9.1",
     "yaml": "^2.5.1"
   },
   "bundleDependencies": [