godpowers 3.13.1 → 3.14.0

package/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.14.0] - 2026-06-17
+
+UX-audit remediation release. Drives the Godpowers UX audit (`uxaudit.md`, 11
+weighted experience lenses) to zero: all 20 findings across usability, content,
+information architecture, interaction, process, journeys, and trust. The changes
+are backward compatible and add no new commands; they tighten the install and
+dashboard surfaces, broaden the free-text router, and rewrite the front-door
+docs. No public command/agent/workflow/recipe surface change (counts stay
+120 / 40 / 13 / 44); lib module count unchanged at 91.
+
+### Added
+- **`docs/README.md` documentation index (IA-004):** a "Start here" section
+  linking every user-facing doc and a separate "Internal and maintainer" section
+  for the rest, so a reader landing in `docs/` can tell which is which.
+- **`--help` "Start here" group (CNT-004):** `npx godpowers --help` now leads
+  with a 6-item common-command group above two labelled advanced groups
+  (ledger/evidence, workflow/tooling), mirroring the install-success copy.
+
+### Changed
+- **Install/surface argument validation (USE-001, USE-002, USE-003):** a typo'd
+  bare subcommand now errors instead of silently starting a global install; an
+  unknown `--profile` is a clean one-line error before any filesystem write, not
+  a mid-install stack trace; `surface --runtime=<bad>` is rejected instead of
+  planning an apply to a nonexistent runtime.
+- **Dashboard and report display honesty (USE-004, CNT-005, CNT-006, IXD-001):**
+  `status --full` shows `Phase/Step: not initialized` (not `Complete`) on an
+  uninitialized project; the readiness headline reads `no blockers` instead of
+  the overloaded `ready`; the empty `report` names the commands that populate
+  the ledger; `next` no longer prints the recommended command a third time.
+- **Free-text router accuracy (IA-001, IA-002):** broadened `intent-keywords`
+  for the highest-traffic recipes so common verbs match a topical recipe (fix a
+  bug, ship it, deploy, release, check progress); `classifyWorkSize` returns
+  null when no small-task signal is present instead of confidently mis-sizing an
+  unrelated intent as `/god-quick`.
+- **Skipped-step progress honesty (JRN-002):** `progressSummary` exposes a
+  `skipped` count and the dashboard progress line annotates it
+  (`... 2 of 13 complete, 2 skipped`) so a run that skipped tiers no longer
+  shows a silently inflated percent.
+- **Close-gate honesty (PROC-001):** `can-close` output, the `canClose`
+  docstring, and the orchestrator runbook now state that `can-close` is the
+  advisory since-in-flight freshness check and `npx godpowers gate` is the
+  mechanically enforced boundary, closing the described-gate vs gate-that-runs
+  gap.
+- **README front door (CNT-001, CNT-002, CNT-003):** the top fold is now
+  tagline -> what/who -> Quick start (install + `/god-mode`) -> inline glossary
+  -> why it exists; version-history prose moved to a one-line CHANGELOG/RELEASE
+  pointer; dense proof prose became a scannable list.
+- **Command descriptions (IA-003):** the worst offenders lead with the
+  user-intent verb (`/god-smite` -> "Clear the dependency cache"; `/god-org-context`
+  -> "Set up or read organization-level context"); the `/god-reconcile` (before,
+  read-only) vs `/god-sync` (after, write-back) overlap is disambiguated.
+- **Resume clarity (JRN-001):** the README states that plain `/god-mode` resumes
+  from disk (no `--yolo` needed) and distinguishes `/god-resume-work`; the
+  generated CHECKPOINT new-session block names the canonical arc-resume command.
+- **Trust claims (TRU-001, TRU-002):** SECURITY.md softens the 7/14-day SLA to
+  best-effort targets; the runtime headline no longer implies 15-way parity and
+  points to the honest Runtime Expectations table.
+
+## [3.13.2] - 2026-06-17
+
+Maintenance release that drives a third self-audit (`codeaudit.md`) to zero: one
+Medium and twelve Low findings across de-duplication, error handling, security
+hardening, the test gate, and docs. No public command/agent/workflow/recipe
+surface change (counts stay 120 / 40 / 13 / 44); lib module count 90 -> 91.
+
+### Changed
+- **Shared sync check-builder (ARC-001):** the four `*-sync` modules no longer
+  copy-paste `addCheck`/`listFiles`; they share `lib/sync-check.js` (full
+  `addCheck` for the aggregator, area-bound `makeAddCheck` for the rest).
+- **Per-file coverage floor (TEST-001):** `coverage:lib` now emits a json-summary
+  and `scripts/check-per-file-coverage.js` (in `release:check`) fails any lib
+  module below 70% lines (excluding the two environment-bound browser drivers),
+  so a single file can no longer rot while the aggregate stays green.
+- **De-duplication and cleanup (QUAL-001/002/003):** removed dead helpers
+  (two unused `rel()`, an unused `sha`), added `sync-fs.readTextOrNull` adopted by
+  `requirements.js` (which now sources PRD/ROADMAP paths from `artifact-map`), and
+  fixed a boolean/string status wart in `repo-surface-sync`.
+- **Pillars delineation (ARC-002):** `pillars.js` now has section dividers
+  separating the model and artifact-sync halves (a full split was deferred; the
+  halves share construction functions that are public API).
+
+### Fixed
+- **Reverse-sync error visibility (ERR-001):** the requirements step now writes
+  state before the ledger and surfaces a caught error as `requirementsError`
+  instead of silently nulling it.
+
+### Security
+- **MCP module-name guard (SEC-001):** `requireRuntime` rejects any name that is
+  not a plain lib basename (defense-in-depth).
+- **YAML recursion cap (SEC-002):** `intent.cleanArrays` caps recursion depth so a
+  pathologically deep file cannot overflow the stack.
+
+### Performance
+- **have-nots regex (PERF-001):** `findPositions` compiles its regex once instead
+  of per line. The whole-ledger read in `evidence.readJsonl` is documented as
+  bounded/acceptable with an opt-in prune noted for the future (PERF-002).
+
+### Docs
+- **Absolute README doc links (DOC-001):** `docs/` is deliberately excluded from
+  the package, so the README's `docs/*` links are now absolute GitHub URLs that
+  resolve on the npm page and in the tarball.
+
 ## [3.13.1] - 2026-06-16
 
 Maintenance release that drives a full self-audit (`codeaudit.md`) to zero: one

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.13.1-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.14.0-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -12,66 +12,53 @@ idea to hardened production. It runs as **slash commands inside your AI coding
 tool** (Claude Code, Codex, Cursor, etc.) that orchestrate **specialist agents**
 in fresh contexts to do the work.
 
