structured-context 0.10.0 → 0.11.0

package/dist/plugins/markdown/extract-content-links.js

@@ -0,0 +1,144 @@
+import { toString as mdastToString } from 'mdast-util-to-string';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+/**
+ * Parse an Obsidian wikilink inner string into its components.
+ * Handles: [[target]], [[target#anchor]], [[target|alias]], [[target#anchor|alias]]
+ */
+function parseWikilinkInner(inner) {
+    // Alias: [[target|alias]] or [[target#anchor|alias]]
+    const pipeIdx = inner.indexOf('|');
+    let core = inner;
+    let displayText;
+    if (pipeIdx >= 0) {
+        core = inner.slice(0, pipeIdx);
+        const alias = inner.slice(pipeIdx + 1).trim();
+        if (alias)
+            displayText = alias;
+    }
+    // Anchor: [[target#anchor]] or [[target#^block]]
+    const hashIdx = core.indexOf('#');
+    if (hashIdx >= 0) {
+        const target = core.slice(0, hashIdx).trim();
+        const anchor = core.slice(hashIdx + 1).trim() || undefined;
+        return { target, anchor, displayText };
+    }
+    return { target: core.trim(), displayText };
+}
+/**
+ * Extract wikilinks (and Obsidian embed wikilinks) from a plain text string.
+ * Matches [[target]], ![[target]], [[target#anchor]], [[target|alias]], etc.
+ */
+function extractWikilinksFromText(text) {
+    const links = [];
+    for (const match of text.matchAll(/(!?)\[\[([^\]]+)\]\]/g)) {
+        const isEmbed = match[1] === '!';
+        const inner = match[2];
+        const { target, anchor, displayText } = parseWikilinkInner(inner);
+        if (!target)
+            continue;
+        links.push({
+            text: displayText ?? target,
+            target,
+            action: isEmbed ? 'embed' : 'link',
+            ...(anchor !== undefined ? { anchor } : {}),
+            linkSyntax: 'wikilink',
+        });
+    }
+    return links;
+}
+/**
+ * Recursively walk an mdast subtree and collect all links.
+ * Handles standard markdown link/image nodes and scans text nodes for wikilinks.
+ */
+export function extractLinksFromAstNode(node) {
+    const links = [];
+    function walk(n) {
+        switch (n.type) {
+            case 'link': {
+                const linkNode = n;
+                links.push({
+                    text: mdastToString(linkNode),
+                    target: linkNode.url,
+                    action: 'link',
+                    linkSyntax: 'markdown',
+                });
+                // Don't recurse into children — they are display text, not link targets
+                break;
+            }
+            case 'image': {
+                const imgNode = n;
+                links.push({
+                    text: imgNode.alt ?? '',
+                    target: imgNode.url,
+                    action: 'embed',
+                    linkSyntax: 'markdown',
+                });
+                break;
+            }
+            case 'text': {
+                // Remark does not parse wikilinks natively; scan text nodes for [[...]] patterns
+                links.push(...extractWikilinksFromText(n.value));
+                break;
+            }
+            default: {
+                if ('children' in n) {
+                    for (const child of n.children) {
+                        walk(child);
+                    }
+                }
+                break;
+            }
+        }
+    }
+    walk(node);
+    return links;
+}
+/**
+ * Extract all links from a raw markdown body string.
+ * Parses the full document and collects links from every node in the tree.
+ */
+export function extractLinksFromBody(body) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
+    return extractLinksFromAstNode(tree);
+}
+/**
+ * Build the set of field names that serve as graph edges (hierarchy + relationship fields).
+ * Used to exclude edge fields from frontmatter link extraction.
+ */
+export function getEdgeFieldNames(metadata) {
+    const fields = new Set();
+    for (const level of metadata.hierarchy?.levels ?? []) {
+        fields.add(level.field);
+        if (level.selfRefField)
+            fields.add(level.selfRefField);
+    }
+    for (const rel of metadata.relationships ?? []) {
+        fields.add(rel.field);
+    }
+    return fields;
+}
+/**
+ * Extract links from frontmatter data fields, excluding known graph edge fields.
+ * Parses each string value as markdown (via mdast) to keep link extraction consistent
+ * with body content parsing — handles wikilinks, markdown links, images, and bare URLs.
+ */
+export function extractLinksFromFrontmatter(data, edgeFields) {
+    const links = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (edgeFields.has(key))
+            continue;
+        if (typeof value === 'string') {
+            links.push(...extractLinksFromBody(value));
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                if (typeof item === 'string') {
+                    links.push(...extractLinksFromBody(item));
+                }
+            }
+        }
+    }
+    return links;
+}

