structured-context 0.10.0 → 0.12.0

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,43 +1,28 @@
-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 levels = graph.hierarchy?.levels ?? [];
+    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;
@@ -69,12 +54,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);
@@ -272,8 +257,8 @@ export async function miroSync(context, 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)) {
@@ -341,7 +326,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

@@ -1,13 +1,22 @@
 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-";
 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,7 +42,24 @@ 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>;
 };
+/** 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 —
@@ -41,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:
@@ -54,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[];

package/dist/plugins/util.js

@@ -1,3 +1,6 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { PLUGIN_PREFIX as _PLUGIN_PREFIX } from '../constants';
 export const PLUGIN_PREFIX = _PLUGIN_PREFIX;
 export const CONFIG_PLUGINS_DIR = 'plugins';
@@ -5,3 +8,143 @@ 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;
+}
+/** Type guard for multi-file render result. */
+export function isRenderMultiFileOutput(result) {
+    return typeof result === 'object' && result !== null && Array.isArray(result.files);
+}
+/**
+ * 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 function resolvePluginDir(pluginName, configDir) {
+    const normalized = normalizePluginName(pluginName);
+    const short = shortenPluginName(pluginName);
+    for (const candidate of [normalized, short]) {
+        const localDir = resolve(configDir, CONFIG_PLUGINS_DIR, candidate);
+        if (existsSync(localDir)) {
+            try {
+                if (statSync(localDir).isDirectory()) {
+                    return localDir;
+                }
+            }
+            catch { }
+        }
+    }
+    // Node module resolution from configDir
+    for (const candidate of [normalized, short]) {
+        try {
+            const req = createRequire(join(configDir, 'package.json'));
+            const pkgPath = req.resolve(`${candidate}/package.json`);
+            return dirname(pkgPath);
+        }
+        catch {
+            const nmCandidate = resolve(configDir, 'node_modules', candidate);
+            if (existsSync(nmCandidate)) {
+                try {
+                    if (statSync(nmCandidate).isDirectory()) {
+                        return nmCandidate;
+                    }
+                }
+                catch { }
+            }
+        }
+    }
+    return 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 function resolvePluginSchemasDir(pluginName, configDir) {
+    const dir = resolvePluginDir(pluginName, configDir);
+    if (dir) {
+        // 1. package.json sctx.schemas
+        const pkgJsonPath = join(dir, 'package.json');
+        if (existsSync(pkgJsonPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+                if (pkg.sctx?.schemas && typeof pkg.sctx.schemas === 'string') {
+                    const customSchemas = resolve(dir, pkg.sctx.schemas);
+                    if (existsSync(customSchemas) && statSync(customSchemas).isDirectory()) {
+                        return customSchemas;
+                    }
+                }
+            }
+            catch { }
+        }
+        // 2. Convention: <pluginDir>/schemas
+        const conventionDir = join(dir, 'schemas');
+        if (existsSync(conventionDir)) {
+            try {
+                if (statSync(conventionDir).isDirectory()) {
+                    return conventionDir;
+                }
+            }
+            catch { }
+        }
+    }
+    // 3. Check config-adjacent plugins/schemas as fallback (e.g. test fixtures)
+    const fallbackSchemas = resolve(configDir, CONFIG_PLUGINS_DIR, 'schemas');
+    if (existsSync(fallbackSchemas)) {
+        try {
+            if (statSync(fallbackSchemas).isDirectory()) {
+                return fallbackSchemas;
+            }
+        }
+        catch { }
+    }
+    return undefined;
+}
+/**
+ * Synchronously collect all plugin schema sources available to a space.
+ */
+export function resolveSpacePluginSchemas(space, config, configDir) {
+    const pluginSources = [];
+    const seenPlugins = new Set();
+    const maybeAddPlugin = (name) => {
+        const shortName = shortenPluginName(name);
+        if (seenPlugins.has(shortName))
+            return;
+        seenPlugins.add(shortName);
+        const schemasDir = resolvePluginSchemasDir(name, configDir);
+        if (schemasDir) {
+            pluginSources.push({
+                pluginName: shortName,
+                schemasDir,
+            });
+        }
+    };
+    // 1. Plugin referenced by space.schema prefix if any (e.g. sctx-wardley-mapping/wardley_map.json)
+    const rawSchema = space?.schema ?? config.schema;
+    if (rawSchema && !isAbsolute(rawSchema) && !rawSchema.startsWith('.')) {
+        const normalized = rawSchema.replace(/\\/g, '/');
+        const slashIdx = normalized.indexOf('/');
+        if (slashIdx !== -1) {
+            const prefix = normalized.slice(0, slashIdx);
+            maybeAddPlugin(prefix);
+        }
+    }
+    // 2. Plugins configured on space
+    if (space?.plugins) {
+        for (const name of Object.keys(space.plugins)) {
+            maybeAddPlugin(name);
+        }
+    }
+    // 3. Plugins configured globally
+    const globalPlugins = config.plugins;
+    if (globalPlugins) {
+        for (const name of Object.keys(globalPlugins)) {
+            maybeAddPlugin(name);
+        }
+    }
+    return pluginSources;
+}

