cool-workflow 0.1.82 → 0.1.84

package/docs/contract-migration-tooling.7.md

@@ -1,23 +1,24 @@
 # Contract Migration Tooling
 
-CW v0.1.36 makes schema migration a first-class, declared subsystem. Before
-v0.1.36 migration was ad-hoc and run-state-only: `RUN_STATE_MIGRATIONS` was an
-inline step array walked by `migrateRunState`, with no declared `up`-transform
-registry, no recorded compatibility PROOF, no round-trip/non-destruction
-guarantee, and NOTHING covering the workflow-app schema (an old app schema was
-flatly rejected, never migrated). v0.1.36 adds a declared registry, per-edge
-compatibility proofs, fail-closed reachability, and a round-trip prover — reusing
-the existing `migrateRunState` transform (no logic forked).
+CW v0.1.36 makes schema migration a named, declared part of the system. Before
+v0.1.36 migration was done one step at a time and only on run-state:
+`RUN_STATE_MIGRATIONS` was an inline step array walked by `migrateRunState`,
+with no declared `up`-transform registry, no kept compatibility PROOF, no
+round-trip/non-destruction guarantee, and NOTHING covering the workflow-app
+schema (an old app schema was turned away flatly, never migrated). v0.1.36 adds
+a declared registry, per-edge compatibility proofs, fail-closed reachability,
+and a round-trip prover — using again the existing `migrateRunState` transform
+(no logic forked).
 
 ## The declared registry
 
-`migration list` is the single declared source for "what versions exist and how
-to advance them": one `MigrationContract` per schema (`run-state`,
+`migration list` is the one declared source for "what versions exist and how
+to move them forward": one `MigrationContract` per schema (`run-state`,
 `workflow-app`), each with `currentVersion`, `minVersion`, and an array of
 `MigrationEdge { from, to, description, proof }`. The run-state edges ARE
-`RUN_STATE_MIGRATIONS` (the transform is not duplicated). Each edge carries a
-mechanically-checkable `MigrationCompatibilityProof` — the invariant it preserves
-(`addsDefaulted`, `dropsNothing`), as data, not prose.
+`RUN_STATE_MIGRATIONS` (the transform is not copied). Each edge carries a
+machine-checkable `MigrationCompatibilityProof` — the invariant it keeps
+(`addsDefaulted`, `dropsNothing`), as data, not as words.
 
 ```text
 migration list [--json]
@@ -25,20 +26,21 @@ migration list [--json]
 
 ## Fail closed on reachability
 
-Before transforming, the chain `detected -> current` is resolved. If a contract's
-detected version is below `minVersion`, above `currentVersion`, or has no chained
-path, the verdict is `unsupported` with a named reason and NO write — never a
-best-effort partial migration. (An older workflow-app, for which no edge exists
-yet, fails closed with a precise reason instead of being silently accepted.)
+Before transforming, the chain `detected -> current` is worked out. If a
+contract's detected version is below `minVersion`, above `currentVersion`, or
+has no chained path, the verdict is `unsupported` with a named reason and NO
+write — never a part-way migration that does its best. (An older workflow-app,
+for which no edge exists yet, fails closed with an exact reason in place of
+being taken in quietly.)
 
 ```text
 migration check <target> [--contract run-state|workflow-app] [--json]
 ```
 
 `<target>` is a run id (resolves to `.cw/runs/<id>/state.json`) or a path to a
-`state.json` / app manifest. The verdict reports `status`
+`state.json` / app manifest. The verdict gives the `status`
 (`current|migrated|normalized|unsupported`), the detected/current versions, the
-resolved `chain`, the change count, and any errors.
+resolved `chain`, the count of changes, and any errors.
 
 ## Round-trip / non-destruction proof
 
@@ -46,33 +48,34 @@ resolved `chain`, the change count, and any errors.
 migration prove <target> [--contract run-state|workflow-app] [--json]
 ```
 
-`migration prove` runs the chain and PROVES four properties, emitting a
+`migration prove` runs the chain and PROVES four properties, putting out a
 deterministic, sha256-fingerprinted `MigrationProof`:
 
 - **validatesAtCurrent** — the result validates at `currentVersion`.
-- **appendOnly** — every source record/key survives into the output (recursive);
-  nothing is destroyed.
-- **idempotent** — re-running migration on the output yields no further change.
-- **sourceImmutable** — `sourceHash == resultHash`-of-source: the original
+- **appendOnly** — every source record/key lives on into the output (recursive);
+  nothing is lost.
+- **idempotent** — running migration again on the output gives no further change.
+- **sourceImmutable** — `sourceHash == resultHash`-of-source: the first
   snapshot is byte-unchanged (`migrateRunState` clones; the source `state.json` is
-  never mutated).
+  never changed).
 
