godpowers 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.2] - 2026-06-11
+
+### Added
+- Added `/god-first-run`, `/god-demo`, and `/god-surface` as concierge
+  entry points for onboarding, sandbox proof, and post-install surface control.
+- Added the `try-safely` recipe for users who want a proof path before
+  touching their current project.
+- Added `godpowers demo` and `godpowers surface` CLI helpers, including
+  dry-run and apply flows for runtime profile changes.
+
+### Changed
+- Changed default command guidance from catalog-first and dashboard-first
+  output to compact recommendations with `Next commands:` blocks.
+- Updated `/god-help`, `/god`, `/god-next`, `/god-status`, and shared
+  dashboard contracts so full catalogs and full dashboards are opt-in.
+- Updated README, roadmap, reference, release notes, architecture, and Pillar
+  context counts for the 120-command and 43-recipe public surface.
+
+### Fixed
+- Added package, routing, installer-profile, command-family, quick-proof, and
+  surface-profile tests for the new concierge surface.
+- Refreshed repo documentation sync and repo surface sync evidence after the
+  new surface landed.
+
+## [3.0.1] - 2026-06-11
+
+### Changed
+- Updated README, roadmap, reference, MCP, architecture, release checklist, and
+  release notes for the 3.0.1 patch release.
+- Bumped `godpowers` and `@godpowers/mcp` package metadata to 3.0.1.
+- Clarified that `npm run lint` is a separate release-sensitive check rather
+  than part of `npm run release:check`.
+
+### Fixed
+- Fixed architecture extension compatibility examples to match shipped
+  first-party pack compatibility ranges.
+- Added quick proof regression coverage for adoption canary and published
+  install verification documentation links.
+
+### Removed
+- Removed the completed migration planning file from the public documentation
+  tree.
+
 ## [3.0.0] - 2026-06-10
 
 ### Added
@@ -23,7 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Routed `/god-observe` through the `ship` verb boundary based on Phase 2 host
   proof evidence.
 - Updated public docs, profile tests, command-family tests, and Phase 5
-  surface evidence for the 117-command surface.
+  surface evidence for the 120-command surface.
 
 ### Deprecated
 - Deprecated `/god-locate` in favor of `/god-status --locate`.
@@ -97,7 +140,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Updated USERS, README, roadmap, reference, architecture, release notes, and
-  bridge-plan status for the Phase 2 host proof campaign.
+  migration status for the Phase 2 host proof campaign.
 
 ## [2.5.0] - 2026-06-10
 
@@ -235,7 +278,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Proof goal labels resolve through shipped `/god` recipes and routes.
 
 ### Changed
-- Updated public surface counts to 112 slash commands and 42 intent recipes
+- Updated public surface counts to 120 slash commands and 43 intent recipes
   across release notes, reference docs, architecture maps, package metadata,
   and project Pillars.
 - Tightened public front-door recipe matching for starter phrases including

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.0.0-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.0.2-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.**
@@ -30,24 +30,18 @@ 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.0.0 makes the omitted installer profile `core`, adds five verb
-dispatch commands, and folds locate and lifecycle views into `/god-status`
-flags while preserving full-profile compatibility aliases. It keeps the
-one-directional state authority from 2.7.0, the optional `@godpowers/mcp`
-companion package, the installed-runtime gate and build-gate fixes, Codex host
-proof studies, executable tier gates, command-family UX, external CLI canary
-evidence, prompt-size guardrails, lib coverage gating, and package verification
-before publish.
+Version 3.0.2 is a concierge surface patch on top of the 3.0.0 surface
+contraction release. The current 3.x line keeps the omitted installer profile
+on `core`, adds 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. The 2.1.0 patch closes a command-injection vector in the
-agent-browser driver, guards runtime file parsing against corrupt state,
-makes data-directory installs a clean replace, and reconciles documentation
-drift. The 2.0.3 patch range-checks workflow agent references,
-derives command metadata from the individual files in `skills/`, delegates
-installer runtime logic to `lib/`, moves the detailed God Mode runbook into
-`references/`, and exposes async file APIs for incremental migration away from
-synchronous-only internals.
+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,
@@ -131,6 +125,13 @@ npx godpowers --codex --local --profile=builder
 npx godpowers --all --profile=maintainer
 ```
 
+After install, switch or preview the visible surface without starting over:
+
+```bash
+npx godpowers surface --profile=builder --codex --global --dry-run
+npx godpowers surface --profile=builder --codex --global --apply
+```
+
 Profiles are `core`, `builder`, `maintainer`, `suite`, and `full`. `core`
 installs the front door, status, verb dispatchers, and `/god-mode`
 compatibility. `full` preserves the complete command surface, while the smaller
@@ -224,13 +225,13 @@ same thing when you open a new session in a Godpowers project.
 If the full command surface feels large, begin with one of these paths and only
 learn the next command when Godpowers recommends it.
 
-`/god-help` presents command families first: start, continue, build, verify,
-operate, maintain, capture, recover, extend, collaborate, and configure. Leaf
-commands remain direct shortcuts.
+`/god-help` presents a short state-aware view by default. `/god-help all`
+shows the complete catalog. Leaf commands remain direct shortcuts.
 
 | Goal | Starter path |
 |---|---|
-| Start a product | `/god-init`, `/god-plan`, `/god-build` |
+| Start a product | `/god-first-run`, `/god-init`, `/god-plan`, `/god-build` |
+| Try safely | `/god-demo`, `/god-first-run`, `/god-init` |
 | Add a feature | `/god-reconcile`, `/god-feature`, `/god-sync`, `/god-review` |
 | Fix production | `/god-fix`, `/god-postmortem`, `/god-status` |
 | Audit an existing repo | `/god-preflight`, `/god-archaeology`, `/god-reconstruct`, `/god-audit`, `/god-tech-debt` |
@@ -260,7 +261,10 @@ runtime that can execute Node:
 ```bash
 npx godpowers status --project=.
 npx godpowers next --project=.
