vgxness 1.20.13 → 1.20.15

package/README.md

@@ -269,6 +269,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/opencode/install/client-install-opencode-contract.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { canonicalCapabilitySubagentLegacyAliases } from '../../../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.';
@@ -141,7 +142,8 @@ export function findConflictingVgxnessAgents(config, agentPlan, input = {}) {
     if (!agentPlan.installsAgents || !isRecord(config.agent))
         return [];
     const defaults = createOpenCodeDefaultAgentConfig(input).agents;
-    return agentPlan.agentNames.filter((name) => Object.hasOwn(config.agent, name) && !deepEqual(config.agent[name], defaults[name]));
+    const managedNames = [...agentPlan.agentNames, ...Object.keys(canonicalCapabilitySubagentLegacyAliases)];
+    return managedNames.filter((name) => Object.hasOwn(config.agent, name) && !deepEqual(config.agent[name], defaults[name]));
 }
 function deepEqual(left, right) {
     if (Object.is(left, right))
@@ -199,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,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { canonicalCapabilitySubagentLegacyAliases } from '../../../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';
@@ -73,7 +74,10 @@ function mergeVgxnessOpenCodeConfig(config, server, installsAgents, effectiveMan
         const defaults = createOpenCodeDefaultAgentConfig({ effectiveManagerInstructions });
         merged.instructions = mergeOpenCodeInstructions(config.instructions);
         merged.default_agent = defaults.defaultAgent;
-        merged.agent = { ...(isRecord(config.agent) ? config.agent : {}), ...defaults.agents };
+        const existingAgents = isRecord(config.agent) ? { ...config.agent } : {};
+        for (const legacyName of Object.keys(canonicalCapabilitySubagentLegacyAliases))
+            delete existingAgents[legacyName];
+        merged.agent = { ...existingAgents, ...defaults.agents };
     }
     merged.permission = { ...(isRecord(config.permission) ? config.permission : {}), bash: 'ask' };
     return merged;
@@ -216,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/application/agents/agent-resolver.js

@@ -1,3 +1,4 @@
+import { canonicalCapabilitySubagentLegacyAliases } from '../../domain/agents/canonical-agent-manifest.js';
 import { normalizeSddPhaseInput } from '../../sdd/schema.js';
 import { agentLookupContexts } from './agent-lookup-contexts.js';
 export class AgentResolver {
@@ -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] };
+}

package/dist/application/knowledge-workspace/obsidian-mcp-workspace-port.js

