vgxness 1.20.13 → 1.20.15

package/dist/interfaces/cli/commands/knowledge-workspace-dispatcher.js

@@ -0,0 +1,252 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { normalizeSddArtifact } from '../../../domain/sdd/schema.js';
+import { renderGeneratedFrontmatter, renderMemorySummaryMarkdown, renderSddBoardMarkdown } from '../../../application/knowledge-workspace/markdown-renderer.js';
+import { renderObsidianCanvas } from '../../../application/knowledge-workspace/canvas-renderer.js';
+import { assertSafeWorkspaceRelativePath, isGeneratedByVgxness } from '../../../application/knowledge-workspace/workspace-port.js';
+import { MemoryService } from '../../../memory/memory-service.js';
+import { optionalNumberFlag, optionalStringFlag, requiredFlag } from '../cli-flags.js';
+import { jsonResult, resultFailure } from '../cli-helpers.js';
+import { okText, usageFailure, validationFailure } from '../cli-help.js';
+const defaultWorkspaceRoot = 'VGXNESS';
+const defaultFolders = [
+    '00 Home',
+    '01 PRDs',
+    '02 Architecture',
+    '03 SDD',
+    '04 Research',
+    '05 Decisions',
+    '06 Memory Summaries',
+    '07 Canvas',
+    '08 Boards',
+    '09 Release Notes',
+];
+export function runKnowledgeWorkspaceCommand(command, parsed, database, environment) {
+    const workspace = workspaceModeFlag(parsed.flags);
+    if (!workspace.ok)
+        return resultFailure(workspace);
+    if (command === 'status')
+        return runStatus(parsed, workspace.value, environment);
+    if (command === 'init')
+        return runInit(parsed, workspace.value, environment);
+    if (command === 'export')
+        return runExport(parsed, workspace.value, database, environment);
+    return usageFailure(`Unknown knowledge command: ${command}`);
+}
+function runStatus(parsed, workspace, environment) {
+    if (workspace === 'obsidian-mcp') {
+        return jsonOrText(parsed, obsidianMcpUnavailableStatus(), 'Obsidian MCP workspace: unavailable from standalone CLI. Configure Obsidian MCP in the agent host, or use --workspace filesystem --vault <path> for explicit fallback.\n');
+    }
+    const vault = vaultFlag(parsed.flags, environment);
+    if (!vault.ok)
+        return resultFailure(vault);
+    const workspaceRoot = resolve(vault.value, defaultWorkspaceRoot);
+    return jsonOrText(parsed, {
+        kind: 'knowledge-workspace-status',
+        status: existsSync(workspaceRoot) ? 'available' : 'unavailable',
+        mode: 'filesystem',
+        workspaceRoot,
+        diagnostics: existsSync(workspaceRoot) ? [] : ['Workspace root does not exist yet; run knowledge init.'],
+        safety: { readOnly: true, writesNotes: false, deletesNotes: false, executesObsidianCommands: false },
+    }, `${existsSync(workspaceRoot) ? 'available' : 'unavailable'} filesystem knowledge workspace: ${workspaceRoot}\n`);
+}
+function runInit(parsed, workspace, environment) {
+    if (workspace === 'obsidian-mcp') {
+        return jsonOrText(parsed, {
+            kind: 'knowledge-workspace-init',
+            workspace,
+            created: [],
+            manualActionRequired: true,
+            guidance: [
+                'Install and enable the Obsidian Local REST API plugin.',
+                'Configure an Obsidian MCP server in the agent host with OBSIDIAN_API_KEY stored outside the repo.',
+                'Scope OBSIDIAN_READ_PATHS and OBSIDIAN_WRITE_PATHS to VGXNESS where supported.',
+                'Keep OBSIDIAN_ENABLE_COMMANDS=false unless a human explicitly approves command execution.',
+            ],
+        }, 'Obsidian MCP init is manual: configure the Obsidian MCP server in the agent host with secrets outside the repo.\n');
+    }
+    const vault = vaultFlag(parsed.flags, environment);
+    if (!vault.ok)
+        return resultFailure(vault);
+    const root = resolve(vault.value, defaultWorkspaceRoot);
+    const created = [root, ...defaultFolders.map((folder) => resolve(root, folder))];
+    for (const path of created)
+        mkdirSync(path, { recursive: true });
+    return jsonOrText(parsed, { kind: 'knowledge-workspace-init', workspace, vaultRoot: vault.value, workspaceRoot: root, created }, `Initialized ${defaultWorkspaceRoot}/ in ${vault.value}\n`);
+}
+function runExport(parsed, workspace, database, environment) {
+    const project = requiredFlag(parsed.flags, 'project');
+    if (!project.ok)
+        return resultFailure(project);
+    const kind = exportKindFlag(parsed.flags);
+    if (!kind.ok)
+        return resultFailure(kind);
+    const limit = optionalNumberFlag(parsed.flags, 'limit');
+    if (!limit.ok)
+        return resultFailure(limit);
+    if (workspace === 'obsidian-mcp') {
+        return resultFailure(validationFailure('Obsidian MCP export requires an agent-host MCP client; standalone CLI cannot call host MCP tools yet. Use --workspace filesystem --vault <path> for explicit fallback, or run the sync from an MCP-capable agent host.'));
+    }
+    const vault = vaultFlag(parsed.flags, environment);
+    if (!vault.ok)
+        return resultFailure(vault);
+    if (database === undefined)
+        return resultFailure(validationFailure('Filesystem knowledge export requires a local SQLite database'));
+    const memory = new MemoryService(database);
+    const exported = exportFilesystemSync({
+        project: project.value,
+        requestedKind: kind.value,
+        vaultRoot: vault.value,
+        transport: 'filesystem',
+        memory,
+        ...(limit.value === undefined ? {} : { limit: limit.value }),
+    });
+    return jsonResult(exported);
+}
+function exportFilesystemSync(input) {
+    try {
+        const workspaceRoot = resolve(input.vaultRoot, defaultWorkspaceRoot);
+        if (!existsSync(workspaceRoot))
+            return validationFailure('Knowledge workspace root does not exist; run knowledge init first');
+        const kinds = input.requestedKind === 'all' ? ['docs', 'memory', 'sdd', 'canvas'] : [input.requestedKind];
+        const exportedNotes = [];
+        for (const kind of kinds) {
+            if (kind === 'docs')
+                exportedNotes.push(writeDocs({ project: input.project, vaultRoot: input.vaultRoot, transport: input.transport }));
+            if (kind === 'memory') {
+                const previews = input.memory.searchObservationPreviewsNoTrace({ project: input.project, limit: input.limit ?? 50 });
+                if (!previews.ok)
+                    return previews;
+                exportedNotes.push(writeMemory({ project: input.project, vaultRoot: input.vaultRoot, transport: input.transport, observations: previews.value }));
+            }
+            if (kind === 'sdd') {
+                const artifacts = input.memory.listArtifactsByTopicPrefixNoTrace(input.project, 'sdd/');
+                if (!artifacts.ok)
+                    return artifacts;
+                exportedNotes.push(...writeSdd({ project: input.project, vaultRoot: input.vaultRoot, transport: input.transport, artifacts: artifacts.value }));
+            }
+            if (kind === 'canvas')
+                exportedNotes.push(writeCanvas({ project: input.project, vaultRoot: input.vaultRoot }));
+        }
+        return {
+            ok: true,
+            value: {
+                kind: 'knowledge-workspace-export',
+                project: input.project,
+                requestedKind: input.requestedKind,
+                transport: input.transport,
+                exportedNotes,
+                safety: {
+                    sqliteRemainsSourceOfTruth: true,
+                    overwritesGeneratedNotesOnly: true,
+                    exportsMemoryPreviewsOnly: true,
+                    infersSddAcceptanceFromObsidian: false,
+                },
+            },
+        };
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: cause instanceof Error ? cause.message : String(cause), cause } };
+    }
+}
+function writeDocs(input) {
+    const content = `${renderGeneratedFrontmatter({ generatedBy: 'vgxness', sourceOfTruth: 'repository-docs', manualEdits: 'overwritten_on_export', transport: input.transport, generatedAt: new Date().toISOString(), project: input.project })}# ${input.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 { ...writeGeneratedFile(input.vaultRoot, `VGXNESS/00 Home/${input.project} Knowledge Workspace.md`, content), kind: 'docs' };
+}
+function writeMemory(input) {
+    const content = renderMemorySummaryMarkdown({
+        project: input.project,
+        generatedAt: new Date().toISOString(),
+        transport: input.transport,
+        observations: input.observations.map((observation) => ({
+            title: observation.title,
+            type: observation.type,
+            scope: observation.scope,
+            preview: observation.preview,
+            updatedAt: observation.updatedAt,
+            ...(observation.topicKey === undefined ? {} : { topicKey: observation.topicKey }),
+        })),
+    });
+    return { ...writeGeneratedFile(input.vaultRoot, `VGXNESS/06 Memory Summaries/${input.project}.md`, content), kind: 'memory' };
+}
+function writeSdd(input) {
+    const exported = [];
+    const boardItems = [];
+    for (const artifact of input.artifacts) {
+        const topic = parseSddTopicKey(artifact.topicKey);
+        if (topic === undefined)
+            continue;
+        const normalized = normalizeSddArtifact(artifact);
+        const notePath = `VGXNESS/03 SDD/${topic.change}/${topic.phase}.md`;
+        const content = `${renderGeneratedFrontmatter({ generatedBy: 'vgxness', sourceOfTruth: 'sqlite', manualEdits: 'overwritten_on_export', transport: input.transport, generatedAt: new Date().toISOString(), project: input.project })}# ${topic.change} / ${topic.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`;
+        exported.push({ ...writeGeneratedFile(input.vaultRoot, notePath, content), kind: 'sdd' });
+        boardItems.push({ changeId: topic.change, phase: topic.phase, state: normalized.metadata.status, updatedAt: artifact.updatedAt, notePath });
+    }
+    const board = renderSddBoardMarkdown({ project: input.project, generatedAt: new Date().toISOString(), transport: input.transport, items: boardItems });
+    exported.push({ ...writeGeneratedFile(input.vaultRoot, 'VGXNESS/08 Boards/SDD Board.md', board), kind: 'sdd' });
+    return exported;
+}
+function writeCanvas(input) {
+    const content = renderObsidianCanvas({
+        nodes: [
+            { id: 'sqlite', type: 'text', label: 'SQLite\nOperational source of truth', x: 0, y: 0 },
+            { id: 'obsidian', type: 'text', label: 'Obsidian\nHuman-facing projection workspace', x: 520, y: 0 },
+        ],
+        edges: [{ id: 'project', fromNode: 'sqlite', toNode: 'obsidian', label: 'project via MCP/export' }],
+    });
+    return { ...writeGeneratedFile(input.vaultRoot, `VGXNESS/07 Canvas/${input.project} Knowledge Architecture.canvas`, content), kind: 'canvas' };
+}
+function writeGeneratedFile(vaultRoot, path, content) {
+    const safePath = assertSafeWorkspaceRelativePath(path, defaultWorkspaceRoot);
+    const workspaceRoot = resolve(vaultRoot, defaultWorkspaceRoot);
+    const absolute = resolve(vaultRoot, safePath);
+    if (absolute !== workspaceRoot && !absolute.startsWith(`${workspaceRoot}${sep}`))
+        throw new Error(`Path must stay under ${workspaceRoot}: ${path}`);
+    const created = !existsSync(absolute);
+    if (!created) {
+        const existing = readFileSync(absolute, 'utf8');
+        if (!isGeneratedByVgxness(existing))
+            throw new Error(`Refusing to overwrite non-generated Obsidian note: ${safePath}`);
+    }
+    mkdirSync(dirname(absolute), { recursive: true });
+    writeFileSync(absolute, content, 'utf8');
+    return { path: safePath, created };
+}
+function workspaceModeFlag(flags) {
+    const workspace = optionalStringFlag(flags, 'workspace') ?? 'obsidian-mcp';
+    if (workspace === 'obsidian-mcp' || workspace === 'filesystem')
+        return { ok: true, value: workspace };
+    return validationFailure('--workspace must be obsidian-mcp or filesystem');
+}
+function exportKindFlag(flags) {
+    const kind = optionalStringFlag(flags, 'kind') ?? 'all';
+    if (kind === 'docs' || kind === 'memory' || kind === 'sdd' || kind === 'canvas' || kind === 'all')
+        return { ok: true, value: kind };
+    return validationFailure('--kind must be docs, memory, sdd, canvas, or all');
+}
+function vaultFlag(flags, environment) {
+    const vault = requiredFlag(flags, 'vault');
+    if (!vault.ok)
+        return vault;
+    return { ok: true, value: resolve(environment.cwd, vault.value) };
+}
+function jsonOrText(parsed, value, text) {
+    return parsed.flags.json === true ? { exitCode: 0, stdout: `${JSON.stringify(value, null, 2)}\n`, stderr: '' } : okText(text);
+}
+function parseSddTopicKey(topicKey) {
+    const match = /^sdd\/([^/]+)\/([^/]+)$/u.exec(topicKey);
+    if (match === null)
+        return undefined;
+    return { change: match[1], phase: match[2] };
+}
+function obsidianMcpUnavailableStatus() {
+    return {
+        kind: 'knowledge-workspace-status',
+        status: 'unavailable',
+        mode: 'obsidian-mcp',
+        workspaceRoot: defaultWorkspaceRoot,
+        diagnostics: ['Standalone CLI cannot call agent-host Obsidian MCP tools yet.'],
+        guidance: ['Configure Obsidian MCP in the agent host.', 'Use --workspace filesystem --vault <path> for explicit fallback.'],
+        safety: { readOnly: true, writesNotes: false, deletesNotes: false, executesObsidianCommands: false },
+    };
+}