-`pass` is the conjunction. An `unsupported` verdict never transforms and never
-claims a positive proof.
+`pass` is true when all of these are true. An `unsupported` verdict never
+transforms and never claims a good proof.
 
 ## Append-only proof storage
 
-`migration prove` persists the `MigrationProof` beside the target under
-`migration/<fingerprint>.json` — a NEW file, never overwriting `state.json` or the
-source manifest. Re-deriving from disk reproduces the same fingerprint.
+`migration prove` keeps the `MigrationProof` next to the target under
+`migration/<fingerprint>.json` — a NEW file, never writing over `state.json` or
+the source manifest. Working it out again from disk gives back the same
+fingerprint.
 
 ## Surfaces & Compatibility
 
 `migration.list`/`check`/`prove` are declared `surface: "both"`, so
-`cw migration <verb> --json` and the `cw_migration_*` MCP tools render one core
-(`src/contract-migration.ts`). Additive: the run-state and workflow-app schema
-versions and `migrateRunState` are unchanged; the registry declares and proves
-over the existing transform. Pre-0.1.36 runs and apps load unchanged.
+`cw migration <verb> --json` and the `cw_migration_*` MCP tools draw from one
+core (`src/contract-migration.ts`). It only adds: the run-state and workflow-app
+schema versions and `migrateRunState` are unchanged; the registry declares and
+proves over the existing transform. Pre-0.1.36 runs and apps load unchanged.
 
 ## See Also
 
@@ -81,7 +84,7 @@ cli-mcp-parity(7)
 
 ## Control-Plane Scheduling (v0.1.37)
 
-priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
+priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7) for more.
 
 ## Agent Delegation Drive (v0.1.38)
 
@@ -101,19 +104,19 @@ evidence grounding + durable audit append + symlink-hardened containment + deter
 
 ## Robust Result Ingest (v0.1.42)
 
-capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
+capture findings/evidence from any agent shape that makes sense (alt keys + prose), CW works out grounded evidence itself, give a warning on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
-Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+Hard gate stopping empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
 
 ## Release-Gate Determinism & Agents Vendor (v0.1.44)
 
-Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) in place of the changeable working tree — getting rid of false-red/false-green from working-tree writes at the same time (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter that gives any non-Claude AI agent one common way in to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
-Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49) on top.
 0.1.51
 
 0.1.76
@@ -126,7 +129,15 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 
 ## Fast Architecture Review (v0.1.80)
 
-Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, wrapper metrics you can measure, a background full-review handoff you can act on, and userland model policy flags for routing fast/strong workers without changing the full review contract.
 
 _No changes to the contract-migration subsystem in v0.1.81._
 _No changes in v0.1.82._
+
+## Hardening and Onboarding (v0.1.83)
+
+Loaders fail closed on corrupt state; store writes are made safe under more than one writer; a new cw doctor checks your setup; help lists every command; and the docs are put into Basic English.
+
+## Privacy Release (v0.1.84)
+
+No other change to this page in v0.1.84.

package/docs/control-plane-scheduling.7.md

