vgxness 1.20.14 → 1.21.0

package/README.md

@@ -1,14 +1,14 @@
 # VGXNESS
 
-VGXNESS is an installable CLI and MCP control plane for guided AI-agent workflows, SDD artifacts, local memory, and OpenCode integration.
+VGXNESS is an installable, local-first governance OS and MCP/CLI control plane for existing coding agents. It governs SDD artifacts, local memory, runs, permissions, skills, provider setup, and verification evidence while OpenCode, Claude Code, and future adapters keep executing provider-native.
 
 ## Release status and license
 
 This package is proprietary software. The npm package ships inspectable JavaScript (`dist/`) so Node can run it, but it is **not open-source licensed** and may not be redistributed unless you have written permission. See [LICENSE](./LICENSE).
 
-OpenCode is the primary supported provider. Claude setup support is secondary. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
+OpenCode is the primary supported provider. Claude Code setup support is secondary/preview guidance. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
 
-VGXNESS is currently versioned from `package.json` (`1.20.0`). The latest full project health audit is the historical [v1.14.x snapshot](./docs/project-health-audit-v1.14.x.md), which documents the implemented CLI/MCP/SDD control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
+VGXNESS is versioned from `package.json`. The latest full project health audit is the historical [v1.14.x snapshot](./docs/project-health-audit-v1.14.x.md), which documents the implemented CLI/MCP/SDD governance control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
 
 ## Requirements
 
@@ -163,7 +163,7 @@ vgxness setup apply --yes
 
 `vgxness setup plan` and `vgxness setup status` are human-readable and do not write provider config by default; local VGXNESS store initialization may occur when a command needs the selected SQLite store. `vgxness doctor`, `vgxness status`, `vgxness next`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd continue`, and `vgxness sdd accept-artifact` are also human-readable by default. Pass `--json` when you need parseable automation output. `vgxness setup apply --yes` is the explicit provider-config write path.
 
-The daily SDD happy path is OpenCode conversation with the installed VGXNESS MCP server and hidden SDD subagents. Use CLI commands for bootstrap, setup, diagnostics, recovery, fallback, and scripting: `status`, `next`, and `sdd continue` inspect state and print read-only continuation guidance; `resume` helps inspect interrupted work. After a draft is ready, `sdd accept-artifact` records explicit human acceptance, and `sdd reopen-artifact` returns rejected artifacts to draft.
+The daily SDD happy path is an OpenCode conversation with the installed VGXNESS MCP server and provider-native hidden SDD subagents. VGXNESS supplies the governance state and guardrails; OpenCode executes the agent loop. Use CLI commands for bootstrap, setup, diagnostics, recovery, fallback, and scripting: `status`, `next`, and `sdd continue` inspect state and print read-only continuation guidance; `resume` helps inspect interrupted work. In the normal organic flow, proposal acceptance is the first mandatory human continue gate; after that, `spec -> design -> tasks` can be drafted without separate confirmations, then VGXNESS asks before apply/implementation. `sdd accept-artifact` records explicit human-only acceptance when a real gate applies, and `sdd reopen-artifact` returns rejected artifacts to draft.
 
 Copy this prompt into OpenCode for normal daily SDD work:
 
@@ -171,24 +171,25 @@ Copy this prompt into OpenCode for normal daily SDD work:
 Continue VGXNESS SDD for project <project> and change <change>.
 Use the VGXNESS MCP tools to inspect status/readiness/artifacts, then delegate phase work to the exact hidden SDD subagent when needed.
 Save draft artifacts when appropriate and report evidence, tests, blockers, and the next human decision.
-Do not accept or reopen artifacts for me; ask me before any human-only, provider-config, git, destructive, external, install, or secret-sensitive action.
+Treat proposal acceptance as the first mandatory human continue gate; after that, draft spec/design/tasks without separate confirmations, then ask before apply/implementation.
+Do not accept or reopen artifacts for me; ask before provider/global config, git/publish, destructive, external, privileged, install, network, secret-sensitive, or official archive actions.
 ```
 
 ## Code runtime status
 