+npx godpowers demo --project=.
+npx godpowers surface --profile=core --codex --global --dry-run
 npx godpowers status --project=. --brief
+npx godpowers status --project=. --full
 npx godpowers status --project=. --json
 npx godpowers quick-proof --project=.
 npx godpowers state advance --step=prd --status=done --project=.
@@ -311,14 +315,14 @@ dependency to the main `godpowers` package:
 
 ```bash
 npx godpowers mcp-info --project=.
-npx -y -p godpowers@3.0.0 -p @godpowers/mcp@3.0.0 godpowers-mcp serve --project=.
+npx -y -p godpowers@3.0.2 -p @godpowers/mcp@3.0.2 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.0.0 -p @godpowers/mcp@3.0.0 godpowers-mcp setup --host=codex --project=. --write
+npx -y -p godpowers@3.0.2 -p @godpowers/mcp@3.0.2 godpowers-mcp setup --host=codex --project=. --write
 ```
 
 See [MCP Companion](docs/mcp.md) for package boundaries and setup details.
@@ -599,7 +603,7 @@ Pi. T3 Code inherits from the underlying agent (Codex / Claude / OpenCode).
 - [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 117 skills + 40 agents)](docs/reference.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)

package/RELEASE.md

@@ -1,65 +1,47 @@
-# Godpowers 3.0.0 Release
+# Godpowers 3.0.2 Release
 
-> Status: Prepared
-> Date: 2026-06-10
+> Status: Published
+> Date: 2026-06-11
 
-[DECISION] Godpowers 3.0.0 is the Phase 5 surface contraction release.
-[DECISION] This release makes the omitted installer profile resolve to `core` instead of `full`.
-[DECISION] This release keeps `--profile=full` as the complete compatibility surface for every shipped command.
-[DECISION] This release preserves the optional `@godpowers/mcp` companion boundary and keeps the main `godpowers` package dependency-free.
+[DECISION] Godpowers 3.0.2 is a concierge surface patch on top of the 3.0.0 surface contraction release and the 3.0.1 release-surface cleanup.
+[DECISION] This release keeps `core` as the omitted installer profile, keeps `--profile=full` as the complete compatibility surface, and adds first-run, demo, and surface-control entry points for safer onboarding.
+[DECISION] This release changes default guidance from catalog-first and dashboard-first output to compact recommendations with `Next commands:` blocks.
+[DECISION] This release keeps `@godpowers/mcp` as the optional read-only companion package.
 
 ## What's in this release
 
-- [DECISION] 117 slash commands.
+- [DECISION] 120 slash commands.
 - [DECISION] 40 specialist agents.
 - [DECISION] 13 executable workflows.