package/dist/read/resolve-graph-edges.d.ts

@@ -1,7 +1,7 @@
 import type { BaseNode, SchemaMetadata, SpaceNode, UnresolvedRef } from '../types';
 /**
  * Enrich parsed nodes into SpaceNodes by applying type alias resolution and resolving
- * parent links using the hierarchy levels and relationships from schema metadata.
+ * parent links using the levels of every hierarchy and the relationships from schema metadata.
  *
  * Returns the enriched nodes and any unresolved refs (broken/invalid wikilinks).
  */

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

@@ -21,19 +21,27 @@ function getRefs(rawField, multiple) {
  * @param nodesByType Map of node type to nodes
  * @param targetIndex Map of link targets to nodes
  * @param edge The edge definition (child type, parent type, field, fieldOn, multiple)
- * @param source Whether this edge comes from hierarchy.levels or relationships
+ * @param source Whether this edge comes from hierarchy levels or relationships
+ * @param hierarchy Name of the hierarchy the edge belongs to (hierarchy edges only)
  * @param selfRef Whether child and parent are the same node type
  * @param unresolvedRefs Array to push broken/invalid link entries into
  * @param typeAliases Optional type aliases for resolution
  */
-function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolvedRefs, typeAliases) {
+function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef, unresolvedRefs, typeAliases) {
     const { type: rawChildType, parent: rawParentType, field, fieldOn, multiple } = edge;
     const childType = resolveNodeType(rawChildType, typeAliases);
     const parentType = resolveNodeType(rawParentType, typeAliases);
     function pushParentRef(childNode, parentTitle) {
         // Deduplicate by (field, title) — same parent via different fields is intentional
         if (!childNode.resolvedParents.some((r) => r.field === field && r.title === parentTitle)) {
-            childNode.resolvedParents.push({ title: parentTitle, field, fieldOn, source, selfRef });
+            childNode.resolvedParents.push({
+                title: parentTitle,
+                field,
+                fieldOn,
+                source,
+                ...(hierarchy !== undefined ? { hierarchy } : {}),
+                selfRef,
+            });
         }
     }
     function checkShape(ownerNode, rawField) {
@@ -54,6 +62,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolved
                 field,
                 reason: 'invalid_shape',
                 message: `Field "${field}" must be a wikilink string, got ${typeof rawField}`,
+                source: ownerNode.source,
             });
             return false;
         }
@@ -69,6 +78,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolved
                 field,
                 reason: 'not_found',
                 message: `Link target "${target}" in field "${field}" not found`,
+                source: ownerNode.source,
             });
             return null;
         }
@@ -79,6 +89,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolved
                 field,
                 reason: 'ambiguous',
                 message: `Link target "${target}" in field "${field}" is ambiguous (matches multiple nodes)`,
+                source: ownerNode.source,
             });
             return null;
         }
@@ -126,14 +137,41 @@ 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.
+ * parent links using the levels of every hierarchy and the relationships from schema metadata.
  *
  * Returns the enriched nodes and any unresolved refs (broken/invalid wikilinks).
  */
 export function resolveGraphEdges(nodes, metadata) {
-    const levels = metadata.hierarchy?.levels ?? [];
+    const hierarchies = metadata.hierarchies ?? [];
     const relationships = metadata.relationships ?? [];
     const typeAliases = metadata.typeAliases;
     const unresolvedRefs = [];
@@ -141,6 +179,7 @@ export function resolveGraphEdges(nodes, metadata) {
         ...n,
         resolvedType: resolveNodeType(n.type, typeAliases),
         resolvedParents: [],
+        resolvedLinks: [],
     }));
     const targetIndex = buildTargetIndex(spaceNodes);
     // Build nodesByType map
