vgxness 1.2.1 → 1.3.1

package/docs/cli.md

@@ -1,10 +1,10 @@
 # Use the local CLI
 
-Run `vgxness` commands from the repo with `bun run cli -- ...`. The CLI is intentionally thin: it parses flags, opens the local SQLite store, and calls the existing domain services for memory, agents, runs, and permissions. `npm run cli -- ...` remains available for Node development tooling compatibility when dependencies are already installed, but installed `vgxness`/`vgx` bins require Bun.
+Run `vgxness` commands from the repo with `bun run cli:bun -- ...` when you need the same Bun runtime path used by installed `vgxness`/`vgx` bins. The CLI is intentionally thin: it parses flags, opens the local SQLite store, and calls the existing domain services for memory, agents, runs, and permissions. `npm run cli -- ...` remains available for Node development tooling compatibility when dependencies are already installed, but installed `vgxness`/`vgx` bins require Bun.
 
 ## Local tarball install and dogfood
 
-Use the Bun package evidence workflow to dogfood the installable package without publishing. It builds package artifacts, validates package contents, installs into an isolated Bun environment, and checks both CLI bins.
+Use the Bun package evidence workflow to dogfood the installable package without publishing. It builds package artifacts, validates package contents, installs into an isolated Bun environment, checks both CLI bins, and runs an installed MCP read-only smoke.
 
 ```bash
 bun run package:bun:evidence
@@ -21,9 +21,10 @@ The evidence includes these smoke checks from the isolated install location:
 ```bash
 vgxness --help
 vgx --help
+vgxness mcp start --db <temp-memory.sqlite> # then call verification_plan with { changeType: 'mcp' }
 ```
 
-`vgx setup plan` and `vgx setup status` are human-readable and read-only by default; pass `--json` when you need parseable automation output. The MCP plan is read-only. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
+`vgxness setup plan` and `vgxness setup status` are human-readable and read-only by default; pass `--json` when you need parseable automation output. The MCP plan is read-only. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
 
 Only apply the OpenCode user/global config after reviewing the plan (use `--scope project` only when you intentionally want project config):
 
@@ -51,20 +52,20 @@ Release defaults used by the guided setup are:
 Recommended user flow after `npm install -g vgxness`:
 
 ```bash
-vgx --help
-vgx                      # operational dashboard in a TTY; static safe guidance in CI/non-TTY
-vgx init                 # setup wizard in a TTY; read-only plan in CI/non-TTY
-vgx setup plan           # human-readable, read-only plan
-vgx setup status         # human-readable, read-only setup status
-vgx setup apply --yes    # writes OpenCode config only after explicit consent
-vgx doctor               # human-readable readiness checks
-vgx sdd next --project <project> --change <change>
-vgx setup rollback --backup <path>
+vgxness --help
+vgxness                      # OpenTUI main menu in a TTY; static safe setup guidance in CI/non-TTY
+vgxness init                 # setup wizard in a TTY; read-only plan in CI/non-TTY
+vgxness setup plan           # human-readable, read-only plan
+vgxness setup status         # human-readable, read-only setup status
+vgxness setup apply --yes    # writes OpenCode config only after explicit consent
+vgxness doctor               # human-readable readiness checks
+vgxness sdd next --project <project> --change <change>
+vgxness setup rollback --backup <path>
 ```
 
-`setup plan`, `setup status`, and non-TTY `init` planning are read-only and do not write provider config. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgx doctor`.
+`setup plan`, `setup status`, and non-TTY `init` planning are read-only and do not write provider config. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
 
-`vgx init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgx doctor`, `vgx sdd status`, `vgx sdd next`, `vgx sdd get-artifact`, and `vgx sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
+`vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
 
 ## Bun-first repository verification
 
@@ -105,7 +106,7 @@ This default mode is diagnostic: it may emit `status: incompatible` and exit `0`
 bun run package:bun:evidence -- --require-pass
 ```
 
-It validates package metadata, artifact contents, forbidden workspace-only files, isolated Bun global install behavior, both `vgxness --help` and `vgx --help`, Bun runtime identity evidence for the installed wrapper, retired bridge invariants, no `package-lock.json`, and `publicationAttempted: false`. It must not invoke registry publication commands.
+It validates package metadata, artifact contents, forbidden workspace-only files, isolated Bun global install behavior, both `vgxness --help` and `vgx --help`, installed MCP `verification_plan` read-only behavior, Bun runtime identity evidence for the installed wrapper, retired bridge invariants, no `package-lock.json`, and `publicationAttempted: false`. It must not invoke registry publication commands or write provider config.
 
 Release-candidate checklist, without publishing:
 
@@ -185,43 +186,48 @@ bun run package:bun:evidence
 
 When reporting a Bun failure, include the Bun version, OS/CPU, Node version, whether `bun install --frozen-lockfile` completed, which `bun run verify:*` command failed, and whether the error points to `bun:sqlite`, migration application, package evidence, or another install step.
 
-## Quick path
+## Repository quick path
+
+These examples are for a source checkout. They use repo-local seeds and `bun run cli:bun -- ...`; they are not installed-package quick-start commands.
 
 ```bash
