structured-context 0.10.0 → 0.12.0

package/dist/commands/schemas.js

@@ -1,8 +1,12 @@
 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 { dirname, join, resolve } from 'node:path';
+import { loadConfig } from '../config';
+import { discoverPlugins } from '../plugins/loader';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema, } from '../schema/schema';
+import { mergeVariantProperties, resolveRef } from '../schema/schema-refs';
+import { DEFAULT_SEVERITY_BY_CATEGORY } from '../schema/validate-rules';
+import { createSpaceContext } from '../space-context';
 function isBundledPath(schemaPath) {
     return dirname(schemaPath) === bundledSchemasDir;
 }
@@ -21,6 +25,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 +35,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'),
         };
@@ -72,9 +77,14 @@ function showDefs(defs) {
     }
 }
 function showMetadata(metadata) {
-    if (metadata.hierarchy?.levels.length) {
-        const parts = metadata.hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type));
-        console.log(`\nhierarchy: ${parts.join(' → ')}`);
+    const hierarchies = metadata.hierarchies ?? [];
+    if (hierarchies.length > 0) {
+        console.log('');
+        for (const hierarchy of hierarchies) {
+            const parts = hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type));
+            const main = hierarchy === metadata.hierarchy ? ' (main)' : '';
+            console.log(`hierarchy "${hierarchy.name}"${main}: ${parts.join(' → ')}`);
+        }
     }
     else {
         console.log('\nhierarchy: (none)');
@@ -87,15 +97,16 @@ function showMetadata(metadata) {
         const groups = new Map();
         for (const rule of metadata.rules) {
             const rules = groups.get(rule.category) ?? [];
-            rules.push({ id: rule.id, description: rule.description });
+            rules.push(rule);
             groups.set(rule.category, rules);
         }
         if (groups.size > 0) {
             console.log('\nRules:');
-            for (const [group, items] of groups) {
-                console.log(`  ${group}:`);
-                for (const item of items) {
-                    console.log(`    ${item.id}: ${item.description}`);
+            for (const [category, rules] of groups) {
+                console.log(`  ${category} (default severity: ${DEFAULT_SEVERITY_BY_CATEGORY[category]}):`);
+                for (const rule of rules) {
+                    const override = rule.severity ? ` [severity: ${rule.severity}]` : '';
+                    console.log(`    ${rule.id}: ${rule.description}${override}`);
                 }
             }
         }
@@ -109,7 +120,7 @@ function showMetadata(metadata) {
         }
     }
 }
-function showRegistry(schemaPath, schemaRefRegistry) {
+function showRegistry(schemaPath, schemaRefRegistry, pluginSchemas) {
     const bundledIds = new Set();
     if (existsSync(bundledSchemasDir)) {
         for (const file of readdirSync(bundledSchemasDir).filter((f) => f.endsWith('.json'))) {
@@ -118,9 +129,22 @@ function showRegistry(schemaPath, schemaRefRegistry) {
                 bundledIds.add(s.$id);
         }
     }
+    const pluginIds = new Set();
+    if (pluginSchemas) {
+        for (const { schemasDir } of pluginSchemas) {
+            if (!existsSync(schemasDir))
+                continue;
+            for (const file of readdirSync(schemasDir).filter((f) => f.endsWith('.json'))) {
+                const s = readRawSchema(join(schemasDir, file));
+                if (typeof s.$id === 'string')
+                    pluginIds.add(s.$id);
+            }
+        }
+    }
     console.log(`\nRegistry (${schemaPath}):`);
     for (const [id] of schemaRefRegistry) {
-        console.log(`  [${bundledIds.has(id) ? 'bundled' : 'local'}]  ${id}`);
+        const origin = bundledIds.has(id) ? 'bundled' : pluginIds.has(id) ? 'plugin' : 'local';
+        console.log(`  [${origin}]  ${id}`);
     }
 }
 /**
@@ -129,7 +153,6 @@ function showRegistry(schemaPath, schemaRefRegistry) {
  */
 function generateMermaidErd(metadata, entities) {
     let mmd = 'erDiagram\n';
-    const hierarchyLevels = metadata.hierarchy?.levels ?? [];
     // Generate entity definitions with properties
     for (const entity of entities) {
         const safeName = entity.type.replace(/[^a-zA-Z0-9_]/g, '_');
@@ -144,8 +167,8 @@ function generateMermaidErd(metadata, entities) {
         }
         mmd += '  }\n';
     }
-    // Generate relationships based on hierarchy metadata
-    if (hierarchyLevels.length > 0) {
+    // Generate relationships based on the levels of each hierarchy
+    for (const { levels: hierarchyLevels } of metadata.hierarchies ?? []) {
         for (let i = 0; i < hierarchyLevels.length - 1; i++) {
             const current = hierarchyLevels[i];
             const next = hierarchyLevels[i + 1];
@@ -165,7 +188,7 @@ function generateMermaidErd(metadata, entities) {
     }
     return mmd;
 }
-export function listSchemas() {
+export async function listSchemas() {
     const config = loadConfig();
     // List all schemas known to config
     if (existsSync(bundledSchemasDir)) {
@@ -181,6 +204,23 @@ export function listSchemas() {
             }
         }
     }
+    // List schemas provided by discovered plugins
+    const plugins = await discoverPlugins();
+    for (const p of plugins) {
+        if (p.schemasDir && existsSync(p.schemasDir)) {
+            const files = readdirSync(p.schemasDir)
+                .filter((f) => f.endsWith('.json'))
+                .sort();
+            if (files.length > 0) {
+                console.log(`\nPlugin schemas (${p.name}):`);
+                for (const file of files) {
+                    const schema = readRawSchema(join(p.schemasDir, file));
+                    const id = typeof schema.$id === 'string' ? schema.$id : '(no $id)';
+                    console.log(`  ${file}${file.startsWith('_') ? '  [partial]' : ''}  (${id})`);
+                }
+            }
+        }
+    }
     const configured = [];
     const seen = new Set();
     if (config.schema && !isBundledPath(config.schema)) {
@@ -200,16 +240,23 @@ export function listSchemas() {
         }
     }
 }
-export function showSchema(file, options) {
+export async function showSchema(file, options) {
     const config = loadConfig();
     let schemaPath;
+    let schema;
+    let schemaRefRegistry;
+    let pluginSchemas;
     if (options.space) {
         const space = config.spaces.find((s) => s.name === options.space);
         if (!space) {
             console.error(`Error: Unknown space "${options.space}"`);
             process.exit(1);
         }
-        schemaPath = resolveSchema(config, space);
+        const context = createSpaceContext(options.space, config);
+        schemaPath = context.resolvedSchemaPath;
+        schema = context.schema;
+        schemaRefRegistry = context.schemaRefRegistry;
+        pluginSchemas = resolveSpacePluginSchemas(context.space, config, context.configDir);
     }
     else if (!file) {
         console.error('Error: specify a file argument or use --space');
@@ -219,7 +266,49 @@ export function showSchema(file, options) {
         schemaPath = file;
     }
     else {
-        schemaPath = join(bundledSchemasDir, file.endsWith('.json') ? file : `${file}.json`);
+        // Check discovered plugins
+        const discovered = await discoverPlugins();
+        pluginSchemas = discovered
+            .filter((p) => p.schemasDir)
+            .map((p) => ({ pluginName: shortenPluginName(p.name), schemasDir: p.schemasDir }));
+        let candidatePath;
+        if (file.includes('/')) {
+            const slashIdx = file.indexOf('/');
+            const prefix = file.slice(0, slashIdx);
+            const subPath = file.slice(slashIdx + 1);
+            const norm = normalizePluginName(prefix);
+            const short = shortenPluginName(prefix);
+            const pluginDir = resolvePluginSchemasDir(prefix, process.cwd());
+            if (pluginDir) {
+                candidatePath = resolve(pluginDir, subPath.endsWith('.json') ? subPath : `${subPath}.json`);
+                if (!pluginSchemas.some((ps) => ps.pluginName === short)) {
+                    pluginSchemas.push({ pluginName: short, schemasDir: pluginDir });
+                }
+            }
+            else {
+                const match = discovered.find((p) => (p.name === norm || p.name === short) && p.schemasDir);
+                if (match?.schemasDir) {
+                    candidatePath = resolve(match.schemasDir, subPath.endsWith('.json') ? subPath : `${subPath}.json`);
+                }
+            }
+        }
+        else {
+            for (const p of discovered) {
+                if (p.schemasDir) {
+                    const c = resolve(p.schemasDir, file.endsWith('.json') ? file : `${file}.json`);
+                    if (existsSync(c)) {
+                        candidatePath = c;
+                        break;
+                    }
+                }
+            }
+        }
+        if (candidatePath && existsSync(candidatePath)) {
+            schemaPath = candidatePath;
+        }
+        else {
+            schemaPath = join(bundledSchemasDir, file.endsWith('.json') ? file : `${file}.json`);
+        }
     }
     if (!existsSync(schemaPath)) {
         console.error(`Schema not found: ${schemaPath}`);
@@ -236,7 +325,11 @@ export function showSchema(file, options) {
         process.stdout.write(content);
         return;
     }
-    const { schema, schemaRefRegistry } = loadSchema(schemaPath);
+    if (!schema || !schemaRefRegistry) {
+        const loaded = loadSchema(schemaPath, pluginSchemas);
+        schema = loaded.schema;
+        schemaRefRegistry = loaded.schemaRefRegistry;
+    }
     // Handle --mermaid-erd: generate ERD and exit
     if (options.mermaidErd) {
         const entityInfo = extractEntityInfo(schema, schemaRefRegistry);
@@ -264,5 +357,5 @@ export function showSchema(file, options) {
             console.log(`  ${ref}`);
         }
     }
-    showRegistry(schemaPath, schemaRefRegistry);
+    showRegistry(schemaPath, schemaRefRegistry, pluginSchemas);
 }

package/dist/commands/show.d.ts

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

package/dist/commands/show.js

@@ -1,6 +1,12 @@
 import { executeRender } from '../render/render';
 export async function show(context, options) {
-    const result = await executeRender('markdown.bullets', context, { filter: options?.filter });
+    const result = await executeRender('markdown.bullets', context, {
+        filter: options?.filter,
+        hierarchy: options?.hierarchy,
+    });
+    if (typeof result !== 'string') {
+        throw new Error('Expected string output from markdown.bullets renderer');
+    }
     process.stdout.write(result);
     if (!result.endsWith('\n'))
         process.stdout.write('\n');

package/dist/commands/spaces.d.ts

@@ -1 +1,3 @@
-export declare function listSpaces(): void;
+export declare function listSpaces(options?: {
+    json?: boolean;
+}): void;

package/dist/commands/spaces.js

@@ -1,21 +1,28 @@
 import { basename, resolve } from 'node:path';
-import { configPath, loadConfig } from '../config';
+import { configPath, getConfigSourceFiles, loadConfig } from '../config';
 function renderConfigValue(v) {
     if (typeof v === 'object' && v !== null)
         return JSON.stringify(v);
     return String(v);
 }
-export function listSpaces() {
+export function listSpaces(options = {}) {
     const path = resolve(configPath());
     const config = loadConfig();
+    if (options.json) {
+        const spaces = config.spaces.map((space) => ({
+            name: space.name,
+            path: space.path,
+            schema: space.schema ?? config.schema,
+        }));
+        console.log(JSON.stringify({ configFiles: [...getConfigSourceFiles()], spaces }));
+        return;
+    }
     console.log(`Config: ${path}\n`);
     for (const space of config.spaces) {
         console.log(`${space.name}`);
         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,34 @@ 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 issue of Object.values(result.errors)) {
+            console.log(`  [${issueLabel(issue)}] ${issue.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 issue of Object.values(result.warnings)) {
+            console.log(`  ${yellow}[${issueLabel(issue)}]${reset} ${issue.message}`);
+        }
     }
     console.log('');
 }
+function issueLabel({ kind, severity }) {
+    return severity ? `${kind}:${severity}` : kind;
+}

package/dist/commands/validate.js

@@ -1,18 +1,22 @@
 import { dirname } from 'node:path';
 import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
+import { resolveSpacePluginSchemas } from '../plugins/util';
 import { bundledSchemasDir } from '../schema/schema';
 import { formatErrors, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
     const { schema, schemaRefRegistry } = context;
     const result = await validateSpace(context);
+    const ruleCounts = { error: 0, warning: 0, info: 0 };
+    for (const v of result.ruleViolations)
+        ruleCounts[v.severity]++;
     // JSON output mode
     if (options.json) {
         const errorsByFile = {};
-        const addError = (file, key, kind, message) => {
+        const addError = (file, key, kind, message, severity) => {
             if (!errorsByFile[file])
                 errorsByFile[file] = {};
-            errorsByFile[file][key] = { kind, message };
+            errorsByFile[file][key] = severity ? { kind, message, severity } : { kind, message };
         };
         for (const { file, errors: ajvErrors, nodeData } of result.nodeErrors) {
             const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, nodeData);
@@ -30,23 +34,28 @@ export async function validate(context, options = {}) {
             }
         }
         for (const v of result.ruleViolations) {
-            if (v.file) {
-                addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`);
+            if (v.file && v.severity === 'error') {
+                addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`, v.severity);
             }
         }
+        const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.file && v.severity === 'error').length;
         for (const v of result.hierarchyViolations) {
             addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description);
         }
         const parseErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
-        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) + parseErrorCount;
+        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) +
+            parseErrorCount +
+            globalRuleErrorCount;
         console.log(JSON.stringify({
             space: context.space.name,
             valid: errorCount === 0,
             validCount: result.validCount,
             errorCount,
             errors: errorsByFile,
+            ruleViolations: result.ruleViolations,
             orphanCount: result.orphans.length,
             parseIssues: result.parseIssues,
+            unresolvedContentLinks: result.unresolvedContentLinks,
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
     }
@@ -78,9 +87,12 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Schema validation errors', result.nodeErrorCount, true));
     console.log(fmt('  Broken links', result.refErrors.length, true));
     console.log(fmt('  Duplicate keys', result.duplicateErrors.length, true));
-    console.log(fmt('  Rule violations', result.ruleViolations.length, true));
+    console.log(fmt('  Rule violations (error)', ruleCounts.error, true));
+    console.log(fmt('  Rule violations (warning)', ruleCounts.warning, true, true));
+    console.log(fmt('  Rule violations (info)', ruleCounts.info, true, 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,17 +100,33 @@ 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) {
+            const loc = issue.line !== undefined ? `:${issue.line}${issue.column !== undefined ? `:${issue.column}` : ''}` : '';
             const detail = issue.message ? ` - ${issue.message}` : '';
-            console.log(`   ${issue.file}: ${issue.severity} - ${issue.type}${detail}`);
+            console.log(`   ${issue.file}${loc}: ${issue.severity} - ${issue.type}${detail}`);
         }
     }
     if (result.nodeErrors.length > 0) {
         console.log(`\nSchema validation errors:`);
-        result.nodeErrors.forEach(({ file, errors, nodeData }) => {
-            console.log(`\n   ${file}:`);
+        result.nodeErrors.forEach(({ file, line, errors, nodeData }) => {
+            const loc = line !== undefined ? `:${line}` : '';
+            console.log(`\n   ${file}${loc}:`);
             const formatted = formatErrors(errors, schema, schemaRefRegistry, nodeData);
             formatted.forEach(({ message }) => {
                 console.log(`      ${message}`);
@@ -107,8 +135,9 @@ export async function validate(context, options = {}) {
     }
     if (result.refErrors.length > 0) {
         console.log(`\nBroken links:`);
-        result.refErrors.forEach(({ file, parent, error }) => {
-            console.log(`   ${file}: ${parent} → ${error}`);
+        result.refErrors.forEach(({ file, line, parent, error }) => {
+            const loc = line !== undefined ? `:${line}` : '';
+            console.log(`   ${file}${loc}: ${parent} → ${error}`);
         });
     }
     if (result.duplicateErrors.length > 0) {
@@ -122,16 +151,14 @@ export async function validate(context, options = {}) {
     }
     if (result.ruleViolations.length > 0) {
         console.log(`\nRule violations:`);
-        const byCategory = new Map();
-        for (const v of result.ruleViolations) {
-            if (!byCategory.has(v.category))
-                byCategory.set(v.category, []);
-            byCategory.get(v.category).push(v);
-        }
-        for (const [category, violations] of byCategory) {
-            console.log(`  ${category.toUpperCase()} (${violations.length}):`);
+        const severityColor = { error: red, warning: yellow, info: reset };
+        for (const severity of ['error', 'warning', 'info']) {
+            const violations = result.ruleViolations.filter((v) => v.severity === severity);
+            if (violations.length === 0)
+                continue;
+            console.log(`  ${severityColor[severity]}${severity.toUpperCase()}${reset} (${violations.length}):`);
             for (const v of violations) {
-                console.log(`    ${v.file ? `${v.file}: ` : ''}${v.description}`);
+                console.log(`    ${v.file ? `${v.file}: ` : ''}${v.description} [${v.category}: ${v.ruleId}]`);
             }
         }
     }
@@ -145,7 +172,7 @@ export async function validate(context, options = {}) {
     if (result.nodeErrorCount > 0 ||
         result.refErrors.length > 0 ||
         result.duplicateErrors.length > 0 ||
-        result.ruleViolations.length > 0 ||
+        ruleCounts.error > 0 ||
         result.hierarchyViolations.length > 0 ||
         parseIssueErrorCount > 0) {
         return 1;
@@ -161,6 +188,12 @@ export async function watchValidate(context) {
     if (schemaDir !== bundledSchemasDir) {
         schemaDirs.push(schemaDir);
     }
+    const pluginSources = resolveSpacePluginSchemas(context.space, context.config, context.configDir);
+    for (const ps of pluginSources) {
+        if (!schemaDirs.includes(ps.schemasDir)) {
+            schemaDirs.push(ps.schemasDir);
+        }
+    }
     console.log(`👀 Watching for changes...`);
     console.log(`   Config files: ${configFiles.join(', ')}`);
     console.log(`   Schema dirs: ${schemaDirs.join(', ')}`);

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,28 @@ 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 a schema identifier or path to an absolute file path.
+ *
+ * Precedence:
+ * 1. Absolute path or URL → used directly.
+ * 2. Explicit relative path (./... or ../...) → resolved relative to configDir.
+ * 3. Plugin-qualified path (e.g. "sctx-wardley-mapping/wardley_map.json" or "wardley-mapping/wardley_map.json"):
+ *    resolved against the matching loaded plugin's schemasDir.
+ * 4. Simple filename without directory (e.g. "wardley_map.json" or "strategy_general.json"):
+ *    - configDir/filename if it exists
+ *    - plugin.schemasDir/filename for any loaded plugin with schemasDir
+ *    - bundledSchemasDir/filename if it exists
+ *    - fallback: configDir/filename
+ */
+export declare function resolveSchemaPath(rawSchema: string | undefined, configDir: string, space?: SpaceConfig, config?: Config): string;
 /** 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 {};
+export declare function resolveSchema(config: Config, space?: SpaceConfig, options?: {
+    configDir?: string;
+}): string;
+/** 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;