structured-context 0.13.1 → 0.15.0

package/README.md

@@ -27,7 +27,7 @@ Content and structure
   Valid                                   16
   Schema validation errors                 0
   Broken links                             1
-  Duplicate keys                           0
+  Duplicate ids                            0
   Rule violations (error)                  0
   Rule violations (warning)                1
   Rule violations (info)                   1
@@ -77,6 +77,8 @@ claude plugin marketplace add mindsocket/structured-context
 claude plugin install structured-context
 ```
 
+Ask Claude to set up a space (or run `/setup-space`) in the folder that holds your notes. The plugin's hooks need Bun.
+
 Skills can also be installed standalone without the plugin:
 
 ```
@@ -89,7 +91,7 @@ See [docs/concepts.md](docs/concepts.md) (`sctx docs concepts`) for terminology:
 
 ## Configuration
 
-The config file maps space names to paths and schemas, with optional plugin settings. It is found from `--config`, then `$SCTX_CONFIG`, then `$XDG_CONFIG_HOME/structured-context/config.json` (default `~/.config/...`), then `./config.json`. Paths resolve relative to the config file, and `includeSpacesFrom` pulls in spaces from other config files.
+The config file maps space names to paths and schemas, with optional plugin settings. It is found from `--config`, then `$SCTX_CONFIG`, then the nearest `.sctx.json` walking up from the working directory, then `$XDG_CONFIG_HOME/structured-context/config.json` (default `~/.config/...`). Paths resolve relative to the config file, and `includeSpacesFrom` pulls in spaces from other config files.
 
 See `config.example.json` and [docs/config.md](docs/config.md) (`sctx docs config`) for the full reference, including `fieldMap`, `typeInference`, templates, filter views and plugin loading.
 
@@ -138,7 +140,7 @@ Validates markdown files against the JSON schema:
 - Extracts YAML frontmatter from each `.md` file
 - Skips files without frontmatter or without a `type` field
 - Reports validation results with counts and per-file errors
-- Runs executable rules (`$metadata.rules`) with **cascade gating**: a schema, hierarchy, or blocking-rule failure on a node suppresses rule evaluation for that node's hierarchy subtree. Gated rules are reported in a Coverage section so you know what wasn't evaluated and why. See [docs/rules.md](docs/rules.md#cascade-gating) for details.
+- Runs executable rules (`$metadata.rules`) with **cascade gating**: a schema, hierarchy or gating rule violation on a node suppresses rule evaluation for that node's hierarchy subtree. Gated rules are reported in a Coverage section so you know what wasn't evaluated and why. See [docs/rules.md](docs/rules.md#cascade-gating) for details.
 - `--depth <n>` limits evaluation to hierarchy nodes within `n` breadth-first levels from the top — useful for staged agentic fix loops (fix the top level, then request the next).
 - `--include-gated` evaluates rules even on gated nodes (still reported as gated) — for surfacing cheap bottom-up checks on request.
 - `--semantic` also evaluates the `semantic` part of rules with the configured model provider (Jev, Anthropic or OpenAI-compatible); `--semantic <provider>` uses that configured model provider instead; `--rule-filter` narrows which rules run. See [docs/semantic-rules.md](docs/semantic-rules.md) (`sctx docs semantic-rules`).

package/dist/api.d.ts

@@ -19,8 +19,9 @@
  */
 export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
 export type { Config, SpaceConfig } from './config';
-export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
-export { PLUGIN_PREFIX } from './constants';
+export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
+export { addSpace } from './config/write';
+export { LOCAL_CONFIG_FILE, PLUGIN_PREFIX } from './constants';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFormat, RenderHook, RenderMultiFileOutput, RenderOptions, RenderResult, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';

package/dist/api.js

@@ -17,8 +17,9 @@
  *   const graph = await assembleSpaceGraph(ctx, { readResult });
  *   const validation = await validateSpace(ctx, { readResult });
  */
-export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
-export { PLUGIN_PREFIX } from './constants';
+export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
+export { addSpace } from './config/write';
+export { LOCAL_CONFIG_FILE, PLUGIN_PREFIX } from './constants';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';

package/dist/commands/dump.js

@@ -11,7 +11,7 @@ export async function buildDump(context, options = {}) {
     if (!options.filter)
         return readResult;
     const graph = await assembleSpaceGraph(context, { ...options, readResult });
-    const nodes = readResult.nodes.filter((node) => graph.nodes.get(node.title) === node);
+    const nodes = readResult.nodes.filter((node) => graph.nodes.get(node.id) === node);
     return { ...readResult, nodes };
 }
 export async function dump(context, options = {}) {

package/dist/commands/spaces.d.ts

@@ -1,3 +1,8 @@
 export declare function listSpaces(options?: {
     json?: boolean;
 }): void;
+export declare function addSpaceCommand(name: string, path: string, options: {
+    schema?: string;
+    global?: boolean;
+    json?: boolean;
+}): void;

package/dist/commands/spaces.js

@@ -1,23 +1,38 @@
 import { basename, resolve } from 'node:path';
-import { configPath, getConfigSourceFiles, loadConfig } from '../config';
+import { loadConfig } from '../config';
+import { checkConfig, hasBlockingProblem } from '../config/health';
+import { addSpace } from '../config/write';
+import { SctxError } from '../errors';
 function renderConfigValue(v) {
     if (typeof v === 'object' && v !== null)
         return JSON.stringify(v);
     return String(v);
 }
 export function listSpaces(options = {}) {
-    const path = resolve(configPath());
-    const config = loadConfig();
+    const health = checkConfig();
     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 }));
+        console.log(JSON.stringify(health));
+        if (hasBlockingProblem(health))
+            process.exitCode = 1;
         return;
     }
