structured-context 0.11.0 → 0.12.0

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

@@ -2,30 +2,7 @@ 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 };
-}
+import { parseWikilink } from '../../read/wikilink-utils';
 /**
  * Extract wikilinks (and Obsidian embed wikilinks) from a plain text string.
  * Matches [[target]], ![[target]], [[target#anchor]], [[target|alias]], etc.
@@ -35,7 +12,7 @@ function extractWikilinksFromText(text) {
     for (const match of text.matchAll(/(!?)\[\[([^\]]+)\]\]/g)) {
         const isEmbed = match[1] === '!';
         const inner = match[2];
-        const { target, anchor, displayText } = parseWikilinkInner(inner);
+        const { target, anchor, displayText } = parseWikilink(inner);
         if (!target)
             continue;
         links.push({
@@ -109,10 +86,12 @@ export function extractLinksFromBody(body) {
  */
 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 hierarchy of metadata.hierarchies ?? []) {
+        for (const level of hierarchy.levels) {
+            fields.add(level.field);
+            if (level.selfRefField)
+                fields.add(level.selfRefField);
+        }
     }
     for (const rel of metadata.relationships ?? []) {
         fields.add(rel.field);

package/dist/plugins/markdown/index.js

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

package/dist/plugins/markdown/parse-embedded.d.ts

@@ -74,11 +74,17 @@ export interface ExtractEmbeddedOptions {
      * Example: { "record_type": "type" } renames `record_type` to `type` in extracted data.
      */
     fieldMap?: Record<string, string>;
+    /** File path of the containing document, for populating node.source. */
+    file?: string;
+    /** Line offset of the body within the source file (e.g. frontmatter lines). */
+    lineOffset?: number;
 }
 export interface ExtractEmbeddedResult {
     nodes: BaseNode[];
     preambleNodeCount: number;
     terminatedHeadings: string[];
+    preambleContent?: string;
+    preambleFields?: Record<string, unknown>;
 }
 /**
  * Extract space nodes from markdown body text.

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

@@ -145,9 +145,11 @@ function appendContent(node, text) {
     if (!text)
         return;
     const existing = node.schemaData.content;
-    node.schemaData.content = existing ? `${existing}\n${text}` : text;
+    const updated = existing ? `${existing}\n${text}` : text;
+    node.schemaData.content = updated;
+    node.content = updated;
 }
-function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend) {
+function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset) {
     const firstPara = item.children.find((c) => c.type === 'paragraph');
     if (!firstPara) {
         appendContent(contentTarget, `- ${mdastToString(item)}`);
@@ -185,6 +187,11 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             schemaData.parent = parentRef;
         if (summary)
             schemaData.summary = summary;
+        const line = item.position?.start.line ? item.position.start.line + (lineOffset ?? 0) : undefined;
+        const column = item.position?.start.column;
+        const source = file
+            ? { file, ...(line !== undefined ? { line } : {}), ...(column !== undefined ? { column } : {}) }
+            : undefined;
         const linkTargets = buildLinkTargets(title);
         const newNode = {
             label: makeLabel(title),
@@ -192,7 +199,9 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             schemaData,
             linkTargets,
             type,
+            ...(schemaData.content !== undefined ? { content: schemaData.content } : {}),
             contentLinks: [],
+            ...(source ? { source } : {}),
         };
         nodes.push(newNode);
         if (parentFieldAppend) {
@@ -202,7 +211,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
         for (const child of item.children) {
             if (child.type === 'list') {
                 for (const subItem of child.children) {
-                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType);
+                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset);
                 }
             }
         }
@@ -240,7 +249,7 @@ export function extractEmbeddedNodes(body, options) {
     const stack = !isOnAPageMode && pageTitle !== undefined
         ? [{ depth: 0, title: pageTitle, nodeType: pageType, refTarget: pageTitle }]
         : [];
-    let parseState = 'preamble';
+    let parseState = isOnAPageMode ? 'preamble' : 'active';
     let preambleNodeCount = 0;
     const terminatedHeadings = [];
     /**
@@ -467,6 +476,11 @@ export function extractEmbeddedNodes(body, options) {
             };
             if (parentRef)
                 schemaData.parent = parentRef;
+            const line = heading.position?.start.line ? heading.position.start.line + (options.lineOffset ?? 0) : undefined;
+            const column = heading.position?.start.column;
+            const source = options.file
+                ? { file: options.file, ...(line !== undefined ? { line } : {}), ...(column !== undefined ? { column } : {}) }
+                : undefined;
             const linkTargets = buildHeadingLinkTargets(rawText, title, anchor);
             const headingNode = {
                 label: makeLabel(title),
@@ -474,7 +488,9 @@ export function extractEmbeddedNodes(body, options) {
                 schemaData,
                 linkTargets,
                 type,
+                ...(schemaData.content !== undefined ? { content: schemaData.content } : {}),
                 contentLinks: [],
+                ...(source ? { source } : {}),
             };
             // Push to stack BEFORE resolving semantic parent — stack[-2] is the correct parent.
             const refTarget = linkTargets[0] ?? title;
@@ -517,13 +533,13 @@ export function extractEmbeddedNodes(body, options) {
                     ? { node: semanticParent.node, field: definition.field }
                     : undefined;
                 for (const item of list.children) {
-                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg);
+                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset);
                 }
                 grouping = null;
             }
             else {
                 for (const item of list.children) {
-                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap);
+                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset);
                 }
             }
         }
@@ -605,6 +621,15 @@ export function extractEmbeddedNodes(body, options) {
                                 schemaData[mappedColName] = cellContent;
                             }
                         }
+                        const line = row.position?.start.line ? row.position.start.line + (options.lineOffset ?? 0) : undefined;
+                        const column = row.position?.start.column;
+                        const source = options.file
+                            ? {
+                                file: options.file,
+                                ...(line !== undefined ? { line } : {}),
+                                ...(column !== undefined ? { column } : {}),
+                            }
+                            : undefined;
                         const linkTargets = buildListItemLinkTargets(title);
                         const rowNode = {
                             label: makeLabel(title),
@@ -613,6 +638,7 @@ export function extractEmbeddedNodes(body, options) {
                             linkTargets,
                             type: rowTypeStr,
                             contentLinks: [],
+                            ...(source ? { source } : {}),
                         };
                         nodes.push(rowNode);
                         if (tableParentFieldAppend) {
@@ -668,5 +694,13 @@ export function extractEmbeddedNodes(body, options) {
             }
         }
     }
-    return { nodes, preambleNodeCount, terminatedHeadings };
+    const preambleContent = rootNode.schemaData.content;
+    const { type: _rootType, content: _rootContent, ...preambleFields } = rootNode.schemaData;
+    return {
+        nodes,
+        preambleNodeCount,
+        terminatedHeadings,
+        preambleContent,
+        preambleFields: Object.keys(preambleFields).length > 0 ? preambleFields : undefined,
+    };
 }

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

@@ -21,10 +21,15 @@ export function readSpaceOnAPage(context) {
         throw new Error(`Schema at ${resolvedSchemaPath} must define "$metadata.hierarchy.levels" to read a space_on_a_page file.`);
     }
     const pageTitle = basename(filePath, '.md');
+    const fmMatch = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
+    const fileName = basename(filePath);
     const { nodes, preambleNodeCount, terminatedHeadings } = extractEmbeddedNodes(body, {
         pageTitle,
         pageType: 'space_on_a_page',
         metadata,
+        file: fileName,
+        lineOffset,
     });
     const parseIssues = terminatedHeadings.map((heading) => ({
         file: heading,
@@ -63,16 +68,27 @@ export async function readSpaceDirectory(context, options) {
             // Clear the cache after any parse error to avoid stale state.
             // See: https://github.com/jonschlinkert/gray-matter/issues/166
             matter.clearCache();
+            const yamlErr = err;
+            const line = yamlErr.mark ? yamlErr.mark.line + 1 : undefined;
+            const column = yamlErr.mark ? yamlErr.mark.column + 1 : undefined;
             parseIssues.push({
                 file,
                 severity: 'error',
                 type: 'parse',
                 message: err instanceof Error ? err.message : String(err),
+                ...(line !== undefined ? { line } : {}),
+                ...(column !== undefined ? { column } : {}),
             });
             continue;
         }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            parseIssues.push({ file, severity: 'warning', type: 'no-type', message: 'No front-matter or type specified' });
+            parseIssues.push({
+                file,
+                severity: 'warning',
+                type: 'no-type',
+                message: 'No front-matter or type specified',
+                line: 1,
+            });
             continue;
         }
         const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
@@ -80,7 +96,7 @@ export async function readSpaceDirectory(context, options) {
             data.type = inferTypeFromPath(file, typeInferenceCfg, knownTypes, context.schema.metadata.typeAliases);
         }
         if (!data.type) {
-            parseIssues.push({ file, severity: 'warning', type: 'no-type' });
+            parseIssues.push({ file, severity: 'warning', type: 'no-type', line: 1 });
             continue;
         }
         if (ON_A_PAGE_TYPES.includes(data.type) && !options?.includeOnAPageFiles) {
@@ -89,21 +105,35 @@ export async function readSpaceDirectory(context, options) {
         const pageType = data.type;
         const fileBase = basename(file, '.md');
         const title = data.title ?? fileBase;
-        nodes.push({
+        const fmMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+        const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
+        const pageNode = {
             label: file,
             title,
             schemaData: { title, ...data },
             linkTargets: [title, fileBase],
             type: pageType,
+            source: { file, line: 1 },
+            ...(data.content !== undefined ? { content: data.content } : {}),
             contentLinks: [...extractLinksFromFrontmatter(data, edgeFields), ...extractLinksFromBody(parsed.content)],
-        });
+        };
         if (!ON_A_PAGE_TYPES.includes(pageType)) {
-            const { nodes: embedded, terminatedHeadings } = extractEmbeddedNodes(parsed.content, {
+            const { nodes: embedded, preambleContent, preambleFields, terminatedHeadings, } = extractEmbeddedNodes(parsed.content, {
                 pageTitle: fileBase,
                 pageType,
                 metadata,
                 fieldMap,
+                file,
+                lineOffset,
             });
+            if (preambleFields) {
+                Object.assign(pageNode.schemaData, preambleFields);
+            }
+            if (preambleContent) {
+                pageNode.schemaData.content = preambleContent;
+                pageNode.content = preambleContent;
+            }
+            nodes.push(pageNode);
             nodes.push(...embedded);
             for (const heading of terminatedHeadings) {
                 parseIssues.push({
@@ -114,6 +144,9 @@ export async function readSpaceDirectory(context, options) {
                 });
             }
         }
+        else {
+            nodes.push(pageNode);
+        }
     }
     return { nodes, parseIssues, diagnostics: { kind: 'directory' } };
 }

package/dist/plugins/markdown/render-directory.d.ts

@@ -0,0 +1,11 @@
+import type { SpaceGraph } from '../../space-graph';
+import type { PluginContext, RenderMultiFileOutput, RenderOptions } from '../util';
+/**
+ * Sanitize a node title into a valid filesystem filename.
+ * Strips Obsidian/OS forbidden characters: \ / : * ? " < > | # ^ [ ]
+ */
+export declare function sanitizeFilename(title: string): string;
+/**
+ * Render a space graph as a markdown directory with one file per node.
+ */
+export declare function renderMarkdownDirectory(context: PluginContext, graph: SpaceGraph, options: RenderOptions): RenderMultiFileOutput;

package/dist/plugins/markdown/render-directory.js

@@ -0,0 +1,130 @@
+import { posix } from 'node:path';
+import matter from 'gray-matter';
+import { getMarkdownConfig } from './index';
+import { coerceDates, invertFieldMap } from './util';
+/**
+ * Sanitize a node title into a valid filesystem filename.
+ * Strips Obsidian/OS forbidden characters: \ / : * ? " < > | # ^ [ ]
+ */
+export function sanitizeFilename(title) {
+    const sanitized = title
+        .replace(/[\\/:*?"<>|#^[\]]/g, '-')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^[-.]+/, '')
+        .replace(/[-.]+$/, '');
+    return sanitized || 'untitled';
+}
+const PREFERRED_FIELD_ORDER = ['type', 'title', 'status', 'summary', 'status_tweet'];
+const EDGE_FIELDS = new Set(['parent', 'dependsOn', 'flowsTo', 'anchors', 'pipelineOf']);
+/**
+ * Format frontmatter object with preferred key ordering for Obsidian notes.
+ */
+function sortFrontmatterKeys(data) {
+    const keys = Object.keys(data);
+    const preferred = [];
+    const edge = [];
+    const middle = [];
+    for (const k of PREFERRED_FIELD_ORDER) {
+        if (keys.includes(k))
+            preferred.push(k);
+    }
+    for (const k of keys) {
+        if (EDGE_FIELDS.has(k)) {
+            edge.push(k);
+        }
+        else if (!PREFERRED_FIELD_ORDER.includes(k)) {
+            middle.push(k);
+        }
+    }
+    const sorted = {};
+    for (const k of [...preferred, ...middle, ...edge]) {
+        sorted[k] = data[k];
+    }
+    return sorted;
+}
+/**
+ * Render a space graph as a markdown directory with one file per node.
+ */
+export function renderMarkdownDirectory(context, graph, options) {
+    const markdownConfig = getMarkdownConfig(context.space?.plugins);
+    const reverseFieldMap = markdownConfig.fieldMap ? invertFieldMap(markdownConfig.fieldMap) : {};
+    const foldersOption = options.data?.folders;
+    let useFolders = false;
+    if (foldersOption === 'type') {
+        useFolders = true;
+    }
+    else if (foldersOption === 'flat') {
+        useFolders = false;
+    }
+    else if (markdownConfig.typeInference?.folderMap) {
+        useFolders = true;
+    }
+    // Build type-to-folder mapping from typeInference.folderMap if available
+    const folderMap = markdownConfig.typeInference?.folderMap;
+    const typeToFolder = new Map();
+    if (folderMap) {
+        for (const [folderPath, mappedType] of Object.entries(folderMap)) {
+            const cleanFolder = folderPath.replace(/\\/g, '/').replace(/\/+$/, '');
+            typeToFolder.set(mappedType.toLowerCase(), cleanFolder);
+        }
+    }
+    const files = [];
+    const usedPaths = new Set();
+    for (const node of graph.nodes.values()) {
+        const baseName = sanitizeFilename(node.title);
+        let folder = '';
+        if (useFolders) {
+            const typeKey = (node.resolvedType || node.type || '').toLowerCase();
+            folder = typeToFolder.get(typeKey) ?? (node.resolvedType || node.type || 'other');
+        }
+        let candidateName = `${baseName}.md`;
+        let counter = 2;
+        let relPath = folder ? posix.join(folder, candidateName) : candidateName;
+        while (usedPaths.has(relPath)) {
+            candidateName = `${baseName}-${counter}.md`;
+            relPath = folder ? posix.join(folder, candidateName) : candidateName;
+            counter++;
+        }
+        usedPaths.add(relPath);
+        const finalBase = candidateName.slice(0, -3);
+        // Prepare frontmatter data from schemaData with reverse fieldMap
+        const rawData = node.schemaData ?? {};
+        const frontmatterData = {};
+        for (const [key, value] of Object.entries(rawData)) {
+            // Body content is not written to frontmatter
+            if (key === 'content')
+                continue;
+            // Omit title only if it matches the final filename base
+            if (key === 'title' && finalBase === node.title)
+                continue;
+            const fileKey = reverseFieldMap[key] ?? key;
+            frontmatterData[fileKey] = value;
+        }
+        // Preserve exact title if final filename differed or disambiguation occurred
+        if (finalBase !== node.title && !frontmatterData.title) {
+            const titleKey = reverseFieldMap.title ?? 'title';
+            frontmatterData[titleKey] = node.title;
+        }
+        // Ensure type is in frontmatter
+        const nodeType = node.type || node.resolvedType;
+        if (nodeType && !frontmatterData.type) {
+            const typeKey = reverseFieldMap.type ?? 'type';
+            frontmatterData[typeKey] = nodeType;
+        }
+        const coercedData = coerceDates(sortFrontmatterKeys(frontmatterData));
+        const body = (node.content ?? '').trim();
+        let fileContent;
+        if (Object.keys(coercedData).length > 0) {
+            fileContent = matter.stringify(body ? `\n${body}\n` : '', coercedData);
+        }
+        else {
+            fileContent = body ? `${body}\n` : '';
+        }
+        files.push({
+            path: relPath,
+            content: fileContent,
+        });
+    }
+    return { files };
+}

package/dist/plugins/mermaid/render-mermaid.js

@@ -15,7 +15,8 @@ function safeNodeId(id) {
     return id.replace(/[^a-zA-Z0-9_-]/g, '_');
 }
 export function renderMermaid(graph) {
-    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet, levels } = graph;
+    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet } = graph;
+    const levels = graph.hierarchy?.levels ?? [];
     let mmd = 'graph TD\n';
     for (let i = 0; i < levels.length; i++) {
         const level = levels[i];

package/dist/plugins/miro/sync.js

@@ -16,6 +16,7 @@ export async function miroSync(context, graph, options) {
     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 levels = graph.hierarchy?.levels ?? [];
     const nodes = [...graph.nodes.values()].filter((n) => graph.hierarchyTitles.has(n.title));
     if (nodes.length === 0) {
         return 'No space nodes found.';
@@ -28,7 +29,7 @@ export async function miroSync(context, graph, options) {
     let layoutOffset = null;
     if (options.newFrame) {
         // Calculate layout bounds to size the frame appropriately
-        const { bounds } = layoutNewCards(nodes, new Map(), graph.levels);
+        const { bounds } = layoutNewCards(nodes, new Map(), 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.
@@ -155,7 +156,7 @@ export async function miroSync(context, graph, options) {
         }
     }
     // Compute positions for new cards
-    const { positions: newPositions } = layoutNewCards(newNodes, existingPositions, graph.levels);
+    const { positions: newPositions } = layoutNewCards(newNodes, existingPositions, levels);
     // 7. Create new cards
     let createdCount = 0;
     for (const node of newNodes) {
@@ -185,7 +186,7 @@ export async function miroSync(context, graph, options) {
                 title: buildCardTitle(node),
                 description: buildCardDescription(node),
             },
-            style: { cardTheme: getCardColor(type, graph.levels) },
+            style: { cardTheme: getCardColor(type, levels) },
             position: { x: pos.x, y: pos.y, origin: 'center' },
             parent: { id: frameId },
             geometry: { width: CARD_WIDTH },
@@ -231,7 +232,7 @@ export async function miroSync(context, graph, options) {
                         title: buildCardTitle(node),
                         description: buildCardDescription(node),
                     },
-                    style: { cardTheme: getCardColor(type, graph.levels) },
+                    style: { cardTheme: getCardColor(type, levels) },
                     position: { x: 0, y: 0, origin: 'center' },
                     parent: { id: frameId },
                     geometry: { width: CARD_WIDTH },
@@ -256,8 +257,8 @@ export async function miroSync(context, graph, options) {
     const desiredEdges = new Map();
     for (const node of nodes) {
         const childTitle = node.title;
-        for (const { title: parentTitle, source } of node.resolvedParents) {
-            if (source !== 'hierarchy')
+        for (const { title: parentTitle, source, hierarchy } of node.resolvedParents) {
+            if (source !== 'hierarchy' || hierarchy !== graph.hierarchy?.name)
                 continue;
             // Both endpoints must have verified cards on the board
             if (verifiedCardIds.has(parentTitle) && verifiedCardIds.has(childTitle)) {

package/dist/plugins/util.d.ts

@@ -1,4 +1,6 @@
 import type { AnySchemaObject } from 'ajv';
+import type { Config, SpaceConfig } from '../config';
+import type { PluginSchemaSource } from '../schema/schema';
 import type { SpaceGraph } from '../space-graph';
 import type { BaseNode, ParseIssue, SpaceContext } from '../types';
 export declare const PLUGIN_PREFIX = "sctx-";
@@ -43,6 +45,21 @@ export type RenderOptions = {
     /** Plugin-specific extra data (e.g. CLI flags forwarded by a convenience command). */
     data?: Record<string, unknown>;
 };
+/** A single file generated as part of a multi-file render output. */
+export type RenderFileOutput = {
+    /** Relative path of the file within the destination directory (e.g. 'goals/My Goal.md'). */
+    path: string;
+    /** File content to write. */
+    content: string;
+};
+/** Multi-file render output generated by a render hook. */
+export type RenderMultiFileOutput = {
+    files: RenderFileOutput[];
+};
+/** Render hook output: either a single string (stdout/single file) or multiple files. */
+export type RenderResult = string | RenderMultiFileOutput;
+/** Type guard for multi-file render result. */
+export declare function isRenderMultiFileOutput(result: RenderResult): result is RenderMultiFileOutput;
 /**
  * The render hook on a plugin: declares available formats and handles rendering.
  * Unlike parse/templateSync (first-responder), render hooks are additive —
@@ -50,7 +67,7 @@ export type RenderOptions = {
  */
 export type RenderHook = {
     formats: RenderFormat[];
-    render: (context: PluginContext, graph: SpaceGraph, options: RenderOptions) => Promise<string> | string;
+    render: (context: PluginContext, graph: SpaceGraph, options: RenderOptions) => Promise<RenderResult> | RenderResult;
 };
 /**
  * Plugin contract:
@@ -63,7 +80,28 @@ export type StructuredContextPlugin = {
     /** JSON Schema used to validate the plugin's config block. Fields with `format: 'path'`
      * are resolved relative to the config directory by `resolveConfigPaths` in the loader. */
     configSchema: AnySchemaObject;
+    /** Optional directory containing JSON schemas contributed by this plugin. */
+    schemasDir?: string;
     parse?: ParseHook;
     templateSync?: TemplateSyncHook;
     render?: RenderHook;
 };
+/**
+ * Synchronously locate the root directory of an external plugin.
+ * Resolution order:
+ * 1. Config-adjacent: {configDir}/plugins/{name} or {configDir}/plugins/sctx-{name}
+ * 2. Node module: resolve from configDir using standard module resolution
+ */
+export declare function resolvePluginDir(pluginName: string, configDir: string): string | undefined;
+/**
+ * Synchronously locate the schemas directory for a plugin.
+ * Convention:
+ * 1. package.json "sctx": { "schemas": "..." }
+ * 2. Convention: <pluginDir>/schemas
+ * 3. Fallback for test fixtures: {configDir}/plugins/schemas
+ */
+export declare function resolvePluginSchemasDir(pluginName: string, configDir: string): string | undefined;
+/**
+ * Synchronously collect all plugin schema sources available to a space.
+ */
+export declare function resolveSpacePluginSchemas(space: SpaceConfig | undefined, config: Config, configDir: string): PluginSchemaSource[];