diff --git a/CHANGELOG.md b/CHANGELOG.md index e00e8b2..09835f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - The handover names why a workflow earns no CI badge and stops there: it never proposes moving, renaming, or editing the workflow file, not even as a hint that a misplaced file belongs in `.github/workflows/` (#26). +- A Node CLI with a `bin` field is installed as that command — from the + registry when publication is evidenced, otherwise `npm install --global .` + from a checkout — and its help output is pointed to by the help command, + never transcribed into the README (#24). ## 1.0.0 - 2026-11-12 diff --git a/skills/github-readme-generator/references/readme-structure.md b/skills/github-readme-generator/references/readme-structure.md index 5a2a9e5..92e1735 100644 --- a/skills/github-readme-generator/references/readme-structure.md +++ b/skills/github-readme-generator/references/readme-structure.md @@ -148,6 +148,13 @@ Beyond the table, let language conventions decide what a reader needs: mentions the vendor publish or migration step only when the repository contains one. Version constraints come from `require`, never from the CI matrix alone. +- **Node CLI** — a `package.json` with a `bin` field installs the command it + names, never `node bin/.js`. Use the registry command + (`npm install --global `) only when publication is evidenced — a release + workflow that publishes, existing docs, or a registry entry you read. + Otherwise install from a checkout: clone the evidenced remote, then + `npm install --global .` (the lock file's package manager equivalent when one + is proven). The quick start then invokes the `bin` name. - **Typed languages** — prefer an example that shows the types a caller gets back, when it costs no extra lines. - **Applications of any language** — the quick start describes environment setup @@ -256,7 +263,9 @@ domain, not filler that would fit any project. - **Application** — the quick start must describe a verified path from a clean environment to a first run. - **CLI** — show the real install command, the smallest verified invocation, and - a pointer to the full help output. + the help command (` --help`) as the pointer to the full option list. Never + transcribe the help output: no `Options` or `Usage` section copying it, and at + most the options the quick start itself uses. - **Monorepo** — explain the purpose of the whole, then link to each package README. Never mix per-package commands into the root instructions. - **No documentation site** — the README must carry a sufficient quick start diff --git a/skills/github-readme-generator/references/validation-checklist.md b/skills/github-readme-generator/references/validation-checklist.md index 2396254..6ca2313 100644 --- a/skills/github-readme-generator/references/validation-checklist.md +++ b/skills/github-readme-generator/references/validation-checklist.md @@ -27,7 +27,9 @@ becomes a line in the handover summary. three sentences, `Installation` shows the main install command itself, and a warning about overwritten files sits next to its command. 10. No sentence merely announces the block below it, and nothing is stated twice - in two sections. + in two sections. A CLI's help output is pointed to by its help command, never + transcribed, and a `bin` command is installed as `readme-structure.md` § + *Ecosystem specifics* says. 11. The diff touches only documentation, within the agreed scope. 12. Every section outside the install path was run through the gate in `section-split.md`. Each moved section left a summary of two to four lines diff --git a/tests/scenarios.md b/tests/scenarios.md index 5cf1dea..f508d04 100644 --- a/tests/scenarios.md +++ b/tests/scenarios.md @@ -162,7 +162,7 @@ means the scenario has not been run since this log was started. | --- | --- | --- | | 1 | 2026-11-12, Claude Code 2.1.322, `claude -p "Update the README for this repository." --permission-mode acceptEdits --setting-sources project` | Partial (#23). Banner kept, license and Tests badges correct, two-sentence intro, install command and first example in place, Support / Postcardware / Alternatives removed. The Packagist version and downloads badges were dropped because publication could not be verified offline, and the documentation link was removed instead of delegated to. | | 2 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. `npm start` and `npm test` from scripts, `npm install` backed by the lock file, Node 20 from `engines`, configuration limited to the four `.env.example` names, no deployment section. | -| 3 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Fail (#24). The smallest invocation comes from the tests, but `Installation` is a `git clone` instead of the manifest `bin` install path, and the full help text is transcribed into an `Options` section instead of referenced. | +| 3 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. `Installation` clones the remote and runs `npm install --global .` (no publish evidence), the smallest invocation `slugify "Hello, World!"` → `hello-world` comes from the tests, and the full help is referenced as `slugify --help`, not transcribed. | | 4 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. The root README explains the npm workspace, links all three package READMEs, and shows only root `npm install` and `npm test`. | | 5 | 2026-11-12, Claude Code 2.1.322, `claude -p "Update the README for this repository." --permission-mode acceptEdits --setting-sources project` | Partial (#25). Logo and hand-written paragraph survive, all five stale items fixed, only `README.md` changed. But the header was rebuilt and sections renamed and added to follow the README standard — more than the outdated parts this scenario allows. | | 6 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. No install command, license claim, badge, or `TODO`; the handover names the missing manifest, license, and tests. Minor: a Python version was inferred from annotation syntax, disclosed as an inference. |