-    console.log(`Config: ${path}\n`);
+    const path = resolve(health.config.path);
+    if (health.problems.length > 0) {
+        console.log(`Config: ${path} (${health.config.source}${health.config.exists ? '' : ', not found'})\n`);
+        for (const p of health.problems) {
+            console.log(`${p.severity.toUpperCase()} ${p.code}: ${p.message}`);
+            if (p.fix)
+                console.log(`  fix: ${p.fix}`);
+        }
+        console.log('');
+        if (hasBlockingProblem(health))
+            process.exitCode = 1;
+        if (!health.config.exists)
+            return;
+    }
+    const config = loadConfig();
+    if (health.problems.length === 0)
+        console.log(`Config: ${path} (${health.config.source})\n`);
     for (const space of config.spaces) {
         console.log(`${space.name}`);
         console.log(`  path:    ${space.path}`);
@@ -42,3 +57,24 @@ export function listSpaces(options = {}) {
         console.log('');
     }
 }
+export function addSpaceCommand(name, path, options) {
+    try {
+        const result = addSpace({ name, path, schema: options.schema, global: options.global });
+        if (options.json) {
+            console.log(JSON.stringify(result));
+            return;
+        }
+        console.log(`${result.created ? 'Created' : 'Updated'} ${result.configPath}`);
+        console.log(`Added space "${result.space.name}" (path: ${result.space.path})`);
+    }
+    catch (err) {
+        if (!(err instanceof SctxError))
+            throw err;
+        const hint = err.code === 'E_TARGET_REQUIRED' ? ' Use --config <folder>/.sctx.json or --global.' : '';
+        if (options.json)
+            console.log(JSON.stringify({ error: { code: err.code, message: err.message + hint } }));
+        else
+            console.error(`${err.code}: ${err.message}${hint}`);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/validate.js

@@ -34,10 +34,10 @@ export async function validate(context, options = {}) {
         for (const { file, parent, error } of result.refErrors) {
             addError(file, `broken-link:${parent}`, 'broken-link', `${parent} → ${error}`);
         }
-        for (const { title, files } of result.duplicateErrors) {
+        for (const { id, files } of result.duplicateErrors) {
             for (const file of files) {
                 const others = files.filter((f) => f !== file);
-                addError(file, `duplicate:${title}`, 'duplicate', `Duplicate title "${title}" also exists in: ${others.join(', ')}`);
+                addError(file, `duplicate:${id}`, 'duplicate', `Duplicate id "${id}" also exists in: ${others.join(', ')}`);
             }
         }
         for (const v of result.ruleViolations) {
@@ -97,7 +97,7 @@ export async function validate(context, options = {}) {
     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 keys', result.duplicateErrors.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));
@@ -114,7 +114,7 @@ export async function validate(context, options = {}) {
     if (result.orphans.length > 0) {
         console.log(`\nOrphans (hierarchy nodes - no parent):`);
         for (const node of result.orphans)
-            console.log(`   ${node.label}`);
+            console.log(`   ${node.id}`);
     }
     if (result.unresolvedContentLinks.length > 0) {
         console.log(`\nUnresolved content links (may be outside-space or broken):`);
@@ -157,9 +157,9 @@ export async function validate(context, options = {}) {
         });
     }
     if (result.duplicateErrors.length > 0) {
-        console.log(`\nDuplicate keys (same title in multiple files):`);
-        result.duplicateErrors.forEach(({ title, files }) => {
-            console.log(`   "${title}":`);
+        console.log(`\nDuplicate ids (same id on multiple nodes):`);
+        result.duplicateErrors.forEach(({ id, files }) => {
+            console.log(`   "${id}":`);
             for (const f of files) {
                 console.log(`      ${f}`);
             }
@@ -194,7 +194,7 @@ export async function validate(context, options = {}) {
         console.log(`\nCoverage — rule checks gated by cascade (use --include-gated to evaluate anyway):`);
         for (const gate of result.coverageGates) {
             const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
-            console.log(`   ${gate.file} (${gate.nodeTitle}) — ${cause} gated ${gate.gatedFiles.length} node(s):`);
+            console.log(`   ${gate.file} (${gate.nodeId}) — ${cause} gated ${gate.gatedFiles.length} node(s):`);
             for (const file of gate.gatedFiles)
                 console.log(`      ${file}`);
         }

package/dist/config/health.d.ts

@@ -0,0 +1,31 @@
+import { type SctxErrorCode } from '../errors';
+import { type ResolvedConfigPath } from '.';
+export type ConfigProblem = {
+    code: SctxErrorCode;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    fix: string;
+    space?: string;
+};
+export type ConfigHealth = {
+    config: ResolvedConfigPath & {
+        exists: boolean;
+    };
+    configFiles: string[];
+    spaces: {
+        name: string;
+        path: string;
+        schema?: string;
+    }[];
+    problems: ConfigProblem[];
+};
+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.
+ */
+export declare function checkConfig(options?: {
+    startDir?: string;
+}): ConfigHealth;
+/** True when the health check found something that stops validation from running. */
+export declare function hasBlockingProblem(health: ConfigHealth): boolean;

package/dist/config/health.js

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'node:fs';
+import JSON5 from 'json5';
+import { LOCAL_CONFIG_FILE } from '../constants';
+import { SctxError } from '../errors';
+import { getConfigSourceFiles, loadConfig, resolveConfigPath, resolveSchema } 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.',
+    E_INCLUDE_NOT_FOUND: 'Correct or remove the missing path in `includeSpacesFrom`.',
+    E_NO_SPACES: 'Add a space with `sctx spaces add`.',
+    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.',
+};
+export function fixFor(code) {
+    return FIXES[code] ?? '';
+}
+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.
+ */
+export function checkConfig(options = {}) {
+    const resolved = resolveConfigPath(options.startDir);
+    const exists = existsSync(resolved.path);
+    const health = { config: { ...resolved, exists }, configFiles: [], spaces: [], problems: [] };
+    if (!exists) {
+        const detail = resolved.source === 'none'
+            ? `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;
+    }
+    let config;
+    try {
+        config = loadConfig({ startDir: options.startDir });
+    }
+    catch (err) {
+        const code = err instanceof SctxError ? err.code : 'E_CONFIG_INVALID';
+        health.problems.push(problem(code, 'error', err.message));
+        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;
+}
+/** True when the health check found something that stops validation from running. */
+export function hasBlockingProblem(health) {
+    return health.problems.some((p) => p.severity === 'error');
+}

package/dist/{config.d.ts → config/index.d.ts}

@@ -1,4 +1,4 @@
-import { type JudgeConfig, type ModelProviderConfig } from './judge/types';
+import { type JudgeConfig, type ModelProviderConfig } from '../judge/types';
 export type SpaceConfig = {
     name: string;
     path: string;
@@ -31,8 +31,23 @@ 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>;
-export declare function configPath(): string;
-export declare function loadConfig(): Config;
+/** How the config file was found. `none` means nothing exists and `path` is where the global file would go. */
+export type ConfigSource = 'override' | 'env' | 'local' | 'global' | 'none';
+export type ResolvedConfigPath = {
+    path: string;
+    source: ConfigSource;
+};
+/** Path of the global config file, whether or not it exists. */
+export declare function globalConfigPath(): string;
+/**
+ * Find the config file. Precedence: explicit override (`--config`), `$SCTX_CONFIG`, the nearest
+ * `.sctx.json` walking up from `startDir` (default: the working directory), then the global file.
+ */
+export declare function resolveConfigPath(startDir?: string): ResolvedConfigPath;
+export declare function configPath(startDir?: string): string;
+export declare function loadConfig(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.js → config/index.js}

@@ -1,12 +1,13 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020';
 import JSON5 from 'json5';
-import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants';
-import { MODEL_PROVIDER_APIS } from './judge/types';
-import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from './plugins/util';
-import { bundledSchemasDir } from './schema/schema';
+import { ENV_CONFIG_VAR, LOCAL_CONFIG_FILE, XDG_CONFIG_DIR } from '../constants';
+import { SctxError } from '../errors';
+import { MODEL_PROVIDER_APIS } from '../judge/types';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { bundledSchemasDir } from '../schema/schema';
 const MODEL_PROVIDER_SCHEMA = {
     type: 'object',
     properties: {
@@ -75,23 +76,40 @@ export function getConfigSourceFiles() {
     }
     return new Set(_spaceSourceFiles.values());
 }
-export function configPath() {
-    if (_configPathOverride) {
-        return _configPathOverride;
-    }
-    if (process.env[ENV_CONFIG_VAR]) {
-        return process.env[ENV_CONFIG_VAR];
-    }
+/** Path of the global config file, whether or not it exists. */
+export function globalConfigPath() {
     const xdgBase = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
-    const xdgPath = join(xdgBase, XDG_CONFIG_DIR, 'config.json');
-    if (existsSync(xdgPath)) {
-        return xdgPath;
-    }
-    const cwdPath = join(process.cwd(), 'config.json');
-    if (existsSync(cwdPath)) {
-        return cwdPath;
+    return join(xdgBase, XDG_CONFIG_DIR, 'config.json');
+}
+function findLocalConfig(startDir) {
+    let dir = resolve(startDir);
+    for (;;) {
+        const candidate = join(dir, LOCAL_CONFIG_FILE);
+        if (existsSync(candidate) && statSync(candidate).isFile())
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
     }
-    return xdgPath;
+}
+/**
+ * Find the config file. Precedence: explicit override (`--config`), `$SCTX_CONFIG`, the nearest
+ * `.sctx.json` walking up from `startDir` (default: the working directory), then the global file.
+ */
+export function resolveConfigPath(startDir = process.cwd()) {
+    if (_configPathOverride)
+        return { path: _configPathOverride, source: 'override' };
+    if (process.env[ENV_CONFIG_VAR])
+        return { path: process.env[ENV_CONFIG_VAR], source: 'env' };
+    const local = findLocalConfig(startDir);
+    if (local)
+        return { path: local, source: 'local' };
+    const global = globalConfigPath();
+    return { path: global, source: existsSync(global) ? 'global' : 'none' };
+}
+export function configPath(startDir) {
+    return resolveConfigPath(startDir).path;
 }
 function normalizePlugins(plugins) {
     if (!plugins)
@@ -128,48 +146,69 @@ function resolveRelativePaths(config, configDir) {
 }
 function _loadConfig(path) {
     if (!existsSync(path)) {
-        throw new Error(`Config file not found: ${path}`);
+        throw new SctxError('E_CONFIG_NOT_FOUND', `Config file not found: ${path}`);
+    }
+    let config;
+    try {
+        config = JSON5.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        throw new SctxError('E_CONFIG_INVALID', `Invalid config in ${path}: ${err.message}`);
     }
-    const config = JSON5.parse(readFileSync(path, 'utf-8'));
     const ajv = new Ajv2020();
     const validate = ajv.compile(CONFIG_SCHEMA);
     if (!validate(config)) {
-        throw new Error(`Invalid config in ${path}: ${JSON.stringify(validate.errors)}`);
+        throw new SctxError('E_CONFIG_INVALID', `Invalid config in ${path}: ${JSON.stringify(validate.errors)}`);
     }
-    if (!config.spaces)
-        config.spaces = [];
-    return config;
+    const parsed = config;
+    if (!parsed.spaces)
+        parsed.spaces = [];
+    return parsed;
 }
-export function loadConfig() {
-    const path = configPath();
+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);
     if (!existsSync(path)) {
-        console.warn(`Config file not found: ${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})`);
         return { spaces: [] };
     }
     const config = _loadConfig(path);
     _spaceSourceFiles.clear();
     // Track which spaces come from the main config file
     const mainSourceDir = dirname(resolve(path));
+    const ownNames = new Set(config.spaces.map((s) => s.name));
     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
+    // Merge includeSpacesFrom configs. A space defined in the including file wins over an included one
+    // of the same name; between includes, later entries win over earlier ones.
     if (config.includeSpacesFrom) {
         for (const includePath of config.includeSpacesFrom) {
             // Resolve relative to the main config file
-            const resolvedIncludePath = isAbsolute(includePath) ? includePath : resolve(dirname(path), includePath);
-            const includedConfig = resolveRelativePaths(_loadConfig(resolvedIncludePath), dirname(resolvedIncludePath));
-            if (includedConfig.spaces.some((s) => config.spaces.some((existing) => existing.name === s.name))) {
-                throw new Error(`Included config contains spaces with duplicate names: ${resolvedIncludePath}`);
+            const expanded = expandHome(includePath);
+            const resolvedIncludePath = isAbsolute(expanded) ? expanded : resolve(dirname(path), expanded);
+            if (!existsSync(resolvedIncludePath)) {
+                throw new SctxError('E_INCLUDE_NOT_FOUND', `Config ${path} includes ${resolvedIncludePath}, which does not exist`);
             }
-            // Track which spaces come from this included config file
+            const includedConfig = resolveRelativePaths(_loadConfig(resolvedIncludePath), dirname(resolvedIncludePath));
             const includeSourceDir = dirname(resolvedIncludePath);
             for (const space of includedConfig.spaces) {
-                _spaceSourceFiles.set(space.name, resolvedIncludePath);
+                if (ownNames.has(space.name))
+                    continue;
                 space.sourceDir = includeSourceDir;
+                _spaceSourceFiles.set(space.name, resolvedIncludePath);
+                const existing = config.spaces.findIndex((s) => s.name === space.name);
+                if (existing >= 0)
+                    config.spaces[existing] = space;
+                else
+                    config.spaces.push(space);
             }
-            config.spaces.push(...includedConfig.spaces);
         }
     }
     return resolveRelativePaths(config, dirname(resolve(path)));

package/dist/config/write.d.ts

@@ -0,0 +1,27 @@
+import { type SpaceConfig } from '.';
+type AddSpaceOptions = Pick<SpaceConfig, 'name' | 'path' | 'schema'> & {
+    /** Write to the global config file. */
+    global?: boolean;
+    /** Write to this config file (created if missing) instead of the discovered one. */
+    configFile?: string;
+    /** Where discovery starts when no explicit target is given. Defaults to the working directory. */
+    startDir?: string;
+};
+type AddSpaceResult = {
+    configPath: string;
+    created: boolean;
+    space: Pick<SpaceConfig, 'name' | 'path' | 'schema'>;
+};
+/**
+ * Decide which file to write. A config named explicitly or found by walking up from the working directory
+ * is used as is. If discovery would land on the global file or on nothing, the caller must say where to
+ * write, so a vault's space never ends up in the global file by accident.
+ */
+export declare function resolveWriteTarget(options: {
+    global?: boolean;
+    configFile?: string;
+    startDir?: string;
+}): string;
+/** Add a space to the chosen config file, creating the file when it does not exist. */
+export declare function addSpace(options: AddSpaceOptions): AddSpaceResult;
+export {};

package/dist/config/write.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { LOCAL_CONFIG_FILE } from '../constants';
+import { SctxError } from '../errors';
+import { globalConfigPath, resolveConfigPath, resolveSchemaPath } from '.';
+/**
+ * Decide which file to write. A config named explicitly or found by walking up from the working directory
+ * is used as is. If discovery would land on the global file or on nothing, the caller must say where to
+ * write, so a vault's space never ends up in the global file by accident.
+ */
+export function resolveWriteTarget(options) {
+    if (options.configFile)
+        return options.configFile;
+    const resolved = resolveConfigPath(options.startDir);
+    if (options.global) {
+        if (resolved.source === 'override' || resolved.source === 'env') {
+            throw new SctxError('E_TARGET_REQUIRED', 'The global config cannot be combined with an explicitly named config');
+        }
+        return globalConfigPath();
+    }
+    if (resolved.source === 'override' || resolved.source === 'env' || resolved.source === 'local') {
+        return resolved.path;
+    }
+    const found = resolved.source === 'global' ? `only the global config (${resolved.path}) exists` : 'no config exists';
+    throw new SctxError('E_TARGET_REQUIRED', `No ${LOCAL_CONFIG_FILE} found from ${resolve(options.startDir ?? process.cwd())} upward; ${found}. ` +
+        `Specify the config file location or global option.`);
+}
+function realOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** The path as written in the config: relative to the config's folder when inside it, else absolute. */
+function storedPath(configFile, absolutePath) {
+    // Compare real paths so a symlinked folder (such as macOS's /var -> /private/var) does not look like it escapes
+    const rel = relative(realOrSelf(dirname(resolve(configFile))), realOrSelf(absolutePath));
+    if (rel === '')
+        return '.';
+    return rel.startsWith('..') || isAbsolute(rel) ? absolutePath : rel;
+}
+/** Add a space to the chosen config file, creating the file when it does not exist. */
+export function addSpace(options) {
+    if (!/^[a-z0-9_-]+$/.test(options.name)) {
+        throw new SctxError('E_CONFIG_INVALID', `Space name "${options.name}" must use lowercase letters, digits, "-" and "_"`);
+    }
+    const target = resolve(resolveWriteTarget(options));
+    const spacePath = resolve(options.startDir ?? process.cwd(), options.path);
+    if (!existsSync(spacePath)) {
+        throw new SctxError('E_SPACE_PATH_MISSING', `Space path does not exist: ${spacePath}`);
+    }
+    const created = !existsSync(target);
+    let config = { spaces: [] };
+    if (!created) {
+        const raw = readFileSync(target, 'utf-8');
+        try {
+            config = JSON.parse(raw);
+        }
+        catch {
+            const entry = { name: options.name, path: storedPath(target, spacePath), schema: options.schema };
+            throw new SctxError('E_CONFIG_NEEDS_MANUAL_EDIT', `${target} is not strict JSON (comments, trailing commas or a syntax error), so it was not rewritten. ` +
+                `Add this entry to "spaces" by hand: ${JSON.stringify(entry)}`);
+        }
+    }
+    if (!config.schema && !options.schema) {
+        throw new SctxError('E_SCHEMA_MISSING', 'Give --schema <name or path>: neither the space nor the config file names a schema');
+    }
+    if (options.schema && !/^https?:\/\//i.test(options.schema)) {
+        if (!existsSync(resolveSchemaPath(options.schema, dirname(target)))) {
+            const hint = options.schema.startsWith('sctx://')
+                ? 'Name the schema by file, such as strategy_general.json, not by sctx:// URI.'
+                : '`sctx schemas list` shows the bundled schemas; a file name needs its extension.';
+            throw new SctxError('E_SCHEMA_NOT_FOUND', `Schema not found: ${options.schema}. ${hint}`);
+        }
+    }
+    config.spaces = config.spaces ?? [];
+    if (config.spaces.some((s) => s.name === options.name)) {
+        throw new SctxError('E_SPACE_EXISTS', `${target} already defines a space named "${options.name}"`);
+    }
+    const space = {
+        name: options.name,
+        path: storedPath(target, spacePath),
+        ...(options.schema ? { schema: options.schema } : {}),
+    };
+    config.spaces.push(space);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, `${JSON.stringify(config, null, 2)}\n`);
+    return { configPath: target, created, space };
+}

package/dist/constants.d.ts

@@ -4,3 +4,5 @@ export declare const CLI_NAME = "sctx";
 export declare const PLUGIN_PREFIX = "sctx-";
 export declare const ENV_CONFIG_VAR = "SCTX_CONFIG";
 export declare const SCHEMA_URI_SCHEME = "sctx";
+/** Name of the config file discovered by walking up from the working directory. */
+export declare const LOCAL_CONFIG_FILE = ".sctx.json";