package/dist/plugins/markdown/index.js

@@ -2,7 +2,6 @@ import { statSync } from 'node:fs';
 import { PLUGIN_PREFIX } from '../util';
 import { readSpaceDirectory, readSpaceOnAPage } from './read-space';
 import { renderBullets } from './render-bullets';
-import { renderMermaid } from './render-mermaid';
 import { templateSync } from './template-sync';
 const TYPE_INFERENCE_CONFIG_SCHEMA = {
     type: 'object',
@@ -37,15 +36,10 @@ export const markdownPlugin = {
     parse,
     templateSync,
     render: {
-        formats: [
-            { name: 'bullets', description: 'Indented bullet list' },
-            { name: 'mermaid', description: 'Mermaid graph TD diagram' },
-        ],
+        formats: [{ name: 'bullets', description: 'Indented bullet list' }],
         render(_context, graph, { format }) {
             if (format === 'bullets')
                 return renderBullets(graph);
-            if (format === 'mermaid')
-                return renderMermaid(graph);
             throw new Error(`Unknown markdown render format: "${format}"`);
         },
     },

package/dist/plugins/markdown/parse-embedded.js

@@ -3,6 +3,7 @@ import { toString as mdastToString } from 'mdast-util-to-string';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
+import { extractLinksFromAstNode } from './extract-content-links';
 import { applyFieldMap, coerceDates } from './util';
 /** Type values that identify a space_on_a_page container (not themselves space nodes). */
 export const ON_A_PAGE_TYPES = ['ost_on_a_page', 'space_on_a_page'];
@@ -191,6 +192,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             schemaData,
             linkTargets,
             type,
+            contentLinks: [],
         };
         nodes.push(newNode);
         if (parentFieldAppend) {
@@ -230,6 +232,7 @@ export function extractEmbeddedNodes(body, options) {
         schemaData: { type: 'space_on_a_page' },
         linkTargets: [],
         type: 'space_on_a_page',
+        contentLinks: [],
     };
     const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
     // In typed-page mode: stack starts with the page's own virtual entry (depth 0).
@@ -471,6 +474,7 @@ export function extractEmbeddedNodes(body, options) {
                 schemaData,
                 linkTargets,
                 type,
+                contentLinks: [],
             };
             // Push to stack BEFORE resolving semantic parent — stack[-2] is the correct parent.
             const refTarget = linkTargets[0] ?? title;
@@ -608,6 +612,7 @@ export function extractEmbeddedNodes(body, options) {
                             schemaData,
                             linkTargets,
                             type: rowTypeStr,
+                            contentLinks: [],
                         };
                         nodes.push(rowNode);
                         if (tableParentFieldAppend) {
@@ -640,6 +645,8 @@ export function extractEmbeddedNodes(body, options) {
                 Object.assign(activeNode.schemaData, allFields);
                 if (remainingText)
                     appendContent(activeNode, remainingText);
+                activeNode.contentLinks ??= [];
+                activeNode.contentLinks.push(...extractLinksFromAstNode(child));
             }
             else if (child.type === 'code' && child.lang?.trim() === 'yaml') {
                 const code = child;
@@ -656,6 +663,8 @@ export function extractEmbeddedNodes(body, options) {
             }
             else {
                 appendContent(activeNode, mdastToString(child));
+                activeNode.contentLinks ??= [];
+                activeNode.contentLinks.push(...extractLinksFromAstNode(child));
             }
         }
     }

package/dist/plugins/markdown/read-space.js

@@ -3,6 +3,7 @@ import { basename, join, resolve } from 'node:path';
 import fg from 'fast-glob';
 import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
+import { extractLinksFromBody, extractLinksFromFrontmatter, getEdgeFieldNames } from './extract-content-links';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
 import { applyFieldMap, coerceDates, inferTypeFromPath } from './util';
 export function readSpaceOnAPage(context) {
@@ -42,6 +43,7 @@ export async function readSpaceDirectory(context, options) {
     const absoluteTemplateDir = templateDir ? resolve(templateDir) : undefined;
     const typeInferenceCfg = mdCfg.typeInference;
     const knownTypes = typeInferenceCfg?.mode !== 'off' ? extractSchemaTypeNames(context.schema, context.schemaRefRegistry) : undefined;
+    const edgeFields = getEdgeFieldNames(metadata);
     const files = await fg('**/*.md', { cwd: directory, followSymbolicLinks: true });
     const nodes = [];
     const parseIssues = [];
@@ -93,6 +95,7 @@ export async function readSpaceDirectory(context, options) {
             schemaData: { title, ...data },
             linkTargets: [title, fileBase],
             type: pageType,
+            contentLinks: [...extractLinksFromFrontmatter(data, edgeFields), ...extractLinksFromBody(parsed.content)],
         });
         if (!ON_A_PAGE_TYPES.includes(pageType)) {
             const { nodes: embedded, terminatedHeadings } = extractEmbeddedNodes(parsed.content, {

package/dist/plugins/mermaid/index.d.ts

@@ -0,0 +1,2 @@
+import type { StructuredContextPlugin } from '../util';
+export declare const mermaidPlugin: StructuredContextPlugin;

package/dist/plugins/mermaid/index.js

@@ -0,0 +1,14 @@
+import { PLUGIN_PREFIX } from '../util';
+import { renderMermaid } from './render-mermaid';
+export const mermaidPlugin = {
+    name: `${PLUGIN_PREFIX}mermaid`,
+    configSchema: { type: 'object', additionalProperties: false },
+    render: {
+        formats: [{ name: 'graph', description: 'Mermaid graph TD diagram' }],
+        render(_context, graph, { format }) {
+            if (format === 'graph')
+                return renderMermaid(graph);
+            throw new Error(`Unknown mermaid render format: "${format}"`);
+        },
+    },
+};

package/dist/plugins/{markdown → mermaid}/render-mermaid.js

@@ -1,3 +1,13 @@
+const LEVEL_PALETTE = [
+    { fill: '#ff9999', stroke: '#ff0000' },
+    { fill: '#99ccff', stroke: '#0066cc' },
+    { fill: '#99ff99', stroke: '#00cc00' },
+    { fill: '#ffcc99', stroke: '#cc9900' },
+    { fill: '#cc99ff', stroke: '#6600cc' },
+    { fill: '#ff99cc', stroke: '#cc0066' },
+    { fill: '#99ffff', stroke: '#009999' },
+    { fill: '#ffff99', stroke: '#cccc00' },
+];
 function escapeMermaidString(str) {
     return str.replace(/"/g, '"');
 }
@@ -5,20 +15,13 @@ function safeNodeId(id) {
     return id.replace(/[^a-zA-Z0-9_-]/g, '_');
 }
 export function renderMermaid(graph) {
-    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet } = graph;
+    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet, levels } = graph;
     let mmd = 'graph TD\n';
-    mmd += '  classDef vision fill:#ff9999,stroke:#ff0000,stroke-width:2px\n';
-    mmd += '  classDef mission fill:#99ccff,stroke:#0066cc,stroke-width:2px\n';
-    mmd += '  classDef goal fill:#99ff99,stroke:#00cc00,stroke-width:2px\n';
-    mmd += '  classDef opportunity fill:#ffcc99,stroke:#cc9900,stroke-width:2px\n';
-    mmd += '  classDef solution fill:#cc99ff,stroke:#6600cc,stroke-width:2px\n';
-    mmd += '  classDef identified fill:#f0f0f0,stroke:#999999,stroke-dasharray: 5 5\n';
-    mmd += '  classDef wondering fill:#fff0cc,stroke:#cccc00,stroke-dasharray: 5 5\n';
-    mmd += '  classDef exploring fill:#ffcc99,stroke:#cc9900,stroke-dasharray: 5 5\n';
-    mmd += '  classDef active fill:#99ff99,stroke:#00cc00,stroke-width:2px\n';
-    mmd += '  classDef paused fill:#ffcc99,stroke:#cc9900,stroke-width:2px\n';
-    mmd += '  classDef completed fill:#ccccff,stroke:#6666cc,stroke-width:2px\n';
-    mmd += '  classDef archived fill:#e0e0e0,stroke:#999999,stroke-width:2px\n';
+    for (let i = 0; i < levels.length; i++) {
+        const level = levels[i];
+        const color = LEVEL_PALETTE[i % LEVEL_PALETTE.length];
+        mmd += `  classDef ${level.type} fill:${color.fill},stroke:${color.stroke},stroke-width:2px\n`;
+    }
     const addedNodes = new Set();
     function addNodeAndChildren(node) {
         const nodeId = node.title;
@@ -26,13 +29,11 @@ export function renderMermaid(graph) {
             return;
         addedNodes.add(nodeId);
         const type = node.resolvedType;
-        const status = node.schemaData.status;
         const priority = node.schemaData.priority;
         const label = priority ? `${nodeId} (${priority})` : nodeId;
-        const className = `${type}_${status}`;
         const safeId = safeNodeId(nodeId);
         const escapedLabel = escapeMermaidString(label);
-        mmd += `  ${safeId}["${escapedLabel}"]:::${className}\n`;
+        mmd += `  ${safeId}["${escapedLabel}"]:::${type}\n`;
         const nodeChildren = children.get(nodeId) ?? [];
         for (const child of nodeChildren) {
             const childTitle = child.title;

package/dist/{integrations → plugins}/miro/cache.d.ts

@@ -1,4 +1,4 @@
-import type { SpaceNode } from '../../types';
+import type { SpaceNode } from '../../api';
 export interface CachedNode {
     miroCardId: string;
     contentHash: string;

package/dist/plugins/miro/index.d.ts

@@ -0,0 +1,2 @@
+import { type StructuredContextPlugin } from '../../api';
+export declare const miroPlugin: StructuredContextPlugin;

package/dist/plugins/miro/index.js

@@ -0,0 +1,27 @@
+import { PLUGIN_PREFIX } from '../../api';
+import { miroSync } from './sync';
+export const miroPlugin = {
+    name: `${PLUGIN_PREFIX}miro`,
+    configSchema: {
+        type: 'object',
+        properties: {
+            boardId: { type: 'string' },
+            frameId: { type: 'string' },
+        },
+        additionalProperties: false,
+    },
+    render: {
+        formats: [{ name: 'board', description: 'Sync space to Miro board' }],
+        async render(context, graph, { format, data }) {
+            if (format === 'board') {
+                const options = {
+                    newFrame: data?.newFrame,
+                    dryRun: data?.dryRun,
+                    verbose: data?.verbose,
+                };
+                return await miroSync(context, graph, options);
+            }
+            throw new Error(`Unknown miro render format: "${format}"`);
+        },
+    },
+};

package/dist/{integrations → plugins}/miro/layout.d.ts

@@ -1,4 +1,4 @@
-import type { HierarchyLevel, SpaceNode } from '../../types';
+import type { HierarchyLevel, SpaceNode } from '../../api';
 export declare const CARD_WIDTH = 320;
 export interface LayoutResult {
     positions: Map<string, {
@@ -25,4 +25,4 @@ export interface LayoutResult {
 export declare function layoutNewCards(newNodes: SpaceNode[], existingPositions: Map<string, {
     x: number;
     y: number;
-}>, hierarchyLevels: HierarchyLevel[]): LayoutResult;
+}>, hierarchyLevels: readonly HierarchyLevel[]): LayoutResult;

package/dist/{integrations → plugins}/miro/layout.js

@@ -3,18 +3,6 @@ const CARD_HEIGHT = 160;
 const H_GAP = 40;
 const V_GAP = 60;
 const FRAME_PADDING = 60;
-/**
- * DEPRECATED - likely not needed after migration to render plugin and SpaceGraph
- * Build a depth map from hierarchy levels.
- * The position in the hierarchy array determines the depth.
- */
-function buildDepthMap(hierarchyLevels) {
-    const depthMap = new Map();
-    for (const [i, level] of hierarchyLevels.entries()) {
-        depthMap.set(level.type, i);
-    }
-    return depthMap;
-}
 /**
  * Compute positions for new cards only. Existing cards keep their Miro positions.
  * New cards are laid out in rows grouped by OST type depth, starting below
@@ -25,8 +13,6 @@ function buildDepthMap(hierarchyLevels) {
  * Returns positions and a bounding box covering all cards (for frame sizing).
  */
 export function layoutNewCards(newNodes, existingPositions, hierarchyLevels) {
-    // Build depth map from hierarchy levels (position in hierarchy = depth)
-    const depthMap = buildDepthMap(hierarchyLevels);
     // Find the lowest y among existing cards
     let lowestY = 0;
     for (const pos of existingPositions.values()) {
@@ -35,10 +21,11 @@ export function layoutNewCards(newNodes, existingPositions, hierarchyLevels) {
         }
     }
     const startY = existingPositions.size > 0 ? lowestY + V_GAP * 2 : 0;
-    // Group new nodes by depth
+    // Group new nodes by depth (position in hierarchy levels array)
     const byDepth = new Map();
     for (const node of newNodes) {
-        const depth = depthMap.get(node.schemaData.type) ?? depthMap.size;
+        const idx = hierarchyLevels.findIndex((l) => l.type === node.schemaData.type);
+        const depth = idx === -1 ? hierarchyLevels.length : idx;
         if (!byDepth.has(depth))
             byDepth.set(depth, []);
         byDepth.get(depth)?.push(node);

package/dist/{integrations → plugins}/miro/styles.d.ts

@@ -1,4 +1,4 @@
-import type { HierarchyLevel, SpaceNode } from '../../types';
+import type { HierarchyLevel, SpaceNode } from '../../api';
 /**
  * Get card color based on type and hierarchy levels.
  * Colors are assigned from palette based on level position.
@@ -6,6 +6,6 @@ import type { HierarchyLevel, SpaceNode } from '../../types';
  * @param type - The node's type string
  * @param hierarchyLevels - Hierarchy levels from metadata
  */
-export declare function getCardColor(type: string, hierarchyLevels: HierarchyLevel[]): string;
+export declare function getCardColor(type: string, hierarchyLevels: readonly HierarchyLevel[]): string;
 export declare function buildCardTitle(node: SpaceNode): string;
 export declare function buildCardDescription(node: SpaceNode): string;

package/dist/plugins/miro/sync.d.ts

@@ -0,0 +1,7 @@
+import type { PluginContext, SpaceGraph } from '../../api';
+export interface SyncOptions {
+    newFrame?: string;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export declare function miroSync(context: PluginContext, graph: SpaceGraph, options: SyncOptions): Promise<string>;

package/dist/{integrations → plugins}/miro/sync.js

@@ -1,50 +1,34 @@
-import { updateSpaceField } from '../../config';
-import { readSpace } from '../../read/read-space';
-import { buildSpaceGraph } from '../../space-graph';
 import { computeMiroCardHash, computeNodeHash, loadCache, saveCache } from './cache';
 import { MiroClient, MiroNotFoundError } from './client';
 import { CARD_WIDTH, layoutNewCards } from './layout';
 import { buildCardDescription, buildCardTitle, getCardColor } from './styles';
-export async function miroSync(context, options) {
+export async function miroSync(context, graph, options) {
     const token = process.env.MIRO_TOKEN;
-    if (!token) {
-        console.error('MIRO_TOKEN environment variable is required');
-        process.exit(1);
-    }
-    const { space, schema: { metadata }, } = context;
+    if (!token)
+        throw new Error('MIRO_TOKEN environment variable is required');
+    const { space } = context;
+    const boardId = context.pluginConfig.boardId;
+    const configuredFrameId = context.pluginConfig.frameId;
     // 1. Resolve board
-    if (!space.miroBoardId) {
-        console.error(`No miroBoardId configured for space "${space.name}".`);
-        console.error('Add miroBoardId to the space entry in config.');
-        process.exit(1);
-    }
-    const boardId = space.miroBoardId;
+    if (!boardId)
+        throw new Error(`No boardId configured for space "${space.name}". Add boardId to the miro plugin config in the space entry.`);
     // 2. Resolve frame
-    if (!space.miroFrameId && !options.newFrame) {
-        console.error('No miroFrameId in space config. Pass --new-frame "Title" to create one.');
-        process.exit(1);
-    }
-    // 3. Load space nodes (load before creating frame so we can calculate size)
-    let nodes;
-    ({ nodes } = await readSpace(context));
+    if (!configuredFrameId && !options.newFrame)
+        throw new Error('No frameId in miro plugin config. Pass --new-frame "Title" to create one.');
+    // 3. Filter to hierarchy nodes only (graph already built by caller)
+    const nodes = [...graph.nodes.values()].filter((n) => graph.hierarchyTitles.has(n.title));
     if (nodes.length === 0) {
-        console.log('No space nodes found.');
-        return;
+        return 'No space nodes found.';
     }
-    // Filter to hierarchy nodes only
-    const levels = metadata.hierarchy?.levels ?? [];
-    const { nonHierarchy, hierarchyTitles: hierarchyNodeTitles } = buildSpaceGraph(nodes, levels);
-    // Filter nodes to only hierarchy nodes
-    nodes = nodes.filter((n) => hierarchyNodeTitles.has(n.title));
-    if (options.verbose && nonHierarchy.length > 0) {
-        console.log(`Excluded ${nonHierarchy.length} non-hierarchy nodes from sync`);
+    if (options.verbose && graph.nonHierarchy.length > 0) {
+        console.log(`Excluded ${graph.nonHierarchy.length} non-hierarchy nodes from sync`);
     }
     const client = new MiroClient(boardId, token);
     let frameId;
     let layoutOffset = null;
     if (options.newFrame) {
         // Calculate layout bounds to size the frame appropriately
-        const { bounds } = layoutNewCards(nodes, new Map(), levels);
+        const { bounds } = layoutNewCards(nodes, new Map(), graph.levels);
         const frameWidth = Math.max(1600, bounds.maxX - bounds.minX);
         const frameHeight = Math.max(1200, bounds.maxY - bounds.minY);
         // Miro positions child items relative to the parent frame's top-left corner.
@@ -69,12 +53,12 @@ export async function miroSync(context, options) {
             });
             frameId = frame.id;
             console.log(`Created frame "${options.newFrame}" (${frameId}) - size: ${finalFrameWidth}x${finalFrameHeight}`);
-            updateSpaceField(space.name, 'miroFrameId', frameId);
-            console.log(`Saved miroFrameId to config`);
+            context.callbacks?.persistConfig?.({ frameId });
+            console.log(`Saved frameId to miro plugin config`);
         }
     }
     else {
-        frameId = space.miroFrameId;
+        frameId = configuredFrameId;
     }
     // 4. Load cache
     const cache = loadCache(boardId, frameId);
@@ -171,7 +155,7 @@ export async function miroSync(context, options) {
         }
     }
     // Compute positions for new cards
-    const { positions: newPositions } = layoutNewCards(newNodes, existingPositions, levels);
+    const { positions: newPositions } = layoutNewCards(newNodes, existingPositions, graph.levels);
     // 7. Create new cards
     let createdCount = 0;
     for (const node of newNodes) {
@@ -201,7 +185,7 @@ export async function miroSync(context, options) {
                 title: buildCardTitle(node),
                 description: buildCardDescription(node),
             },
-            style: { cardTheme: getCardColor(type, levels) },
+            style: { cardTheme: getCardColor(type, graph.levels) },
             position: { x: pos.x, y: pos.y, origin: 'center' },
             parent: { id: frameId },
             geometry: { width: CARD_WIDTH },
@@ -247,7 +231,7 @@ export async function miroSync(context, options) {
                         title: buildCardTitle(node),
                         description: buildCardDescription(node),
                     },
-                    style: { cardTheme: getCardColor(type, levels) },
+                    style: { cardTheme: getCardColor(type, graph.levels) },
                     position: { x: 0, y: 0, origin: 'center' },
                     parent: { id: frameId },
                     geometry: { width: CARD_WIDTH },
@@ -341,7 +325,5 @@ export async function miroSync(context, options) {
     if (!options.dryRun)
         saveCache(cache);
     // Summary
-    console.log(`\n${prefix}Sync complete:`);
-    console.log(`  Cards: ${createdCount} created, ${updatedCount} updated, ${skippedCount} unchanged`);
-    console.log(`  Connectors: ${connectorsCreated} created, ${connectorsDeleted} deleted`);
+    return `\n${prefix}Sync complete:\n  Cards: ${createdCount} created, ${updatedCount} updated, ${skippedCount} unchanged\n  Connectors: ${connectorsCreated} created, ${connectorsDeleted} deleted`;
 }

package/dist/plugins/util.d.ts

@@ -5,9 +5,16 @@ export declare const PLUGIN_PREFIX = "sctx-";
 export declare const CONFIG_PLUGINS_DIR = "plugins";
 /** Normalize a plugin name to its canonical prefixed form. */
 export declare function normalizePluginName(name: string): string;
+/** Shorten a plugin name to its non-prefixed form. */
+export declare function shortenPluginName(name: string): string;
 export type PluginContext = SpaceContext & {
     /** Validated config for this plugin invocation. */
     pluginConfig: Record<string, unknown>;
+    /** Optional callback functions for plugins to interact with the system. */
+    callbacks?: {
+        /** Persist plugin config updates to the config file. */
+        persistConfig?: (updates: Record<string, string>) => void;
+    };
 };
 export type ParseResult = {
     nodes: BaseNode[];
@@ -33,6 +40,8 @@ export type RenderFormat = {
 export type RenderOptions = {
     /** The format name being rendered (e.g. 'bullets', 'mermaid'). */
     format: string;
+    /** Plugin-specific extra data (e.g. CLI flags forwarded by a convenience command). */
+    data?: Record<string, unknown>;
 };
 /**
  * The render hook on a plugin: declares available formats and handles rendering.

package/dist/plugins/util.js

@@ -5,3 +5,7 @@ export const CONFIG_PLUGINS_DIR = 'plugins';
 export function normalizePluginName(name) {
     return name.startsWith(PLUGIN_PREFIX) ? name : `${PLUGIN_PREFIX}${name}`;
 }
+/** Shorten a plugin name to its non-prefixed form. */
+export function shortenPluginName(name) {
+    return name.startsWith(PLUGIN_PREFIX) ? name.slice(PLUGIN_PREFIX.length) : name;
+}

package/dist/read/resolve-graph-edges.js

@@ -126,6 +126,33 @@ function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolved
         }
     }
 }
+/**
+ * Classify a ContentLink into a ResolvedContentLink by determining its location.
+ *
+ * Wikilinks are resolved against the target index: if found, location is 'node',
+ * otherwise 'internal' (in the source system but not a space node).
+ * Markdown links are classified by URL scheme: external (http/https), system (file://),
+ * protocol (other scheme), or internal (relative path / no scheme).
+ */
+function classifyContentLink(link, targetIndex) {
+    const { linkSyntax, target, text, action, anchor } = link;
+    const base = { text, target, action, ...(anchor !== undefined ? { anchor } : {}) };
+    if (linkSyntax === 'wikilink') {
+        // Try the full target#anchor key first, then the bare target — either means it's a space node.
+        const lookupKey = anchor !== undefined ? `${target}#${anchor}` : target;
+        const inIndex = targetIndex.has(lookupKey) || (anchor !== undefined && targetIndex.has(target));
+        return { ...base, location: inIndex ? 'node' : 'internal' };
+    }
+    // Markdown link: classify by URL scheme.
+    const colonIdx = target.indexOf('://');
+    if (colonIdx > 0) {
+        const scheme = target.slice(0, colonIdx).toLowerCase();
+        const location = scheme === 'https' || scheme === 'http' ? 'external' : scheme === 'file' ? 'system' : 'protocol';
+        return { ...base, location };
+    }
+    // Relative path or fragment — in the source system but not a resolvable space node.
+    return { ...base, location: 'internal' };
+}
 /**
  * Enrich parsed nodes into SpaceNodes by applying type alias resolution and resolving
  * parent links using the hierarchy levels and relationships from schema metadata.
@@ -141,6 +168,7 @@ export function resolveGraphEdges(nodes, metadata) {
         ...n,
         resolvedType: resolveNodeType(n.type, typeAliases),
         resolvedParents: [],
+        resolvedLinks: [],
     }));
     const targetIndex = buildTargetIndex(spaceNodes);
     // Build nodesByType map
@@ -186,6 +214,10 @@ export function resolveGraphEdges(nodes, metadata) {
         };
         resolveEdge(nodesByType, targetIndex, edge, 'relationship', rel.type === rel.parent, unresolvedRefs, typeAliases);
     }
+    // 3. Resolve content links — classify each raw ContentLink into a ResolvedContentLink.
+    for (const node of spaceNodes) {
+        node.resolvedLinks = (node.contentLinks ?? []).map((link) => classifyContentLink(link, targetIndex));
+    }
     // Deduplicate by (label, field, ref) — the same broken link may be encountered across
     // multiple resolveEdge calls (e.g. selfRef + regular hierarchy share the same field).
     const seen = new Set();

package/dist/render/render.d.ts

@@ -1,4 +1,5 @@
 import type { SpaceContext } from '../types';
 export declare function executeRender(formatName: string, context: SpaceContext, options: {
     filter?: string;
+    data?: Record<string, unknown>;
 }): Promise<string>;