@@ -0,0 +1,109 @@
+import { assertSafeWorkspaceRelativePath, isGeneratedByVgxness, } from './workspace-port.js';
+export class ObsidianMcpWorkspacePort {
+    options;
+    workspaceRoot;
+    constructor(options) {
+        this.options = options;
+        this.workspaceRoot = options.workspaceRoot ?? 'VGXNESS';
+    }
+    async status() {
+        try {
+            await this.options.client.callTool('obsidian_list_notes', { path: this.workspaceRoot, recursive: false });
+            return {
+                kind: 'knowledge-workspace-status',
+                status: 'available',
+                mode: 'obsidian-mcp',
+                workspaceRoot: this.workspaceRoot,
+                diagnostics: [],
+                safety: { readOnly: true, writesNotes: false, deletesNotes: false, executesObsidianCommands: false },
+            };
+        }
+        catch (cause) {
+            return {
+                kind: 'knowledge-workspace-status',
+                status: 'unavailable',
+                mode: 'obsidian-mcp',
+                workspaceRoot: this.workspaceRoot,
+                diagnostics: [`Obsidian MCP unavailable: ${cause instanceof Error ? cause.message : String(cause)}`],
+                safety: { readOnly: true, writesNotes: false, deletesNotes: false, executesObsidianCommands: false },
+            };
+        }
+    }
+    async listNotes(input) {
+        const path = assertSafeWorkspaceRelativePath(input.pathPrefix, this.workspaceRoot);
+        const result = await this.options.client.callTool('obsidian_list_notes', { path, recursive: input.recursive ?? true });
+        return extractNoteRefs(result);
+    }
+    async getNote(input) {
+        const path = assertSafeWorkspaceRelativePath(input.path, this.workspaceRoot);
+        const result = await this.options.client.callTool('obsidian_get_note', { path, format: 'content' });
+        return { path, content: extractContent(result) };
+    }
+    async writeGeneratedNote(input) {
+        const path = assertSafeWorkspaceRelativePath(input.path, this.workspaceRoot);
+        const existing = await this.readExisting(path);
+        if (existing !== undefined && input.overwriteGeneratedOnly && !isGeneratedByVgxness(existing.content)) {
+            throw new Error(`Refusing to overwrite non-generated Obsidian note: ${path}`);
+        }
+        const result = await this.options.client.callTool('obsidian_write_note', { path, content: input.content, overwrite: existing !== undefined });
+        return extractWriteResult(result, path, existing === undefined);
+    }
+    async patchNote(input) {
+        const path = assertSafeWorkspaceRelativePath(input.path, this.workspaceRoot);
+        const result = await this.options.client.callTool('obsidian_patch_note', {
+            path,
+            section: input.section,
+            operation: input.operation,
+            content: input.content,
+        });
+        return extractWriteResult(result, path, false);
+    }
+    async openInUi(input) {
+        const path = assertSafeWorkspaceRelativePath(input.path, this.workspaceRoot);
+        await this.options.client.callTool('obsidian_open_in_ui', { path, failIfMissing: true });
+    }
+    async readExisting(path) {
+        try {
+            return await this.getNote({ path });
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function extractContent(result) {
+    if (typeof result === 'string')
+        return result;
+    if (isRecord(result)) {
+        if (typeof result.content === 'string')
+            return result.content;
+        if (typeof result.result === 'string')
+            return result.result;
+        const note = result.note;
+        if (isRecord(note) && typeof note.content === 'string')
+            return note.content;
+    }
+    return JSON.stringify(result);
+}
+function extractNoteRefs(result) {
+    const entries = isRecord(result) && Array.isArray(result.entries) ? result.entries : Array.isArray(result) ? result : [];
+    return entries.flatMap((entry) => {
+        if (!isRecord(entry) || typeof entry.path !== 'string')
+            return [];
+        const type = entry.type === 'directory' ? 'directory' : 'file';
+        return [{ path: entry.path, type }];
+    });
+}
+function extractWriteResult(result, path, defaultCreated) {
+    if (!isRecord(result))
+        return { path, created: defaultCreated };
+    const output = { path, created: typeof result.created === 'boolean' ? result.created : defaultCreated };
+    if (typeof result.previousSizeInBytes === 'number')
+        output.previousSizeInBytes = result.previousSizeInBytes;
+    if (typeof result.currentSizeInBytes === 'number')
+        output.currentSizeInBytes = result.currentSizeInBytes;
+    return output;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

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

@@ -0,0 +1,20 @@
+export function assertSafeWorkspaceRelativePath(path, workspaceRoot = 'VGXNESS') {
+    const normalized = normalizeWorkspacePath(path);
+    const normalizedRoot = normalizeWorkspacePath(workspaceRoot);
+    if (normalizedRoot === '' || normalizedRoot === '.' || normalizedRoot.includes('..'))
+        throw new Error('Invalid workspace root');
+    if (normalized !== normalizedRoot && !normalized.startsWith(`${normalizedRoot}/`)) {
+        throw new Error(`Path must stay under ${normalizedRoot}/: ${path}`);
+    }
+    return normalized;
+}
+export function isGeneratedByVgxness(content) {
+    return /^---[\s\S]*?^generated_by:\s*vgxness\s*$/m.test(content);
+}
+export function normalizeWorkspacePath(path) {
+    const normalized = path.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+/g, '/').trim();
+    const parts = normalized.split('/').filter((part) => part.length > 0 && part !== '.');
+    if (parts.some((part) => part === '..'))
+        throw new Error(`Path traversal is not allowed: ${path}`);
+    return parts.join('/');
+}

package/dist/application/provider-setup/provider-doctor.js

@@ -470,7 +470,7 @@ function delegationCheck(config) {
     const missing = vgxnessOpenCodeSddSubagents.filter((name) => permission[name] !== 'allow');
     if (missing.length > 0)
         return { id: 'opencode-delegation-permissions', status: 'fail', detail: `Manager cannot delegate to expected subagents: ${missing.join(', ')}.` };
-    return { id: 'opencode-delegation-permissions', status: 'pass', detail: 'Manager task permission is deny-by-default and allows exact capability subagents plus legacy SDD aliases.' };
+    return { id: 'opencode-delegation-permissions', status: 'pass', detail: 'Manager task permission is deny-by-default and allows exact canonical capability subagents only.' };
 }
 function promptContractCheck(config, expected) {
     const agents = isRecord(config?.agent) ? config.agent : undefined;

package/dist/domain/agents/canonical-agent-manifest.js

@@ -144,7 +144,6 @@ export function createCanonicalOpenCodeSddTaskPermissions() {
     return Object.fromEntries([
         ['*', 'deny'],
         ...canonicalCapabilitySubagentNames.map((name) => [name, 'allow']),
-        ...Object.keys(canonicalCapabilitySubagentLegacyAliases).map((name) => [name, 'allow']),
     ]);
 }
 export function createCanonicalOpenCodeSddMcpToolPermissions() {

package/dist/domain/knowledge-workspace/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/cli/cli-help.js

@@ -20,6 +20,9 @@ Areas:
   verification plan --type docs-only|test-only|cli|mcp|sdd-storage|provider-setup|package-release|workflow-runs|code-context [--json]
   verification report save --project <name> --change <id> --file <report.json> [--db <path>] [--json]
   verification report get --project <name> --change <id> [--db <path>] [--json]
+  knowledge status [--workspace obsidian-mcp|filesystem] [--vault <path>] [--json]
+  knowledge init [--workspace obsidian-mcp|filesystem] [--vault <path>] [--json]
+  knowledge export --project <name> [--workspace obsidian-mcp|filesystem] [--vault <path>] [--kind docs|memory|sdd|canvas|all] [--limit <n>] [--db <path>]
   Status answers "where am I?" with the human front-door cockpit.
   Next answers "what should I do now?" with a shorter next-action view.
   Resume answers "how do I continue interrupted work?" with run inspection guidance.
@@ -29,6 +32,7 @@ Areas:
   Doctor defaults to human-readable output; pass --json for automation.
   Verification plans are read-only recommendations only; they never execute commands, write provider config, persist results, mutate SDD artifacts, or infer acceptance.
   Verification reports are manual file-only SDD verify draft artifacts; save/get never execute commands, contact providers, write provider config, or auto-accept verification.
+  Knowledge commands project SQLite/repository state into an Obsidian workspace. Obsidian MCP is the preferred host transport; standalone CLI export fails fast without an MCP-capable host and only writes filesystem fallback when --workspace filesystem --vault <path> is explicit.
 
   agents register --project <name> --name <name> --description <text> --instructions <text>
   agents register --file <agent.json>
@@ -69,7 +73,7 @@ Areas:
   mcp doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>]
   MCP setup preview is read-only; it does not install or write .opencode/, .claude/, or provider config.
   Without --db, MCP install and setup commands use the vgxness global default database; pass --db .vgx/memory.sqlite for project-local compatibility.
-  OpenCode install defaults to user-global scope and installs mcp.vgxness plus top-level permission.bash=ask, vgxness-manager with bash=deny and native repo tools disabled, and hidden capability agents such as vgxness-explore/vgxness-plan/vgxness-verify with legacy vgxness-sdd-* task aliases; use --mcp-only for legacy MCP-only config.
+  OpenCode install defaults to user-global scope and installs mcp.vgxness plus top-level permission.bash=ask, vgxness-manager with bash=deny and native repo tools disabled, and hidden capability agents such as vgxness-explore/vgxness-plan/vgxness-verify with canonical task permissions only; use --mcp-only for legacy MCP-only config.
   Use --overwrite-vgxness (alias --reinstall) to reinstall only VGXNESS-managed OpenCode entries while preserving unrelated config; --yes is still required to write.
   It writes only after --yes. VGX-managed provider configuration is user-global only for OpenCode and Claude; the OpenCode target is $HOME/.config/opencode/opencode.json.
   Project/local provider files are external/manual diagnostics and will not be written by VGXNESS. Plans are read-only; applies refuse unsafe existing user-global config and create backups before merge.

package/dist/interfaces/cli/commands/index.js

@@ -2,6 +2,7 @@ export { runCodeContextCommand } from './code-context-dispatcher.js';
 export { runAgentCommand, runSkillCommand, runSubagentCommand } from './agent-skill-dispatcher.js';
 export { runDefaultInteractiveEntrypoint } from './interactive-entrypoint-dispatcher.js';
 export { runDoctorAliasCommand, runMcpDoctorCommand, runMcpDoctorOpenCodeCommand, runMcpInstallCommand, runMcpSetupCommand } from './mcp-dispatcher.js';
+export { runKnowledgeWorkspaceCommand } from './knowledge-workspace-dispatcher.js';
 export { runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runSddCommand } from './memory-sdd-dispatcher.js';
 export { runApprovalsCommand, runPermissionsCommand, runRunsCommand } from './run-permission-dispatcher.js';
 export { applySetupPlanInput, collectRunDetails, collectRunInsights, createSetupLifecycleService, promptSetupWizard, readSetupStatus, runHomeTuiCommand, runInitCommand, runSetupApplyCommand, runSetupBackupCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupReinstallApplyCommand, runSetupReinstallCommand, runSetupRollbackCommand, setupMcpEvidence, setupPlanInputFromFlags, } from './setup-dispatcher.js';