-The experimental `vgxness code` runtime and principal OpenTUI code surface have been removed temporarily because they were copied OpenCode-like runtime work. Continue SDD work in OpenCode through VGXNESS MCP, and use the safe CLI commands above for diagnostics and recovery.
+The experimental `vgxness code` runtime and principal OpenTUI code surface have been removed and are not the default product direction. Continue SDD work in OpenCode through VGXNESS MCP, and use the safe CLI commands above for diagnostics and recovery. Reintroducing a first-party coding-agent runtime would require a separate accepted SDD change.
 
 ## Safety model
 
 - Preview, status, and plan commands do not write provider config; local VGXNESS store initialization may occur where the command needs SQLite-backed state.
 - VGX-managed OpenCode and Claude provider config writes are user-global only and require explicit `--yes` confirmation.
 - Runtime VGXNESS state remains project-aware; project-local provider files are read-only external/manual diagnostics and may still affect provider behavior outside VGXNESS.
-- Setup/status TUI surfaces are read-only setup, diagnostics, recovery, and fallback surfaces; daily SDD progression stays in OpenCode with VGXNESS MCP.
+- Setup/status TUI surfaces are read-only setup, diagnostics, recovery, and fallback surfaces; daily SDD progression stays in OpenCode with VGXNESS MCP and provider-native execution.
 - SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write `openspec/`.
-- `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
+- `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance, and normal spec/design/tasks draft autorun after proposal acceptance is not silent acceptance.
 - `vgxness sdd reopen-artifact` is the explicit path from a rejected artifact back to draft before revision.
-- OpenCode is the primary supported provider; other providers are preview/manual extension points.
-- VGXNESS exposes 42 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See [MCP tools](./docs/mcp.md).
+- OpenCode is the primary supported provider; Claude Code is secondary/preview guidance; other providers are preview/manual extension points.
+- VGXNESS exposes 63 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See [MCP tools](./docs/mcp.md).
 
 ## Principal entrypoint
 
@@ -269,6 +270,8 @@ Remove any user-global OpenCode/Claude config entries and local/global VGXNESS d
 - [Project health audit v1.10.x](./docs/project-health-audit-v1.10.x.md)
 - [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md)
 - [Architecture](./docs/architecture.md)
+- [Knowledge Workspace](./docs/knowledge-workspace.md)
+- [Obsidian MCP integration](./docs/obsidian-mcp.md)
 - [MCP tools](./docs/mcp.md)
 - [Safety model](./docs/safety.md)
 - [Storage](./docs/storage.md)

package/dist/adapters/claude/install/claude-code-agent-config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, parse, resolve } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeCode } from '../../../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeCode } from '../../../application/agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeCodeGeneratedMarker = 'VGXNESS-GENERATED';
 export function expectedClaudeCodeAgentFiles(input) {

package/dist/adapters/claude/install/claude-code-project-memory.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../application/agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeProjectMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
 export const claudeProjectMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';

package/dist/adapters/claude/install/claude-code-user-memory.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../application/agents/canonical-agent-projection.js';
 import { safeHomeDirectory } from './claude-code-agent-config.js';
 export const claudeUserMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE USER MEMORY -->';
 export const claudeUserMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE USER MEMORY -->';

package/dist/adapters/claude/install/client-install-claude-code-contract.js

@@ -1,4 +1,4 @@
-import { withEffectiveManagerInstructions } from '../../../agents/canonical-agent-projection.js';
+import { withEffectiveManagerInstructions } from '../../../application/agents/canonical-agent-projection.js';
 import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
 import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig } from './claude-code-config.js';

package/dist/adapters/opencode/install/client-install-opencode-contract.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { canonicalCapabilitySubagentLegacyAliases } from '../../../agents/canonical-agent-manifest.js';
+import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, } from './opencode-default-agent-config.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
 const opencodeUserGlobalOnlyMessage = 'VGX-managed OpenCode configuration is user-global only. Project/local OpenCode files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
@@ -201,7 +201,7 @@ function warningsForScope(_scope, overwriteVgxness, agentPlan, bashPermissionPol
         : [];
     const bashWarnings = bashPermissionPolicy.manager === 'deny'
         ? [
-            'OpenCode config sets top-level permission.bash = ask; manager read/search discovery tools (read/glob/grep) are allowed while manager bash/edit/write are denied; capability subagents keep explicit permissions plus legacy SDD task aliases. This is config-level evidence only and does not verify provider runtime enforcement.',
+            'OpenCode config sets top-level permission.bash = ask; manager read/search discovery tools (read/glob/grep) are allowed while manager bash/edit/write are denied; capability subagents keep explicit canonical permissions only. This is config-level evidence only and does not verify provider runtime enforcement.',
         ]
         : ['OpenCode top-level permission.bash is set to ask.'];
     return [

package/dist/adapters/opencode/install/client-install-opencode.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { canonicalCapabilitySubagentLegacyAliases } from '../../../agents/canonical-agent-manifest.js';
+import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createManagedProviderConfigBackup } from '../../../setup/backup-rollback-service.js';
 import { findConflictingVgxnessAgents, planOpenCodeMcpInstall, } from './client-install-opencode-contract.js';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, vgxnessOpenCodeInstructionsPath, } from './opencode-default-agent-config.js';
