Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
fix: Trial 2 lessons; release 0.4.1
- move: list links that name a moved doc by full address (a URL or
  file:///) for review (hazard H13)
- init: allow a protected doc at the docs root in rootAllowed; warn when
  Biome would reject the comments in docs-kit.json
- check: the exports error says an exports/ folder is not allowed
- /docs-kit-reorg: generators before moves; keep folders that hold a
  protected doc; archive is never a subject; "cannot move" vs "kept by
  choice"; tell the owner about code files changed only in a doc path
- DESIGN: H13, move step 10, Trial 2 result

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Sujit Gangadharan <gsujit@gmail.com>
  • Loading branch information
jisujit and claude committed Nov 13, 2026
commit c893746d352a22ddf0a0571070bf76642c00a1c4
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
{
"name": "docs-kit",
"description": "One layout for docs/ in any repo: a check that keeps it, a mover that keeps every link and path working, and notes and how-tos. Help: /docs-kit-help",
"version": "0.4.0",
"version": "0.4.1",
"source": "./",
"author": {
"name": "Techsilon LLC",
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "docs-kit",
"description": "One layout for docs/ in any repo: a check that keeps it, a mover that keeps every link and path working, and notes and how-tos. Help: /docs-kit-help",
"version": "0.4.0",
"version": "0.4.1",
"author": {
"name": "Techsilon LLC",
"email": "oss@techsilon.com",
Expand Down
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

All notable changes to docs-kit. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [semver](https://semver.org/).

## [0.4.1] - 2026-11-13

Fixes from Trial 2 (DESIGN §10).

### Changed

- `move` lists every link that names a moved doc by its full address, such as a GitHub URL to the repo's own file or a `file:///` link, under `REVIEW` (hazard H13). It does not rewrite them.
- `init` adds a protected doc at the docs root to `rootAllowed`, because it may not move, so the check can pass with it in place.
- `init` warns when the repo uses Biome, which rejects the comments in `docs-kit.json`, and names the fix.
- `check`: the exports error now says an `exports/` folder is not allowed, instead of reading as if the folder were missing.
- `/docs-kit-reorg`: the generator slice comes before the moves, and the largest move last; folders that hold a protected doc are kept; `archive` is never listed as a subject; each doc that stays gets one reason, "cannot move" or "kept by choice"; and the owner is told which code files changed only in a doc path, since a doc-sync gate may report them.

## [0.4.0] - 2026-11-13

### Added
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ docs-kit gives every repo the same `docs/` layout, a check that keeps it, and a
From the root of your repo, in a terminal:

```sh
npx github:techsilon-oss/docs-kit#v0.4.0 init --dry-run
npx github:techsilon-oss/docs-kit#v0.4.0 init
npx github:techsilon-oss/docs-kit#v0.4.1 init --dry-run
npx github:techsilon-oss/docs-kit#v0.4.1 init
npm install
```

Expand All @@ -41,7 +41,7 @@ In Claude Code, install the plugin once, then run `/docs-kit-init` in any repo:
| **Never** | Commits, pushes, sends data anywhere, or edits a file under `immutablePrefixes`. The Claude Code skills commit only after you say yes, and never push |
| **Depends on** | Node 22 or later, and git. No runtime dependencies: Node built-ins only |

**Pin a release.** `init` pins the devDependency to the tag it ran from (`github:techsilon-oss/docs-kit#v0.4.0`). Release tags never move. For a stricter pin, use the commit: `github:techsilon-oss/docs-kit#<commit>`. To vendor it instead, copy `scripts/docs-kit.mjs` and `scripts/lib/` into your repo and keep the banner and `VERSION` in `docs-kit.mjs`.
**Pin a release.** `init` pins the devDependency to the tag it ran from (`github:techsilon-oss/docs-kit#v0.4.1`). Release tags never move. For a stricter pin, use the commit: `github:techsilon-oss/docs-kit#<commit>`. To vendor it instead, copy `scripts/docs-kit.mjs` and `scripts/lib/` into your repo and keep the banner and `VERSION` in `docs-kit.mjs`.

## Uninstall

Expand Down
14 changes: 13 additions & 1 deletion docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,7 @@ For each pair (file or folder):
7. **Prints every file it changed,** and ends with `git status --porcelain`. The caller must stage all of them (hazard H9).
8. Runs `docs-kit check` at the end.
9. **Follows a renamed file by name** (hazard H12). When a move changes a file's name, not only its folder: a link label that is exactly the old file name, the old destination or the old repo path becomes the new one (`[OLD.md](OLD.md)` becomes `[NEW.md](NEW.md)`); every other line in a tracked text file that names the old file name alone, with no path, is listed for review and not rewritten, because a bare name in prose may mean something else.
10. **Lists links that spell out a full address** (hazard H13): a link to a moved doc by URL, such as a GitHub link to the repo's own file, or by `file:///`. It does not rewrite them, because it cannot tell this repo from another repo or machine.

### 6.3 Guided reorganisation — `/docs-kit-reorg` (skill)

Expand Down Expand Up @@ -235,7 +236,7 @@ The project's own agent instructions (branch rules, commit style, dependency rul

## 7. Hazards found in a real reorganisation

Each hazard below happened, or nearly happened, during a real reorganisation: H1 to H10 in one large `docs/` tree, H11 and H12 in Trial 1. Each has a guard in the tools. The audit step checks for all of them.
Each hazard below happened, or nearly happened, during a real reorganisation: H1 to H10 in one large `docs/` tree, H11 and H12 in Trial 1, H13 in Trial 2. Each has a guard in the tools. The audit step checks for all of them.

| # | Hazard | What goes wrong | Guard |
|---|---|---|---|
Expand All @@ -251,6 +252,7 @@ Each hazard below happened, or nearly happened, during a real reorganisation: H1
| H10 | A test scanner reads zero files after a move | The check passes vacuously | Every scanning check asserts a non-empty set |
| H11 | The proposal that records the reorganisation names the old paths | `move` rewrites the record's "old" column, so the record shows every file moving to where it already is | The proposal note goes in `immutablePrefixes` when it is written (L10) |
| H12 | A renamed file is named in a link label, or by its file name alone with no path | The link target follows the move, but the label still shows the old name, and the bare name is neither rewritten nor reported | `move` rewrites a label that is exactly the old name or path, and lists every other bare mention for review (§6.2 step 9) |
| H13 | A link names a moved doc by its full address: a URL to the repo's own file, or `file:///` | The link is not rewritten and not reported, so it breaks once the move reaches the branch the URL names | `move` lists every such link for review (§6.2 step 10) |

## 8. Distribution

Expand Down Expand Up @@ -296,6 +298,16 @@ docs-kit stands alone. When a repo also uses govkit, a thin module in govkit (bu
- `move` rewrote the proposal that recorded the move: H11, guarded by L10.
- When a move **renames** a file, two references go stale that `move` neither rewrites nor reports: a link label that shows the old file name (`[OLD.md](OLD.md)`: the target is rewritten, the label is not), and the old file name written alone, with no path. **Planned for 0.3:** `move` rewrites a link label that is exactly the old file name or path, and lists every other line in a tracked text file that names the old file name, for review. A move that keeps the name (L2) has neither problem.

**Trial 2 result (2026-11-13).** Adopted with `/docs-kit-reorg` in five slices: setup, folder maps and proposal, generator to snapshots, the moves, roles and how-tos. The owner answered the roles and approved the proposal once, plus one choice no default settled (below). The generator, in Python, now asks `docs-kit snapshot path` where to write and calls `docs-kit snapshot archive`; its outputs stay gitignored, and the check reports the topic as local-only. 13 docs moved as renames, with links rewritten across 71 files; the check passes and runs in the tests. What it taught (fixed in 0.4.1 unless marked):

- The exports error read as "the folder is missing". It now says an `exports/` folder is not allowed.
- A protected doc at the docs root could never pass the check, because it may not move. `init` now adds it to `rootAllowed`. The skill keeps folders that hold a protected doc, and never lists `archive` as a subject.
- The proposal mixed "cannot move" (protected) with "kept by choice" (a default), so the owner had to choose between them. The skill now gives each kept doc one of the two reasons.
- `docs-kit.json` has comments, and a linter that reads JSON strictly (Biome) rejected it. `init` now warns and names the fix.
- Links that spell out a full address (a GitHub URL to the repo's own file, `file:///`) were neither rewritten nor reported: H13, now reported.
- A move rewrites doc paths in code comments, so a doc-sync gate that maps code to docs reports them as code changes on the release pull request. The skill now tells the owner. **Not fixed here:** the lasting fix is in that gate (govkit), which can ignore a file whose only change is a doc path renamed in the same diff.
- The generator slice went before the moves, and the largest move last, so each problem showed on its own. The skill now orders the slices that way.

**Decided (2026-11-13):** the least-change defaults (§6.3, L1 to L9). In Trial 1 the owner was asked a dozen judgement calls (branch, dependency, test path, what to protect, folder and file renames, historical docs, new subjects, which docs become how-tos). Almost all had one safe answer. Defaults now settle those, so the owner answers `roles` and approves the proposal once. With that, 0.3's `protected` suggestions are written by `init` rather than only suggested, because protecting only adds safety.

## 11. Owner questions
Expand Down
6 changes: 3 additions & 3 deletions docs/guides/howto/HOWTO-adopt-docs-kit.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ Use the terminal you normally use for git, in the root folder of your repo.
1. See what `init` would write. It writes nothing:

```sh
npx github:techsilon-oss/docs-kit#v0.4.0 init --dry-run
npx github:techsilon-oss/docs-kit#v0.4.1 init --dry-run
```

2. Set it up:

```sh
npx github:techsilon-oss/docs-kit#v0.4.0 init
npx github:techsilon-oss/docs-kit#v0.4.1 init
```

3. If your repo has a `package.json`, fetch the devDependency that `init` added:
Expand All @@ -49,7 +49,7 @@ Use the terminal you normally use for git, in the root folder of your repo.
5. Add to `docs-kit.json` what only you know: other `protected` paths (a doc path that a database, a URL or code uses as a key), each with its reason.
6. Commit the files `init` listed.

If your repo must not get a new dependency, add `--no-package` in step 2. Then run the check with `npx github:techsilon-oss/docs-kit#v0.4.0 check`.
If your repo must not get a new dependency, add `--no-package` in step 2. Then run the check with `npx github:techsilon-oss/docs-kit#v0.4.1 check`.

## Check

Expand Down
2 changes: 1 addition & 1 deletion docs/guides/howto/HOWTO-upgrade-docs-kit.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ last_checked: 2026-11-13

## Steps for a repo

1. In `package.json`, change the devDependency to the new tag, for example `github:techsilon-oss/docs-kit#v0.4.0`.
1. In `package.json`, change the devDependency to the new tag, for example `github:techsilon-oss/docs-kit#v0.4.1`.
2. In a terminal, in the root folder of your repo, run `npm install`.
3. Run the check:

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "docs-kit",
"version": "0.4.0",
"version": "0.4.1",
"description": "One layout for docs/ in any repo: a check that keeps it, and a mover that keeps every link and path working.",
"license": "Apache-2.0",
"author": "Techsilon LLC <oss@techsilon.com>",
Expand Down
2 changes: 1 addition & 1 deletion scripts/docs-kit.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import { audit, formatAudit } from './lib/audit.mjs';
import { SnapshotError, archiveOlder, formatArchive, snapshotPath, topicDir } from './lib/snapshots.mjs';
import { writeIndex } from './lib/roles.mjs';

export const VERSION = '0.4.0';
export const VERSION = '0.4.1';

const USAGE = `docs-kit ${VERSION}

Expand Down
2 changes: 1 addition & 1 deletion scripts/lib/check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ export function check(root, cfg, { today = new Date() } = {}) {
const i = parts.indexOf('exports');
if (i !== -1 && i < parts.length - 1) exportDirs.add(parts.slice(0, i + 1).join('/'));
}
for (const e of exportDirs) errors.push(`${D}/${e}/: no exports/ tree; generated docs go to <subject>/snapshots/<topic>/`);
for (const e of exportDirs) errors.push(`${D}/${e}/: an exports/ folder is not allowed; move generated docs to <subject>/snapshots/<topic>/ (docs-kit snapshot)`);

// Rule 6: archive mirrors the live tree.
const archiveSubjects = new Set();
Expand Down
15 changes: 15 additions & 0 deletions scripts/lib/init.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,21 @@ export function detectConfig(root, docsRoot = DEFAULTS.docsRoot) {
}

const prot = protectNamedDocs(root, docsRoot, immutablePrefixes, listDocFiles(root, docsRoot), notes);
// A protected doc at the docs root cannot move, so the check must allow it there.
for (const p of Object.keys(prot)) {
const f = p.slice(docsRoot.length + 1);
if (f.includes('/') || rootAllowed.includes(f)) continue;
rootAllowed.push(f);
notes.push(`rootAllowed: ${p} stays at the docs root, because it is protected`);
}

// docs-kit.json has comments; a linter that reads every .json file strictly rejects them.
for (const f of ['biome.json', 'biome.jsonc']) {
if (existsSync(join(root, f))) {
notes.push(`${f}: Biome reads docs-kit.json as strict JSON and rejects its comments; exclude docs-kit.json in ${f}, or allow comments in it`);
break;
}
}

const config = {
docsRoot,
Expand Down
13 changes: 10 additions & 3 deletions scripts/lib/move.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync
import { join, posix } from 'node:path';
import { DEFAULTS, normalizeRel } from './config.mjs';
import { checkIgnored, gitMv, ignoredFiles, statusPorcelain, trackedFiles, untrackedFiles } from './git.mjs';
import { PathMap, findOldNames, findPiecedPaths, rewriteMarkdown, replaceRootPaths, rootPathRegex } from './rewrite.mjs';
import { PathMap, findAddressPaths, findOldNames, findPiecedPaths, rewriteMarkdown, replaceRootPaths, rootPathRegex } from './rewrite.mjs';

export class MoveError extends Error {}

Expand Down Expand Up @@ -105,6 +105,7 @@ export function planRewrites(root, plan, cfg = DEFAULTS) {
const immutableHits = [];
const piecedHits = [];
const nameHits = [];
const addressHits = [];
// H12: the old names of files whose name changes, not only their folder.
const oldNames = [...new Set(plan.filePairs.filter((p) => posix.basename(p.from) !== posix.basename(p.to)).map((p) => posix.basename(p.from)))];
const scanNames = (file, text) => { for (const h of findOldNames(text, oldNames)) nameHits.push({ file, ...h }); };
Expand Down Expand Up @@ -136,8 +137,9 @@ export function planRewrites(root, plan, cfg = DEFAULTS) {
}
if (next !== text) rewrites.push({ oldPath: file, newPath, content: next });
scanNames(newPath, next);
if (!inArchive) for (const h of findAddressPaths(next, keys)) addressHits.push({ file: newPath, ...h });
}
return { rewrites, immutableHits, piecedHits, nameHits };
return { rewrites, immutableHits, piecedHits, nameHits, addressHits };
}

function removeEmptyDirs(root, dir, stopAt, warnings) {
Expand All @@ -162,14 +164,15 @@ function removeEmptyDirs(root, dir, stopAt, warnings) {
*/
export function move(root, pairs, { cfg = DEFAULTS, dryRun = false } = {}) {
const plan = planMoves(root, pairs, cfg);
const { rewrites, immutableHits, piecedHits, nameHits } = planRewrites(root, plan, cfg);
const { rewrites, immutableHits, piecedHits, nameHits, addressHits } = planRewrites(root, plan, cfg);
const report = {
dryRun,
moves: plan.filePairs,
rewritten: rewrites.map((r) => r.newPath),
immutableHits,
piecedHits,
nameHits,
addressHits,
ignoredMoves: plan.ignoredMoves,
newlyVisible: [],
warnings: [],
Expand Down Expand Up @@ -221,6 +224,10 @@ export function formatMove(r) {
lines.push(`REVIEW: ${r.nameHits.length} line(s) name a renamed file by its old name alone; not rewritten, fix by hand:`);
for (const h of r.nameHits) lines.push(` ${h.file}:${h.line}: ${h.text} [${h.names.join(', ')}]`);
}
if (r.addressHits.length) {
lines.push(`REVIEW: ${r.addressHits.length} line(s) link to a moved path by a full address (a URL or file:///); not rewritten, fix by hand:`);
for (const h of r.addressHits) lines.push(` ${h.file}:${h.line}: ${h.text} [${h.paths.join(', ')}]`);
}
for (const w of r.warnings) lines.push(`WARNING ${w}`);
if (r.newlyVisible.length) {
lines.push(`DANGER: ${r.newlyVisible.length} file(s) that were ignored are no longer ignored. Fix .gitignore before you stage anything:`);
Expand Down
19 changes: 19 additions & 0 deletions scripts/lib/rewrite.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,25 @@ export function findOldNames(text, names) {
return hits;
}

/*
* Full-address links (a URL or an absolute path) that end in a moved path,
* such as https://host/org/repo/blob/main/docs/x/A.md in a link, or
* file:///c:/work/repo/docs/x/A.md. move cannot tell this repo from another
* repo or machine, so these are reported for review, never rewritten.
*/
export function findAddressPaths(text, keys) {
const hits = [];
if (!keys.length) return hits;
const re = new RegExp(`(?<=[${PATH_CHAR}]\\/)(${keys.map(escapeRe).join('|')})${AFTER}`, 'g');
const lines = text.split(/\r?\n/);
for (let n = 0; n < lines.length; n++) {
if (!/[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(lines[n])) continue;
const found = [...new Set([...lines[n].matchAll(re)].map((m) => m[1]))];
if (found.length) hits.push({ line: n + 1, text: lines[n].trim(), paths: found.sort() });
}
return hits;
}

/*
* Pieced-together paths (hazard H7): code that builds a moved path from
* quoted segments, such as join(root, "docs", "exports", "legal"). These are
Expand Down
2 changes: 1 addition & 1 deletion skills/docs-kit-init/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ On the answers, in order:
| `folder is not a configured subject` | A docs-root folder not in `subjects` | Adding it to `subjects`, or moving it |
| `missing (every subject folder needs a map)` | A subject folder with no `README.md` | Writing that README (a short map of the folder) |
| `missing (the front door)` | No `docs/README.md` | `init` writes one; if it is listed, re-run `init` |
| `no exports/ tree` | Generated docs in an `exports/` folder | Moving them to `<subject>/snapshots/<topic>/` |
| `an exports/ folder is not allowed` | Generated docs in an `exports/` folder | Moving them to `<subject>/snapshots/<topic>/` |
| `doc map file not found`, or a doc map path that does not exist | A gate names a doc that is not there | Fixing the map, or the doc's path |
| `how-tos are named HOWTO-<task>.md`, `last_checked` | A how-to's name or its freshness date | Renaming it with `move`, or checking the steps and setting `last_checked` |
| Role findings (`no roles:`, `How-tos by role`) | Only when `roles` is set | Adding `roles:` to each how-to, then `DOCS_KIT index` |
Expand Down
Loading
Loading