@rungs/cli 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,7 @@
 # rungs
 
-**Installs and maintains a repository's agentic development system.**
+**rungs CLI — repository infrastructure for coding agents.** It installs and
+maintains a repository's agentic development system.
 
 Your agent has instructions. Do they have gates? Is your backlog's status field
 telling the truth about what actually merged? That thing you noticed last
@@ -10,6 +11,22 @@ rungs scaffolds the parts of a working setup — agent instructions, skills, wor
 tracking, findings, decision records, validation gates — as **modules you pick**,
 then keeps checking that they still say what they said.
 
+**Start read-only.** `doctor` writes nothing, works on repos that never installed
+anything, and ends by naming one command:
+
+```console
+$ npx @rungs/cli doctor
+  ci             theirs
+      1× .github/workflows/*.yml  e.g. .github/workflows/ci.yml
+
+  1 present · 0 different paradigm · 14 absent
+
+  Next
+  rungs add ci  — adopt what you already built, in place
+```
+
+Once you have run that:
+
 ```console
 $ rungs init . tracked
   instructions   3 create
@@ -47,7 +64,7 @@ So rungs does not ship a good idea about how to work. It ships **what four repos
 learned, with the incident attached**. Every module declares its provenance, and
 `doctor` quotes that incident back when a gate it installed has never fired:
 
-> `check-findings-register` has run 340 times and never fired. It exists because
+> `audit-output-is-rows` has run 340 times and never fired. It exists because
 > one repo produced 268 audit reports with no register to close them into. Is
 > that still a risk here — or is this gate scoped too narrowly?
 
@@ -67,6 +84,9 @@ command to run next. Once you have run that:
 **[your first hour](docs/getting-started.md)** — which of the new files matter,
 what the installed skills are for, and what to do when a gate goes red.
 
+New to the vocabulary? **[The nine words this page uses](docs/glossary.md)**,
+defined once each.
+
 Requires **Node 22.18+**. The published package ships a bundled JavaScript entry point; the source
 checkout still runs the TypeScript sources directly with `node`.
 
@@ -109,6 +129,7 @@ reported as diverged and left alone.
 | --- | --- |
 | `rungs init [path] [profile]` | Scaffold — `minimal` · `tracked` · `disciplined` · `hardened` · `fleet` |
 | `rungs doctor [path]` | What does this repo already have? Works on repos that never installed anything |
+| `rungs doctor --explain` | Also run the detectors over what it found — evidence rows, never a score |
 | `rungs add <module…>` | Install one module, resolving dependencies and adopting what exists |
 | `rungs check [path]` | Run the gates, record the ledger |
 | `rungs render [path]` | Re-emit path-scoped rules for each harness |
@@ -116,13 +137,16 @@ reported as diverged and left alone.
 | `rungs eject [path]` | Materialise the engines; stop depending on rungs |
 | `rungs setup git [path]` | Install the merge drivers `.gitattributes` names |
 | `rungs modules` | List the set and audit the manifests |
+| `rungs backlog archive` | Move finished items to `archive/`, repointing every link that cites them |
 
 | Option | Effect |
 | --- | --- |
 | `--dry-run` | Report what would happen, write nothing. Any write command |
+| `--explain` | `doctor`: run the detectors too. Read-only, and it runs no command your repo owns |
 | `--into <path>` | `add`: install into this repo rather than the working directory |
 | `--set <module>.<param>=<value>` | `add` / `init`: override a module parameter. Repeatable, and `--set m.p=v` works too |
 | `--confirm-threshold` | `add`: install a module whose rung is above this repo |
+| `--confirm-paradigm` | `add`: install a module this repo already solves another way |
 | `--apply` | `upgrade`: write the changes rather than preview them |
 | `--fast` / `--full` | `check`: pick the gate tier, as the positional also does |
 | `--copilot` | Also emit Copilot instruction files |
@@ -153,6 +177,12 @@ Full specification: [`docs/design/module-catalog.md`](docs/design/module-catalog
 
 ## Which agents
 
+**Bring your own.** rungs is not a methodology and not an orchestrator: it does
+not decide how your agent plans, specifies, or executes. It checks that the
+repository underneath stays coherent while it does — which is why it composes
+with whatever harness or spec-driven process you already run rather than
+replacing one. `AGENTS.md` is embraced, not competed with.
+
 Skills are **spec-compliant Agent Skills**, portable to Claude Code, Codex,
 Cursor, Copilot, Gemini CLI and 40+ others without translation.
 
@@ -182,12 +212,19 @@ Four promises that shape everything else:
 
 ## Status
 
-**Release candidate, v0.1.1** — prepared locally as
-[`@rungs/cli`](https://www.npmjs.com/package/@rungs/cli); the public `latest` tag remains v0.1.0
-until registry credentials are available.
+**Next release: v0.2.0** — assembled from [`changelog.d/0.2.0.md`](changelog.d/0.2.0.md) and
+prepared in [`package.json`](package.json), untagged until the
+[release runbook](docs/design/release-runbook.md) is run to completion. That number is checked
+against the manifest by the `docs-version-claims` gate, so this sentence cannot drift from what
+ships.
+
+What is **published** is deliberately not restated here. It lives on
+[the versions page](https://docs.rungscli.com/versions/), which is the one place that tracks it —
+this file and the roadmap both carried their own copy and both said `v0.1.2` for two days after
+v0.1.3 went to npm.
 
-rungs is installed in its own repo and its gates run on every change — 20 pass,
-0 fail (`rungs check`, 2026-08-15). A clean consumer has also installed the packed
+rungs is installed in its own repo and its gates run on every change — 25 pass,
+0 fail (`rungs check`, 2026-08-17). A clean consumer has also installed the packed
 artifact and completed the doctor → init → add → check → render → upgrade/eject
 journey locally. Detection is [verified against all four source repos](docs/design/detection-verification.md).
 Not yet done: an install from the public registry and a cross-platform release matrix.
@@ -211,7 +248,7 @@ nobody paid for does not ship.
 | [`docs/design/`](docs/design/README.md) | Product brief, module catalogue, verification |
 | [`docs/decisions/`](docs/decisions/README.md) | ADRs |
 | [`modules/`](modules/README.md) | The fifteen modules |
-| [`src/`](src/) | The CLI, ~2,800 lines |
+| [`src/`](src/) | The CLI, ~4,700 lines (`wc -l src/*.ts`, 2026-08-17; held within 10% by `docs-version-claims`) |
 
 ## Licence