-npm run cli -- agents register --project vgxness --name apply-agent --description "Applies focused slices" --instructions "Follow SDD apply rules."
-npm run cli -- agents seed load --file seeds/agents/agent-seed-v1.json
-npm run cli -- agents list --project vgxness
-npm run cli -- agents get --project vgxness --name apply-agent
-npm run cli -- agents resolve --project vgxness --capabilities implementation,typescript --workflow sdd --phase apply --provider opencode --task "Implement a focused slice"
-npm run cli -- agents render --provider json --project vgxness --name apply-agent
-npm run cli -- agents render --provider opencode --project vgxness --name apply-agent
-npm run cli -- opencode preview --provider opencode --agent apply-agent --project vgxness --change my-change --phase apply-progress
-npm run cli -- sdd status --project vgxness --change my-change
+bun run cli:bun -- agents register --project vgxness --name apply-agent --description "Applies focused slices" --instructions "Follow SDD apply rules."
+bun run cli:bun -- agents seed load --file seeds/agents/agent-seed-v1.json
+bun run cli:bun -- agents list --project vgxness
+bun run cli:bun -- agents get --project vgxness --name apply-agent
+bun run cli:bun -- agents resolve --project vgxness --capabilities implementation,typescript --workflow sdd --phase apply --provider opencode --task "Implement a focused slice"
+bun run cli:bun -- agents render --provider json --project vgxness --name apply-agent
+bun run cli:bun -- agents render --provider opencode --project vgxness --name apply-agent
+bun run cli:bun -- opencode preview --provider opencode --agent apply-agent --project vgxness --change my-change --phase apply-progress
+bun run cli:bun -- sdd status --project vgxness --change my-change
 ```
 
+The checked-in agent seed is currently a repository development asset. It is not part of the published package whitelist; installed users should rely on setup-generated manager/agent config unless a release explicitly ships `seeds/agents/agent-seed-v1.json`.
+
 `agents render` returns generated artifacts in JSON. It does **not** install them or write `.opencode/`, `.claude/`, or any user/global provider config.
 
 `agents seed load` reads a project-local JSON manifest and upserts those agents into the local SQLite registry. It does **not** install OpenCode, create `.opencode/` or `.claude/`, or write provider/user/global config.
 
 `opencode preview` returns a combined, preview-only injection envelope for future OpenCode/MCP/hook callers. It does **not** execute OpenCode, install hooks or MCP servers, create runs, record skill usage, or write provider config.
 
-## Operational dashboard
+## OpenTUI main menu
 
-Use the interactive dashboard for a read-only operational view:
+Use no arguments in a TTY to open the main menu from a checkout:
 
 ```bash
-npm run cli --
-npm run cli -- dashboard interactive [--project vgxness] [--change my-change]
-npm run cli -- dashboard status --project vgxness [--change my-change]
+bun run cli:bun --
 ```
 
-The installed `vgxness`/`vgx` binary opens the same operational dashboard as `dashboard interactive` when run with no arguments in a TTY. With no TTY, no-args prints deterministic safe guidance, exits 0, and does not read dashboard status, infer a project, open project state, toggle raw mode, or write provider/config artifacts. Use `vgxness --help` or `vgxness -h` to print command help without starting the dashboard; explicit subcommands keep their normal behavior.
+The installed `vgxness`/`vgx` binary opens the OpenTUI main menu when run with no arguments in a TTY. With no TTY, no-args prints deterministic safe setup guidance, exits 0, and does not infer a project, open project state, toggle raw mode, or write provider/config artifacts. Use `vgxness --help` or `vgxness -h` to print command help without starting the main menu; explicit subcommands keep their normal behavior.
 
-The top-level menu is: **Installation, Status, Agents, Skills, Memory, SDD, Runs, Approvals, Permissions, Settings**. Terminal controls are `1-9`/`0` to switch screens, `r` to refresh, `?` for help, and `q` to quit. `Enter` shows details only; operational actions remain copy-only and must be run outside the TUI.
+The top-level menu is: **Installation, Doctor / recovery, SDD / workflow guidance, Advanced CLI, Exit**. Terminal controls are `↑/↓` or `j/k` to move, `Enter` to open the focused item, `?` for help, and `q` to quit.
 
-`dashboard interactive` can launch without `--project`; it opens Installation/status-oriented guidance while project-scoped checks are deferred rather than failed. Project-scoped screens render recoverable `project-required` states until you relaunch or refresh with a project.
+For scriptable status, use explicit read-only commands:
 
-`dashboard status --project <name>` is the scriptable/read-only renderer. It intentionally remains separate from no-args behavior and validates required project/limit flags.
+```bash
+bun run cli:bun -- setup status --project vgxness
+bun run cli:bun -- sdd status --project vgxness --change my-change
+```
 
 Provider support shown in the Installation surface is:
 
@@ -230,14 +236,14 @@ Provider support shown in the Installation surface is:
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
-The dashboard displays preview/status data, workflow registry entries, run traces, and approvals/preflights as read-only/copy-only data. It does **not** silently write OpenCode or other provider config, does **not** call provider executables, does **not** run install/apply/doctor/workflow commands, and does **not** approve/reject preflights. Any operational next action is copied for explicit execution outside the TUI.
+Setup and main-menu TUI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. Any operational next action is copied for explicit execution outside the TUI.
 
 ## Natural-language orchestrator preview
 
 Use `orchestrator preview` when you want `vgxness` to classify a request before deciding whether to answer directly, plan manually, diagnose, or enter SDD:
 
 ```bash
-npm run cli -- orchestrator preview \
+bun run cli:bun -- orchestrator preview \
   --project vgxness \
   --intent "Build a new persistent checkout workflow" \
   --change checkout-workflow \
