structured-context 0.16.0 → 0.17.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roger Barnes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,6 +21,18 @@ Command line tools:
 ```
 > sctx validate strategy
 
+Orphans (hierarchy nodes - no parent):
+   Solution looking for a problem.md
+
+Broken links:
+   Steal underpants.md: [[Gnome goals]] → Link target "Gnome goals" in field "related" not found
+
+Rule violations:
+  WARNING (1):
+    Build Death Star.md: Opportunities should contribute to at least one Outcome [workflow: opportunity-has-outcome]
+  INFO (1):
+    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for the target opportunity [best-practice: solution-quantity]
+
 Space Validation Results
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Content and structure
@@ -35,18 +47,6 @@ Content and structure
   Orphans (hierarchy nodes - no parent)    1
   Unresolved content links                 0
   Excluded during parsing                  0
-
-Orphans (hierarchy nodes - no parent):
-   Solution looking for a problem.md
-
-Broken links:
-   Steal underpants.md: [[Gnome goals]] → Link target "Gnome goals" in field "related" not found
-
-Rule violations:
-  WARNING (1):
-    Build Death Star.md: Opportunities should contribute to at least one Outcome [workflow: opportunity-has-outcome]
-  INFO (1):
-    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for the target opportunity [best-practice: solution-quantity]
 ```
 
 Rule violations carry a severity (`error`, `warning` or `info`) that defaults from the rule's category. Only errors fail validation — see [docs/rules.md](docs/rules.md#rule-shape).
@@ -237,7 +237,7 @@ Keeps Obsidian template files in sync with schema examples:
 ## Programmatic API
 
 The package exposes a library entry point at `structured-context/api` for embedding the tooling
-in other applications. See
+in other applications, and `structured-context/browser` for loading an exported space graph in a browser. See
 [docs/api.md](docs/api.md) for the full reference and usage examples.
 
 ## Development

package/dist/api.d.ts

@@ -18,6 +18,7 @@
  *   const validation = await validateSpace(ctx, { readResult });
  */
 export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
+export { type SpaceGraph, type SpaceNode, spaceGraphFrom } from './browser';
 export type { Config, SpaceConfig } from './config';
 export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { addSpace } from './config/write';
@@ -31,7 +32,8 @@ export { listSchemas } from './schema/list-schemas';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
 export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema';
 export { createSpaceContext, SpaceNotFoundError } from './space-context';
-export { buildSpaceGraph, type SpaceGraph } from './space-graph';
-export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
+export { buildSpaceGraph } from './space-graph';
+export { exportSpaceGraph } from './space-graph-data';
+export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, UnresolvedRef, ValidateFileOutput, } from './types';
 export type { ValidationResult } from './validate';
 export { validateFile, validateSpace } from './validate';

package/dist/api.js

@@ -18,6 +18,7 @@
  *   const graph = await assembleSpaceGraph(ctx, { readResult });
  *   const validation = await validateSpace(ctx, { readResult });
  */
+export { spaceGraphFrom } from './browser';
 export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { addSpace } from './config/write';
 export { LOCAL_CONFIG_FILE, PLUGIN_PREFIX } from './constants';
@@ -29,4 +30,5 @@ export { listSchemas } from './schema/list-schemas';
 export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
 export { createSpaceContext, SpaceNotFoundError } from './space-context';
 export { buildSpaceGraph } from './space-graph';
+export { exportSpaceGraph } from './space-graph-data';
 export { validateFile, validateSpace } from './validate';

package/dist/browser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser-safe API for structured-context: nothing here imports Node built-ins.
+ *
+ * Rebuild a graph that a server exported with exportSpaceGraph:
+ *
+ *   import { spaceGraphFrom } from 'structured-context/browser';
+ *   const graph = spaceGraphFrom(await (await fetch('/graph.json')).json());
+ *
+ * Everything here is also exported from `structured-context/api`. Derive other types from these, e.g.
+ * `Parameters<typeof spaceGraphFrom>[0]` for the exported data or `SpaceNode['id']` for a node id.
+ */
+export type { SpaceGraph } from './space-graph';
+export { spaceGraphFrom } from './space-graph-data';
+export type { SpaceNode } from './types';

