@rungs/cli 0.1.3 → 0.3.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,20 @@ 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 |
+| `rungs session start <branch>` | Cut a branch and worktree from the last **verified** merge, not the tip |
+| `rungs preflight [path]` | Did the integration branch change files *you* changed? |
+| `rungs land <branch>` | Merge → verify the merged tree → advance with a compare-and-swap, or refuse and park it |
+| `rungs worktrees [path]` | Which worktrees are merged, prunable, or merged and still dirty |
 
 | 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 |
@@ -145,6 +173,10 @@ you when you are installing above your level.
 | **4** docs that restate each other | `doc-authority` |
 | **5** 5+ concurrent sessions | `concurrency` |
 
+The last four commands are the `concurrency` loop. They drive git, which nothing else in rungs
+does — [ADR-0009](docs/decisions/ADR-0009-rungs-drives-git.md) sets the rules they obey: verify
+before you advance, never destroy (only refuse), and never hold the integration branch.
+
 `concurrency` refuses to install without `--confirm-threshold`, because below
 five simultaneous sessions every mechanism in it costs more than it returns.
 Selling rung 5 to a rung-1 repo is the most likely way this tool does harm.
@@ -153,6 +185,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,15 +220,27 @@ Four promises that shape everything else:
 
 ## Status
 
-**Next release, v0.1.3** — prepared locally as
-[`@rungs/cli`](https://www.npmjs.com/package/@rungs/cli); the public `latest` tag is v0.1.2.
-The release remains untagged until the release gates and publication step are run.
+**Current release: v0.3.0** — that number is checked against [`package.json`](package.json) by the
+`docs-version-claims` gate, so this sentence cannot drift from what ships — and the gate fails if
+the sentence is reworded out of existence, because a claim nothing checks any more should not look
+the same as a claim that passes.
+
+It deliberately does **not** say "and it is on npm". Whether this version is tagged and published
+is a fact about the registry, not about the manifest, and it was wrong here for two days once
+already.
+
+Whether a release is **pending**, and what npm currently serves, live on
+[the versions page](https://docs.rungscli.com/versions/) — the one place that tracks them. 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. Cutting the next one follows the [release runbook](docs/design/release-runbook.md).
 
-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
-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.
+rungs is installed in its own repo and its 29 gates run on every change — 29 pass,
+0 fail (`rungs check`, 2026-08-17). A clean consumer has installed from the **public
+registry** and run the binary, and another completed the doctor → init → add → check →
+render → upgrade/eject journey from a packed artifact. Detection is
+[verified against all four source repos](docs/design/detection-verification.md).
+Not yet done: a cross-platform release matrix — only Windows is verified — and writing
+to a repo rungs did not scaffold.
 
 Expect module *contents* to move. The command surface is settled.
 
@@ -211,7 +261,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, ~5,100 lines (`wc -l src/*.ts`, 2026-08-17; held within 10% by `docs-version-claims`) |
 
 ## Licence