@sledorze/cairn 0.1.0

package/dist/core/glob.bench.js

@@ -0,0 +1,62 @@
+import { bench, describe } from 'vitest';
+import { globToRegExp, matchesAny, matchesGlob } from "./glob.js";
+const DIRS = ['src', 'docs', 'lib', 'packages', 'apps', 'test', 'scripts', 'vendor'];
+const SUBDIRS = ['core', 'utils', 'components', 'services', 'models', 'fixtures'];
+const EXTS = ['ts', 'tsx', 'md', 'json', 'css', 'tmp'];
+const makePaths = (count) => Array.from({ length: count }, (_, i) => {
+    const dir = DIRS[i % DIRS.length];
+    const sub = SUBDIRS[i % SUBDIRS.length];
+    const ext = EXTS[i % EXTS.length];
+    if (i % 11 === 0) {
+        return `${dir}/node_modules/${sub}/pkg-${i}/index.${ext}`;
+    }
+    if (i % 13 === 0) {
+        return `${dir}/.git/objects/${i}.pack`;
+    }
+    if (i % 17 === 0) {
+        return `dist/${sub}/bundle-${i}.${ext}`;
+    }
+    return `${dir}/${sub}/deep/nested/path/file-${i}.${ext}`;
+});
+const IGNORE_PATTERNS = ['**/node_modules/**', '**/.git/**', 'dist/**', '**/*.tmp'];
+const SIMPLE_PATTERN = 'docs/*.md';
+const STAR_STAR_PATTERN = 'docs/**/a.md';
+const ENCLOSURE_PATTERN = '**/node_modules/**';
+const COMPLEX_PATTERN = '**/src/**/*.spec.?s?(x)';
+const paths500 = makePaths(500);
+const paths5000 = makePaths(5000);
+describe('globToRegExp() — compilation cost by pattern complexity', () => {
+    bench('simple single-segment pattern', () => {
+        globToRegExp(SIMPLE_PATTERN);
+    });
+    bench('`**` pattern', () => {
+        globToRegExp(STAR_STAR_PATTERN);
+    });
+    bench('`**/dir/**` enclosure pattern', () => {
+        globToRegExp(ENCLOSURE_PATTERN);
+    });
+    bench('longer pattern with mixed wildcards', () => {
+        globToRegExp(COMPLEX_PATTERN);
+    });
+});
+describe('matchesGlob() — single call, since it recompiles the regex every time', () => {
+    bench('match against a `**/node_modules/**` pattern', () => {
+        matchesGlob('src/core/node_modules/pkg/index.ts', ENCLOSURE_PATTERN);
+    });
+    bench('non-match against a `**/node_modules/**` pattern', () => {
+        matchesGlob('src/core/deep/nested/path/file.ts', ENCLOSURE_PATTERN);
+    });
+});
+describe('matchesAny() — scanning cost across candidate-path-list scale', () => {
+    bench('~500 paths against the realistic ignore list', () => {
+        for (const path of paths500) {
+            matchesAny(path, IGNORE_PATTERNS);
+        }
+    });
+    bench('~5000 paths against the realistic ignore list', () => {
+        for (const path of paths5000) {
+            matchesAny(path, IGNORE_PATTERNS);
+        }
+    });
+});
+//# sourceMappingURL=glob.bench.js.map

package/dist/core/glob.bench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.bench.js","sourceRoot":"","sources":["../../src/core/glob.bench.ts"],"names":[],"mappings":"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"}

package/dist/core/glob.d.ts

@@ -0,0 +1,7 @@
+/** Compile a glob into an anchored RegExp. */
+export declare const globToRegExp: (pattern: string) => RegExp;
+/** True when `path` matches the glob `pattern`. */
+export declare const matchesGlob: (path: string, pattern: string) => boolean;
+/** True when `path` matches any of the glob `patterns`. */
+export declare const matchesAny: (path: string, patterns: readonly string[]) => boolean;
+//# sourceMappingURL=glob.d.ts.map

package/dist/core/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/core/glob.ts"],"names":[],"mappings":"AAWA,8CAA8C;AAC9C,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAQ9C,CAAA;AA4BD,mDAAmD;AACnD,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,OAA2C,CAAA;AAEvG,2DAA2D;AAC3D,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,EAAE,UAAU,SAAS,MAAM,EAAE,KAAG,OACf,CAAA"}

package/dist/core/glob.js