@@ -2,24 +2,24 @@
 
 CW v0.1.37 adds Control-Plane Scheduling: a scheduling-policy layer over the
 v0.1.28 Run Registry queue. Before v0.1.37 the queue had ORDER (priority,
-`enqueuedAt`) but no policy — nothing limited how many runs were in flight, nothing
-retried a transient failure with backoff, and nothing bounded retries
-(`queue drain` would re-hand the same failing entry forever). v0.1.37 layers
-policy-as-data over the existing queue (no queue file duplicated): priority +
-readiness selection, a hard concurrency ceiling, leases, retry with computed
-backoff, and a fail-closed park state. The verbs use a distinct `sched` namespace,
-separate from the unrelated wall-clock `schedule` (loop/cron) scheduler.
-
-The core (`src/scheduling.ts`) is pure and deterministic — every function takes an
-injected `now`; "CW records readiness/order/leases, the host still executes the
+`enqueuedAt`) but no policy — nothing kept down how many runs were in flight, nothing
+tried again after a short-lived failure with backoff, and nothing put a limit on retries
+(`queue drain` would hand out the same failing entry again and again, for ever). v0.1.37 puts
+policy-as-data over the queue that is already there (no queue file is copied): priority +
+readiness selection, a hard concurrency ceiling, leases, retry with worked-out
+backoff, and a fail-closed park state. The verbs use their own `sched` namespace,
+apart from the unrelated wall-clock `schedule` (loop/cron) scheduler.
+
+The core (`src/scheduling.ts`) is pure and deterministic — every function is given an
+injected `now`; "CW writes down readiness/order/leases, the host still runs the
 workers."
 
 ## Policy as data
 
 `SchedulingPolicy` is a plain, diffable file under `$CW_HOME/registry/
-scheduling-policy.json`, defaulting to conservative fail-closed values when
-absent: `maxConcurrent 1`, `maxAttempts 3`, `leaseTtlMs 300000`, backoff
-`baseMs 1000 * factor 2 ^ (attempts-1)` capped at `60000` (no jitter).
+scheduling-policy.json`. When it is not there, it takes safe fail-closed values:
+`maxConcurrent 1`, `maxAttempts 3`, `leaseTtlMs 300000`, backoff
+`baseMs 1000 * factor 2 ^ (attempts-1)` with a top of `60000` (no jitter).
 
 ```text
 sched policy show [--json]
