vgxness 1.5.1 → 1.5.2

package/dist/sdd/sdd-workflow-service.js

@@ -21,7 +21,9 @@ export class SddWorkflowService {
         if (!validated.ok)
             return validated;
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases);
+        if (!phases.ok)
+            return phases;
+        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value);
         return {
             ok: true,
             value: {
@@ -36,20 +38,27 @@ export class SddWorkflowService {
         if (!validated.ok)
             return validated;
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return statusFromPhases(validated.value.change, phases);
+        if (!phases.ok)
+            return phases;
+        return statusFromPhases(validated.value.change, phases.value);
     }
     getNext(input) {
         const validated = validateProjectAndChange(input.project, input.change);
         if (!validated.ok)
             return validated;
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return ok(nextDecisionFromStatuses(validated.value.change, phases));
+        if (!phases.ok)
+            return phases;
+        return ok(nextDecisionFromStatuses(validated.value.change, phases.value));
     }
     getCockpit(input) {
         const validated = validateProjectAndChange(input.project, input.change);
         if (!validated.ok)
             return validated;
-        const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
+        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
+        if (!snapshot.ok)
+            return snapshot;
+        const phases = snapshot.value.phases;
         const next = nextDecisionFromStatuses(validated.value.change, phases);
         const cockpitPhases = phases.map((phaseStatus) => {
             const readiness = {
@@ -57,9 +66,7 @@ export class SddWorkflowService {
                 phase: phaseStatus.phase,
                 ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases),
             };
-            const artifact = phaseStatus.present
-                ? this.artifactSummaryForPhase(validated.value.project, validated.value.change, phaseStatus.phase, phaseStatus.topicKey)
-                : undefined;
+            const artifact = phaseStatus.present ? cockpitArtifactSummaryFromSnapshotItem(phaseStatus) : undefined;
             const blockers = cockpitBlockersForPhase(phaseStatus, readiness);
             return {
                 phase: phaseStatus.phase,
@@ -100,6 +107,39 @@ export class SddWorkflowService {
         };
         return ok(cockpit);
     }
+    getGovernanceSnapshot(input) {
+        const validated = validateProjectAndChange(input.project, input.change);
+        if (!validated.ok)
+            return validated;
+        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
+        if (!snapshot.ok)
+            return snapshot;
+        const phases = snapshot.value.phases;
+        const status = statusFromPhases(validated.value.change, phases);
+        if (!status.ok)
+            return status;
+        const warnings = [];
+        const artifacts = phases.flatMap((phase) => {
+            if (phase.artifact === undefined)
+                return [];
+            const envelope = normalizeSddArtifact(phase.artifact);
+            warnings.push(...envelope.warnings);
+            if ((input.payloadMode ?? 'compact') === 'compact') {
+                const compactArtifact = compactGovernanceArtifact(envelope.artifact);
+                return [
+                    {
+                        phase: phase.phase,
+                        topicKey: phase.topicKey,
+                        artifact: compactArtifact,
+                        envelope: { ...envelope, artifact: compactArtifact },
+                    },
+                ];
+            }
+            return [{ phase: phase.phase, topicKey: phase.topicKey, artifact: phase.artifact, envelope }];
+        });
+        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases) };
+        return ok({ status: status.value, artifacts, ...(readiness === undefined ? {} : { readiness }), warnings });
+    }
     saveArtifact(input) {
         const validated = this.validatePhaseInput(input);
         if (!validated.ok)
@@ -161,12 +201,33 @@ export class SddWorkflowService {
         if (input.payloadMode !== 'compact')
             return artifact;
         const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses)));
+        if (!statuses.ok)
+            return statuses;
+        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value)));
     }
     listArtifacts(input) {
         const validated = validateProjectAndChange(input.project, input.change);
         if (!validated.ok)
             return validated;
+        if (input.payloadMode === 'compact') {
+            const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
+            if (!snapshot.ok)
+                return snapshot;
+            return ok({
+                project: validated.value.project,
+                change: validated.value.change,
+                artifacts: snapshot.value.phases.flatMap((phase) => {
+                    if (phase.artifact === undefined)
+                        return [];
+                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases))];
+                }),
+                fullRetrieval: {
+                    tool: 'vgxness_sdd_list_artifacts',
+                    payloadMode: 'verbose',
+                    input: { project: validated.value.project, change: validated.value.change },
+                },
+            });
+        }
         const listed = this.memory.listArtifactsByTopicPrefix(validated.value.project, `sdd/${validated.value.change}/`, this.context);
         if (!listed.ok)
             return listed;
