cool-workflow 0.1.82 → 0.1.83

package/docs/team-collaboration.7.md

@@ -2,48 +2,48 @@
 
 CW v0.1.32 adds Team Collaboration: a host-attested actor, append-only approvals,
 rejections, comments, and handoffs, and a review gate that STACKS ON the verifier
-gate. Before v0.1.32 there was no review/approval/comment/handoff/identity concept
-anywhere; the foundations already existed — trust-audit recorded every decision
-with an `actor`, candidate selection carried `selectedBy`, role policies existed,
-and commits were verifier-gated. This release adds the human-decision layer ON TOP
-of those mechanisms, without changing them and without taking ownership of source
+gate. Before v0.1.32 there was no review/approval/comment/handoff/identity idea
+anywhere; the base parts were already there — trust-audit kept a note of every
+decision with an `actor`, candidate selection had `selectedBy`, role policies were
+there, and commits were verifier-gated. This release adds the human-decision layer ON TOP
+of those mechanisms. It does not change them and does not take ownership of source
 truth.
 
-The design follows the same base-system discipline as
+The design keeps to the same base-system way as
 [Security / Trust Hardening](security-trust-hardening.7.md) and the
 [Verifier-Gated Commit](verifier-gated-commit.7.md):
 
 - the per-run `.cw/runs/<id>/state.json` is the SINGLE source of truth
-- collaboration records are an APPEND-ONLY log, never mutated in place
+- collaboration records are an APPEND-ONLY log, never changed in place
 - identity is ATTESTED provenance, never authenticated; CW is not an auth server
-- the review gate is POLICY layered on the verifier MECHANISM — never a bypass
-- fail closed: missing authority, ambiguous role, or self-approval is a denial
+- the review gate is POLICY put over the verifier MECHANISM — never a bypass
+- fail closed: missing authority, unclear role, or self-approval is a denial
 - policy (required approvals, authorized roles, self-approval) is data, not kernel
-- backward compatible; every collaboration field is additive and optional
+- backward compatible; every collaboration field is added on and optional
 
 ## Identity is attested, not authenticated
 
-An `Actor` is host-attested provenance, not an authenticated principal. CW records
-WHO acted; it does not verify a password, a token, or a signature — that is a host
-trust-boundary concern. `normalizeActor` maps an actor input to one of three
-provenances: `host-attested` (the host vouched, `--attested`), `operator-recorded`
-(supplied unverified), or `unattributed` (no identity supplied). An absent identity
-becomes the explicit `unattributed` actor — `{ kind: "unattributed", id:
-"unattributed", attested: false }` — never a fabricated one. Spoofing is recorded
-honestly as whatever provenance the host attested, not hidden. This extends the
+An `Actor` is host-attested provenance, not an authenticated principal. CW keeps a
+note of WHO acted; it does not check a password, a token, or a signature — that is a host
+trust-boundary thing. `normalizeActor` maps an actor input to one of three
+provenances: `host-attested` (the host said so, `--attested`), `operator-recorded`
+(given but not checked), or `unattributed` (no identity given). A missing identity
+becomes the plain `unattributed` actor — `{ kind: "unattributed", id:
+"unattributed", attested: false }` — never a made-up one. Spoofing is kept on record
+in a true way as whatever provenance the host attested, not hidden. This builds on the
 existing trust-audit `actor` string and the v0.1.29/v0.1.31 attestation pattern.
 
 ## Approvals and rejections are append-only and provenance-linked
 
 `approve` and `reject` append an `ApprovalRecord` to `run.collaboration.approvals`.
-Each record carries the actor, the decision, the durable target it attaches to, an
+Each record holds the actor, the decision, the durable target it joins to, an
 optional rationale, the role the actor claims, and `auditEventIds` linking it to a
 `collaboration.approval`/`collaboration.rejection` event in the trust-audit log —
-exactly as `candidate.selection` records both a `CandidateSelection` and an audit
+just as `candidate.selection` keeps a note of both a `CandidateSelection` and an audit
 event. The approved artifact (candidate/commit/selection) is NEVER edited in place:
