godpowers 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -7,6 +7,30 @@ 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
@@ -42,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`.
@@ -254,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.1-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,12 +30,13 @@ 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.1 is a release-surface cleanup patch on top of the 3.0.0 surface
+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`, 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.
+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. Historical release details
@@ -124,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
@@ -217,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` |
@@ -253,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=.
@@ -304,14 +315,14 @@ dependency to the main `godpowers` package:
 
 ```bash
 npx godpowers mcp-info --project=.
-npx -y -p godpowers@3.0.1 -p @godpowers/mcp@3.0.1 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.1 -p @godpowers/mcp@3.0.1 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.
@@ -592,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,47 +1,47 @@
-# Godpowers 3.0.1 Release
+# Godpowers 3.0.2 Release
 
 > Status: Published
 > Date: 2026-06-11
 
-[DECISION] Godpowers 3.0.1 is a documentation and release-surface cleanup patch on top of the 3.0.0 surface contraction release.
-[DECISION] This release preserves the 3.0.0 runtime behavior: `core` remains the omitted installer profile, `--profile=full` remains the complete compatibility surface, verb dispatchers continue routing to existing leaves, and `@godpowers/mcp` remains the optional read-only companion package.
-[DECISION] This release removes the completed migration planning document from the public documentation tree.
-[DECISION] This release updates stale README, roadmap, architecture, reference, MCP, release checklist, package metadata, and package version surfaces.
+[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] 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`.
 
 ## Changes
 
-- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.0.1 patch version.
-- [DECISION] README current-release prose now points at the 3.x release line instead of foregrounding older 2.x patch details.
-- [DECISION] `docs/ROADMAP.md` now reports the 3.x public adoption window and the v3.0.1 current surface.
-- [DECISION] `docs/RELEASE-CHECKLIST.md` now describes `npm run lint` as a separate static release-sensitive gate instead of claiming it runs inside `npm run release:check`.
-- [DECISION] Architecture extension compatibility examples now match the shipped first-party pack range `>=2.0.0 <4.0.0`.
-- [DECISION] MCP setup examples now pin `godpowers@3.0.1` and `@godpowers/mcp@3.0.1`.
-- [DECISION] The quick proof regression test now guards adoption canary and release verification documentation links.
+- [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 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.82 percent line coverage.
+- [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.1 with 117 skills, 40 agents, 13 workflows, and 42 recipes.
-- [DECISION] `npm run release:check` passed root package contents with 548 files.
+- [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.1` produced `godpowers-3.0.1.tgz` with 548 files.
-- [DECISION] `npm pack --workspace @godpowers/mcp --pack-destination /tmp/godpowers-release-3.0.1` produced `godpowers-mcp-3.0.1.tgz` 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.1` or `npx godpowers@3.0.1`.
+- [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.
@@ -49,5 +49,5 @@
 
 ## Notes
 
-- [DECISION] The publish targets are npm `godpowers@3.0.1`, npm `@godpowers/mcp@3.0.1`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.0.1`.
+- [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

@@ -96,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.
@@ -225,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
@@ -249,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

package/bin/install.js

@@ -58,6 +58,8 @@ function showHelp() {
   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:');
@@ -72,6 +74,10 @@ function showHelp() {
   log('  --tier=<name>        Tier for gate: prd, design, arch, roadmap, stack, repo, build, or harden');
   log('  --json               Emit JSON for status, next, proof, or automation commands');
   log('  --brief              Render compact output for status, next, or proof');
+  log('  --full               Render complete output for status, next, or demo');
+  log('  --dry-run            Preview a surface profile change');
+  log('  --apply              Apply a surface profile change');
+  log('  --runtime=<name>     Runtime target for surface, such as codex');
   log('  --name=<scope/name>  Extension package name for extension-scaffold');
   log('  --output=<path>      Extension output root for extension-scaffold');
   log('  --skill=<name>       Extension skill name for extension-scaffold');
@@ -110,6 +116,8 @@ function showHelp() {
   log('  npx godpowers automation-status --project=.');
   log('  npx godpowers automation-setup --project=.');
   log('  npx godpowers dogfood');
+  log('  npx godpowers demo --project=.');
+  log('  npx godpowers surface --profile=builder --codex --global --dry-run');
   log('  npx godpowers extension-scaffold --name=@godpowers/my-pack --output=.');
   log('  npx godpowers --claude --global');
   log('  npx godpowers --claude --global --profile=core');
@@ -216,7 +224,9 @@ module.exports = {
   runAutomationCommand: cliDispatch.runAutomationCommand,
   runDashboardCommand: cliDispatch.runDashboardCommand,
   runDogfoodCommand: cliDispatch.runDogfoodCommand,
+  runDemoCommand: cliDispatch.runDemoCommand,
   runQuickProofCommand: cliDispatch.runQuickProofCommand,
+  runSurfaceCommand: cliDispatch.runSurfaceCommand,
   runMcpInfoCommand: cliDispatch.runMcpInfoCommand,
   runExtensionScaffoldCommand: cliDispatch.runExtensionScaffoldCommand,
   runGateCommand: cliDispatch.runGateCommand,

package/lib/README.md

@@ -112,6 +112,7 @@ package-level integrations.
 | `installer-args.js` | Parse `bin/install.js` arguments and subcommands. |
 | `cli-dispatch.js` | Dispatch local CLI helper commands such as status, quick-proof, gate, dogfood, and extension-scaffold. |
 | `install-profiles.js` | Select smaller role-specific slash-command install surfaces. |
+| `surface-profile.js` | Preview and apply runtime command surface profile switches after install. |
 | `installer-runtimes.js` | Map supported runtimes to their config directories. |
 | `package-identity.js` | Centralize package name, version, repository, docs, and command identity. |
 | `automation-providers.js` | Detect and configure host-native automation providers. |

package/lib/cli-dispatch.js

@@ -46,7 +46,7 @@ function runDashboardCommand(opts) {
     return;
   }
 
-  console.log(dashboard.render(result, { brief: opts.brief }));
+  console.log(dashboard.render(result, { brief: opts.brief || !opts.full }));
   if (opts.command === 'next') {
     console.log('');
     console.log('Suggested next command:');
@@ -65,6 +65,10 @@ function runDogfoodCommand(opts) {
   if (result.status !== 'pass') process.exit(1);
 }
 
+function runDemoCommand(opts) {
+  return runQuickProofCommand({ ...opts, brief: opts.full ? false : true });
+}
+
 function runQuickProofCommand(opts) {
   const quickProof = require('./quick-proof');
   const result = quickProof.compute(opts.project);
@@ -75,6 +79,37 @@ function runQuickProofCommand(opts) {
   }
 }
 
+function runSurfaceCommand(opts) {
+  const path = require('path');
+  const surfaceProfile = require('./surface-profile');
+  const srcDir = path.resolve(__dirname, '..');
+  let applied = [];
+
+  if (opts.apply) {
+    if (opts.json) {
+      const originalLog = console.log;
+      const originalError = console.error;
+      console.log = () => {};
+      console.error = () => {};
+      try {
+        applied = surfaceProfile.apply(srcDir, opts);
+      } finally {
+        console.log = originalLog;
+        console.error = originalError;
+      }
+    } else {
+      applied = surfaceProfile.apply(srcDir, opts);
+    }
+  }
+
+  const result = surfaceProfile.plan(srcDir, opts);
+  if (opts.json) {
+    console.log(JSON.stringify({ ...result, applied }, null, 2));
+  } else {
+    console.log(surfaceProfile.render(result));
+  }
+}
+
 function runMcpInfoCommand(opts) {
   const mcpInfo = require('./mcp-info');
   const result = mcpInfo.info(opts.project);
@@ -185,6 +220,8 @@ const COMMAND_RUNNERS = {
   'automation-status': runAutomationCommand,
   'automation-setup': runAutomationCommand,
   dogfood: runDogfoodCommand,
+  demo: runDemoCommand,
+  surface: runSurfaceCommand,
   'extension-scaffold': runExtensionScaffoldCommand,
   gate: runGateCommand
 };
@@ -204,7 +241,9 @@ module.exports = {
   runAutomationCommand,
   runDashboardCommand,
   runDogfoodCommand,
+  runDemoCommand,
   runQuickProofCommand,
+  runSurfaceCommand,
   runMcpInfoCommand,
   runExtensionScaffoldCommand,
   runGateCommand,

package/lib/command-families.js

@@ -15,6 +15,8 @@ const COMMAND_FAMILIES = [
     purpose: 'Start or import a project.',
     commands: [
       '/god',
+      '/god-first-run',
+      '/god-demo',
       '/god-init',
       '/god-mode',
       '/god-plan',
@@ -191,6 +193,7 @@ const COMMAND_FAMILIES = [
     purpose: 'Tune settings, budgets, cache, profiles, help, and version info.',
     commands: [
       '/god-settings',
+      '/god-surface',
       '/god-set-profile',
       '/god-budget',
       '/god-cost',
@@ -292,9 +295,14 @@ function familyForCommand(command) {
   return COMMAND_FAMILIES.find((family) => family.commands.includes(command)) || null;
 }
 
-function renderFamilyCards(families = COMMAND_FAMILIES.filter((family) => family.visibility !== 'hidden')) {
+function renderFamilyCards(
+  families = COMMAND_FAMILIES.filter((family) => family.visibility !== 'hidden'),
+  opts = {}
+) {
   return families.map((family) => (
-    `${family.label}: ${family.purpose} (${family.commands.join(', ')})`
+    opts.includeCommands
+      ? `${family.label}: ${family.purpose} (${family.commands.join(', ')})`
+      : `${family.label}: ${family.purpose}`
   ));
 }
 

package/lib/install-profiles.js

@@ -1,6 +1,9 @@
 const COMMON = [
   'god',
+  'god-first-run',
+  'god-demo',
   'god-help',
+  'god-surface',
   'god-version',
   'god-status'
 ];
@@ -131,7 +134,7 @@ const PROFILE_SKILLS = {
 };
 
 const PROFILE_DESCRIPTIONS = {
-  core: 'front door, status, verbs, and autonomous compatibility',
+  core: 'first-run guidance, front door, status, verbs, surface control, and autonomous compatibility',
   builder: 'core plus planning leaves, stories, and runtime verification',
   maintainer: 'core plus hygiene, deps, docs, repair, automation, and extensions',
   suite: 'core plus multi-repo suite and workstream coordination',