@@ -262,9 +268,9 @@ Use workflow commands when you want an explicit operator-controlled path from in
 Each workflow has three modes:
 
 ```bash
-npm run cli -- <workflow> preview --project <name> --intent <text>
-npm run cli -- <workflow> run --project <name> --intent <text> [--phase <name>] [--agent-id <id>] [--db <path>]
-npm run cli -- <workflow> execute --run-id <id> --confirm [--override-escalation] [--workspace <path>] [--db <path>] [--executor safe-non-dispatching|provider|command]
+bun run cli:bun -- <workflow> preview --project <name> --intent <text>
+bun run cli:bun -- <workflow> run --project <name> --intent <text> [--phase <name>] [--agent-id <id>] [--db <path>]
+bun run cli:bun -- <workflow> execute --run-id <id> --confirm [--override-escalation] [--workspace <path>] [--db <path>] [--executor safe-non-dispatching|provider|command]
 ```
 
 `preview` is read-only: it returns the workflow registry plus optional planner output, does not open or write the database, does not create runs, does not call providers, does not edit files, and does not write provider config. Use it to choose between `quickfix`, `debug`, `sdd`, or another workflow before recording state.
@@ -277,25 +283,25 @@ Examples:
 
 ```bash
 # Preview a small docs/help fix.
-npm run cli -- quickfix preview \
+bun run cli:bun -- quickfix preview \
   --project vgxness \
   --intent "Fix the CLI help copy for workflow execute"
 
 # Record a debug workflow run, then inspect the run id in the JSON output.
-npm run cli -- debug run \
+bun run cli:bun -- debug run \
   --project vgxness \
   --intent "Investigate why workflow execute is blocked" \
   --db /tmp/vgxness-debug.sqlite
 
 # Record formal SDD work at a canonical phase.
-npm run cli -- sdd run \
+bun run cli:bun -- sdd run \
   --project vgxness \
   --intent "Implement the workflow CLI documentation" \
   --phase apply-progress \
   --db /tmp/vgxness-sdd.sqlite
 
 # Execute a previously recorded run with the default non-dispatching gate.
-npm run cli -- quickfix execute \
+bun run cli:bun -- quickfix execute \
   --run-id <run-id> \
   --confirm \
   --db /tmp/vgxness-debug.sqlite
@@ -311,7 +317,7 @@ Use `--executor command` only for the built-in bounded-process checks. It never
 | `node-version` | `node --version` | 5s | 8 KiB | Harmless local runtime smoke check. |
 
 ```bash
-npm run cli -- quickfix execute \
+bun run cli:bun -- quickfix execute \
   --run-id <run-id> \
   --confirm \
   --executor command \
@@ -328,9 +334,9 @@ Command execution is bounded to the workspace: `--command-cwd` must resolve insi
 Use approval commands to resolve per-operation human approval requests without loosening global permissions:
 
 ```bash
-npm run cli -- approvals list [--run-id <id>] [--db <path>]
-npm run cli -- approvals approve --id <approval-id> [--db <path>]
-npm run cli -- approvals reject --id <approval-id> [--reason <text>] [--db <path>]
+bun run cli:bun -- approvals list [--run-id <id>] [--db <path>]
+bun run cli:bun -- approvals approve --id <approval-id> [--db <path>]
+bun run cli:bun -- approvals reject --id <approval-id> [--reason <text>] [--db <path>]
 ```
 
 The safer default is unchanged: shell operations use `shell: ask` unless explicitly configured otherwise. Approval records let an operator authorize one exact pending operation, instead of changing provider or global permissions to make future shell operations pass automatically.
@@ -339,13 +345,13 @@ Command executor approval flow:
 
 ```bash
 # 1. Record the workflow run and keep the returned run id.
-npm run cli -- quickfix run \
+bun run cli:bun -- quickfix run \
   --project vgxness \
   --intent "Check the local Node runtime" \
   --db /tmp/vgxness-workflow.sqlite
 
 # 2. Request an allowlisted command dispatch. With shell ask, this stops at approval.
-npm run cli -- quickfix execute \
+bun run cli:bun -- quickfix execute \
   --run-id <run-id> \
   --confirm \
   --executor command \
@@ -353,17 +359,17 @@ npm run cli -- quickfix execute \
   --db /tmp/vgxness-workflow.sqlite
 
 # 3. Inspect the pending approval for that run.
-npm run cli -- approvals list \
+bun run cli:bun -- approvals list \
   --run-id <run-id> \
   --db /tmp/vgxness-workflow.sqlite
 
 # 4. Approve the exact recorded operation.
-npm run cli -- approvals approve \
+bun run cli:bun -- approvals approve \
   --id <approval-id> \
   --db /tmp/vgxness-workflow.sqlite
 
 # 5. Re-run the same execute command; the command now dispatches.
-npm run cli -- quickfix execute \
+bun run cli:bun -- quickfix execute \
   --run-id <run-id> \
   --confirm \
   --executor command \
@@ -378,7 +384,7 @@ Approval reuse is intentionally narrow. A resolved approval must match the run i
 To deny an operation, reject the approval instead of approving it:
 
 ```bash
-npm run cli -- approvals reject \
+bun run cli:bun -- approvals reject \
   --id <approval-id> \
   --reason "not appropriate for this run" \
   --db /tmp/vgxness-workflow.sqlite