package/dist/browser.js

@@ -0,0 +1,13 @@
+// Public entry point: do not add exports without the maintainer's agreement (AGENTS.md, "Public API surface").
+/**
+ * Browser-safe API for structured-context: nothing here imports Node built-ins.
+ *
+ * Rebuild a graph that a server exported with exportSpaceGraph:
+ *
+ *   import { spaceGraphFrom } from 'structured-context/browser';
+ *   const graph = spaceGraphFrom(await (await fetch('/graph.json')).json());
+ *
+ * Everything here is also exported from `structured-context/api`. Derive other types from these, e.g.
+ * `Parameters<typeof spaceGraphFrom>[0]` for the exported data or `SpaceNode['id']` for a node id.
+ */
+export { spaceGraphFrom } from './space-graph-data';

package/dist/commands/dump.d.ts

@@ -4,6 +4,8 @@ export interface DumpOptions {
     filter?: string;
     /** Hierarchy used when evaluating the filter (default: the main hierarchy). */
     hierarchy?: string;
+    /** Emit SpaceGraphData (nodes plus every hierarchy) instead of nodes, source and diagnostics. */
+    graph?: boolean;
 }
 /**
  * Build the dump payload: every parsed node, or only nodes matched by a filter.

package/dist/commands/dump.js

@@ -1,5 +1,6 @@
 import { assembleSpaceGraph } from '../load-space-graph';
 import { readSpace } from '../read/read-space';
+import { exportSpaceGraph } from '../space-graph-data';
 /**
  * Build the dump payload: every parsed node, or only nodes matched by a filter.
  *
@@ -16,5 +17,6 @@ export async function buildDump(context, options = {}) {
 }
 export async function dump(context, options = {}) {
     const { nodes, source, diagnostics } = await buildDump(context, options);
-    console.log(JSON.stringify({ nodes, source, diagnostics }, null, 2));
+    const output = options.graph ? exportSpaceGraph(nodes, context.schema.metadata) : { nodes, source, diagnostics };
+    console.log(JSON.stringify(output, null, 2));
 }

package/dist/commands/schemas.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { loadConfig } from '../config';
+import { loadConfig, loadConfigOrEmpty } from '../config';
 import { discoverPlugins } from '../plugins/loader';
 import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
 import { listSchemas } from '../schema/list-schemas';
@@ -231,7 +231,8 @@ export async function printSchemas(options = {}) {
     }
 }
 export async function showSchema(file, options) {
-    const config = loadConfig();
+    // A schema named by file needs no config; a space does, so a missing one is worth a warning.
+    const config = options.space ? loadConfig() : loadConfigOrEmpty();
     let schemaPath;
     let schema;
     let schemaRefRegistry;

package/dist/commands/spaces.js

@@ -1,6 +1,5 @@
 import { basename, resolve } from 'node:path';
-import { loadConfig } from '../config';
-import { checkConfig, hasBlockingProblem } from '../config/health';
+import { hasBlockingProblem, inspectConfig } from '../config/health';
 import { addSpace } from '../config/write';
 import { SctxError } from '../errors';
 function renderConfigValue(v) {
@@ -9,7 +8,7 @@ function renderConfigValue(v) {
     return String(v);
 }
 export function listSpaces(options = {}) {
-    const health = checkConfig();
+    const { health, config } = inspectConfig();
     if (options.json) {
         console.log(JSON.stringify(health));
         if (hasBlockingProblem(health))
@@ -27,10 +26,9 @@ export function listSpaces(options = {}) {
         console.log('');
         if (hasBlockingProblem(health))
             process.exitCode = 1;
-        if (!health.config.exists)
-            return;
     }
-    const config = loadConfig();
+    if (!config)
+        return;
     if (health.problems.length === 0)
         console.log(`Config: ${path} (${health.config.source})\n`);
     for (const space of config.spaces) {

package/dist/commands/validate.js

@@ -91,26 +91,7 @@ export async function validate(context, options = {}) {
         const countStr = String(count).padStart(3);
         return `${label.padEnd(40)} ${color}${countStr}${reset}`;
     };
-    console.log(`\nSpace Validation Results`);
-    console.log(`━`.repeat(45));
-    console.log('Content and structure');
-    console.log(fmt('  Valid', result.validCount));
-    console.log(fmt('  Schema validation errors', result.nodeErrorCount, true));
-    console.log(fmt('  Broken links', result.refErrors.length, true));
-    console.log(fmt('  Duplicate ids', result.duplicateErrors.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.depthLimit !== undefined) {
-        console.log(fmt('  Skipped by depth limit', result.skippedByDepth.length, true, true));
-    }
-    const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedFiles.length, 0);
-    console.log(fmt('  Rule checks gated (cascade)', gatedFileCount, true, true));
     if (result.orphans.length > 0) {
         console.log(`\nOrphans (hierarchy nodes - no parent):`);
         for (const node of result.orphans)
@@ -207,6 +188,26 @@ export async function validate(context, options = {}) {
     if (result.contextTrimmed.nodeCount > 0) {
         console.log(`\nContext trimmed for ${result.contextTrimmed.nodeCount} node(s) across rules ${result.contextTrimmed.ruleIds.join(', ')}.`);
     }
+    // Last, so a truncated tail (`| tail`) still shows the counts.
+    console.log(`\nSpace Validation Results`);
+    console.log(`━`.repeat(45));
+    console.log('Content and structure');
+    console.log(fmt('  Valid', result.validCount));
+    console.log(fmt('  Schema validation errors', result.nodeErrorCount, true));
+    console.log(fmt('  Broken links', result.refErrors.length, true));
+    console.log(fmt('  Duplicate ids', result.duplicateErrors.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));
+    console.log(fmt('  Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0));
+    if (result.depthLimit !== undefined) {
+        console.log(fmt('  Skipped by depth limit', result.skippedByDepth.length, true, true));
+    }
+    const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedFiles.length, 0);
+    console.log(fmt('  Rule checks gated (cascade)', gatedFileCount, true, true));
     console.log(`\n`);
     if (result.nodeErrorCount > 0 ||
         result.refErrors.length > 0 ||

package/dist/config/health.d.ts

@@ -1,5 +1,5 @@
 import { type SctxErrorCode } from '../errors';
-import { type ResolvedConfigPath } from '.';
+import { type Config, type ResolvedConfigPath } from '.';
 export type ConfigProblem = {
     code: SctxErrorCode;
     severity: 'error' | 'warning' | 'info';
@@ -21,11 +21,15 @@ export type ConfigHealth = {
 };
 export declare function fixFor(code: SctxErrorCode): string;
 /**
- * Check that the config for the working directory can be found and loaded, and that each space's
- * path and schema exist. Never throws: every failure becomes a problem with a stable code.
+ * Find and load the config for the working directory, reporting failures as problems with stable
+ * codes instead of throwing. It reports on the config only: what a space's `path` means belongs to
+ * the plugin that reads it, and a schema is checked when it is loaded.
  */