-- [DECISION] 42 intent recipes.
-- [DECISION] Five thin verb dispatch commands: `/god-plan`, `/god-fix`, `/god-ship`, `/god-capture`, and `/god-extend`.
-- [DECISION] `core` installs the front door, status, verb dispatchers, and `/god-mode` compatibility.
-- [DECISION] `full` preserves all direct leaf commands and compatibility aliases.
-- [DECISION] Five read-only MCP tools remain available in `@godpowers/mcp`.
+- [DECISION] 43 intent recipes.
+- [DECISION] Three concierge entry points are now shipped: `/god-first-run`, `/god-demo`, and `/god-surface`.
+- [DECISION] Five thin verb dispatch commands remain shipped: `/god-plan`, `/god-fix`, `/god-ship`, `/god-capture`, and `/god-extend`.
+- [DECISION] Five read-only MCP tools remain available in `@godpowers/mcp`: `status`, `next`, `gate_check`, `lint_artifact`, and `trace_requirement`.
 
-## Highlights
+## Changes
 
-- [DECISION] Omitted installer profile selection now writes `GODPOWERS_PROFILE` as `core`.
-- [DECISION] `/god-plan` routes planning intent to PRD, design, architecture, roadmap, stack, or reconstruction leaves.
-- [DECISION] `/god-fix` routes fix intent to debug or hotfix leaves.
-- [DECISION] `/god-ship` routes shipping intent to deploy, observe, or launch leaves.
-- [DECISION] `/god-capture` routes capture intent to note, todo, backlog, or seed leaves.
-- [DECISION] `/god-extend` routes extension intent to scaffold, add, list, info, remove, test, or agent-authoring leaves.
-- [DECISION] `/god-locate` is deprecated in favor of `/god-status --locate`.
-- [DECISION] `/god-lifecycle` is deprecated in favor of `/god-status --lifecycle`.
-- [DECISION] `/god-roadmap-check` now has `successor` metadata pointing to `/god-reconcile`.
+- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.0.2 patch version.
+- [DECISION] `/god-help` now starts with contextual next moves, while `/god-help all` remains the full installed catalog.
+- [DECISION] `/god`, `/god-next`, `/god-status`, and the shared dashboard contract now prefer concise action briefs and explicit `Next commands:` blocks.
+- [DECISION] `godpowers demo` exposes the shipped sandbox proof from the CLI without modifying the current project.
+- [DECISION] `godpowers surface --profile=<name> --dry-run` previews runtime profile changes, and `--apply` writes the selected installed surface.
+- [DECISION] README, roadmap, reference, architecture, release notes, and Pillar context now describe the 3.0.2 concierge surface.
 
 ## Validation
 
-- [DECISION] `npm ci` passed and reported 0 vulnerabilities.
-- [DECISION] `node scripts/test-installer-profiles.js` passed.
-- [DECISION] `node scripts/test-surface-contraction.js` passed.
-- [DECISION] `node scripts/test-command-families.js` passed.
-- [DECISION] `node scripts/validate-skills.js` passed.
-- [DECISION] `node scripts/test-quick-proof.js` passed.
-- [DECISION] `node scripts/test-doc-surface-counts.js` passed with public surface docs matching version 3.0.0.
-- [DECISION] `node scripts/test-repo-doc-sync.js` passed.
-- [DECISION] `node scripts/test-repo-surface-sync.js` passed.
-- [DECISION] `node scripts/test-automation-surface-sync.js` passed.
-- [DECISION] `node scripts/test-router.js` passed.
-- [DECISION] `npm run test:e2e` passed.
-- [DECISION] `node scripts/test-runtime-verification.js` passed.
-- [DECISION] `node scripts/test-agent-browser.js` passed.
-- [DECISION] `node scripts/test-install-smoke.js` passed.
-- [DECISION] `node bin/install.js dogfood --json` passed 5 of 5 scenarios.
-- [DECISION] `npm --workspace @godpowers/mcp test` passed.
-- [DECISION] `npm run pack:check` passed with 548 root package files.
-- [DECISION] `npm run pack:mcp:check` passed with 8 companion package files.
-- [DECISION] `npm run lint` passed.
-- [DECISION] `npm run test:audit` passed with `npm audit --omit=dev`, `git diff --check`, and public surface checks green.
-- [DECISION] `npm run release:check` passed with `coverage:lib` at 92.79 percent line coverage, `npm audit --omit=dev` reporting 0 vulnerabilities, public surface docs matching version 3.0.0, root package contents verified at 548 files, and `@godpowers/mcp` package contents verified at 8 files.
-- [DECISION] Publish status remains pending until branch review, protected merge, registry credentials, and release hooks are all green.
+- [DECISION] `npm run test:quick-proof` passed with 22 tests.
+- [DECISION] `npm run lint` passed with 29 static checks.
+- [DECISION] `npm run release:check` passed with `coverage:lib` at 92.69 percent line coverage.
+- [DECISION] `npm run release:check` passed `npm audit --omit=dev` with 0 vulnerabilities.
+- [DECISION] `npm run release:check` passed public surface docs for version 3.0.2 with 120 skills, 40 agents, 13 workflows, and 43 recipes.
+- [DECISION] `npm run release:check` passed root package contents with 556 files.
+- [DECISION] `npm run release:check` passed `@godpowers/mcp` package contents with 8 files.
+- [DECISION] `npm pack --pack-destination /tmp/godpowers-release-3.0.2` produced `godpowers-3.0.2.tgz` with 556 files.
+- [DECISION] `npm pack --workspace @godpowers/mcp --pack-destination /tmp/godpowers-release-3.0.2` produced `godpowers-mcp-3.0.2.tgz` with 8 files.
 
 ## Upgrade
 
