agent-docs-bootstrap 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follo
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-27
+
+### Fixed
+- Content hashes left out every dot file, so a user's own hidden file in a kit folder, such as `.claude/skills/docs-check/.notes.md`, did not count as a change and was deleted by an update or `--uninstall`. Only files the OS adds are left out now: `.DS_Store`, `._*`, `Thumbs.db`, `desktop.ini`. A folder without them hashes as in 0.4.0.
+- `LEGACY` lacked what 0.4.0 and 0.4.1 installed for `docs-check`, so installs stuck on 0.4.0 would stop recovering once `docs-check` changed. The hash is added, and `scripts/check.mjs` now installs every release tag and fails when `LEGACY` misses anything one of them installed; CI fetches the tags for it.
+
 ## [0.4.1] - 2026-10-27
 
 ### Fixed

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.4.1 --target claude
+   npx agent-docs-bootstrap@0.4.2 --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.4.1 --target claude
+npx agent-docs-bootstrap@0.4.2 --target claude
 ```
 
 **From a GitHub release tag**, when the npm registry is blocked or unavailable:
 
 ```bash
-npx github:TraneDev/agent-docs-bootstrap#v0.4.1 --target claude
+npx github:TraneDev/agent-docs-bootstrap#v0.4.2 --target claude
 ```
 
 **From a clone**, to read or change the kit first:
 
 ```bash
-git clone --branch v0.4.1 https://github.com/TraneDev/agent-docs-bootstrap.git ~/agent-docs-bootstrap
+git clone --branch v0.4.2 https://github.com/TraneDev/agent-docs-bootstrap.git ~/agent-docs-bootstrap
 node ~/agent-docs-bootstrap/install.mjs --target claude
 ```
 
@@ -135,7 +135,7 @@ Two skills are installed, `docs-bootstrap` and `docs-check`. The guides by other
 
 - 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;
+- files the OS adds to the kit's folders (`.DS_Store`, `._*`, `Thumbs.db`, `desktop.ini`) do not count as a change; a file of your own there, hidden or not, does, so it is never deleted;
 - 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

package/install.mjs

@@ -12,9 +12,9 @@
 //   opencode  skills → .agents/skills/   agents → .opencode/agents/*.md   commands → .opencode/commands/*.md
 // 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.
+// that hash or something a version of the kit wrote. OS files such as .DS_Store do not count; a user's own file,
+// hidden or not, does. 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';
@@ -65,7 +65,9 @@ for (const l of read(MARKER).split('\n').map(l => l.trim()).filter(l => l && !l.
   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.
+// Hashes of every path each released version installed (all targets, no model flags), so an install whose marker
+// lost its lines is still recognised after the kit changes. Every release adds the outgoing version's hashes;
+// nothing is ever removed. check.mjs installs each release tag and fails, listing the missing ones.
 const LEGACY = new Set([
   '00ca80d7077c0e4b', '122ae594f7eb38bd', '185ec7d02d9cf70b', '1f5a0fe496f38dd6', '3798ad63dd954bac',
   '4c36074d70c5a88c', '562d1e8f3a090ffd', '698cadefe39cb46f', '6acf8481d4dd6a1a', '72bcff6d0e5476ba',
@@ -73,6 +75,8 @@ const LEGACY = new Set([
   '900cf27ab683e5d1', '96288a3e60126264', '9e0e5c30da22c059', 'b45162299d9aa78b', 'c5d47d8811aa61ee',
   'c87450584ed42c8b', 'cf2f8a40c91f3c45', 'dac09810ceb351f7', 'dc418221c7363caa', 'f741ba5711364c55',
   'fceff4c3b3159c80', 'fd975138dcda6b38', 'fe412d3c3c312f7a',
+  // 0.4.0, 0.4.1
+  '7f6ef4c3f161abfa',
 ]);
 
 const skills = skillDirs();
@@ -242,16 +246,16 @@ function usage(code, msg) {
   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.
+// checkout with CRLF line endings still matches. Files the OS adds (.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); }
+// Only files the OS adds on its own. A user's own hidden file, such as .notes.md, is content and counts as a change.
+function isOsFile(name) { return /^(\.DS_Store|Thumbs\.db|desktop\.ini)$/i.test(name) || name.startsWith('._'); }
 // 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-docs-bootstrap",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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" },