vgxness 1.5.1 → 1.6.0

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/install planners (OpenCode, JSON, Claude project-local support). 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/default supported provider for the control plane. The configurator renders OpenCode MCP config and manager/SDD agent definitions. Claude Code is supported secondary for project-local VGXNESS MCP/subagent configuration through explicit guarded apply.
+
+## 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 — supported secondary for project-local VGXNESS MCP/subagent configuration and guarded project-root `CLAUDE.md` managed memory. Confirmed writes are explicit and guarded (`.mcp.json`, `.claude/agents/*.md`, and the `CLAUDE.md` managed block only); VGXNESS does not install/execute Claude Code and never manually writes `~/.claude.json` or `.claude/CLAUDE.md`.
 
 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/default; Claude is supported secondary for project-local explicit apply. |
+| 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).

package/docs/providers.md

@@ -0,0 +1,150 @@
+# Providers
+
+VGXNESS is provider-agnostic at the core: the registry stores provider-neutral definitions and adapters translate them into provider-specific config and runtime behavior. This document covers the two adapter layers: the **control-plane adapter** (OpenCode primary plus supported secondary Claude Code support) and the **code-runtime provider adapter** (OpenAI-compatible + fake).
+
+## Status (v1.6.0)
+
+| Provider | Control plane | Code runtime | Notes |
+|---|---|---|---|
+| OpenCode | `managed` | n/a (target) | Primary supported provider. The configurator renders OpenCode MCP config and manager/SDD agent definitions into the chosen scope. |
+| Claude Code | `supported-secondary` | n/a | Supported for Claude CLI MCP registration planning/apply, project `.mcp.json` compatibility, project-root `CLAUDE.md` managed memory, and project/user agent planning. Scopes are `local`, `project`, and `user`; `personal`/`global` map to `user` for compatibility. Confirmed applies are explicit and guarded; read-only surfaces do not execute Claude Code and VGXNESS never manually mutates `~/.claude.json`. |
+| Antigravity | `placeholder` | n/a | Listed in the TUI Installation surface as coming-soon. |
+| Custom / future | `extension` | extension point | Per the [Architecture](./architecture.md) decision, anything not OpenCode or Claude is a custom extension. |
+| OpenAI-compatible | n/a | `openai-compatible-provider-adapter.ts` | Real adapter used by `vgxness code`. Speaks to any OpenAI-compatible endpoint. |
+| Fake | n/a | `fake-provider-adapter.ts` | Deterministic, offline; for unit tests and CI. |
+
+## Control-plane adapter contract
+
+The control-plane adapter takes a root agent plus optional registered subagents and returns previewable artifacts. It does not mutate the registry, write provider config, or call providers.
+
+| Type | Purpose |
+|---|---|
+| `ProviderRenderer` | Named renderer for one output format/provider. |
+| `ProviderRenderInput` | A root agent plus optional registered subagents. |
+| `ProviderRenderResult` | Generated artifacts, provider name, `installable: false`, warnings. |
+| `ProviderRenderArtifact` | Relative path, content type, and generated contents. |
+
+### OpenCode renderer
+
+`src/agents/renderers/opencode-renderer.ts` renders a single OpenCode config preview with `$schema` and an `agent` object. Top-level agents default to `primary`; subagents render as `subagent`. Agent keys are sanitized deterministically from registry names, and rendering rejects key collisions instead of overwriting generated config.
+
+```bash
+vgxness agents render --provider opencode --project vgxness --name apply-agent
+```
+
+The output is previewable JSON; the renderer does not write to `.opencode/`, `.claude/`, or any user/global provider config.
+
+### JSON renderer
+
+`src/agents/renderers/json-renderer.ts` produces a debug/export shape. It includes the matching `adapters.json` as `selectedAdapter` so downstream consumers can replay the same rendering deterministically.
+
+```bash
+vgxness agents render --provider json --project vgxness --name apply-agent
+```
+
+### Claude Code support
+
+Claude Code is supported as a secondary, non-default control-plane target. Read-only status, doctor, setup plan, and change-plan surfaces can inspect or preview Claude targets without Claude Code installed and without writing files.
+
+Claude scopes are canonicalized to `local`, `project`, and `user`; VGXNESS compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as argv only, for example `claude mcp add --scope user vgxness -- vgxness mcp start`; no shell strings or manual `~/.claude.json` edits are generated. Status/doctor/change-plan avoid private Claude config reads and do not execute Claude Code.
+
+Allowed project-scope writes, only after explicit guarded apply with run preflight metadata (`vgxness mcp install claude --scope project --yes --run-id <id>`):
+
+- `.mcp.json`
+- `.claude/agents/*.md`
+- project-root `CLAUDE.md`, only the VGXNESS managed block; user content outside the block is preserved exactly and existing files are backed up before append/update
+
+User-scoped agent files target `~/.claude/agents/*.md` only as an explicit external-directory/preflighted operation. They are never written by read-only planning/status/doctor/change-plan.
+
+Forbidden writes:
+
+- `~/.claude.json`
+- `.claude/CLAUDE.md`
+
+Malformed, duplicate, partial, or conflicting VGXNESS markers in `CLAUDE.md` cause the full Claude project install to be refused before `.mcp.json`, `.claude/agents/*.md`, or `CLAUDE.md` are mutated.
+
+Manual/opt-in runtime validation checklist (not normal CI):
+
+1. Apply Claude project-local config through the guarded VGXNESS flow.
+2. Open Claude Code in the project manually.
+3. Approve the project MCP server if prompted.
+4. Run `/mcp` and verify `vgxness` is connected.
+5. Run `/agents` and verify expected project subagents are visible.
+6. Ask Claude to call a safe read-only VGXNESS MCP tool.
+7. Confirm forbidden files were not written by VGXNESS.
+
+### OpenCode injection preview
+
+`OpenCodeInjectionPreviewService` (in `src/providers/opencode/`) composes existing read-only outputs into a single envelope:
+
+| Output | Source |
+|---|---|
+| `providerArtifacts` | OpenCode renderer for the selected agent and registered subagents. |
+| `skillPayload` | Skill registry payload builder for the selected SDD phase and OpenCode adapter. |
+| `sdd` | SDD workflow status and readiness for the selected project/change/phase. |
+| `context` and `safety` | OpenCode preview layer metadata for future OpenCode/MCP/hook callers. |
+
+The envelope is always `installable: false` and `readOnly: true`. It does not execute OpenCode, install hooks, create MCP servers, create runs, record skill usage, or touch provider/user/global config. Future live injection should build on this contract only after a separate approved change defines execution, hook, or MCP safety rules.
+
+```bash
+vgxness opencode preview --provider opencode --agent apply-agent --project vgxness --change checkout-flow --phase apply-progress
+```
+
+## Code-runtime provider adapter
+
+The code runtime speaks to a model through `CodeProviderAdapter` (`src/code/providers/provider-adapter.ts`):
+
+```ts
+export interface CodeProviderAdapter {
+  readonly id: string;
+  readonly displayName: string;
+  readonly capabilities: ProviderCapabilities;
+  createResponse(request: ProviderRequest): Promise<ProviderResponse>;
+  streamResponse?(request: ProviderRequest): AsyncIterable<ProviderStreamEvent>;
+  countTokens?(input: ProviderTokenInput): Promise<TokenUsageEstimate>;
+  diagnostics?(model: string): Promise<ProviderDiagnostics>;
+}
+```
+
+Errors are surfaced through `CodeProviderError` with a `code` of `missing_credentials`, `blocked_credentials`, `provider_error`, or `retryable_provider_error`. The `retryable` flag tells callers whether a transient retry is meaningful.
+
+### `openai-compatible-provider-adapter.ts`
+
+The real adapter. Speaks to any OpenAI-compatible endpoint; credentials come from environment references, never embedded in prompts or reports. The adapter streams responses through `stream-normalizer.ts` and maps messages with `message-mapper.ts`.
+
+### `fake-provider-adapter.ts`
+
+Deterministic, offline. Used by `test/code/` and `bun run smoke:opentui-code` to keep CI hermetic. The fake adapter is intentionally thin — it does not model provider quirks, only the contract.
+
+### Adding a new code-runtime provider
+
+1. Implement `CodeProviderAdapter` and a `CodeProviderError`-throwing path. The interface is small; most of the work is in the request/response shape and the stream normalizer.
+2. Add credentials handling in `src/code/providers/credentials.ts`. Do not embed secrets; accept environment references only.
+3. Add a smoke test under `test/code/providers.test.ts` that exercises `createResponse`, `streamResponse`, and `countTokens` (where applicable).
+4. If the new provider has a different default tool shape, add a normalizer. If the stream events are different, extend `stream-normalizer.ts`.
+5. Update [Code runtime](./code-runtime.md) and this document with the new adapter id and capabilities.
+
+## OpenCode provider install and doctor
+
+Provider install and doctor flows live in `src/mcp/client-install-opencode.ts` and `src/mcp/provider-doctor.ts` and are exposed through the MCP server and the CLI:
+
+- `vgxness mcp install opencode --plan` — read-only plan; never writes config.
+- `vgxness mcp install opencode --yes` — explicit write path; creates a backup first.
+- `vgxness mcp doctor opencode` — JSON report of provider health.
+- `vgxness provider status` / `vgxness provider doctor` (planned CLI) — same shape through the operator surface.
+- `vgxness setup rollback --backup <path>` — restores a previous OpenCode config byte-for-byte after validation.
+
+Writes happen only through `apply` with explicit consent. Plans, status, doctor, change-plan, and previews are read-only by contract.
+
+## Safety boundary
+
+Adapters and renderers must not:
+
+- Write provider config outside explicit guarded apply. OpenCode install writes only its selected target; Claude project compatibility apply writes only `.mcp.json`, `.claude/agents/*.md`, and the guarded project-root `CLAUDE.md` managed block; Claude local/user MCP registration uses Claude CLI argv after confirmation/preflight and never manual private-config mutation.
+- Call providers (`opencode`, `claude`, etc.) during preview or status.
+- Install global memory.
+- Create `openspec/`.
+- Bypass permission policy.
+- Mutate other tools' state outside the VGXNESS SQLite store.
+
+Adapter code is reviewed against the safety boundary tests in `test/mcp/` and `test/agents/provider-renderer.test.ts` before merge.