📖 docs: explain purpose and first-session prerequisites

README.md

@@ -6,14 +6,19 @@
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-Pluk classifies, subscribes to, and reacts to JSONL event streams from AI coding agent terminals.
+Pluk turns an AI coding agent's terminal output into events, such as “agent is
+idle” or “usage limit reached”. Other tools can read these events and decide
+what to do. Events are stored as **JSONL**: one JSON record per line.
 
 ## Install
 
 Requirements:
 
 - Node.js 22 or newer
-- tmux (`attach`, `send` and `watch --capture` drive tmux sessions)
+- tmux, a tool that keeps terminal sessions running (`attach`, `send` and
+  `watch --capture` drive those sessions)
+- For the live examples, an installed and authenticated coding-agent CLI
+  such as Claude Code; pluk does not install or sign in to it for you
 
 ```bash
 npm install -g @hivecommons/pluk
@@ -69,9 +74,23 @@ helper           claude    idle      ●     45s ago       892
 goose-exp        goose     idle      ○     3m ago        156
 ```
 
+## Reference: commands, integration, and event formats
+
+After your first session, use the sections below as needed:
+[commands](#cli-commands), [flags](#attach-flags),
+[health diagnostics](#health-diagnostics-watch-subscribe),
+[library API](#programmatic-api), [event schema](#event-schema), and
+[custom patterns](#pattern-file-format).
+
+<details>
+<summary>Optional: wire tmux and event capture manually</summary>
+
 ## Manual Setup
 
-If you prefer to wire things up yourself:
+**Advanced wiring; most users can stay with `attach`.** Data flows from the
+agent's tmux pane → `pipe-pane` (tmux's output pipe) → `pluk watch` → a JSONL
+log. `pluk subscribe` reads that log from another terminal.
+The run directory must be the same in both terminals.
 
 ```bash
 # 1. Create a tmux session (don't start the CLI yet)
@@ -106,6 +125,8 @@ tmux attach -t my-agent
 | `PLUK_LOG_KEEP_LINES` | `5000` | Keep up to this many trailing lines across rotation, within the `PLUK_LOG_MAX_BYTES` cap |
 | `PLUK_RATIONGUARD_BIN` | *(unset)* | Rationguard command for `pluk attach --rationguard` when it is not on `PATH`; same as `--rationguard-bin` |
 
+</details>
+
 ## CLI Commands
 
 | Command | What it does |
@@ -155,6 +176,9 @@ Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name
 
 ### Health diagnostics (`watch`, `subscribe`)
 
+<details>
+<summary>Operator reference: counters and diagnostics intervals</summary>
+
 `pluk watch` and `pluk subscribe` deliberately swallow capture-pane failures,
 input errors and malformed log lines so the pipe-pane process never dies. To
 tell a healthy quiet session from one that is repeatedly failing, add
@@ -176,8 +200,16 @@ period above 2147483.647 seconds (about 24.9 days) have it capped at that value
 to stay within Node's timer limit; the CLI rejects out-of-range values as
 described above.
 
+</details>
+
 ## Programmatic API
 
+This example enables automatic messages and skips the launched CLI's permission
+prompts. Both are optional: omit `rebuttal: 'send'` and
+`dangerouslySkipPermissions: true` for a detection-only setup with normal
+permission checks. Only bypass prompts in an environment you have deliberately
+isolated and authorized.
+
 ```typescript
 import { Classifier, getPatterns, subscribe, watch, discoverSessions, attach, send } from '@hivecommons/pluk';
 

ROADMAP.md

@@ -3,6 +3,8 @@
 Pluk turns AI-agent terminal output into structured events that downstream
 tools can consume. This roadmap describes the direction for the TypeScript
 package and its relationship with the wider Hive Commons agent-tooling stack.
+For example, a `state_change` event can report that an agent went idle.
+Logs use JSONL: one JSON record per line.
 
 ## Recently shipped
 
@@ -16,20 +18,23 @@ package and its relationship with the wider Hive Commons agent-tooling stack.
 
 ## Near term
 
-1. **Event schema evolution:** keep the JSONL envelope additive within schema
+1. **Event schema evolution:** keep the JSONL envelope (fields around each event)
+   additive within schema
    version 1 and define the process for a version bump, so tools such as
-   rationguard can depend on it safely.
+   rationguard can depend on it safely: add fields without removing or changing
+   the meaning of existing ones within version 1.
 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.
+   explicit diagnostics, non-zero exits for operator errors, and isolated tests
+   that do not depend on a real agent or external service.
 
 ## Implementation
 
 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.
+compatibility surface — the behavior other tools depend on.
 
 ## Non-goals for now