structured-context 0.9.3 → 0.11.0

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

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { Glob } from 'bun';
+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,7 +43,8 @@ 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 files = await Array.fromAsync(new Glob('**/*.md').scan({ cwd: directory, followSymlinks: true }));
+    const edgeFields = getEdgeFieldNames(metadata);
+    const files = await fg('**/*.md', { cwd: directory, followSymbolicLinks: true });
     const nodes = [];
     const parseIssues = [];
     for (const file of files) {
@@ -70,7 +72,7 @@ export async function readSpaceDirectory(context, options) {
             continue;
         }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            parseIssues.push({ file, severity: 'warning', type: 'empty' });
+            parseIssues.push({ file, severity: 'warning', type: 'no-type', message: 'No front-matter or type specified' });
             continue;
         }
         const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
@@ -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/markdown/template-sync.d.ts

@@ -1,5 +1,5 @@
 import type { AnySchemaObject } from 'ajv';
-import type { HierarchyLevel, Relationship, SchemaWithMetadata } from '../../plugin-api';
+import type { HierarchyLevel, Relationship, SchemaWithMetadata } from '../../api';
 import type { PluginContext, TemplateSyncOptions } from '../util';
 export interface TypeVariant {
     required: string[];

package/dist/plugins/markdown/template-sync.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { Glob } from 'bun';
+import fg from 'fast-glob';
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
 import { mergeVariantProperties, resolveRef } from '../../schema/schema-refs';
@@ -190,7 +190,7 @@ export async function templateSync(context, options) {
     const { schema, schemaRefRegistry } = context;
     const typeVariants = getTypeVariants(schema, schemaRefRegistry);
     const matchedTypes = new Set();
-    const files = await Array.fromAsync(new Glob('*.md').scan({ cwd: templateDir, absolute: true }));
+    const files = await fg('*.md', { cwd: templateDir, absolute: true });
     const dryRun = options.dryRun ?? false;
     let filesModified = 0;
     let filesCreated = 0;

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>;

package/dist/render/render.js

@@ -1,7 +1,7 @@
-import { filterNodes } from '../filter/filter-nodes';
+import { shortenPluginName } from '@/plugins/util';
+import { updateSpaceField } from '../config';
+import { assembleSpaceGraph } from '../load-space-graph';
 import { loadPlugins } from '../plugins/loader';
-import { readSpace } from '../read/read-space';
-import { buildSpaceGraph } from '../space-graph';
 import { buildFormatRegistry } from './registry';
 export async function executeRender(formatName, context, options) {
     const pluginMap = context.space?.plugins ?? {};
@@ -12,17 +12,21 @@ export async function executeRender(formatName, context, options) {
         const available = registry.map((r) => r.qualifiedName).join(', ');
         throw new Error(`Unknown render format: "${formatName}".${available ? ` Available: ${available}` : ' No formats registered.'}`);
     }
-    const { nodes: allNodes } = await readSpace(context);
-    // Validate: drop nodes that fail schema validation
-    const { schemaValidator } = context;
-    const validNodes = allNodes.filter((node) => schemaValidator(node.schemaData));
-    const levels = context.schema.metadata.hierarchy?.levels ?? [];
-    let graph = buildSpaceGraph(validNodes, levels);
-    // Filter: apply filter expression if provided
-    if (options.filter) {
-        const expression = context.space.views?.[options.filter]?.expression ?? options.filter;
-        graph = await filterNodes(expression, graph);
-    }
-    const pluginContext = { ...context, pluginConfig: entry.plugin.pluginConfig };
-    return entry.plugin.plugin.render.render(pluginContext, graph, { format: entry.format.name });
+    const graph = await assembleSpaceGraph(context, { filter: options.filter });
+    const shortName = shortenPluginName(entry.plugin.plugin.name);
+    const pluginContext = {
+        ...context,
+        pluginConfig: entry.plugin.pluginConfig,
+        callbacks: {
+            persistConfig: (updates) => {
+                for (const [field, value] of Object.entries(updates)) {
+                    updateSpaceField(context.space.name, field, value, shortName);
+                }
+            },
+        },
+    };
+    return entry.plugin.plugin.render.render(pluginContext, graph, {
+        format: entry.format.name,
+        data: options.data,
+    });
 }

package/dist/schema/evaluate-rule.js

@@ -52,6 +52,7 @@ function flattenNode(node) {
         resolvedType: node.resolvedType,
         resolvedParentTitle: node.resolvedParents[0]?.title, // first parent or undefined, provided for convenience
         resolvedParentTitles: node.resolvedParents.map((r) => r.title), // full array of parent titles
+        resolvedLinks: node.resolvedLinks,
     };
 }
 /**

package/dist/schema/schema.d.ts

@@ -1,6 +1,8 @@
 import { type AnySchemaObject, type ValidateFunction } from 'ajv';
 import type { SchemaMetadata, SchemaWithMetadata } from '../types';
-export declare const bundledSchemasDir: string;
+export declare let bundledSchemasDir: string;
+/** Override the bundled schemas directory (e.g. when running in a bundled context). */
+export declare function setBundledSchemasDir(dir: string): void;
 export declare function readRawSchema(schemaPath: string): AnySchemaObject;
 /**
  * Build the full two-layer registry for a schema path:

package/dist/schema/schema.js

@@ -3,11 +3,15 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import Ajv, {} from 'ajv';
-import { JSON5 } from 'bun';
+import JSON5 from 'json5';
 import { DIALECT_META_SCHEMA, METADATA_SCHEMA, SCHEMA_META_ID, } from './metadata-contract';
 import { isObject, mergeVariantProperties, resolveJsonPointer } from './schema-refs';
-const packageDir = dirname(fileURLToPath(import.meta.url));
-export const bundledSchemasDir = join(packageDir, '..', '..', 'schemas');
+const packageDir = import.meta.url ? dirname(fileURLToPath(import.meta.url)) : '';
+export let bundledSchemasDir = packageDir ? join(packageDir, '..', '..', 'schemas') : '';
+/** Override the bundled schemas directory (e.g. when running in a bundled context). */
+export function setBundledSchemasDir(dir) {
+    bundledSchemasDir = dir;
+}
 const validateMetadataContract = new Ajv().compile(METADATA_SCHEMA);
 export function readRawSchema(schemaPath) {
     return JSON5.parse(readFileSync(resolve(schemaPath), 'utf-8'));

package/dist/schemas/_knowledge_wiki.json

@@ -207,7 +207,7 @@
     },
     "note": {
       "type": "object",
-      "description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.",
+      "description": "Personal notes, journal entries, talk notes, or rough thoughts not drawn from an external URL.",
       "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "note" },