@@ -152,27 +191,35 @@ export function resolveGraphEdges(nodes, metadata) {
         }
         nodesByType.get(type).push(node);
     }
-    // 1. Process hierarchy levels
-    for (let i = 0; i < levels.length; i++) {
-        const level = levels[i];
-        // Regular relationship (child type → parent type)
-        if (i > 0) {
-            const parentLevel = levels[i - 1];
-            resolveEdge(nodesByType, targetIndex, {
-                type: level.type,
-                parent: parentLevel.type,
-                field: level.field,
-                fieldOn: level.fieldOn,
-                multiple: level.multiple,
-            }, 'hierarchy', false, unresolvedRefs, typeAliases);
-        }
-        // Same-type relationship (child type → same type) via primary field
-        if (level.selfRef) {
-            resolveEdge(nodesByType, targetIndex, { type: level.type, parent: level.type, field: level.field, fieldOn: level.fieldOn, multiple: level.multiple }, 'hierarchy', true, unresolvedRefs, typeAliases);
-        }
-        // Same-type relationship via explicit selfRefField
-        if (level.selfRefField) {
-            resolveEdge(nodesByType, targetIndex, { type: level.type, parent: level.type, field: level.selfRefField, fieldOn: 'child', multiple: false }, 'hierarchy', true, unresolvedRefs, typeAliases);
+    // 1. Process the levels of each hierarchy
+    for (const { name, levels } of hierarchies) {
+        for (let i = 0; i < levels.length; i++) {
+            const level = levels[i];
+            // Regular relationship (child type → parent type)
+            if (i > 0) {
+                const parentLevel = levels[i - 1];
+                resolveEdge(nodesByType, targetIndex, {
+                    type: level.type,
+                    parent: parentLevel.type,
+                    field: level.field,
+                    fieldOn: level.fieldOn,
+                    multiple: level.multiple,
+                }, 'hierarchy', name, false, unresolvedRefs, typeAliases);
+            }
+            // Same-type relationship (child type → same type) via primary field
+            if (level.selfRef) {
+                resolveEdge(nodesByType, targetIndex, {
+                    type: level.type,
+                    parent: level.type,
+                    field: level.field,
+                    fieldOn: level.fieldOn,
+                    multiple: level.multiple,
+                }, 'hierarchy', name, true, unresolvedRefs, typeAliases);
+            }
+            // Same-type relationship via explicit selfRefField
+            if (level.selfRefField) {
+                resolveEdge(nodesByType, targetIndex, { type: level.type, parent: level.type, field: level.selfRefField, fieldOn: 'child', multiple: false }, 'hierarchy', name, true, unresolvedRefs, typeAliases);
+            }
         }
     }
     // 2. Process additional relationships
@@ -184,7 +231,11 @@ export function resolveGraphEdges(nodes, metadata) {
             fieldOn: rel.fieldOn,
             multiple: rel.multiple,
         };
-        resolveEdge(nodesByType, targetIndex, edge, 'relationship', rel.type === rel.parent, unresolvedRefs, typeAliases);
+        resolveEdge(nodesByType, targetIndex, edge, 'relationship', undefined, 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).

package/dist/read/wikilink-utils.d.ts

@@ -1,4 +1,21 @@
 import type { BaseNode } from '../types';
+export interface ParsedWikilink {
+    target: string;
+    anchor?: string;
+    displayText?: string;
+}
+/**
+ * Format a wikilink string.
+ * formatWikilink('My Goal') -> '[[My Goal]]'
+ * formatWikilink('My Goal', 'Custom Display') -> '[[My Goal|Custom Display]]'
+ */
+export declare function formatWikilink(target: string, alias?: string): string;
+/**
+ * Parse a wikilink or link inner string into target, anchor, and displayText.
+ * Handles: [[target]], [[target#anchor]], [[target|alias]], [[target#anchor|alias]]
+ * Also handles bare forms without enclosing brackets.
+ */
+export declare function parseWikilink(wikilink: string): ParsedWikilink;
 /**
  * Extract the lookup key from a wikilink string such as:
  *   [[Personal Vision]]                → "Personal Vision"