📖 docs: fix documentation rot

README.md

@@ -105,6 +105,7 @@ tmux attach -t my-agent
 | `pluk watch <session>` | Classify stdin line-by-line |
 | `pluk send <session> --text="..." --enter` | Send text to a tmux session |
 | `pluk patterns --cli=claude` | Show loaded patterns for a CLI |
+| `pluk version` | Print the installed version |
 | `pluk <command> --help` / `-h` | Show usage (works after any subcommand) |
 
 Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name for "pluk <cmd>" (see pluk <cmd> --help)`) instead of being silently ignored. For example, `pluk sessions --cli=claude` is rejected: `--cli` belongs to `attach`, `watch`, and `patterns`, not `sessions`. Run `pluk --help` for the per-command flag lists.
@@ -116,7 +117,7 @@ Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name
 | `--cli=claude` | CLI type: `claude`, `copilot`, `gemini`, `goose`, `codex`, `aider`, `omp` |
 | `--command=<cmd>` | Override the CLI command/executable to launch (instead of the default resolved from `--cli`); combines with `--cli-args` |
 | `--rationguard` | Start rationguard watcher alongside pluk (requires `rationguard` on `PATH` — `npm install -g @hivecommons/rationguard` — or `--rationguard-bin`; pluk never fetches it from the registry implicitly) |
-| `--rationguard-bin=<cmd>` | Explicit rationguard command to run instead of the one on `PATH`, e.g. `--rationguard-bin='npx --yes @hivecommons/rationguard@0.11.0'` (also `PLUK_RATIONGUARD_BIN`); the flag is ignored with a warning without `--rationguard` |
+| `--rationguard-bin=<cmd>` | Explicit rationguard command to run instead of the one on `PATH`, e.g. `--rationguard-bin='npx --yes @hivecommons/rationguard@0.13.0'` (also `PLUK_RATIONGUARD_BIN`); the flag is ignored with a warning without `--rationguard` |
 | `--rebuttal=log\|send` | Log rebuttals or auto-send them when rationguard detects excuses; other values exit with code 2 before attaching. Ignored with a warning without `--rationguard` |
 | `--dangerous` | Skip CLI permission prompts (`--dangerously-skip-permissions` for claude, `--allow-all-tools` for copilot, `--full-auto` for codex, `--non-interactive` for goose, `--approval-mode yolo` for omp) |
 | `--dir=/path` | Working directory for the agent |
@@ -138,7 +139,7 @@ Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name
 | `patterns` | `--patterns-dir=<dir>` | Show the patterns loaded from this directory (same lookup as `watch`) |
 | `subscribe` | `--from-beginning` | Replay the existing log from the start instead of only new lines |
 | `subscribe` | `--verbose` | Show debug output |
-| `sessions`, `subscribe` | `--run-dir=<path>` | Run directory to read (overrides `PLUK_RUN_DIR`) |
+| `sessions`, `subscribe`, `watch` | `--run-dir=<path>` | Run directory to use (overrides `PLUK_RUN_DIR`); `attach` accepts it too |
 | `sessions` | `--json` | Print the session list as JSON instead of a table |
 
 ### Health diagnostics (`watch`, `subscribe`)

ROADMAP.md

@@ -11,22 +11,25 @@ package and its relationship with the wider Hive Commons agent-tooling stack.
 - Built-in pattern sets for Claude, Copilot, Gemini, Goose, Codex, Aider, and Oh My Pi (`omp`).
 - Rationguard integration through `pluk attach --rationguard` and stable event
   fields consumed by companion tools.
+- A versioned JSONL event envelope (`v: 1`) with documented compatibility
+  rules in the README's [Event Schema](README.md#event-schema) section.
 
 ## Near term
 
-1. **Event schema stability:** document compatibility expectations for the JSONL
-   event format so tools such as rationguard and hotshot can depend on it safely.
+1. **Event schema evolution:** keep the JSONL envelope additive within schema
+   version 1 and define the process for a version bump, so tools such as
+   rationguard can depend on it safely.
 2. **Broader CLI coverage:** add and test pattern packs for additional active
    agent CLIs as they become adoption-relevant.
 3. **Operational hardening:** continue replacing tmux/terminal edge cases with
    explicit diagnostics, non-zero exits for operator errors, and hermetic tests.
 
-## Go and TypeScript relationship
+## Implementation
 
-The TypeScript package is the npm-facing implementation for JavaScript users and
-companion tools. The Go implementation remains useful where a static binary is
-preferred. Near-term work should keep event shapes and user-facing semantics
-aligned rather than forcing a repository merge.
+Pluk is a single TypeScript package published to npm as `@hivecommons/pluk`;
+there is no separate Go binary. Hive and other consumers shell out to the npm
+CLI and read its JSONL logs, so event shapes and user-facing semantics are the
+compatibility surface.
 
 ## Non-goals for now
 

runbooks/publish-failure.md

@@ -1,7 +1,8 @@
 # Runbook: a tag push whose publish pipeline failed
 
-`publish.yml` runs three jobs on every `v*` tag push: `verify-tag`, then
-`publish` (npm), then `release` (GitHub release). Which job failed decides the
+`publish.yml` runs three jobs on every `v*` tag push (and when
+`auto-release.yml` dispatches it after a version-bump merge): `verify-tag`,
+then `publish` (npm), then `release` (GitHub release). Which job failed decides the
 recovery. For a version that already reached npm and is bad, use
 `release-rollback.md` instead.
 

runbooks/release-rollback.md

@@ -1,7 +1,9 @@
 # Runbook: rolling back a bad pluk release
 
-`publish.yml` runs `npm test` against the tagged ref and then publishes to npm
-on every `v*` tag push. Tests reduce risk but cannot catch every regression
+Merging a `package.json` version bump to `main` makes `auto-release.yml`
+create the `v<version>` tag and dispatch `publish.yml` (a manual `v*` tag
+push also triggers it). `publish.yml` runs `npm test` against the tagged ref
+and then publishes to npm. Tests reduce risk but cannot catch every regression
 (for example, behavior that only breaks under a real tmux session, a
 downstream consumer's assumptions, or an environment-specific failure). This
 runbook covers what to do once a bad version has already reached the npm
@@ -54,12 +56,14 @@ packaging nit.
 
 1. Branch from `main`, fix the regression, and add a regression test per
    `CONTRIBUTING.md`.
-2. Bump the version in `package.json` and land the fix through the normal PR
-   process.
-3. Tag `vX.Y.Z` on `main` once merged; `publish.yml` runs the test suite
-   against that tag and publishes automatically.
-4. Add a `changelog.d/fixed-<slug>.md` fragment describing the regression and
+2. Add a `changelog.d/fixed-<slug>.md` fragment describing the regression and
    the fix, following the existing entries in `changelog.d/`.
+3. Bump the version in `package.json`, roll the fragments into a non-empty
+   `## X.Y.Z` section of `CHANGELOG.md`, and land the fix through the normal
+   PR process.
+4. On merge, `auto-release.yml` tags `vX.Y.Z` and dispatches `publish.yml`,
+   which runs the test suite against that tag and publishes automatically.
+   If tagging or dispatch fails, see `publish-failure.md`.
 
 ## After
 

runbooks/session-monitoring-failure.md

@@ -46,8 +46,9 @@ A silent watcher means those consumers act on stale state.
 | `eventsFiltered` ≈ `linesSeen` | `--filter` excludes everything | Review the filter set |
 | `malformedLines` rising (subscriber) | Log has non-pluk lines | Check for another writer on the log file or truncated rotation |
 
-If counters are healthy and events still do not arrive, the CLI may have no
-bundled patterns (`codex`, `aider`): pass `--patterns-dir`.
+If counters are healthy and events still do not arrive, check that a pattern
+set exists for the CLI name you passed (`pluk patterns --cli=<cli>` lists the
+bundled sets); for an unsupported CLI, pass `--patterns-dir`.
 
 ## Recover