-Want the short proof first? Start with [Quick Proof](docs/quick-proof.md) to
-run `npx godpowers quick-proof --project=. --brief`, see outcome metrics, pick
-a starter command set, and understand runtime expectations before reading the
-full reference. The [First 10 Minute Proof Case Study](docs/case-studies/first-10-minute-proof.md)
-shows the same evidence as a before-and-after adoption story. External
-CLI-verifiable canaries now cover [sindresorhus/is](docs/case-studies/sindresorhus-is-adoption-canary.md),
-[expressjs/cors](docs/case-studies/expressjs-cors-adoption-canary.md), and
-[tinyhttp/tinyhttp](docs/case-studies/tinyhttp-adoption-canary.md), with host
-slash-command gaps called out rather than hidden.
-Host-run proof studies now cover [slugify-cli](docs/case-studies/run-a.md),
-[Countdown](docs/case-studies/run-b.md), and
-[react-github-readme-button](docs/case-studies/run-c.md), including one
-blocked harden run recorded as evidence instead of hidden as success.
+## Quick start
+
+```bash
+# 1. Install for your AI coding tool (Claude Code shown; other tools under Install)
+npx godpowers --claude --global --profile=core
+```
+
+Then, inside your AI tool:
+
+```
+/god         # describe what you want in plain language; it routes you
+/god-mode    # run the full arc from idea to hardened production, autonomously
+```
+
+Prefer to try before installing? `npx godpowers quick-proof --project=. --brief`
+prints disk-state evidence, missing-artifact visibility, a next command, and
+host guarantees against a shipped fixture, no install required.
+
+New to the vocabulary? Quick glosses: `arc` (a full project run from idea to
+launch), `tier` (a phase of that run), `have-nots` (the artifact-quality checks
+every output must pass), `quarterback` (the single orchestrator that routes each
+step), `Pillars` (the durable project-context files), `bluefield` (a new project
+inside an established org). Full definitions are in
+[docs/concepts.md](https://github.com/aihxp/godpowers/blob/main/docs/concepts.md).
+
+## Why it exists
 
 Godpowers makes AI coding accountable: every serious run should leave disk
 state, artifacts, validation gates, host guarantees, and a next action. Code is
-only one output. The project memory and proof trail matter too.
-
-Version 3.13.1 is a maintenance release that drives a full self-audit to zero:
-the runtime ledger no longer loses verification records under concurrent writes,
-the `outcome check` verifier and the pre-tool-use hook are hardened, the
-`*-sync` modules share one filesystem helper, the argument parser is table-driven,
-branch coverage is now gated, and the architecture map is kept in lockstep by a
-machine guard. Version 3.13.0 makes the default greenfield arc (`/god-mode`) miss
-less. The one-shot `full-arc` workflow now runs a whole-codebase code audit after the
-build (so it catches what the per-slice reviews missed in AI-generated code) and
-a documentation pass after harden (so the shipped product has docs verified
-against the code, not vibes). The arc goes build, code-audit, deploy, observe,
-harden, docs, launch, final-sync: per-slice review, whole-codebase audit plus
-remediation, a security gate, and verified docs before launch. This builds on
-3.12.x, which made that code audit codeauditor-grade: `god-debt-assessor`
-(`/god-tech-debt`) produces a scored, prioritized, self-contained source-code
-audit across nine weighted dimensions, and the `audit-remediate` recipe drives
-the findings to zero (audit, fix worst-first with an independent reviewer,
-re-audit, bounded by an outcome budget, with the can't-fake-done gate ensuring
-"clean" is evidence-backed). It all sits on top of the completed Mythify fusion
-(the evidence producer, enforced close-on-evidence, the quarterback, work report,
-reflections, memory, lessons, outcome loops, MCP read tools, and ledger importer). The current 3.x line keeps
-the omitted installer profile on `core`, keeps first-run, demo, and
-surface-control entry points, preserves `--profile=full` for compatibility,
-keeps locate and lifecycle views under `/god-status`, ships the optional
-`@godpowers/mcp` companion package, and verifies docs, package contents, npm
-metadata, GitHub release state, and published install behavior before public
-release.
-
-Maintainer hardening continues on the 3.x line with small, audited public
-surface updates when they close real workflow gaps. Historical release details
-live in [CHANGELOG.md](CHANGELOG.md), while the current release status lives in
-[RELEASE.md](RELEASE.md).
-
-Strict release readiness remains fail-closed. Godpowers requires delegated
-release checks to cover root docs, docs, agents, skills, routing, workflows,
-schema, templates, references, hooks, lib, scripts, tests, fixtures, GitHub
-workflows, package metadata, npm, GitHub release, CI, publish workflow, and
-local install state before a human-approved release executor can run.
-
-The dashboard now starts with an action brief and a host guarantee line: the
-next command, why it is recommended, whether the project is ready, the first
-blockers that need attention, and whether the current host can provide full,
-degraded, or unknown runtime guarantees.
+only one output; the project memory and proof trail matter too.
+
+### See it work
+
+- [Quick Proof](https://github.com/aihxp/godpowers/blob/main/docs/quick-proof.md): run `npx godpowers quick-proof --project=. --brief` for outcome metrics, a starter command set, and runtime expectations.
+- [First 10 Minute Proof Case Study](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/first-10-minute-proof.md): the same evidence as a before-and-after adoption story.
+- Independent, CLI-verifiable canaries: [sindresorhus/is](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/sindresorhus-is-adoption-canary.md), [expressjs/cors](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/expressjs-cors-adoption-canary.md), [tinyhttp/tinyhttp](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/tinyhttp-adoption-canary.md). Host slash-command gaps are called out, not hidden.
+- Host-run proof studies: [slugify-cli](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/run-a.md), [Countdown](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/run-b.md), [react-github-readme-button](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/run-c.md), including one blocked harden run kept as evidence.
+
+The dashboard leads with an action brief and a host guarantee line: the next
+command, why it is recommended, whether the project is ready, the first blockers
+that need attention, and whether the host can provide full, degraded, or unknown
+runtime guarantees.
+
+**What's new:** [CHANGELOG.md](CHANGELOG.md) holds release history and
+[RELEASE.md](RELEASE.md) the current release status. Strict release readiness is
+fail-closed: a human-approved release executor runs only after delegated checks
+cover docs, package metadata, npm, GitHub release, CI, and local install state.
 
 ### Ten Minute Proof Path
 
@@ -183,7 +170,7 @@ instead of pretending a background agent ran.
 | Other install targets | Skills and agent contracts install, while host-native spawning depends on the tool. |
 | Degraded hosts | Godpowers must report local-only or simulated agent behavior instead of hiding the limitation. |
 
-See [Host capabilities](docs/host-capabilities.md) for the detailed guarantee
+See [Host capabilities](https://github.com/aihxp/godpowers/blob/main/docs/host-capabilities.md) for the detailed guarantee
 model.
 
 ## Usage
@@ -334,17 +321,17 @@ dependency to the main `godpowers` package:
 
 ```bash
 npx godpowers mcp-info --project=.
-npx -y -p godpowers@3.13.1 -p @godpowers/mcp@3.13.1 godpowers-mcp serve --project=.
+npx -y -p godpowers@3.14.0 -p @godpowers/mcp@3.14.0 godpowers-mcp serve --project=.
 ```
 
 The companion exposes `status`, `next`, `gate_check`, `lint_artifact`, and
 `trace_requirement`. Host registration is opt-in:
 
 ```bash
-npx -y -p godpowers@3.13.1 -p @godpowers/mcp@3.13.1 godpowers-mcp setup --host=codex --project=. --write
+npx -y -p godpowers@3.14.0 -p @godpowers/mcp@3.14.0 godpowers-mcp setup --host=codex --project=. --write
 ```
 
-See [MCP Companion](docs/mcp.md) for package boundaries and setup details.
+See [MCP Companion](https://github.com/aihxp/godpowers/blob/main/docs/mcp.md) for package boundaries and setup details.
 
 ### Slash Commands
 
@@ -377,10 +364,10 @@ See [MCP Companion](docs/mcp.md) for package boundaries and setup details.
 | `/god-dogfood` | Run messy-repo dogfood scenarios for release and autonomy readiness | (built-in) |
 | `/god-migrate` | Detect legacy planning, BMAD, and Superpowers context; import and sync back | god-greenfieldifier when needed |
 | `/god-preflight` | Read-only intake audit before project-run readiness and pillars | god-auditor |
-| `/god-audit` | Score artifacts against have-nots | god-auditor |
+| `/god-audit` | Score artifacts against the have-nots quality checklist | god-auditor |
 | `/god-debug` | 4-phase systematic debug | god-debugger |
 | `/god-review` | Two-stage code review | god-spec-reviewer + god-quality-reviewer |
-| `/god-lint` | Mechanically validate artifacts against have-nots | (built-in) |
+| `/god-lint` | Mechanically validate artifacts against the have-nots checklist | (built-in) |
 | `/god-scan` | Rebuild linkage map from code; run reverse-sync | (built-in) |
 | `/god-link` | Manually add or remove a code-artifact link | (built-in) |
 | `/god-design-impact` | What-if analysis on DESIGN.md changes | (built-in) |
@@ -424,8 +411,12 @@ files, changed public behavior, and verification before editing. Reviewers
 block speculative flexibility, unrelated cleanup, and any touched file that
 does not trace back to the request or slice plan.
 
-If `.godpowers` state already exists, `/god-mode --yolo` resumes from disk
-instead of asking for the project description again.
+If `.godpowers` state already exists, plain `/god-mode` resumes the arc from
+disk (it reads `CHECKPOINT.md`) instead of asking for the project description
+again; `--yolo` is not required to resume, it only changes how many pauses the
+run takes. To resume a manual handoff created by `/god-pause-work`, use
+`/god-resume-work` (it reads `HANDOFF.md`). Either way, `/god-status` and
+`/god-next` are always safe re-entry points that report where the run stands.
 
 Under `--yolo`, Godpowers also auto-applies Pillars sync proposals when
 durable `.godpowers` artifacts change project truth. The decision is logged to
@@ -612,22 +603,25 @@ options with tradeoffs, and a default if the user just says "go".
 
 ## Supported Tools
 
-15 first-class runtimes: Claude Code, Codex, Cursor, Windsurf, Gemini CLI,
+Installs for 15 runtimes: Claude Code, Codex, Cursor, Windsurf, Gemini CLI,
 OpenCode, Copilot, Augment, Trae, Cline, Kilo, Antigravity, Qwen, CodeBuddy,
 Pi. T3 Code inherits from the underlying agent (Codex / Claude / OpenCode).
+Support is not uniform: Claude Code and Codex are the reference-grade paths; on
+the other targets the skills and agent contracts install but host-native agent
+spawning depends on the tool. See the Runtime Expectations table above.
 
 ## Full reference
 
-- [Getting Started](docs/getting-started.md)
-- [Quick Proof](docs/quick-proof.md)
-- [First 10 Minute Proof Case Study](docs/case-studies/first-10-minute-proof.md)
-- [Concepts](docs/concepts.md)
-- [Command reference (all 120 skills + 40 agents)](docs/reference.md)
-- [Feature awareness](docs/feature-awareness.md)
-- [Adoption Canary](docs/adoption-canary.md)
-- [Repository documentation sync](docs/repo-doc-sync.md)
-- [Repository surface sync](docs/repo-surface-sync.md)
-- [Roadmap](docs/ROADMAP.md)
+- [Getting Started](https://github.com/aihxp/godpowers/blob/main/docs/getting-started.md)
+- [Quick Proof](https://github.com/aihxp/godpowers/blob/main/docs/quick-proof.md)
+- [First 10 Minute Proof Case Study](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/first-10-minute-proof.md)
+- [Concepts](https://github.com/aihxp/godpowers/blob/main/docs/concepts.md)
+- [Command reference (all 120 skills + 40 agents)](https://github.com/aihxp/godpowers/blob/main/docs/reference.md)
+- [Feature awareness](https://github.com/aihxp/godpowers/blob/main/docs/feature-awareness.md)
+- [Adoption Canary](https://github.com/aihxp/godpowers/blob/main/docs/adoption-canary.md)
+- [Repository documentation sync](https://github.com/aihxp/godpowers/blob/main/docs/repo-doc-sync.md)
+- [Repository surface sync](https://github.com/aihxp/godpowers/blob/main/docs/repo-surface-sync.md)
+- [Roadmap](https://github.com/aihxp/godpowers/blob/main/docs/ROADMAP.md)
 - [Release Notes](RELEASE.md)
 - [Changelog](CHANGELOG.md)
 - [Inspiration](INSPIRATION.md)

package/RELEASE.md

@@ -1,41 +1,41 @@
-# Godpowers 3.13.1 Release
+# Godpowers 3.14.0 Release
 
-> Status: Prepared
-> Date: 2026-06-16
+> Status: Pending
+> Date: 2026-06-17
 
-[DECISION] Godpowers 3.13.1 is a maintenance release that drives a full self-audit (`codeaudit.md`, codeauditor-grade, nine weighted dimensions) to zero. It fixes one High finding plus the Medium and Low findings across runtime correctness, security hardening, the test gate, documentation, and de-duplication.
-[DECISION] No new skill, agent, workflow, or recipe surface is added or removed. Surface counts are unchanged from 3.13.0: 120 slash commands, 40 specialist agents, 13 workflows, 44 recipes.
-[DECISION] This release keeps `core` as the omitted installer profile, keeps `--profile=full` as the complete compatibility surface, and keeps the full 3.1.0-3.13.0 surface (fusion + codeauditor-grade audit + remediation loop + audited/documented greenfield arc).
+[DECISION] Godpowers 3.14.0 is a UX-audit remediation release that drives the Godpowers UX audit (`uxaudit.md`, 11 weighted experience lenses) to zero: all 20 findings across usability, content, information architecture, interaction, process, journeys, and trust.
+[DECISION] The changes are backward compatible and add no new commands. They tighten the install and dashboard surfaces, broaden the free-text router, restructure `--help`, add a docs index, and rewrite the front-door documentation. This is a minor bump because it adds backward-compatible user-facing functionality.
+[DECISION] No new skill, agent, workflow, or recipe surface is added or removed. Surface counts are unchanged: 120 slash commands, 40 specialist agents, 13 workflows, 44 recipes. The lib module count is unchanged at 91.
 
 ## What's in this release
 
-- [DECISION] Runtime correctness: `lib/evidence.js` `appendJsonlAtomic` now appends with `fs.appendFileSync` (O_APPEND) instead of a read-modify-write, so concurrent `verify`/`outcome check` processes no longer lose ledger records and the append is no longer O(n) (ERR-001). A `maxBuffer` overflow is surfaced distinctly instead of as a plain failure (ERR-003).
-- [DECISION] Security hardening: the pre-tool-use hook is reframed as a best-effort advisory typo guard and matches more destructive-command variants (SEC-001); `outcome check` announces a disk-sourced verifier before running it (SEC-002); the `LEDGER-LOG.md` command echo masks obvious secret shapes and `SECURITY.md` documents the ledger and Codex-sandbox trust boundaries (SEC-003, SEC-004); `SECURITY.md` replaces the non-existent `npm install --verify` with `npm audit signatures` (DOC-002).
-- [DECISION] Test gate: `coverage:lib` now enforces `--branches 75` (TEST-001); a new `scripts/test-runtime-audit.js` raises `lib/runtime-audit.js` line coverage from 68.8% to 77.8% (TEST-002); `scripts/test-router.js` no longer shares cumulative state across tests and cleans up its temp dirs (TEST-003); new `scripts/test-hooks.js`, `scripts/test-cli-log.js`, and `scripts/test-text-util.js` cover the new code.
-- [DECISION] De-duplication: the five `*-sync` modules share `lib/sync-fs.js`; the ANSI logger moves to `lib/cli-log.js` and `slugify` to `lib/text-util.js`; `installer-args.parseArgs` is now table-driven (ARC-001, QUAL-001, QUAL-002).
-- [DECISION] Documentation: `ARCHITECTURE-MAP.md` counts are regenerated and now machine-guarded by `scripts/test-doc-surface-counts.js`; `state.STATE_FILE` is the canonical state-file constant and `artifact-map.js`'s scope is documented accurately (DOC-001, DOC-003, ARC-002).
-- [DECISION] Re-audit follow-ups: a fresh self-audit confirmed no regressions and closed the residual gaps it found - `installer-core.js` imports the shared logger (QUAL-003); `dashboard.js`/`planning-systems.js` consume `sync-fs` (ARC-003); the `lib/README` module catalog is complete and now guarded by a completeness check (DOC-004); the ledger-append comment is corrected (DOC-005); the corrupt-state error is typed rather than message-matched (ERR-004); and the hook tests assert each warning's text (TEST-005).
+- [DECISION] Install and surface validation (USE-001, USE-002, USE-003): a typo'd bare subcommand errors instead of silently starting a global install; an unknown `--profile` is a clean one-line error before any filesystem write; `surface --runtime=<bad>` is rejected instead of planning an apply to a nonexistent runtime.
+- [DECISION] Dashboard and report display honesty (USE-004, CNT-005, CNT-006, IXD-001): `status --full` shows `Phase/Step: not initialized` instead of `Complete` on an uninitialized project; the readiness headline reads `no blockers` instead of the overloaded `ready`; the empty `report` names the commands that populate the ledger; `next` no longer prints the recommended command a third time.
+- [DECISION] Free-text router accuracy (IA-001, IA-002): broadened `intent-keywords` so common verbs match a topical recipe (fix a bug, ship it, deploy, release, check progress); `classifyWorkSize` returns null when no small-task signal is present instead of mis-sizing an unrelated intent as `/god-quick`.
+- [DECISION] Process and journey honesty (PROC-001, JRN-002): `can-close` output, its docstring, and the orchestrator runbook now state that `can-close` is the advisory freshness check and `npx godpowers gate` is the enforced boundary; the dashboard progress line annotates skipped steps so a skipped-tier run no longer shows an inflated percent.
+- [DECISION] Help and docs prioritization (CNT-004, IA-004): `--help` leads with a 6-item "Start here" group above two labelled advanced groups; a new `docs/README.md` indexes user-facing docs under "Start here" and separates internal/maintainer docs.
+- [DECISION] Front-door content, vocabulary, and trust (CNT-001, CNT-002, CNT-003, IA-003, JRN-001, TRU-001, TRU-002): the README top fold leads with a runnable Quick start and an inline glossary, version archaeology moved to a CHANGELOG/RELEASE pointer; the worst command descriptions lead with the user-intent verb and the `/god-reconcile` vs `/god-sync` overlap is disambiguated; the README clarifies that plain `/god-mode` resumes from disk; SECURITY.md softens its SLA to best-effort; the runtime headline no longer implies 15-way parity.
 
 ## Changes
 
-- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.13.1 version.
-- [DECISION] New runtime modules `lib/sync-fs.js`, `lib/cli-log.js`, and `lib/text-util.js` (lib module count 87 -> 90). No public command/agent/workflow/recipe surface change.
-- [DECISION] CHANGELOG, RELEASE notes, README, roadmap, reference, architecture, and the architecture map now reflect 3.13.1. The SECURITY supported-version table already carries the `3.13.x` row.
+- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.14.0 version.
+- [DECISION] No new runtime module (lib module count unchanged at 91). No public command/agent/workflow/recipe surface change.
+- [DECISION] CHANGELOG, RELEASE notes, README, roadmap, reference, architecture, the architecture map, and `agents/context.md` now reflect 3.14.0. The SECURITY supported-version table now carries the `3.14.x` row.
 
 ## Validation
 
 - [DECISION] `npm test` passed all command groups.
-- [DECISION] `npm run release:check` passed `coverage:lib` above the 90 percent line floor and the new 75 percent branch floor for `lib/**/*.js`.
+- [DECISION] `npm run release:check` passed `coverage:lib` above the 90 percent line floor and the 75 percent branch floor, and the per-file floor (>= 70 percent lines across the lib modules).
 - [DECISION] `npm run release:check` passed `npm audit --omit=dev` with 0 vulnerabilities and `git diff --check`.
-- [DECISION] `npm run release:check` passed public surface docs for version 3.13.1 with 120 skills, 40 agents, 13 workflows, and 44 recipes.
+- [DECISION] `npm run release:check` passed public surface docs for version 3.14.0 with 120 skills, 40 agents, 13 workflows, and 44 recipes.
 - [DECISION] `npm run release:check` passed root and `@godpowers/mcp` package contents.
 
 ## Upgrade
 
-- [DECISION] Use `npm install -g godpowers@3.13.1` or `npx godpowers@3.13.1`.
-- [DECISION] No migration is required. Existing projects are unaffected; the changes are internal correctness, security, test-gate, and maintainability fixes with no surface change.
+- [DECISION] Use `npm install -g godpowers@3.14.0` or `npx godpowers@3.14.0`.
+- [DECISION] No migration is required. The changes are install-surface validation, dashboard/router honesty, and documentation improvements with no breaking surface change.
 
 ## Notes
 
-- [DECISION] The publish targets are npm `godpowers@3.13.1`, npm `@godpowers/mcp@3.13.1`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.13.1`.
-- [DECISION] The tag-triggered GitHub publish workflow remains the preferred npm path because it publishes with provenance. This release has not been tagged or published to npm yet.
+- [DECISION] The publish targets are npm `godpowers@3.14.0`, npm `@godpowers/mcp@3.14.0`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.14.0`.
+- [DECISION] Not tagged or published yet. Tagging `v3.14.0` triggers the GitHub publish workflow (`.github/workflows/publish.yml`), which publishes `godpowers@3.14.0` and `@godpowers/mcp@3.14.0` to npm with provenance.

package/bin/install.js

@@ -10,14 +10,14 @@
 
 const path = require('path');
 
-const { parseArgs } = require('../lib/installer-args');
+const { parseArgs, COMMANDS } = require('../lib/installer-args');
 const { RUNTIMES, runtimeKeys } = require('../lib/installer-runtimes');
 const {
   installForRuntime,
   uninstallForRuntime,
   countInstalledSurface
 } = require('../lib/installer-core');
-const { describeProfiles } = require('../lib/install-profiles');
+const { describeProfiles, normalizeProfiles } = require('../lib/install-profiles');
 const commandFamilies = require('../lib/command-families');
 const identity = require('../lib/package-identity');
 const cliDispatch = require('../lib/cli-dispatch');
@@ -33,11 +33,15 @@ const BANNER = `
 function showHelp() {
   console.log(BANNER);
   log('Usage: npx godpowers [command] [options]\n');
-  log('Commands:');
+  log('Start here (most common):');
+  log('  (install)            npx godpowers --claude --global   Install for your AI tool');
   log('  status               Show the Godpowers Dashboard for a project');
   log('  next                 Show the dashboard and recommended next command');
-  log('  state advance        Update one tracked Godpowers state step');
-  log('  gate                 Check a tier artifact gate');
+  log('  quick-proof          Run a proof from the shipped fixture (no install)');
+  log('  demo                 Show the shipped sandbox proof');
+  log('  surface              Preview or apply an installed command profile');
+  log('');
+  log('Advanced - ledger and evidence:');
   log('  verify               Run a command as executed verification evidence');
   log('  can-close            Check whether a substep has the evidence to close');
   log('  route                Classify a prompt into an entry play (quarterback)');
@@ -47,13 +51,14 @@ function showHelp() {
   log('  lesson               Add or list reusable lessons in the ledger');
   log('  outcome              Start, check, stop, or inspect a bounded retry loop');
   log('  import-ledger        Import an existing .mythify/ ledger into .godpowers/ledger/');
+  log('');
+  log('Advanced - workflow and tooling:');
+  log('  state advance        Update one tracked Godpowers state step');
+  log('  gate                 Check a tier artifact gate');
   log('  mcp-info             Show read-only MCP companion setup instructions');
-  log('  quick-proof          Show a runnable proof from the shipped fixture');
   log('  automation-status    Show host automation provider support');
   log('  automation-setup     Show an opt-in automation setup plan');
   log('  dogfood              Run built-in messy-repo dogfood scenarios');
-  log('  demo                 Show the shipped sandbox proof');
-  log('  surface              Preview or apply an installed command profile');
   log('  extension-scaffold   Create a publishable extension pack skeleton');
   log('');
   log('Command families:');
@@ -208,6 +213,25 @@ function main() {
 
   if (cliDispatch.runCommand(opts)) return;
 
+  // USE-001: a bare leading token that is not a known command is a typo'd
+  // subcommand, not an install target (runtimes are passed as --flags). Reject
+  // it instead of silently starting a global install.
+  const firstToken = process.argv[2];
+  if (!opts.command && firstToken && !firstToken.startsWith('-') && !COMMANDS.has(firstToken)) {
+    error(`Unknown command: ${firstToken}`);
+    log('Run "npx godpowers --help" for usage.');
+    process.exit(1);
+  }
+
+  // USE-002: validate the install profile before any filesystem writes, so a bad
+  // value is a clean one-line error rather than a stack trace mid-install.
+  try {
+    normalizeProfiles(opts.profile);
+  } catch (_) {
+    error(`Unknown install profile: ${opts.profile}. Valid: core, builder, maintainer, suite, full`);
+    process.exit(1);
+  }
+
   console.log(BANNER);
   const srcDir = path.resolve(__dirname, '..');
 

package/lib/README.md

@@ -29,6 +29,7 @@ package-level integrations.
 | `atomic-write.js` | Write load-bearing files through temp-file validation and atomic rename. |
 | `fs-async.js` | Promise-based file read/write helpers for non-blocking runtime paths. |
 | `sync-fs.js` | Shared project-relative read/write/exists/readJson helpers for the `*-sync` modules. |
+| `sync-check.js` | Shared check-builder (`addCheck`/`makeAddCheck`) and file-lister for the `*-sync` modules. |
 
 ## Events and observability
 

package/lib/checkpoint.js

@@ -198,7 +198,11 @@ function write(projectRoot, state) {
     '   diff and recent events.',
     '3. Run `/god-status` to verify disk reality.',
     '4. Run `/god-next` for the next suggested command.',
-    '5. If anything in this file feels inconsistent with what you',
+    '5. To resume the autonomous arc, run `/god-mode` (plain, no `--yolo`',
+    '   needed): it reads this checkpoint and continues from disk. Use',
+    '   `/god-resume-work` only for a manual `/god-pause-work` handoff',
+    '   (it reads HANDOFF.md, not this file).',
+    '6. If anything in this file feels inconsistent with what you',
     '   know, run `/god-context-scan` to surface drift.',
     '',
     '## Provenance',

package/lib/cli-dispatch.js

@@ -31,12 +31,9 @@ function runDashboardCommand(opts) {
     return;
   }
 
+  // IXD-001: the rendered dashboard already states the recommendation under
+  // "Action brief: Next" and "Next: Recommended"; do not print it a third time.
   console.log(dashboard.render(result, { brief: opts.brief || !opts.full }));
-  if (opts.command === 'next') {
-    console.log('');
-    console.log('Suggested next command:');
-    console.log(`  ${result.next && result.next.command ? result.next.command : 'describe the next intent'}`);
-  }
 }
 
 function runDogfoodCommand(opts) {
@@ -67,6 +64,19 @@ function runQuickProofCommand(opts) {
 function runSurfaceCommand(opts) {
   const path = require('path');
   const surfaceProfile = require('./surface-profile');
+  const { runtimeKeys } = require('./installer-runtimes');
+  // USE-003: reject a surface --runtime target that does not exist, the same way
+  // the installer rejects an unknown runtime, instead of rendering a plan with a
+  // null path and recommending an --apply to a nonexistent target.
+  const validRuntimes = new Set(runtimeKeys());
+  const unknownRuntimes = (opts.runtimes || []).filter((name) => !validRuntimes.has(name));
+  if (unknownRuntimes.length > 0) {
+    const message = `Unknown runtime: ${unknownRuntimes.join(', ')}`;
+    if (opts.json) console.log(JSON.stringify({ command: 'surface', error: message }, null, 2));
+    else error(message);
+    process.exitCode = 1;
+    return;
+  }
   const srcDir = path.resolve(__dirname, '..');
   let applied = [];
 
@@ -283,6 +293,11 @@ function renderCanClose(result) {
   lines.push(`Reason: ${result.reason}`);
   if (result.strategy) lines.push(`Strategy: ${result.strategy}`);
   if (result.wentInFlightAt) lines.push(`In-flight since: ${result.wentInFlightAt}`);
+  // PROC-001: be honest about what enforces what. can-close is the advisory
+  // freshness check the orchestrator runs before closing a substep; the
+  // mechanically enforced gate is `npx godpowers gate`. Stating this here
+  // closes the "described gate vs gate that runs" gap.
+  lines.push('Note: advisory freshness check; the enforced gate is "npx godpowers gate".');
   return lines.join('\n');
 }
 

package/lib/command-families.js

@@ -365,7 +365,14 @@ function classifyWorkSize(text = '') {
   if (/\b(feature|new capability|enhancement)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'feature');
   if (/\b(milestone|roadmap|increment)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'build');
   if (/\b(tiny|typo|one-line|config tweak|trivial)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'fast');
-  return WORK_SIZE_LADDER.find((item) => item.id === 'quick');
+  // IA-002: only return the small-task default when there is an actual
+  // small-coding-task signal. Otherwise return null so callers (the /god
+  // router) fall back to the state-driven /god-next instead of confidently
+  // mis-sizing an unrelated intent ("ship it", "check progress", "deploy") as
+  // a /god-quick TDD coding task. A confident-but-wrong route is worse than a
+  // no-match.
+  if (/\b(quick|small|tdd|slice|minor|chore|refactor)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'quick');
+  return null;
 }
 
 function classifyVerification(text = '') {

package/lib/dashboard.js

@@ -366,13 +366,13 @@ function render(dashboard, opts = {}) {
       'Action brief:',
       `  Next: ${brief.recommended}`,
       `  Why: ${brief.reason}`,
-      `  Readiness: ${brief.confidence}`,
+      `  Readiness: ${brief.confidence === 'ready' ? 'no blockers' : brief.confidence}`,
       `  Attention: ${brief.blockers && brief.blockers.length > 0 ? brief.blockers.join('; ') : 'none'}${brief.overflow ? `; ${brief.overflow} more` : ''}`,
       `  Host guarantees: ${dashboard.host ? hostCapabilities.summary(dashboard.host) : proactive.host || 'unknown'}`,
       '',
       'Current status:',
       `  State: ${dashboard.state}`,
-      `  Progress: ${progress.percent || 0}% workflow progress (${progress.completed || 0} of ${progress.total || 0} tracked steps complete)`,
+      `  Progress: ${progress.percent || 0}% workflow progress (${progress.completed || 0} of ${progress.total || 0} tracked steps complete${progress.skipped ? `, ${progress.skipped} skipped` : ''})`,
       ...(deliverableBrief ? [deliverableBrief] : []),
       '',
       'Next:',
@@ -388,9 +388,9 @@ function render(dashboard, opts = {}) {
     '',
     'Current status:',
     `  State: ${dashboard.state}`,
-    `  Phase: ${current.phase || 'unknown'}${current.tierNumber !== null && current.tierNumber !== undefined ? ` (tier ${current.tierOrdinal} of ${current.tierCount}, internal ${current.tierKey || `tier-${current.tierNumber}`})` : ''}`,
-    `  Step: ${current.stepLabel || 'unknown'}${current.stepNumber ? ` (step ${current.stepNumber} of ${current.totalSteps})` : ''}`,
-    `  Progress: ${progress.percent || 0}% workflow progress (${progress.completed || 0} of ${progress.total || 0} tracked steps complete)`,
+    `  Phase: ${dashboard.state === 'not initialized' ? 'not initialized' : (current.phase || 'unknown')}${dashboard.state !== 'not initialized' && current.tierNumber !== null && current.tierNumber !== undefined ? ` (tier ${current.tierOrdinal} of ${current.tierCount}, internal ${current.tierKey || `tier-${current.tierNumber}`})` : ''}`,
+    `  Step: ${dashboard.state === 'not initialized' ? 'not initialized' : (current.stepLabel || 'unknown')}${dashboard.state !== 'not initialized' && current.stepNumber ? ` (step ${current.stepNumber} of ${current.totalSteps})` : ''}`,
+    `  Progress: ${progress.percent || 0}% workflow progress (${progress.completed || 0} of ${progress.total || 0} tracked steps complete${progress.skipped ? `, ${progress.skipped} skipped` : ''})`,
     `  Worktree: ${dashboard.worktree}`,
     `  Index: ${dashboard.index}`,
     '',