@ps-neko/nekowork 0.1.0-alpha.0

package/docs/CODEMAPS/manifests.md

@@ -0,0 +1,14 @@
+# CODEMAP: manifests
+
+> Generated by `scripts/build-codemaps.js` from `manifests/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+manifests/
+|-- install-components.json
+|-- install-modules.json
+`-- install-profiles.json
+```
+

package/docs/CODEMAPS/rules.md

@@ -0,0 +1,22 @@
+# CODEMAP: rules
+
+> Generated by `scripts/build-codemaps.js` from `rules/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+rules/
+|-- common/
+|   |-- coding-style.md
+|   |-- security.md
+|   `-- testing.md
+|-- python/
+|   |-- coding-style.md
+|   `-- testing.md
+`-- typescript/
+    |-- coding-style.md
+    |-- security.md
+    `-- testing.md
+```
+

package/docs/CODEMAPS/schemas.md

@@ -0,0 +1,21 @@
+# CODEMAP: schemas
+
+> Generated by `scripts/build-codemaps.js` from `schemas/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+schemas/
+|-- agent-yaml.schema.json
+|-- agent.schema.json
+|-- handoff.schema.json
+|-- hooks.schema.json
+|-- install-components.schema.json
+|-- install-modules.schema.json
+|-- install-profiles.schema.json
+|-- install-state.schema.json
+|-- routing.schema.json
+`-- skill.schema.json
+```
+

package/docs/CODEMAPS/scripts.md

