Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
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
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.3.1",
"version": "0.4.0",
"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.3.1",
"version": "0.4.0",
"author": {
"name": "Techsilon LLC",
"email": "oss@techsilon.com",
Expand Down
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,20 @@

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.0] - 2026-11-13

### Added

- `/docs-kit-reorg`: the guided reorganisation (DESIGN §6.3). It audits the docs, writes one proposal that applies the least-change defaults, asks the owner only for the roles and one approval, then moves the docs in slices, routes generators through `docs-kit snapshot`, and adds the check to the tests.
- `docs-kit audit [--json]`: a read-only inventory before a reorganisation: the docs root and its folders, exports trees, code inside the docs folder, generators, ignored files and `.gitignore` rules, docs that immutable files name, agent instructions, how-to look-alikes, and every reference to a doc from outside the docs folder.
- `docs-kit snapshot path <topic>` and `docs-kit snapshot archive <topic>` (DESIGN §6.6): where a generator in any language writes today's snapshot, and archiving the older ones to `archive/<subject>/snapshots/<topic>/`. The archive refuses any other folder (hazard H1), and fails loudly when an ignored snapshot would become visible (hazard H4).
- How-to: [Route generated docs to snapshots](docs/guides/howto/HOWTO-route-generated-docs.md), with Python and Node examples that the tests run.

### Changed

- `check`: a snapshot topic whose folder git ignores is reported as local-only, instead of failing as "no dated snapshots".
- `/docs-kit-init` hands the reorganisation to `/docs-kit-reorg`.

## [0.3.1] - 2026-11-13

