vgxness 1.5.0 → 1.5.2

package/docs/contributing.md

@@ -0,0 +1,120 @@
+# Contributing
+
+VGXNESS is an alpha local-first control plane. The repository follows a few rules that keep the product safe, predictable, and reviewable. This document is for humans and AI assistants who want to change the code, the docs, or both.
+
+## Repository layout
+
+```
+src/
+  agents/         # agent + subagent registry, resolver, canonical manifest
+  cli/            # CLI dispatch, command modules, TUI, OpenTUI
+  code/           # native code runtime (vgxness code)
+  export/         # redaction and export helpers
+  governance/     # governance report builder, overlay fingerprint
+  harness/        # harness-side tool handlers
+  mcp/            # MCP server, schemas, control plane, doctor, OpenCode install
+  memory/         # memory service, SQLite database, migrations
+  orchestrator/   # natural-language planner (preview only)
+  payload/        # payload summary helpers
+  permissions/    # policy evaluator, schemas
+  providers/      # OpenCode provider adapter
+  runs/           # run lifecycle, execution planning, retry, snapshot export
+  sdd/            # SDD workflow service, schema, artifact portability
+  setup/          # setup defaults, plan, lifecycle, backup-rollback
+  skills/         # skill registry, resolver, payload, improvement proposals
+  verification/   # verification plan + report services
+  workflows/      # workflow registry, executor, allowlist adapter
+
+test/             # node:test files mirroring src/ structure
+seeds/            # shipped skill/agent seed assets
+scripts/          # repo-level helper scripts
+docs/             # human-facing documentation
+```
+
+## Runtime and toolchain
+
+- Bun `>= 1.3.14` is the installed CLI/MCP runtime and the canonical CI verification path. It is also the only supported storage runtime (`bun:sqlite`).
+- Node.js `>= 22` is development/build/test tooling for TypeScript, `node:test`, and selected helper scripts.
+- TypeScript is ESM/NodeNext and strict, with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. Prefer explicit `undefined` over loose optional properties.
+- Tests use the built-in `node:test` runner with `node:assert/strict`, not Jest/Vitest.
+
+Install dependencies with `bun install --frozen-lockfile` when reproducing CI. When `package.json` dependency specifiers change, refresh and review `bun.lock` intentionally. Use `bun run check:bun-lock` to detect drift without mutating `node_modules`.
+
+## Verification order
+
+CI runs the verification chain in this order:
+
+```bash
+bun install --frozen-lockfile
+bun run check:bun-lock
+bun run verify:typecheck
+bun run verify:test
+bun run verify:test:bun-storage
+bun run verify:bun-sqlite
+bun run verify:package       # which is bun run package:bun:evidence
+bun run package:bun:evidence -- --require-pass
+```
+
+The full chain is wrapped in `bun run verify`. For release-readiness, the package evidence run must pass explicitly with `--require-pass`.
+
+`bun run verify:bun-sqlite` is the SQLite runtime release gate. It copies the source migrations into a temporary directory, applies them against a temporary database, and checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup.
+
+## Product boundaries
+
+VGXNESS is a local-first CLI/MCP control plane. The same domain services should back CLI, TUI, and MCP. Avoid reimplementing workflow, setup, or storage rules in only one surface.
+
+The configurator/setup plane (rendering/installing provider config) is separate from the runtime control plane (executing SDD phases, recording runs, gating approvals). They are wired by services, not by side effects.
+
+## Safety conventions
+
+These rules are non-negotiable. The harness is loaded with capability; do not remove these guards.
+
+- Read-only/preview commands must stay non-mutating. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views must not write provider config or call providers.
+- Provider config writes require explicit consent (`--yes` or equivalent confirmed flow) plus backup/rollback behavior.
+- Do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys `sdd/{change}/{phase}`.
+- Human acceptance is distinct from artifact presence. Do not infer acceptance from generated content or saved drafts. The runtime rejects `acceptedBy.type !== 'human'`.
+- Workspace boundary denials cannot be relaxed by agent or subagent overrides. The policy evaluator uses `realpathSync` to defeat symlink escapes.
+- Secrets and external directory access deny by default. Redaction helpers in `src/code/reporting/redaction.ts` and `src/export/redaction.ts` are the only place secret-shaped values should be stripped.
+
+## Style
+
+- TypeScript strict, ESM/NodeNext, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`.
+- Prefer explicit `undefined` over loose optional properties. Use the existing `MemoryResult<T>` / `MemoryResult<...>` style for fallible operations instead of throwing across module boundaries.
+- Domain entities live in their module's `schema.ts`. Tool-facing payloads live in `src/mcp/schema.ts` (or a sibling) and are validated with `zod` before dispatch.
+- Tests are colocated by module under `test/`. Use `node:test` and `node:assert/strict`. Each test file should set up its own `MemoryDatabase` (see existing files for the pattern).
+- Public CLI/setup language is English unless existing docs explicitly say otherwise.
+
+## Doc-sync discipline
+
+The docs are the user-facing contract. When the code drifts, the docs must catch up — not the other way around.
+
+- When you add, rename, or remove an MCP tool, update `SUPPORTED_VGX_MCP_TOOL_NAMES` in `src/mcp/schema.ts` and the table in [MCP tools](./mcp.md). They must stay in sync.
+- When you add a new CLI command, document it in [CLI reference](./cli.md).
+- When you change a permission category, default, or phase mode, update [Safety model](./safety.md).
+- When you add a migration, append it to the table in [Storage](./storage.md).
+- When you add or change a provider, update [Providers](./providers.md) and the [Code runtime](./code-runtime.md) tool list.
+
+## Pull request process
+
+VGXNESS is shipped as a proprietary package. The npm publication step is a separate, explicit, human-approved process. PRs that change published artifacts must:
+
+1. Run `bun run verify` locally and confirm all steps pass.
+2. Include or update tests for any behavioral change.
+3. Update docs that reference the changed surface.
+4. Not change the publication path. `npm publish`, `bun publish`, registry dry-runs, provenance upload, release creation, and dist-tag mutation are not part of normal PR flow.
+5. Not change `engines.bun` or remove the `bin`/`files` whitelist without a separate, documented decision.
+
+PRs that touch safety gates, permission categories, default policies, the run lifecycle, or the SDD acceptance gate are reviewed by a maintainer who can answer "does this still match the safety model?" without consulting the diff. If you are unsure, open the PR as a draft and ask.
+
+## Commit conventions
+
+- Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, `build:`, `ci:`).
+- No `Co-Authored-By` lines for AI assistants. Do not add AI attribution to commits.
+- One logical change per commit. Squash fixups locally before pushing.
+
+## AI assistants in this repo
+
+`AGENTS.md` at the repository root carries the working instructions for AI assistants. The two non-negotiables are:
+
+- Do not write to `openspec/`.
+- Do not infer SDD acceptance from generated content. The runtime will reject it, but the rejection costs a run.

package/docs/glossary.md

@@ -0,0 +1,211 @@
+# Glossary
+
+Terms used across the VGXNESS docs and codebase. The product surface is small enough that most of these are first-class concepts in `src/` rather than incidental vocabulary.
+
+## Acceptance
+
+A human-only action that records explicit approval of a SDD phase artifact. `vgxness_sdd_accept_artifact` requires `acceptedBy.type === 'human'`; the runtime rejects agent or anonymous acceptance. Acceptance is distinct from artifact presence — saving a draft never implies acceptance.
+
+## Adapter
+
+A translator between VGXNESS's provider-neutral domain and a specific provider. The control plane uses renderers (OpenCode, JSON, Claude preview). The code runtime uses `CodeProviderAdapter` implementations (`openai-compatible`, `fake`).
+
+## Agent
+
+A provider-neutral definition of who executes work. Carries role, instructions, capabilities, model preference, permissions, and compatible workflows. Subagents are specialized agents intended for delegated, scoped work with constrained tools.
+
+## Approval record
+
+A first-class record linked to a permission-decision event. Created when a permission request resolves to `ask`; resolved once as `approved`, `rejected`, or `cancelled` with actor, reason, and timestamp. Approvals drive `resumeApprovedOperation(...)`.
+
+## Attempt
+
+A reserved operation execution linked to an approval. Attempts transition through `reserved` → `succeeded` | `failed` | `abandoned`. Multiple ordered attempts are allowed per approval, but only one is `reserved` at a time.
+
+## Blockers (SDD cockpit)
+
+Aggregated reasons a SDD phase is not ready. Kinds: `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. Surfaced through `vgxness_sdd_cockpit`.
+
+## Bun
+
+The canonical installed CLI/MCP runtime and verification path. Required `>= 1.3.14`. The only supported storage runtime (via `bun:sqlite`).
+
+## Canonical agent manifest
+
+The built-in, validated manifest that defines the manager agent and the SDD subagents (`vgxness-sdd-explore`, `vgxness-sdd-propose`, `vgxness-sdd-spec`, `vgxness-sdd-design`, `vgxness-sdd-tasks`, `vgxness-sdd-apply`, `vgxness-sdd-verify`, `vgxness-sdd-archive`, plus `init` and `onboard`). Lives in `src/agents/canonical-agent-manifest.ts`. `promptContractVersion` increments on breaking contract changes.
+
+## Change (SDD)
+
+The unit of SDD work. Identified by a project-scoped `change` id. Artifacts are stored under canonical topic keys `sdd/{change}/{phase}`.
+
+## Checkpoint
+
+A labeled, ordered JSON blob attached to a run that lets work resume. Append through `vgxness_run_checkpoint`. Checkpoints are part of the run; they are not the same as memory observations.
+
+## Cockpit
+
+A read-only SDD aggregate view. `vgxness_sdd_cockpit` returns per-phase status, blockers, and a recommended next action. The TUI should eventually mirror this surface.
+
+## Code runtime
+
+The native workspace runtime exposed through `vgxness code` (`inspect` / `plan` / `craft-preview` / `craft` / `sdd`). Provider-neutral; speaks to any OpenAI-compatible endpoint through `openai-compatible-provider-adapter.ts`.
+
+## Configurator plane
+
+The part of VGXNESS that renders provider-specific artifacts (OpenCode config, agent JSON) without mutating the registry. Separate from the runtime control plane.
+
+## Control plane
+
+The part of VGXNESS that owns workflow state, runs, approvals, checkpoints, and audit evidence. Exposed through CLI, TUI, and MCP.
+
+## Decision
+
+A permission resolution: `allow`, `ask`, or `deny`. For SDD-phase gating the matrix uses four modes: `allow`, `audit`, `require-preflight`, `deny`.
+
+## Dry-run
+
+A read-only preview. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views are dry-runs by contract — they must not write provider config or call providers.
+
+## Eval target
+
+A testable property of the harness. The 11 eval targets live in [Architecture](./architecture.md) and are covered by `node:test` files under `test/`.
+
+## Execution isolation plan
+
+A planned strategy for executing a reserved operation: `workspace`, `git-worktree`, or `process-sandbox`. Produced by `planExecutionIsolation(...)`. The actual executor is still test-only in v1.5.1.
+
+## Governance report
+
+A redacted, structured report over SDD state, runs, and approvals. Surfaced through `vgxness_governance_report`. Useful for review before promotion.
+
+## MCP
+
+Model Context Protocol. The agent-facing transport. VGXNESS exposes 38 typed tools over stdio through `vgxness mcp start`. The tool list lives in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`) and is documented in [MCP tools](./mcp.md).
+
+## Memory observation
+
+A durable record in the SQLite store. Identified by `id`; upserted by `topicKey`. Types: `architecture`, `decision`, `bugfix`, `pattern`, `config`, `discovery`, `learning`, `preference`, `manual`. Project or personal scope.
+
+## Natural-language planner
+
+The provider-agnostic front-door classifier for operator text. Maps an intent to exactly one preview flow: `direct`, `plan`, `sdd`, or `diagnose`. Non-executing by design.
+
+## OpenCode
+
+The primary supported provider for the control plane. The configurator renders OpenCode MCP config and manager/SDD agent definitions. Claude Code is preview/manual only.
+
+## Operation attempt
+
+See **Attempt**.
+
+## Payload mode
+
+A knob that controls how much context a payload returns. `compact` (default for the manager) keeps tokens bounded; `verbose` returns the full content. Applies to `vgxness_agent_activate`, `vgxness_skill_payload`, `vgxness_sdd_get_artifact`, `vgxness_sdd_list_artifacts`, `vgxness_governance_report`.
+
+## Pending approval
+
+An approval record that has not been resolved yet. Created when a permission request resolves to `ask`. Visible in the run details.
+
+## Permission
+
+A category of action. Categories: `read`, `edit`, `implementation-edit`, `spec-write`, `design-write`, `task-write`, `shell`, `test-run`, `install`, `network`, `git`, `git-write`, `memory`, `memory-write`, `external-directory`, `provider-tool`, `secrets`. See [Safety model](./safety.md).
+
+## Phase (SDD)
+
+A canonical stage in the SDD lifecycle: `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, `archive`. Each phase has prerequisites and an acceptance requirement.
+
+## Policy evaluator
+
+The function that resolves a permission request. Returns `allow`, `ask`, or `deny` with a reason. Conservative defaults; workspace boundary denials cannot be relaxed by agent overrides.
+
+## Preflight
+
+A permission decision plus execution isolation plan produced before a reserved operation. `vgxness_run_preflight` may create a pending approval when the decision is `ask`.
+
+## Project (scope)
+
+One of two memory scopes. `project` is repo-specific; `personal` is user-global. Scopes live in the same database, separated by columns.
+
+## Provider adapter
+
+See **Adapter**.
+
+## Readiness
+
+Whether a SDD phase can advance. Combines prerequisite artifacts, human acceptance of prerequisites, and aggregate blockers. Surfaced through `vgxness_sdd_ready`, `vgxness_sdd_get_readiness`, and `vgxness_sdd_cockpit`.
+
+## Redaction
+
+Stripping secret-shaped values before they leave the runtime. `redactSecrets`, `redactJson`, and `omitSensitiveCommandOutput` live in `src/code/reporting/redaction.ts` and `src/export/redaction.ts`.
+
+## Reserved attempt
+
+An operation attempt in the `reserved` state. Exclusive per approval. Finalized to `succeeded` or `failed` after the executor returns; recovery-only `abandoned` for stuck attempts.
+
+## Retry policy
+
+The policy that decides whether a new attempt is allowed after a prior one. `never`, `after-abandoned`, `after-failure`, `after-failure-or-abandoned`. Default is `never`. Evaluated by `vgxness_run_resume_gate`.
+
+## Run
+
+The auditable unit of execution. Has 8 statuses: `created`, `planned`, `running`, `needs-human`, `completed`, `failed`, `blocked`, `cancelled`. Carries events, checkpoints, approvals, and operation attempts.
+
+## Run snapshot export
+
+A versioned JSON package containing the full run, its events, checkpoints, approvals, and attempts. Useful for review and debugging. `RunSnapshotPackageV1`.
+
+## Scope
+
+`project` or `personal`. Memory, agents, skills, and manager profile overlays all carry a scope.
+
+## SDD
+
+Spec-Driven Development. The canonical workflow `explore → proposal → spec → design → tasks → apply-progress → verify → archive`. See [PRD](./prd.md) for the principles and [Architecture](./architecture.md) for the engine.
+
+## Session
+
+A scoped record of work in progress. Started with `vgxness_session_start`, appended to with `vgxness_session_append_activity`, closed with `vgxness_session_close`. The latest restorable session is read through `vgxness_session_restore` or, more reliably, `vgxness_context_cockpit`.
+
+## Skill
+
+A versioned, reusable knowledge/procedure that can be attached to an agent, workflow, phase, or provider adapter. Skill improvement proposals must be approved by a human before activation.
+
+## Skill improvement proposal
+
+A reviewable, versioned change to a skill. Goes through `draft` → `submitted` → `approved`/`rejected`/`cancelled` → `applied`. Only `approved` proposals can be applied.
+
+## SddCockpitBlocker
+
+A typed blocker surfaced by the SDD cockpit. Kinds: `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. See [Safety model](./safety.md) and [Architecture](./architecture.md).
+
+## SddPrerequisiteBlocker
+
+A typed blocker for a missing or unaccepted prerequisite phase. Reasons: `missing`, `draft`, `legacy`, `rejected`, `superseded`.
+
+## Subagent
+
+See **Agent**.
+
+## Topic key
+
+The durable upsert key for memory observations and SDD artifacts. For SDD, the canonical form is `sdd/{change}/{phase}`.
+
+## Trace event
+
+A structured event in a run's timeline. Kinds: `timeline`, `evidence`, `memory-operation`, `artifact-reference`, `tool-call`, `permission-decision`, `execution-plan`, `operation-execution`, `approval`, `verification`.
+
+## TUI
+
+Terminal UI. OpenTUI (`@opentui/core`) is the framework for the main menu and setup screens.
+
+## Verification plan
+
+A recommended set of verification steps for a change type. `vgxness_verification_plan` takes a `changeType` (`docs-only`, `test-only`, `cli`, `mcp`, `sdd-storage`, `provider-setup`, `package-release`, `workflow-runs`) and returns the recommended plan.
+
+## Worktree (planned)
+
+A planned execution isolation strategy. `git-worktree` plans produce a plan to mutate inside an isolated worktree; the actual worktree creation is follow-up.
+
+## Workspace boundary
+
+The set of paths inside `workspaceRoot`. The policy evaluator uses `realpathSync` to defeat symlink escapes and refuses to relax boundary denials.

package/docs/mcp.md

@@ -0,0 +1,144 @@
+# MCP tools
+
+VGXNESS exposes 38 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
+
+Tools are exposed under the `vgxness_*` prefix. Some MCP hosts strip the prefix and accept the short form (`sdd_status`, `memory_save`, etc.). The schema accepts both.
+
+All tools:
+
+- Are read-only or auditable on the VGXNESS side. The only state-mutating tools are the ones explicitly named `*_save`, `*_update`, `*_start`, `*_checkpoint`, `*_finalize`, `*_accept_artifact`, `*_set`, `*_append_activity`, `*_close`, `*_record_*`.
+- Validate input with `zod` before dispatching to the service layer.
+- Return either a typed result or a `VgxMcpError` with a `code` and `message`.
+- Do not require the agent to import or instantiate anything; pass JSON, get JSON.
+
+## SDD workflow (10)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_sdd_status` | Report per-phase artifact presence and the next ready missing phase. | `project`, `change` | |
+| `vgxness_sdd_next` | Recommend the next phase decision for a change. | `project`, `change` | |
+| `vgxness_sdd_ready` | Check whether a specific phase is ready. | `project`, `change`, `phase`; optional `runId`, `agentId` | Returns structured `SddReadiness` with `blockedPrerequisites`. |
+| `vgxness_sdd_get_readiness` | Same as `ready` with explicit output shape. | same as `ready` | |
+| `vgxness_sdd_save_artifact` | Persist phase content under canonical topic key `sdd/{change}/{phase}`. | `project`, `change`, `phase`, `content` | Saving does not imply acceptance. |
+| `vgxness_sdd_accept_artifact` | Record explicit human acceptance for a phase. | `project`, `change`, `phase`, `acceptedBy` (`{type:"human", id, displayName?}`); optional `acceptedAt`, `note`, `notes`, `rationale`, `runId`, `agentId` | `acceptedBy.type` must be `"human"`. Runtime rejects agent or anonymous acceptance. |
+| `vgxness_sdd_get_artifact` | Read one full artifact. | `project`, `change`, `phase`; optional `payloadMode` (`compact`/`verbose`) | |
+| `vgxness_sdd_list_artifacts` | List all artifacts for a change in canonical phase order. | `project`, `change`; optional `payloadMode` | |
+| `vgxness_sdd_cockpit` | Aggregate per-phase status, blockers, and recommended next action. | `project`, `change` | Returns `SddCockpit` with `aggregateBlockers` of kinds `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. |
+| `vgxness_governance_report` | Build a redacted governance report for a project/change/run. | `project`; optional `change`, `runId`, `workflow`, `phase`, `agentId`, `agent` (with `id`, `name`, `mode`, `scope`), `payloadMode` | See [Safety model](./safety.md) for redaction rules. |
+
+## Memory (4)
+
+| Tool | Purpose | Required inputs |
+|---|---|---|
+| `vgxness_memory_save` | Upsert memory observation. | `project`, `type` (`architecture`/`decision`/`bugfix`/`pattern`/`config`/`discovery`/`learning`/`preference`/`manual`), `title`, `content`; optional `scope` (`project`/`personal`), `topicKey` |
+| `vgxness_memory_search` | FTS5 search over memory. | `limit` (1–100); optional `project`, `scope`, `type`, `topicKey`, `query` |
+| `vgxness_memory_get` | Read one observation by id. | `id` |
+| `vgxness_memory_update` | Patch an existing observation. | `id`; optional `type`, `title`, `content`, `topicKey` |
+
+`topicKey` is the durable upsert key: re-saving with the same key updates the existing observation rather than creating a duplicate.
+
+## Sessions (5)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_session_start` | Begin a session record. | `project`; optional `id`, `directory` | If `id` is omitted, the runtime generates one. |
+| `vgxness_session_append_activity` | Append a structured event to a session. | `sessionId`, `actor`, `kind` (`prompt`/`tool_call`/`artifact`/`summary`/`error`), `payloadJson` | `payloadJson` is a stringified JSON value, validated before append. |
+| `vgxness_session_close` | Close a session with a summary. | `sessionId`, `actor`, `summary` (non-empty, trimmed) | |
+| `vgxness_session_restore` | Read the latest restorable session for a project/directory. | `project`; optional `directory` | One signal — not authoritative. Prefer `vgxness_context_cockpit`. |
+| `vgxness_context_cockpit` | Read-only cockpit: recent sessions, bounded memory previews, last restorable session. | `project`; optional `directory`, `limit` | Does not trace, mutate state, run preflight, or write provider config. |
+
+## Agents, profile, skills (5)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_agent_resolve` | Rank registered agents/subagents for a task. | `project`, `scope?`, `taskDescription` or `intent`; optional `desiredCapabilities`, `workflow`, `phase`, `providerAdapter`, `mode` (`agent`/`subagent`) | Deterministic rule-based ranking. No model call. |
+| `vgxness_agent_activate` | Build an activation envelope for the resolved agent. | `project`, `agentId` or `name`; optional `scope`, `workflow`, `phase`, `providerAdapter`, `mode`, `workspaceRoot`, `maxSourceBytes`, `payloadMode` | Default `payloadMode` is `compact`. |
+| `vgxness_manager_profile_get` | Read the manager profile overlay. | `project`; optional `scope`, `managerName` | |
+| `vgxness_manager_profile_set` | Upsert a manager profile overlay. | input shape from `SaveManagerProfileOverlayInput` | Requires explicit human authorization in the harness prompt. |
+| `vgxness_skill_payload` | Resolve and build a provider-agnostic skill injection payload. | `agentId`/`name`+`project`+`scope`, `workflow`, `phase`, `providerAdapter`; `workspaceRoot`; optional `maxSourceBytes`, `mode` | `mode` defaults to `compact`. See [Code runtime](./code-runtime.md) for how the runtime consumes this. |
+
+## OpenCode preview (2)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_opencode_manager_payload` | Build the OpenCode manager payload envelope. | `OpenCodeManagerPayloadInput` shape (project, scope, agent, workflow/phase, workspaceRoot, maxSourceBytes, payloadMode) | `installable: false`, `readOnly: true`. |
+| `vgxness_opencode_handoff_preview` | Compose a full handoff preview: provider artifacts + skill diagnostics + SDD status + provider status + safety flags. | `project`; optional `scope`, `agentId`, `agentName`, `workspaceRoot`, `maxSourceBytes`, `change`, `phase` | Read-only preview. Does not execute OpenCode, install hooks, or write provider config. |
+
+## Runs (8)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_run_list` | List runs with filters. | `limit`; optional `project`, `status` (one of the 8 `RunStatus` values) | |
+| `vgxness_run_get` | Read a run with `events`, `checkpoints`, `approvals`, `operationAttempts`. | `id` | |
+| `vgxness_run_start` | Create a run record. | `CreateRunInput` shape | |
+| `vgxness_run_checkpoint` | Append a resumable JSON state. | `AppendRunCheckpointInput` shape | |
+| `vgxness_run_finalize` | Finalize a run with `outcome` and `outcomeReason`. | `FinalizeRunInput` shape | `outcome` must match a terminal `status`. Re-finalization is rejected. |
+| `vgxness_run_preflight` | Run policy evaluation and return the decision + planned execution isolation strategy. | `PreflightRunOperationInput` shape | May create a pending approval when the decision is `ask`. Does not invoke an executor. |
+| `vgxness_run_resume_inspect` | Plan-only resume advisory. | `runId` | Returns `RunResumeOrchestrationPlan` with blockers and `nextAction` (`resolve-approval`/`inspect-run`/`retry-check`/`manual-recovery`/`no-action`). |
+| `vgxness_run_resume_gate` | Evaluate retry policy for an approval without executing. | `approvalId`; optional `policy` | Default policy is `never`. See [Safety model](./safety.md) for the policy table. |
+
+Run `status` accepts the full 8-state vocabulary: `created`, `planned`, `running`, `needs-human`, `completed`, `failed`, `blocked`, `cancelled`. `outcome` is one of `success`, `partial`, `failure`, `blocked`, `cancelled`.
+
+## Providers (3)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_provider_status` | Report provider health for a project/scope. | `ProviderHealthInput` shape (project, scope, workspaceRoot, providerAdapter) | Read-only. |
+| `vgxness_provider_doctor` | Run provider health checks with structured JSON output. | same as `status` | |
+| `vgxness_provider_change_plan` | Compose a read-only provider config change plan. | `ProviderChangePlanInput` shape (`provider`: `opencode`/`claude`/`antigravity`/`custom`; `changeType`: `opencode-mcp-install`/`setup`/`install`/`config-preparation`; `workspaceRoot`; `payloadMode`) | Does not write provider config. See [Providers](./providers.md). |
+
+## Verification (1)
+
+| Tool | Purpose | Required inputs |
+|---|---|---|
+| `vgxness_verification_plan` | Recommend a verification plan for a change type. | `changeType` (`docs-only`/`test-only`/`cli`/`mcp`/`sdd-storage`/`provider-setup`/`package-release`/`workflow-runs`) |
+
+## Usage patterns
+
+Starting, resuming, and ending a session:
+
+```text
+vgxness_session_start           { project: "vgxness", directory: "/path" }
+vgxness_session_append_activity { sessionId, actor, kind, payloadJson }
+vgxness_session_close           { sessionId, actor, summary }
+```
+
+Inspecting SDD before doing any work:
+
+```text
+vgxness_sdd_cockpit    { project: "vgxness", change: "new-flow" }
+vgxness_sdd_get_readiness { project: "vgxness", change: "new-flow", phase: "proposal" }
+```
+
+The cockpit returns `aggregateBlockers`; if any are `unaccepted-phase`, the agent should not run the next phase until a human accepts the prerequisite.
+
+Recording a phase with explicit human acceptance:
+
+```text
+vgxness_sdd_save_artifact    { project, change, phase: "proposal", content: "..." }
+# human opens the harness and runs:
+vgxness_sdd_accept_artifact  { project, change, phase: "proposal", acceptedBy: { type: "human", id: "uziel" }, rationale: "Reviewed proposal." }
+```
+
+Running a planned operation:
+
+```text
+vgxness_run_start       { project, userIntent, workflow: "sdd", phase: "apply-progress", selectedAgentId, providerAdapter, model }
+vgxness_run_preflight   { runId, category: "edit", operation: "apply_patch", workspaceRoot, targetPath, payload }
+# if decision is "ask", wait for human approval; on approval, the harness resumes via run_resume_inspect + run_resume_gate.
+vgxness_run_checkpoint  { runId, label: "after-step-1", state: {...} }
+vgxness_run_finalize    { runId, outcome: "success", outcomeReason: "..." }
+```
+
+## Safety boundary
+
+MCP tools do not:
+
+- Write provider config (`.opencode/`, `.claude/`, `opencode.json`, `CLAUDE.md`).
+- Execute providers (`opencode`, `claude`, etc.).
+- Install global memory.
+- Create `openspec/`.
+- Bypass permission policy.
+- Mutate other tools' state outside the VGXNESS SQLite store.
+
+Tools that would normally mutate external state (provider install, shell, network) are split into a plan/preview step and an explicit `apply` step. The apply step requires an MCP-side `apply` flag or a separate `vgxness` CLI command (e.g. `vgxness setup apply --yes`).