-export declare function checkConfig(options?: {
+export declare function inspectConfig(options?: {
     startDir?: string;
-}): ConfigHealth;
-/** True when the health check found something that stops validation from running. */
+}): {
+    health: ConfigHealth;
+    config?: Config;
+};
+/** True when the config problems stop validation from running. */
 export declare function hasBlockingProblem(health: ConfigHealth): boolean;

package/dist/config/health.js

@@ -1,8 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs';
-import JSON5 from 'json5';
+import { existsSync } from 'node:fs';
 import { LOCAL_CONFIG_FILE } from '../constants';
 import { SctxError } from '../errors';
-import { getConfigSourceFiles, loadConfig, resolveConfigPath, resolveSchema } from '.';
+import { getConfigSourceFiles, loadConfig, resolveConfigPath } from '.';
 const FIXES = {
     E_CONFIG_NOT_FOUND: `Create a config with \`sctx spaces add <name> <path> --schema <schema> --config <folder>/${LOCAL_CONFIG_FILE}\`, or use the setup-space skill.`,
     E_CONFIG_INVALID: 'Fix the JSON in the config file named in the message; `sctx docs config` describes the shape.',
@@ -11,7 +10,7 @@ const FIXES = {
     E_SPACE_PATH_MISSING: 'The folder or file was moved or deleted. Correct `path` in the config, or remove the space.',
     E_SCHEMA_MISSING: 'Set `schema` on the space or at the top level of the config file.',
     E_SCHEMA_NOT_FOUND: 'Check the schema name or path. `sctx schemas list` shows the bundled schemas.',
-    E_SCHEMA_INVALID: 'The schema file is not valid JSON5. Open it and fix the syntax.',
+    E_SCHEMA_INVALID: 'The schema could not be loaded. The message says what to fix; `sctx docs schema` describes the format.',
 };
 export function fixFor(code) {
     return FIXES[code] ?? '';
@@ -20,10 +19,11 @@ function problem(code, severity, message, space) {
     return { code, severity, message, fix: fixFor(code), ...(space ? { space } : {}) };
 }
 /**
- * Check that the config for the working directory can be found and loaded, and that each space's
- * path and schema exist. Never throws: every failure becomes a problem with a stable code.
+ * Find and load the config for the working directory, reporting failures as problems with stable
+ * codes instead of throwing. It reports on the config only: what a space's `path` means belongs to
+ * the plugin that reads it, and a schema is checked when it is loaded.
  */
-export function checkConfig(options = {}) {
+export function inspectConfig(options = {}) {
     const resolved = resolveConfigPath(options.startDir);
     const exists = existsSync(resolved.path);
     const health = { config: { ...resolved, exists }, configFiles: [], spaces: [], problems: [] };
@@ -32,7 +32,7 @@ export function checkConfig(options = {}) {
             ? `No ${LOCAL_CONFIG_FILE} found from the working directory upward, and no global config at ${resolved.path}`
             : `Config file not found: ${resolved.path}`;
         health.problems.push(problem('E_CONFIG_NOT_FOUND', resolved.source === 'none' ? 'info' : 'error', detail));
-        return health;
+        return { health };
     }
     let config;
     try {
@@ -41,46 +41,13 @@ export function checkConfig(options = {}) {
     catch (err) {
         const code = err instanceof SctxError ? err.code : 'E_CONFIG_INVALID';
         health.problems.push(problem(code, 'error', err.message));
-        return health;
+        return { health };
     }
     health.configFiles = [...getConfigSourceFiles()];
     health.spaces = config.spaces.map((s) => ({ name: s.name, path: s.path, schema: s.schema ?? config.schema }));
-    if (config.spaces.length === 0) {
-        health.problems.push(problem('E_NO_SPACES', 'warning', `Config ${resolved.path} defines no spaces`));
-    }
-    for (const space of config.spaces) {
-        if (!existsSync(space.path)) {
-            health.problems.push(problem('E_SPACE_PATH_MISSING', 'error', `Space "${space.name}" path does not exist: ${space.path}`, space.name));
-        }
-        const schemaRef = space.schema ?? config.schema;
-        if (!schemaRef) {
-            health.problems.push(problem('E_SCHEMA_MISSING', 'error', `Space "${space.name}" has no schema`, space.name));
-            continue;
-        }
-        let schemaPath;
-        try {
-            schemaPath = resolveSchema(config, space);
-        }
-        catch (err) {
-            health.problems.push(problem('E_SCHEMA_NOT_FOUND', 'error', err.message, space.name));
-            continue;
-        }
-        if (/^https?:\/\//i.test(schemaPath))
-            continue;
-        if (!existsSync(schemaPath)) {
-            health.problems.push(problem('E_SCHEMA_NOT_FOUND', 'error', `Space "${space.name}" schema not found: ${schemaPath}`, space.name));
-            continue;
-        }
-        try {
-            JSON5.parse(readFileSync(schemaPath, 'utf-8'));
-        }
-        catch (err) {
-            health.problems.push(problem('E_SCHEMA_INVALID', 'error', `Space "${space.name}" schema ${schemaPath} is not valid: ${err.message}`, space.name));
-        }
-    }
-    return health;
+    return { health, config };
 }
-/** True when the health check found something that stops validation from running. */
+/** True when the config problems stop validation from running. */
 export function hasBlockingProblem(health) {
     return health.problems.some((p) => p.severity === 'error');
 }

package/dist/config/index.d.ts

@@ -48,6 +48,10 @@ export declare function configPath(startDir?: string): string;
 export declare function loadConfig(options?: {
     startDir?: string;
 }): Config;
+/** Like `loadConfig`, for commands that work without a config: a missing config is empty, with no warning. */
+export declare function loadConfigOrEmpty(options?: {
+    startDir?: string;
+}): Config;
 /** Get the full space config entry by name. Throws if not found. */
 export declare function getSpaceConfig(name: string, config: Config): SpaceConfig;
 /**

package/dist/config/index.js

@@ -72,7 +72,7 @@ export function setConfigPath(path) {
 /** Get all config file paths that were loaded (main config + included configs). */
 export function getConfigSourceFiles() {
     if (_spaceSourceFiles.size === 0) {
-        loadConfig();
+        loadConfigOrEmpty();
     }
     return new Set(_spaceSourceFiles.values());
 }
@@ -169,12 +169,21 @@ function expandHome(p) {
     return p === '~' || p.startsWith('~/') ? join(process.env.HOME ?? homedir(), p.slice(1)) : p;
 }
 export function loadConfig(options = {}) {
-    const { path, source } = resolveConfigPath(options.startDir);
+    return loadConfigFile(options.startDir, true);
+}
+/** Like `loadConfig`, for commands that work without a config: a missing config is empty, with no warning. */
+export function loadConfigOrEmpty(options = {}) {
+    return loadConfigFile(options.startDir, false);
+}
+function loadConfigFile(startDir, warnIfMissing) {
+    const { path, source } = resolveConfigPath(startDir);
     if (!existsSync(path)) {
-        const where = source === 'none'
-            ? `no ${LOCAL_CONFIG_FILE} found from ${resolve(options.startDir ?? process.cwd())} upward, and none at ${path}`
-            : path;
-        console.warn(`E_CONFIG_NOT_FOUND: Config file not found (${where})`);
+        if (warnIfMissing) {
+            const where = source === 'none'
+                ? `no ${LOCAL_CONFIG_FILE} found from ${resolve(startDir ?? process.cwd())} upward, and none at ${path}`
+                : path;
+            console.warn(`E_CONFIG_NOT_FOUND: Config file not found (${where})`);
+        }
         return { spaces: [] };
     }
     const config = _loadConfig(path);

package/dist/filter/augment-nodes.d.ts

@@ -2,7 +2,7 @@ import type { NodeId, SpaceNode } from '../types';
 /** Edge metadata merged into each ancestor/descendant entry. */
 export type EdgeMetadata = {
     _field: string;
-    _source: 'hierarchy' | 'relationship';
+    _kind: 'hierarchy' | 'relationship';
     /** Hierarchy name, present only for hierarchy edges. */
     _hierarchy?: string;
     _selfRef: boolean;
@@ -21,6 +21,6 @@ export type AugmentedFlatNode = Record<string, unknown> & {
  *
  * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by id.
  * - descendants: BFS via childrenIndex, nearest first, deduplicated by id.
- * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef).
+ * - Each entry merges the parent/child node's fields with edge metadata (_field, _kind, _hierarchy, _selfRef).
  */
 export declare function augmentNode(node: SpaceNode, nodeIndex: ReadonlyMap<NodeId, SpaceNode>, childrenIndex: ReadonlyMap<NodeId, readonly SpaceNode[]>): AugmentedFlatNode;

package/dist/filter/augment-nodes.js

@@ -2,7 +2,7 @@
 function edgeMetadata(ref) {
     return {
         _field: ref.field,
-        _source: ref.source,
+        _kind: ref.kind,
         ...(ref.hierarchy !== undefined ? { _hierarchy: ref.hierarchy } : {}),
         _selfRef: ref.selfRef,
     };
@@ -22,7 +22,7 @@ function flattenData(node) {
  *
  * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by id.
  * - descendants: BFS via childrenIndex, nearest first, deduplicated by id.
- * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef).
+ * - Each entry merges the parent/child node's fields with edge metadata (_field, _kind, _hierarchy, _selfRef).
  */
 export function augmentNode(node, nodeIndex, childrenIndex) {
     const ancestors = buildAncestors(node, nodeIndex);

package/dist/filter/expand-include.js

@@ -139,13 +139,13 @@ function applyDirective(node, aug, directive, childrenIndex, addById) {
         case 'relationships': {
             // Relationship-sourced ancestors (matched node is the child side)
             for (const a of aug.ancestors) {
-                if (a._source === 'relationship' && matchesRelSpec(node, a, directive, true)) {
+                if (a._kind === 'relationship' && matchesRelSpec(node, a, directive, true)) {
                     addById(a.id);
                 }
             }
             // Relationship-sourced descendants (matched node is the parent side)
             for (const d of aug.descendants) {
-                if (d._source === 'relationship' && matchesRelSpec(node, d, directive, false)) {
+                if (d._kind === 'relationship' && matchesRelSpec(node, d, directive, false)) {
                     addById(d.id);
                 }
             }

package/dist/index.js

@@ -16,6 +16,7 @@ import { validate, watchValidate } from './commands/validate';
 import { validateFileCommand } from './commands/validate-file';
 import { loadConfig, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
+import { SctxError } from './errors';
 import { JudgeConfigError } from './judge/factory';
 import { createSpaceContext, SpaceNotFoundError } from './space-context';
 // Once node:process is loaded (vfile, via unified, loads it), Bun's console.log drops piped output
@@ -121,6 +122,7 @@ program
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
     .option('--hierarchy <name>', 'Hierarchy used to evaluate --filter (default: the main hierarchy)')
+    .option('--graph', 'Output the space graph format: nodes plus every hierarchy')
     .action(async (spaceName, options) => dump(buildSpaceContext(spaceName), options));
 program
     .command('miro-sync')
@@ -227,4 +229,10 @@ renderCmd
     await render(buildSpaceContext(spaceName), format, options);
 });
 program.addCommand(renderCmd);
-program.parse();
+// Expected errors print as one line; anything else keeps its stack trace
+program.parseAsync().catch((err) => {
+    if (!(err instanceof SctxError))
+        throw err;
+    console.error(`${err.code}: ${err.message}`);
+    process.exitCode = 1;
+});

package/dist/judge/context.js

@@ -49,7 +49,7 @@ export function relatedNodes(graph, node, context) {
     const parentsOf = (n) => graph.hierarchy === undefined
         ? []
         : n.resolvedParents
-            .filter((p) => p.source === 'hierarchy' && p.hierarchy === hierarchyName)
+            .filter((p) => p.kind === 'hierarchy' && p.hierarchy === hierarchyName)
             .map((p) => graph.nodes.get(p.id))
             .filter((p) => p !== undefined);
     const childrenOf = (n) => graph.hierarchyChildren.get(n.id) ?? [];

package/dist/load-space-graph.js

@@ -1,7 +1,7 @@
 import { filterNodes } from './filter/filter-nodes';
 import { readSpace } from './read/read-space';
 import { createSpaceContext } from './space-context';
-import { buildSpaceGraph } from './space-graph';
+import { buildSpaceGraph, selectHierarchy } from './space-graph';
 /**
  * Assemble a SpaceGraph from a space context: read the space, drop nodes that
  * fail schema validation, build the graph for the selected hierarchy (the main
@@ -26,18 +26,6 @@ export async function assembleSpaceGraph(context, options = {}) {
     }
     return graph;
 }
-/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */
-function selectHierarchy(metadata, name) {
-    if (name === undefined)
-        return metadata.hierarchy;
-    const hierarchies = metadata.hierarchies ?? [];
-    const hierarchy = hierarchies.find((h) => h.name === name);
-    if (!hierarchy) {
-        const available = hierarchies.map((h) => h.name).join(', ');
-        throw new Error(`Unknown hierarchy: "${name}".${available ? ` Available: ${available}` : ' The schema defines no hierarchies.'}`);
-    }
-    return hierarchy;
-}
 /**
  * Load a named space and return its assembled, filtered SpaceGraph.
  *

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

@@ -364,7 +364,7 @@ export function extractEmbeddedNodes(body, options) {
             fieldOn: rel.fieldOn,
             multiple: rel.multiple,
             templateFormat: rel.templateFormat ?? 'heading',
-            source: 'relationship',
+            kind: 'relationship',
             matchers: rel.matchers,
             embeddedTemplateFields: rel.embeddedTemplateFields,
         };
@@ -378,7 +378,7 @@ export function extractEmbeddedNodes(body, options) {
             fieldOn: level.fieldOn,
             multiple: level.multiple,
             templateFormat: level.templateFormat ?? 'heading',
-            source: 'hierarchy',
+            kind: 'hierarchy',
             matchers: level.matchers,
             embeddedTemplateFields: level.embeddedTemplateFields,
         };
@@ -435,7 +435,7 @@ export function extractEmbeddedNodes(body, options) {
                     fieldOn: currentLevel.fieldOn,
                     multiple: currentLevel.multiple,
                     templateFormat: currentLevel.templateFormat ?? 'list',
-                    source: 'hierarchy',
+                    kind: 'hierarchy',
                     matchers: immediateParentLevel.matchers,
                 };
             }
@@ -651,7 +651,7 @@ export function extractEmbeddedNodes(body, options) {
                 // e.g. definition.type='capabilities', definition.parent='application' → capabilities is above application.
                 const typeIdx = hierarchy.indexOf(definition.type);
                 const parentIdx = hierarchy.indexOf(definition.parent);
-                const isParentLevelMatch = definition.source === 'hierarchy' && typeIdx !== -1 && parentIdx !== -1 && typeIdx < parentIdx;
+                const isParentLevelMatch = definition.kind === 'hierarchy' && typeIdx !== -1 && parentIdx !== -1 && typeIdx < parentIdx;
                 const activeNodeFieldAppendArg = isParentLevelMatch && semanticParent.node
                     ? { node: semanticParent.node, field: definition.field }
                     : undefined;

package/dist/plugins/miro/cache.js

@@ -30,7 +30,7 @@ export function computeNodeHash(node) {
         status: node.schemaData.status,
         summary: node.schemaData.summary,
         priority: node.schemaData.priority,
-        parents: node.resolvedParents.filter((r) => r.source === 'hierarchy').map((r) => r.id),
+        parents: node.resolvedParents.filter((r) => r.kind === 'hierarchy').map((r) => r.id),
     };
     return createHash('sha256').update(JSON.stringify(relevant)).digest('hex').slice(0, 16);
 }

package/dist/plugins/miro/sync.js

@@ -257,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 { id: parentId, source, hierarchy } of node.resolvedParents) {
-            if (source !== 'hierarchy' || hierarchy !== graph.hierarchy?.name)
+        for (const { id: parentId, kind, hierarchy } of node.resolvedParents) {
+            if (kind !== 'hierarchy' || hierarchy !== graph.hierarchy?.name)
                 continue;
             const parentTitle = graph.nodes.get(parentId)?.title ?? parentId;
             // Both endpoints must have verified cards on the board