@@ -0,0 +1,158 @@
+# CODEMAP: scripts
+
+> Generated by `scripts/build-codemaps.js` from `scripts/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+scripts/
+|-- agents/
+|   |-- runners/
+|   |   |-- claude.js
+|   |   |-- codex.js
+|   |   |-- gemini.js
+|   |   `-- mock.js
+|   `-- dispatch.js
+|-- auth/
+|   |-- github-import-gh.js
+|   |-- github-login.js
+|   |-- github-logout.js
+|   `-- github-status.js
+|-- ci/
+|   |-- catalog.js
+|   |-- check-markers.js
+|   |-- security-hardening.js
+|   |-- validate-agents.js
+|   |-- validate-hooks.js
+|   |-- validate-manifests.js
+|   `-- validate-skills.js
+|-- core/
+|   |-- auth-guard.js
+|   |-- build-roots.js
+|   |-- cli-resolver.js
+|   |-- execution-workspace.js
+|   |-- git-mutation-guard.js
+|   |-- install-state.js
+|   |-- json-extractor.js
+|   `-- subprocess.js
+|-- daemon/
+|   `-- wait.js
+|-- lib/
+|   |-- acceptance-criteria.js
+|   |-- costs.js
+|   |-- instincts.js
+|   |-- keychain.js
+|   |-- profile-policy.js
+|   |-- profile-safety.js
+|   |-- risk-classifier.js
+|   |-- router.js
+|   |-- severity.js
+|   `-- token-vault.js
+|-- orchestrators/
+|   |-- apply.js
+|   |-- ask.js
+|   |-- gate.js
+|   |-- ralph.js
+|   |-- review.js
+|   |-- run.js
+|   |-- ship.js
+|   |-- team-lite.js
+|   |-- team.js
+|   |-- verify.js
+|   `-- work.js
+|-- portability/
+|   `-- simulate-port.js
+|-- verify/
+|   |-- claude-live.js
+|   |-- codex-live.js
+|   |-- gemini-live.js
+|   `-- runtime.js
+|-- build-claude.js
+|-- build-codemaps.js
+|-- build-codex.js
+|-- build-cursor.js
+|-- build-gemini.js
+|-- build-opencode.js
+|-- cli.js
+|-- demo-external-project.js
+|-- demo-quick-run.js
+|-- demo-review.js
+|-- doctor.js
+|-- install-apply.js
+|-- install-plan.js
+|-- repair.js
+`-- sync-claude-md.js
+```
+
+## JS Exports
+
+| File | Exports | Description |
+|---|---|---|
+| `agents/dispatch.js` | `dispatch`, `loadAgentFrontmatter` | dispatch. agent.md frontmatter provider runner . / JSON . . |
+| `agents/runners/claude.js` | `buildCliArgs`, `buildSystem`, `buildUserMessage`, `extractJson`, `normalizeCliUsage`, `parseCliJson`, `runClaude` | Claude runner. Default live mode uses the local Claude Code CLI subscription/OAuth session. Set HARNESS_CLAUDE_RUNNER=sdk to opt into Anthro |
+| `agents/runners/codex.js` | `buildPrompt`, `extractJson`, `normalizeHandoff`, `runCodex` | Codex runner: OpenAI Codex CLI subprocess . : codex . throw. (codex 0.124.0+ ): codex exec --sandbox read-only [--profile <name>] < prompt s |
+| `agents/runners/gemini.js` | `buildCliArgs`, `buildPrompt`, `parseGeminiOutput`, `runGemini` | Gemini runner: calls the local Gemini CLI subprocess. Default auth is delegated to the user's local gemini/gcloud session. |
+| `agents/runners/mock.js` | `runMock` | Mock runner: LLM . API / CLI dry-run . : - planner: AC 3 PRD - executor: - code-reviewer: round 1 high 1 (fix loop ), round 2 approve - code |
+| `auth/github-import-gh.js` | _(none)_ | Import the already-authenticated GitHub CLI OAuth token into the HARNESS vault. This is an explicit local-session bridge, not a static API-k |
+| `auth/github-login.js` | _(none)_ | GitHub OAuth Device Flow. : HARNESS_GITHUB_CLIENT_ID ( OAuth App client_id). docs/AUTH-MIGRATION.md 5.3. |
+| `auth/github-logout.js` | _(none)_ | GitHub OAuth . vault . : device flow client secret GitHub revoke API . GitHub https://github.com/settings/applications . |
+| `auth/github-status.js` | _(none)_ | GitHub OAuth . vault GitHub API . |
+| `build-claude.js` | _(none)_ | (agents/, skills/, commands/, hooks/) .claude/ . Claude Code + .claude-plugin/plugin.json. |
+| `build-codemaps.js` | _(none)_ | Generate docs/CODEMAPS/<area>.md from repository directories. The maps include a shallow directory tree plus exported JS symbols. They inten |
+| `build-codex.js` | _(none)_ | .codex/ . Codex CLI : config.toml + agents/*.toml. |
+| `build-cursor.js` | _(none)_ | .cursor/ . Cursor : .cursor/rules/*.mdc ( ), .cursorrules (legacy ). : hook PreToolUse/PostToolUse PascalCase before/after camelCase. |
+| `build-gemini.js` | _(none)_ | .gemini/ . Gemini : (output_format: summary). . GEMINI.md , description (progressive disclosure). |
+| `build-opencode.js` | _(none)_ | .opencode/ . opencode : JSON (config_format: json). agents/skills/hooks JSON . |
+| `ci/catalog.js` | _(none)_ | . agent.yaml agents/skills/commands , . |
+| `ci/check-markers.js` | _(none)_ | HARNESS:START / HARNESS:END . . |
+| `ci/security-hardening.js` | `checkSecurityHardening`, `isPinnedActionRef`, `isSemverMcpPin` | Security hardening CI gate: workflow permissions/timeouts/action pins, MCP pins, package spec hygiene, package-lock presence, and OIDC cloud |
+| `ci/validate-agents.js` | _(none)_ | agents/<name>.md frontmatter schemas/agent.schema.json . agent.yaml agents . |
+| `ci/validate-hooks.js` | _(none)_ | hooks/hooks.json schemas/hooks.schema.json . |
+| `ci/validate-manifests.js` | _(none)_ | agent.yaml + manifests/install-{profiles,modules,components}.json . 1) schema 2) |
+| `ci/validate-skills.js` | _(none)_ | skills/<name>/SKILL.md frontmatter schemas/skill.schema.json . agent.yaml skills . |
+| `cli.js` | _(none)_ | NEKOWORK/HARNESS CLI entrypoint. Public verbs: doctor, ask, plan, team, work, verify, gate, ship, apply, run, review, review-cycle, install, |
+| `core/auth-guard.js` | ` BLOCKED_ENV `, `assertDelegatedCliAuth` |  |
+| `core/build-roots.js` | `buildRoots` |  |
+| `core/cli-resolver.js` | `assertProviderCliTrust`, `isPathInside`, `resolveCli`, `resolveProviderCli` |  |
+| `core/execution-workspace.js` | `applyExecutionDiff`, `captureExecutionDiff`, `changedFiles`, `withExecutionWorkspace` |  |
+| `core/git-mutation-guard.js` | `readGitStatus`, `withGitMutationGuard` |  |
+| `core/install-state.js` | `ZERO_SHA`, `assertInstallState`, `buildInstallState`, `buildStateComponent`, `installStatePath`, `loadInstallState`, `sha256`, `sha256OfCatalog`, `sha256OfDir`, `writeInstallState` |  |
+| `core/json-extractor.js` | `extractJson`, `parseJsonObject` |  |
+| `core/subprocess.js` | `spawnAndCollect` |  |
+| `daemon/wait.js` | `buildResumePlan`, `parseActiveFile`, `processWakeups`, `tick` | Persistent wait daemon. It watches wakeup.json files created by the persistent-mode hook and resumes only sessions that declare a safe engin |
+| `demo-external-project.js` | _(none)_ | Create a tiny target project and run the repository-based NEKOWORK porting path. |
+| `demo-quick-run.js` | _(none)_ | Run the shortest NEKOWORK experience against a disposable target project. |
+| `demo-review.js` | _(none)_ | claude-led-codex-review (Week 1 ). LLM 7 / / round . ("git push ") ship . |
+| `doctor.js` | `buildDoctorReport`, `parseDoctorArgs`, `renderDoctorReport` |  |
+| `install-apply.js` | _(none)_ | HARNESS install --apply : plan harness (agent.yaml harnesses ) install-state . (idempotent). git checkout . |
+| `install-plan.js` | `plan` | HARNESS install --plan: dry-run manifest planner. |
+| `lib/acceptance-criteria.js` | `buildDefaultAcceptanceCriteria`, `ensureAcceptanceCriteria`, `normalizeAcceptanceCriteria`, `readAcceptanceCriteria` |  |
+| `lib/costs.js` | `list`, `record`, `summarize` | . USD ~/.harness/costs.jsonl append. CLI : harness costs --since=7d ( --since=1h, 30m, all). |
+| `lib/instincts.js` | `get`, `list`, `promote`, `prune`, `ready`, `record` | continuous-learning-v2 . review ( + + verdict ) ~/.harness/instincts/<id>.json . " " . |
+| `lib/keychain.js` | `get`, `isAvailable`, `list`, `remove`, `set` | scripts/lib/keychain.js OS keychain wrapper (@napi-rs/keyring sync API). macOS Keychain / Windows Credential Manager / Linux Secret Service. |
+| `lib/profile-policy.js` | `acceptanceCoverage`, `acceptanceCoverageWarnings`, `buildQualityChecklist`, `evidenceFieldWarnings`, `normalizeProfileName`, `profilePolicy` |  |
+| `lib/profile-safety.js` | `CORE_PROFILE_MODULES`, `validateProfileSafety` |  |
+| `lib/risk-classifier.js` | `SENSITIVE_PATTERNS`, `classifyRisk`, `gateReasonFromFindings`, `humanGatePolicy`, `isSensitiveWork` |  |
+| `lib/router.js` | `decide`, `trace` | . : stage, task, files, ecoMode, riskLevel : { agent, model, provider, rationale, alternatives } SKILL claude-led-codex-review Stage Routing |
+| `lib/severity.js` | `classifyCategory`, `classifySeverity`, `deriveVerdict`, `riskLevel`, `severityCounts` | Severity / category + blast radius . REVIEW.md . . |
+| `lib/token-vault.js` | `audit`, `backend`, `list`, `load`, `redact`, `remove`, `save` | scripts/lib/token-vault.js auth.token_store: os-keychain (default) encrypted-file. : HARNESS_TOKEN_STORE_KIND=os-keychain keychain only ( th |
+| `orchestrators/apply.js` | `applyCycle`, `latestStageHandoff`, `readApplyGitStatus`, `readDiffForHandoff`, `readPriorHandoffs` |  |
+| `orchestrators/ask.js` | `askGate`, `buildQuestionGate`, `classifyAskTask` |  |
+| `orchestrators/gate.js` | `approveGate`, `blockGate`, `gateCommand`, `gateStatus`, `markerTime`, `readMarker` |  |
+| `orchestrators/ralph.js` | `defaultPrd`, `normalizeEngine`, `ralphLoop` | Persistent Ralph loop. It repeats an execution engine until PRD acceptance criteria pass, a human gate stops the run, cost cap is hit, or ma |
+| `orchestrators/review.js` | ` SENSITIVE_PATTERNS `, `reviewCycle` | 7 review . claude-led-codex-review SKILL Stage Routing . : - 5/6 verdict block critical/high fix loop (executor , round++) - round = 3. crit |
+| `orchestrators/run.js` | `runCycle` |  |
+| `orchestrators/ship.js` | `finalVerificationVerdict`, `humanGateReason`, `latestStageHandoff`, `readPriorHandoffs`, `shipCycle` |  |
+| `orchestrators/team-lite.js` | `TEAM_LITE_STAGES`, `assertTaskGraph`, `createTasks`, `teamLiteCycle` |  |
+| `orchestrators/team.js` | `DEFAULT_WORKERS`, `WORKER_SPECS`, `parseWorkers`, `teamCycle` |  |
+| `orchestrators/verify.js` | `gateReasonFromFindings`, `latestStageHandoff`, `readDiffForHandoff`, `readPriorHandoffs`, `verifyCycle` |  |
+| `orchestrators/work.js` | `nextRound`, `readPriorHandoffs`, `workCycle` |  |
+| `portability/simulate-port.js` | _(none)_ | PoC . PORTING.md 30 dry-run . : --target < > ( ) --profile <name> ( : research) positional target: node scripts/portability/simulate-port.js |
+| `repair.js` | _(none)_ | HARNESS repair : install-state.json / sha256 . install-apply . - state . - . - sha256 ( ) . - --check . exit 1. |
+| `sync-claude-md.js` | _(none)_ | CLAUDE.md / .claude/CLAUDE.md HARNESS:START~HARNESS:END agent.yaml + package.json + manifests . ( ) . (idempotent). "## " . |
+| `verify/claude-live.js` | _(none)_ | Claude Code CLI live smoke. Uses the local Claude subscription/OAuth session by default, not ANTHROPIC_API_KEY. |
+| `verify/codex-live.js` | _(none)_ | codex runner live (P2-c). : codex CLI ( 0.124) + ChatGPT . OPENAI_API_KEY , opt-in HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1 . : 1 ~15K (ChatGPT ).  |
+| `verify/gemini-live.js` | _(none)_ | Gemini CLI live smoke. Uses the local Gemini/gcloud session by default, not GEMINI_API_KEY. |
+| `verify/runtime.js` | _(none)_ | Rust runtime verification smoke: cargo build/test/clippy plus CLI IPC checks. |
+

package/docs/CODEMAPS/skills.md

@@ -0,0 +1,29 @@
+# CODEMAP: skills
+
+> Generated by `scripts/build-codemaps.js` from `skills/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+skills/
+|-- claude-led-codex-review/
+|   `-- SKILL.md
+|-- plan-eng-review/
+|   `-- SKILL.md
+|-- porting/
+|   `-- SKILL.md
+|-- ralph/
+|   `-- SKILL.md
+|-- release-readiness/
+|   `-- SKILL.md
+|-- review/
+|   `-- SKILL.md
+|-- security-hardening/
+|   `-- SKILL.md
+|-- ship/
+|   `-- SKILL.md
+`-- tdd-workflow/
+    `-- SKILL.md
+```
+

package/docs/CODEMAPS/tests.md

@@ -0,0 +1,98 @@
+# CODEMAP: tests
+
+> Generated by `scripts/build-codemaps.js` from `tests/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+tests/
+|-- e2e/
+|   |-- case-studies-doc.test.js
+|   |-- external-demo.test.js
+|   |-- github-actions-hardening-example.test.js
+|   |-- quality-lifecycle-example.test.js
+|   |-- quick-demo.test.js
+|   |-- review-cycle.test.js
+|   `-- trading-dashboard-example.test.js
+|-- integration/
+|   `-- build-pipeline.test.js
+|-- optional/
+|   `-- keychain-smoke.test.js
+`-- unit/
+    |-- acceptance-criteria.test.js
+    |-- apply.test.js
+    |-- ask.test.js
+    |-- auth-guard.test.js
+    |-- cli-options.test.js
+    |-- codex-isolation.test.js
+    |-- core-utils.test.js
+    |-- costs.test.js
+    |-- doctor.test.js
+    |-- execution-workspace.test.js
+    |-- gate.test.js
+    |-- git-mutation-guard.test.js
+    |-- instincts.test.js
+    |-- orchestrator.test.js
+    |-- portability.test.js
+    |-- profile-safety.test.js
+    |-- ralph.test.js
+    |-- risk-classifier.test.js
+    |-- router.test.js
+    |-- run.test.js
+    |-- runners-extract.test.js
+    |-- security-hardening.test.js
+    |-- severity.test.js
+    |-- ship.test.js
+    |-- team-lite.test.js
+    |-- team.test.js
+    |-- token-vault.test.js
+    |-- verify.test.js
+    |-- wait.test.js
+    `-- work.test.js
+```
+
+## JS Exports
+
+| File | Exports | Description |
+|---|---|---|
+| `e2e/case-studies-doc.test.js` | _(none)_ |  |
+| `e2e/external-demo.test.js` | _(none)_ |  |
+| `e2e/github-actions-hardening-example.test.js` | _(none)_ |  |
+| `e2e/quality-lifecycle-example.test.js` | _(none)_ |  |
+| `e2e/quick-demo.test.js` | _(none)_ |  |
+| `e2e/review-cycle.test.js` | _(none)_ | E2E smoke tests for the deterministic mock review flow. |
+| `e2e/trading-dashboard-example.test.js` | _(none)_ |  |
+| `integration/build-pipeline.test.js` | _(none)_ | : install plan apply 5 state repair . . .harness/install-state.json . |
+| `optional/keychain-smoke.test.js` | _(none)_ | OS keychain . npm test (tests/optional/ ). : HARNESS_KEYCHAIN_SMOKE=1 npm run test:keychain : HARNESS_KEYCHAIN_SMOKE=1 node --test tests/opt |
+| `unit/acceptance-criteria.test.js` | _(none)_ |  |
+| `unit/apply.test.js` | _(none)_ |  |
+| `unit/ask.test.js` | _(none)_ |  |
+| `unit/auth-guard.test.js` | _(none)_ |  |
+| `unit/cli-options.test.js` | _(none)_ |  |
+| `unit/codex-isolation.test.js` | _(none)_ | Codex Claude . 2 "Claude , Codex " . codex buildPrompt Claude /agent body prompt leak . |
+| `unit/core-utils.test.js` | _(none)_ |  |
+| `unit/costs.test.js` | _(none)_ |  |
+| `unit/doctor.test.js` | _(none)_ |  |
+| `unit/execution-workspace.test.js` | _(none)_ |  |
+| `unit/gate.test.js` | _(none)_ |  |
+| `unit/git-mutation-guard.test.js` | _(none)_ |  |
+| `unit/instincts.test.js` | _(none)_ |  |
+| `unit/orchestrator.test.js` | _(none)_ | review . mock provider . node:test based orchestrator checks. |
+| `unit/portability.test.js` | _(none)_ |  |
+| `unit/profile-safety.test.js` | _(none)_ |  |
+| `unit/ralph.test.js` | _(none)_ |  |
+| `unit/risk-classifier.test.js` | _(none)_ |  |
+| `unit/router.test.js` | _(none)_ |  |
+| `unit/run.test.js` | _(none)_ |  |
+| `unit/runners-extract.test.js` | _(none)_ | live runner JSON / prompt . Claude/Codex CLI ( ). |
+| `unit/security-hardening.test.js` | _(none)_ |  |
+| `unit/severity.test.js` | _(none)_ |  |
+| `unit/ship.test.js` | _(none)_ |  |
+| `unit/team-lite.test.js` | _(none)_ |  |
+| `unit/team.test.js` | _(none)_ |  |
+| `unit/token-vault.test.js` | _(none)_ |  |
+| `unit/verify.test.js` | _(none)_ |  |
+| `unit/wait.test.js` | _(none)_ |  |
+| `unit/work.test.js` | _(none)_ |  |
+