-"who approved what" is a provenance link, not a field overwrite. A correction is a
-NEW record carrying `supersedes` (git-style); the superseded record stays in the
-log, no longer counts, and the original is unchanged.
+"who approved what" is a provenance link, not a field overwrite. A fix is a
+NEW record holding `supersedes` (git-style); the superseded record stays in the
+log, no longer counts, and the original is left as it was.
 
 A target is one of `run | task | candidate | selection | commit | node`. "Who
 approved which candidate/commit" is answered by filtering the append-only records
@@ -54,76 +54,76 @@ by target.
 The verifier-gated commit is the MECHANISM (see
 [Verifier-Gated Commit](verifier-gated-commit.7.md)): `resolveCommitGate` accepts a
 commit only when a verified verifier node, a scored+verified candidate, and a
-complete acceptance rationale are present. A review gate is POLICY layered on top.
+full acceptance rationale are present. A review gate is POLICY put on top.
 `reviewGateErrors` runs INSIDE `resolveCommitGate`, AFTER the verifier checks, and
-can only ADD errors — required approvals from authorized roles — never remove the
+can only ADD errors — required approvals from authorized roles — never take away the
 verifier's. The same call guards candidate selection in `selectCandidate`.
 
 Data flow for a gated commit:
 
-1. `resolveCommitGate` resolves the candidate/selection and runs every verifier
+1. `resolveCommitGate` works out the candidate/selection and runs every verifier
    check; if any fail the commit is blocked as before.
 2. If a `ReviewGatePolicy` applies to `commit` (or `selection`), `reviewGateErrors`
-   derives the review state over the approvals targeting the commit AND its
+   works out the review state over the approvals pointing at the commit AND its
    underlying selection/candidate (you approve the candidate; the commit honors it).
 3. If the review state is not `approved`, a single `review-gate-missing-approvals`
-   StateNodeError is appended, listing exactly which approvals are missing.
-   `commitState` throws `CommitGateError`, recorded as append-only feedback.
+   StateNodeError is appended, listing just which approvals are missing.
+   `commitState` throws `CommitGateError`, kept on record as append-only feedback.
 4. Only when BOTH gates pass is the commit written — and it is stamped with a
-   `CommitReviewProvenance` recording WHO approved the very artifact that shipped.
+   `CommitReviewProvenance` keeping a note of WHO approved the very artifact that shipped.
 
-Because the review errors are appended after the verifier errors and never replace
-them, an approval can never turn an unverified result into a committed one: an
+Because the review errors are appended after the verifier errors and never take their
+place, an approval can never turn an unverified result into a committed one: an
 approved-but-unverified candidate is still blocked by the verifier gate.
 
 ## Fail closed on authority and quorum
 
 `deriveReviewState` is a pure, deterministic projection of the append-only records
