structured-context 0.10.0 → 0.11.0

package/README.md

@@ -335,13 +335,26 @@ sctx schemas show strategy_general --mermaid-erd
 sctx miro-sync <space> [--new-frame <title>] [--dry-run] [--verbose]
 ```
 
-Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `miroBoardId` set in the space's config entry.
+Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `boardId` set in the `miro` plugin config for the space.
 
-- `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `miroFrameId` back to the config file
+- `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `frameId` back to the miro plugin config
 - `--dry-run` — show what would change without touching Miro
 - `--verbose` / `-v` — detailed per-card and per-connector output
 
-On subsequent runs, the cached `miroFrameId` is used automatically. Cards are colour-coded by node type and linked by parent→child connectors. A local `.miro-cache/` directory tracks Miro IDs to enable incremental updates.
+Configure the miro plugin in the space's config entry:
+
+```json
+{
+  "plugins": {
+    "miro": {
+      "boardId": "your-board-id",
+      "frameId": "your-frame-id"
+    }
+  }
+}
+```
+
+On subsequent runs, the cached `frameId` is used automatically. Cards are colour-coded by node type and linked by parent→child connectors. A local `.miro-cache/` directory tracks Miro IDs to enable incremental updates.
 
 Sync is one-way (OST → Miro) and scoped to a single frame. Only cards and connectors created by this tool within that frame are managed — everything else on the board is left untouched. Card content and connectors are overwritten or recreated to match the markdown source; any edits made directly in Miro to managed cards will be lost on the next sync. Existing card positions are not changed.
 
@@ -357,6 +370,12 @@ Keeps Obsidian template files in sync with schema examples:
 - `templatePrefix` in `plugins.markdown` config (default blank) sets a naming convention for templates (`{templatePrefix}{type}.md`). This will be used to check existing filenames, and create new templates with `--create-missing`.
 - `--dry-run` previews changes without writing files
 
+## Programmatic API
+
+The package exposes a library entry point at `structured-context/api` for embedding the tooling
+in other applications. See
+[docs/api.md](docs/api.md) for the full reference and usage examples.
+
 ## Development
 
 ```bash

package/dist/api.d.ts

@@ -3,13 +3,31 @@
  *
  * Import from this module to use structured-context as a library:
  *
- *   import { validateFile } from 'structured-context/api';
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
  *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *
+ * Common patterns:
+ *
+ *   const config = loadConfig();
+ *   const graph = await loadSpaceGraph('my-space', config, { filter: 'my-view' });
+ *
+ *   // Read once, then assemble a graph and validate from the same read and context:
+ *   const ctx = createSpaceContext('my-space', config);
+ *   const readResult = await readSpace(ctx);
+ *   const graph = await assembleSpaceGraph(ctx, { readResult });
+ *   const validation = await validateSpace(ctx, { readResult });
  */
 export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
 export type { Config, SpaceConfig } from './config';
+export { loadConfig, setConfigPath } from './config';
+export { PLUGIN_PREFIX } from './constants';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
+export { readSpace } from './read/read-space';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
+export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
+export { createSpaceContext, SpaceNotFoundError } from './space-context';
 export type { SpaceGraph } from './space-graph';
