markdown-mindmap AGENTS.md

Agent guide

Canonical instructions for coding agents in this repo. CLAUDE.md and GEMINI.md are symlinks to this file, so every tool reads one source.

What this is

Leveled left-to-right mind maps from note frontmatter links, with two adapters over one shared core: an Obsidian plugin and a VS Code extension. One ```mindmap YAML block per map (see README.md). A block renders as one of three view types (view: map | gantt | kanban): the same collected + filtered tree laid out as a tree of cards, a gantt (bars by gantt.start/gantt.end, milestone diamonds), or a kanban board (columns by kanban.groupBy). Filters/search/collapse apply before layout, so they work in every view. A second block type, ```causalmap, renders causal-loop diagrams (systems-thinking graphs with automatic cycle detection) — Obsidian only for now.

Architecture

• src/core/ — pure core. No host coupling. Modules: config (types + defaults), helpers, collect, edges, visibility, layout-tree, layout-gantt, layout-kanban, views, render-model (buildRenderModel -> the serializable RenderModel both adapters draw; dispatches on the view type), export (HTML/Excalidraw export builders). All unit-tested. Shared by both adapters.
• src/graph.ts — re-exporting barrel over src/core/; every import path goes through it.
• src/causal.ts — pure causal-map core. Imports only from graph.ts. Signed-edge collection, cycle detection, loop polarity, force-directed layout. Same rules as the core: host-free, 100% covered.
• src/render/ — shared SVG renderer (renderer.ts draws a RenderModel into an injected document/SVG root for all three views; panzoom.ts owns pan/zoom/fit). The only DOM code outside the adapters; coverage-excluded like them, but lint-covered and bundled into both builds.
• src/obsidian/ — Obsidian adapter. main.ts (```mindmap blocks), causal.ts (```causalmap blocks), modals.ts (prompt/confirm/help/note dialogs) — the only files that import obsidian — plus svg.ts, a host-free element helper. Owns host I/O (vault read, resolver, code-block processor, YAML write-back), toolbar/state wiring, and exports. Builds main.js.
• src/vscode/ — VS Code adapter. extension.ts (host: reads workspace markdown, runs buildRenderModel, posts the RenderModel), webview.ts (bootstrap: shared renderer + pan/zoom + click-to-open). Builds dist/extension.js + dist/webview.js.
• styles.css — Obsidian theming via CSS variables. (VS Code styling is inline in the webview HTML shell, using --vscode-* vars.)
• test/ — vitest, exercising the core through plain NoteLike data (host-agnostic).