@ps-neko/nekowork 0.1.0-alpha.1 → 0.1.0-alpha.3

package/CLAUDE.md

@@ -8,7 +8,7 @@
 
 ## 자동 갱신 영역
 
-<!-- HARNESS:START version=0.1.0-alpha.1 -->
+<!-- HARNESS:START version=0.1.0-alpha.3 -->
 <!-- 이 영역은 scripts/sync-claude-md.js 가 자동 갱신한다. 직접 편집 금지. -->
 
 ## 카탈로그 요약

package/README.md

@@ -1,14 +1,19 @@
 # NEKOWORK
 
-Local-first AI development harness for Claude Code, Codex CLI, and Gemini CLI.
+Local-first AI development quality runtime for Claude Code, Codex CLI, and Gemini CLI.
 
 [![harness-validate](https://github.com/Ps-Neko/NEKOWORK/actions/workflows/harness-validate.yml/badge.svg)](https://github.com/Ps-Neko/NEKOWORK/actions/workflows/harness-validate.yml)
 
-NEKOWORK is the product. HARNESS is the local runtime it packages: one source catalog, `agent.yaml`, projected into Claude Code, Codex CLI, Cursor, Gemini CLI, and OpenCode surfaces.
+NEKOWORK prevents AI coding agents from shipping unverified changes.
+
+It runs:
 
-Claude writes or plans, Codex challenges the result in a separate context, and human gates stop critical or repeated-risk changes.
+1. Work
+2. Independent verification
+3. Human approval
+4. Explicit apply
 
-NEKOWORK is also a quality runtime: it combines disciplined development workflow, product-aware planning, read-only multi-agent review, independent Codex verification, Human Gate approval, and explicit apply control.
+No auto-commit. No auto-push. No surprise deploy.
 
 Product principle:
 
@@ -16,14 +21,48 @@ Product principle:
 NEKOWORK = Claude work -> Codex verification -> Human Gate
 ```
 
-NEKOWORK is not meant to become a large agent pack. Skills, hooks, profiles, and team modes are added only when they preserve the verification loop.
+NEKOWORK is the product. HARNESS is the local runtime it packages: one source catalog, `agent.yaml`, projected into Claude Code, Codex CLI, Cursor, Gemini CLI, and OpenCode surfaces.
 
-NEKOWORK intentionally keeps the catalog selective. Every agent, skill, hook, profile, module, and pack must preserve the verification loop.
+NEKOWORK is intentionally not a 100-agent pack. Every agent, skill, hook, profile, module, and pack must:
 
-**Public alpha evidence:** 7 packs · 9 profiles · 36 components · 5 harness targets · 6 case-study flows · 245 tests · 0 moderate+ npm audit issues
+1. improve verification,
+2. preserve one-executor writes,
+3. produce auditable evidence,
+4. respect Human Gate.
+
+**Public alpha evidence:** 7 packs / 9 profiles / 36 components / 5 harness targets / 7 case-study flows / 251 tests / 0 moderate+ npm audit issues / fresh `npx @alpha` smoke
 
 NEKOWORK does not automatically commit, push, publish, deploy, or apply diffs. `apply` is explicit and requires verified ship-ready evidence.
 
+**One-minute demo:** [terminal transcript](docs/DEMO.md#one-minute-terminal-transcript) / [full report example](docs/DEMO-REPORT.md) / [alpha feedback](https://github.com/Ps-Neko/NEKOWORK/issues/new?template=alpha-feedback.yml) / [roadmap](docs/ROADMAP.md)
+
+![NEKOWORK one-minute terminal demo](docs/assets/demo-terminal.svg)
+
+## Start Here
+
+Use the current npm alpha for the published health smoke:
+
+```bash
+npx -y @ps-neko/nekowork@alpha check
+```
+
+Use a source checkout for the new simple command path:
+
+```bash
+node scripts/cli.js check
+node scripts/cli.js run "implement this safely" --session first-run
+node scripts/cli.js report --session first-run
+node scripts/cli.js gate status --session first-run
+```
+
+The simple path maps to the full evidence loop: `check = doctor --quick`, and `run = work -> verify -> ship`.
+
+To add generated harness surfaces to another local repository from a source checkout:
+
+```bash
+node /path/to/harness/scripts/cli.js init --profile developer --project-root /path/to/my-project
+```
+
 ## Example Report
 
 `report` is the main trust surface. It turns session evidence into a readable `REPORT.md`:
@@ -47,6 +86,26 @@ Evidence:
 
 See the full report contract and example artifact in [docs/DEMO-REPORT.md](docs/DEMO-REPORT.md), and the one-minute terminal transcript in [docs/DEMO.md](docs/DEMO.md).
 
+## Human Gate Example
+
+```text
+Risk: security-sensitive auth parser change
+Codex verdict: approve_with_fixes
+Ship ready: false
+
+Required before apply:
+[ ] Add parser boundary test
+[ ] Remove long-lived API key env fallback
+[ ] Re-run verify --strict-quality
+
+Decision:
+- approve
+- block
+- request fixes
+```
+
+Human Gate is the point where NEKOWORK stops being an autopilot and becomes an approval system.
+
 ## Compared With Agent Packs
 
 | Tool pattern | Optimizes for | NEKOWORK optimizes for |
@@ -56,11 +115,21 @@ See the full report contract and example artifact in [docs/DEMO-REPORT.md](docs/
 | Autopilot | Fast autonomous execution | Report, gate, explicit apply |
 | Discipline workflows | Better development habits | Evidence-backed ship decision |
 
+## When To Choose What
+
+| Use case | Prefer |
+|---|---|
+| Add TDD and discipline habits to Claude Code | Superpowers |
+| Get the broadest Claude Code skill/command environment | Everything Claude Code |
+| Simulate startup team roles from planning to QA | GStack |
+| Run autonomous multi-agent execution | OMC |
+| Verify AI changes, require human approval, then apply explicitly | NEKOWORK |
+
 ## Three Paths
 
 Most users should start with the Beginner path. The other paths are for explicit phase control or legacy compatibility.
 
-1. Beginner: `doctor -> ask -> run -> report -> gate`
+1. Beginner: `check -> run -> report -> gate`
 2. Advanced: `ask -> plan -> team -> work -> verify -> gate -> ship -> report -> apply`
 3. Legacy: `review` / `review-cycle`
 
@@ -70,19 +139,20 @@ NEKOWORK is for teams that want AI-assisted development without making the agent
 
 ## Status
 
-- Current repository version: `0.1.0-alpha.1` alpha candidate
+- Current repository version: `0.1.0-alpha.3`
 - Current package name: `@ps-neko/nekowork`
-- npm publishing: `@ps-neko/nekowork@alpha` is currently `0.1.0-alpha.0`; `0.1.0-alpha.1` publish is prepared and awaiting owner OTP/web auth
+- Current npm alpha: `@ps-neko/nekowork@0.1.0-alpha.3`
 - Supported install path today: npm alpha, clone, submodule, or local repository integration
-- Dist-tag note: `alpha` is published; `latest` also points at the first alpha because it is the only published version
+- Dist-tag note: use `@alpha` until a stable release; `latest` still points at the first alpha line
 - Default mode: mock providers, no API keys, no provider CLI calls
 
 Current local verification:
 
 - `npm run lint`: pass
-- `npm test`: 245 tests pass
+- `npm test`: 251 tests pass
 - `npm audit --audit-level=moderate`: 0 vulnerabilities
 - `npm pack --dry-run --json`: pass
+- `npx -y @ps-neko/nekowork@alpha check`: pass with warnings only
 
 ## Case-study Evidence
 
@@ -94,6 +164,7 @@ Current local verification:
 | npm package boundary | package/release risk | pack/audit evidence |
 | Auth parser boundary | auth/security risk | parser boundary evidence |
 | Python protocol parser | protocol correctness risk | test-backed verification |
+| Dotenv configuration boundary | config/security risk | no-secret parser evidence |
 
 ## Official Packs
 
@@ -118,7 +189,7 @@ Requirements:
 Fastest no-API demo:
 
 ```bash
-npx -y @ps-neko/nekowork@alpha doctor --quick
+npx -y @ps-neko/nekowork@alpha check
 ```
 
 Repository demo:
@@ -138,8 +209,7 @@ Recommended path for most users:
 git clone https://github.com/Ps-Neko/NEKOWORK.git harness
 cd harness
 npm ci
-node scripts/cli.js doctor --quick
-node scripts/cli.js ask "clarify a risky or ambiguous request" --session first-ask
+node scripts/cli.js check
 node scripts/cli.js run "implement, verify, and prepare ship readiness" --session first-run
 node scripts/cli.js report --session first-run
 node scripts/cli.js gate status --session first-run
@@ -147,6 +217,12 @@ node scripts/cli.js gate status --session first-run
 
 `run` executes `work -> verify -> ship`. `report` turns the session evidence into a readable `REPORT.md`. It does not apply by default. `apply` is always explicit and requires a verified `SHIP_READY` live-work diff.
 
+To initialize another local repository from this checkout:
+
+```bash
+node /path/to/harness/scripts/cli.js init --profile developer --project-root /path/to/my-project
+```
+
 Advanced path:
 
 ```text
@@ -163,13 +239,15 @@ The default review path uses mock providers, so it does not need API keys or pro
 
 For the fuller first-run guide, see [docs/QUICKSTART.md](docs/QUICKSTART.md).
 
+For the trust and recovery model, see [Safety Guarantees](docs/SAFETY-GUARANTEES.md), [Failure Modes](docs/FAILURE-MODES.md), [Trust Model](docs/TRUST-MODEL.md), and [Why Not Autopilot](docs/WHY-NOT-AUTOPILOT.md).
+
 To see the repository-based external project flow end to end:
 
 ```bash
 npm run demo:external
 ```
 
-To inspect small case-study targets, see [examples/trading-dashboard-mock](examples/trading-dashboard-mock), [examples/github-actions-hardening](examples/github-actions-hardening), [examples/quality-lifecycle-smoke](examples/quality-lifecycle-smoke), and [docs/case-studies](docs/case-studies). They demonstrate financial UI, CI workflow, quality lifecycle, npm package, auth parser, and Python protocol library flows passing local checks while still preserving Codex verification, Human Gate policy, and explicit apply control.
+To inspect small case-study targets, see [examples/trading-dashboard-mock](examples/trading-dashboard-mock), [examples/github-actions-hardening](examples/github-actions-hardening), [examples/quality-lifecycle-smoke](examples/quality-lifecycle-smoke), and [docs/case-studies](docs/case-studies). They demonstrate financial UI, CI workflow, quality lifecycle, npm package, auth parser, Python protocol library, and environment configuration flows while still preserving Codex verification, Human Gate policy, and explicit apply control.
 
 ## What You Get
 
@@ -333,7 +411,7 @@ npm run security:hardening
 npm pack --dry-run --json
 ```
 
-`npm pack --dry-run --json` currently produces a package named like `ps-neko-nekowork-0.1.0-alpha.1.tgz`. It does not publish.
+`npm pack --dry-run --json` currently produces a package named like `ps-neko-nekowork-0.1.0-alpha.3.tgz`. It does not publish.
 
 ## Documentation
 
@@ -341,6 +419,8 @@ npm pack --dry-run --json
 - [docs/WHY-NEKOWORK.md](docs/WHY-NEKOWORK.md) - comparison and product positioning
 - [docs/CATALOG-PACKS.md](docs/CATALOG-PACKS.md) - curated catalog, official packs, and case-study evidence
 - [docs/PUBLISH-ALPHA.md](docs/PUBLISH-ALPHA.md) - public npm alpha release plan
+- [docs/ROADMAP.md](docs/ROADMAP.md) - small alpha roadmap and non-goals
+- [docs/FEEDBACK-TRIAGE.md](docs/FEEDBACK-TRIAGE.md) - alpha feedback classification and response guide
 - [docs/INTERNAL-PROVIDER.md](docs/INTERNAL-PROVIDER.md) - private command adapter protocol
 - [docs/DEMO.md](docs/DEMO.md) - sample command output and generated files
 - [docs/DEMO-REPORT.md](docs/DEMO-REPORT.md) - readable session report UX

package/agent.yaml

@@ -1,7 +1,7 @@
 spec_version: gitagent/0.1.0
 name: nekowork
 runtime_name: harness
-version: 0.1.0-alpha.1
+version: 0.1.0-alpha.2
 description: "NEKOWORK HARNESS - Local-first multi-AI development verification runtime"
 license: MIT
 homepage: https://github.com/Ps-Neko/NEKOWORK

package/docs/ARCHITECTURE.md

@@ -202,8 +202,8 @@ Builders project the catalog into tool-specific files:
 
 ## Release State
 
-The current release line is `0.1.0-alpha.1`:
+The current release line is `0.1.0-alpha.2`:
 
 - Repository and GitHub tarball release are available.
 - Public npm alpha is published as `@ps-neko/nekowork@alpha`.
-- Clone, submodule, and local checkout integration remain the supported install paths until the package is published.
+- Clone, submodule, and local checkout integration remain supported for repository-pinned workflows.

package/docs/AUDIT.md

@@ -1,26 +1,27 @@
 # Audit
 
-Status date: 2026-05-07
+Status date: 2026-05-08
 
-This audit summarizes the current NEKOWORK state after preparing the `0.1.0-alpha.1` alpha candidate. It replaces the older week-by-week scratch audit, which contained stale planning notes and encoding damage.
+This audit summarizes the current NEKOWORK state after publishing the `0.1.0-alpha.3` public alpha. It replaces the older week-by-week scratch audit, which contained stale planning notes and encoding damage.
 
 ## Current Status
 
 | Area | Status | Notes |
 |---|---|---|
-| Package metadata | OK | `@ps-neko/nekowork@0.1.0-alpha.1`, `agent.yaml` uses `name: nekowork`, `runtime_name: harness` |
-| npm publish | WARN | `@ps-neko/nekowork@0.1.0-alpha.0` is published; `0.1.0-alpha.1` publish is prepared but requires owner OTP/web auth |
+| Package metadata | OK | `@ps-neko/nekowork@0.1.0-alpha.3`, `agent.yaml` uses `name: nekowork`, `runtime_name: harness` |
+| npm publish | OK | `@ps-neko/nekowork@alpha` points at `0.1.0-alpha.3` |
 | Source install | OK | Clone, local checkout, and submodule workflows are documented |
-| Public npm alpha | OK | `docs/PUBLISH-ALPHA.md` records the first alpha publish and the pending `0.1.0-alpha.1` publish attempt |
-| CLI doctor | OK | `doctor`, `doctor --quick`, and `doctor --gemini-smoke` are available |
+| Public npm alpha | OK | `docs/PUBLISH-ALPHA.md` records the first alpha publish and the `0.1.0-alpha.3` alpha update |
+| CLI doctor/check | OK | `check`, `doctor`, `doctor --quick`, and `doctor --gemini-smoke` are available |
 | Provider auth | OK | Local delegated CLI auth is the default path |
 | Internal provider adapter | OK | `HARNESS_PROVIDER_OVERRIDE=internal` can call an explicit JSON command adapter without weakening gates |
 | Catalog | OK | 7 official packs, 11 agents, 10 skills, 5 hooks, 7 modules, 36 components, 9 profiles |
 | Multi-harness output | OK | Claude, Codex, Cursor, Gemini, and OpenCode builders are present |
 | Quick demo | OK | `npm run demo:quick` verifies the shortest no-API `doctor -> run -> report -> gate status` path |
+| Fresh npm alpha smoke | OK | CI runs `npx -y @ps-neko/nekowork@alpha doctor --quick --json` from a disposable directory |
 | Report UX | OK | `report` writes inspect-only `REPORT.md` and `report-summary.json` from session evidence |
 | External demo | OK | `npm run demo:external` verifies a disposable target project flow |
-| Third-party case studies | OK | `docs/case-studies/` records real public repository runs for npm package, auth boundary, and Python protocol targets |
+| Third-party case studies | OK | `docs/case-studies/` records real public repository runs for npm package, auth boundary, Python protocol, and environment configuration targets |
 | Decomposed workflow | OK | `ask`, `team`, `work`, `verify`, `gate`, `ship`, `report`, `apply`, and `run` are available |
 | Risk policy | OK | Shared classifier drives ask, routing traces, verify challenge/gates, and ship gate rechecks |
 | Acceptance criteria | OK | `work` ensures every session has `acceptance-criteria.json` |
@@ -29,7 +30,7 @@ This audit summarizes the current NEKOWORK state after preparing the `0.1.0-alph
 | Persistent wakeup | OK | `wait` resumes supported active sessions and blocks on `HUMAN_GATE` |
 | Generated docs | OK | CODEMAP output is stable ASCII and reproducible |
 | Tests | OK | Unit, integration, and e2e suites pass locally and in CI |
-| Release | WARN | `v0.1.0-alpha.0` prerelease exists; `v0.1.0-alpha.1` should be tagged after npm publish succeeds |
+| Release | OK | `v0.1.0-alpha.3` is tagged and published as a GitHub prerelease |
 
 ## Verification Gates
 
@@ -54,7 +55,7 @@ Current local result for this working tree:
 - `npm run test:unit`: covered by full `npm test`
 - `npm run validate:all`: pass
 - `npm run lint`: pass
-- `npm test`: 245 tests pass
+- `npm test`: 251 tests pass
 - quick run demo: pass through `npm run demo:quick -- --cleanup`
 - external project e2e smoke: pass through `npm test`
 - `node scripts/sync-claude-md.js --check`: pass
@@ -62,8 +63,9 @@ Current local result for this working tree:
 - `npm audit --audit-level=moderate`: 0 vulnerabilities
 - `npm pack --dry-run --json`: pass
 - `npm publish --dry-run --access public --tag alpha`: pass
-- `npm publish --access public --tag alpha`: `0.1.0-alpha.1` blocked by npm `EOTP` pending owner OTP/web auth
-- `npx -y @ps-neko/nekowork@alpha doctor --quick`: previously passed for `0.1.0-alpha.0` with WARN summary from Gemini auth not checked
+- `npm publish --access public --tag alpha`: `0.1.0-alpha.3` published
+- `npm view @ps-neko/nekowork dist-tags version versions --json`: `alpha` points at `0.1.0-alpha.3`; `latest` remains `0.1.0-alpha.0`
+- `npx -y @ps-neko/nekowork@alpha check`: passed for `0.1.0-alpha.3` with WARN summary from non-git project root and Gemini auth not checked
 
 ## Completed Work
 
@@ -90,16 +92,15 @@ Current local result for this working tree:
 - `report` gives public alpha users a readable inspect-only session artifact without applying or mutating project files.
 - Official packs expose curated install shapes without creating a second safety model.
 - Checked-in example fixtures now cover financial UI, CI hardening, and quality lifecycle evidence flows.
-- Third-party case studies record NEKOWORK runs against `sindresorhus/is-plain-obj`, `jshttp/basic-auth`, and `python-hyper/h11`.
-- Public npm alpha `0.1.0-alpha.0` is published and smoke-tested through `npx`; `0.1.0-alpha.1` is prepared for owner-authenticated publish.
+- Third-party case studies record NEKOWORK runs against `sindresorhus/is-plain-obj`, `jshttp/basic-auth`, `python-hyper/h11`, and `motdotla/dotenv`.
+- Public npm alpha `0.1.0-alpha.3` is published under the `alpha` dist-tag.
 
 ## Remaining Optional Work
 
 | Item | Priority | Reason |
 |---|---|---|
-| Publish `0.1.0-alpha.1` | High | Package is prepared and dry-run passes, but npm requires owner OTP/web auth |
-| Stable `latest` promotion | Medium | `alpha` is correct; npm also points `latest` at the only published version and rejected removal with `E400`, so move it to a stable version later |
-| More third-party case studies | Low | Three public repo case studies exist; more frameworks can still improve adoption evidence later |
+| Stable `latest` promotion | Medium | `alpha` is correct; npm keeps `latest` on the first alpha line for now, so move it to a stable version later |
+| More third-party case studies | Low | Four public repo case studies exist; more frameworks can still improve adoption evidence later |
 | More skill catalog expansion | Low | Catalog expansion should stay selective to preserve progressive disclosure |
 
 ## Explicit Non-Goals
@@ -116,7 +117,6 @@ Current external readiness, excluding broader adoption evidence: **9.1 / 10**.
 
 Main deductions:
 
-- `latest` currently points at the alpha because it is the only published version; docs still recommend `@alpha` until a stable release exists.
-- `0.1.0-alpha.1` publish requires owner OTP/web auth.
-- Three independent real-world external project case studies exist so far.
+- `latest` currently remains on the first alpha; docs still recommend `@alpha` until a stable release exists.
+- Four independent real-world external project case studies exist so far.
 - Advanced surfaces exist but are intentionally secondary to the public decomposed workflow and install flow.

package/docs/CATALOG-PACKS.md

@@ -19,8 +19,8 @@ Packs are public install aliases over validated profiles. They make the catalog
 10 skills
 5 hooks
 5 harness targets
-6 case-study flows
-245 tests
+7 case-study flows
+251 tests
 ```
 
 Harness targets:
@@ -38,6 +38,7 @@ quality lifecycle smoke
 npm package boundary
 auth parser boundary
 Python protocol parser boundary
+environment configuration boundary
 ```
 
 ## Official Packs

package/docs/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 ## [Unreleased]
 
+### Added
+- No entries yet.
+
+## [0.1.0-alpha.3] - 2026-05-08
+
+### Added
+- Add a `motdotla/dotenv` third-party case study for environment configuration and secret-loading boundary evidence.
+- Add alpha feedback triage guidance and issue-template classification fields.
+- Add beginner `check` and `init` CLI aliases for first-run health checks and install apply.
+- Add Safety Guarantees, Failure Modes, Trust Model, and Why Not Autopilot docs.
+- Add trust-doc and CLI alias tests, bringing the suite to 251 tests.
+
+### Changed
+- Rewrite the README first screen around unverified-change prevention, Human Gate, explicit apply, and no-surprise safety.
+- Add a direct competitor choice table and clearer selective-catalog framing.
+
+## [0.1.0-alpha.2] - 2026-05-08
+
+### Added
+- Add GitHub issue templates for alpha feedback and reproducible bug reports.
+- Add CI coverage for a fresh `npx @ps-neko/nekowork@alpha doctor --quick` smoke against the published alpha package.
+- Add an alpha.2 roadmap focused on release smoke evidence, demo assets, and external feedback.
+- Add a static terminal SVG for the one-minute README demo.
+
+### Changed
+- Make the published alpha smoke workflow compare against the registry's current `@alpha` version instead of a hard-coded alpha string.
+
+## [0.1.0-alpha.1] - 2026-05-07
+
 ### Added
 - Add `report` to write inspect-only `REPORT.md` and `report-summary.json` from session evidence.
 - Add official catalog packs as install aliases over safety-checked profiles.
@@ -15,7 +44,7 @@
 - Add a third-party `python-hyper/h11` Python protocol case study.
 - Add an opt-in internal provider command adapter.
 - Add the focused `acceptance-coverage` quality evidence skill.
-- Prepare public alpha `@ps-neko/nekowork@0.1.0-alpha.1` with the updated adapter, case study, and catalog evidence; actual npm publish requires owner OTP/web auth.
+- Publish public alpha `@ps-neko/nekowork@0.1.0-alpha.1` with the updated adapter, case study, catalog evidence, report sample, and demo transcript.
 - Add `npm run demo:external` to create a disposable target project and verify repository-based porting end to end.
 - Add `docs/EXAMPLE-PROJECT.md` and e2e coverage for the external project demo.
 - Add product principles and core invariants for the Claude work -> Codex verification -> Human Gate runtime.

package/docs/CODEMAPS/scripts.md

@@ -114,7 +114,7 @@ scripts/
 | `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, report, review, review-cycle,  |
+| `cli.js` | _(none)_ | NEKOWORK/HARNESS CLI entrypoint. Public verbs: check, init, doctor, ask, plan, team, work, verify, gate, ship, apply, run, report, review, r |
 | `core/auth-guard.js` | ` BLOCKED_ENV `, `assertDelegatedCliAuth` |  |
 | `core/build-roots.js` | `buildRoots` |  |
 | `core/cli-resolver.js` | `assertProviderCliTrust`, `isPathInside`, `resolveCli`, `resolveProviderCli` |  |

package/docs/CODEMAPS/tests.md

@@ -10,11 +10,13 @@ tests/
 |-- e2e/
 |   |-- case-studies-doc.test.js
 |   |-- external-demo.test.js
+|   |-- feedback-triage-doc.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
+|   |-- trading-dashboard-example.test.js
+|   `-- trust-docs.test.js
 |-- integration/
 |   `-- build-pipeline.test.js
 |-- optional/
@@ -59,11 +61,13 @@ tests/
 |---|---|---|
 | `e2e/case-studies-doc.test.js` | _(none)_ |  |
 | `e2e/external-demo.test.js` | _(none)_ |  |
+| `e2e/feedback-triage-doc.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)_ |  |
+| `e2e/trust-docs.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)_ |  |

package/docs/DEMO.md

@@ -25,6 +25,8 @@ Demo completed: verdict=approve_with_fixes, ship_ready=false, applied=false
 
 This transcript is the README-friendly demo path. It uses mock providers, so it is safe to run on a fresh checkout without Claude, Codex, Gemini, or API keys.
 
+![NEKOWORK one-minute terminal demo](assets/demo-terminal.svg)
+
 ```text
 $ npx -y @ps-neko/nekowork@alpha doctor --quick
 NEKOWORK doctor
@@ -141,7 +143,7 @@ project root : C:\path\to\harness
 
 STATUS  CHECK                   MESSAGE
 PASS    node                    Node 24.x
-PASS    package metadata        @ps-neko/nekowork@0.1.0-alpha.1; public alpha publish candidate
+PASS    package metadata        @ps-neko/nekowork@0.1.0-alpha.2; public alpha package
 PASS    git worktree            project root is inside a git worktree
 WARN    gemini cli              installed, auth status is not checked non-interactively
 

package/docs/EXAMPLE-PROJECT.md

@@ -87,6 +87,6 @@ demo-target/
 
 ## What This Does Not Prove
 
-- Public npm installation. The package metadata is ready, but publish execution still requires npm owner auth.
+- Public npm installation. This demo intentionally exercises the source-checkout path; run the npm install smoke separately for package resolution.
 - 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.

package/docs/FAILURE-MODES.md

@@ -0,0 +1,94 @@
+# Failure Modes
+
+NEKOWORK should fail in ways that leave evidence behind and avoid surprise writes.
+
+## Health Check Warnings
+
+`check` is a quick alias for `doctor --quick`.
+
+Typical warnings include:
+
+- target directory is not a git repository
+- provider CLI is missing
+- optional live auth was not checked
+- package metadata is present but not release-ready
+
+Warnings are meant to tell the user what would matter for live work. They do not mutate the project.
+
+## No-Ship
+
+`ship` writes `NO_SHIP` when the session has unresolved quality, security, or acceptance risk.
+
+Recovery path:
+
+```bash
+node scripts/cli.js report --session <id>
+node scripts/cli.js run "fix the reported blocker" --session <new-id>
+node scripts/cli.js gate status --session <new-id>
+```
+
+`apply` refuses a no-ship session unless a maintainer intentionally changes the evidence flow.
+
+## Human Gate
+
+`HUMAN_GATE` means the tool found risk that needs a person before apply.
+
+The user can:
+
+```bash
+node scripts/cli.js gate status --session <id>
+node scripts/cli.js gate approve --session <id> --reason "reviewed risk"
+node scripts/cli.js gate block --session <id> --reason "needs more tests"
+```
+
+Approval records evidence. Blocking keeps the session from shipping.
+
+## Apply Refusal
+
+`apply` can refuse when:
+
+- there is no live-work diff
+- `SHIP_READY` is missing
+- a newer `NO_SHIP` exists
+- `HUMAN_GATE` is unresolved
+- the target worktree is dirty
+
+Recovery path:
+
+```bash
+git status -sb
+node scripts/cli.js report --session <id>
+node scripts/cli.js gate status --session <id>
+```
+
+Then either fix the blocker, approve/block the gate, or rerun the session.
+
+## Stale Generated Files
+
+When catalog, tests, or generated docs change, codemap or generated-output checks may fail.
+
+Recovery path:
+
+```bash
+node scripts/build-codemaps.js
+npm test
+```
+
+The generated diff should be reviewed like any other project change.
+
+## Provider Auth Problems
+
+Default mock mode does not require provider auth.
+
+Live mode can fail if local CLI auth is missing or expired. In that case, log in through the provider CLI, then rerun the same command. NEKOWORK does not need long-lived API-key fallback for the normal delegated CLI path.
+
+## npm / npx Problems
+
+If `npx -y @ps-neko/nekowork@alpha doctor --quick` fails, capture:
+
+- OS and shell
+- Node and npm versions
+- exact command
+- redacted output
+
+Then open an alpha feedback issue with the triage template.