Human Viewer Compatibility

Feature Overview [edit]

The vault is designed to be opened directly by standard Markdown tools — Obsidian, VS Code Markdown preview, and similar viewers — with no plugin, binary, or GUI runtime required by spec-memo. Viewer support is purely passive: the vault layout and record schemas are standards-compliant Markdown with YAML frontmatter, so a human can browse the same knowledge an agent reads over MCP.

This page documents the file-format compatibility contract. The MCP/CLI surfaces remain the only supported way to write records; viewers are read-only.

Business Rules & Logic [edit]

• Record files are <slug>.md containing YAML frontmatter followed by Markdown body. parseRecord reads them; serializeRecord writes them with trimmed body content.
• Directory layout is stable and human-navigable: projects/<projectId>/ holds INDEX.md, TRAPS.md, DECISIONS.md, PROMPTS.md, SESSIONS.md, WIKI.md, and kind subdirectories (traps/, decisions/, specs/, plans/, logs/, reviews/, scratch/, plus prompt/session stores).
• Compiled views link to records with standard relative Markdown links (text is the record id, target is the kind subdir plus <id>.md, for example a link to the traps/trap-id.md file), and also print an Obsidian-compatible wikilink token as inline code, e.g. ` [[trap-id]] `. Resolvers therefore work in both plain Markdown viewers and Obsidian without configuration.
• The per-project WIKI.md uses project-relative Markdown links to each record (target ./<subdir>/<id>.md) plus ` [[id]] wikilink tokens, and links the compiled views INDEX.md, TRAPS.md, and DECISIONS.md` in the same directory.
• Compiled views are regenerated, never hand-edited: AUTO-GENERATED material is overwritten by rebuildCompiledViews. WIKI.md carries <!-- AUTO-GENERATED BY spec-memo wiki — DO NOT EDIT DIRECTLY --> semantics.
• No viewer-specific plugins, runtime binaries, or proprietary dependencies are required. Opening the vault root as an Obsidian vault or VS Code workspace must not error on vault contents.
• Relative link targets are project-relative files that exist on disk; links do not point outside the vault project directory.
• Frontmatter uses ordinary YAML scalars and arrays (id, kind, title, status, severity, pathPatterns, tags, occurrences, lastSeen, hits, created, updated), which generic Markdown viewers render as a metadata block rather than executable content.
• The default vault root is ~/.spec-memo (overridable via SPEC_MEMO_ROOT or --vaultRoot); a human can open that directory directly. config.json and memo.sqlite are non-Markdown files that viewers simply ignore.
• Compiled views are plain Markdown with a scannable title and bullet lists; trap/decision entries show status, path patterns, and the [[id]] token inline. A reader can follow either the relative link (plain Markdown) or the wikilink token (Obsidian).
• Viewer access is read-only in spirit: the agent contract treats MCP/CLI as the only writer, and compiled views are regenerated so hand edits are overwritten.

Technical Architecture [edit]

• src/schema.ts: parseRecord / serializeRecord define the on-disk Markdown + frontmatter contract.
• src/compiler.ts: rebuildCompiledViews(projectId, vaultRoot) writes TRAPS.md, DECISIONS.md, PROMPTS.md, SESSIONS.md, and INDEX.md. Trap and decision bullets include a relative Markdown link and a quoted [[id]] wikilink; supersedes relations are rendered as [[...]] tokens.
• src/wiki.ts: renderWikiMarkdown builds WIKI.md from a template.md, mdLink emits a relative Markdown link whose target is ./<subdir>/<id>.md, and regenerateWiki persists it. splitWikiSections / readWikiSection parse level-2 sections for section reads.
• src/vault.ts: RECORD_SUBDIRS and the vault structure define the human-visible tree; record subdirectories are keyed by kind via getSubdirForKind.
• Reads for viewers go through memo wiki (print/regenerate WIKI.md) and memo get; there is no viewer UI process in the core engine.
• memo wiki --project <id> prints an existing WIKI.md; memo wiki --regenerate rebuilds it from vault sources. readWikiFile, parseLastGenerated, and readWikiSection support human and programmatic section reads.
• insertWikiLink-style tokens are emitted as inline-code ` [[id]] ` so they are copy-paste friendly and do not create dangling links when a record is archived; the companion relative link always points at the real record file.

Provenance: 0015-viewer.spec.md.