@@ -220,7 +220,7 @@ function confirmationRequiredMessage(scope) {
 function warnings() {
     return [
         'Restart OpenCode after installation so it reloads the project MCP config.',
-        'OpenCode config sets top-level permission.bash = ask; manager read/search discovery tools (read/glob/grep) are allowed while manager bash/edit/write are denied; capability subagents keep explicit permissions plus legacy SDD task aliases. This is config-level evidence only and does not verify provider runtime enforcement.',
+        'OpenCode config sets top-level permission.bash = ask; manager read/search discovery tools (read/glob/grep) are allowed while manager bash/edit/write are denied; capability subagents keep explicit canonical permissions only. This is config-level evidence only and does not verify provider runtime enforcement.',
     ];
 }
 function manualTest(databasePath, source) {

package/dist/adapters/opencode/install/opencode-default-agent-config.js

@@ -1,5 +1,5 @@
-import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddMcpToolPermissions, createCanonicalOpenCodeSddTaskPermissions, } from '../../../agents/canonical-agent-manifest.js';
-import { projectCanonicalAgentManifestToOpenCode, withEffectiveOpenCodeManagerInstructions, } from '../../../agents/canonical-agent-projection.js';
+import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddMcpToolPermissions, createCanonicalOpenCodeSddTaskPermissions, } from '../../../domain/agents/canonical-agent-manifest.js';
+import { projectCanonicalAgentManifestToOpenCode, withEffectiveOpenCodeManagerInstructions, } from '../../../application/agents/canonical-agent-projection.js';
 export const vgxnessOpenCodeDefaultAgent = canonicalDefaultAgentName;
 export const vgxnessOpenCodePromptContractVersion = canonicalPromptContractVersion;
 export const vgxnessOpenCodeInstructionsPath = 'AGENTS.md';

package/dist/application/agents/agent-resolver.js

