agent-docs-bootstrap 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follo
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-27
+
+### Fixed
+- A `.DS_Store` or other OS file inside an installed folder counted as a change: the first run skipped the path and dropped its marker line, and later runs called it "not installed by this kit", so updates stopped for the whole team once the marker was committed. Dot files, `Thumbs.db` and `desktop.ini` are now left out of content hashes; a folder without them hashes exactly as in 0.4.0.
+- A path that exists without a marker line but holds content a kit version wrote, byte for byte, is recognised, updated and listed again, so installs stuck on 0.4.0 recover with a normal run.
+- A shipped path the user changed keeps its marker line and old hash, so every run reports the same thing about it instead of "changed" first and "not installed by this kit" afterwards.
+- The installer exits non-zero and lists the paths it could not install when a shipped path is skipped, so an agent or CI notices an incomplete install. A changed path the kit no longer ships is only a warning.
+
+## [0.4.0] - 2026-10-27
+
+### Changed
+- `.agent-docs-bootstrap` lines are `<path> <content hash>`. A path is replaced or removed only if its content still matches what the kit wrote; lines without a hash, from 0.3.0 and earlier, are checked against the hashes of everything those versions installed.
+
+### Fixed
+- An update or `--uninstall` removed a listed path whatever was in it, so a skill the user had replaced with their own version under the same name, such as `grilling` after 0.2.0, was deleted. A changed path is now left in place as the user's, with a warning, and drops out of the marker. Subagent files a 0.3.0 or earlier install rendered with `--scout-model` or `--reader-model` do not match the known hashes and are left in place too: delete them and run the installer again.
+
 ## [0.3.0] - 2026-10-27
 
 ### Changed

package/README.md

@@ -17,7 +17,7 @@ You need Node.js 18+ and a git repository.
 1. From your project root, install the skills and subagents:
 
    ```bash
-   npx agent-docs-bootstrap@0.3.0 --target claude
+   npx agent-docs-bootstrap@0.4.1 --target claude
    ```
 
    Replace `claude` with `codex`, `opencode`, a list such as `claude,codex`, or `all`.
@@ -103,19 +103,19 @@ All options run the same installer from your project root. Pin the version: the
 **From npm** (recommended):
 
 ```bash
-npx agent-docs-bootstrap@0.3.0 --target claude
+npx agent-docs-bootstrap@0.4.1 --target claude
 ```
 
 **From a GitHub release tag**, when the npm registry is blocked or unavailable:
 
 ```bash
-npx github:TraneDev/agent-docs-bootstrap#v0.3.0 --target claude
+npx github:TraneDev/agent-docs-bootstrap#v0.4.1 --target claude
 ```
 
 **From a clone**, to read or change the kit first:
 
 ```bash
-git clone --branch v0.3.0 https://github.com/TraneDev/agent-docs-bootstrap.git ~/agent-docs-bootstrap
+git clone --branch v0.4.1 https://github.com/TraneDev/agent-docs-bootstrap.git ~/agent-docs-bootstrap
 node ~/agent-docs-bootstrap/install.mjs --target claude
 ```
 
@@ -131,7 +131,12 @@ Files are copied into the project, not linked, so they get committed with it.
 
 Two skills are installed, `docs-bootstrap` and `docs-check`. The guides by other authors that `docs-bootstrap` relies on travel inside it, in `docs-bootstrap/vendor/`, and are not registered as skills, so a skill of yours with the same name, such as `grilling`, never clashes with them.
 
-`.agent-docs-bootstrap` lists every installed path. The installer replaces or removes only those paths and never touches files it did not create: a path that already exists and is not listed there is skipped with a warning, and a line in the marker that is not shaped like a path the kit installs (for example `src` or `../x`, added by a bad merge) is ignored with a warning.
+`.agent-docs-bootstrap` lists every installed path with a hash of what was written. The installer replaces or removes a path only if it is listed there and its content still matches, so it never touches files it did not create or that you changed:
+
+- a path that exists but is not listed is skipped with a warning;
+- a listed path whose content you changed is left in place, with a warning, and the installer exits non-zero; a changed path the kit no longer ships, for example a skill you replaced with your own version, becomes yours and drops out of the marker;
+- files the OS adds to the kit's folders, such as `.DS_Store`, `Thumbs.db` or `desktop.ini`, do not count as a change;
+- a marker line not shaped like a path the kit installs (for example `src` or `../x`, added by a bad merge) is ignored with a warning.
 
 ### Other agents
 