-plus a policy. It counts ONLY approvals that are, all at once: from an attested
+plus a policy. It counts ONLY approvals that are, all at the same time: from an attested
 identity (when `requireAttestedActor`), from a role in `authorizedRoles` (or `*`),
 and not a self-approval (when `allowSelfApproval` is false; "self" is the
-candidate's producing worker and its selector). Distinct counted approvers must
-reach `requiredApprovals`. Anything short is not auto-passed; the status is:
+candidate's producing worker and its selector). The number of separate counted approvers must
+reach `requiredApprovals`. Anything less is not let through on its own; the status is:
 
 - `approved` — requirement met (or the target is not gated)
 - `pending` — gated, no blocking reject, fewer than required counted approvals
-- `blocked` — recorded approvals exist but none count (authority/self)
+- `blocked` — recorded approvals are there but none count (authority/self)
 - `unattributed` — the only recorded approvals are from unattributed actors
 - `rejected` — an authorized, attested reject is a blocking veto
 
-Every disqualified approval is surfaced with its reason (`unattributed`,
+Every approval that does not qualify is shown with its reason (`unattributed`,
 `unauthorized-role`, `self-approval`, `superseded`), so a reader can audit why an
-approval did not count. A target requiring N approvals with fewer recorded is
-BLOCKED, and the block records exactly what is missing.
+approval did not count. A target needing N approvals with fewer recorded is
+BLOCKED, and the block keeps a note of just what is missing.
 
 ## Comments and handoffs are state, not chat
 
 A `comment` appends a `CommentRecord` to a durable target with an actor, a thread
-id, and an audit link; threads are ordered by `createdAt` and never edited in
-place. A `handoff` appends a `HandoffRecord` — an explicit ownership transfer with
-a from-actor, a to-actor, and a reason — and the current owner of a run/task is
-DERIVED from the latest handoff, never an overwritten field. There is no side
-channel: the collaboration IS the durable, inspectable state, consistent with CW's
+id, and an audit link; threads are put in order by `createdAt` and never edited in
+place. A `handoff` appends a `HandoffRecord` — a clear ownership transfer with
+a from-actor, a to-actor, and a reason — and the present owner of a run/task is
+DERIVED from the newest handoff, never an overwritten field. There is no side
+channel: the collaboration IS the durable, inspectable state, in keeping with CW's
 no-hidden-dashboard-database rule.
 
 ## Policy as data, kept out of the kernel
 
 `review policy <run-id>` writes a `ReviewGatePolicy` to `run.collaboration.policy`:
 `requiredApprovals` (0 = no gate), `authorizedRoles` (`*` = any), `allowSelfApproval`,
-`requireAttestedActor`, and `appliesTo` (target kinds). The default — absent policy
-or `requiredApprovals: 0` — requires no approvals, so pre-v0.1.32 runs and any run
-without a policy behave exactly as before. The policy is data; the kernel only
-enforces the mechanism.
+`requireAttestedActor`, and `appliesTo` (target kinds). The default — no policy
+or `requiredApprovals: 0` — needs no approvals, so pre-v0.1.32 runs and any run
+without a policy act just as before. The policy is data; the kernel only
+makes the mechanism hold.
 
 ## One source, every surface
 
 Each collaboration verb is declared once in `src/capability-registry.ts`, so
 `cw <cmd> --json` is schema-identical to `cw_<cmd>` and passes the parity gate. The
-read-only `review status` and `comment list` are byte-for-byte identical across CLI
-and MCP (the payload-identity probe strips only ISO timestamps; the only
+read-only `review status` and `comment list` are byte-for-byte the same across CLI
+and MCP (the payload-identity probe takes out only ISO timestamps; the only
 now-derived field in a review report is `generatedAt`). The v0.1.30 Workbench
-renders the review timeline and per-target approval state read-only as a sixth
-panel, embedding the `review status` payload verbatim. The v0.1.31 metrics report
+shows the review timeline and per-target approval state read-only as a sixth
+panel, putting in the `review status` payload word for word. The v0.1.31 metrics report
 adds derived approval-rate, time-to-approval, handoff-count, and reviewer-count,
 all from recorded timestamps — deterministic over a fixed snapshot.
 
@@ -141,7 +141,7 @@ cw review status <run-id> [--json]
 
 `<kind>` is one of `run | task | candidate | selection | commit | node`. Approve a
 candidate (or selection), then commit `--candidate`/`--selection`; the commit gate
-honors the candidate's approvals and records who approved the shipped commit.
+honors the candidate's approvals and keeps a note of who approved the shipped commit.
 
 CW is the base system. Workflow apps are userland. Collaboration adds the human
 decision as durable, attested, append-only state — never a hidden dashboard, never
@@ -149,11 +149,11 @@ a bypass of the verifier gate.
 
 ## Release Tooling (v0.1.33)
 
-the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(7).
+the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(7) for more.
 
 ## Real Execution Backend Integrations (v0.1.34)
 
-container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is unavailable. See real-execution-backends(7).
+container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is not there to use. See real-execution-backends(7).
 
 ## Node Snapshot / Diff / Replay (v0.1.35)
 
@@ -193,11 +193,11 @@ Hard gate blocking empty-capture verifier-gated commits, plus quickstart and lau
 
 ## 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 mutable working tree — doing away with 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.
 
 ## 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), and CI content-surface determinism hardening (v0.1.49).
 0.1.51
 
 0.1.76
@@ -210,7 +210,11 @@ 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, measurable wrapper metrics, useful background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
 
 _No changes to the team-collaboration surface 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.

package/docs/trust-model.md

@@ -1,57 +1,57 @@
 # Trust Model & Limitations
 
-> **Read this before you trust a cool-workflow record.** This document states
+> **Read this before you trust a cool-workflow record.** This page says
 > exactly what CW's cryptographic guarantees prove, and — just as important —
-> what they do **not** prove. We would rather lose a skeptical reader here than
-> have them over-trust a green checkmark in production. If anything below reads
-> as an overclaim, it is a bug; please file it.
+> what they do **not** prove. We would be happier to lose a doubting reader here than
+> to have them put too much trust in a green check mark in production. If anything below
+> says more than is true, it is a bug; please send it in.
 
-CW is an **auditable control-plane**. It plans, dispatches, records, and verifies
-agent work — it does **not** run the model itself. That single architectural
-choice is what the guarantees below rest on, and it is also the source of their
-honest ceiling.
+CW is an **auditable control-plane**. It plans, sends out, records, and checks
+agent work — it does **not** run the model itself. That one design
+choice is what the guarantees below are built on, and it is also the cause of their
+honest limit.
 
 ---
 
 ## TL;DR
 
 - CW's ed25519 signature + hash-chained ledger prove **integrity and
-  attribution**: a recorded usage figure was signed by the keyholder and has not
-  been edited since it was recorded. Both re-verify **offline** — the recorded
+  attribution**: a recorded usage number was signed by the keyholder and has not
+  been changed since it was recorded. Both check again **offline** — the recorded
   ledger's integrity with **no key at all** (`cw telemetry verify`), and each
-  `attested` signature with the **public key alone** (`cw telemetry verify
-  --pubkey <public.pem>`; also reproduced by `cw demo tamper`).
-- They do **not** prove the original number was **true**. A dishonest signer can
-  sign a lie; the lie is then cryptographically bound to its signer, but it is
-  still a lie.
-- **CW holds no private key.** It can verify, but it can neither forge a
-  signature nor measure usage itself (by design — see the red line below).
+  `attested` signature with the **public key by itself** (`cw telemetry verify
+  --pubkey <public.pem>`; also done again by `cw demo tamper`).
+- They do **not** prove the first number was **true**. A signer who is not honest can
+  sign a false number; the false number is then bound by cryptography to its signer, but it is
+  still false.
+- **CW holds no private key.** It can verify, but it can not make a fake
+  signature and it can not measure usage itself (by design — see the red line below).
 - The honest gap is **single-keyholder / no second party**: when the same
   operator runs CW *and* holds the only signing key, integrity is real but there
-  is no independent party attesting that the source was honest. **This is exactly
-  why we are seeking early integration partners** who supply an independent
+  is no separate party giving word that the source was honest. **This is exactly
+  why we are looking for early integration partners** who give a separate
   second party / co-signer. See [Closing the gap](#closing-the-gap-the-second-party).
 
 ---
 
 ## What the cryptography is, precisely
 
-There are two distinct mechanisms. Conflating them is the most common way to
-over- or under-state the guarantee, so they are kept separate here.
+There are two separate parts. Mixing them up is the most common way to
+say too much or too little about the guarantee, so they are kept apart here.
 
 ### 1. The telemetry signature (ed25519) — attribution of a reported number
 
-The agent (the **executor**) self-reports its token usage. A control-plane that
-records that number verbatim is recording a **claim**. To turn the claim into an
+The agent (the **executor**) reports its own token usage. A control-plane that
+records that number word for word is recording a **claim**. To make the claim into an
 **attestation**, the executor signs a canonical payload with its **private key**:
 
 ```
 sign({ usage, runId, taskId, promptDigest })   // ed25519, executor-side
 ```
 
-The `runId` / `taskId` / `promptDigest` binding is load-bearing: it ties the
-signature to **this** hop, so a valid signature from one task cannot be replayed
-onto another. `promptDigest` is the sha256 of the exact worker prompt CW handed
+The `runId` / `taskId` / `promptDigest` binding does important work: it ties the
+signature to **this** hop, so a good signature from one task can not be used again
+on another. `promptDigest` is the sha256 of the exact worker prompt CW gave
 the agent.
 
 CW then **verifies** that signature against an **operator-provisioned public
@@ -61,42 +61,42 @@ key**. CW holds *only* the public half. From `telemetry-attestation.ts`:
 > ONLY the public key — it can verify, but can neither forge a signature nor (the
 > red line) call a model to measure usage itself.
 
-The result is one of three honest states, surfaced loudly and never silently
-upgraded to "trusted":
+The result is one of three honest states, shown clearly and never quietly
+moved up to "trusted":
 
 | State | Meaning |
 |---|---|
-| `attested` | A valid ed25519 signature over the reported usage, bound to this run/task/prompt, verified against the configured public key. |
-| `unattested` | Usage was reported but the signature is missing, malformed, made with the wrong key, or does not match the payload (tampered or replayed). Also: no trust key configured. |
+| `attested` | A good ed25519 signature over the reported usage, bound to this run/task/prompt, checked against the set public key. |
+| `unattested` | Usage was reported but the signature is missing, badly formed, made with the wrong key, or does not match the payload (changed or used again). Also: no trust key set. |
 | `absent` | The agent reported no usage at all. |
 
 Defaults are honest: no signature ⇒ `unattested`; no usage ⇒ `absent`. **Usage
-is never silently recorded as trusted.** The opt-in `require-attested-telemetry`
+is never quietly recorded as trusted.** The opt-in `require-attested-telemetry`
 policy fails the run closed on anything other than `attested`.
 
 ### 2. The hash-chained ledgers — tamper-evidence of the recorded log
 
-A signature proves the agent *said* a number in flight. It does not, by itself,
-prove that **CW recorded exactly that** and that **nobody edited the record
-afterward**. That is the job of the append-only, hash-chained ledgers:
+A signature proves the agent *said* a number while running. By itself it does not
+prove that **CW recorded exactly that** and that **nobody changed the record
+after**. That is the job of the append-only, hash-chained ledgers:
 
 - **Telemetry ledger** (`telemetry.json`, one entry per agent hop): each entry
-  chains to the previous via `prevHash`, and `recordHash = sha256(canonical
-  entry)`. Flip a recorded verdict (`unattested` → `attested`) or edit a recorded
-  usage digest, and the chain no longer recomputes.
-- **Trust-audit event log** (`events.jsonl`): the same discipline applied to
+  chains to the one before through `prevHash`, and `recordHash = sha256(canonical
+  entry)`. Flip a recorded verdict (`unattested` → `attested`) or change a recorded
+  usage digest, and the chain no longer comes out the same.
+- **Trust-audit event log** (`events.jsonl`): the same care put on
   every recorded decision — sandbox path allow/deny, policy snapshots,
   verifier-gated commits, collaboration approvals.
 
-Verification **recomputes every hash independently and never trusts the stored
-value**, so an edited, reordered, removed, or truncated entry flips
-`verified = false`. A ledger that exists but cannot be parsed **fails closed** —
-it is treated as corrupt, never silently as the clean empty chain.
+Verification **works out every hash on its own and never trusts the stored
+value**, so a changed, reordered, removed, or cut-short entry flips
+`verified = false`. A ledger that is there but can not be parsed **fails closed** —
+it is taken as broken, never quietly as the clean empty chain.
 
 This is all **offline**. The chain re-proof needs **no key at all**; add
 `--pubkey <public.pem>` to re-run the signature **attribution** check against the
 stored raw usage for every `attested` record. There is no telemetry service to
-trust or breach — the record proves its own integrity, and a third-party auditor
+trust or break into — the record proves its own integrity, and a third-party auditor
 can re-run both checks on their own machine.
 
 ---
@@ -104,79 +104,79 @@ can re-run both checks on their own machine.
 ## What this DOES prove
 
 For telemetry, if `cw telemetry verify <run> --pubkey <public.pem>` reports green,
-you can rely on **all** of the following, and only these:
+you can put trust in **all** of the following, and only these:
 
-1. **Attribution.** Each `attested` usage figure was signed by the holder of the
-   configured private key, over a payload bound to that specific run, task, and
-   prompt. It is **non-repudiable**: the signer cannot later disown it, and it
-   could not have been replayed from a different hop.
+1. **Attribution.** Each `attested` usage number was signed by the holder of the
+   set private key, over a payload bound to that one run, task, and
+   prompt. It is **non-repudiable**: the signer can not later say it is not theirs, and it
+   could not have been used again from a different hop.
 2. **Tamper-evidence of the record.** The recorded ledger — verdicts, usage
-   digests, audit decisions — has not been edited, reordered, truncated, or had
-   entries removed since it was written, *to the extent a self-recomputable chain
-   can detect* (see the threat-model caveat below). Casual or partial tampering,
-   accidental corruption, truncation, and forged unchained lines are all caught.
+   digests, audit decisions — has not been changed, reordered, cut short, or had
+   entries taken out since it was written, *as far as a self-recomputable chain
+   can see* (see the threat-model note below). Light or part tampering,
+   damage by chance, cutting short, and faked unchained lines are all caught.
 3. **Offline, independent re-verification.** Re-proving the recorded ledger needs
-   no network, no CW service, and no trust in our infrastructure — `cw telemetry
-   verify` recomputes the chain on your machine (and needs no key to do it). With
-   `--pubkey`, the ed25519 **attribution** is independently re-checked with the
-   **public key alone**; `cw demo tamper` reproduces that sign-and-catch
-   end-to-end, offline. The integrity claim does not depend on trusting us.
-4. **CW never forged or measured anything.** CW holds no private key and never
-   calls a model. It cannot mint a signature, and it cannot fabricate a usage
-   number to sign. What it records, it received and verified.
+   no network, no CW service, and no trust in our setup — `cw telemetry
+   verify` works out the chain again on your machine (and needs no key to do it). With
+   `--pubkey`, the ed25519 **attribution** is checked again on its own with the
+   **public key by itself**; `cw demo tamper` does that sign-and-catch again
+   end-to-end, offline. The integrity claim does not rest on trusting us.
+4. **CW never faked or measured anything.** CW holds no private key and never
+   calls a model. It can not make a signature, and it can not make up a usage
+   number to sign. What it records, it took in and checked.
 
 ---
 
 ## What this DOES NOT prove
 
-Equally load-bearing. None of the following are within the guarantee, and we will
-not imply otherwise:
+Just as important. None of the following are inside the guarantee, and we will
+not give any other idea:
 
 1. **It does not prove the reported number is true.** A signature proves *who*
-   said it and that it *wasn't altered* — **not** that it was correct at the
-   source. Quoting the code's own honest ceiling:
+   said it and that it *was not changed* — **not** that it was right at the
+   source. To quote the code's own honest limit:
 
    > A dishonest keyholder can still sign a lie, but the lie is now
    > cryptographically bound to its signer.
 
-   CW deliberately does **not** independently measure usage (doing so would mean
-   calling the model — the red line it refuses to cross). So the strongest honest
+   CW on purpose does **not** measure usage on its own (to do so would mean
+   calling the model — the red line it will not cross). So the strongest honest
    claim is **attribution, not ground-truth measurement**.
 
-2. **It does not defend against a single party who holds both roles.** If the
+2. **It does not guard against a single party who holds both roles.** If the
    same operator runs CW, holds the signing private key, *and* controls the
-   machine the ledger lives on, then a green verdict attests that **that party**
-   signed and that **that party's** record is internally consistent. It does not
-   bring in any *independent* party. Self-consistency is not third-party
+   machine the ledger lives on, then a green verdict gives word that **that party**
+   signed and that **that party's** record agrees with itself. It does not
+   bring in any *separate* party. Agreeing with itself is not third-party
    verification.
 
-3. **A determined local writer can re-chain the whole log.** The hash-chain's
+3. **A set local writer can re-chain the whole log.** The hash-chain's
    genesis is `sha256(runId)` — a value the local writer knows. So the chain
-   detects edits to *part* of a log, but a writer who edits an entry and then
-   **re-computes every subsequent hash** with CW's own sha256 produces a log that
-   re-verifies green. From `trust-audit.ts`:
+   sees changes to *part* of a log, but a writer who changes an entry and then
+   **works out every later hash** with CW's own sha256 makes a log that
+   verifies green again. From `trust-audit.ts`:
 
    > THREAT MODEL (be honest about the limit): the genesis is sha256(runId), so
    > this detects casual/partial tampering, accidental corruption, truncation,
    > removal, and forged-unchained lines — but NOT a determined local writer who
    > re-chains the WHOLE log with this module's own sha256 after an edit.
 
-   This is **inherent** to any local, self-recomputable chain. Closing it needs an
-   anchor the writer cannot reproduce. CW **cannot mint that anchor itself** —
+   This is **built in** to any local, self-recomputable chain. To close it needs an
+   anchor the writer can not make again. CW **can not make that anchor itself** —
    because by design it holds no private key. The one cryptographic anchor that
-   exists is the **agent's** telemetry signature, which covers agent-reported
+   is there is the **agent's** telemetry signature, which covers agent-reported
    *usage* — it does **not** cover CW-only decisions (sandbox / policy /
-   commit-gate), which have no external signer.
+   commit-gate), which have no outside signer.
 
-   For those CW-only decisions, the only stronger guarantee available today is
-   **operational**, not cryptographic: commit `events.jsonl` to an external
+   For those CW-only decisions, the only stronger guarantee we have today is
+   **operational**, not cryptographic: commit `events.jsonl` to an outside
    append-only medium (git history, a remote append-only log) that the local
-   writer cannot rewrite. The chain is a **strict upgrade** over a bare
-   append-only log — not a substitute for an external anchor.
+   writer can not rewrite. The chain is a **clear step up** over a bare
+   append-only log — not a thing to use in place of an outside anchor.
 
 4. **It says nothing about the quality, safety, or correctness of the work.**
-   Attestation is about *provenance and integrity of records*, not about whether
-   the agent's output is good, secure, or even functional. Other CW mechanisms
+   Attestation is about *where records come from and the integrity of records*, not about whether
+   the agent's output is good, safe, or even working. Other CW parts
    (verifier gate, schema validation, evidence grounding) speak to that; the
    cryptography here does not.
 
@@ -184,84 +184,84 @@ not imply otherwise:
 
 ## The single-keyholder limitation (stated plainly)
 
-> **The core honest gap:** when the same operator runs CW and holds the only
-> verification/signing key, tamper-evidence proves that **records were not edited
-> after the fact** — it does **not** prove that the **original signer was
-> honest**. Integrity, yes. A trustworthy source, not necessarily.
+> **The main honest gap:** when the same operator runs CW and holds the only
+> verification/signing key, tamper-evidence proves that **records were not changed
+> after the fact** — it does **not** prove that the **first signer was
+> honest**. Integrity, yes. A source you can trust, not for certain.
 
-Concretely, in a single-party setup:
+To put it plainly, in a single-party setup:
 
-- The operator provisions the keypair.
+- The operator makes the keypair.
 - The operator's agent process signs usage with the private key.
 - CW (run by the same operator) verifies with the public key and writes the
   ledger to the operator's disk.
 
-Every cryptographic check can pass while a motivated single party fabricates the
-source number, or — given the genesis caveat above — rewrites the whole local
-chain. **Cryptography cannot manufacture a second party that does not exist.**
-Separation of duties is the property auditors require everywhere; with one
-operator wearing both hats, it is structurally absent no matter how good the
+Every cryptographic check can pass while a single party who wants to lie makes up the
+source number, or — given the genesis note above — rewrites the whole local
+chain. **Cryptography can not make a second party that is not there.**
+Separation of duties is the property auditors need everywhere; with one
+operator wearing both hats, it is missing by design no matter how good the
 math is.
 
-We are not going to argue this point away. It is real, it is the most important
-limitation in this document, and it is the right critique to raise.
+We are not going to talk this point away. It is real, it is the most important
+limit in this page, and it is the right point to bring up.
 
 ---
 
 ## Closing the gap: the second party
 
-The fix is **not** more cryptography on one machine — it is an **independent
-second party**, which is precisely the thing a single operator cannot self-supply.
-This is why CW's near-term priority is **early integration partners**, and what we
-mean by that concretely:
+The fix is **not** more cryptography on one machine — it is a **separate
+second party**, which is just the thing a single operator can not give itself.
+This is why CW's near-term aim is **early integration partners**, and what we
+mean by that plainly:
 
-- **An independent co-signer / second keyholder.** A second party (a different
+- **A separate co-signer / second keyholder.** A second party (a different
   team, a CI identity outside the operator's control, or a partner's signing
   service) holds a key the operator does not. When that party counter-signs runs —
   or *is* the executor that signs usage — a green verdict starts to mean
   "two parties who do not fully trust each other agree," which is the property
-  single-party attestation structurally cannot provide.
-- **An external append-only anchor.** Pushing `events.jsonl` to a medium the local
-  operator cannot rewrite (a partner-held log, a public transparency log, signed
-  git history on a remote the operator doesn't control) closes the re-chain gap
-  for CW-only decisions described above.
+  single-party attestation by its nature can not give.
+- **An outside append-only anchor.** Pushing `events.jsonl` to a medium the local
+  operator can not rewrite (a partner-held log, a public transparency log, signed
+  git history on a remote the operator does not control) closes the re-chain gap
+  for CW-only decisions named above.
 - **Separated execution and verification.** The party that *spends the money*
-  (runs the model) and the party that *keeps the books* (CW) being genuinely
-  different entities turns CW's separation-of-duties design from an architectural
-  intent into an enforced fact.
+  (runs the model) and the party that *keeps the books* (CW) being truly
+  different bodies turns CW's separation-of-duties design from a plan
+  into an enforced fact.
 
-If you are a potential partner who can supply an independent second party — a
-co-signer, an external anchor, or separated execution — **that is the
-collaboration we are actively looking for.** We would rather ship this honestly
-and earn the second party than paper over the gap with a stronger-sounding claim
-than the math supports.
+If you are a possible partner who can give a separate second party — a
+co-signer, an outside anchor, or separated execution — **that is the
+work together we are now looking for.** We would rather ship this honestly
+and earn the second party than cover over the gap with a claim that sounds stronger
+than the math will back up.
 
 ---
 
 ## How to verify for yourself
 
-- `cw telemetry verify <run>` — re-proves the telemetry ledger's **integrity**:
-  chain linkage + an independent per-record hash recompute, so any edit to a
+- `cw telemetry verify <run>` — proves the telemetry ledger's **integrity** again:
+  chain linkage + a per-record hash worked out on its own, so any change to a
   recorded verdict or usage digest since record time flips it red. It needs **no
-  key** (it re-proves the *recording*). Add `--pubkey <pem-or-path>` to re-run the
+  key** (it proves the *recording* again). Add `--pubkey <pem-or-path>` to re-run the
   ed25519 **signature** check for every `attested` record against the stored raw
-  usage; unreadable keys, missing raw usage, digest mismatches, wrong keys, and
+  usage; keys that can not be read, missing raw usage, digest mismatches, wrong keys, and
   signature mismatches fail closed. Mirrored as `cw_telemetry_verify` on the MCP
   surface.
-- `cw demo tamper` — a hermetic, offline, one-command proof: it builds a real
-  ed25519-signed ledger and then forges it two ways — flips a recorded verdict and
-  re-computes the *local* record hash (the chain still breaks), and reuses a
-  signature over inflated tokens (ed25519 rejects it). Everything is verified with
+- `cw demo tamper` — a sealed, offline, one-command proof: it builds a real
+  ed25519-signed ledger and then fakes it two ways — flips a recorded verdict and
+  works out the *local* record hash again (the chain still breaks), and uses a
+  signature again over blown-up tokens (ed25519 turns it down). Everything is checked with
   the public key only. The `✗ DETECTED` lines are the point.
 - Re-run either with **only the public key** on a machine we do not control. If it
-  doesn't reproduce, our integrity claim is false — hold us to it.
+  does not come out the same, our integrity claim is false — hold us to it.
 
 ---
 
 ## One-line summary
 
-CW's cryptography proves **records weren't edited and were signed by the
+CW's cryptography proves **records were not changed and were signed by the
 keyholder** — strong, offline, public-key-verifiable **integrity and
 attribution**. It does **not** prove the **source was honest**, and a single
-operator holding both roles is the honest limit we are explicitly recruiting
+operator holding both roles is the honest limit we are openly looking for
 integration partners to close.