docs: explain Codex plugin workflow

README.md

@@ -48,6 +48,37 @@ cewp init
 cewp doctor
 ```
 
+The npm install provides the `cewp` and `cewp-mcp` commands. It does not
+automatically register the CEWP Codex plugin.
+
+## Install The Codex Plugin
+
+The full local plugin bundles three CEWP skills, the local `cewp-mcp` bridge,
+review-required subagent evidence hooks, and plugin metadata. After installing
+the npm package globally, register its marketplace with Codex.
+
+PowerShell:
+
+```powershell
+$cewpPackage = Join-Path (npm root -g) "@setrathex\codex-engineering-workflow-pack"
+codex plugin marketplace add "$cewpPackage"
+codex plugin add cewp@cewp-local
+codex plugin list
+```
+
+macOS or Linux:
+
+```bash
+codex plugin marketplace add "$(npm root -g)/@setrathex/codex-engineering-workflow-pack"
+codex plugin add cewp@cewp-local
+codex plugin list
+```
+
+Restart Codex, open a new conversation, and enable CEWP from the Plugins
+Directory. This installs the complete plugin on the current machine from a
+local marketplace source; it does not list CEWP in the universal public plugin
+directory.
+
 To evaluate the exact GitHub candidate before or without a registry publication,
 run it from a source checkout:
 
@@ -57,6 +88,13 @@ cd Codex-Engineering-Workflow-Pack
 node ./bin/cewp.js doctor
 ```
 
+The source checkout can also be registered directly:
+
+```bash
+codex plugin marketplace add /path/to/Codex-Engineering-Workflow-Pack
+codex plugin add cewp@cewp-local
+```
+
 Run the credential-free walkthrough:
 
 ```bash
@@ -89,6 +127,40 @@ cewp policy reset
 The advanced policy permits requested local operations; it does not disable
 scope, budget, verification, ownership, or reviewer gates.
 
+## Use CEWP From Codex
+
+The intended product interaction is a normal Codex request that explicitly
+selects CEWP:
+
+```text
+Use CEWP to complete @roadmap.md. Turn it into bounded checkpoints, use
+independent workers only where scopes do not overlap, verify every checkpoint,
+require reviewer PASS, preserve receipts, and stop on a closed gate.
+```
+
+Native Codex `/goal` keeps a persistent objective attached to the active task.
+CEWP does not replace or control that private host goal. The plugin adds an
+engineering control plane around the work: source-bound planning, explicit
+scope, isolated worktrees, budgets, deterministic verification, recovery,
+independent review, and final evidence.
+
+Today CEWP provides three related execution levels:
+
+1. **Supervised checkpoint:** the plugin plans and runs one bounded managed
+   checkpoint at a time through CEWP Core.
+2. **Coordinator Mode:** CEWP can run two non-overlapping `codex-exec` workers
+   sequentially or in parallel, then run an independent reviewer.
+3. **Workflow runtime:** CEWP validates versioned DAGs, dependencies, worker
+   capacity, budgets, revisions, results, and reviewer gates.
+
+The complete one-sentence-to-finished-roadmap experience is a product direction,
+not a current completion claim. The workflow compiler currently emits a
+source-bound agent request; the host agent must produce the structured workflow
+proposal, and approval, task start/result, review, and finalization transitions
+remain explicit. Codex can spawn native subagents when directly requested or
+when plugin/project instructions request them, but CEWP currently treats native
+subagent hooks as optional evidence rather than canonical execution control.
+
 ## Safety Model
 
 CEWP Core is the authority for every completion claim:

docs/release-notes.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Changed
+
+- Documented full CEWP Codex plugin installation from the globally installed npm
+  package as a separate step from CLI installation.
+- Clarified the intended roadmap-driven Codex experience and the current boundary
+  between supervised checkpoints, Coordinator Mode, workflow DAG state, and
+  native Codex subagent evidence.
+
 ## 0.14.0-beta.1 — 2026-07-27
 
 ### Changed

tests/contracts/plugin-package.js

@@ -15,6 +15,7 @@ function runPluginPackageContract() {
   const packageJson = readJson(path.join(repoRoot, "package.json"));
   const manifest = readJson(path.join(repoRoot, "plugins", "cewp", ".codex-plugin", "plugin.json"));
   const marketplace = readJson(path.join(repoRoot, ".agents", "plugins", "marketplace.json"));
+  const readme = fs.readFileSync(path.join(repoRoot, "README.md"), "utf8");
   const compatibility = readJson(
     path.join(repoRoot, "tests", "fixtures", "compat", "v0.7.0-beta.0", "contracts.json"),
   );
@@ -79,6 +80,19 @@ function runPluginPackageContract() {
   assert(entry.source.path === "./plugins/cewp", "marketplace path stays repo-relative");
   assert(entry.policy.installation === "AVAILABLE", "plugin install remains opt-in");
   assert(entry.policy.authentication === "ON_INSTALL", "marketplace auth policy is explicit");
+  assert(
+    /npm.*CLI.*does not.*register.*Codex plugin/is.test(readme),
+    "README distinguishes npm CLI installation from Codex plugin registration",
+  );
+  assert(
+    /codex plugin marketplace add.*codex-engineering-workflow-pack/is.test(readme),
+    "README installs the marketplace from the globally installed npm package",
+  );
+  assert(readme.includes("codex plugin add cewp@cewp-local"), "README installs the CEWP plugin from its marketplace");
+  assert(
+    /Use CEWP to complete.*roadmap\.md/is.test(readme),
+    "README shows the roadmap-completion product intent",
+  );
 
   assert(compatibility.schemas.adapterResult === ADAPTER_RESULT_SCHEMA_VERSION, "v0.7 adapter result readable");
   assert(