-export type { BaseNode, EdgeDefinition, FileNotInSpaceResult, FileValidationResult, HierarchyLevel, ParseIssue, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
-export { validateFile } from './validate';
+export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationResult, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
+export type { ValidationResult } from './validate';
+export { validateFile, validateSpace } from './validate';

package/dist/api.js

@@ -3,7 +3,24 @@
  *
  * Import from this module to use structured-context as a library:
  *
- *   import { validateFile } from 'structured-context/api';
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
  *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *
+ * Common patterns:
+ *
+ *   const config = loadConfig();
+ *   const graph = await loadSpaceGraph('my-space', config, { filter: 'my-view' });
+ *
+ *   // Read once, then assemble a graph and validate from the same read and context:
+ *   const ctx = createSpaceContext('my-space', config);
+ *   const readResult = await readSpace(ctx);
+ *   const graph = await assembleSpaceGraph(ctx, { readResult });
+ *   const validation = await validateSpace(ctx, { readResult });
  */
-export { validateFile } from './validate';
+export { loadConfig, setConfigPath } from './config';
+export { PLUGIN_PREFIX } from './constants';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
+export { readSpace } from './read/read-space';
+export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
+export { createSpaceContext, SpaceNotFoundError } from './space-context';
+export { validateFile, validateSpace } from './validate';

package/dist/commands/diagram.js

@@ -1,7 +1,7 @@
 import { writeFileSync } from 'node:fs';
 import { executeRender } from '../render/render';
 export async function diagram(context, options) {
-    const result = await executeRender('markdown.mermaid', context, { filter: options.filter });
+    const result = await executeRender('mermaid.graph', context, { filter: options.filter });
     if (options.output) {
         writeFileSync(options.output, result);
         console.log(`Mermaid diagram written to ${options.output}`);

package/dist/commands/miro-sync.d.ts

@@ -0,0 +1,3 @@
+import type { SyncOptions } from '../plugins/miro/sync';
+import type { SpaceContext } from '../types';
+export declare function miroSyncCommand(context: SpaceContext, options: SyncOptions): Promise<void>;

package/dist/commands/miro-sync.js

@@ -0,0 +1,8 @@
+import { executeRender } from '../render/render';
+export async function miroSyncCommand(context, options) {
+    const summary = await executeRender('sctx-miro:board', context, {
+        filter: undefined,
+        data: options,
+    });
+    console.log(summary);
+}

package/dist/commands/schemas.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { loadConfig, resolveSchema } from '../config';
 import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema } from '../schema/schema';
-import { mergeVariantProperties } from '../schema/schema-refs';
+import { mergeVariantProperties, resolveRef } from '../schema/schema-refs';
 function isBundledPath(schemaPath) {
     return dirname(schemaPath) === bundledSchemasDir;
 }
@@ -21,6 +21,7 @@ function extractRefs(obj, refs) {
 function extractEntities(oneOf, schemaRefRegistry, schema) {
     return oneOf.map((entry) => {
         const entryObj = entry;
+        const resolvedObj = resolveRef(entryObj, schema, schemaRefRegistry) ?? entryObj;
         const { properties, required } = mergeVariantProperties(entryObj, schema, schemaRefRegistry);
         const typeDef = properties.type;
         let types = [];
@@ -30,7 +31,7 @@ function extractEntities(oneOf, schemaRefRegistry, schema) {
             types = typeDef.enum.map(String);
         return {
             types,
-            description: typeof entryObj.description === 'string' ? entryObj.description : undefined,
+            description: typeof resolvedObj.description === 'string' ? resolvedObj.description : undefined,
             properties: Object.keys(properties).filter((k) => k !== 'type'),
             required: required.filter((r) => r !== 'type'),
         };

package/dist/commands/spaces.js

@@ -14,8 +14,6 @@ export function listSpaces() {
         console.log(`  path:    ${space.path}`);
         const schema = space.schema ?? config.schema;
         console.log(`  schema:  ${schema ? basename(schema) : '(none)'}`);
-        if (space.miroBoardId)
-            console.log(`  miro:    configured`);
         const plugins = space.plugins ?? {};
         if (Object.keys(plugins).length > 0) {
             console.log('  plugins:');

package/dist/commands/validate-file.js

@@ -21,19 +21,31 @@ export async function validateFileCommand(filePath, options = {}) {
     else {
         printHumanReadable(result);
     }
-    return Object.keys(result.errors).length > 0 ? 1 : 0;
+    return result.errorCount > 0 ? 1 : 0;
 }
 function printHumanReadable(result) {
     const reset = '\x1b[0m';
     const green = '\x1b[32m';
     const red = '\x1b[31m';
-    if (result.errorCount === 0) {
+    const yellow = '\x1b[33m';
+    if (result.errorCount === 0 && result.warningCount === 0) {
         console.log(`${green}✓${reset} ${result.label} (space: ${result.space})`);
         return;
     }
-    console.log(`\n${red}✗${reset} ${result.label} (space: ${result.space}) — ${result.errorCount} error(s)\n`);
-    for (const { kind, message } of Object.values(result.errors)) {
-        console.log(`  [${kind}] ${message}`);
+    if (result.errorCount > 0) {
+        console.log(`\n${red}✗${reset} ${result.label} (space: ${result.space}) — ${result.errorCount} error(s)\n`);
+        for (const { kind, message } of Object.values(result.errors)) {
+            console.log(`  [${kind}] ${message}`);
+        }
+    }
+    else {
+        console.log(`\n${green}✓${reset} ${result.label} (space: ${result.space})`);
+    }
+    if (result.warningCount > 0) {
+        console.log(`\n  ${yellow}${result.warningCount} warning(s):${reset}`);
+        for (const { kind, message } of Object.values(result.warnings)) {
+            console.log(`  ${yellow}[${kind}]${reset} ${message}`);
+        }
     }
     console.log('');
 }

package/dist/commands/validate.js

@@ -47,6 +47,7 @@ export async function validate(context, options = {}) {
             errors: errorsByFile,
             orphanCount: result.orphans.length,
             parseIssues: result.parseIssues,
+            unresolvedContentLinks: result.unresolvedContentLinks,
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
     }
@@ -81,6 +82,7 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Rule violations', result.ruleViolations.length, true));
     console.log(fmt('  Hierarchy violations', result.hierarchyViolations.length, true));
     console.log(fmt('  Orphans (hierarchy nodes - no parent)', result.orphans.length, true, true));
+    console.log(fmt('  Unresolved content links', result.unresolvedContentLinks.length, true, true));
     const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
     console.log(fmt('  Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0));
     if (result.orphans.length > 0) {
@@ -88,6 +90,20 @@ export async function validate(context, options = {}) {
         for (const node of result.orphans)
             console.log(`   ${node.label}`);
     }
+    if (result.unresolvedContentLinks.length > 0) {
+        console.log(`\nUnresolved content links (may be outside-space or broken):`);
+        const byFile = new Map();
+        for (const { file, target } of result.unresolvedContentLinks) {
+            if (!byFile.has(file))
+                byFile.set(file, []);
+            byFile.get(file).push(target);
+        }
+        for (const [file, targets] of byFile) {
+            console.log(`   ${file}:`);
+            for (const target of targets)
+                console.log(`      ${target}`);
+        }
+    }
     if (result.parseIssues.length > 0) {
         console.log(`\nExcluded during parsing:`);
         for (const issue of result.parseIssues) {

package/dist/config.d.ts

@@ -2,14 +2,18 @@ export type SpaceConfig = {
     name: string;
     path: string;
     schema?: string;
-    miroBoardId?: string;
-    miroFrameId?: string;
     /** Plugin name → plugin config map. Overrides top-level plugins when set. */
     plugins?: Record<string, Record<string, unknown>>;
     /** Named filter views for this space. Keys are view names; values contain the filter expression. */
     views?: Record<string, {
         expression: string;
     }>;
+    /**
+     * Directory of the config file that defined this space, used to anchor relative plugin-config
+     * paths. Set by loadConfig; absent for a hand-assembled Config, whose callers must pass an
+     * explicit configDir to createSpaceContext. Not persisted by updateSpaceField.
+     */
+    sourceDir?: string;
 };
 export type Config = {
     spaces: SpaceConfig[];
@@ -20,19 +24,11 @@ export type Config = {
 export declare function setConfigPath(path: string | undefined): void;
 /** Get all config file paths that were loaded (main config + included configs). */
 export declare function getConfigSourceFiles(): Set<string>;
-/**
- * Get the directory of the config file that defines a given space.
- */
-export declare function getSpaceConfigDir(spaceName: string): string;
 export declare function configPath(): string;
 export declare function loadConfig(): Config;
 /** Get the full space config entry by name. Throws if not found. */
 export declare function getSpaceConfig(name: string, config: Config): SpaceConfig;
 /** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
 export declare function resolveSchema(config: Config, space?: SpaceConfig): string;
-type StringFields<T> = {
-    [K in keyof T]: T[K] extends string | undefined ? K : never;
-}[keyof T];
-/** Update a string field on a space entry and persist config. */
-export declare function updateSpaceField(spaceName: string, field: StringFields<SpaceConfig>, value: string): void;
-export {};
+/** Update a string field on a space entry and persist config. When `plugin` is given, updates that field inside `space.plugins[plugin]` instead. */
+export declare function updateSpaceField(spaceName: string, field: string, value: string, plugin?: string): void;

package/dist/config.js

@@ -4,7 +4,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import Ajv from 'ajv';
 import JSON5 from 'json5';
 import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants';
-import { normalizePluginName } from './plugins/util';
+import { normalizePluginName, shortenPluginName } from './plugins/util';
 import { bundledSchemasDir } from './schema/schema';
 const CONFIG_SCHEMA = {
     type: 'object',
@@ -17,8 +17,6 @@ const CONFIG_SCHEMA = {
                     name: { type: 'string', pattern: '^[a-z0-9_-]+$' },
                     path: { type: 'string' },
                     schema: { type: 'string' },
-                    miroBoardId: { type: 'string' },
-                    miroFrameId: { type: 'string' },
                     plugins: { type: 'object', additionalProperties: { type: 'object' } },
                     views: {
                         type: 'object',
@@ -37,7 +35,7 @@ const CONFIG_SCHEMA = {
         schema: { type: 'string' },
         includeSpacesFrom: { type: 'array', items: { type: 'string' } },
     },
-    required: ['spaces'],
+    anyOf: [{ required: ['spaces'] }, { required: ['includeSpacesFrom'] }],
     additionalProperties: false,
 };
 let _configPathOverride;
@@ -54,18 +52,6 @@ export function getConfigSourceFiles() {
     }
     return new Set(_spaceSourceFiles.values());
 }
-/**
- * Get the directory of the config file that defines a given space.
- */
-export function getSpaceConfigDir(spaceName) {
-    if (_spaceSourceFiles.size === 0) {
-        loadConfig();
-    }
-    const spaceConfigPath = _spaceSourceFiles.get(spaceName);
-    if (!spaceConfigPath)
-        throw new Error('Space config path not found');
-    return dirname(spaceConfigPath);
-}
 export function configPath() {
     if (_configPathOverride) {
         return _configPathOverride;
@@ -130,6 +116,8 @@ function _loadConfig(path) {
     if (!validate(config)) {
         throw new Error(`Invalid config in ${path}: ${JSON.stringify(validate.errors)}`);
     }
+    if (!config.spaces)
+        config.spaces = [];
     return config;
 }
 export function loadConfig() {
@@ -141,8 +129,10 @@ export function loadConfig() {
     const config = _loadConfig(path);
     _spaceSourceFiles.clear();
     // Track which spaces come from the main config file
+    const mainSourceDir = dirname(resolve(path));
     for (const space of config.spaces) {
         _spaceSourceFiles.set(space.name, path);
+        space.sourceDir = mainSourceDir;
     }
     // Load includeSpacesFrom configs and merge their spaces in, with later entries taking precedence over earlier ones
     if (config.includeSpacesFrom) {
@@ -154,8 +144,10 @@ export function loadConfig() {
                 throw new Error(`Included config contains spaces with duplicate names: ${resolvedIncludePath}`);
             }
             // Track which spaces come from this included config file
+            const includeSourceDir = dirname(resolvedIncludePath);
             for (const space of includedConfig.spaces) {
                 _spaceSourceFiles.set(space.name, resolvedIncludePath);
+                space.sourceDir = includeSourceDir;
             }
             config.spaces.push(...includedConfig.spaces);
         }
@@ -178,17 +170,27 @@ export function resolveSchema(config, space) {
     }
     return schema;
 }
-/** Update a string field on a space entry and persist config. */
-export function updateSpaceField(spaceName, field, value) {
+/** Update a string field on a space entry and persist config. When `plugin` is given, updates that field inside `space.plugins[plugin]` instead. */
+export function updateSpaceField(spaceName, field, value, plugin) {
     const sourcePath = _spaceSourceFiles.get(spaceName);
-    if (!sourcePath) {
+    if (!sourcePath)
         throw new Error(`Space "${spaceName}" not found in any config file`);
-    }
     const config = _loadConfig(sourcePath);
     const space = config.spaces?.find((s) => s.name === spaceName);
-    if (!space) {
+    if (!space)
         throw new Error(`Unknown space config: "${spaceName}". Check config.`);
+    if (plugin !== undefined) {
+        if (!space.plugins)
+            space.plugins = {};
+        const normalized = normalizePluginName(plugin);
+        const shortName = shortenPluginName(normalized);
+        const existingKey = Object.keys(space.plugins).find((k) => k === normalized || k === shortName) ?? normalized;
+        if (!space.plugins[existingKey])
+            space.plugins[existingKey] = {};
+        space.plugins[existingKey][field] = value;
+    }
+    else {
+        space[field] = value;
     }
-    space[field] = value;
     writeFileSync(sourcePath, `${JSON5.stringify(config, null, 2)}\n`);
 }

package/dist/index.js

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import { diagram } from './commands/diagram';
 import { docs } from './commands/docs';
 import { dump } from './commands/dump';
+import { miroSyncCommand } from './commands/miro-sync';
 import { listPlugins } from './commands/plugins';
 import { render, renderList } from './commands/render';
 import { listSchemas, showSchema } from './commands/schemas';
@@ -12,29 +13,20 @@ import { listSpaces } from './commands/spaces';
 import { templateSync } from './commands/template-sync';
 import { validate, watchValidate } from './commands/validate';
 import { validateFileCommand } from './commands/validate-file';
-import { getSpaceConfigDir, loadConfig, resolveSchema, setConfigPath } from './config';
+import { loadConfig, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
-import { miroSync } from './integrations/miro/sync';
-import { loadSchema } from './schema/schema';
+import { createSpaceContext, SpaceNotFoundError } from './space-context';
 export function buildSpaceContext(spaceName) {
-    const config = loadConfig();
-    const space = config.spaces.find((s) => s.name === spaceName);
-    if (!space) {
-        console.error(`Error: Unknown space "${spaceName}"`);
-        process.exit(1);
+    try {
+        return createSpaceContext(spaceName, loadConfig());
+    }
+    catch (err) {
+        if (err instanceof SpaceNotFoundError) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
     }
-    const resolvedSchemaPath = resolveSchema(config, space);
-    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath);
-    const configDir = getSpaceConfigDir(space.name);
-    return {
-        space,
-        config,
-        resolvedSchemaPath,
-        schema,
-        schemaRefRegistry,
-        schemaValidator,
-        configDir,
-    };
 }
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
@@ -97,7 +89,7 @@ program
     .option('--new-frame <title>', 'Create a new frame on the board and sync into it')
     .option('--dry-run', 'Show what would change without touching Miro')
     .option('-v, --verbose', 'Detailed output')
-    .action((spaceName, options) => miroSync(buildSpaceContext(spaceName), options));
+    .action((spaceName, options) => miroSyncCommand(buildSpaceContext(spaceName), options));
 program
     .command('template-sync')
     .description('Sync schema examples to templates')

package/dist/load-space-graph.d.ts

@@ -0,0 +1,40 @@
+import type { Config } from './config';
+import { type SpaceGraph } from './space-graph';
+import type { ReadSpaceResult, SpaceContext } from './types';
+export interface AssembleSpaceGraphOptions {
+    /** Named view (resolved via space.views) or a raw filter DSL expression. */
+    filter?: string;
+    /** Pre-loaded read result to assemble from, avoiding a re-read of the space. */
+    readResult?: ReadSpaceResult;
+}
+/**
+ * Assemble a SpaceGraph from a space context: read the space, drop nodes that
+ * fail schema validation, build the hierarchy graph, and apply an optional
+ * view/filter expression.
+ *
+ * Nodes that fail schema validation are silently excluded so the graph is
+ * well-formed enough to render and traverse. This is NOT a validation pass —
+ * schema-valid nodes may still have broken references, rule violations, or
+ * duplicates. Use validateSpace for a full validation report.
+ *
+ * Shared by the render pipeline and the public loadSpaceGraph API so their
+ * graph-assembly behaviour cannot drift.
+ */
+export declare function assembleSpaceGraph(context: SpaceContext, options?: AssembleSpaceGraphOptions): Promise<SpaceGraph>;
+export interface LoadSpaceGraphOptions extends AssembleSpaceGraphOptions {
+    /**
+     * Directory to anchor relative plugin paths against. Required when config is
+     * hand-assembled (has no source file); see {@link createSpaceContext}.
+     */
+    configDir?: string;
+}
+/**
+ * Load a named space and return its assembled, filtered SpaceGraph.
+ *
+ * Convenience entry point over createSpaceContext + assembleSpaceGraph: pass a
+ * space name, config, and optional filter. Pass options.readResult to reuse an
+ * already-loaded read (e.g. when also calling validateSpace) and skip re-reading.
+ * When you already hold a SpaceContext, call assembleSpaceGraph directly to avoid
+ * rebuilding (and recompiling the schema for) the context.
+ */
+export declare function loadSpaceGraph(spaceName: string, config: Config, options?: LoadSpaceGraphOptions): Promise<SpaceGraph>;

package/dist/load-space-graph.js

@@ -0,0 +1,42 @@
+import { filterNodes } from './filter/filter-nodes';
+import { readSpace } from './read/read-space';
+import { createSpaceContext } from './space-context';
+import { buildSpaceGraph } from './space-graph';
+/**
+ * Assemble a SpaceGraph from a space context: read the space, drop nodes that
+ * fail schema validation, build the hierarchy graph, and apply an optional
+ * view/filter expression.
+ *
+ * Nodes that fail schema validation are silently excluded so the graph is
+ * well-formed enough to render and traverse. This is NOT a validation pass —
+ * schema-valid nodes may still have broken references, rule violations, or
+ * duplicates. Use validateSpace for a full validation report.
+ *
+ * Shared by the render pipeline and the public loadSpaceGraph API so their
+ * graph-assembly behaviour cannot drift.
+ */
+export async function assembleSpaceGraph(context, options = {}) {
+    const { nodes: allNodes } = options.readResult ?? (await readSpace(context));
+    const { schemaValidator } = context;
+    const validNodes = allNodes.filter((node) => schemaValidator(node.schemaData));
+    const levels = context.schema.metadata.hierarchy?.levels ?? [];
+    let graph = buildSpaceGraph(validNodes, levels);
+    if (options.filter) {
+        const expression = context.space.views?.[options.filter]?.expression ?? options.filter;
+        graph = await filterNodes(expression, graph);
+    }
+    return graph;
+}
+/**
+ * Load a named space and return its assembled, filtered SpaceGraph.
+ *
+ * Convenience entry point over createSpaceContext + assembleSpaceGraph: pass a
+ * space name, config, and optional filter. Pass options.readResult to reuse an
+ * already-loaded read (e.g. when also calling validateSpace) and skip re-reading.
+ * When you already hold a SpaceContext, call assembleSpaceGraph directly to avoid
+ * rebuilding (and recompiling the schema for) the context.
+ */
+export async function loadSpaceGraph(spaceName, config, options = {}) {
+    const context = createSpaceContext(spaceName, config, { configDir: options.configDir });
+    return assembleSpaceGraph(context, options);
+}

package/dist/plugins/index.js

@@ -1,3 +1,5 @@
 import { markdownPlugin } from './markdown';
+import { mermaidPlugin } from './mermaid';
+import { miroPlugin } from './miro';
 /** All built-in plugins, in default load order. */
-export const builtinPlugins = [markdownPlugin];
+export const builtinPlugins = [markdownPlugin, mermaidPlugin, miroPlugin];

package/dist/plugins/loader.js

@@ -3,7 +3,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import Ajv, {} from 'ajv';
 import { getConfigSourceFiles } from '../config';
 import { builtinPlugins } from '.';
-import { CONFIG_PLUGINS_DIR, normalizePluginName, PLUGIN_PREFIX } from './util';
+import { CONFIG_PLUGINS_DIR, normalizePluginName, PLUGIN_PREFIX, shortenPluginName, } from './util';
 /**
  * Walk a plugin's configSchema and resolve any string fields annotated with
  * format:'path' relative to configDir.
@@ -92,7 +92,7 @@ export async function loadPlugins(pluginMap, configDir) {
     }
     // Built-in plugins: always loaded, config taken from map if declared (with or without prefix)
     for (const builtin of builtinPlugins) {
-        const rawConfig = pluginMap[builtin.name] ?? pluginMap[builtin.name.slice(PLUGIN_PREFIX.length)] ?? {};
+        const rawConfig = pluginMap[builtin.name] ?? pluginMap[shortenPluginName(builtin.name)] ?? {};
         const pluginConfig = resolveConfigPaths(builtin.configSchema, rawConfig, configDir);
         const validate = ajv.compile(builtin.configSchema);
         if (!validate(pluginConfig)) {

package/dist/plugins/markdown/extract-content-links.d.ts

@@ -0,0 +1,23 @@
+import type { Node } from 'mdast';
+import type { ContentLink, SchemaMetadata } from '../../types';
+/**
+ * Recursively walk an mdast subtree and collect all links.
+ * Handles standard markdown link/image nodes and scans text nodes for wikilinks.
+ */
+export declare function extractLinksFromAstNode(node: Node): ContentLink[];
+/**
+ * Extract all links from a raw markdown body string.
+ * Parses the full document and collects links from every node in the tree.
+ */
+export declare function extractLinksFromBody(body: string): ContentLink[];
+/**
+ * Build the set of field names that serve as graph edges (hierarchy + relationship fields).
+ * Used to exclude edge fields from frontmatter link extraction.
+ */
+export declare function getEdgeFieldNames(metadata: SchemaMetadata): Set<string>;
+/**
+ * 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 declare function extractLinksFromFrontmatter(data: Record<string, unknown>, edgeFields: Set<string>): ContentLink[];