-- [DECISION] Use `npm install -g godpowers@3.0.0` or `npx godpowers@3.0.0`.
+- [DECISION] Use `npm install -g godpowers@3.0.2` or `npx godpowers@3.0.2`.
 - [DECISION] Use `npx godpowers --profile=full` when the complete pre-3.0 command surface should be installed.
 - [DECISION] Use `npx godpowers --profile=core` or omit `--profile` for the contracted default surface.
 - [DECISION] Use optional MCP package install `npm install -g godpowers @godpowers/mcp` when the host can register MCP servers.
@@ -67,6 +49,5 @@
 
 ## Notes
 
-- [DECISION] No npm publish has been attempted from this prepared release note.
-- [DECISION] No GitHub release has been created from this prepared release note.
-- [DECISION] The next bridge-plan action is protected review and merge for the Phase 5 behavior slice.
+- [DECISION] The publish targets are npm `godpowers@3.0.2`, npm `@godpowers/mcp@3.0.2`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.0.2`.
+- [DECISION] The tag-triggered GitHub publish workflow remains the preferred npm path because it publishes with provenance.

package/SKILL.md

@@ -52,6 +52,9 @@ re-derive state from disk. Never rely on conversation memory for progress.
 Each tier gates on a verified artifact from the prior tier. You cannot build
 without architecture. You cannot deploy without a build. You cannot launch with
 unresolved Critical security findings.
+When a tier command has an executable gate, run
+`npx godpowers gate --tier=<tier> --project=.` and block on any non-zero exit
+before marking that tier done.
 
 For PRD, design, architecture, roadmap, stack, repo, build, and harden, run
 `npx godpowers gate --tier=<tier> --project=.` after the tier artifact is
@@ -93,120 +96,82 @@ answer a question, inspect first. When a term is resolved, record it in
 `.godpowers/domain/GLOSSARY.md` with canonical spelling, avoided aliases,
 relationships, and any unresolved ambiguity.
 
-### 9. Proposal Closeout
-When you answer with a recommendation, proposal, or exploratory plan and do not
-make file edits, run commands, or hand off to another command, end with a
-proposition block. The block must give the user concrete next moves instead of
-leaving them at a dead stop.
+### 9. Next Commands Closeout
+When you answer with a recommendation, proposal, status report, diagnostic,
+audit, lifecycle view, reconciliation, or exploratory plan, end with
+`Next commands:` unless a downstream command already launched.
 
-This also applies to diagnostic, status, audit, lifecycle, reconciliation, and
-decision-support reports when they end with suggestions, options, or a
-recommended sequence.
+The block must contain 1 to 4 runnable commands. Put the best option first.
+Each line must be a concrete command plus one plain sentence explaining what it
+will do. Do not end with abstract options such as "implement partial" or
+"discuss more" unless those words are part of the command argument.
 
 Use this shape:
 
 ```