@@ -395,21 +401,21 @@ A rejected approval is recorded in the run audit trail and prevents the matching
 Use this flow to manually verify MCP readiness after implementation. Setup preview is read-only: it does **not** install anything, create `.opencode/` or `.claude/`, or write provider/user/global config.
 
 ```bash
-npm run cli -- mcp setup --preview --provider opencode --db <path>
-npm run cli -- mcp setup --preview --provider claude --db <path>
-npm run cli -- mcp doctor --db <path> --project vgxness --change manual-smoke
+bun run cli:bun -- mcp setup --preview --provider opencode --db <path>
+bun run cli:bun -- mcp setup --preview --provider claude --db <path>
+bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke
 ```
 
 The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`.
 
-The top-level `vgx doctor` command prints human-readable readiness checks by default and accepts `--json` for scriptable output. Lower-level `mcp doctor` remains useful for MCP-specific checks and manual diagnostics; use `--json` where parseable output is needed. `ready:true` means required checks passed. `ready:false` means at least one required check failed; read the failed check `id`, `detail`, and optional `remediation` to fix the local setup, then run doctor again.
+The top-level `vgxness doctor` command prints human-readable readiness checks by default and accepts `--json` for scriptable output. Lower-level `mcp doctor` remains useful for MCP-specific checks and manual diagnostics; use `--json` where parseable output is needed. `ready:true` means required checks passed. `ready:false` means at least one required check failed; read the failed check `id`, `detail`, and optional `remediation` to fix the local setup, then run doctor again.
 
 ## OpenCode MCP visibility
 
 Use this read-only diagnostic when you need to confirm why OpenCode sees the project-local `vgxness` server from the repo but not from outside the worktree:
 
 ```bash
-npm run cli -- mcp doctor opencode
+bun run cli:bun -- mcp doctor opencode
 opencode mcp list
 ```
 
@@ -424,11 +430,11 @@ From a parent directory or another path outside the worktree, the project-local
 Use the installer when you want `vgxness` registered in OpenCode instead of copying the setup preview by hand. User/global scope is the default; project scope is opt-in:
 
 ```bash
-npm run cli -- mcp doctor --db <path> --project vgxness --change manual-smoke
-npm run cli -- mcp install opencode --plan
-npm run cli -- mcp install opencode --yes
-npm run cli -- mcp install opencode --plan --scope project --db <path>
-npm run cli -- mcp install opencode --yes --scope project --db <path>
+bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke
+bun run cli:bun -- mcp install opencode --plan
+bun run cli:bun -- mcp install opencode --yes
+bun run cli:bun -- mcp install opencode --plan --scope project --db <path>
+bun run cli:bun -- mcp install opencode --yes --scope project --db <path>
 ```
 
 Use `--plan` first when you want concrete target analysis without mutation. It prints the same OpenCode install contract the apply path uses, including `scope`, `targetPath`, `safety`, backup requirement, merge policy, verification hints, and any refusal reason. It does not create `.opencode/`, write user config, touch `$HOME/.config/opencode`, or create backups. User/global scope plans target `$HOME/.config/opencode/opencode.json` by default; project scope requires explicit `--scope project` and targets only the project config path.
@@ -450,12 +456,12 @@ Rollback is file-based:
 
 - If install created a new config, delete the reported `targetPath` (`.opencode/opencode.json` for project scope or `$HOME/.config/opencode/opencode.json` for user scope).
 - If install modified an existing config, restore the reported backup over `targetPath`.
-- Run `npm run cli -- mcp doctor --db <path> --project vgxness --change manual-smoke` again after rollback.
+- Run `bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke` again after rollback.
 
 Manual OpenCode verification checklist:
 
 1. Run doctor before install and note any failed checks.
-2. Run `npm run cli -- mcp install opencode --yes --db <path>`.
+2. Run `bun run cli:bun -- mcp install opencode --yes --db <path>`.
 3. Inspect the reported target path (default `$HOME/.config/opencode/opencode.json`) and confirm `mcp.vgxness` has `type:"local"`, a `command` array, and `enabled:true`.
 4. Restart OpenCode so it reloads config.
 5. In OpenCode, confirm the `vgxness` MCP tools are available.
@@ -466,14 +472,14 @@ Manual OpenCode verification checklist:
 Use `sdd` commands to inspect local SDD artifact state and save, read, or list phase artifacts. These commands read and write only the selected `vgxness` local SQLite memory store: `--db <path>` when passed, `VGXNESS_DB_PATH` when set, or the global default database when neither override is present.
 
 ```bash