@@ -0,0 +1,52 @@
+// Tiny dependency-free glob matcher for `ignore` patterns and `roots` expansion.
+// Supports `**` (any run, including `/`), `*` (any run except `/`) and `?` (one
+// char except `/`). Patterns and paths use `/` separators. Pure and unit-tested.
+const SPECIAL = /[.+^${}()|[\]\\]/g;
+// Ignore/root pattern lists are small and reused across every path they're tested
+// against (an O(paths) x O(patterns) product), so compiling once per distinct
+// pattern — instead of once per call — turns that product into O(patterns).
+const compiled = new Map();
+/** Compile a glob into an anchored RegExp. */
+export const globToRegExp = (pattern) => {
+    const cached = compiled.get(pattern);
+    if (cached) {
+        return cached;
+    }
+    const re = compile(pattern);
+    compiled.set(pattern, re);
+    return re;
+};
+const compile = (pattern) => {
+    let re = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                // `**` — any run including path separators. Absorb a following `/`.
+                i += 1;
+                if (pattern[i + 1] === '/') {
+                    i += 1;
+                    re += '(?:.*/)?';
+                }
+                else {
+                    re += '.*';
+                }
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else {
+            re += (c ?? '').replace(SPECIAL, '\\$&');
+        }
+    }
+    return new RegExp(`^${re}$`);
+};
+/** True when `path` matches the glob `pattern`. */
+export const matchesGlob = (path, pattern) => globToRegExp(pattern).test(path);
+/** True when `path` matches any of the glob `patterns`. */
+export const matchesAny = (path, patterns) => patterns.some((pattern) => matchesGlob(path, pattern));
+//# sourceMappingURL=glob.js.map

package/dist/core/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/core/glob.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,gFAAgF;AAChF,iFAAiF;AAEjF,MAAM,OAAO,GAAG,mBAAmB,CAAA;AAEnC,kFAAkF;AAClF,8EAA8E;AAC9E,4EAA4E;AAC5E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAA;AAE1C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAU,EAAE;IACtD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACpC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAA;IACf,CAAC;IACD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3B,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IACzB,OAAO,EAAE,CAAA;AACX,CAAC,CAAA;AAED,MAAM,OAAO,GAAG,CAAC,OAAe,EAAU,EAAE;IAC1C,IAAI,EAAE,GAAG,EAAE,CAAA;IACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;QACpB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACd,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC3B,oEAAoE;gBACpE,CAAC,IAAI,CAAC,CAAA;gBACN,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;oBAC3B,CAAC,IAAI,CAAC,CAAA;oBACN,EAAE,IAAI,UAAU,CAAA;gBAClB,CAAC;qBAAM,CAAC;oBACN,EAAE,IAAI,IAAI,CAAA;gBACZ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,EAAE,IAAI,OAAO,CAAA;YACf,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACrB,EAAE,IAAI,MAAM,CAAA;QACd,CAAC;aAAM,CAAC;YACN,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AAC9B,CAAC,CAAA;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,OAAe,EAAW,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEvG,2DAA2D;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,QAA2B,EAAW,EAAE,CAC/E,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA"}

package/dist/core/paths.d.ts

@@ -0,0 +1,3 @@
+/** Convert an OS path to POSIX form (`\` -> `/`). */
+export declare const toPosix: (p: string) => string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAIA,qDAAqD;AACrD,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,KAAG,MAAiC,CAAA"}

package/dist/core/paths.js

@@ -0,0 +1,6 @@
+// Path normalisation. The pure planners reason in POSIX (`/`) paths so behaviour
+// is identical on every OS; the IO layer normalises real filesystem paths (which
+// may use `\` on Windows) to POSIX before they reach the core.
+/** Convert an OS path to POSIX form (`\` -> `/`). */
+export const toPosix = (p) => p.replaceAll('\\', '/');
+//# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,iFAAiF;AACjF,+DAA+D;AAE/D,qDAAqD;AACrD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './core/DocSummaries.ts';
+export * from './core/glob.ts';
+export * from './core/MarkdownLinks.ts';
+export * from './core/SummaryTree.ts';
+export * from './io/DocsFs.ts';
+export * from './program/CheckLinks.ts';
+export * from './program/CheckSummaries.ts';
+export * from './program/locale.ts';
+export * from './config.ts';
+export type { AgentTarget, InitArgs, InitResult } from './init/generate.ts';
+export { runInit } from './init/generate.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,wBAAwB,CAAA;AACtC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,yBAAyB,CAAA;AACvC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// Public API surface. The CLI (`cairn`) is the primary entrypoint, but the pure
+// planners and Effect programs are exported for programmatic use and testing.
+export * from "./core/DocSummaries.js";
+export * from "./core/glob.js";
+export * from "./core/MarkdownLinks.js";
+export * from "./core/SummaryTree.js";
+export * from "./io/DocsFs.js";
+export * from "./program/CheckLinks.js";
+export * from "./program/CheckSummaries.js";
+export * from "./program/locale.js";
+export * from "./config.js";
+export { runInit } from "./init/generate.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,8EAA8E;AAE9E,cAAc,wBAAwB,CAAA;AACtC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,yBAAyB,CAAA;AACvC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAE3B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/init/content.d.ts