package/docs/CORE-INVARIANTS.md

@@ -0,0 +1,38 @@
+# Core Invariants
+
+NEKOWORK is a verification runtime. These invariants are not feature toggles.
+
+```text
+Claude work -> Codex verification -> Human Gate
+```
+
+## Runtime Rules
+
+1. Multi-worker phases are read-only by default.
+2. Only one executor may mutate project files in a work cycle.
+3. Codex review is the default independent verification path.
+4. Secure or sensitive changes require Codex challenge or Human Gate.
+5. Human Gate cannot be bypassed by skill, hook, profile, module, or CLI expansion.
+6. Profiles may add capabilities, but they cannot weaken core safety gates.
+7. Local delegated CLI auth is the default live-provider path.
+8. Long-lived provider API keys are not required by the default path.
+9. Handoffs must be inspectable artifacts.
+10. Shipping requires evidence from work, verification, and gate state.
+
+## Enforcement Surfaces
+
+- `team` and `team-lite` run as read-only handoff surfaces.
+- `work` runs one executor and records acceptance criteria before implementation.
+- `verify` requires prior work, runs Codex review, and triggers challenge/gates for sensitive work.
+- `gate` records explicit human approve/block decisions.
+- `ship` refuses unresolved gates and writes readiness markers only after verification.
+- `apply` is the explicit mutation command for verified live-work diffs.
+- Manifest validation rejects profiles that try to weaken core safety policy.
+
+## Compatibility
+
+`review` remains the legacy full cycle for the `0.0.3` line. `review-cycle` is the explicit compatibility alias. New automation should prefer:
+
+```text
+ask -> plan -> team -> work -> verify -> gate -> ship -> apply
+```