-npm run cli -- sdd status --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
-npm run cli -- sdd ready --project vgxness --change sdd-workflow-engine --phase spec --db /tmp/vgxness-memory.sqlite
-npm run cli -- sdd save-artifact --project vgxness --change sdd-workflow-engine --phase proposal --content "# Proposal" --db /tmp/vgxness-memory.sqlite
-npm run cli -- sdd accept-artifact --project vgxness --change sdd-workflow-engine --phase proposal --actor user --note "Approved for spec" --db /tmp/vgxness-memory.sqlite
-npm run cli -- sdd get-artifact --project vgxness --change sdd-workflow-engine --phase proposal --db /tmp/vgxness-memory.sqlite
-npm run cli -- sdd list-artifacts --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
-npm run cli -- sdd next --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
-VGXNESS_DB_PATH=/tmp/vgxness-memory.sqlite npm run cli -- sdd list-artifacts --project vgxness --change sdd-workflow-engine
+bun run cli:bun -- sdd status --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd ready --project vgxness --change sdd-workflow-engine --phase spec --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd save-artifact --project vgxness --change sdd-workflow-engine --phase proposal --content "# Proposal" --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd accept-artifact --project vgxness --change sdd-workflow-engine --phase proposal --actor user --note "Approved for spec" --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd get-artifact --project vgxness --change sdd-workflow-engine --phase proposal --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd next --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
+VGXNESS_DB_PATH=/tmp/vgxness-memory.sqlite bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine
 ```
 
 Current phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present and the next ready missing phase. `sdd next` reports the next SDD action for a project/change. `sdd status`, `sdd next`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
@@ -487,8 +493,8 @@ The SDD CLI is status/persistence only. It does **not** execute providers, conti
 `agents resolve` ranks registered agents/subagents for a task using transparent metadata rules. It is read-only and does not execute agents, call a model, or mutate provider configuration.
 
 ```bash
-npm run cli -- agents resolve --project vgxness --capabilities implementation,typescript --workflow sdd --phase apply --provider opencode --task "Implement the next PRD slice"
-npm run cli -- agents resolve --project vgxness --mode subagent --capabilities review --workflow sdd --phase verify
+bun run cli:bun -- agents resolve --project vgxness --capabilities implementation,typescript --workflow sdd --phase apply --provider opencode --task "Implement the next PRD slice"
+bun run cli:bun -- agents resolve --project vgxness --mode subagent --capabilities review --workflow sdd --phase verify
 ```
 
 The response includes ranked `candidates` with `score` and `reasons`, plus `skipped` definitions with reasons such as provider, workflow, capability, scope, or mode mismatch. Exact workflow/phase matches are reported as `workflow phase matched: sdd:<phase>`, and SDD planning or verification task semantics are reported as `phase semantics matched: sdd-planning` or `phase semantics matched: sdd-verification`. Empty adapter maps are treated as provider-neutral; explicit adapter maps must include the requested provider.
@@ -497,12 +503,14 @@ Resolution v1 uses only current registry metadata: capabilities, workflows/phase
 
 ## Agent seed loading
 
-Load the checked-in v1 seed when a local registry should contain the project manager and seed subagents:
+Load the checked-in v1 seed from a source checkout when a local registry should contain the project manager and seed subagents:
 
 ```bash
-npm run cli -- agents seed load --file seeds/agents/agent-seed-v1.json
+bun run cli:bun -- agents seed load --file seeds/agents/agent-seed-v1.json
 ```
 
+This seed file is repo-only in v1.3.0 package contents. If installed-package workflows need it, first make an explicit package-contract change by adding it to `package.json.files` and the package evidence expectations.
+
 The command prints an `AgentSeedLoadSummary` JSON payload with `created`, `updated`, `agents`, `subagents`, and `warnings`. Re-running the same seed is safe: records are upserted by the current project, scope, and name, so existing seed records are updated in place instead of duplicated.
 
 The checked-in `vgxness-manager` and SDD subagents are self-contained: their seed instructions describe the MCP-first orchestration contract inline and do not require installing `~/.config/opencode/skills/sdd-*`. SDD skills can still be registered and attached as optional registry assets when a project wants extra reusable guidance.
@@ -512,8 +520,8 @@ Seed loading preserves user-created agents that are absent from the manifest. It
 After loading, you can inspect or preview the seed manager through normal registry commands:
 
 ```bash
-npm run cli -- agents get --project vgxness --name vgxness-manager
-npm run cli -- agents render --provider opencode --project vgxness --name vgxness-manager
+bun run cli:bun -- agents get --project vgxness --name vgxness-manager
+bun run cli:bun -- agents render --provider opencode --project vgxness --name vgxness-manager
 ```
 
 The render command returns preview artifacts only and keeps provider config untouched.
@@ -523,17 +531,17 @@ The render command returns preview artifacts only and keeps provider config unto
 Register an optional provider-agnostic skill, add an active version, attach it to a workflow phase, and record a simple run outcome. These examples are registry-managed enhancements, not requirements for the checked-in OpenCode manager/subagents:
 
 ```bash
-npm run cli -- skills register --project vgxness --name sdd-apply --description "Applies focused SDD slices"
-npm run cli -- skills add-version --project vgxness --name sdd-apply --version 1.0.0 --source-kind path --source-path .config/opencode/skills/sdd-apply/SKILL.md --activate
-npm run cli -- skills attach --project vgxness --name sdd-apply --target-type workflow-phase --target-key sdd:apply
-npm run cli -- skills record-usage --project vgxness --name sdd-apply --outcome helped --run-id <run-id> --target-type workflow-phase --target-key sdd:apply
+bun run cli:bun -- skills register --project vgxness --name sdd-apply --description "Applies focused SDD slices"
+bun run cli:bun -- skills add-version --project vgxness --name sdd-apply --version 1.0.0 --source-kind path --source-path .config/opencode/skills/sdd-apply/SKILL.md --activate
+bun run cli:bun -- skills attach --project vgxness --name sdd-apply --target-type workflow-phase --target-key sdd:apply
+bun run cli:bun -- skills record-usage --project vgxness --name sdd-apply --outcome helped --run-id <run-id> --target-type workflow-phase --target-key sdd:apply
 ```
 
 Resolve the skills that would be available to a runtime context:
 
 ```bash