@@ -144,7 +149,7 @@ What changes without the installer's targets:
 
 ### Update or remove
 
-- **Update:** run the installer again with the new version and commit the result. Paths the previous version installed and this one no longer ships are removed.
+- **Update:** run the installer again with the new version and commit the result. Paths the previous version installed and this one no longer ships are removed. Do not install an older version over a newer one: an older installer does not read the newer marker and treats the kit's files as yours. Run `--uninstall` with the newer version first.
 - **Remove:** run it with `--uninstall`. Everything listed in `.agent-docs-bootstrap` is deleted, along with the marker itself.
 
 <details>

package/install.mjs

@@ -10,15 +10,18 @@
 //   claude    skills → .claude/skills/   agents → .claude/agents/*.md
 //   codex     skills → .agents/skills/   agents → .codex/agents/*.toml
 //   opencode  skills → .agents/skills/   agents → .opencode/agents/*.md   commands → .opencode/commands/*.md
-// Installed paths are listed in .agent-docs-bootstrap; only those are ever replaced or removed, and only if a line
-// has the shape of a path the kit writes (<layout folder>/<kit name>). On an update, listed paths this version no
-// longer ships are removed.
+// Installed paths are listed in .agent-docs-bootstrap with a hash of what was written. A path is replaced or removed
+// only if its line has the shape of a path the kit writes (<layout folder>/<kit name>) and its content still matches
+// that hash or something a version of the kit wrote; OS files such as .DS_Store do not count. A changed path is left
+// in place and the run exits non-zero. On an update, listed paths this version no longer ships are removed under the
+// same rule, or left to the user if changed.
 // No network access, no changes to harness settings, no admin rights.
 
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
 
 const KIT = path.dirname(fileURLToPath(import.meta.url));
 const TARGETS = ['claude', 'codex', 'opencode'];