package/docs/DEMO.md

@@ -0,0 +1,110 @@
+# Demo
+
+This demo uses mock providers. It does not call Claude, Codex, Gemini, or paid APIs.
+
+## Quick Run Demo
+
+```bash
+npm run demo:quick -- --cleanup
+```
+
+This is the shortest demo path. It creates a disposable target project, runs `doctor --quick`, runs `run = work -> verify -> ship`, checks `gate status`, and removes the target when `--cleanup` is set.
+
+Expected shape:
+
+```text
+NEKOWORK quick run demo
+doctor ... OK
+run workflow ... OK
+gate status ... OK
+Demo completed: verdict=approve_with_fixes, ship_ready=false, applied=false
+```
+
+## External Project Demo
+
+```bash
+npm run demo:external
+```
+
+This creates a tiny disposable target project, applies the `developer` profile, runs `doctor --quick`, and writes a planning session into the target project's `.harness/` directory. See [EXAMPLE-PROJECT.md](EXAMPLE-PROJECT.md) for details.
+
+## Command
+
+```bash
+node scripts/cli.js review "check the project setup" --no-ship --session demo-readme
+```
+
+## Example Output
+
+```text
+[review:demo-readme] task: check the project setup
+[review:demo-readme] mode: mock --no-ship
+[review:demo-readme] 1 ideate
+[review:demo-readme] 2 plan
+[review:demo-readme] 3 implement
+[review:demo-readme] 4 self-review (round 1)
+[review:demo-readme] fix-loop: executor round 2
+[review:demo-readme] 4 self-review (round 2)
+[review:demo-readme] 5 codex-review
+[review:demo-readme] 6 codex-challenge skipped (sensitive not detected, --secure not set)
+[review:demo-readme] 7 ship skipped (--no-ship)
+```
+
+## Generated Files
+
+```text
+.harness/state/sessions/demo-readme/
+  prd.json
+  progress.txt
+  handoffs/
+    01-ideate.md
+    02-plan.md
+    03-implement.md
+    04-self-review.md
+    04-self-review-r2.md
+    05-codex-review.md
+```
+
+Each handoff follows the same five-field shape:
+
+- Decided
+- Rejected
+- Risks
+- Files
+- Remaining
+
+## Security-Sensitive Demo
+
+Use `--secure` to force the Codex challenge stage:
+
+```bash
+node scripts/cli.js review "change auth token validation" --secure --no-ship --session demo-secure
+```
+
+Expected behavior:
+
+- `codex-review` runs
+- `codex-challenge` runs
+- `ship` is skipped because `--no-ship` is set
+
+## Doctor Demo
+
+```bash
+node scripts/cli.js doctor --quick
+```
+
+Example shape:
+
+```text
+NEKOWORK doctor
+harness root : C:\path\to\harness
+project root : C:\path\to\harness
+
+STATUS  CHECK                   MESSAGE
+PASS    node                    Node 24.x
+PASS    package metadata        @ps-neko/nekowork@0.1.0-alpha.0; public alpha publish candidate
+PASS    git worktree            project root is inside a git worktree
+WARN    gemini cli              installed, auth status is not checked non-interactively
+
+summary: WARN
+```

