structured-context 0.15.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).
@@ -188,6 +188,14 @@ Generates a Mermaid `graph TD` diagram from validated space nodes:
 - Handles orphan nodes (no parent) as a separate cluster
 - Outputs to file or stdout
 
+### List schemas
+
+```bash
+sctx schemas list [--json]
+```
+
+Lists the bundled schemas, schemas contributed by plugins, and any other schema file your config uses, with the spaces that use each. `--json` gives the data that `listSchemas` returns; see [docs/api.md](docs/api.md).
+
 ### Show schema ERD
 
 ```bash
@@ -229,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';
@@ -27,10 +28,12 @@ export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFor
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';
 export { buildTargetIndex, formatWikilink, type ParsedWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
+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

@@ -1,3 +1,4 @@
+// Public entry point: do not add exports without the maintainer's agreement (AGENTS.md, "Public API surface").
 /**
  * Public API for structured-context.
  *
@@ -17,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';
@@ -24,7 +26,9 @@ export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';
 export { buildTargetIndex, formatWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
+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.d.ts

@@ -1,4 +1,6 @@
-export declare function listSchemas(): Promise<void>;
+export declare function printSchemas(options?: {
+    json?: boolean;
+}): Promise<void>;
 export declare function showSchema(file: string | undefined, options: {
     space?: string;
     raw: boolean;

package/dist/commands/schemas.js

@@ -1,16 +1,14 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { loadConfig } from '../config';
+import { join, resolve } from 'node:path';
+import { loadConfig, loadConfigOrEmpty } from '../config';
 import { discoverPlugins } from '../plugins/loader';
 import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { listSchemas } from '../schema/list-schemas';
 import { ruleSemantic } from '../schema/rule-severity';
 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;
-}
 function extractRefs(obj, refs) {
     if (typeof obj !== 'object' || obj === null)
         return;
@@ -207,60 +205,34 @@ function ruleAnnotations(rule) {
         notes.push(`when: ${rule.when}`);
     return notes.length > 0 ? ` [${notes.join('] [')}]` : '';
 }
-export async function listSchemas() {
-    const config = loadConfig();
-    // List all schemas known to config
-    if (existsSync(bundledSchemasDir)) {
-        const files = readdirSync(bundledSchemasDir)
-            .filter((f) => f.endsWith('.json'))
-            .sort();
-        if (files.length > 0) {
-            console.log('Bundled schemas:');
-            for (const file of files) {
-                const schema = readRawSchema(join(bundledSchemasDir, file));
-                const id = typeof schema.$id === 'string' ? schema.$id : '(no $id)';
-                console.log(`  ${file}${file.startsWith('_') ? '  [partial]' : ''}  (${id})`);
-            }
-        }
+export async function printSchemas(options = {}) {
+    const listings = await listSchemas();
+    if (options.json) {
+        console.log(JSON.stringify(listings, null, 2));
+        return;
     }
-    // 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 sources = [...new Set(listings.map((l) => l.source))].sort((a, b) => Number(b === 'core') - Number(a === 'core') || Number(a === 'configured') - Number(b === 'configured'));
+    for (const source of sources) {
+        const group = listings.filter((l) => l.source === source);
+        if (source === 'core')
+            console.log('Bundled schemas:');
+        else if (source === 'configured')
+            console.log('\nConfigured schemas:');
+        else
+            console.log(`\nPlugin schemas (${source}):`);
+        for (const l of group) {
+            if (source === 'configured')
+                console.log(`  ${l.usedBy.join(', ')}: ${l.path ?? l.schema}${l.error ? `  [${l.error}]` : ''}`);
+            else {
+                const notes = [l.partial && '[partial]', l.id && `(${l.id})`, l.error && `[${l.error}]`].filter(Boolean);
+                console.log(`  ${l.schema}${notes.length > 0 ? `  ${notes.join('  ')}` : ''}`);
             }
         }
     }
-    const configured = [];
-    const seen = new Set();
-    if (config.schema && !isBundledPath(config.schema)) {
-        configured.push({ source: 'global', path: config.schema });
-        seen.add(config.schema);
-    }
-    for (const space of config.spaces) {
-        if (space.schema && !seen.has(space.schema) && !isBundledPath(space.schema)) {
-            configured.push({ source: space.name, path: space.schema });
-            seen.add(space.schema);
-        }
-    }
-    if (configured.length > 0) {
-        console.log('\nConfigured schemas:');
-        for (const { source, path } of configured) {
-            console.log(`  ${source}: ${path}`);
-        }
-    }
 }
 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);
                 }
             }