@@ -34,36 +34,36 @@ ready --lease--> leased --complete--> drained
    |__reset________/
 ```
 
-- **`sched plan`** — READ-ONLY: the would-be lease plan for the current
-  queue+policy+now, deterministic and replayable, without mutating. Payload-
+- **`sched plan`** — READ-ONLY: the lease plan that would be used for the current
+  queue+policy+now, deterministic and able to be run again, with no changes made. Payload-
   identical across CLI and MCP.
-- **`sched lease`** — claim eligible entries (priority order via `compareQueue`,
-  skipping anything not yet eligible / parked / leased) as `leased` with a
+- **`sched lease`** — take eligible entries (priority order via `compareQueue`,
+  jumping over anything not yet eligible / parked / leased) as `leased` with a
   `leaseId` and `leaseExpiresAt`. The **concurrency ceiling is a hard limit** —
-  leasing stops at `maxConcurrent`; over-limit entries stay `ready`.
-- **`sched complete <leaseId>`** — terminal success (`drained`).
-- **`sched release <leaseId> [--failed]`** — failed releases count an attempt
-  (retry/backoff or park); a clean release returns the entry to `ready`.
-- **`sched reclaim`** — an EXPIRED lease (the host died) is reclaimable and counts
-  one failed attempt — recorded, not silently reset.
+  leasing stops at `maxConcurrent`; entries over the limit stay `ready`.
+- **`sched complete <leaseId>`** — end success (`drained`).
+- **`sched release <leaseId> [--failed]`** — failed releases count as an attempt
+  (retry/backoff or park); a clean release sends the entry back to `ready`.
+- **`sched reclaim`** — an EXPIRED lease (the host died) can be reclaimed and counts
+  as one failed attempt — written down, not quietly reset.
 - **`sched reset <id>`** — operator recovery: a parked entry back to `ready`.
 
 ## Fail closed
 
-- **Concurrency is a hard ceiling** — never exceeded; `sched plan`/`lease` stop at
+- **Concurrency is a hard ceiling** — never gone past; `sched plan`/`lease` stop at
   `maxConcurrent` in-flight leases.
 - **Park past budget** — when `attempts >= maxAttempts` the entry becomes `parked`
-  with a `parkedReason` and is NEVER re-selected. `sched reset` is the only way
-  back. The queue can never re-hand a failing entry forever.
-- **Backoff is deterministic** — a pure curve, no randomness; a retried entry sets
-  `nextEligibleAt` and is skipped until then.
+  with a `parkedReason` and is NEVER picked again. `sched reset` is the only way
+  back. The queue can never hand out a failing entry for ever.
+- **Backoff is deterministic** — a pure curve, nothing random; a retried entry sets
+  `nextEligibleAt` and is jumped over until then.
 
 ## Compatibility
 
-Additive: `RunQueueEntry` gains optional `attempts`/`leaseId`/`leaseExpiresAt`/
+Additive: `RunQueueEntry` gets the optional `attempts`/`leaseId`/`leaseExpiresAt`/
 `nextEligibleAt`/`parkedReason` and two statuses (`leased`/`parked`); a pre-0.1.37
-`queue.json` loads unchanged (no scheduling fields = a plain ordered queue). The
-existing `queue add|list|drain|show` verbs are unchanged. No new database, no
+`queue.json` loads with no change (no scheduling fields = a plain ordered queue). The
+`queue add|list|drain|show` verbs that are already there do not change. No new database, no
 daemon-owned state.
 
 ## See Also
@@ -72,35 +72,35 @@ run-registry-control-plane(7), cli-mcp-parity(7), release-and-migration(7)
 
 ## Agent Delegation Drive (v0.1.38)
 
-spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+start an outside agent process for each worker, take in result.md + attestation, and drive plan->dispatch->fulfill->accept->commit by itself
 
 ## Run Retention & Provable Reclamation (v0.1.39)
 
-tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+tiered, append-only, cryptographically-verifiable run reclamation: shut the audit skeleton, free the bulk that can be built again, give proof of it
 
 ## Durable State & Locking (v0.1.40)
 
-atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+atomic temp->rename writes + fsync-durability for the authoritative stores; portable stale-stealing file lock that puts the cross-process read-modify-write stores in order, one at a time
 
 ## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
 
-evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); the orchestrator god-object is broken up into per-domain operation modules (pure loadRun->delegate router)
 
 ## Robust Result Ingest (v0.1.42)
 
-capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
+take in findings/evidence from any reasonable agent shape (alt keys + prose), CW works out grounded evidence by itself, give a warning on empty capture — this shuts the v0.1.41 live-drive 'accepted with 0 captured' failure
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
-Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+Hard gate that stops empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
 
 ## Release-Gate Determinism & Agents Vendor (v0.1.44)
 
-Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+Release-readiness checks now check the committed blob (`git show HEAD:<path>`) in place of the mutable working tree — taking away false-red/false-green that came from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter that gives any non-Claude AI agent one common interface to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
-Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+Migration DAG with edges that can go both ways (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
 0.1.51
 
 0.1.76
@@ -113,7 +113,15 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 
 ## Fast Architecture Review (v0.1.80)
 
-Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, Map and Assess results that can be used again, wrapper metrics that can be measured, a background full-review handoff you can act on, and userland model policy flags for routing fast/strong workers without changing the full review contract.
 
 _No changes to the control-plane scheduling surface in v0.1.81._
-_No behavioral change in v0.1.82 (schedule/run ids are now deterministic-but-unique via a monotonic counter + pid instead of Math.random; ids stay collision-free)._
+_No change in behavior in v0.1.82 (schedule/run ids are now deterministic-but-unique through a monotonic counter + pid in place of Math.random; ids stay collision-free)._
+
+## Hardening and Onboarding (v0.1.83)
+
+Loaders fail closed on corrupt state; store writes are made safe under more than one writer; a new cw doctor checks your setup; help lists every command; and the docs are put into Basic English.
+
+## Privacy Release (v0.1.84)
+
+No other change to this page in v0.1.84.

package/docs/coordinator-blackboard.7.md

@@ -7,15 +7,15 @@ CW v0.1.25 adds `blackboard summarize <run-id>` (MCP: `cw_blackboard_summarize`)
 a deterministic blackboard digest with topic rollups, thread summaries,
 unresolved questions, conflicts, decisions, artifacts, adopted and missing
 evidence, policy violations, judge rationale, recent changes, and high-signal
-records. The digest is a derived userland index: it preserves links back to
-source messages, contexts, artifacts, snapshots, coordinator decisions, and
-audit events, and never deletes raw records. See
+records. The digest is a worked-out index made from other records: it keeps
+links back to source messages, contexts, artifacts, snapshots, coordinator
+decisions, and audit events, and never deletes raw records. See
 [state-explosion-management.7.md](state-explosion-management.7.md).
 
-This release defines stable primitives for shared context, messages, artifact
-indexing, snapshots, and coordinator decisions. It does not implement debate,
-judge, map-reduce, swarm, committee, or synthesis topologies yet. Those
-topologies should consume this substrate later.
+This release gives fixed building blocks for shared context, messages, artifact
+indexing, snapshots, and coordinator decisions. It does not yet build debate,
+judge, map-reduce, swarm, committee, or synthesis topologies. Those topologies
+are meant to use this base later.
 
 ## State Model
 
@@ -44,14 +44,14 @@ Runtime objects are:
 - `BlackboardSnapshot`
 - `CoordinatorDecision`
 
-Every record carries schema version, stable id, timestamps, author/source,
+Every record has schema version, stable id, timestamps, author/source,
 scope, status, parent references, tags, metadata, and links back to workflow,
 multi-agent, worker, task, candidate, verifier, commit, audit, and evidence
-records where applicable.
+records when they apply.
 
 ## Storage Layout
 
-CW mirrors blackboard state to durable local files:
+CW copies blackboard state to local files that last:
 
 ```text
 .cw/runs/<run-id>/blackboard/