-npm run cli -- skills resolve --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
-npm run cli -- skills resolve --agent apply-agent --project vgxness --phase apply --run <run-id> --record-usage selected
+bun run cli:bun -- skills resolve --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
+bun run cli:bun -- skills resolve --agent apply-agent --project vgxness --phase apply --run <run-id> --record-usage selected
 ```
 
 `skills resolve` is read-only by default. It combines matching skill attachments plus the agent definition `skills` field, returns active/current versions only, and includes source metadata plus inline `summary`/`content` when available. It records `selected` or `injected` usage only when both `--run` and `--record-usage` are explicit.
@@ -541,8 +549,8 @@ npm run cli -- skills resolve --agent apply-agent --project vgxness --phase appl
 Inspect skill registry and agent/subagent linkage status without mutating provider config:
 
 ```bash
-npm run cli -- skills status --project vgxness
-npm run cli -- skills status --project vgxness --scope project --provider opencode --mode agent --agent apply-agent
+bun run cli:bun -- skills status --project vgxness
+bun run cli:bun -- skills status --project vgxness --scope project --provider opencode --mode agent --agent apply-agent
 ```
 
 `skills status` prints deterministic JSON with `kind: "skills-status"` and `version: 1`. It includes project/scope/provider context, registry skill counts and current-version status, declared/resolved/missing skills for matching agents or subagents, resolver diagnostics, and safety markers. The command is read-only: it does not repair, install, or write provider configuration and does not record skill usage. A missing `--agent` match returns valid JSON with a warning diagnostic instead of crashing.
@@ -550,17 +558,17 @@ npm run cli -- skills status --project vgxness --scope project --provider openco
 Create and review a skill improvement proposal without activating it:
 
 ```bash
-npm run cli -- skills propose --project vgxness --name sdd-apply --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Updated skill body"}' --rationale "Repeated correction from trace" --source-signal '{"kind":"trace-failure"}'
-npm run cli -- skills proposals --status draft
-npm run cli -- skills get-proposal --proposal <proposal-id>
+bun run cli:bun -- skills propose --project vgxness --name sdd-apply --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Updated skill body"}' --rationale "Repeated correction from trace" --source-signal '{"kind":"trace-failure"}'
+bun run cli:bun -- skills proposals --status draft
+bun run cli:bun -- skills get-proposal --proposal <proposal-id>
 ```
 
 Activation is gated. Submitting and approving a proposal still does **not** change the active skill; only explicit apply creates the new active/current skill version:
 
 ```bash
-npm run cli -- skills submit-proposal --proposal <proposal-id> --actor uziel --reason "Ready for review"
-npm run cli -- skills approve-proposal --proposal <proposal-id> --actor uziel --reason "Reviewed diff"
-npm run cli -- skills apply-proposal --proposal <proposal-id> --actor uziel --reason "Activate approved proposal"
+bun run cli:bun -- skills submit-proposal --proposal <proposal-id> --actor uziel --reason "Ready for review"
+bun run cli:bun -- skills approve-proposal --proposal <proposal-id> --actor uziel --reason "Reviewed diff"
+bun run cli:bun -- skills apply-proposal --proposal <proposal-id> --actor uziel --reason "Activate approved proposal"
 ```
 
 Rejected or cancelled proposals cannot be applied. These commands store reviewable diffs and audit metadata in SQLite only; they do not rewrite external skill files or provider configs.
@@ -568,7 +576,7 @@ Rejected or cancelled proposals cannot be applied. These commands store reviewab
 Build an injection-ready payload without mutating provider config:
 
 ```bash
-npm run cli -- skills payload --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
+bun run cli:bun -- skills payload --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
 ```
 
 `skills payload` resolves the same active skills and returns payload v1 JSON: skill identity/version, source kind, available content or an unavailable reason, attachment reasons, and ordering metadata. Inline `content` is included directly. Local `path` sources are loaded read-only only when they resolve inside the current workspace root. URL sources are never fetched in v1 and return `url_fetch_disabled`. The command does **not** write `.opencode/`, `.claude/`, provider prompts, or external skill files.
@@ -576,8 +584,8 @@ npm run cli -- skills payload --agent apply-agent --project vgxness --workflow s
 `skills get` returns the current version, all versions, attachments, and usage records:
 
 ```bash
-npm run cli -- skills get --project vgxness --name sdd-apply
-npm run cli -- skills list --project vgxness
+bun run cli:bun -- skills get --project vgxness --name sdd-apply
+bun run cli:bun -- skills list --project vgxness
 ```
 
 Skill registry/resolution v1 is descriptive and controlled. It stores source metadata, compatibility hints, attachments, usage outcomes, and reviewable improvement proposals. Payload v1 can load inline content and safe workspace-local path content. It does **not** fetch URLs, mutate provider config, rewrite external skill files, generate unapproved diffs, or activate autonomous updates.
@@ -585,9 +593,9 @@ Skill registry/resolution v1 is descriptive and controlled. It stores source met
 ## Subagent examples
 
 ```bash