@@ -1,4 +1,5 @@
-import { normalizeSddPhaseInput } from '../../sdd/schema.js';
+import { canonicalCapabilitySubagentLegacyAliases } from '../../domain/agents/canonical-agent-manifest.js';
+import { normalizeSddPhaseInput } from '../../domain/sdd/schema.js';
 import { agentLookupContexts } from './agent-lookup-contexts.js';
 export class AgentResolver {
     loadAgents;
@@ -12,7 +13,7 @@ export class AgentResolver {
         const normalized = normalizeInput(input);
         const candidates = [];
         const skipped = [];
-        for (const agent of agents.value) {
+        for (const agent of suppressLegacyAliasAgents(agents.value)) {
             const skipReasons = hardSkipReasons(agent, normalized);
             if (skipReasons.length > 0) {
                 skipped.push(toSkipped(agent, skipReasons));
@@ -44,6 +45,13 @@ export class AgentResolver {
         });
     }
 }
+function suppressLegacyAliasAgents(agents) {
+    const names = new Set(agents.map((agent) => agent.name));
+    return agents.filter((agent) => {
+        const canonical = canonicalCapabilitySubagentLegacyAliases[agent.name];
+        return canonical === undefined || !names.has(canonical);
+    });
+}
 const SDD_PHASE_SEMANTICS = [
     {
         name: 'sdd-planning',

package/dist/application/knowledge-workspace/canvas-renderer.js

@@ -0,0 +1,36 @@
+export function renderObsidianCanvas(input) {
+    const nodes = [...input.nodes].sort(compareById).map(mapNode);
+    const edges = [...input.edges].sort(compareById).map(mapEdge);
+    return `${JSON.stringify({ nodes, edges }, null, 2)}\n`;
+}
+function mapNode(node) {
+    const base = {
+        id: node.id,
+        x: node.x,
+        y: node.y,
+        width: node.width ?? 360,
+        height: node.height ?? 220,
+    };
+    if (node.type === 'file') {
+        if (node.file === undefined || node.file.trim() === '') {
+            throw new Error(`Canvas file node requires a file path: ${node.id}`);
+        }
+        return { ...base, type: 'file', file: node.file };
+    }
+    return { ...base, type: 'text', text: node.label };
+}
+function mapEdge(edge) {
+    const mapped = {
+        id: edge.id,
+        fromNode: edge.fromNode,
+        fromSide: edge.fromSide ?? 'right',
+        toNode: edge.toNode,
+        toSide: edge.toSide ?? 'left',
+    };
+    if (edge.label !== undefined)
+        mapped.label = edge.label;
+    return mapped;
+}
+function compareById(a, b) {
+    return a.id.localeCompare(b.id);
+}

package/dist/application/knowledge-workspace/filesystem-workspace-port.js

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { assertSafeWorkspaceRelativePath, isGeneratedByVgxness, normalizeWorkspacePath, } from './workspace-port.js';
+export class FilesystemWorkspacePort {
+    vaultRoot;
+    workspaceRoot;
+    absoluteWorkspaceRoot;
+    constructor(options) {
+        this.vaultRoot = resolve(options.vaultRoot);
+        this.workspaceRoot = normalizeWorkspacePath(options.workspaceRoot ?? 'VGXNESS');
+        this.absoluteWorkspaceRoot = resolve(this.vaultRoot, this.workspaceRoot);
+    }
+    async status() {
+        return {
+            kind: 'knowledge-workspace-status',
+            status: existsSync(this.absoluteWorkspaceRoot) ? 'available' : 'unavailable',
+            mode: 'filesystem',
+            workspaceRoot: this.absoluteWorkspaceRoot,
+            diagnostics: existsSync(this.absoluteWorkspaceRoot) ? [] : ['Workspace root does not exist yet.'],
+            safety: { readOnly: true, writesNotes: false, deletesNotes: false, executesObsidianCommands: false },
+        };
+    }
+    async listNotes(input) {
+        const absolute = this.resolveContained(input.pathPrefix, false);
+        if (!existsSync(absolute))
+            return [];
+        const stat = statSync(absolute);
+        if (stat.isFile())
+            return [{ path: this.toWorkspacePath(absolute), type: 'file' }];
+        const entries = readdirSync(absolute, { withFileTypes: true });
+        const refs = [];
+        for (const entry of entries) {
+            const child = join(absolute, entry.name);
+            if (entry.isDirectory()) {
+                refs.push({ path: this.toWorkspacePath(child), type: 'directory' });
+                if (input.recursive ?? true)
+                    refs.push(...(await this.listNotes({ pathPrefix: this.toWorkspacePath(child), recursive: true })));
+            }
+            else {
+                refs.push({ path: this.toWorkspacePath(child), type: 'file' });
+            }
+        }
+        return refs.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async getNote(input) {
+        const absolute = this.resolveContained(input.path, false);
+        return { path: this.toWorkspacePath(absolute), content: readFileSync(absolute, 'utf8') };
+    }
+    async writeGeneratedNote(input) {
+        const absolute = this.resolveContained(input.path, true);
+        const exists = existsSync(absolute);
+        const previousContent = exists ? readFileSync(absolute, 'utf8') : undefined;
+        if (previousContent !== undefined && input.overwriteGeneratedOnly && !isGeneratedByVgxness(previousContent)) {
+            throw new Error(`Refusing to overwrite non-generated Obsidian note: ${this.toWorkspacePath(absolute)}`);
+        }
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, input.content, 'utf8');
+        const output = {
+            path: this.toWorkspacePath(absolute),
+            created: !exists,
+            currentSizeInBytes: Buffer.byteLength(input.content),
+        };
+        if (previousContent !== undefined)
+            output.previousSizeInBytes = Buffer.byteLength(previousContent);
+        return output;
+    }
+    async patchNote(input) {
+        const note = await this.getNote({ path: input.path });
+        const marker = `## ${input.section}`;
+        if (!note.content.includes(marker))
+            throw new Error(`Section not found: ${input.section}`);
+        const nextContent = applySimpleHeadingPatch(note.content, marker, input.operation, input.content);
+        return this.writeGeneratedNote({ path: note.path, content: nextContent, overwriteGeneratedOnly: false });
+    }
+    resolveContained(path, allowNonexistentLeaf) {
+        const relativePath = assertSafeWorkspaceRelativePath(path, this.workspaceRoot);
+        const absolute = resolve(this.vaultRoot, relativePath);
+        if (!isPathInside(absolute, this.absoluteWorkspaceRoot))
+            throw new Error(`Path must stay under ${this.absoluteWorkspaceRoot}: ${path}`);
+        if (!allowNonexistentLeaf && !existsSync(absolute))
+            throw new Error(`Note not found: ${relativePath}`);
+        return absolute;
+    }
+    toWorkspacePath(absolutePath) {
+        const relativePath = relative(this.vaultRoot, absolutePath).replaceAll(sep, '/');
+        return normalizeWorkspacePath(relativePath);
+    }
+}
+function applySimpleHeadingPatch(content, marker, operation, patch) {
+    if (operation === 'prepend')
+        return content.replace(marker, `${patch}\n${marker}`);
+    if (operation === 'append')
+        return content.replace(marker, `${marker}\n${patch}`);
+    return content.replace(marker, patch);
+}
+function isPathInside(path, root) {
+    return path === root || path.startsWith(`${root}${sep}`);
+}

package/dist/application/knowledge-workspace/markdown-renderer.js

@@ -0,0 +1,68 @@
+export function renderGeneratedFrontmatter(metadata) {
+    return [
+        '---',
+        'generated_by: vgxness',
+        `source_of_truth: ${metadata.sourceOfTruth}`,
+        'manual_edits: overwritten_on_export',
+        `transport: ${metadata.transport}`,
+        `generated_at: ${quoteYamlScalar(metadata.generatedAt)}`,
+        `project: ${quoteYamlScalar(metadata.project)}`,
+        '---',
+        '',
+    ].join('\n');
+}
+export function renderMemorySummaryMarkdown(input) {
+    const observations = [...input.observations].sort(compareMemoryItems);
+    const frontmatter = renderGeneratedFrontmatter({
+        generatedBy: 'vgxness',
+        sourceOfTruth: 'sqlite',
+        manualEdits: 'overwritten_on_export',
+        transport: input.transport ?? 'preview',
+        generatedAt: input.generatedAt,
+        project: input.project,
+    });
+    const rows = observations.map((item) => [item.scope, item.type, item.title, item.topicKey ?? '', item.updatedAt, item.preview].map(escapeTableCell).join(' | '));
+    return `${frontmatter}# ${input.project} Memory Summary\n\n> Generated by VGXNESS from SQLite memory previews. SQLite remains the source of truth; this note is a human-facing projection.\n\n${rows.length === 0
+        ? 'No memory observations matched this export.\n'
+        : ['| Scope | Type | Title | Topic Key | Updated | Preview |', '|---|---|---|---|---|---|', ...rows.map((row) => `| ${row} |`)].join('\n') + '\n'}`;
+}
+export function renderSddBoardMarkdown(input) {
+    const items = [...input.items].sort(compareSddItems);
+    const frontmatter = renderGeneratedFrontmatter({
+        generatedBy: 'vgxness',
+        sourceOfTruth: 'sqlite',
+        manualEdits: 'overwritten_on_export',
+        transport: input.transport ?? 'preview',
+        generatedAt: input.generatedAt,
+        project: input.project,
+    });
+    const rows = items.map((item) => [item.changeId, item.phase, item.state, item.updatedAt ?? '', item.notePath === undefined ? '' : `[[${item.notePath}]]`].map(escapeTableCell).join(' | '));
+    const grouped = groupSddItemsByState(items);
+    const summary = [...grouped.entries()]
+        .map(([state, stateItems]) => `- ${state}: ${stateItems.length}`)
+        .join('\n');
+    return `${frontmatter}# ${input.project} SDD Board\n\n> Generated by VGXNESS from SQLite SDD artifact/governance state. Obsidian does not prove acceptance, readiness, verification, or authorization.\n\n## Summary\n\n${summary || '- No SDD items matched this export.'}\n\n## Board\n\n${rows.length === 0
+        ? 'No SDD items matched this export.\n'
+        : ['| Change | Phase | State | Updated | Note |', '|---|---|---|---|---|', ...rows.map((row) => `| ${row} |`)].join('\n') + '\n'}`;
+}
+function compareMemoryItems(a, b) {
+    return b.updatedAt.localeCompare(a.updatedAt) || a.scope.localeCompare(b.scope) || a.type.localeCompare(b.type) || a.title.localeCompare(b.title);
+}
+function compareSddItems(a, b) {
+    return a.changeId.localeCompare(b.changeId) || a.phase.localeCompare(b.phase) || a.state.localeCompare(b.state);
+}
+function groupSddItemsByState(items) {
+    const groups = new Map();
+    for (const item of items) {
+        const existing = groups.get(item.state) ?? [];
+        existing.push(item);
+        groups.set(item.state, existing);
+    }
+    return groups;
+}
+function escapeTableCell(value) {
+    return value.replace(/\r?\n/g, '<br>').replace(/\|/g, '\\|').trim();
+}
+function quoteYamlScalar(value) {
+    return JSON.stringify(value);
+}

package/dist/application/knowledge-workspace/obsidian-export-service.js

@@ -0,0 +1,157 @@
+import { normalizeSddArtifact } from '../../domain/sdd/schema.js';
+import { renderGeneratedFrontmatter, renderMemorySummaryMarkdown, renderSddBoardMarkdown } from './markdown-renderer.js';
+export class KnowledgeWorkspaceExportService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async export(input) {
+        const status = await this.options.workspace.status();
+        if (status.status !== 'available') {
+            return { ok: false, error: { code: 'validation_failed', message: `Knowledge workspace unavailable: ${status.diagnostics.join('; ') || status.mode}` } };
+        }
+        const transport = status.mode;
+        const kinds = input.kind === 'all' ? ['docs', 'memory', 'sdd', 'canvas'] : [input.kind];
+        const exportedNotes = [];
+        for (const kind of kinds) {
+            if (kind === 'docs')
+                exportedNotes.push(await this.exportDocs(input.project, transport));
+            if (kind === 'memory') {
+                const memory = this.requireReadModel();
+                if (!memory.ok)
+                    return memory;
+                const exported = await this.exportMemorySummary({ project: input.project, transport, readModel: memory.value, ...(input.limit === undefined ? {} : { limit: input.limit }) });
+                if (!exported.ok)
+                    return exported;
+                exportedNotes.push(exported.value);
+            }
+            if (kind === 'sdd') {
+                const memory = this.requireReadModel();
+                if (!memory.ok)
+                    return memory;
+                const exported = await this.exportSdd({ project: input.project, transport, readModel: memory.value });
+                if (!exported.ok)
+                    return exported;
+                exportedNotes.push(...exported.value);
+            }
+            if (kind === 'canvas')
+                exportedNotes.push(await this.exportArchitectureCanvas(input.project));
+        }
+        return {
+            ok: true,
+            value: {
+                kind: 'knowledge-workspace-export',
+                project: input.project,
+                requestedKind: input.kind,
+                transport,
+                exportedNotes,
+                safety: {
+                    sqliteRemainsSourceOfTruth: true,
+                    overwritesGeneratedNotesOnly: true,
+                    exportsMemoryPreviewsOnly: true,
+                    infersSddAcceptanceFromObsidian: false,
+                },
+            },
+        };
+    }
+    async exportDocs(project, transport) {
+        const content = `${renderGeneratedFrontmatter({
+            generatedBy: 'vgxness',
+            sourceOfTruth: 'repository-docs',
+            manualEdits: 'overwritten_on_export',
+            transport,
+            generatedAt: this.now(),
+            project,
+        })}# ${project} Knowledge Workspace\n\nThis workspace is a human-facing projection generated by VGXNESS.\n\n## Boundaries\n\n- SQLite remains the source of truth for memory, SDD governance, runs, traces, and acceptance.\n- Obsidian is for review, planning, docs, boards, and canvas navigation.\n- Generated notes disclose that manual edits may be overwritten on export.\n`;
+        return toExportedNote(await this.options.workspace.writeGeneratedNote({ path: `VGXNESS/00 Home/${project} Knowledge Workspace.md`, content, overwriteGeneratedOnly: true }), 'docs');
+    }
+    async exportMemorySummary(input) {
+        const previews = input.readModel.searchObservationPreviewsNoTrace({ project: input.project, limit: input.limit ?? 50 });
+        if (!previews.ok)
+            return previews;
+        const content = renderMemorySummaryMarkdown({
+            project: input.project,
+            generatedAt: this.now(),
+            transport: input.transport,
+            observations: previews.value.map((observation) => ({
+                title: observation.title,
+                type: observation.type,
+                scope: observation.scope,
+                preview: observation.preview,
+                updatedAt: observation.updatedAt,
+                ...(observation.topicKey === undefined ? {} : { topicKey: observation.topicKey }),
+            })),
+        });
+        const result = await this.options.workspace.writeGeneratedNote({
+            path: `VGXNESS/06 Memory Summaries/${input.project}.md`,
+            content,
+            overwriteGeneratedOnly: true,
+        });
+        return { ok: true, value: toExportedNote(result, 'memory') };
+    }
+    async exportSdd(input) {
+        const artifacts = input.readModel.listArtifactsByTopicPrefixNoTrace(input.project, 'sdd/');
+        if (!artifacts.ok)
+            return artifacts;
+        const artifactNotes = [];
+        const boardItems = [];
+        for (const artifact of artifacts.value) {
+            const parsedTopic = parseSddTopicKey(artifact.topicKey);
+            if (parsedTopic === undefined)
+                continue;
+            const normalized = normalizeSddArtifact(artifact);
+            const notePath = `VGXNESS/03 SDD/${parsedTopic.change}/${parsedTopic.phase}.md`;
+            const content = `${renderGeneratedFrontmatter({
+                generatedBy: 'vgxness',
+                sourceOfTruth: 'sqlite',
+                manualEdits: 'overwritten_on_export',
+                transport: input.transport,
+                generatedAt: this.now(),
+                project: input.project,
+            })}# ${parsedTopic.change} / ${parsedTopic.phase}\n\n> Generated from SQLite SDD artifact state. Obsidian does not prove readiness or acceptance.\n\n## State\n\n- Status: ${normalized.metadata.status}\n- Accepted: ${normalized.metadata.status === 'accepted' ? 'yes' : 'no'}\n- Updated: ${artifact.updatedAt}\n\n## Artifact\n\n${artifact.content}\n`;
+            const result = await this.options.workspace.writeGeneratedNote({ path: notePath, content, overwriteGeneratedOnly: true });
+            artifactNotes.push(toExportedNote(result, 'sdd'));
+            boardItems.push({
+                changeId: parsedTopic.change,
+                phase: parsedTopic.phase,
+                state: normalized.metadata.status,
+                updatedAt: artifact.updatedAt,
+                notePath,
+            });
+        }
+        const board = renderSddBoardMarkdown({ project: input.project, generatedAt: this.now(), transport: input.transport, items: boardItems });
+        const boardResult = await this.options.workspace.writeGeneratedNote({
+            path: 'VGXNESS/08 Boards/SDD Board.md',
+            content: board,
+            overwriteGeneratedOnly: true,
+        });
+        return { ok: true, value: [...artifactNotes, toExportedNote(boardResult, 'sdd')] };
+    }
+    async exportArchitectureCanvas(project) {
+        const content = `${JSON.stringify({
+            nodes: [
+                { id: 'sqlite', type: 'text', text: 'SQLite\nOperational source of truth', x: 0, y: 0, width: 360, height: 180 },
+                { id: 'obsidian', type: 'text', text: 'Obsidian\nHuman-facing projection workspace', x: 520, y: 0, width: 360, height: 180 },
+            ],
+            edges: [{ id: 'project', fromNode: 'sqlite', fromSide: 'right', toNode: 'obsidian', toSide: 'left', label: 'project via MCP/export' }],
+        }, null, 2)}\n`;
+        return toExportedNote(await this.options.workspace.writeGeneratedNote({ path: `VGXNESS/07 Canvas/${project} Knowledge Architecture.canvas`, content, overwriteGeneratedOnly: true }), 'canvas');
+    }
+    requireReadModel() {
+        if (this.options.readModel !== undefined)
+            return { ok: true, value: this.options.readModel };
+        return { ok: false, error: { code: 'validation_failed', message: 'Knowledge export kind requires a SQLite read model' } };
+    }
+    now() {
+        return this.options.now?.() ?? new Date().toISOString();
+    }
+}
+function toExportedNote(result, kind) {
+    return { path: result.path, created: result.created, kind };
+}
+function parseSddTopicKey(topicKey) {
+    const match = /^sdd\/([^/]+)\/([^/]+)$/u.exec(topicKey);
+    if (match === null)
+        return undefined;
+    return { change: match[1], phase: match[2] };
+}