package/docs/EXAMPLE-PROJECT.md

@@ -0,0 +1,92 @@
+# External Project Example
+
+This walkthrough shows the current repository-based NEKOWORK integration path against a tiny external project.
+
+The demo is intentionally mock-first. It does not call Claude, Codex, Gemini, or paid APIs.
+
+## One-Command Demo
+
+From the NEKOWORK checkout:
+
+```bash
+npm run demo:external
+```
+
+Expected shape:
+
+```text
+NEKOWORK external project demo
+target : <temp-dir>
+profile: developer
+
+git    : initialized
+preflight ... OK
+install apply ... OK
+doctor ... OK
+plan smoke ... OK
+
+Demo completed.
+Inspect target: <temp-dir>
+```
+
+To remove the generated target after a successful run:
+
+```bash
+npm run demo:external -- --cleanup
+```
+
+To run against a specific folder:
+
+```bash
+npm run demo:external -- --target C:/path/to/demo-target --force
+```
+
+`--force` allows the demo to write into a non-empty target. Use an empty or disposable folder when trying the path for the first time.
+
+## Manual Equivalent
+
+Create a small target project:
+
+```bash
+mkdir demo-target
+cd demo-target
+git init
+mkdir src
+echo "console.log('hello NEKOWORK')" > src/index.js
+```
+
+Then run NEKOWORK from its checkout:
+
+```bash
+cd C:/Users/Mun/harness
+node scripts/portability/simulate-port.js C:/path/to/demo-target --profile developer --verbose
+node scripts/install-apply.js --profile developer --project-root C:/path/to/demo-target
+node scripts/cli.js doctor --project-root C:/path/to/demo-target --quick
+node scripts/cli.js plan "external project smoke" --project-root C:/path/to/demo-target --session external-smoke
+```
+
+Expected target outputs:
+
+```text
+demo-target/
+  .harness/install-state.json
+  .harness/state/sessions/external-smoke/handoffs/02-plan.json
+  .claude/CLAUDE.md
+  .codex/config.toml
+  .cursor/hooks.json
+  .gemini/GEMINI.md
+  .opencode/config.json
+```
+
+## What This Proves
+
+- NEKOWORK can stay outside the target project as a tool root.
+- Generated harness surfaces are written into the target project.
+- Session state is written under the target project's `.harness/`.
+- The default planning flow works without live provider calls.
+
+## What This Does Not Prove
+
+- Public npm installation. The package metadata is ready, but publish execution still requires npm owner auth.
+- Live provider execution. Run live provider smoke checks separately after local CLI login.
+- A production rollout. Pin a release tag or submodule commit before using the tool in a shared workflow.