-npm run cli -- subagents register --parent-agent-id <agent-id> --project vgxness --name review-subagent --description "Reviews focused slices" --instructions "Review the current slice."
-npm run cli -- subagents list --parent-agent-id <agent-id>
-npm run cli -- subagents get --project vgxness --name review-subagent
+bun run cli:bun -- subagents register --parent-agent-id <agent-id> --project vgxness --name review-subagent --description "Reviews focused slices" --instructions "Review the current slice."
+bun run cli:bun -- subagents list --parent-agent-id <agent-id>
+bun run cli:bun -- subagents get --project vgxness --name review-subagent
 ```
 
 ## JSON definitions
@@ -610,8 +618,8 @@ Use `--file` when a definition has permissions, memory, workflows, skills, or ad
 ```
 
 ```bash
-npm run cli -- agents register --file ./agent.json
-npm run cli -- subagents register --file ./subagent.json
+bun run cli:bun -- agents register --file ./agent.json
+bun run cli:bun -- subagents register --file ./subagent.json
 ```
 
 For subagents, include `parentAgentId` in the JSON file.
@@ -621,8 +629,8 @@ For subagents, include `parentAgentId` in the JSON file.
 Render uses the provider-agnostic registry as input and returns generated content only:
 
 ```bash
-npm run cli -- agents render --provider json --id <agent-id>
-npm run cli -- agents render --provider opencode --id <agent-id>
+bun run cli:bun -- agents render --provider json --id <agent-id>
+bun run cli:bun -- agents render --provider opencode --id <agent-id>
 ```
 
 Example response shape:
@@ -665,7 +673,7 @@ The preview `opencode.json` includes `$schema` and an `agent` object. Top-level
 Use `opencode preview` when you want to inspect the full SDD context that could later be handed to an OpenCode integration:
 
 ```bash
-npm run cli -- opencode preview \
+bun run cli:bun -- opencode preview \
   --provider opencode \
   --agent apply-agent \
   --project vgxness \
@@ -713,8 +721,8 @@ The boundary is intentionally strict: the preview composes the existing OpenCode
 ## Memory examples
 
 ```bash
-npm run cli -- memory save --project vgxness --type decision --title "CLI path" --content "Use local SQLite by default."
-npm run cli -- memory search --project vgxness --query SQLite
+bun run cli:bun -- memory save --project vgxness --type decision --title "CLI path" --content "Use local SQLite by default."
+bun run cli:bun -- memory search --project vgxness --query SQLite
 ```
 
 ## Run examples
@@ -722,16 +730,16 @@ npm run cli -- memory search --project vgxness --query SQLite
 Create an auditable local run record, add a checkpoint, inspect it, and finish it:
 
 ```bash
-npm run cli -- runs create --project vgxness --intent "Build runtime foundation" --workflow sdd --phase apply --agent-id apply-agent --provider-adapter opencode --model openai/gpt-5.5
-npm run cli -- runs permission-check --run-id <run-id> --category shell --operation npm-test
-npm run cli -- runs approvals --run <run-id>
-npm run cli -- runs approve --approval <approval-id> --actor uziel --reason "Approved for local verification"
-npm run cli -- runs checkpoint --run-id <run-id> --label after-plan --state '{"next":"tests"}'
-npm run cli -- runs get --id <run-id>
-npm run cli -- runs resume-inspect --id <run-id>
-npm run cli -- runs resume-gate --approval <approval-id>
-npm run cli -- runs list --project vgxness
-npm run cli -- runs finish --run-id <run-id> --status completed --outcome success
+bun run cli:bun -- runs create --project vgxness --intent "Build runtime foundation" --workflow sdd --phase apply --agent-id apply-agent --provider-adapter opencode --model openai/gpt-5.5
+bun run cli:bun -- runs permission-check --run-id <run-id> --category shell --operation npm-test
+bun run cli:bun -- runs approvals --run <run-id>
+bun run cli:bun -- runs approve --approval <approval-id> --actor uziel --reason "Approved for local verification"
+bun run cli:bun -- runs checkpoint --run-id <run-id> --label after-plan --state '{"next":"tests"}'
+bun run cli:bun -- runs get --id <run-id>
+bun run cli:bun -- runs resume-inspect --id <run-id>
+bun run cli:bun -- runs resume-gate --approval <approval-id>
+bun run cli:bun -- runs list --project vgxness
+bun run cli:bun -- runs finish --run-id <run-id> --status completed --outcome success
 ```
 
 Runs are runtime state, not long-term memory. Use event and checkpoint payloads to reference memory observation IDs or artifact IDs when needed; do not duplicate durable observations into run state.
@@ -741,9 +749,9 @@ Runs are runtime state, not long-term memory. Use event and checkpoint payloads
 Resolving an approval appends an `approval` audit event and updates the approval status:
 
 ```bash
-npm run cli -- runs approve --approval <approval-id> --actor uziel --reason "Looks safe"
-npm run cli -- runs reject --approval <approval-id> --actor uziel --reason "Too broad"
-npm run cli -- runs cancel-approval --approval <approval-id> --actor uziel --reason "No longer needed"
+bun run cli:bun -- runs approve --approval <approval-id> --actor uziel --reason "Looks safe"
+bun run cli:bun -- runs reject --approval <approval-id> --actor uziel --reason "Too broad"
+bun run cli:bun -- runs cancel-approval --approval <approval-id> --actor uziel --reason "No longer needed"
 ```
 
 Approval resolution is persistence-only: approving records human consent but does **not** execute by itself. Resume-after-approval currently exists only in the runtime service through `RunService.resumeApprovedOperation({ approvalId, executor })`, and it requires an injected fake/test/sandbox executor supplied by code. Before that injected executor is called, the service writes a durable operation attempt reservation with an ordered attempt sequence. Storage supports multiple attempts per approval for future retries, but active `reserved` attempts still block another reservation. The default retry policy is `never`: repeated resume calls for the same approval fail before executor invocation after `reserved`, `succeeded`, `failed`, or `abandoned` attempts, even if the final runtime event was not recorded.
@@ -751,8 +759,8 @@ Approval resolution is persistence-only: approving records human consent but doe
 `runs retry-check` evaluates whether an approval is eligible for another attempt. It is read-only: it does **not** retry, reserve an attempt, invoke an executor, append events, or mutate retry state. Without `--policy`, it uses the safe default policy, `never`.
 
 ```bash