@@ -0,0 +1,3 @@
+export declare const CONVENTION_BODY = "# Documentation summary convention\n\nThis repo enforces a **hierarchical, content-hashed documentation summary** tree.\nCI runs `cairn check` and **fails the merge** if any summary is missing,\nstale, or a link is broken. Treat green `check` as a hard requirement, not a nicety.\n\n## The invariant\n\n1. **File summaries** \u2014 every Markdown file longer than the threshold (default 30\n   lines) has a sibling `X.summary.md`: a fast-to-read digest of the CURRENT content\n   of `X.md`.\n2. **Directory summaries** \u2014 every in-scope directory has a `_SUMMARY.md` that\n   aggregates its direct docs (each doc's `.summary.md` if the doc is big, else the\n   doc itself) plus the `_SUMMARY.md` of each direct sub-directory. It links to\n   **every** direct child file and sub-directory (link-completeness).\n3. **Freshness by content hash** \u2014 each summary's first line is\n   `<!-- source-sha256: <64-hex> -->`. The checker recomputes the source hash;\n   mismatch = stale, absent = missing. This survives git clone and CI (mtime does not).\n4. **Bottom-up in one pass** \u2014 a directory summary hashes a manifest of its children's\n   hashes (a Merkle tree), so (re)write leaves-first: file summaries, then directories\n   deepest-first, then stamp.\n\n## Workflow when you edit docs\n\nWhen you create or edit any doc:\n\n1. If the doc is longer than the threshold, create or update its `X.summary.md` to\n   reflect the new content.\n2. Update the `_SUMMARY.md` of every affected directory, walking **up** the tree\n   leaves-first, and keep a link to every child file and sub-directory.\n3. Run the stamp command to (re)write the `source-sha256` hashes bottom-up:\n   `npx cairn check --summaries-only --stamp`.\n4. Run `npx cairn check` and ensure it exits 0 (green) before you finish.\n\n## Commands\n\n- `npx cairn check` \u2014 check summaries + links (exit 1 on any problem).\n- `npx cairn check --summaries-only` / `--links-only`.\n- `npx cairn check --links-only --fix` \u2014 auto-repair unambiguous dead links.\n- `npx cairn check --summaries-only --stamp` \u2014 write stamps of EXISTING\n  summaries bottom-up. It does **not** author prose; you write the content, then stamp.\n\nYou author the prose. The tool only verifies and stamps.\n";
+export declare const SKILL_BODY = "# Writing good documentation summaries\n\nUse this when you author or refresh the summary tree that `cairn`\nenforces. It covers *how* to write summaries that are worth reading, and the exact\nmechanical order to (re)generate them so `check` goes green in one pass.\n\n## Two kinds of summary \u2014 do not conflate them\n\n**A file summary (`X.summary.md`) condenses ONE document.**\nGoal: a reader grasps what `X.md` says in ~10 seconds.\n\n- Faithful to the source \u2014 never invent, never contradict, never add claims the doc\n  doesn't make. It is a digest, not commentary.\n- Front-load the thesis and the hard numbers. Lead with the conclusion, the decision,\n  the metric \u2014 not the background.\n- Bullet-dense, no fluff. Drop hedging, transitions, and restated headings.\n- If the source changes, the summary changes. A summary that no longer matches its\n  source is a bug the checker will catch.\n\n**A directory summary (`_SUMMARY.md`) is a MAP, not a digest.**\nGoal: a reader knows what lives in this directory and where to go next.\n\n- A short orientation paragraph (1-3 sentences): what this directory is about.\n- Then one line per direct child \u2014 file **and** sub-directory \u2014 each with a Markdown\n  link and a few-word hook describing what's behind it.\n- For a big doc, link and hook its `.summary.md`; for a small doc, link the doc itself.\n- For a sub-directory, link its `_SUMMARY.md`.\n- **Link-completeness:** every direct child must appear as a link. A missing link fails\n  `check`. When you add or remove a child, update the parent's `_SUMMARY.md`.\n\n## Why leaves-first \u2014 the Merkle mental model\n\nEach summary is stamped with `<!-- source-sha256: <hex> -->` over its source. A\ndirectory summary's source is a **manifest of its children's hashes**, so a child's\nhash must be settled before its parent can be stamped. Think of it as a Merkle tree:\nchange a leaf and every hash on the path to the root must be recomputed. If you stamp\ntop-down, parents capture stale child hashes and `check` stays red.\n\n## The bottom-up procedure\n\n1. **Author leaves first.** For every doc over the threshold, write/refresh its\n   `X.summary.md`. Get the prose right before touching any directory.\n2. **Author directories deepest-first.** Walk from the deepest directories up to the\n   roots. For each, write its `_SUMMARY.md`: orientation paragraph, then a linked line\n   for every direct child (child `.summary.md` or doc, and each sub-dir's `_SUMMARY.md`).\n3. **Stamp mechanically.** Run `npx cairn check --summaries-only --stamp`.\n   It rewrites every `source-sha256` bottom-up. **Never hand-edit a sha256** \u2014 it is\n   computed, not authored; a hand-typed hash is always wrong.\n4. **Verify.** Run `npx cairn check` and confirm exit 0.\n\n## Tiny examples\n\nA **file summary** (`guides/getting-started.summary.md`):\n\n```markdown\n<!-- source-sha256: 0000...(stamped by the tool) -->\n# Getting started \u2014 summary\n\n- Install as a dev dependency, then run the init command.\n- Configure via a single rc file; every option has a sensible default.\n- First run scaffolds an example and prints the next command to run.\n```\n\nA **directory summary** (`guides/_SUMMARY.md`):\n\n```markdown\n<!-- source-sha256: 0000...(stamped by the tool) -->\n# Guides\n\nHow-to guides for everyday tasks, in reading order.\n\n- [getting-started](./getting-started.summary.md) \u2014 install, configure, first run\n- [configuration](./configuration.md) \u2014 every rc option, with its default\n- [advanced/](./advanced/_SUMMARY.md) \u2014 recipes for larger setups\n```\n\nKeep summaries short, keep links complete, stamp last, verify green.\n";
+//# sourceMappingURL=content.d.ts.map