@@ -64,13 +64,13 @@ CW mirrors blackboard state to durable local files:
   decisions/<decision-id>.json
 ```
 
-`messages.jsonl` is append-friendly. `index.json` is regenerated
-deterministically from run state. CW does not store secrets or raw environment
+`messages.jsonl` is good for adding to the end. `index.json` is made again the
+same way from run state each time. CW does not keep secrets or raw environment
 values in blackboard metadata.
 
 ## Context Semantics
 
-Shared context supports:
+Shared context takes these kinds:
 
 - `fact`
 - `constraint`
@@ -78,12 +78,12 @@ Shared context supports:
 - `question`
 - `decision`
 
-Context updates do not silently overwrite older records. If a new update has
+Context updates do not quietly write over older records. If a new update has
 the same topic, kind, and key as an active context record but a different value,
 CW marks the records `conflicting` and records a `CoordinatorDecision`.
 
-Use `--supersedes <context-id>` to intentionally replace older context. The
-older record is marked `superseded`, and the new record links to it.
+Use `--supersedes <context-id>` when you mean to take the place of older context.
+The older record is marked `superseded`, and the new record links to it.
 
 ## Artifact Index
 
@@ -91,15 +91,15 @@ older record is marked `superseded`, and the new record links to it.
 locators, generated artifacts, reports, commit snapshots, and external paths.
 
 Artifact refs include kind, path or locator, owner, source, provenance,
-evidence refs, checksum when the path is a readable file, and trust audit links.
-Existing `StateArtifact` records remain valid; blackboard refs bridge them into
-shared coordination state instead of replacing them.
+evidence refs, checksum when the path is a file that can be read, and trust audit
+links. Existing `StateArtifact` records stay good; blackboard refs join them into
+shared coordination state and do not take their place.
 
 ## Multi-Agent Integration
 
 `MultiAgentRun`, groups, roles, memberships, fanout, and fanin can link to a
 blackboard id and topic ids. Worker manifests for blackboard-enabled work
-include:
+have:
 
 ```json
 {
@@ -112,8 +112,8 @@ include:
 }
 ```
 
-Accepted worker output can publish result summaries and artifacts into the
-blackboard. Fanin can require indexed blackboard evidence and fails closed when
+Accepted worker output can put result summaries and artifacts into the
+blackboard. Fanin can ask for indexed blackboard evidence and fails closed when
 required role memberships have no blackboard message or artifact refs.
 
 ## CLI
@@ -133,12 +133,12 @@ node scripts/cw.js coordinator summary <run-id>
 node scripts/cw.js coordinator decision <run-id> --kind conflict-resolution --outcome accepted --reason "..."
 ```
 
-The CLI is JSON-friendly by default for focused blackboard and coordinator
+The CLI gives JSON by default for focused blackboard and coordinator
 commands.
 
 ## MCP Parity
 
-MCP exposes matching tools:
+MCP gives the same tools:
 
 ```text
 cw_blackboard_summary
@@ -155,14 +155,14 @@ cw_coordinator_summary
 cw_coordinator_decision
 ```
 
-There is no intentional CLI-only behavior for core blackboard operations.
+There is no CLI-only behavior on purpose for core blackboard operations.
 
 ## Operator UX
 
-`status`, `report --show`, and graph output include a Blackboard / Coordinator
+`status`, `report --show`, and graph output have a Blackboard / Coordinator
 panel. It shows topics, message counts, open questions, conflicts, missing
-evidence, artifact counts, snapshot paths, ready-for-fanin state, and next
-recommended action.
+evidence, artifact counts, snapshot paths, ready-for-fanin state, and the next
+suggested action.
 
 Use:
 
@@ -177,7 +177,7 @@ node scripts/cw.js audit provenance <run-id>
 ## Migration
 
 Older v0.1.17 and earlier runs normalize with empty blackboard state and a
-`.cw/runs/<run-id>/blackboard/` path. Unknown user data is preserved.
+`.cw/runs/<run-id>/blackboard/` path. User data that is not known is kept.
 
-Newer unsupported run-state schemas still fail closed.
+Newer run-state schemas that are not supported still fail closed.
 0.1.51