-Proposition:
-  1. Implement partial: <smallest safe slice and command>
-  2. Implement complete: <larger command or project run>
-  3. Discuss more: <focused question or /god-discuss topic>
-  4. Run God Mode: /god-mode <optional flags or scope>
-Recommended: <one option and why>
+Next commands:
+- /god-next: Continue with the safest state-derived next step.
+- /god-status --full: Inspect the complete dashboard when you need all checks.
+- /god-discuss <topic>: Resolve the named open question before work starts.
 ```
 
-Only include options that actually fit the situation. If `/god-mode` is too
-broad or unsafe for the request, say so and offer `/god-feature`,
-`/god-refactor`, `/god-spike`, or `/god-discuss` instead.
+Only include commands that fit the current state. If `/god-mode` is too broad
+or unsafe for the request, use `/god-feature`, `/god-refactor`, `/god-spike`,
+`/god-fast`, `/god-quick`, or `/god-discuss` instead.
 
 ### 10. Completion Closeout
 When you complete work, especially from `/god-mode`, `/god-build`,
 `/god-feature`, `/god-hotfix`, `/god-refactor`, `/god-quick`, or any command
-that edits code or artifacts, do not stop at "complete" plus validation. End
-with a disk-derived closeout that tells the user the current state and what is
-next.
-
-Every closeout must include a **Godpowers Dashboard**. This dashboard is the
-same mental model across `/god-status`, `/god-progress`, `/god-next`,
-`/god-mode`, and every command that completes, pauses, or proposes work.
-
-When the runtime bundle is available, compute this with
-`lib/dashboard.compute(projectRoot)` and render it with
-`lib/dashboard.render(result)`. The executable dashboard engine is the shared
-source for phase, tier, step, progress, PRD and roadmap visibility, proactive
-checks, host guarantees, open items, and the next route. If the runtime module
-is unavailable, fall back to a manual disk scan and say `Dashboard engine:
-unavailable, manual scan used`.
+that edits code or artifacts, do not stop at "complete" plus validation.
+End with a concise disk-derived closeout that tells the user what changed,
+what needs attention, and what command to run next.
+
+Closeouts use the dashboard engine for computation, but they do not print the
+full dashboard by default. When the runtime bundle is available, compute with
+`lib/dashboard.compute(projectRoot)` and render a compact action brief. The
+complete dashboard is available through `/god-status --full`.
+
+If the runtime module is unavailable, silently use a manual disk scan. Mention
+the fallback only when the missing runtime changes the recommendation, then
+suggest `/god-doctor`.
 
 Use this shape:
 
 ```
-Godpowers Dashboard
-
-Current status:
-  State: <complete | partial | blocked | complete with deferred item>
-  Phase: <plain-language phase> (tier <human ordinal> of <human total>) when available
-  Step: <sub-step label> (<step n> of <total steps>) when available
-  Progress: <pct>% (<done> of <total> steps complete) when available
-  Worktree: <clean | modified files unstaged | staged changes | mixed>
-  Index: <untouched | staged files listed>
-
-Action brief:
-  Next: <recommended command or user decision>
-  Why: <route reason tied to disk state>
-  Readiness: <ready | needs attention>
-  Attention: <top blockers or none>
-  Host guarantees: <full | degraded | unknown with host and first gap>
-
-Planning visibility:
-  PRD: <done | pending | missing | deferred> <artifact path when present>
-  Roadmap: <done | pending | missing | deferred> <artifact path when present>
-  Current milestone: <roadmap milestone, tier, or next planning gate when known>
-  Completion: <pct>% <brief basis, for example done steps over total tracked steps>
-
-What changed:
-  1. <highest-signal change>
-  2. <highest-signal change>
+<one sentence describing the completed result>
+
+Changed:
+- <highest-signal user-visible change>
+- <highest-signal user-visible change>
 
 Validation:
-  + <command>: <result>
-
-Proactive checks:
-  Checkpoint: <fresh | refreshed | missing | stale | conflicts with state.json>
-  Reviews: <none | N pending, suggest /god-review-changes>
-  Sync: <fresh | missing | stale | local helper ran | suggest /god-sync>
-  Docs: <fresh | N stale, suggest /god-docs | repo-doc-sync ran>
-  Repo surface: <fresh | N stale, suggest /god-doctor | repo-surface-sync ran>
-  Host: <full | degraded | unknown with host and first gap>
-  Runtime: <not-applicable | known URL, suggest /god-test-runtime | no known URL, defer deployed verification>
-  Automation: <not configured | N active | available via provider, suggest /god-automation-setup>
-  Security: <clear | sensitive files changed, suggest /god-harden>
-  Dependencies: <clear | dependency files changed, suggest /god-update-deps>
-  Hygiene: <fresh | stale, suggest /god-hygiene>
-
-Open items:
-  1. <deferred staging, unstaged files, pending review, blocker, or none>
-
-Next:
-  Recommended: <one concrete command or user decision>
-  Why: <one sentence tied to current state>
+- <command>: <result>
+
+Attention:
+- <only blockers or signals that change the recommendation>
+
+Next commands:
+- <recommended command>: <one sentence reason>
+- /god-status --full: See the complete dashboard and proactive checks.
 ```
 
-If the command intentionally did not stage, commit, push, or deploy, say that
-plainly and explain what the user can do next. If deployed staging is deferred,
-include the deferred artifact path or exact missing input. If the worktree has
-pre-existing unrelated changes, say the index was left untouched and recommend
-a scoped review or staging command rather than implying the project is fully
-shipped.
+Omit empty sections. Do not print rows that only say `fresh`, `clear`, `none`,
+or `not-applicable`. If the command intentionally did not stage, commit, push,
+or deploy, say that plainly in the completion sentence or `Attention`.
+If deployed staging is deferred, include the deferred artifact path or exact
+missing input. If the worktree has pre-existing unrelated changes, say the
+index was left untouched and recommend a scoped review or staging command
+rather than implying the project is fully shipped.
 
-When the command only recommends work, keep the same dashboard but set
-`State: proposal` and end with the proposition block from Section 9. When the
-command pauses, set `State: blocked` or `State: paused` and make `Next` the
-one exact user decision needed to continue.
+When the command only recommends work, use the same compact shape and end with
+`Next commands:` from Section 9. When the command pauses, make the first next
+command the exact user decision or command needed to continue.
 
 ### 11. Command Family UX
 Godpowers has many leaf commands, but user-facing routing should start from
-families. Keep the full command surface available while presenting these
-families first:
+families and likely next moves. Keep the full command surface available, but
+show the full catalog only when the user asks for `/god-help all`,
+`/god-help <family>`, `/god-help search <keyword>`, or a direct command.
 
 - Start: start or import a project.
 - Continue: understand state and choose the next move.
@@ -222,9 +187,9 @@ families first:
 
 When choosing between similar commands, use the ladders from
 `lib/command-families.js`: capture ladder, work size ladder, verification
-ladder, status views, and trigger precedence. `/god-help` should render
-families before leaf commands, and `/god` should use the family helpers before
-asking the user to choose from a long list.
+ladder, status views, and trigger precedence. `/god-help` should render 3 to 6
+state-relevant choices by default, and `/god` should recommend one command
+before showing alternatives.
 
 ### 12. User-Facing Vocabulary
 Godpowers may use internal words such as "arc" in routing, recipes, and agent
@@ -246,32 +211,29 @@ and roadmap visibility when those files exist or are expected. Show whether
 the PRD is done, whether the roadmap exists, which milestone or tier is active,
 how close the tracked workflow is to completion, and the next concrete move.
 
-### 13. Auto-Invoke Visibility
+### 13. Automatic Work Visibility
 When Godpowers automatically runs another command, agent, or local runtime
-helper, show the user what happened. Do not describe these as "background"
-unless they are truly detached from the current run. Most Godpowers sync work
-is auto-invoked but still part of the current workflow.
+helper, make the user-visible message proportional to the outcome. Internal
+helper names do not appear by default.
 
-Use this shape whenever an automatic step runs or is skipped:
+If the automatic step changed user-visible artifacts or changed the next
+recommendation, say it in one plain sentence:
 
 ```