package/dist/init/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/init/content.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,eAAe,8tEA2C3B,CAAA;AAED,eAAO,MAAM,UAAU,gnHA6EtB,CAAA"}

package/dist/init/content.js

@@ -0,0 +1,127 @@
+// Prose surfaces injected by `cairn init`.
+// These are agent-neutral bodies; the generator wraps each with the
+// frontmatter appropriate to its target (Claude rule, Copilot instructions,
+// AGENTS.md block, or SKILL.md).
+export const CONVENTION_BODY = `# Documentation summary convention
+
+This repo enforces a **hierarchical, content-hashed documentation summary** tree.
+CI runs \`cairn check\` and **fails the merge** if any summary is missing,
+stale, or a link is broken. Treat green \`check\` as a hard requirement, not a nicety.
+
+## The invariant
+
+1. **File summaries** — every Markdown file longer than the threshold (default 30
+   lines) has a sibling \`X.summary.md\`: a fast-to-read digest of the CURRENT content
+   of \`X.md\`.
+2. **Directory summaries** — every in-scope directory has a \`_SUMMARY.md\` that
+   aggregates its direct docs (each doc's \`.summary.md\` if the doc is big, else the
+   doc itself) plus the \`_SUMMARY.md\` of each direct sub-directory. It links to
+   **every** direct child file and sub-directory (link-completeness).
+3. **Freshness by content hash** — each summary's first line is
+   \`<!-- source-sha256: <64-hex> -->\`. The checker recomputes the source hash;
+   mismatch = stale, absent = missing. This survives git clone and CI (mtime does not).
+4. **Bottom-up in one pass** — a directory summary hashes a manifest of its children's
+   hashes (a Merkle tree), so (re)write leaves-first: file summaries, then directories
+   deepest-first, then stamp.
+
+## Workflow when you edit docs
+
+When you create or edit any doc:
+
+1. If the doc is longer than the threshold, create or update its \`X.summary.md\` to
+   reflect the new content.
+2. Update the \`_SUMMARY.md\` of every affected directory, walking **up** the tree
+   leaves-first, and keep a link to every child file and sub-directory.
+3. Run the stamp command to (re)write the \`source-sha256\` hashes bottom-up:
+   \`npx cairn check --summaries-only --stamp\`.
+4. Run \`npx cairn check\` and ensure it exits 0 (green) before you finish.
+
+## Commands
+
+- \`npx cairn check\` — check summaries + links (exit 1 on any problem).
+- \`npx cairn check --summaries-only\` / \`--links-only\`.
+- \`npx cairn check --links-only --fix\` — auto-repair unambiguous dead links.
+- \`npx cairn check --summaries-only --stamp\` — write stamps of EXISTING
+  summaries bottom-up. It does **not** author prose; you write the content, then stamp.
+
+You author the prose. The tool only verifies and stamps.
+`;
+export const SKILL_BODY = `# Writing good documentation summaries
+
+Use this when you author or refresh the summary tree that \`cairn\`
+enforces. It covers *how* to write summaries that are worth reading, and the exact
+mechanical order to (re)generate them so \`check\` goes green in one pass.
+
+## Two kinds of summary — do not conflate them
+
+**A file summary (\`X.summary.md\`) condenses ONE document.**
+Goal: a reader grasps what \`X.md\` says in ~10 seconds.
+
+- Faithful to the source — never invent, never contradict, never add claims the doc
+  doesn't make. It is a digest, not commentary.
+- Front-load the thesis and the hard numbers. Lead with the conclusion, the decision,
+  the metric — not the background.
+- Bullet-dense, no fluff. Drop hedging, transitions, and restated headings.
+- If the source changes, the summary changes. A summary that no longer matches its
+  source is a bug the checker will catch.
+
+**A directory summary (\`_SUMMARY.md\`) is a MAP, not a digest.**
+Goal: a reader knows what lives in this directory and where to go next.
+
+- A short orientation paragraph (1-3 sentences): what this directory is about.
+- Then one line per direct child — file **and** sub-directory — each with a Markdown
+  link and a few-word hook describing what's behind it.
+- For a big doc, link and hook its \`.summary.md\`; for a small doc, link the doc itself.
+- For a sub-directory, link its \`_SUMMARY.md\`.
+- **Link-completeness:** every direct child must appear as a link. A missing link fails
+  \`check\`. When you add or remove a child, update the parent's \`_SUMMARY.md\`.
+
+## Why leaves-first — the Merkle mental model
+
+Each summary is stamped with \`<!-- source-sha256: <hex> -->\` over its source. A
+directory summary's source is a **manifest of its children's hashes**, so a child's
+hash must be settled before its parent can be stamped. Think of it as a Merkle tree:
+change a leaf and every hash on the path to the root must be recomputed. If you stamp
+top-down, parents capture stale child hashes and \`check\` stays red.
+
+## The bottom-up procedure
+
+1. **Author leaves first.** For every doc over the threshold, write/refresh its
+   \`X.summary.md\`. Get the prose right before touching any directory.
+2. **Author directories deepest-first.** Walk from the deepest directories up to the
+   roots. For each, write its \`_SUMMARY.md\`: orientation paragraph, then a linked line
+   for every direct child (child \`.summary.md\` or doc, and each sub-dir's \`_SUMMARY.md\`).
+3. **Stamp mechanically.** Run \`npx cairn check --summaries-only --stamp\`.
+   It rewrites every \`source-sha256\` bottom-up. **Never hand-edit a sha256** — it is
+   computed, not authored; a hand-typed hash is always wrong.
+4. **Verify.** Run \`npx cairn check\` and confirm exit 0.
+
+## Tiny examples
+
+A **file summary** (\`guides/getting-started.summary.md\`):
+
+\`\`\`markdown
+<!-- source-sha256: 0000...(stamped by the tool) -->
+# Getting started — summary
+
+- Install as a dev dependency, then run the init command.
+- Configure via a single rc file; every option has a sensible default.
+- First run scaffolds an example and prints the next command to run.
+\`\`\`
+
+A **directory summary** (\`guides/_SUMMARY.md\`):
+
+\`\`\`markdown
+<!-- source-sha256: 0000...(stamped by the tool) -->
+# Guides
+
+How-to guides for everyday tasks, in reading order.
+
+- [getting-started](./getting-started.summary.md) — install, configure, first run
+- [configuration](./configuration.md) — every rc option, with its default
+- [advanced/](./advanced/_SUMMARY.md) — recipes for larger setups
+\`\`\`
+
+Keep summaries short, keep links complete, stamp last, verify green.
+`;
+//# sourceMappingURL=content.js.map