@@ -54,9 +57,37 @@ const layoutDirs = new Set(Object.values(LAYOUT).flatMap(L => Object.values(L)).
 // The marker is committed, so a bad merge or PR can add any line to it. Only a line shaped like a path the kit
 // writes, <layout folder>/<shipped name>[.md|.toml], is trusted; nothing else is ever replaced or removed.
 const isOwnedPath = (r) => layoutDirs.has(path.normalize(path.dirname(r))) && SHIPPED.has(path.basename(r).replace(/\.(md|toml)$/, ''));
-const markerLines = read(MARKER).split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('version='));
-for (const l of markerLines) if (!isOwnedPath(l)) warn(`ignored '${l}' in .agent-docs-bootstrap: not a path this kit installs`);
-const oldList = markerLines.filter(isOwnedPath);
+// Marker lines are `<path> <hash>`; versions up to 0.3.0 wrote the path alone, so their content is checked
+// against everything those versions installed (LEGACY).
+const old = new Map();
+for (const l of read(MARKER).split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('version='))) {
+  const [r, h] = l.split(/\s+/);
+  if (isOwnedPath(r)) old.set(r, h);
+  else warn(`ignored '${r}' in .agent-docs-bootstrap: not a path this kit installs`);
+}
+// Hashes of every path versions 0.1.0–0.3.0 installed (all targets, no model flags). Fixed: never edit.
+const LEGACY = new Set([
+  '00ca80d7077c0e4b', '122ae594f7eb38bd', '185ec7d02d9cf70b', '1f5a0fe496f38dd6', '3798ad63dd954bac',
+  '4c36074d70c5a88c', '562d1e8f3a090ffd', '698cadefe39cb46f', '6acf8481d4dd6a1a', '72bcff6d0e5476ba',
+  '790d7e6ae5034b3e', '79d9da94af685633', '7cd7eeac11324b51', '855778c0459cea17', '8c5adb3f63300a43',
+  '900cf27ab683e5d1', '96288a3e60126264', '9e0e5c30da22c059', 'b45162299d9aa78b', 'c5d47d8811aa61ee',
+  'c87450584ed42c8b', 'cf2f8a40c91f3c45', 'dac09810ceb351f7', 'dc418221c7363caa', 'f741ba5711364c55',
+  'fceff4c3b3159c80', 'fd975138dcda6b38', 'fe412d3c3c312f7a',
+]);
+
+const skills = skillDirs();
+const agents = AGENTS.map(n => parseAgent(path.join(KIT, 'agents', `${n}.md`)));
+const models = { 'docs-scout': a['scout-model'], 'docs-reader': a['reader-model'] };
+const COMMANDS = [['docs-bootstrap', "Build the project's reference documentation"], ['docs-check', "Optional: test the project's documentation with a fresh reader"]];
+const commandBody = (name, what) => `---\ndescription: ${JSON.stringify(`${what} (${name})`)}\n---\nLoad the \`${name}\` skill and follow it. Arguments from the developer, if any: $ARGUMENTS\n`;
+// What this version writes when no model is pinned. Content that matches it or LEGACY byte for byte is the kit's,
+// even where the marker lost its line (0.4.0 counted a .DS_Store as a change and dropped the line).
+const CURRENT = new Set([...skills.map(d => contentHash(d)),
+  ...TARGETS.flatMap(t => agents.map(ag => textHash(render(t, ag)))), ...COMMANDS.map(([n, w]) => textHash(commandBody(n, w)))]);
+const isKitContent = (h) => LEGACY.has(h) || CURRENT.has(h);
+// The path is the kit's and nobody changed it since it was installed.
+const isUnchanged = (r) => { const h = contentHash(abs(r)); return h === old.get(r) || isKitContent(h); };
+const changedNote = (r) => `${r} changed since it was installed, so it is left in place as yours`;
 if (a.uninstall) { uninstall(); process.exit(0); }
 
 if (!a.target) usage(1, 'Missing --target.');
@@ -69,23 +100,27 @@ if (!GLOBAL) {
     die(`No .git here (${BASE}) — is this the project root? Run from the root or add --yes.`);
 }
 
-const installed = new Set();
-const ours = (r) => oldList.includes(r);
+const installed = new Map();
+const released = new Set();
+const shipped = new Set();
+const skipped = [];
+// A shipped path the user changed keeps its marker line and old hash, so every run says the same thing about it.
 function writeOwned(r, fn) {
-  if (installed.has(r)) return false;
+  if (shipped.has(r)) return false;
+  shipped.add(r);
   const dst = abs(r);
-  if (exists(dst) && !ours(r)) { warn(`skipped ${r}: exists and was not installed by this kit`); return false; }
+  if (exists(dst)) {
+    const why = !old.has(r) && !isKitContent(contentHash(dst)) ? 'exists and was not installed by this kit'
+      : old.has(r) && !isUnchanged(r) ? 'changed since it was installed' : '';
+    if (why) { warn(`skipped ${r}: ${why}`); skipped.push(r); return false; }
+  }
   fs.rmSync(dst, { recursive: true, force: true });
   fs.mkdirSync(path.dirname(dst), { recursive: true });
   fn(dst);
-  installed.add(r);
+  installed.set(r, contentHash(dst));
   return true;
 }
 