-npm run cli -- runs retry-check --approval <approval-id>
-npm run cli -- runs retry-check --approval <approval-id> --policy '{"mode":"after-failure","retryableStatuses":["failed"]}'
+bun run cli:bun -- runs retry-check --approval <approval-id>
+bun run cli:bun -- runs retry-check --approval <approval-id> --policy '{"mode":"after-failure","retryableStatuses":["failed"]}'
 ```
 
 Example blocked response:
@@ -780,7 +788,7 @@ Policy input is strict JSON. Current policy modes are `never`, `after-abandoned`
 Use `runs resume-inspect --id <run-id>` when an operator needs checkpoint and blocker context before deciding what to do manually:
 
 ```bash
-npm run cli -- runs resume-inspect --id <run-id>
+bun run cli:bun -- runs resume-inspect --id <run-id>
 ```
 
 The JSON output includes the run identity and status, latest checkpoint or `null`, blockers, pending approvals, active and failed attempts, debug evidence references, conservative `manualNextCommands`, and safety flags:
@@ -807,17 +815,17 @@ This flow is inspection only. It does **not** execute provider work, run preflig
 Use `runs resume-gate --approval <approval-id>` after `resume-inspect` identifies a pending approval and you want one approval-scoped planner response:
 
 ```bash
-npm run cli -- runs resume-inspect --id <run-id>
-npm run cli -- runs resume-gate --approval <approval-id>
-npm run cli -- runs resume-gate --approval <approval-id> --policy '{"mode":"after-failure","retryableStatuses":["failed"]}'
+bun run cli:bun -- runs resume-inspect --id <run-id>
+bun run cli:bun -- runs resume-gate --approval <approval-id>
+bun run cli:bun -- runs resume-gate --approval <approval-id> --policy '{"mode":"after-failure","retryableStatuses":["failed"]}'
 ```
 
 resume-gate is plan-only. It returns the `RunService.getRunResumeOrchestrationPlan` JSON with run and approval status, reconstructed pending operation context, retry-check guidance, blockers, manual next commands, and read-only safety flags. It does **not** run preflight, admit retry, invoke executors, execute operations, write provider config, create sandboxes, create worktrees, or append audit mutation records.
 
 Manual next-step examples:
 
-- `npm run cli -- runs approve --approval <approval-id> --actor <name> --reason "Reviewed"` when the approval is still pending.
-- `npm run cli -- runs retry-check --approval <approval-id>` to inspect retry eligibility separately.
+- `bun run cli:bun -- runs approve --approval <approval-id> --actor <name> --reason "Reviewed"` when the approval is still pending.
+- `bun run cli:bun -- runs retry-check --approval <approval-id>` to inspect retry eligibility separately.
 - Inspect the returned operation and continue manually outside the CLI if policy and human review allow it.
 
 There is still no executable `runs resume` CLI surface. The gate only explains the next safe manual step.
@@ -833,9 +841,9 @@ The runtime service has an enforcement gate for operation attempts, but there is
 Preview the current core policy without executing the operation:
 
 ```bash
-npm run cli -- permissions check --category read --operation read-file --path src/index.ts
-npm run cli -- permissions check --category edit --operation write-file --path ../outside.txt
-npm run cli -- permissions check --category provider-tool --operation call-tool --provider-tool vendor.tool
+bun run cli:bun -- permissions check --category read --operation read-file --path src/index.ts
+bun run cli:bun -- permissions check --category edit --operation write-file --path ../outside.txt
+bun run cli:bun -- permissions check --category provider-tool --operation call-tool --provider-tool vendor.tool
 ```
 
 The response is a decision object with `decision`, `reason`, and `message`. This is a policy decision service only; use `runs permission-check` when you also want an auditable run event and approval record for `ask`. Real provider/tool execution, CLI resume wiring, and isolated sandbox execution remain follow-up work.
@@ -855,12 +863,12 @@ Selection precedence is `--db <path>` (selected source: `flag`) > `VGXNESS_DB_PA
 Override the path when you need an isolated store:
 
 ```bash
-npm run cli -- agents list --db /tmp/vgxness.sqlite
-VGXNESS_DB_PATH=/tmp/vgxness.sqlite npm run cli -- memory search --project vgxness
+bun run cli:bun -- agents list --db /tmp/vgxness.sqlite
+VGXNESS_DB_PATH=/tmp/vgxness.sqlite bun run cli:bun -- memory search --project vgxness
 ```
 
 Existing project-local stores remain compatible; opt in explicitly when needed:
 
 ```bash
-npm run cli -- memory search --project vgxness --db .vgx/memory.sqlite
+bun run cli:bun -- memory search --project vgxness --db .vgx/memory.sqlite
 ```