package/dist/init/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/init/content.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,oEAAoE;AACpE,4EAA4E;AAC5E,iCAAiC;AAEjC,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2C9B,CAAA;AAED,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6EzB,CAAA"}

package/dist/init/generate.d.ts

@@ -0,0 +1,14 @@
+export declare const AGENT_TARGETS: readonly ["agents", "all", "claude", "copilot", "opencode"];
+export type AgentTarget = (typeof AGENT_TARGETS)[number];
+export interface InitArgs {
+    readonly agent: AgentTarget;
+    readonly cwd: string;
+    readonly roots: readonly string[];
+}
+export interface InitResult {
+    readonly written: readonly string[];
+    readonly skipped: readonly string[];
+}
+/** Run the scaffold. Returns which files were written vs left untouched. */
+export declare const runInit: ({ agent, cwd, roots }: InitArgs) => InitResult;
+//# sourceMappingURL=generate.d.ts.map

package/dist/init/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/init/generate.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,aAAa,6DAA8D,CAAA;AACxF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AA2FD,4EAA4E;AAC5E,eAAO,MAAM,OAAO,GAAI,uBAAuB,QAAQ,KAAG,UA6BzD,CAAA"}

package/dist/init/generate.js

@@ -0,0 +1,121 @@
+// `cairn init` — scaffold agent guidance from a single source of truth.
+// The SAME convention body is rendered into the format each agent reads:
+//  - Claude Code:   .claude/rules/docs-summaries.md          (frontmatter `paths:`)
+//  - GitHub Copilot: .github/instructions/docs-summaries.instructions.md (`applyTo:`)
+//  - Cross-tool:    a marked block in AGENTS.md — the file OpenCode (and Codex) read
+//    natively, so `--agent opencode` is a thin alias for `--agent agents`: no separate
+//    file format, just this block.
+//  - Claude/Codex:  .claude/skills/cairn/SKILL.md            (the writing methodology)
+//  - Claude Code:   a marked `@AGENTS.md` import in CLAUDE.md — Claude Code auto-loads
+//    CLAUDE.md at session start but never reads AGENTS.md on its own, so without this
+//    pointer the cross-tool block in AGENTS.md is invisible to it.
+// Plus a starter .cairnrc.json (only when absent).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CONVENTION_BODY, SKILL_BODY } from "./content.js";
+// Single source of truth for valid `--agent` values, so the CLI's choice list
+// (src/cli.ts) can never drift from what `runInit` actually understands.
+export const AGENT_TARGETS = ['agents', 'all', 'claude', 'copilot', 'opencode'];
+const AGENTS_START = '<!-- cairn:start -->';
+const AGENTS_END = '<!-- cairn:end -->';
+const rootsToGlobs = (roots) => roots.map((r) => `${r.replace(/\/+$/, '')}/**`);
+const ensureDir = (file) => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+};
+const write = (file, content, written) => {
+    ensureDir(file);
+    fs.writeFileSync(file, content.endsWith('\n') ? content : `${content}\n`);
+    written.push(file);
+};
+const claudeRule = (globs) => {
+    const paths = globs.map((g) => `  - '${g}'`).join('\n');
+    return `---\npaths:\n${paths}\n---\n\n${CONVENTION_BODY}`;
+};
+const copilotInstructions = (globs) => `---\napplyTo: '${globs.join(', ')}'\n---\n\n${CONVENTION_BODY}`;
+const skillFile = () => [
+    '---',
+    'name: cairn',
+    'description: Methodology for writing and maintaining the hierarchical documentation summary tree enforced by cairn. Use when authoring or refreshing docs summaries (X.summary.md / _SUMMARY.md).',
+    '---',
+    '',
+    SKILL_BODY,
+].join('\n');
+/** Insert or replace the cairn block in AGENTS.md, leaving other content intact. */
+const upsertAgentsBlock = (cwd, written) => {
+    const file = path.join(cwd, 'AGENTS.md');
+    const block = `${AGENTS_START}\n\n${CONVENTION_BODY.trimEnd()}\n\n${AGENTS_END}`;
+    let next;
+    if (fs.existsSync(file)) {
+        const existing = fs.readFileSync(file, 'utf8');
+        if (existing.includes(AGENTS_START) && existing.includes(AGENTS_END)) {
+            next = existing.replace(new RegExp(`${AGENTS_START}[\\s\\S]*?${AGENTS_END}`), block);
+        }
+        else {
+            next = `${existing.trimEnd()}\n\n${block}\n`;
+        }
+    }
+    else {
+        next = `# AGENTS.md\n\n${block}\n`;
+    }
+    fs.writeFileSync(file, next.endsWith('\n') ? next : `${next}\n`);
+    written.push(file);
+};
+/** Ensure CLAUDE.md imports AGENTS.md. Claude Code auto-loads CLAUDE.md (not AGENTS.md)
+ * at session start, so without this the AGENTS.md block cairn writes is never read. Leaves
+ * other CLAUDE.md content intact, and no-ops if an `@AGENTS.md` import is already present
+ * (hand-written or from a previous run). */
+const upsertClaudeMdImport = (cwd, written, skipped) => {
+    const file = path.join(cwd, 'CLAUDE.md');
+    const block = `${AGENTS_START}\n@AGENTS.md\n${AGENTS_END}`;
+    if (fs.existsSync(file)) {
+        const existing = fs.readFileSync(file, 'utf8');
+        if (existing.includes('@AGENTS.md')) {
+            skipped.push(file);
+            return;
+        }
+        const next = existing.includes(AGENTS_START) && existing.includes(AGENTS_END)
+            ? existing.replace(new RegExp(`${AGENTS_START}[\\s\\S]*?${AGENTS_END}`), block)
+            : `${existing.trimEnd()}\n\n${block}\n`;
+        fs.writeFileSync(file, next.endsWith('\n') ? next : `${next}\n`);
+    }
+    else {
+        fs.writeFileSync(file, `${block}\n`);
+    }
+    written.push(file);
+};
+const starterConfig = (roots) => `${JSON.stringify({
+    $schema: './node_modules/@sledorze/cairn/schema/cairn.schema.json',
+    ignore: ['**/node_modules/**'],
+    naming: { dirSummary: '_SUMMARY.md', fileSummarySuffix: '.summary.md' },
+    roots,
+    thresholdLines: 30,
+}, null, 2)}\n`;
+/** Run the scaffold. Returns which files were written vs left untouched. */
+export const runInit = ({ agent, cwd, roots }) => {
+    const globs = rootsToGlobs(roots);
+    const written = [];
+    const skipped = [];
+    const doClaude = agent === 'claude' || agent === 'all';
+    const doCopilot = agent === 'copilot' || agent === 'all';
+    const doAgents = agent === 'agents' || agent === 'opencode' || agent === 'all';
+    if (doClaude) {
+        write(path.join(cwd, '.claude/rules/docs-summaries.md'), claudeRule(globs), written);
+        write(path.join(cwd, '.claude/skills/cairn/SKILL.md'), skillFile(), written);
+        upsertClaudeMdImport(cwd, written, skipped);
+    }
+    if (doCopilot) {
+        write(path.join(cwd, '.github/instructions/docs-summaries.instructions.md'), copilotInstructions(globs), written);
+    }
+    if (doAgents || doClaude || doCopilot) {
+        upsertAgentsBlock(cwd, written);
+    }
+    const rc = path.join(cwd, '.cairnrc.json');
+    if (fs.existsSync(rc)) {
+        skipped.push(rc);
+    }
+    else {
+        write(rc, starterConfig(roots), written);
+    }
+    return { skipped, written };
+};
+//# sourceMappingURL=generate.js.map