package/docs/prd.md

@@ -128,18 +128,7 @@ Minimum MCP capabilities:
 
 Candidate MCP tools:
 
-```text
-vgxness_sdd_status
-vgxness_sdd_next
-vgxness_sdd_ready
-vgxness_sdd_save_artifact
-vgxness_run_start
-vgxness_run_checkpoint
-vgxness_run_request_approval
-vgxness_agent_resolve
-vgxness_skill_payload
-vgxness_profile_get
-```
+The current MCP surface covers SDD status and artifacts, memory read/write, sessions, agent resolution and activation, skill payload, OpenCode manager payload, run lifecycle (start, list, get, preflight, checkpoint, finalize, resume inspect, resume gate), provider status/doctor/change-plan, verification plan, governance report, and context cockpit. The full, current list lives in [MCP tools](./mcp.md) and in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth.
 
 #### CLI
 
@@ -213,8 +202,8 @@ The same flow must be available through CLI flags for automation and CI-friendly
 
 Initial integration targets:
 
-- OpenCode
-- Claude Code
+- OpenCode — primary supported provider. The configurator plane renders OpenCode MCP config and manager/SDD agent definitions; the code runtime speaks to any OpenAI-compatible endpoint, including OpenCode's local bridge.
+- Claude Code — preview/manual only as of v1.5.1. The canonical agent manifest declares Claude support as `preview` with an explicit reason: VGXNESS does not install Claude or write `.claude/` or `CLAUDE.md`. Owners of Claude-only workflows must run setup themselves.
 
 Pi/`gentle-pi` is a design reference and future adapter target, not part of the first integration target list unless the MVP scope is explicitly expanded.
 