package/dist/interfaces/cli/dispatcher.js

@@ -5,7 +5,7 @@ import { runBootAgentSeedUpgrade } from '../../agents/boot-upgrade.js';
 import { databasePathFor, parseArgs, requiredFlag } from './cli-flags.js';
 import { okText, usageFailure, visibleHelpText } from './cli-help.js';
 import { openCliDatabase, resultFailure } from './cli-helpers.js';
-import { runAgentCommand, runApprovalsCommand, runCodeContextCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runHomeTuiCommand, runInitCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runProductNextCommand, runProductResumeCommand, runProductStatusCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupReinstallApplyCommand, runSetupRollbackCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
+import { runAgentCommand, runApprovalsCommand, runCodeContextCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runHomeTuiCommand, runInitCommand, runKnowledgeWorkspaceCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runProductNextCommand, runProductResumeCommand, runProductStatusCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupReinstallApplyCommand, runSetupRollbackCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
 import { canRunInteractiveTui } from './tui/terminal-capabilities.js';
 const _promptBuffers = new WeakMap();
 const require = createRequire(import.meta.url);
@@ -51,6 +51,9 @@ export function dispatchCli(argv, environment) {
     }
     if (area === 'memory' && command === 'import')
         return runMemoryImportCommand(parsed, environment);
+    if (area === 'knowledge' && (command === 'status' || command === 'init' || parsed.flags.workspace !== 'filesystem')) {
+        return runKnowledgeWorkspaceCommand(command, parsed, undefined, environment);
+    }
     const selectedDatabasePath = databasePathFor(parsed.flags, environment);
     if (!selectedDatabasePath.ok)
         return resultFailure(selectedDatabasePath);
@@ -71,6 +74,8 @@ export function dispatchCli(argv, environment) {
             return runSubagentCommand(command, parsed, opened.value, environment);
         if (area === 'memory')
             return runMemoryCommand(command, parsed, opened.value);
+        if (area === 'knowledge')
+            return runKnowledgeWorkspaceCommand(command, parsed, opened.value, environment);
         if (area === 'approvals')
             return runApprovalsCommand(command, parsed, opened.value);
         if (area === 'runs')
@@ -148,6 +153,9 @@ function validateCommand(area, command) {
     if (area === 'memory') {
         return command === 'save' || command === 'search' || command === 'import' ? { ok: true } : { ok: false, message: `Unknown memory command: ${command}` };
     }
+    if (area === 'knowledge') {
+        return command === 'status' || command === 'init' || command === 'export' ? { ok: true } : { ok: false, message: `Unknown knowledge command: ${command}` };
+    }
     if (area === 'runs') {
         return command === 'create' ||
             command === 'list' ||

package/docs/architecture.md

@@ -471,7 +471,7 @@ The envelope is always `installable:false` and `readOnly:true`. It does **not**
 
 ### OpenCode manager orchestration
 
-The checked-in OpenCode default config and `seeds/agents/agent-seed-v1.json` define `vgxness-manager` as an MCP-first orchestrator. The manager should use `vgxness_session_restore` with the project and workspace directory when starting, resuming, or recovering context, then use SDD artifact/status tools, memory tools, agent resolution, run/preflight tools, and read-only payload/profile previews before delegating substantial work to exact capability subagents. Before ending, pausing, handing off, or compacting, it should call `vgxness_session_close` with the current session id, actor `manager`, and an actionable summary; if no current session id is available, it must not invent one and should preserve the summary in its final response. Its OpenCode `permission.task` remains deny-by-default: `*` is denied and only the canonical capability subagent names plus legacy `vgxness-sdd-*` aliases are allowed explicitly. The seed/default prompts are self-contained and do not require external provider-native skill files; optional guidance should live in VGXNESS registry assets unless a future provider-native integration is explicitly designed.
+The checked-in OpenCode default config and `seeds/agents/agent-seed-v1.json` define `vgxness-manager` as an MCP-first orchestrator. The manager should use `vgxness_session_restore` with the project and workspace directory when starting, resuming, or recovering context, then use SDD artifact/status tools, memory tools, agent resolution, run/preflight tools, and read-only payload/profile previews before delegating substantial work to exact capability subagents. Before ending, pausing, handing off, or compacting, it should call `vgxness_session_close` with the current session id, actor `manager`, and an actionable summary; if no current session id is available, it must not invent one and should preserve the summary in its final response. Its OpenCode `permission.task` remains deny-by-default: `*` is denied and only the canonical capability subagent names are allowed explicitly. The seed/default prompts are self-contained and do not require external provider-native skill files; optional guidance should live in VGXNESS registry assets unless a future provider-native integration is explicitly designed.
 
 ## Run lifecycle
 

package/docs/cli.md

@@ -208,6 +208,19 @@ bun run package:bun:evidence
 
 When reporting a Bun failure, include the Bun version, OS/CPU, Node version, whether `bun install --frozen-lockfile` completed, which `bun run verify:*` command failed, and whether the error points to `bun:sqlite`, migration application, package evidence, or another install step.
 
+## Knowledge workspace CLI
+
+VGXNESS exposes one grouped knowledge surface instead of mirroring every Obsidian MCP note operation:
+
+```bash
+vgxness knowledge status --workspace obsidian-mcp --json
+vgxness knowledge init --workspace obsidian-mcp --json
+vgxness knowledge init --workspace filesystem --vault /path/to/vault --json
+vgxness knowledge export --project vgxness --workspace filesystem --vault /path/to/vault --kind docs|memory|sdd|canvas|all --db /path/to/memory.sqlite
+```
+
+`obsidian-mcp` is the preferred workspace mode for agent-host integrations. The standalone CLI cannot directly call host MCP tools, so `knowledge export --workspace obsidian-mcp` fails fast with configuration guidance. `filesystem` writes are available only when the caller explicitly passes `--workspace filesystem --vault <path>`.
+
 ## Repository quick path
 
 These examples are for a source checkout. They use repo-local seeds and `bun run cli:bun -- ...`; they are not installed-package quick-start commands.

package/docs/glossary.md

@@ -32,7 +32,7 @@ The canonical installed CLI/MCP runtime and verification path. Required `>= 1.3.
 
 ## Canonical agent manifest
 
-The built-in, validated manifest that defines the manager agent and generic capability subagents (`vgxness-explore`, `vgxness-propose`, `vgxness-requirements`, `vgxness-design`, `vgxness-plan`, `vgxness-apply`, `vgxness-verify`, `vgxness-archive`, `vgxness-init`, and `vgxness-onboard`). Legacy `vgxness-sdd-*` task names remain callable as compatibility aliases, but the canonical provider-facing names are no longer SDD-prefixed. Lives in `src/domain/agents/canonical-agent-manifest.ts` with old-path compatibility through `src/agents/canonical-agent-manifest.ts`. `promptContractVersion` increments on breaking contract changes.
+The built-in, validated manifest that defines the manager agent and generic capability subagents (`vgxness-explore`, `vgxness-propose`, `vgxness-requirements`, `vgxness-design`, `vgxness-plan`, `vgxness-apply`, `vgxness-verify`, `vgxness-archive`, `vgxness-init`, and `vgxness-onboard`). Legacy `vgxness-sdd-*` task names are no longer provider-callable; the canonical provider-facing names are not SDD-prefixed. Lives in `src/domain/agents/canonical-agent-manifest.ts` with old-path compatibility through `src/agents/canonical-agent-manifest.ts`. `promptContractVersion` increments on breaking contract changes.
 
 ## Change (SDD)
 

package/docs/knowledge-workspace.md

@@ -0,0 +1,135 @@
+# Knowledge Workspace
+
+VGXNESS separates operational memory from human-facing knowledge work.
+
+SQLite remains the authoritative local state engine for agent memory, SDD artifacts, sessions, runs, traces, approvals, and governance state. Obsidian is a human workspace for reading, planning, visualizing, and curating derived views of that state.
+
+## Source-of-truth boundary
+
+| Layer | Source of truth? | Purpose |
+|---|---:|---|
+| SQLite | Yes | Operational memory, SDD artifact state, acceptance, run history, traces, search indexes, revisions, and governance state. |
+| Obsidian vault | No | Human-facing docs, research, boards, canvas maps, and curated summaries. |
+| Obsidian MCP | No | Controlled transport for VGXNESS/agents to read, create, patch, search, and open Obsidian notes. |
+| Repository docs | Yes for shipped product docs | Versioned product documentation and implementation guidance. |
+
+The practical rule is:
+
+```text
+If an agent needs it to retrieve or decide quickly, store it in SQLite.
+If a human needs it to read, organize, or visualize, project it into Obsidian.
+If both need it, SQLite stays authoritative and Obsidian gets a generated or curated projection.
+```
+
+## What belongs in SQLite
+
+Use SQLite-backed VGXNESS services for:
+
+- project and personal memory observations;
+- observation revisions and topic-key upserts;
+- SDD artifacts and their governance metadata;
+- explicit human artifact acceptance/reopen state;
+- run records, events, checkpoints, approvals, and traces;
+- skill/agent registry state;
+- any future search or embedding indexes used by agents.
+
+Memory observations should stay compact and reusable. Full transcripts, raw logs, secrets, and large documents should not be copied into memory just because they exist in Obsidian or the repo.
+
+## What belongs in Obsidian
+
+Use Obsidian for human-facing material:
+
+- PRDs and product notes;
+- roadmaps and release planning;
+- architecture notes and diagrams;
+- Obsidian Canvas maps;
+- SDD board projections;
+- research notes and curated decision writeups;
+- memory summaries that are safe for human review.
+
+Generated Obsidian files are projections. They do not approve SDD artifacts, verify work, grant permissions, or replace SQLite state.
+
+## Recommended vault layout
+
+VGXNESS writes under a dedicated `VGXNESS/` folder in the configured vault:
+
+```text
+VGXNESS/
+├── 00 Inbox/
+├── 01 Product/
+│   ├── PRD.md
+│   ├── Roadmap.md
+│   └── Glossary.md
+├── 02 Architecture/
+│   ├── Architecture.md
+│   ├── Storage.md
+│   ├── Module Boundaries.md
+│   └── Architecture.canvas
+├── 03 SDD/
+│   ├── Active/<change-id>/
+│   └── Archive/
+├── 04 Research/
+├── 05 Decisions/
+├── 06 Memory Summaries/
+│   ├── Project Memory.md
+│   └── Personal Patterns.md
+├── 07 Canvas/
+│   ├── Knowledge System.canvas
+│   └── SDD Flow.canvas
+├── 08 Boards/
+│   ├── SDD Board.md
+│   └── Release Board.md
+└── 09 Release Notes/
+```
+
+Generated notes should include frontmatter similar to:
+
+```yaml
+---
+generated_by: vgxness
+source_of_truth: sqlite
+manual_edits: overwritten_on_export
+transport: obsidian-mcp
+---
+```
+
+VGXNESS should overwrite only generated files carrying this marker. Curated human notes should either live outside generated paths or omit the generated marker.
+
+## Obsidian MCP transport
+
+The preferred integration path is an Obsidian MCP server. VGXNESS should use a workspace port so the product is not coupled to a specific community server package:
+
+```text
+SQLite services
+  -> Markdown/Canvas renderers
+  -> KnowledgeWorkspacePort
+     -> Obsidian MCP adapter (preferred)
+     -> filesystem adapter (tests/offline fallback)
+  -> Obsidian vault / VGXNESS/
+```
+
+The Obsidian MCP adapter may map high-level VGXNESS operations to MCP tools such as note read/write/search/patch/frontmatter operations. VGXNESS should not mirror every Obsidian MCP tool into its own MCP surface; if needed later, expose one grouped sync operation instead.
+
+See [Obsidian MCP integration](./obsidian-mcp.md) for setup and safety guidance.
+
+## CLI workflow
+
+Use the grouped `knowledge` command for high-level workspace operations:
+
+```bash
+vgxness knowledge status --workspace obsidian-mcp --json
+vgxness knowledge init --workspace obsidian-mcp --json
+vgxness knowledge init --workspace filesystem --vault /path/to/vault --json
+vgxness knowledge export --project vgxness --workspace filesystem --vault /path/to/vault --kind all --db /path/to/memory.sqlite
+```
+
+Standalone CLI export intentionally does not call host-configured Obsidian MCP tools directly yet. When `--workspace obsidian-mcp` is selected for export, it reports an actionable configuration error. Use `--workspace filesystem --vault <path>` only as an explicit fallback/test path, or run the eventual grouped sync from an MCP-capable agent host.
+
+## Safety invariants
+
+- SQLite is authoritative for SDD readiness, artifact acceptance, verification, and permissions.
+- Obsidian exports are projections and may be regenerated.
+- Destructive or opaque Obsidian command execution stays disabled by default.
+- Obsidian MCP read/write allowlists should be scoped to `VGXNESS/` where supported.
+- Memory exports should use safe summaries/previews by default, not raw transcripts or traces.
+- Read-only/status commands must not write notes, provider config, or repository files.

package/docs/obsidian-mcp.md

@@ -0,0 +1,130 @@
+# Obsidian MCP Integration
+
+VGXNESS can use an Obsidian MCP server as the preferred transport for its human-facing knowledge workspace. SQLite remains the source of truth; the Obsidian vault receives generated or curated projections for human review.
+
+## Recommended server for the first spike
+
+Use `obsidian-mcp-server` for the initial implementation spike unless a blocker appears during integration testing.
+
+At the time this document was written, the npm package `obsidian-mcp-server@3.2.8` exposes note read/list/search/write/append/patch/replace/frontmatter/tag/open-in-ui tools over STDIO or Streamable HTTP.
+
+## Prerequisites
+
+- Obsidian desktop is installed and the target vault is open.
+- Obsidian community plugin **Local REST API** v4 or newer is installed and enabled.
+- A Local REST API key is generated in Obsidian settings.
+- The Local REST API HTTP endpoint is reachable, normally `http://127.0.0.1:27123`.
+- Node/npm or Bun is available for launching the MCP server.
+
+Keep the Local REST API key out of git. Store it in the invoking client configuration or local secret store.
+
+## Hermes native MCP configuration
+
+Hermes can connect to the Obsidian MCP server directly. Add a server entry similar to this to the active Hermes profile config and restart Hermes:
+
+```yaml
+mcp_servers:
+  obsidian:
+    command: "npx"
+    args: ["-y", "obsidian-mcp-server@latest"]
+    env:
+      MCP_TRANSPORT_TYPE: "stdio"
+      MCP_LOG_LEVEL: "info"
+      OBSIDIAN_API_KEY: "<local-rest-api-key>"
+      OBSIDIAN_BASE_URL: "http://127.0.0.1:27123"
+      OBSIDIAN_READ_PATHS: "VGXNESS"
+      OBSIDIAN_WRITE_PATHS: "VGXNESS"
+      OBSIDIAN_ENABLE_COMMANDS: "false"
+    timeout: 120
+    connect_timeout: 60
+```
+
+After restart, Hermes discovers tools with names prefixed by the server name, for example:
+
+```text
+mcp_obsidian_obsidian_get_note
+mcp_obsidian_obsidian_search_notes
+mcp_obsidian_obsidian_write_note
+mcp_obsidian_obsidian_patch_note
+mcp_obsidian_obsidian_manage_frontmatter
+mcp_obsidian_obsidian_manage_tags
+mcp_obsidian_obsidian_open_in_ui
+```
+
+Use the real discovered names from `hermes mcp list` / `hermes mcp test obsidian`; exact names depend on the MCP server and Hermes tool naming normalization.
+
+## VGXNESS integration contract
+
+VGXNESS should treat Obsidian MCP as an adapter behind a small workspace port:
+
+```ts
+interface KnowledgeWorkspacePort {
+  status(): Promise<KnowledgeWorkspaceStatus>;
+  listNotes(input: { pathPrefix: string; recursive?: boolean }): Promise<KnowledgeWorkspaceNoteRef[]>;
+  getNote(input: { path: string }): Promise<KnowledgeWorkspaceNote>;
+  writeGeneratedNote(input: { path: string; content: string; overwriteGeneratedOnly: boolean }): Promise<KnowledgeWorkspaceWriteResult>;
+  patchNote(input: { path: string; section: string; operation: 'append' | 'prepend' | 'replace'; content: string }): Promise<KnowledgeWorkspaceWriteResult>;
+  openInUi?(input: { path: string }): Promise<void>;
+}
+```
+
+The adapter should translate these operations to the configured Obsidian MCP server. The rest of VGXNESS should call the port, not raw filesystem writes and not package-specific MCP tool functions directly.
+
+## Generated-note policy
+
+Generated files should include frontmatter that makes the source and overwrite behavior obvious:
+
+```yaml
+---
+generated_by: vgxness
+source_of_truth: sqlite
+manual_edits: overwritten_on_export
+transport: obsidian-mcp
+---
+```
+
+VGXNESS may overwrite generated files only when the existing note contains `generated_by: vgxness`. It should not overwrite curated human notes by default.
+
+## Path and command safety
+
+For the first version:
+
+- scope `OBSIDIAN_READ_PATHS` and `OBSIDIAN_WRITE_PATHS` to `VGXNESS` when the MCP server supports path allowlists;
+- leave `OBSIDIAN_ENABLE_COMMANDS=false`;
+- do not call delete or command-palette execution tools;
+- keep status/preview operations non-mutating;
+- return the Obsidian note paths written by export operations;
+- export memory summaries/previews, not traces, raw transcripts, provider config, or secrets.
+
+## Smoke test checklist
+
+With Obsidian open and Local REST API configured:
+
+```bash
+hermes mcp test obsidian
+```
+
+Then verify the configured client can:
+
+1. list notes under `VGXNESS/`;
+2. create `VGXNESS/00 Inbox/VGXNESS MCP Smoke.md`;
+3. read the created note;
+4. patch a section in that note;
+5. refuse or fail a write outside `VGXNESS/` when path allowlists are enabled.
+
+Remove the smoke note or leave it under `00 Inbox/` as visible test evidence.
+
+## Relationship to VGXNESS MCP
+
+Do not mirror the Obsidian MCP server's detailed note tools inside VGXNESS MCP. If agents need a VGXNESS-facing operation later, add one grouped tool such as:
+
+```ts
+knowledge_workspace_sync({
+  project: string,
+  target: 'obsidian-mcp',
+  kind: 'docs' | 'memory' | 'sdd' | 'all',
+  mode: 'preview' | 'write' | 'open-ui'
+})
+```
+
+That keeps VGXNESS responsible for product-level orchestration while Obsidian MCP remains responsible for vault-level note operations.