package/dist/init/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/init/generate.ts"],"names":[],"mappings":"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"}

package/dist/io/DocsFs.d.ts

@@ -0,0 +1,30 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+export interface FileStat {
+    readonly mtimeMs: number;
+    readonly sizeBytes: number;
+}
+export interface DocsFsService {
+    readonly deleteFile: (abs: string) => Effect.Effect<void>;
+    readonly exists: (abs: string) => Effect.Effect<boolean>;
+    readonly listFiles: (roots: readonly string[]) => Effect.Effect<readonly string[]>;
+    readonly readFile: (abs: string) => Effect.Effect<string>;
+    readonly stat: (abs: string) => Effect.Effect<FileStat>;
+    readonly writeFile: (abs: string, content: string) => Effect.Effect<void>;
+}
+declare const DocsFs_base: Context.TagClass<DocsFs, "DocsFs", DocsFsService>;
+export declare class DocsFs extends DocsFs_base {
+}
+/** Live implementation bound to the Node filesystem. */
+export declare const DocsFsLive: Layer.Layer<DocsFs, never, FileSystem.FileSystem | Path.Path>;
+export interface TestFile {
+    readonly content: string;
+    readonly mtimeMs: number;
+}
+/**
+ * In-memory DocsFs layer for tests. `files` maps absolute path -> file.
+ * `writeFile` mutates the backing map so fix behaviour can be asserted.
+ */
+export declare const makeTestDocsFs: (files: Record<string, TestFile>) => Layer.Layer<DocsFs>;
+export {};
+//# sourceMappingURL=DocsFs.d.ts.map

