vgxness 0.1.0

package/docs/cli.md

@@ -0,0 +1,741 @@
+# Use the local CLI
+
+Run `vgxness` commands from the repo with `npm 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.
+
+## Local tarball alpha install
+
+Use this workflow to dogfood the installable alpha without publishing to npm. It builds the package, installs the tarball into an isolated temporary prefix, and uses an explicit temporary database so your default global memory store is untouched.
+
+```bash
+npm run build
+VGXNESS_TARBALL=$(npm pack --json | node -e 'const fs = require("node:fs"); const [pkg] = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(pkg.filename);')
+
+VGXNESS_SMOKE_PREFIX=$(mktemp -d)
+VGXNESS_SMOKE_WORKDIR=$(mktemp -d)
+VGXNESS_SMOKE_DB="$VGXNESS_SMOKE_WORKDIR/smoke.sqlite"
+
+npm install --prefix "$VGXNESS_SMOKE_PREFIX" --global --no-audit --no-fund "./$VGXNESS_TARBALL"
+export PATH="$VGXNESS_SMOKE_PREFIX/bin:$PATH"
+```
+
+Run the smoke checks from the temporary workdir:
+
+```bash
+cd "$VGXNESS_SMOKE_WORKDIR"
+vgxness --help
+vgx --help
+vgx setup plan
+vgxness setup status --db "$VGXNESS_SMOKE_DB"
+vgxness dashboard status --project vgxness --db "$VGXNESS_SMOKE_DB"
+vgxness mcp install opencode --plan --db "$VGXNESS_SMOKE_DB"
+```
+
+The MCP plan is read-only. With the explicit smoke DB above, it should show an installed server command that starts with `vgxness mcp start --db "$VGXNESS_SMOKE_DB"` and must not mention `npm run cli`, `tsx`, or repository-relative source paths. If `--db` is omitted, the installed command should be `vgxness mcp start` and use the global default at runtime.
+
+Only apply the OpenCode project config after reviewing the plan:
+
+```bash
+vgxness mcp install opencode --yes --db "$VGXNESS_SMOKE_DB"
+```
+
+Rollback cleanup:
+
+```bash
+rm -rf "$VGXNESS_SMOKE_PREFIX"
+rm -rf "$VGXNESS_SMOKE_WORKDIR"
+rm -f "./$VGXNESS_TARBALL"
+```
+
+For the automated version of this workflow, run `npm run package:smoke:install`.
+
+## Alpha npm/global setup
+
+The npm package name is `vgxness`, the recommended alpha release tag is `alpha`, and the license is proprietary (`SEE LICENSE IN LICENSE`). The npm package is inspectable JavaScript for Node runtime purposes, but it is not open-source licensed and must not be redistributed without permission.
+
+Release defaults used by the guided setup are:
+
+- Node.js `>=22`.
+- Provider: OpenCode.
+- Database: global user data location by default.
+- Install mode: MCP plus manager/SDD agents (`mcp-plus-agents`).
+- Public CLI language: English.
+
+Recommended user flow after `npm install -g vgxness`:
+
+```bash
+vgx --help
+vgx init                 # guided wizard in a TTY; read-only plan in CI/non-TTY
+vgx setup plan           # explicit read-only plan
+vgx setup apply --yes    # writes OpenCode config only after explicit consent
+vgx doctor               # general alias for MCP doctor checks
+vgx setup rollback --backup <path>
+```
+
+`setup plan` is always read-only. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <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`.
+
+`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.
+
+## Quick path
+
+```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
+```
+
+`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.
+
+## Guided dashboard
+
+Use the interactive dashboard for a read-only operational view and guided setup:
+
+```bash
+npm run cli --
+npm run cli -- dashboard interactive [--project vgxness] [--change my-change]
+npm run cli -- dashboard status --project vgxness [--change my-change]
+```
+
+The installed `vgxness` binary opens the interactive dashboard when run with no arguments. Use `vgxness --help` or `vgxness -h` to print command help without starting the dashboard; explicit subcommands keep their normal behavior.
+
+The top-level menu is exactly: **Setup, Workflows, Runs, Approvals, Agents, SDD, Doctor, Settings**. Terminal controls are `1-8` to switch screens, `r` to refresh, `?` for help, and `q` to quit. In Setup, use `n`/`b` for wizard steps, `j`/`k` for provider focus, `space` to toggle selection, `d` for details, and `esc` to close details or go back.
+
+`dashboard interactive` can launch without `--project`; it opens Setup and reports environment/provider 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.
+
+Provider support shown in the Setup wizard is:
+
+- **OpenCode** — supported primary provider with preview/status/doctor and read-only install planning.
+- **Claude** — preview-only guidance; no install/apply action is exposed.
+- **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.
+
+## 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 \
+  --project vgxness \
+  --intent "Build a new persistent checkout workflow" \
+  --change checkout-workflow \
+  --db .vgx/memory.sqlite
+```
+
+The command prints a deterministic JSON envelope with `flow`, `confidence`, `reason`, `signals`, `needsClarification`, optional `suggestedChangeId`, `previewActions`, `safety`, and optional read-only SDD `status`/`next` context when `--change` is supplied.
+
+Safety boundary: this is a preview only. It does **not** call providers, edit files, write provider config, create runs, run installers, install global memory, or create `openspec/`. Preview actions are labels/manual commands for review, not executed steps.
+
+## Workflow CLI
+
+Use workflow commands when you want an explicit operator-controlled path from intent classification to a recorded run and, optionally, a guarded execution request. Supported workflows are `explore`, `quickfix`, `plan`, `build`, `debug`, and `sdd`:
+
+- `explore` — inspect or discover context without committing to implementation.
+- `quickfix` — small, low-risk fixes where formal SDD is likely unnecessary.
+- `plan` — produce a plan or review path before implementation.
+- `build` — implement a planned feature or change.
+- `debug` — investigate and validate a bug or failure.
+- `sdd` — substantial or high-risk work that should follow formal SDD phases.
+
+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]
+```
+
+`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.
+
+`run` records the selected workflow intent and a `workflow-run-planned` checkpoint in the local SQLite store. It selects or validates an agent, stores the run id, and reports any planner recommendation such as SDD escalation. It does not dispatch providers, edit files, write provider config, create subagents, or mutate SDD artifacts.
+
+`execute` is the explicit gated continuation for an existing run. It requires `--run-id` and `--confirm`, verifies the run belongs to the workflow command being executed, resolves the selected agent, checks escalation unless `--override-escalation` is supplied, and records preflight/evidence before any executor can run. The default `safe-non-dispatching` executor records ready-to-dispatch/preflight state only. The `provider` executor is guarded and non-dispatching unless enforceable evidence and adapter gates prove dispatch is safe.
+
+Examples:
+
+```bash
+# Preview a small docs/help fix.
+npm run cli -- 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 \
+  --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 \
+  --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 \
+  --run-id <run-id> \
+  --confirm \
+  --db /tmp/vgxness-debug.sqlite
+```
+
+### Command executor allowlist
+
+Use `--executor command` only for the built-in bounded-process checks. It never accepts shell strings; each command maps to a fixed executable and argv array:
+
+| `--command` | Fixed argv | Timeout | Output cap | Use |
+| --- | --- | ---: | ---: | --- |
+| `typecheck` | `npm run typecheck` | 60s | 256 KiB | Run the project TypeScript typecheck script. |
+| `node-version` | `node --version` | 5s | 8 KiB | Harmless local runtime smoke check. |
+
+```bash
+npm run cli -- quickfix execute \
+  --run-id <run-id> \
+  --confirm \
+  --executor command \
+  --command typecheck \
+  --command-cwd . \
+  --command-targets src/cli/dispatcher.ts,docs/cli.md \
+  --db /tmp/vgxness-workflow.sqlite
+```
+
+Command execution is bounded to the workspace: `--command-cwd` must resolve inside `--workspace` (or the current working directory when `--workspace` is omitted), provider/OpenCode config directories are rejected as cwd or targets, timeouts and output caps are enforced, and the process runs without a shell. It is not a general sandbox: it does not provide filesystem or network isolation beyond the explicit cwd/target validation and fixed command allowlist.
+
+### Workflow approvals CLI
+
+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>]
+```
+
+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.
+
+Command executor approval flow:
+
+```bash
+# 1. Record the workflow run and keep the returned run id.
+npm run cli -- 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 \
+  --run-id <run-id> \
+  --confirm \
+  --executor command \
+  --command node-version \
+  --db /tmp/vgxness-workflow.sqlite
+
+# 3. Inspect the pending approval for that run.
+npm run cli -- approvals list \
+  --run-id <run-id> \
+  --db /tmp/vgxness-workflow.sqlite
+
+# 4. Approve the exact recorded operation.
+npm run cli -- 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 \
+  --run-id <run-id> \
+  --confirm \
+  --executor command \
+  --command node-version \
+  --db /tmp/vgxness-workflow.sqlite
+```
+
+When approval is required, `execute` returns `status:"needs-human"`, `reason:"approval-required"`, and an approval id in the preflight audit. `approvals list --run-id <run-id>` shows pending approvals for that run; omit `--run-id` to list pending approvals across runs in the selected database.
+
+Approval reuse is intentionally narrow. A resolved approval must match the run id, permission category and operation, command input, selected agent, workflow, and related metadata closely enough for the same operation to resume. A different command, run, workflow, or selected-agent context will not reuse the old approval.
+
+To deny an operation, reject the approval instead of approving it:
+
+```bash
+npm run cli -- approvals reject \
+  --id <approval-id> \
+  --reason "not appropriate for this run" \
+  --db /tmp/vgxness-workflow.sqlite
+```
+
+A rejected approval is recorded in the run audit trail and prevents the matching operation from dispatching on retry; create a new run or request a different operation if the decision changes later.
+
+### SDD workflow commands vs formal SDD commands
+
+`sdd preview`, `sdd run`, and `sdd execute` are workflow commands and use the three-mode workflow contract above. `sdd status`, `sdd ready`, `sdd save-artifact`, `sdd get-artifact`, `sdd list-artifacts`, and `sdd next` are formal SDD artifact/status commands. Formal SDD commands read or write SDD artifact state in the selected local SQLite store; they do not execute providers or continue workflow runs.
+
+## MCP setup preview and doctor
+
+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
+```
+
+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 project config automation, inspect `mcp install opencode --plan` before applying with `--yes`.
+
+Doctor prints JSON with `ready` and `checks`. `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
+opencode mcp list
+```
+
+Run both commands from the `vgxness` repo or a directory inside its worktree. The diagnostic reports the current cwd, detected project root, expected project target `.opencode/opencode.json`, optional user target `$HOME/.config/opencode/opencode.json`, whether each target contains `mcp.vgxness`, and whether the project config is inside OpenCode's project-local discovery boundary for the current cwd.
+
+Expected happy path: after OpenCode starts inside `vgxness`, `opencode mcp list` should show `vgxness` with the registered VGXNESS MCP tools exposed by the current build. Treat `SUPPORTED_VGX_MCP_TOOL_NAMES` and `client.listTools()` as the source of truth rather than a fixed count. Restart OpenCode if the server is not listed after project-local config changes.
+
+From a parent directory or another path outside the worktree, the project-local `vgxness` server is not expected to appear. Use `mcp install opencode --scope user --plan` to inspect the user/global target without writing it. OpenCode may load project config with higher precedence than user config for a workspace, so check project config first when both define `mcp.vgxness`.
+
+## OpenCode MCP install
+
+Use the installer when you want `vgxness` registered in OpenCode instead of copying the setup preview by hand. Project scope is the default; user scope is opt-in:
+
+```bash
+npm run cli -- mcp doctor --db <path> --project vgxness --change manual-smoke
+npm run cli -- mcp install opencode --plan --scope project --db <path>
+npm run cli -- mcp install opencode --yes --scope project --db <path>
+npm run cli -- mcp install opencode --plan --scope user
+npm run cli -- mcp install opencode --yes --scope user
+```
+
+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. Project scope plans target only the project config path; user scope requires explicit `--scope user` and targets `$HOME/.config/opencode/opencode.json` only when requested.
+
+The `--yes` flag is required for apply because this path writes OpenCode config. If `--db` and `VGXNESS_DB_PATH` are omitted, the installed server and manual doctor commands omit `--db` and resolve the global default database at runtime. Pass `--db .vgx/memory.sqlite` when you intentionally want the old project-local database, or another explicit path when you need an isolated store preserved in the installed command.
+
+On success, the installer creates or updates exactly one target: project scope writes `<workspace>/.opencode/opencode.json`; user scope writes `$HOME/.config/opencode/opencode.json`. It writes top-level `mcp.vgxness` as an OpenCode local server, preserves unrelated fields and `$schema`, and reports the installed `targetPath`, optional `backupPath`, server command, restart warning, and manual doctor command.
+
+Safety boundaries:
+
+- Project scope is the default. `--scope project` is an explicit alias for the default; `--scope user` is required for `$HOME/.config/opencode/opencode.json`.
+- `--plan` is read-only and `--yes` is the explicit mutating apply path.
+- It refuses to proceed without `--yes`.
+- It refuses ambiguous project targets, missing `HOME` for user scope, malformed JSON, JSONC config, unsupported `mcp` shapes, and existing `mcp.vgxness` by default.
+- Before modifying an existing JSON config, it writes a sibling backup such as `.opencode/opencode.json.backup-20260515T052852123Z` or `$HOME/.config/opencode/opencode.json.backup-20260515T052852123Z`.
+- OpenCode project config may override user config for a workspace; if user-scope install succeeds but `vgxness` is not visible, inspect project `.opencode/opencode.json` first.
+
+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.
+
+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>`.
+3. Inspect `.opencode/opencode.json` and confirm `mcp.vgxness` has `type:"local"`, a `command` array, and `enabled:true`.
+4. Restart OpenCode so it reloads project config.
+5. In OpenCode, confirm the `vgxness` MCP tools are available.
+6. Call `vgxness_sdd_status` against a known project/change, then run doctor again if anything fails.
+
+## SDD workflow examples
+
+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 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
+VGXNESS_DB_PATH=/tmp/vgxness-memory.sqlite npm run cli -- 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 ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` returns the full stored artifact plus metadata; `sdd list-artifacts` returns matching artifacts in canonical SDD phase order.
+
+The SDD CLI is status/persistence only. It does **not** execute providers, continue workflows, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
+
+## Agent resolution
+
+`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
+```
+
+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.
+
+Resolution v1 uses only current registry metadata: capabilities, workflows/phases, adapters, `skills`, task text, mode, and parent constraints. Future orchestration/AI ranking can build on this result, but it is intentionally not part of v1.
+
+## Agent seed loading
+
+Load the checked-in v1 seed 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
+```
+
+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.
+
+Seed loading preserves user-created agents that are absent from the manifest. It only writes to the selected local registry database (`--db`, `VGXNESS_DB_PATH`, or the global default); it does **not** create `.opencode/`, `.claude/`, provider config, or user/global OpenCode configuration.
+
+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
+```
+
+The render command returns preview artifacts only and keeps provider config untouched.
+
+## Skill examples
+
+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
+```
+
+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
+```
+
+`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.
+
+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>
+```
+
+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"
+```
+
+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.
+
+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
+```
+
+`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.
+
+`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
+```
+
+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.
+
+## 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
+```
+
+## JSON definitions
+
+Use `--file` when a definition has permissions, memory, workflows, skills, or adapter config. File input is a complete definition: the CLI rejects mixed definition flags such as `--name`, `--project`, `--instructions`, or `--parent-agent-id` when `--file` is present.
+
+```json
+{
+  "project": "vgxness",
+  "scope": "project",
+  "name": "apply-agent",
+  "description": "Applies focused slices",
+  "instructions": { "kind": "inline", "value": "Follow SDD apply rules." },
+  "permissions": { "read": "allow", "edit": "ask", "shell": "ask" },
+  "memory": { "scopes": ["project"] },
+  "workflows": ["sdd"],
+  "skills": ["sdd-apply"],
+  "adapters": { "opencode": { "model": "openai/gpt-5.5" } }
+}
+```
+
+```bash
+npm run cli -- agents register --file ./agent.json
+npm run cli -- subagents register --file ./subagent.json
+```
+
+For subagents, include `parentAgentId` in the JSON file.
+
+## Render preview
+
+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>
+```
+
+Example response shape:
+
+```json
+{
+  "provider": "json",
+  "installable": false,
+  "artifacts": [
+    {
+      "relativePath": "rendered/json/vgxness/project/apply-agent.agent.json",
+      "contentType": "application/json",
+      "contents": "{...}\n"
+    }
+  ],
+  "warnings": ["Rendering returns preview artifacts only; it does not install or write provider configuration."]
+}
+```
+
+OpenCode preview returns one safe artifact path, not a real config write:
+
+```json
+{
+  "provider": "opencode",
+  "installable": false,
+  "artifacts": [
+    {
+      "relativePath": "rendered/opencode/vgxness/project/apply-agent/opencode.json",
+      "contentType": "application/json",
+      "contents": "{\"$schema\":\"https://opencode.ai/config.json\",\"agent\":{...}}\n"
+    }
+  ]
+}
+```
+
+The preview `opencode.json` includes `$schema` and an `agent` object. Top-level registry agents render as OpenCode `primary`; registered subagents render as `subagent`.
+
+## OpenCode injection preview
+
+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 \
+  --provider opencode \
+  --agent apply-agent \
+  --project vgxness \
+  --change checkout-flow \
+  --phase apply-progress
+```
+
+Required inputs are `--provider opencode`, exactly one of `--agent` or `--agent-id`, `--project`, `--change`, and `--phase`. Add `--scope personal` only when selecting a personal-scope agent; otherwise project scope is used.
+
+The command prints only the preview envelope JSON on success:
+
+```json
+{
+  "version": 1,
+  "provider": "opencode",
+  "installable": false,
+  "readOnly": true,
+  "context": {
+    "project": "vgxness",
+    "change": "checkout-flow",
+    "workflow": "sdd",
+    "phase": "apply-progress",
+    "provider": "opencode",
+    "agent": { "id": "...", "name": "apply-agent", "scope": "project", "mode": "agent" }
+  },
+  "providerArtifacts": { "provider": "opencode", "installable": false, "artifacts": [] },
+  "skillPayload": { "version": 1, "providerAgnostic": true, "items": [] },
+  "sdd": { "status": {}, "readiness": {} },
+  "safety": {
+    "installable": false,
+    "readOnly": true,
+    "executesProvider": false,
+    "writesProviderConfig": false,
+    "recordsRuns": false,
+    "recordsSkillUsage": false
+  },
+  "warnings": ["OpenCode injection preview is preview-only and installable=false."]
+}
+```
+
+Validation failures are deterministic and print `validation_failed: ...` to stderr with no partial JSON envelope. Unsupported providers fail; this command currently supports only `--provider opencode`.
+
+The boundary is intentionally strict: the preview composes the existing OpenCode render artifact, skill payload, and SDD status/readiness so future MCP or hook wiring has a stable contract. It is not live injection yet.
+
+## 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
+```
+
+## Run examples
+
+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
+```
+
+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.
+
+`runs permission-check` evaluates the same core permission policy as `permissions check`, records a `permission-decision` event on the run timeline, and returns the decision plus event. When the decision is `ask`, it also creates a pending approval record linked to that decision event. `allow` and `deny` decisions do not create approvals.
+
+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"
+```
+
+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.
+
+`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"]}'
+```
+
+Example blocked response:
+
+```json
+{
+  "approvalId": "...",
+  "runId": "...",
+  "decision": "blocked",
+  "allowed": false,
+  "reasonCode": "retry_disabled",
+  "reason": "Retry blocked by policy never after failed",
+  "policy": { "mode": "never" },
+  "retryableStatuses": [],
+  "evaluatedAttemptCount": 1,
+  "executorInvoked": false,
+  "operationExecuted": false
+}
+```
+
+Policy input is strict JSON. Current policy modes are `never`, `after-abandoned`, `after-failure`, and `after-failure-or-abandoned`; active `reserved` attempts and already `succeeded` attempts are never retryable.
+
+### Read-only resume inspection
+
+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>
+```
+
+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:
+
+```json
+{
+  "safety": {
+    "executableResume": false,
+    "executorInvoked": false,
+    "operationExecuted": false,
+    "writesProviderConfig": false,
+    "createsSandbox": false,
+    "createsWorktree": false
+  }
+}
+```
+
+Manual next-command examples include `vgxness runs get --id <run-id>`, `vgxness runs timeline --id <run-id>`, `vgxness runs debug --id <run-id>`, `vgxness runs resume-plan --id <run-id>`, `vgxness runs approvals --run <run-id>`, and `vgxness runs retry-check --approval <approval-id>`. The inspect command does not run those commands for you.
+
+This flow is inspection only. It does **not** execute provider work, run preflight, admit retry attempts, write provider config, create sandboxes, create worktrees, or expose a CLI resume command.
+
+### Read-only resume gate
+
+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"]}'
+```
+
+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.
+- 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.
+
+If a reservation gets stuck, code can call `RunService.abandonReservedOperationAttempt({ attemptId, actor, reason })`. This records `abandoned` plus an audit event and does not execute, retry, or invoke any executor. There is no CLI resume, abandon, or retry command yet because the CLI has no safe default executor or operator flow.
+
+Code can also call `RunService.admitOperationRetryAttempt({ approvalId, policy, executorName })` to reserve retry metadata only after explicit policy evaluation allows the latest terminal attempt. This is **not** retry execution: it appends audit metadata with `executorInvoked: false` and `operationExecuted: false`, and it does not call a shell, filesystem, network, provider, or executor. CLI mutation for retry admission is intentionally deferred until the operator UX clearly separates reservation from actual execution.
+
+The runtime service has an enforcement gate for operation attempts, but there is intentionally no CLI command for real execution yet. Denied and approval-required operations are blocked before executor invocation, and allowed or approved-resumed operations require an injected fake/test/sandbox executor from code.
+
+## Permission check examples
+
+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
+```
+
+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.
+
+## Storage
+
+By default, vgxness uses a global user data database and creates the parent directory when needed:
+
+| Platform | Global default |
+|---|---|
+| macOS | `~/Library/Application Support/vgxness/memory.sqlite` |
+| Linux | `${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite` |
+| Windows | `%APPDATA%\\vgxness\\memory.sqlite` |
+
+Selection precedence is `--db <path>` (selected source: `flag`) > `VGXNESS_DB_PATH` (selected source: `environment`) > global default (selected source: `global-default`). The resolver fails clearly if no user data base directory is available instead of falling back to the current working directory.
+
+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
+```
+
+Existing project-local stores remain compatible; opt in explicitly when needed:
+
+```bash
+npm run cli -- memory search --project vgxness --db .vgx/memory.sqlite
+```