@@ -174,22 +235,7 @@ export class SddWorkflowService {
         const artifacts = sddPhases
             .map((phase) => artifactsByTopicKey.get(sddTopicKey(validated.value.change, phase)))
             .filter((artifact) => artifact !== undefined);
-        if (input.payloadMode !== 'compact')
-            return ok({ project: validated.value.project, change: validated.value.change, artifacts });
-        const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return ok({
-            project: validated.value.project,
-            change: validated.value.change,
-            artifacts: artifacts.map((artifact) => {
-                const phase = isSddPhase(artifact.phase) ? artifact.phase : phaseFromTopicKey(validated.value.change, artifact.topicKey);
-                return compactArtifactProjection(artifact, validated.value.change, phase, getReadinessFromStatuses(validated.value.change, phase, statuses));
-            }),
-            fullRetrieval: {
-                tool: 'vgxness_sdd_list_artifacts',
-                payloadMode: 'verbose',
-                input: { project: validated.value.project, change: validated.value.change },
-            },
-        });
+        return ok({ project: validated.value.project, change: validated.value.change, artifacts });
     }
     validatePhaseInput(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -200,31 +246,38 @@ export class SddWorkflowService {
         return { ok: true, value: { ...validated.value, phase: input.phase } };
     }
     getPhaseStatuses(project, change) {
-        return sddPhases.map((phase) => {
+        const snapshot = this.loadPhaseSnapshot(project, change);
+        if (!snapshot.ok)
+            return snapshot;
+        return ok(snapshot.value.phases.map(({ artifact, acceptance, createdAt, updatedAt, warnings, ...status }) => status));
+    }
+    loadPhaseSnapshot(project, change) {
+        const listed = this.memory.listArtifactsByTopicPrefixNoTrace(project, `sdd/${change}/`);
+        if (!listed.ok)
+            return listed;
+        const artifactsByTopicKey = new Map(listed.value.map((artifact) => [artifact.topicKey, artifact]));
+        const phases = sddPhases.map((phase) => {
             const topicKey = sddTopicKey(change, phase);
-            const artifact = this.memory.getArtifact(project, topicKey, this.context);
-            if (!artifact.ok)
-                return { phase, topicKey, present: false, state: 'missing', accepted: false, legacy: false };
-            return phaseStatusFromArtifact(phase, topicKey, artifact.value);
+            const artifact = artifactsByTopicKey.get(topicKey);
+            if (artifact === undefined)
+                return { phase, topicKey, present: false, state: 'missing', accepted: false, legacy: false, warnings: [] };
+            const envelope = normalizeSddArtifact(artifact);
+            return {
+                phase,
+                topicKey,
+                present: true,
+                state: envelope.metadata.status,
+                accepted: envelope.metadata.status === 'accepted',
+                legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
+                artifactId: artifact.id,
+                artifact,
+                ...(envelope.metadata.acceptance === undefined ? {} : { acceptance: envelope.metadata.acceptance }),
+                createdAt: artifact.createdAt,
+                updatedAt: artifact.updatedAt,
+                warnings: envelope.warnings,
+            };
         });
-    }
-    artifactSummaryForPhase(project, change, phase, topicKey) {
-        const artifact = this.memory.getArtifact(project, topicKey, this.context);
-        if (!artifact.ok)
-            return undefined;
-        const envelope = normalizeSddArtifact(artifact.value);
-        return {
-            phase,
-            topicKey,
-            present: true,
-            accepted: envelope.metadata.status === 'accepted',
-            legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
-            state: envelope.metadata.status,
-            artifactId: artifact.value.id,
-            ...(envelope.metadata.acceptance === undefined ? {} : { acceptance: envelope.metadata.acceptance }),
-            createdAt: artifact.value.createdAt,
-            updatedAt: artifact.value.updatedAt,
-        };
+        return ok({ project, change, phases });
     }
 }
 export function nextDecisionFromStatuses(change, phases) {
@@ -336,18 +389,6 @@ function getReadinessFromStatuses(change, phase, phases) {
         blockedPrerequisites,
     };
 }
-function phaseStatusFromArtifact(phase, topicKey, artifact) {
-    const envelope = normalizeSddArtifact(artifact);
-    return {
-        phase,
-        topicKey,
-        present: true,
-        state: envelope.metadata.status,
-        accepted: envelope.metadata.status === 'accepted',
-        legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
-        artifactId: artifact.id,
-    };
-}
 function compactArtifactProjection(artifact, change, phase, readiness) {
     const envelope = normalizeSddArtifact(artifact);
     const summary = summarizePayloadContent(artifact.content);
@@ -370,6 +411,35 @@ function compactArtifactProjection(artifact, change, phase, readiness) {
         updatedAt: artifact.updatedAt,
     };
 }
+function cockpitArtifactSummaryFromSnapshotItem(item) {
+    if (item.artifact === undefined || item.artifactId === undefined || item.createdAt === undefined || item.updatedAt === undefined)
+        return undefined;
+    return {
+        phase: item.phase,
+        topicKey: item.topicKey,
+        present: true,
+        accepted: item.accepted === true,
+        legacy: item.legacy === true,
+        state: item.state ?? 'draft',
+        artifactId: item.artifactId,
+        ...(item.acceptance === undefined ? {} : { acceptance: item.acceptance }),
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+    };
+}
+function compactGovernanceArtifact(artifact) {
+    return {
+        id: artifact.id,
+        project: artifact.project,
+        topicKey: artifact.topicKey,
+        phase: artifact.phase,
+        observationId: artifact.observationId,
+        createdAt: artifact.createdAt,
+        updatedAt: artifact.updatedAt,
+        contentLength: artifact.content.length,
+        contentOmitted: true,
+    };
+}
 function cockpitBlockersForPhase(status, readiness) {
     const blockers = [];
     if (!status.present)

package/dist/setup/providers/claude-setup-adapter.js

@@ -4,17 +4,20 @@ export const claudeSetupAdapter = {
     id: 'claude',
     displayName: 'Claude',
     supportLevel: 'preview-only',
-    capabilities: ['mcp-preview', 'manual-guidance'],
-    targets: [{ kind: 'manual', label: 'Claude MCP config snippet', writableBySetup: false }],
+    capabilities: ['mcp-preview', 'mcp-install-plan', 'agent-preview', 'doctor', 'manual-guidance'],
+    targets: [
+        { kind: 'project-config', label: 'Project .mcp.json', path: '.mcp.json', writableBySetup: false },
+        { kind: 'project-config', label: 'Project Claude agents', path: '.claude/agents/*.md', writableBySetup: false },
+    ],
     getStatus(context) {
         return {
             providerId: 'claude',
             status: 'preview-only',
-            summary: 'Claude setup is preview-only with manual MCP guidance.',
+            summary: 'Claude setup supports project-local read-only planning for .mcp.json and .claude/agents/*.md; confirmed writes are handled by guarded install flows.',
             evidence: context.databasePath !== undefined
                 ? ['Claude MCP preview can be generated from the selected database path.']
                 : ['Claude MCP preview uses a placeholder until a database path is selected.'],
-            guidance: ['Copy snippets manually after reviewing them. The TUI does not install or apply Claude config.'],
+            guidance: ['Review the Claude plan before any write. VGXNESS never writes ~/.claude.json, CLAUDE.md, or .claude/CLAUDE.md and does not execute/install Claude Code.'],
             actions: [
                 {
                     id: 'claude-manual-guidance',

package/docs/architecture.md

@@ -1,10 +1,12 @@
 # vgxness Architecture
 
+> **Scope:** this document describes the v1.5.1 architecture as it is actually built. It is the source of truth for how the product works today. Planned work that is not yet shipped lives in [Roadmap](./roadmap.md); historical planning context that no longer reflects reality has been retired. Where this doc disagrees with code, code wins — file a doc-sync task against the relevant module.
+
 `vgxness` is a local-first, provider-agnostic, Gentle-AI-like harness for agentic development. Its core architecture separates the product domain from provider-specific tooling so agents, skills, memory, SDD workflows, runs, and traces can work across OpenCode, Claude Code, and future adapters such as Pi.
 
-The architectural goal is not only to install better prompts or agent configs. `vgxness` should combine an ecosystem configurator with a runtime control plane: configured agents may execute the work, but the product keeps explicit state for phase readiness, artifacts, runs, approvals, checkpoints, and audit evidence.
+The architectural goal is not only to install better prompts or agent configs. `vgxness` combines an ecosystem configurator with a runtime control plane and a native code runtime: configured agents may execute the work, the control plane keeps explicit state for phase readiness, artifacts, runs, approvals, checkpoints, and audit evidence, and the code runtime performs bounded agentic work in the local workspace with explicit permission decisions.
 
-The user-facing shape is deliberately three-surface: **MCP for agents**, **CLI for scriptable operator control**, and **TUI for guided setup and visual local operations**. All three must call the same core services instead of reimplementing workflow rules.
+The user-facing shape is deliberately four-surface: **MCP for agents**, **CLI for scriptable operator control**, **TUI for guided setup and visual local operations**, and **code runtime (`vgxness code`)** for bounded agentic work in the workspace. All four call the same core services instead of reimplementing workflow rules.
 
 ## Architecture decision summary
 
@@ -14,9 +16,9 @@ The user-facing shape is deliberately three-surface: **MCP for agents**, **CLI f
 | Reference model | Similar product surface to Gentle-AI/`gentle-pi`: agent setup, SDD orchestration, memory wiring, skills, profiles, permissions, verification. |
 | Differentiator | Verifiable runtime state engine: SDD phases, artifacts, runs, approvals, checkpoints, and audit trails are queryable product state, not prompt-only convention. |
 | Core workflow | SDD-first canonical state: explore → proposal → spec → design → tasks → apply-progress → verify → archive. |
-| Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows. |
+| Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows, and `vgxness code` runtime for bounded workspace work. |
 | Installation UX | Step-based guided setup with doctor checks, dry-run support, and no manual provider JSON editing on the happy path. |
-| Provider strategy | Provider-agnostic domain model with OpenCode and Claude Code first; Pi/`gentle-pi` compatibility is a future adapter/reference target. |
+| Provider strategy | Provider-agnostic domain model with OpenCode as the primary supported provider; Claude Code is preview/manual only and VGXNESS does not install Claude or write `.claude/` or `CLAUDE.md`. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
 | Memory | Project memory plus personal/global memory, backed locally. |
 | Agents | Agents/subagents are registered in a neutral schema, then rendered into provider-specific config. |
 | Skills | Skills are first-class, versioned, attachable to agents/workflows/adapters, and improved through reviewable proposals. |
@@ -98,7 +100,7 @@ Gentle-AI/`gentle-pi` are strong references for the configurator and agent-behav
 | Project | Repo-specific memory, SDD artifacts, run history, adapter config, project agents/skills. | `.vgx/` or project-local SQLite store. |
 | Personal/global | User preferences, reusable skills, cross-project patterns, global agents. | User-level config/data directory. |
 
-The exact path format is still open, but the architectural rule is fixed: **project data and personal data must not be collapsed into one scope**.
+The exact path format is still open, but the architectural rule is fixed: **project data and personal data must not be collapsed into one scope**. See [Storage](./storage.md) for schema, migration layout, and lifecycle.
 
 ## SDD workflow engine
 
@@ -116,18 +118,20 @@ Current phase artifacts use one canonical topic key each:
 sdd/{change}/{phase}
 ```
 
-Readiness is based on artifact presence only:
+Readiness is a combination of prerequisite phase artifacts, explicit human acceptance, and aggregate blockers — artifact presence alone is not enough:
 
-| Phase | Required artifacts |
-|---|---|
-| `explore` | none |
-| `proposal` | `explore` |
-| `spec` | `proposal` |
-| `design` | `proposal`, `spec` |
-| `tasks` | `proposal`, `spec`, `design` |
-| `apply-progress` | `tasks` |
-| `verify` | `apply-progress` |
-| `archive` | `verify` |
+| Phase | Required prerequisites | Acceptance required |
+|---|---|---|
+| `explore` | none | no |
+| `proposal` | `explore` | yes (on `explore`) |
+| `spec` | `proposal` | yes (on `proposal`) |
+| `design` | `proposal`, `spec` | yes (on `proposal`, `spec`) |
+| `tasks` | `proposal`, `spec`, `design` | yes (on `proposal`, `spec`, `design`) |
+| `apply-progress` | `tasks` | yes (on `tasks`) |
+| `verify` | `apply-progress` | yes (on `apply-progress`) |
+| `archive` | `verify` | yes (on `verify`) |
+
+`SddWorkflowService.getReady(...)` returns a structured `SddReadiness` with `blockedPrerequisites`, while `getCockpit(...)` aggregates `SddCockpitBlocker`s of kind `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, or `readiness`. Acceptance is recorded only by a human actor (`acceptedBy.type === 'human'`); the runtime rejects agent or anonymous acceptance.
 
 Current service API:
 
@@ -409,7 +413,7 @@ NO silent mutation of active skills. Eso es una línea roja.
 
 ## Provider adapter contract
 
-Adapters render registry definitions into provider artifacts without changing the registry model.
+Adapters render registry definitions into provider artifacts without changing the registry model. The full adapter contract, render API, and how to add a new provider live in [Providers](./providers.md); this section is a high-level map.
 
 Current contract:
 
@@ -462,15 +466,15 @@ The checked-in OpenCode default config and `seeds/agents/agent-seed-v1.json` def
 
 ## Run lifecycle
 
-A run is the core unit of execution. The current foundation stores local, provider-neutral run records in SQLite; deeper orchestration and approval enforcement are follow-up work.
-
-Current terminal lifecycle rules:
+A run is the core unit of execution. Run records are stored locally in SQLite and stay provider-neutral. The lifecycle is complete in v1.5.1:
 
 ```text
-created → completed | failed | blocked | cancelled
+created → planned → running → needs-human
+                                      ↓
+                              completed | failed | blocked | cancelled
 ```
 
-The broader planned lifecycle still includes `planned`, `running`, and `needs-human`, but this slice only enforces safe finalization: terminal runs cannot be finalized again, and final outcomes must match the terminal status.
+All eight statuses are first-class on `RunStatus` (`src/runs/schema.ts:1`). The control plane exposes lifecycle operations through `vgxness_run_start`, `vgxness_run_checkpoint`, `vgxness_run_finalize`, and the read-only `vgxness_run_resume_inspect` and `vgxness_run_resume_gate` tools. Finalize is safe by default: terminal runs cannot be finalized again, and the final `outcome` must match the terminal `status` (`success`/`partial`/`failure`/`blocked`/`cancelled`).
 
 Current run fields:
 
@@ -556,14 +560,13 @@ runService.appendCheckpoint({
 });
 ```
 
-Follow-up runtime work:
+Open follow-up for run execution lives in [Roadmap](./roadmap.md). The remaining work is:
+
+- real provider/tool invocation behind sandboxed executors (the lifecycle and policy recording are stable; the actual executor is still test-only)
+- CLI/MCP orchestration for `resume-after-approval` once a safe executor exists outside tests
+- richer verification evidence summaries that link runs, tasks, and verifications
 
-- active state transitions for `planned`, `running`, and `needs-human`
-- real provider/tool invocation behind sandboxed executors
-- CLI or adapter orchestration for resume-after-approval once a safe executor exists outside tests
-- operator UX for retry admission and retry execution, with clear separation between reservation and actual execution
-- sandbox/worktree execution strategies after decision recording is stable
-- richer verification evidence summaries
+What is already shipped: 8-state lifecycle, approval records, reserved attempts, retry policy evaluation with `never`/`after-abandoned`/`after-failure`/`after-failure-or-abandoned`, run insights with debug summary, run snapshot export (`RunSnapshotPackageV1`), and a `runs retry-check --approval <id> [--policy <json>]` operator command.
 
 ## Trace model
 
@@ -584,9 +587,7 @@ Minimum trace events:
 
 ## Permission model
 
-Permissions must be defined in `vgxness` first, then mapped to adapters.
-
-Minimum categories:
+Permissions are defined in `vgxness` first, then mapped to adapters through the neutral `permissions` field on agents and subagents. The full safety model, including approval flow, redactors, and runtime gates, is in [Safety model](./safety.md). Categories:
 
 | Category | Examples |
 |---|---|
@@ -600,15 +601,9 @@ Minimum categories:
 | `provider-tool` | opaque adapter/provider tool calls |
 | `secrets` | environment variables, credentials, tokens |
 
-Operations can resolve to:
-
-- `allow`
-- `ask`
-- `deny`
-
-Default stance for destructive or external operations: **ask or deny**, never implicit allow.
+Operations resolve to `allow`, `ask`, or `deny`. Destructive or external operations default to **ask or deny**, never implicit allow.
 
-Current foundation API: `evaluatePermission(request)` in `src/permissions/` returns `allow`, `ask`, or `deny` with a reason. Defaults are intentionally conservative:
+Current foundation API: `evaluatePermission(request)` in `src/permissions/policy-evaluator.ts` returns `allow`, `ask`, or `deny` with a reason. Defaults are intentionally conservative:
 
 - workspace reads are allowed only when the target path stays inside `workspaceRoot`
 - edits, shell, git, network, memory writes/searches, and provider-specific tools ask by default
@@ -616,84 +611,31 @@ Current foundation API: `evaluatePermission(request)` in `src/permissions/` retu
 - destructive, external, privileged, or ambiguous requests require ask even when an agent override would otherwise allow the category
 - workspace boundary denials cannot be relaxed by agent/subagent overrides
 
-Agent and subagent registry definitions keep neutral `permissions` such as `{ "shell": "ask", "provider-tool": "deny" }`. Provider names and tool details remain opaque metadata; enforcement and sandbox execution are follow-up runtime work.
+The code runtime layers a second, finer-grained decision on top of the policy evaluator: per-tool definitions declare whether a tool is `read`, `confirm`, or `restricted`; `PolicyApprovalBroker`, `StdioApprovalBroker`, and `ConservativePermissionGateway` (in `src/code/runtime/approval-coordinator.ts`) wire approval prompts to the runtime event stream. See [Code runtime](./code-runtime.md) for the workspace-side contract.
 
-## Future interface surface
+## Interface surface (current)
 
-Current and near-term CLI surface should build on the plural domain commands documented in `docs/cli.md`. Future shortcuts can be added later, but they should not imply separate singular command families:
+CLI surface groups are documented in [CLI reference](./cli.md). The plural form is canonical — singular shortcuts are not added.
 
-```bash
-vgxness init
-vgxness memory search|get|save|update
-vgxness agents list|register|get|resolve|render
-vgxness skills list|register|propose|approve-proposal|apply-proposal
-vgxness sdd status|next|ready|save-artifact|accept-artifact|list-artifacts
-vgxness runs list|get|timeline|debug|resume-inspect|resume-gate
-vgxness mcp doctor|install
-vgxness opencode preview
-```
-
-Representative MCP tools mirror the same core services for agent use. For the current exact tool names, use `SUPPORTED_VGX_MCP_TOOL_NAMES`:
-
-```text
-vgxness_sdd_status
-vgxness_sdd_next
-vgxness_sdd_ready
-vgxness_sdd_save_artifact
-vgxness_sdd_get_artifact
-vgxness_sdd_list_artifacts
-vgxness_memory_search
-vgxness_memory_get
-vgxness_memory_save
-vgxness_memory_update
-vgxness_run_start
-vgxness_run_list
-vgxness_run_get
-vgxness_run_preflight
-vgxness_run_checkpoint
-vgxness_run_finalize
-vgxness_agent_resolve
-vgxness_agent_activate
-vgxness_manager_profile_get
-vgxness_manager_profile_set
-vgxness_skill_payload
-vgxness_opencode_manager_payload
-```
-
-The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations are the execution/configuration plane.
+MCP tools mirror the same core services for agent use. The full, current list of 38 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations and the code runtime sit on the execution plane.
 
 ## Evaluation strategy
 
-Minimum eval/test targets:
-
-- Agent resolution selects the expected agent.
-- Skill resolution injects the expected skill.
-- Adapter rendering produces valid provider config.
-- Permission rules block unsafe operations.
-- SDD artifact chains remain complete.
-- Memory upserts preserve revisions.
-- Run resume restores expected state.
-- Skill improvement proposals are versioned and require approval.
-- MCP tools call the same core services as CLI/TUI and return actionable blocked states.
-- TUI setup screens expose loading, empty, error, success, blocked, and permission states.
+Minimum eval/test targets (asserted through `node:test` files under `test/`, totaling 95 files as of v1.5.1):
+
+- Agent resolution selects the expected agent (`test/agents/agent-resolver.test.ts`).
+- Skill resolution injects the expected skill (`test/skills/`).
+- Adapter rendering produces valid provider config (`test/agents/provider-renderer.test.ts`).
+- Permission rules block unsafe operations (`test/permissions/policy-evaluator.test.ts`).
+- SDD artifact chains remain complete and human acceptance is enforced (`test/sdd/sdd-workflow-service.test.ts`).
+- Memory upserts preserve revisions (`test/memory/`).
+- Run resume restores expected run state and respects retry policies (`test/runs/`).
+- Skill improvement proposals are versioned and require approval (`test/skills/`).
+- MCP tools call the same core services as CLI/TUI and return actionable blocked states (`test/mcp/`).
+- Code runtime behavior across inspect, plan, craft-preview, and craft modes (`test/code/`).
+- OpenCode config rendering and drift detection (`test/mcp/opencode-agent-config-drift.test.ts`).
 - Installation dry-run reports the exact provider config changes before mutation.
 
-## Immediate implementation recommendation
-
-The next SDD change should be `harness-runtime-foundation`.
-
-Scope:
-
-- define schemas for agents, skills, runs, traces, permissions, and adapters
-- add local persistence for these entities where missing
-- add adapter validation/render skeleton
-- add CLI/MCP/TUI interface boundaries for validation, inspection, and guided setup
-- add tests for schema validation, permission decisions, and adapter rendering
-
-Out of scope:
+## Future work
 
-- cloud sync
-- team collaboration
-- web console
-- distributed workers
-- fully autonomous skill mutation
+Planned work that is not yet shipped lives in [Roadmap](./roadmap.md). This document stays focused on the architecture as built; the roadmap is the place to track what is next and what is explicitly deferred.

package/docs/cli.md

@@ -254,6 +254,45 @@ The command prints a deterministic JSON envelope with `flow`, `confidence`, `rea
 
 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.
 
+## Code runtime CLI (`vgxness code`)
+
+`vgxness code` is the native workspace runtime for bounded agentic work. It is not a wrapper around OpenCode or any provider; provider adapters translate VGXNESS-native requests only. See [Code runtime](./code-runtime.md) for the full contract; this section lists the CLI surface.
+
+Modes (read-only by default unless `--approval-channel` and `--approval-policy` are passed):
+
+| Mode | Purpose | Mutations |
+|---|---|---|
+| `inspect` | Read-only investigation of the workspace. | None. |
+| `plan` | Read-only implementation planning. | None. |
+| `craft-preview` | Show the diff that would be applied. | None. |
+| `craft` | Approval-gated, bounded edit-capable work. | Edits, shell, network, git, SDD persistence all routed through explicit policy decisions. |
+
+Common flags across modes:
+
+```bash
+vgxness code inspect "<question>"   \
+  --provider openai-compatible      \  # or "fake" for offline testing
+  --model <model-id>                 \
+  --stream                           \  # emit JSONL runtime events as they happen
+  --json                             \  # final response as JSON
+  --max-source-bytes <bytes>         \  # bound on sources loaded into prompt
+  --approval-policy ask|allow|deny   \
+  --approval-channel stdio|auto      \
+  --verification none|suggest|run|repair \
+  --transcript off|summary|full      \
+  --memory off|ask|auto
+```
+
+SDD-aware mode is exposed through `vgxness code sdd <change> <phase>`; pass `--save-artifact` only when persistence is intended, and pass `--change-id`/`--phase` to scope work. Read-only phases stay artifact-oriented; `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools.
+
+Useful events-only output for piping into the OpenTUI shell or your own tooling:
+
+```bash
+vgxness code inspect "Summarize the current architecture" --events-jsonl
+```
+
+Safety boundary: `inspect`, `plan`, and `craft-preview` never mutate. `craft` may only mutate through the permission-aware executors and the explicit approval channel; it never writes outside the workspace, never pushes to remote, and never edits `openspec/`. Secret-like values are redacted from prompts, transcripts, checkpoints, and memory saves. See [Safety model](./safety.md).
+
 ## 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`:
@@ -872,3 +911,17 @@ Existing project-local stores remain compatible; opt in explicitly when needed:
 ```bash
 bun run cli:bun -- memory search --project vgxness --db .vgx/memory.sqlite
 ```
+
+For more on schema, scopes, and lifecycle, see [Storage](./storage.md).
+
+## See also
+
+- [Architecture](./architecture.md) — current-state architecture and core domain model.
+- [Code runtime](./code-runtime.md) — `vgxness code` modes, tools, providers, and approval flow.
+- [MCP tools](./mcp.md) — full reference for the 38 MCP tools exposed to agents.
+- [Safety model](./safety.md) — permission categories, approval flow, redactors, and runtime gates.
+- [Storage](./storage.md) — SQLite schema, scopes, and lifecycle.
+- [Providers](./providers.md) — adapter contract and how to add a new provider.
+- [Roadmap](./roadmap.md) — planned work not yet shipped.
+- [Contributing](./contributing.md) — repository layout, verification, and style.
+- [Glossary](./glossary.md) — terminology used across the docs and the codebase.