cool-workflow 0.1.82 → 0.1.83

package/docs/web-desktop-workbench.7.md

@@ -1,99 +1,99 @@
 # Web / Desktop Workbench
 
-CW v0.1.30 adds the Web / Desktop Workbench: a human-facing console that renders
+CW v0.1.30 adds the Web / Desktop Workbench: a console for people that shows
 a run's five operator surfaces — run graph, blackboard, worker logs, candidate
-compare, and audit timeline — plus a cross-run entry point over the v0.1.28 Run
+compare, and audit timeline — plus a way in across runs over the v0.1.28 Run
 Registry. It is a THIRD FRONT DOOR, not a new brain.
 
-Before v0.1.30 CW had no web/HTTP/UI surface at all: the CLI rendered for human
-speed and the MCP server (JSON-RPC over stdio) rendered for machine context. The
-Workbench adds human inspection at a glance — and adds NOTHING else. It computes,
-decides, and stores nothing the CLI/MCP cannot already produce.
+Before v0.1.30 CW had no web/HTTP/UI surface at all: the CLI showed things at human
+speed and the MCP server (JSON-RPC over stdio) showed things for machine context. The
+Workbench lets a person look at a run quickly — and adds NOTHING else. It works out,
+decides, and keeps nothing that the CLI/MCP cannot already make.
 
 ## The third front door (mechanism vs policy)
 
 The kernel and the durable `.cw/` state are the MECHANISM. The CLI, the MCP
-surface, and the Workbench are three renderings — three policies — over that one
+surface, and the Workbench are three ways to show it — three policies — over that one
 mechanism:
 
 - the per-run `.cw/runs/<id>/state.json` is the SINGLE source of truth
-- the v0.1.28 Run Registry is a DERIVED, rebuildable index over runs across repos
+- the v0.1.28 Run Registry is a DERIVED index over runs across repos that you can build again
 - the Workbench is a STATELESS, READ-ONLY RENDERER over both
 