-const skills = skillDirs();
-const agents = AGENTS.map(n => parseAgent(path.join(KIT, 'agents', `${n}.md`)));
-const models = { 'docs-scout': a['scout-model'], 'docs-reader': a['reader-model'] };
-
 for (const t of targets) {
   const L = LAYOUT[t];
   console.log(`\n${t}`);
@@ -98,26 +133,36 @@ for (const t of targets) {
     const r = `${L.agents}/${ag.name}.${ext}`;
     if (writeOwned(r, dst => fs.writeFileSync(dst, render(t, ag, models[ag.name])))) log(`agent  ${r}`);
   }
-  if (L.commands) for (const [name, what] of [['docs-bootstrap', "Build the project's reference documentation"], ['docs-check', "Optional: test the project's documentation with a fresh reader"]]) {
+  if (L.commands) for (const [name, what] of COMMANDS) {
     const r = `${L.commands}/${name}.md`;
-    const body = `---\ndescription: ${JSON.stringify(`${what} (${name})`)}\n---\nLoad the \`${name}\` skill and follow it. Arguments from the developer, if any: $ARGUMENTS\n`;
-    if (writeOwned(r, dst => fs.writeFileSync(dst, body))) log(`command /${name}`);
+    if (writeOwned(r, dst => fs.writeFileSync(dst, commandBody(name, what)))) log(`command /${name}`);
   }
 }
 
 // Paths an earlier version installed into these targets' folders and this version no longer ships.
 const ownDirs = new Set(targets.flatMap(t => Object.values(LAYOUT[t])));
-for (const r of oldList)
-  if (!installed.has(r) && ownDirs.has(path.dirname(r)) && exists(abs(r))) { fs.rmSync(abs(r), { recursive: true, force: true }); log(`removed  ${r} (no longer shipped)`); }
+for (const r of old.keys()) {
+  if (shipped.has(r) || !ownDirs.has(path.dirname(r)) || !exists(abs(r))) continue;
+  if (isUnchanged(r)) { fs.rmSync(abs(r), { recursive: true, force: true }); log(`removed  ${r} (no longer shipped)`); }
+  else { warn(`not removed: ${changedNote(r)}`); released.add(r); }
+}
 
-// Keep entries of earlier installs (e.g. another target) that are still on disk.
-const keep = oldList.filter(r => !installed.has(r) && exists(abs(r)));
-fs.writeFileSync(MARKER, [`version=${VERSION}`, ...keep, ...installed].join('\n') + '\n');
+// Keep entries of earlier installs (e.g. another target) and skipped shipped paths that are still on disk; a changed
+// path this version no longer ships is the user's and is no longer listed.
+const keep = [...old].filter(([r]) => !installed.has(r) && !released.has(r) && exists(abs(r)));
+fs.writeFileSync(MARKER, [`version=${VERSION}`, ...[...keep, ...installed].map(([r, h]) => h ? `${r} ${h}` : r)].join('\n') + '\n');
 
-console.log(`\nDone: agent-docs-bootstrap ${VERSION}, ${targets.join(', ')}${GLOBAL ? ' (global)' : ''}.`);
-if (!GLOBAL) log(`commit the installed folders and .agent-docs-bootstrap so the whole team gets the same version`);
-log('restart the agent session so it picks up the new skills and subagents');
-log('start with the docs-bootstrap skill (Claude Code /docs-bootstrap, Codex $docs-bootstrap, OpenCode /docs-bootstrap)');
+if (skipped.length) {
+  console.error(`\nIncomplete: agent-docs-bootstrap ${VERSION} could not install ${skipped.length} path(s):`);
+  for (const r of skipped) console.error(`  ${r}`);
+  console.error('They hold content this kit did not write. To get this version, move or delete them, then run the installer again.');
+  process.exitCode = 1;
+} else {
+  console.log(`\nDone: agent-docs-bootstrap ${VERSION}, ${targets.join(', ')}${GLOBAL ? ' (global)' : ''}.`);
+  if (!GLOBAL) log(`commit the installed folders and .agent-docs-bootstrap so the whole team gets the same version`);
+  log('restart the agent session so it picks up the new skills and subagents');
+  log('start with the docs-bootstrap skill (Claude Code /docs-bootstrap, Codex $docs-bootstrap, OpenCode /docs-bootstrap)');
+}
 
 // ---------- rendering
 function render(target, ag, model) {
@@ -166,11 +211,15 @@ function skillDirs() {
   return out;
 }
 function uninstall() {
-  if (!oldList.length) die(`Nothing to remove: no ${MARKER}.`);
+  if (!old.size) die(`Nothing to remove: no ${MARKER}.`);
   console.log(`Removing agent-docs-bootstrap from ${BASE}`);
-  for (const r of oldList) if (exists(abs(r))) { fs.rmSync(abs(r), { recursive: true, force: true }); log(`removed ${r}`); }
+  for (const r of old.keys()) {
+    if (!exists(abs(r))) continue;
+    if (isUnchanged(r)) { fs.rmSync(abs(r), { recursive: true, force: true }); log(`removed ${r}`); }
+    else warn(`not removed: ${changedNote(r)}`);
+  }
   fs.rmSync(MARKER, { force: true });
-  const dirs = new Set(oldList.flatMap(r => [path.dirname(r), path.dirname(path.dirname(r))]));
+  const dirs = new Set([...old.keys()].flatMap(r => [path.dirname(r), path.dirname(path.dirname(r))]));
   for (const d of [...dirs].sort((x, y) => y.length - x.length)) try { fs.rmdirSync(abs(d)); } catch {}
 }
 function parseArgs(argv) {
@@ -192,6 +241,27 @@ function usage(code, msg) {
   console.log(src.slice(0, src.findIndex(l => !l.startsWith('//'))).map(l => l.replace(/^\/\/ ?/, '')).join('\n'));
   process.exit(code);
 }
+// Content hash of an installed file or folder: relative names and text with line endings normalised, so a
+// checkout with CRLF line endings still matches. Files the OS adds (dot files such as .DS_Store, Thumbs.db,
+// desktop.ini) are left out; the kit ships none (check.mjs makes sure). The format must not change: markers and
+// LEGACY depend on it.
+function contentHash(p) {
+  const h = createHash('sha256');
+  const files = fs.lstatSync(p).isDirectory() ? listFiles(p).sort() : [''];
+  for (const f of files) h.update(`${f}\0${read(path.join(p, f)).replace(/\r\n/g, '\n')}\0`);
+  return h.digest('hex').slice(0, 16);
+}
+function isOsFile(name) { return name.startsWith('.') || /^(thumbs\.db|desktop\.ini)$/i.test(name); }
+// The same hash for text about to be written as a file.
+function textHash(text) {
+  return createHash('sha256').update(`\0${text.replace(/\r\n/g, '\n')}\0`).digest('hex').slice(0, 16);
+}
+function listFiles(dir, base = dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).filter(e => !isOsFile(e.name)).flatMap(e => {
+    const p = path.join(dir, e.name);
+    return e.isDirectory() ? listFiles(p, base) : [path.relative(base, p).split(path.sep).join('/')];
+  });
+}
 function read(p) { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } }
 function log(s) { console.log(`  ${s}`); }
 function warn(s) { console.error(`WARNING: ${s}`); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-docs-bootstrap",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Agent skills that build reference documentation for a codebase (glossary, ADRs, architecture, how-tos, AGENTS.md) through interviews with the team, with an optional check by a fresh agent. Works with any agent that runs skills; the installer sets up Claude Code, Codex and OpenCode.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/TraneDev/agent-docs-bootstrap.git" },

package/skills/docs-check/scripts/reader-run.mjs

@@ -38,7 +38,7 @@ const win = process.platform === 'win32';
 // Documents the kit builds; kit-installed paths and its run files never reach the reader. The marker is committed
 // and could hold any line, so only lines shaped like an installed path count (a line `docs` would hide every document).
 const KIT_DIRS = ['.claude/skills', '.claude/agents', '.agents/skills', '.codex/agents', '.opencode/agents', '.opencode/commands'];
-const kitPaths = read(path.join(ROOT, '.agent-docs-bootstrap'), '', true).split('\n').map(l => l.trim())
+const kitPaths = read(path.join(ROOT, '.agent-docs-bootstrap'), '', true).split('\n').map(l => l.trim().split(/\s+/)[0])
   .filter(l => KIT_DIRS.includes(path.posix.dirname(l)) && /^[a-z0-9-]+(\.md|\.toml)?$/.test(path.posix.basename(l)));
 const isKit = (p) => p === '.agent-docs-bootstrap' || p.startsWith('docs/agents/') || kitPaths.some(k => p === k || p.startsWith(k + '/'));
 // README and other files stay as they were in the parent commit, like the code: they are the project as it was,