package/dist/io/DocsFs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsFs.d.ts","sourceRoot":"","sources":["../../src/io/DocsFs.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAU,MAAM,QAAQ,CAAA;AAIvD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACzD,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACxD,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IAClF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACzD,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IACvD,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAC1E;;AAED,qBAAa,MAAO,SAAQ,WAA8C;CAAG;AAE7E,wDAAwD;AACxD,eAAO,MAAM,UAAU,+DA2DtB,CAAA;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CA2ClF,CAAA"}

package/dist/io/DocsFs.js

@@ -0,0 +1,95 @@
+// Filesystem capability for the docs checkers, expressed as an Effect service
+// so programs stay testable. `DocsFsLive` binds it to the real Node platform
+// (via @effect/platform-node); `makeTestDocsFs` provides an in-memory layer.
+import { FileSystem, Path } from '@effect/platform';
+import { Context, Effect, Layer, Option } from 'effect';
+import { toPosix } from "../core/paths.js";
+export class DocsFs extends Context.Tag('DocsFs')() {
+}
+/** Live implementation bound to the Node filesystem. */
+export const DocsFsLive = Layer.effect(DocsFs, Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    // `FileSystem.readDirectory` returns bare names (no Dirent-style type info),
+    // so telling files from directories still costs one `stat` per entry — but
+    // those stats are independent, so bounding their concurrency (rather than
+    // awaiting them one at a time) lets the underlying I/O overlap instead of
+    // serializing on a tree with many entries. 32 caps outstanding file
+    // descriptors well clear of typical `ulimit -n` defaults.
+    const STAT_CONCURRENCY = 32;
+    const listFiles = (roots) => Effect.gen(function* () {
+        const out = [];
+        for (const root of roots) {
+            const present = yield* fs.exists(root);
+            if (!present) {
+                continue;
+            }
+            const entries = yield* fs.readDirectory(root, { recursive: true });
+            const abses = yield* Effect.forEach(entries, (entry) => {
+                const abs = path.join(root, entry);
+                return fs.stat(abs).pipe(Effect.map((info) => (info.type === 'File' ? abs : null)));
+            }, { concurrency: STAT_CONCURRENCY });
+            for (const abs of abses) {
+                if (abs !== null) {
+                    // Normalise to POSIX so the pure planners see `/` paths on every OS.
+                    out.push(toPosix(abs));
+                }
+            }
+        }
+        return out;
+    }).pipe(Effect.orDie);
+    const stat = (abs) => fs.stat(abs).pipe(Effect.map((info) => ({
+        mtimeMs: Option.match(info.mtime, { onNone: () => 0, onSome: (d) => d.getTime() }),
+        sizeBytes: Number(info.size),
+    })), Effect.orDie);
+    return {
+        deleteFile: (abs) => fs.remove(abs).pipe(Effect.orDie),
+        exists: (abs) => fs.exists(abs).pipe(Effect.orDie),
+        listFiles,
+        readFile: (abs) => fs.readFileString(abs).pipe(Effect.orDie),
+        stat,
+        writeFile: (abs, content) => fs.writeFileString(abs, content).pipe(Effect.orDie),
+    };
+}));
+/**
+ * In-memory DocsFs layer for tests. `files` maps absolute path -> file.
+ * `writeFile` mutates the backing map so fix behaviour can be asserted.
+ */
+export const makeTestDocsFs = (files) => {
+    const store = new Map(Object.entries(files));
+    const dirsOf = () => {
+        const dirs = new Set();
+        for (const abs of store.keys()) {
+            let dir = abs.slice(0, abs.lastIndexOf('/'));
+            while (dir.length > 0 && !dirs.has(dir)) {
+                dirs.add(dir);
+                dir = dir.slice(0, dir.lastIndexOf('/'));
+            }
+        }
+        return dirs;
+    };
+    const service = {
+        deleteFile: (abs) => Effect.sync(() => void store.delete(abs)),
+        exists: (abs) => Effect.sync(() => store.has(abs) || dirsOf().has(abs)),
+        listFiles: (roots) => Effect.sync(() => [...store.keys()].filter((p) => roots.some((r) => p.startsWith(`${r}/`) || p === r))),
+        readFile: (abs) => Effect.sync(() => {
+            const f = store.get(abs);
+            if (!f) {
+                throw new Error(`ENOENT: ${abs}`);
+            }
+            return f.content;
+        }),
+        stat: (abs) => Effect.sync(() => {
+            const f = store.get(abs);
+            if (!f) {
+                throw new Error(`ENOENT: ${abs}`);
+            }
+            return { mtimeMs: f.mtimeMs, sizeBytes: Buffer.byteLength(f.content) };
+        }),
+        writeFile: (abs, content) => Effect.sync(() => {
+            store.set(abs, { content, mtimeMs: (store.get(abs)?.mtimeMs ?? 0) + 1 });
+        }),
+    };
+    return Layer.succeed(DocsFs, service);
+};
+//# sourceMappingURL=DocsFs.js.map