-Every Workbench panel embeds, VERBATIM, the canonical `--json` payload of ONE
-already-declared capability, assembled by calling the SAME capability core
-entries the CLI and MCP route through (the v0.1.27 parity contract, see
+Every Workbench panel holds, VERBATIM, the true `--json` payload of ONE
+capability already named, put together by calling the SAME capability core
+entries the CLI and MCP go through (the v0.1.27 parity contract, see
 [CLI ↔ MCP Parity](cli-mcp-parity.7.md)). The Workbench can show nothing the CLI
-or MCP cannot; a `workbench.view` panel is byte-for-byte equal to its underlying
-`cw <cmd> --json` payload, and that equality is parity-gated.
+or MCP cannot; a `workbench.view` panel is byte-for-byte equal to the
+`cw <cmd> --json` payload under it, and that sameness is parity-gated.
 
 ## No hidden dashboard database
 
-CW's README promises there is "no hidden dashboard database." The Workbench
-upholds that promise by holding ZERO authoritative state:
+CW's README gives its word that there is "no hidden dashboard database." The Workbench
+keeps that word by holding ZERO authoritative state:
 
-- it persists nothing — there is no Workbench store, cache, or schema
-- every response is re-derived on demand from disk; refresh re-reads `.cw/`
+- it keeps nothing — there is no Workbench store, cache, or schema
+- every response is made again, when asked, from disk; refresh re-reads `.cw/`
 - delete the host process and nothing is lost — the data IS the files
 - it forks no run/state schema; the view models in `src/types.ts`
   (`WorkbenchRunView`, `WorkbenchPanel`, `WorkbenchServeDescriptor`) are DERIVED
-  projections that embed existing payloads, never copies of them
+  projections that hold payloads that already exist, never copies of them
 
-The Workbench is OPTIONAL, like Bun is an optional execution backend: the
-committed `dist/` and a plain `node` runtime keep working with the Workbench (and
-its static UI assets under `ui/workbench/`) absent. The kernel imports the
+The Workbench is OPTIONAL, the way Bun is an optional execution backend: the
+committed `dist/` and a plain `node` runtime keep working when the Workbench (and
+its static UI assets under `ui/workbench/`) is not there. The kernel imports the
 Workbench never; the Workbench imports the kernel.
 
 ## The five panels
 
-Each panel renders existing operator vocabulary, with the same names and
-semantics as the CLI (least astonishment). For run `<id>`:
+Each panel shows operator words that already exist, with the same names and
+meaning as the CLI (least surprise). For run `<id>`:
 
 1. RUN GRAPH — `cw graph <id> --json` (operator graph) plus
    `cw multi-agent graph <id> [--view compact|critical-path] --json`. Backend
-   ids/attestations (v0.1.29) ride on the nodes; the critical path, failures,
-   missing evidence, and policy violations are never collapsed.
+   ids/attestations (v0.1.29) sit on the nodes; the critical path, failures,
+   missing evidence, and policy violations are never folded away.
 2. BLACKBOARD — `cw coordinator summary <id>`, `cw blackboard summarize <id>
    --json`, and `cw blackboard graph <id>`: topics, messages, contexts,
    artifacts, snapshots, decisions, conflicts, and adopted/missing evidence.
 3. WORKER LOGS — `cw worker summary <id> --json`: manifests, outputs, scoped
    results, failures, and the recorded execution backend + sandbox attestation.
 4. CANDIDATE COMPARE — `cw candidate summary <id> --json` plus
-   `cw multi-agent reasoning <id> --json`: scores, selection, rejection reasons,
+   `cw multi-agent reasoning <id> --json`: scores, selection, reasons for turning down,
    and the v0.1.26 evidence-adoption reasoning chain (why adopted).
 5. AUDIT TIMELINE — `cw audit summary <id>`, `cw audit multi-agent <id> --json`,
    `cw audit policy <id> --json`, and `cw audit judge <id> --json`: trust-audit
    events, role policy decisions, provenance, judge/chair rationale, and policy
    violations.
 
-Cross-run entry lists/searches runs via the Run Registry (`cw registry show
---json` + `cw run list|search --json`); drilling into a run opens its five panels.
+The way in across runs lists/searches runs through the Run Registry (`cw registry show
+--json` + `cw run list|search --json`); going into a run opens its five panels.
 
 ## Explicit, inspectable, fail closed
 
-The Workbench surfaces freshness honestly. When a source capability is unreadable
-(a run with no blackboard yet, or unresolvable state), the panel is rendered
-`absent` with the honest error — exactly what the CLI would report — and the view
-is `resolved: false`. It never fabricates a view when source state is unreadable.
+The Workbench shows freshness in a true way. When a source capability cannot be read
+(a run with no blackboard yet, or state that cannot be worked out), the panel is shown
+`absent` with the true error — just what the CLI would report — and the view
+is `resolved: false`. It never makes up a view when source state cannot be read.
 The same `valid`/`stale`/`absent`/`missing` freshness the runtime already records
-(Run Registry, Evidence Adoption Reasoning Chain, state-explosion summaries) flows
+(Run Registry, Evidence Adoption Reasoning Chain, state-explosion summaries) goes
 through verbatim.
 
 ## Trust boundary
 
-The host is least-privilege and local by default:
+The host has least privilege and is local by default:
 
 - it binds the loopback interface `127.0.0.1` ONLY — never a public address
-- it is READ-ONLY: every route is `GET`; any write verb is refused `405`
-- it rejects non-localhost `Host` headers (a DNS-rebinding defense) with `403`
-- it refuses path traversal out of `ui/workbench/` with `403`
-- it serves nothing beyond the current user's `.cw/` scope and the Run Registry's
+- it is READ-ONLY: every route is `GET`; any write verb is turned away with `405`
+- it turns away non-localhost `Host` headers (a DNS-rebinding defense) with `403`
+- it turns away path traversal out of `ui/workbench/` with `403`
+- it serves nothing past the current user's `.cw/` scope and the Run Registry's
   registered repos
 - it fails closed on anything it cannot read
 
-The console is read-only. It offers no actions. If a future release adds an action
-(resume, rerun, dispatch), that action MUST route through an existing declared
-capability core entry — never a parallel code path — so it cannot drift from the
+The console is read-only. It offers no actions. If a later release adds an action
+(resume, rerun, dispatch), that action MUST go through a declared
+capability core entry that already exists — never a side code path — so it cannot drift from the
 CLI/MCP and is covered by the parity gate.
 
 ## Surfaces
@@ -104,13 +104,13 @@ cw workbench serve [--port N] [--scope repo|home] [--once|--json]
 ```
 
 `cw workbench serve` with `--once`/`--json` prints the serve descriptor (bind
-host/port, scope, routes) and exits without starting a server; the default starts
+host/port, scope, routes) and stops without starting a server; the default starts
 the localhost host (like `schedule daemon`). The MCP tools `cw_workbench_view` and
-`cw_workbench_serve` mirror these: `cw_workbench_view` returns the same view as the
-CLI `--json`, and `cw_workbench_serve` returns the descriptor only — an MCP stdio
-host cannot start a blocking server. That single side-effect difference is the
-declared, documented payload divergence recorded in `src/capability-registry.ts`;
-the descriptor payload itself is identical across surfaces.
+`cw_workbench_serve` match these: `cw_workbench_view` gives back the same view as the
+CLI `--json`, and `cw_workbench_serve` gives back the descriptor only — an MCP stdio
+host cannot start a server that blocks. That one side-effect difference is the
+declared, documented payload divergence written down in `src/capability-registry.ts`;
+the descriptor payload itself is the same across surfaces.
 
 The read-only HTTP routes the host serves:
 
@@ -124,9 +124,9 @@ GET /api/run/:runId         # the five-panel WorkbenchRunView
 
 ## Version
 
-This is CW v0.1.30. The Workbench changes no run-state schema and requires no
-migration: it is a pure read-only projection over existing durable state and
-existing capability payloads. Removing it leaves the framework fully functional.
+This is CW v0.1.30. The Workbench changes no run-state schema and needs no
+migration: it is a pure read-only projection over durable state that already exists and
+capability payloads that already exist. Taking it away leaves the framework fully working.
 
 See also [Operator UX](operator-ux.7.md), [CLI ↔ MCP Parity](cli-mcp-parity.7.md),
 and [Run Registry / Control Plane](run-registry-control-plane.7.md).
@@ -134,12 +134,12 @@ and [Run Registry / Control Plane](run-registry-control-plane.7.md).
 ## Observability + Cost Accounting (v0.1.31)
 
 v0.1.31 adds Observability + Cost Accounting: `metrics show`/`metrics summary`
-derive durations, failure/verifier/acceptance rates (with sample counts and
-fail-closed `n/a`), and host-attested token/cost from existing durable run state
+work out durations, failure/verifier/acceptance rates (with sample counts and
+fail-closed `n/a`), and host-attested token/cost from durable run state that already exists
 — no metrics database, no collector daemon, no hidden counter. Usage is additive
 and optional (absent ⇒ `unreported`, never 0); cost is `attested` (attested usage
 × a recorded pricing policy) or clearly `estimated`, with pricing as policy. Both
-verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
+verbs are parity-gated and show read-only in the v0.1.30 Workbench. See
 [observability-cost-accounting.7.md](observability-cost-accounting.7.md).
 
 
@@ -149,19 +149,19 @@ v0.1.32 adds Team Collaboration: a host-attested actor and append-only
 approvals/rejections/comments/handoffs provenance-linked to a durable target,
 plus a review gate that STACKS ON the verifier gate — required approvals from
 authorized roles, enforced inside `resolveCommitGate` AFTER the verifier checks
-and never instead of them, failing closed on quorum/authority/self-approval and
+and never in place of them, failing closed on quorum/authority/self-approval and
 recording who approved the very artifact that shipped. Policy (required approvals,
-authorized roles, self-approval) is data, default off (pre-v0.1.32 behavior
-unchanged). The verbs are parity-gated and render read-only in the v0.1.30
+authorized roles, self-approval) is data, off by default (pre-v0.1.32 behavior
+unchanged). The verbs are parity-gated and show read-only in the v0.1.30
 Workbench. See [Team Collaboration](team-collaboration.7.md).
 
 ## 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 release gate that has no doubled steps. See release-tooling(7).
 
 ## 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 run (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. See real-execution-backends(7).
 
 ## Node Snapshot / Diff / Replay (v0.1.35)
 
@@ -169,7 +169,7 @@ per-node snapshot, structural diff, and isolated deterministic replay over State
 
 ## Contract Migration Tooling (v0.1.36)
 
-first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
+first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover that checks it. See contract-migration-tooling(7).
 
 ## Control-Plane Scheduling (v0.1.37)
 
@@ -177,11 +177,11 @@ priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed pa
 
 ## 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 result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
 
 ## 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: seal the audit skeleton, free the bulk that can be built again, prove it
 
 ## Durable State & Locking (v0.1.40)
 
@@ -193,15 +193,15 @@ 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
+take findings/evidence from any reasonable agent shape (alt keys + prose), CW works out grounded evidence itself, warn 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 that blocks 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 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 interface to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
@@ -218,7 +218,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, Map and Assess results you can use again, 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 Web / Desktop Workbench 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/worker-isolation.7.md

@@ -28,15 +28,15 @@ node dist/cli.js dispatch <run-id> --sandbox readonly
 
 ## DESCRIPTION
 
-Worker Isolation is the small boundary layer between dispatch manifests, worker
-task prompts, worker-local files, result envelopes, StateNode records,
-PipelineRunner verifier gates, ErrorFeedback, and reports.
+Worker Isolation is the small boundary layer that sits between dispatch
+manifests, worker task prompts, worker-local files, result envelopes, StateNode
+records, PipelineRunner verifier gates, ErrorFeedback, and reports.
 
 It is not a process sandbox, container runtime, lease manager, or autonomous
 agent spawner. CW still writes task artifacts. Operators or the agent host run
-workers explicitly and return results through declared files.
+workers themselves and send results back through named files.
 
-The kernel owns only:
+The kernel keeps only these jobs:
 
 - worker scope allocation
 - stable worker manifests
@@ -48,8 +48,8 @@ The kernel owns only:
 
 ## WORKER MODEL
 
-Dispatch moves runnable tasks to `running` and allocates one worker scope per
-dispatched task. Each worker receives a plain input file and a result path.
+Dispatch moves runnable tasks to `running` and gives one worker scope to each
+dispatched task. Each worker gets a plain input file and a result path.
 
 The normal flow is:
 
@@ -58,14 +58,14 @@ dispatch task -> worker scope -> worker.json + manifest.json/input.md -> result.
 -> result node -> verifier node -> commit/report
 ```
 
-Worker output does not mutate shared run state directly. CW records accepted
-output as result and verifier nodes after boundary checks pass.
+Worker output does not change shared run state on its own. CW records accepted
+output as result and verifier nodes after the boundary checks are passed.
 
 ## ISOLATION BOUNDARIES
 
-Isolation is path and contract based.
+Isolation is based on path and contract.
 
-In CW v0.1.8, named Sandbox Profiles define the worker read paths, write paths,
+In CW v0.1.8, named Sandbox Profiles set the worker read paths, write paths,
 command policy, network policy, environment policy, worker output allowances,
 and host enforcement instructions. See `sandbox-profiles.7.md`.
 
@@ -75,11 +75,11 @@ inside `artifacts/` when `workerOutput.artifacts` is allowed, inside `logs/`
 when `workerOutput.logs` is allowed, or inside an explicitly allowed path
 passed by the legacy runtime policy.
 
-Reads and writes are represented separately. CW validates accepted output writes
-it records. The agent host must enforce actual OS-level read/write restrictions
-while the worker is running.
+Reads and writes are shown apart from each other. CW checks the accepted output
+writes that it records. The agent host must enforce the real OS-level read and
+write limits while the worker is running.
 
-Out-of-scope output is rejected and preserved as:
+Out-of-scope output is rejected and kept as:
 
 - a failed or rejected worker scope
 - an `error` StateNode
@@ -101,27 +101,25 @@ Out-of-scope output is rejected and preserved as:
 ```
 
 `worker.json` is the durable worker-scope state record. `manifest.json` is the
-worker-facing projection that hosts and agents read before writing `result.md`.
-Keeping them separate prevents a regenerated manifest from overwriting
-scope-only runtime state such as retry counters, lifecycle metadata, or future
-operator annotations. New v0.1.8 worker records include `sandboxProfileId`,
-`sandboxPolicy`, and a `sandbox` host contract with `enforcedByCW` and
-`hostRequired`.
+worker-facing view that hosts and agents read before they write `result.md`.
+Keeping them apart stops a rebuilt manifest from writing over scope-only runtime
+state such as retry counters, lifecycle metadata, or later operator notes. New
+v0.1.8 worker records hold `sandboxProfileId`, `sandboxPolicy`, and a `sandbox`
+host contract with `enforcedByCW` and `hostRequired`.
 
 ## FAILURE MODES
 
-Missing result files are retryable worker failures.
+Missing result files are worker failures that can be retried.
 
-Boundary violations are rejected worker outputs. They are not accepted into
-result state. Sandbox write denials use `sandbox-write-denied`; unknown and
-invalid profiles use `sandbox-profile-not-found` and `sandbox-profile-invalid`.
+Boundary violations are rejected worker outputs. They are not taken into result
+state. Sandbox write denials use `sandbox-write-denied`; unknown and invalid
+profiles use `sandbox-profile-not-found` and `sandbox-profile-invalid`.
 
-Verifier failures remain verifier failures. Worker Isolation preserves the
-worker directory and records feedback so the operator can inspect or correct the
-result.
+Verifier failures stay verifier failures. Worker Isolation keeps the worker
+directory and records feedback so the operator can look at or fix the result.
 
 Corrupt run state, unknown workers, and unknown tasks are hard errors because
-the runtime cannot proceed safely.
+the runtime cannot go on safely.
 
 ## EXAMPLES
 
@@ -151,17 +149,16 @@ node dist/cli.js worker fail <run-id> <worker-id> --message "worker could not in
 
 ## COMPATIBILITY
 
-Worker Isolation is introduced in CW v0.1.5. It adds optional worker fields to
+Worker Isolation is first added in CW v0.1.5. It adds optional worker fields to
 run paths, tasks, dispatch tasks, dispatch records, summaries, and run state.
 
-Sandbox Profiles are introduced in CW v0.1.8. The legacy `allowedPaths` field
-remains available and now mirrors effective write acceptance paths for older
-hosts. New hosts should prefer `sandboxPolicy.readPaths`,
+Sandbox Profiles are first added in CW v0.1.8. The legacy `allowedPaths` field
+is still there and now matches the effective write acceptance paths for older
+hosts. New hosts should use `sandboxPolicy.readPaths`,
 `sandboxPolicy.writePaths`, `sandboxPolicy.workerOutput`, and
 `sandbox.hostRequired`.
 
-Existing `plan`, `dispatch`, `result`, `node`, `contract`, and `feedback`
-commands remain compatible. The legacy `result` command still accepts a task id
-and result file. The stricter boundary-aware path is the `worker output`
-command.
+The existing `plan`, `dispatch`, `result`, `node`, `contract`, and `feedback`
+commands still work. The legacy `result` command still takes a task id and
+result file. The stricter boundary-aware path is the `worker output` command.
 0.1.51

package/docs/workflow-app-framework.7.md

@@ -27,12 +27,12 @@ node scripts/cw.js plan my-app --question "What should happen?"
 
 ## Description
 
-CW treats the runner as the base system and workflow apps as userland. The
+CW uses the runner as the base system and workflow apps as userland. The
 runner owns state transitions, dispatch, result recording, verifier gates,
-commits, and reports. A workflow app owns domain-specific inputs, phases, task
-prompts, evidence requirements, and sandbox profile hints.
+commits, and reports. A workflow app owns its own inputs, phases, task
+prompts, evidence needs, and sandbox profile hints.
 
-The framework is intentionally small. The public app helpers are:
+The framework is kept small on purpose. The public app helpers are:
 
 - `defineWorkflowApp(definition)`
 - `workflow(definition)`
@@ -41,9 +41,9 @@ The framework is intentionally small. The public app helpers are:
 - `artifact(id, prompt, options)`
 - `input(name, options)`
 
-Legacy workflow factories remain valid. If a canonical app owns the public id,
-the legacy wrapper should use an explicit compatibility id such as
-`legacy-research-synthesis` to avoid duplicate discovery:
+Legacy workflow factories are still good to use. If a canonical app owns the public id,
+the legacy wrapper should use a clear compatibility id such as
+`legacy-research-synthesis` so the same app is not found twice:
 
 ```js
 module.exports = ({ workflow, phase, agent, artifact }) =>
@@ -61,7 +61,7 @@ module.exports = ({ workflow, phase, agent, artifact }) =>
 
 ## App Contract
 
-A first-class app contract is a plain object:
+A first-class app contract is a simple object:
 
 ```js
 module.exports = defineWorkflowApp({
@@ -101,30 +101,30 @@ module.exports = defineWorkflowApp({
 });
 ```
 
-The durable fields are:
+The lasting fields are:
 
-- `schemaVersion`: currently `1`
+- `schemaVersion`: now `1`
 - `id`: stable app id, lowercase letters, digits, dots, and hyphens
-- `title`: human-readable name
-- `summary`: short description
+- `title`: name people can read
+- `summary`: short note
 - `version`: semver app version
 - `author`: string or `{ name, url, email }`
 - `workflow`: workflow definition or manifest entrypoint
-- `inputs`: declared input definitions
-- `sandboxProfiles`: named bundled sandbox profiles used by the app
-- `compatibility`: optional CW version constraints
+- `inputs`: the input definitions you set
+- `sandboxProfiles`: named bundled sandbox profiles the app uses
+- `compatibility`: optional CW version limits
 - `metadata`: app-owned JSON metadata
 
 ## App Directory
 
-CW also discovers app directories:
+CW also finds app directories:
 
 ```text
 apps/<app-id>/app.json
 apps/<app-id>/workflow.js
 ```
 
-`app.json` stores the app metadata and points at a relative workflow entrypoint:
+`app.json` keeps the app metadata and points at a relative workflow entrypoint:
 
 ```json
 {
@@ -139,7 +139,7 @@ apps/<app-id>/workflow.js
 }
 ```
 
-The entrypoint may export a workflow object or a factory:
+The entrypoint may give out a workflow object or a factory:
 
 ```js
 module.exports = ({ workflow, phase, agent, input }) => {
@@ -159,18 +159,18 @@ module.exports = ({ workflow, phase, agent, input }) => {
 
 ## Validation
 
-App loading fails closed. CW validates:
+App loading fails closed. CW checks:
 
 - app `schemaVersion`, `id`, `title`, and semver `version`
-- input names, types, duplicate inputs, and boolean flags
-- workflow id/title matching the app id/title
-- positive limits and `maxConcurrentAgents <= maxAgents`
-- phase ids and duplicate phase ids
-- task ids, duplicate task ids, task kind, prompt, and evidence flags
+- input names, types, the same input given twice, and boolean flags
+- workflow id/title that match the app id/title
+- limits above zero and `maxConcurrentAgents <= maxAgents`
+- phase ids and the same phase id given twice
+- task ids, the same task id given twice, task kind, prompt, and evidence flags
 - sandbox profile references on the app, workflow, and tasks
-- compatibility constraints against the current CW runtime
+- compatibility limits against the current CW runtime
 
-`cw.js app validate` prints a structured result. Invalid apps return nonzero:
+`cw.js app validate` prints a structured result. Apps that are not valid return nonzero:
 
 ```json
 {
@@ -185,7 +185,7 @@ App loading fails closed. CW validates:
 }
 ```
 
-CW does not silently rewrite malformed apps into runnable workflows.
+CW does not quietly change broken apps into workflows that can run.
 
 ## CLI
 
@@ -197,20 +197,20 @@ node scripts/cw.js app init <app-id> --title "Title"
 node scripts/cw.js app package <app-id> --output app.cwapp.json
 ```
 
-`cw.js list`, `cw.js init`, and `cw.js plan` remain compatible. `list` includes
-legacy workflow files and first-class app directories. `plan` accepts either
+`cw.js list`, `cw.js init`, and `cw.js plan` still work the same way. `list` shows
+legacy workflow files and first-class app directories. `plan` takes either
 kind by id.
 
 ## Canonical Apps
 
-CW v0.1.13 includes four maintained canonical app directories:
+CW v0.1.13 comes with four kept-up canonical app directories:
 
 - `architecture-review`
 - `pr-review-fix-ci`
 - `release-cut`
 - `research-synthesis`
 
-These apps are official userland pressure tests for the framework. They use declared
+These apps are the official userland hard tests for the framework. They use set
 inputs, compatibility metadata, sandbox profile hints, and evidence-required
 verification or synthesis/verdict tasks. Validate and plan the full matrix with:
 
@@ -222,7 +222,7 @@ See [canonical-workflow-apps.7.md](canonical-workflow-apps.7.md).
 
 ## MCP
 
-The MCP bridge exposes matching tools:
+The MCP bridge gives matching tools:
 
 - `cw_app_list`
 - `cw_app_show`
@@ -232,16 +232,16 @@ The MCP bridge exposes matching tools:
 - `cw_app_run`
 
 Tool results are JSON and use the same app summaries and validation issue
-records as the CLI. `cw_app_run` creates a run from an app id and structured
-`inputs`, then returns the run id, app id/version, state/report paths, pending
-task count, compact operator status, and next actions.
+records as the CLI. `cw_app_run` makes a run from an app id and structured
+`inputs`, then gives back the run id, app id/version, state/report paths, the count of
+tasks still waiting, short operator status, and next actions.
 
-The full agent-host runtime surface is documented in
+The full agent-host runtime surface is written up in
 [mcp-app-surface.7.md](mcp-app-surface.7.md).
 
 ## State And Reports
 
-Run state records compact app metadata at:
+Run state keeps short app metadata at:
 
 ```text
 state.json.workflow.app
@@ -254,7 +254,7 @@ Workflow App: <id>@<version>
 Workflow App Source: <manifest-or-entrypoint-path>
 ```
 
-CW stores app identity, version, compatibility, source path, sandbox profile
+CW keeps app identity, version, compatibility, source path, sandbox profile
 references, and metadata. It does not copy workflow source into run state.
 
 ## Files

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.1.82",
+    "version": "0.1.83",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {
@@ -20,9 +20,9 @@
     ]
   },
   "descriptions": {
-    "short": "Auditable workflow control-plane.",
-    "standard": "Auditable workflow control-plane and orchestration runtime: TypeScript dispatch, evidence-gated verification, state commits, scheduling, routines, multi-agent coordination, and MCP. Delegates execution to external agents — never runs models.",
-    "long": "Cool Workflow (CW) is an auditable workflow control-plane and orchestration runtime. It provides a TypeScript COL runtime, Workflow App framework contracts, Router/Orchestrator, Subagent Dispatch, Deterministic Harness, Adversarial Verifier, Git/State Commit, Sandbox Profiles, scheduled tasks, routine triggers, a high-level Multi-Agent CLI/MCP host surface, and an MCP JSON-RPC 2.0 bridge. Developers write reusable workflow apps; CW delegates execution to an external agent host and records verified, replayable state — it never embeds a model API."
+    "short": "A workflow control plane you are able to check.",
+    "standard": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
+    "long": "Cool Workflow (CW) is a workflow control plane and run-time you are able to check. It gives you: a TypeScript COL run-time, Workflow App framework agreements, a Router and Orchestrator, Subagent Dispatch, a same-every-time Harness, a hard-questioning Verifier, Git and State Commit, Sandbox Profiles, time-ordered jobs, jobs that come round again, a high-level Multi-Agent CLI and MCP host face, and an MCP JSON-RPC 2.0 bridge. Builders make workflow apps they are able to use again; CW gives the doing of the work to an outside agent host and keeps a checked, play-again record of state — it never puts a model API inside itself."
   },
   "interface": {
     "displayName": "Cool Workflow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -14,7 +14,7 @@
   "bugs": {
     "url": "https://github.com/coo1white/cool-workflow/issues"
   },
-  "description": "Auditable workflow control-plane and orchestration runtime: TypeScript dispatch, evidence-gated verification, state commits, scheduling, routines, multi-agent coordination, and MCP. Delegates execution to external agents — never runs models.",
+  "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
   "type": "commonjs",
   "license": "BSD-2-Clause",
   "author": {
@@ -51,6 +51,7 @@
     "forward-ref": "node scripts/forward-ref-docs.js",
     "verify:container": "node scripts/verify-container-selfref.js",
     "gen:manifests": "node scripts/gen-manifests.js",
+    "gen:parity": "node scripts/gen-parity-doc.js",
     "manifest:load-check": "node test/vendor-manifest-load-smoke.js",
     "parity:check": "node scripts/parity-check.js --check",
     "version:sync": "node scripts/version-sync-check.js",