-Auto-invoked:
-  Trigger: <what caused this automatic step>
-  Agent: <god-updater | god-context-writer | none, local runtime only>
-  Local syncs:
-    + <feature-awareness | planning-system-import | reverse-sync | source-sync | repo-doc-sync | repo-surface-sync | route-quality-sync | recipe-coverage-sync | release-surface-sync | host-capabilities | dogfood-runner | pillars-sync | checkpoint-sync | context-refresh>: <result or skipped reason>
-  Artifacts: <changed files, no-op, or deferred>
-  Log: <SYNC-LOG.md, CHECKPOINT.md, REVIEW-REQUIRED.md, or none>
+Synced project artifacts after the change. Details were written to .godpowers/SYNC-LOG.md.
 ```
 
-If no agent was spawned, say so plainly:
+If the automatic step is routine and does not change the recommendation, keep
+the details in `.godpowers/SYNC-LOG.md`, `.godpowers/CHECKPOINT.md`, or
+`.godpowers/REVIEW-REQUIRED.md` without printing a card.
 
-```
-Agent: none, local runtime only
-Why: this path calls lib/reverse-sync.run directly
-```
+Use a detailed `Auto-invoked:` card only for `--verbose`, debugging,
+release-gate evidence, or a direct user request for automation internals.
+When shown, it must name the user-facing trigger, changed artifacts, and log
+path before any internal helper id.
 
-Automatic steps that especially need visible reporting:
+Automatic steps that especially need a concise note when they change the next
+recommendation, and a log entry otherwise:
 - `/god-sync` spawning `god-updater`
 - `god-updater` calling reverse-sync, Pillars sync, checkpoint sync, or
   AI-tool context refresh
@@ -365,7 +327,7 @@ Spawn these agents only when the trigger is direct and scope is bounded:
 - `god-docs-writer` when repo-doc-sync reports narrative drift in
   `CHANGELOG.md`, `RELEASE.md`, `CONTRIBUTING.md`, `SECURITY.md`, or
   `SUPPORT.md` after local mechanical sync has finished.
-- `god-auditor`, `god-roadmap-reconciler`, or `god-coordinator` when
+- `god-auditor`, `god-reconciler`, or `god-coordinator` when
   repo-surface-sync reports structural drift that needs agent contract,
   lifecycle graph, or extension-pack judgment.
 - `god-browser-tester` when frontend-visible files changed and a known local,

package/agents/god-archaeologist.md

@@ -8,6 +8,17 @@ description: |
 
   Spawned by: /god-archaeology, brownfield-arc workflow
 tools: Read, Bash, Grep, Glob, WebSearch
+inputs:
+  - "brownfield codebase"
+  - "git history"
+  - "repository documentation"
+outputs:
+  - ".godpowers/archaeology/REPORT.md"
+gates:
+  - "archaeology have-nots"
+  - "evidence-backed history and risk claims"
+handoff:
+  - "return report path and priority risks to caller"
 ---
 
 # God Archaeologist

package/agents/god-architect.md

@@ -6,6 +6,18 @@ description: |
 
   Spawned by: /god-arch, god-orchestrator
 tools: Read, Write, Bash, Grep, Glob
+inputs:
+  - ".godpowers/prd/PRD.md"
+  - "optional .godpowers/domain/GLOSSARY.md"
+  - "optional preparation context"
+outputs:
+  - ".godpowers/arch/ARCH.md"
+  - ".godpowers/arch/adr/"
+gates:
+  - "A-01 through A-13 have-nots"
+  - "npx godpowers gate --tier=arch --project=."
+handoff:
+  - "return architecture artifact and pause only for tied load-bearing decisions"
 ---
 
 # God Architect

package/agents/god-auditor.md

@@ -7,6 +7,19 @@ description: |
 
   Spawned by: /god-preflight, /god-audit, god-orchestrator (gate checks)
 tools: Read, Bash, Grep, Glob
+inputs:
+  - ".godpowers artifacts"
+  - "repository structure"
+  - "Pillars and workflow evidence"
+outputs:
+  - ".godpowers/preflight/PREFLIGHT.md"
+  - ".godpowers/AUDIT-REPORT.md"
+  - "gate pass or fail verdict"
+gates:
+  - "all applicable have-nots"
+  - "preflight and audit scoring evidence"
+handoff:
+  - "return prioritized remediation and gate verdict to caller"
 ---
 
 # God Auditor

package/agents/god-automation-engineer.md

@@ -7,6 +7,19 @@ description: |
 
   Spawned by: /god-automation-setup
 tools: Read, Write, Edit, Bash, Glob
+inputs:
+  - "approved automation setup plan"
+  - "host provider choice"
+  - ".godpowers/state.json"
+outputs:
+  - ".godpowers/automations.json"
+  - "host-native automation configuration"
+gates:
+  - "explicit user approval"
+  - "provider verification"
+  - "no unverified background claims"
+handoff:
+  - "return successful automation ids or hard-stop blocker"
 ---
 
 # God Automation Engineer