@@ -358,15 +347,23 @@ The MVP is successful when an advanced individual developer can:
 
 ## Open questions
 
-- What is the first integration adapter: OpenCode or Claude Code?
-- Should memory storage be per-repo by default, with global memory in a user-level directory?
-- What config format should define agents/subagents?
-- What config format should define skills and skill versions?
-- Which skill improvement proposals should require approval versus automatic rejection?
-- Which commands form the first public CLI surface?
-- Which TUI framework should be used for the first implementation?
-- Should the MCP server run only over stdio for MVP, or also support local HTTP later?
-- What is the safest default install command and update channel?
-- What privacy/export guarantees are required before public release?
-- What is the first sandbox strategy: normal workspace, git worktree, or process/container isolation?
-- What trace format should be used for local inspection and future cloud sync?
+Many of the early PRD questions are resolved in v1.5.1. Tracking them here keeps the historical record.
+
+| Question | Resolved as of v1.5.1 |
+|---|---|
+| First integration adapter | OpenCode primary; Claude is preview/manual. |
+| Memory storage scopes | Project memory and personal/global memory live in separate SQLite stores; `--db` flag and `VGXNESS_DB_PATH` env var override. |
+| Agent config format | Provider-neutral schema in `src/agents/schema.ts`; canonical manifest with validation in `src/agents/canonical-agent-manifest.ts`. |
+| Skill config format | Versioned skills with source metadata (`path`/`url`/`inline`); active version gating in `src/skills/skill-registry-service.ts`. |
+| Skill improvement approval | All proposals require explicit human approval before activation; rejected/cancelled proposals cannot be applied. |
+| First public CLI surface | `vgxness {init, setup, doctor, mcp, sdd, agents, skills, memory, runs, code, opencode}`. See [CLI reference](./cli.md). |
+| First TUI framework | OpenTUI (`@opentui/core`) for the main menu and setup screens; legacy tui-kit screens still in tree for backwards compatibility. |
+| MCP transport | Local stdio for MVP; HTTP deferred. |
+| Default install command | `npm install -g vgxness` ships both `vgxness` and `vgx` bins; Bun 1.3.14+ is the canonical installed runtime. |
+| Sandbox strategy | Planning-only in v1.5.1 (`src/runs/sandbox-worktree-planning.ts`); real sandbox/worktree execution is follow-up. Approval-gated edits/shell happen through the code runtime's executors. |
+
+Still open:
+
+- Privacy/export guarantees required before public release (depends on release scope).
+- Distributed multi-worker execution model (post-MVP).
+- Web/hosted console surface (post-MVP).