docs-kit now follows the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md). See [Upgrading](docs/UPGRADING.md#031).
Expand Down
14 changes: 9 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ docs-kit gives every repo the same `docs/` layout, a check that keeps it, and a
- **Every doc has one place.** The front door, `docs/README.md`, lists one folder per subject, and each folder has a map.
- **A test fails when a doc is in the wrong place**, when a folder has no map, or when a file another tool reads is missing.
- **You move a doc and nothing breaks.** `docs-kit move` rewrites every link and every path to it: in other docs, scripts, config, CI workflows and agent instructions. It never edits a file that must not change, such as an applied migration.
- **Generated docs land in one known place.** A report script asks `docs-kit snapshot path` where to write, gets a dated name, and archives the older copies with `docs-kit snapshot archive`, in any language.
- **Readers find the steps for their own role.** How-tos name who they are for, and the front door lists them by role.
- **Notes and how-tos do not get lost in chats.** In Claude Code, `/docs-kit-pin` saves a discussion or a set of steps to its place, with `.docx` and `.pdf` copies if you ask.

Expand All @@ -15,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.3.1 init --dry-run
npx github:techsilon-oss/docs-kit#v0.3.1 init
npx github:techsilon-oss/docs-kit#v0.4.0 init --dry-run
npx github:techsilon-oss/docs-kit#v0.4.0 init
npm install
```

Expand All @@ -34,13 +35,13 @@ In Claude Code, install the plugin once, then run `/docs-kit-init` in any repo:
| | |
|---|---|
| **Reads** | The files git tracks, and `docs-kit.json` at the repo root |
| **Writes** | `init`: `docs-kit.json`, `docs/README.md` if missing, two keys in `package.json`, and the test file you name. It never overwrites a file. `move`: moves files with `git mv`, and rewrites the links and paths that name them. `index`: one marked section of `docs/README.md`. `print`: `.docx` and `.pdf` copies beside the source |
| **Writes** | `init`: `docs-kit.json`, `docs/README.md` if missing, two keys in `package.json`, and the test file you name. It never overwrites a file. `move`: moves files with `git mv`, and rewrites the links and paths that name them. `index`: one marked section of `docs/README.md`. `print`: `.docx` and `.pdf` copies beside the source. `snapshot archive`: moves older snapshots to the archive folder. `audit` and `check` write nothing |
| **Runs** | `git`. `print` runs `pandoc` when it is installed |
| **Network** | docs-kit makes no network calls. `npx`, `npm install` and the plugin install download docs-kit from GitHub |
| **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.3.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`.
**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`.

## Uninstall

Expand All @@ -53,16 +54,19 @@ In Claude Code, install the plugin once, then run `/docs-kit-init` in any repo:
| `docs-kit init` | Sets up a repo in one step: a `docs-kit.json` that describes the docs as they are, the front door, a pinned devDependency, the check as a test | [Commands](docs/reference/COMMANDS.md#docs-kit-init) |
| `docs-kit check` | The layout check. Exit 0 when the layout holds, 1 with a list when it does not | [Commands](docs/reference/COMMANDS.md#docs-kit-check) |
| `docs-kit move` | Moves docs and keeps every link and path working | [Commands](docs/reference/COMMANDS.md#docs-kit-move) |
| `docs-kit audit` | Read-only inventory before a reorganisation: what must move, generators, ignored files, every reference to a doc | [Commands](docs/reference/COMMANDS.md#docs-kit-audit) |
| `docs-kit snapshot` | Where a generator writes today's snapshot, and archiving the older ones | [Route generated docs](docs/guides/howto/HOWTO-route-generated-docs.md) |
| `docs-kit index` | Writes the "How-tos by role" section of the front door | [Commands](docs/reference/COMMANDS.md#docs-kit-index) |
| `docs-kit print` | Makes `.docx` and `.pdf` print copies with pandoc | [Commands](docs/reference/COMMANDS.md#docs-kit-print) |
| `/docs-kit-init` | Claude Code: applies the setup defaults, explains what the check found, commits on your yes, and leads the reorganisation | [Adopt docs-kit](docs/guides/howto/HOWTO-adopt-docs-kit.md) |
| `/docs-kit-reorg` | Claude Code: audits the docs, writes one proposal, asks only for the roles and one approval, then moves the docs in slices | [Reorganise a docs folder](docs/guides/howto/HOWTO-reorganise-a-docs-folder.md) |
| `/docs-kit-pin` | Claude Code: saves a discussion as a dated note, or steps as a how-to | [DESIGN §6.4](docs/DESIGN.md#64-pins-and-how-tos--docs-kit-pin-skill) |
| `/docs-kit-help` | Claude Code: answers a question from the docs of the version you have | [FAQ](docs/FAQ.md) |

## Docs

- [Front door](docs/README.md): every doc, by subject.
- [How-tos](docs/guides/README.md): adopt, reorganise, print, upgrade, remove.
- [How-tos](docs/guides/README.md): adopt, reorganise, route generated docs, print, upgrade, remove.
- [Commands](docs/reference/COMMANDS.md): every command, option, finding and exit code.
- [FAQ](docs/FAQ.md) and [Upgrading](docs/UPGRADING.md).
- [Design](docs/DESIGN.md): the layout rule, and why each part works the way it does.
Expand Down
19 changes: 11 additions & 8 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# docs-kit — design spec

> **Status:** draft 2026-10-31; owner decisions added 2026-11-12 (§11 answered, §3, §4.1, §10). Rollout step 0.1 (`docs-kit.json`, `check` with how-tos by role, `index`, `move`, hazard tests) was released as v0.1.0 on 2026-11-12; see [CHANGELOG.md](../CHANGELOG.md). Step 0.2 (`init` and the plugin with `/docs-kit-init`, §6.7) was released as v0.2.0 on 2026-11-12, and v0.2.1 (setup in two answers) the same day. Trial 1 was completed on 2026-11-13. Step 0.3 (`/docs-kit-pin`, `print`, `init` protecting what immutable files name, `move` following renamed files) is v0.3.0. v0.3.1 (2026-11-13) brings docs-kit in line with the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md): skill names with the `docs-kit-` prefix, `/docs-kit-help`, pre-approval of the plugin's own scripts only, Apache-2.0, and docs that follow the layout. Later steps are not built yet.
> **Status:** draft 2026-10-31; owner decisions added 2026-11-12 (§11 answered, §3, §4.1, §10). Rollout step 0.1 (`docs-kit.json`, `check` with how-tos by role, `index`, `move`, hazard tests) was released as v0.1.0 on 2026-11-12; see [CHANGELOG.md](../CHANGELOG.md). Step 0.2 (`init` and the plugin with `/docs-kit-init`, §6.7) was released as v0.2.0 on 2026-11-12, and v0.2.1 (setup in two answers) the same day. Trial 1 was completed on 2026-11-13. Step 0.3 (`/docs-kit-pin`, `print`, `init` protecting what immutable files name, `move` following renamed files) is v0.3.0. v0.3.1 (2026-11-13) brings docs-kit in line with the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md): skill names with the `docs-kit-` prefix, `/docs-kit-help`, pre-approval of the plugin's own scripts only, Apache-2.0, and docs that follow the layout. Step 0.4 (`/docs-kit-reorg`, `docs-kit audit`, `docs-kit snapshot`) is v0.4.0; its done-when is Trial 2. Later steps are not built yet.
> **Owner:** Techsilon LLC. **Decisions in this file:** marked **Decided**. Everything else is a proposal until the owner approves it.

---
Expand Down Expand Up @@ -146,9 +146,9 @@ For each pair (file or folder):

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

For a repo that does not follow the rule. Never moves anything before the owner approves the proposal.
For a repo that does not follow the rule. Never moves anything before the owner approves the proposal. **Built in 0.4** as `/docs-kit-reorg`, with `docs-kit audit` for step 1.

1. **Audit** (read-only): inventory every file under `docs/` and every doc path referenced outside it; group by likely subject; find generators, gitignore rules, path-based keys and pieced-together paths (the hazard list is the checklist).
1. **Audit** (read-only, `docs-kit audit`): inventory every file under `docs/` and every doc path referenced outside it; group by likely subject; find generators, gitignore rules, path-based keys and pieced-together paths (the hazard list is the checklist).
2. **Proposal:** the subject list, the old → new table, the protected paths with reasons, the hazards found, and the slices. Written as a pin (`docs/notes/`) so it survives the session. It applies the least-change defaults below and lists each one it applied, so the owner can override any of them.
3. **Owner approves** the whole proposal once. The only question asked before that is the `roles` list, when the repo will have how-tos. Each slice's pull request is then merged by the owner as usual; a slice raises a new question only when the check, the tests or `move` show something the proposal did not foresee.
4. **Slices:** one pull request per slice (for example: front door and READMEs; one subject per slice; generators last). Each slice: `move --dry-run`, `move`, run the project's tests and `check`, stage everything changed, confirm a clean working tree, open the PR.
Expand Down Expand Up @@ -194,11 +194,14 @@ Makes `.docx` and `.pdf` beside the source with the naming rule, and removes the

For projects that generate docs:

- `snapshotDir(topic)` returns `docs/<subject>/snapshots/<topic>/` from `snapshotTopics`. **An unknown topic is an error**, never a default folder.
**Built in 0.4** as `scripts/lib/snapshots.mjs` and the `docs-kit snapshot` command, so a generator in any language uses it: `docs-kit snapshot path <topic>` prints where today's snapshot goes, and `docs-kit snapshot archive <topic>` archives the older ones. A Python port is not needed.

- `topicDir(topic)` returns `docs/<subject>/snapshots/<topic>/` from `snapshotTopics`. **An unknown topic is an error**, never a default folder.
- `archiveOlder(dir, keep)` moves older snapshots to `archive/<subject>/snapshots/<topic>/`. **It refuses any folder that is not a `snapshots/<topic>/` folder** (hazard H1).
- File names carry the date: `<TOPIC>_<YYYY-MM-DD>.md`.
- File names carry the date: `<TOPIC>_<YYYY-MM-DD>.<ext>`.
- **Gitignored topics.** A generator may keep its snapshots out of git, made on demand. When git ignores a topic's folder, `check` reports the topic as local-only instead of failing H10, and `archive` fails loudly (exit 1) when it moves an ignored file to a place git does not ignore (H4).

Node first. A Python port is a later option, only if a trial project needs it.
Node only. Trial 2's generator is Python; it calls the command instead of a port.

### 6.7 Setup — `docs-kit init` and `/docs-kit-init`

Expand Down Expand Up @@ -251,8 +254,8 @@ Each hazard below happened, or nearly happened, during a real reorganisation: H1

## 8. Distribution

- **Plugin:** the skills (`/docs-kit-init`, `/docs-kit-pin` and `/docs-kit-help`, then `/docs-kit-reorg`) as a Claude Code plugin from this repo, which is also its marketplace (`.claude-plugin/`). The skills run the plugin's own copy of `scripts/docs-kit.mjs`.
- **Scripts:** `scripts/docs-kit.mjs` with subcommands `init`, `check`, `index`, `move`, `print`, plus `lib/snapshots.mjs`. Usable through `npx` from this repo, as a devDependency pinned to a tag, or vendored.
- **Plugin:** the skills (`/docs-kit-init`, `/docs-kit-reorg`, `/docs-kit-pin` and `/docs-kit-help`) as a Claude Code plugin from this repo, which is also its marketplace (`.claude-plugin/`). The skills run the plugin's own copy of `scripts/docs-kit.mjs`.
- **Scripts:** `scripts/docs-kit.mjs` with subcommands `init`, `check`, `audit`, `index`, `move`, `print` and `snapshot` (`lib/snapshots.mjs`). Usable through `npx` from this repo, as a devDependency pinned to a tag, or vendored.
- **Versioning:** semver and a `CHANGELOG.md`. A vendored copy records its version. Release tags never move (a tag ruleset blocks it).
- **License:** Apache License 2.0 with a `NOTICE`, from 0.3.1. Earlier releases stay MIT.
- **The kit standard:** docs-kit follows the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md). Tests enforce its plugin rules (skill prefix, `allowed-tools`, help skill, license) and its documentation rules for docs-kit's own docs (the layout, the commands they show, the version they pin, their links).
Expand Down
4 changes: 4 additions & 0 deletions docs/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ Because the check fails. A failing test would block every commit while you reorg

A file that `move` never edits, such as an applied migration, names that doc by its path. Moving the doc would leave that file pointing at nothing, for good. If the reason no longer holds, remove the path from `protected`. See [DESIGN §6.3, default L3](DESIGN.md#63-guided-reorganisation--docs-kit-reorg-skill).

## Our generated docs are gitignored. Does the check fail on them?

No. If git ignores a snapshot topic's folder, the check reports the topic as local-only, and does not ask for its snapshots. Keep the archive folder ignored too. See [Route generated docs to snapshots](guides/howto/HOWTO-route-generated-docs.md).

## Can a release change after I pin it?

No. Release tags never move: a bad release is fixed by a new release. For a stricter pin, use a commit instead of a tag. See [What it does on your machine](../README.md#what-it-does-on-your-machine).
Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Where to find things. Each subject folder has a `README.md` that maps it.

- [guides](guides/README.md): how-tos to adopt, reorganise, print, upgrade and remove docs-kit.
- [guides](guides/README.md): how-tos to adopt, reorganise, route generated docs, print, upgrade and remove docs-kit.
- [reference](reference/README.md): every command, option, finding and exit code.

At the docs root:
Expand Down
1 change: 1 addition & 0 deletions docs/guides/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Step-by-step how-tos. Each one does one task, and says when its steps were last

- [Adopt docs-kit in a repo](howto/HOWTO-adopt-docs-kit.md)
- [Reorganise a docs folder](howto/HOWTO-reorganise-a-docs-folder.md)
- [Route generated docs to snapshots](howto/HOWTO-route-generated-docs.md)
- [Print a doc as .docx and .pdf](howto/HOWTO-print-a-doc.md)
- [Upgrade docs-kit](howto/HOWTO-upgrade-docs-kit.md)
- [Remove docs-kit](howto/HOWTO-remove-docs-kit.md)
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.3.1 init --dry-run
npx github:techsilon-oss/docs-kit#v0.4.0 init --dry-run
```

2. Set it up:

```sh
npx github:techsilon-oss/docs-kit#v0.3.1 init
npx github:techsilon-oss/docs-kit#v0.4.0 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.3.1 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.0 check`.

## Check

Expand Down
Loading
Loading