structured-context 0.14.0 → 0.15.0

package/README.md

@@ -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.
 

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/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/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";

package/dist/constants.js

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

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stable codes for configuration and environment problems. Hooks and agent skills map a code to a
+ * fix, so the message wording can change without breaking them.
+ */
+export type SctxErrorCode = 'E_CONFIG_NOT_FOUND' | 'E_CONFIG_INVALID' | 'E_INCLUDE_NOT_FOUND' | 'E_NO_SPACES' | 'E_SPACE_PATH_MISSING' | 'E_SCHEMA_MISSING' | 'E_SCHEMA_NOT_FOUND' | 'E_SCHEMA_INVALID' | 'E_SPACE_EXISTS' | 'E_TARGET_REQUIRED' | 'E_CONFIG_NEEDS_MANUAL_EDIT';
+export declare class SctxError extends Error {
+    readonly code: SctxErrorCode;
+    constructor(code: SctxErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class SctxError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SctxError';
+    }
+}

package/dist/index.js

@@ -10,7 +10,7 @@ import { listPlugins } from './commands/plugins';
 import { render, renderList } from './commands/render';
 import { listSchemas, showSchema } from './commands/schemas';
 import { show } from './commands/show';
-import { listSpaces } from './commands/spaces';
+import { addSpaceCommand, listSpaces } from './commands/spaces';
 import { templateSync } from './commands/template-sync';
 import { validate, watchValidate } from './commands/validate';
 import { validateFileCommand } from './commands/validate-file';
@@ -54,7 +54,7 @@ program
     .name(CLI_NAME)
     .description('Structured context validation and diagram generation tool')
     .version(packageJson.version)
-    .option('--config <path>', 'Path to config file (overrides default config.json locations)');
+    .option('--config <path>', 'Path to config file (overrides config discovery)');
 program.hook('preAction', () => {
     setConfigPath(program.opts().config);
 });
@@ -150,6 +150,17 @@ spacesCmd
     .description('List all configured spaces and their paths')
     .option('--json', 'Output as JSON: config files, and each space with its path and schema')
     .action((options) => listSpaces(options));
+spacesCmd
+    .command('add')
+    .description('Add a space to a config file, creating the file if needed')
+    .argument('<name>', 'Space name (lowercase letters, digits, - and _)')
+    .argument('<path>', 'Path to the space (a folder or a file); must exist')
+    .option('--schema <schema>', 'Schema name or path (required unless the config names a top-level schema)')
+    .option('--global', 'Write to the global config file')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', '\nWrites to the config found by walking up from the working directory, or the one named with --config.\n' +
+    'If only the global config (or none) exists, name the target: --config <folder>/.sctx.json or --global.')
+    .action((name, path, options) => addSpaceCommand(name, path, options));
 program.addCommand(spacesCmd);
 const providersCmd = new Command('providers').description('List model providers (bundled and configured) with their effective config');
 providersCmd

package/dist/plugins/markdown/read-space.js

@@ -97,7 +97,8 @@ export async function readSpaceDirectory(context, options) {
             continue;
         }
         const pageType = data.type;
-        const explicitTitle = data.title;
+        // A non-string title (e.g. `title: 42`) isn't a usable name or link target; schema validation reports it.
+        const explicitTitle = typeof data.title === 'string' ? data.title : undefined;
         const title = explicitTitle ?? defaultPageTitle(file, mdCfg.folderIndex);
         const pathTargets = pathLinkTargets(file);
         const fmMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);

package/docs/concepts.md

@@ -10,7 +10,7 @@ This document is the canonical reference for concepts and terminology used in th
 
 ## Space
 
-A **space** is a named collection of nodes organised according to a schema. Spaces are the primary unit of organisation — a space has a backing format (a `space directory` or a `space on a page` file) and may be registered in `config.json` with a name for convenient access.
+A **space** is a named collection of nodes organised according to a schema. Spaces are the primary unit of organisation — a space has a backing format (a `space directory` or a `space on a page` file) and may be registered in a config file (`.sctx.json` or the global `config.json`) with a name for convenient access.
 
 ```mermaid
 flowchart TD

package/docs/config.md

@@ -6,13 +6,30 @@ title: "Configuration Reference"
 
 ## Config file location
 
-structured-context looks for its config file in this order:
+structured-context uses the first config file it finds, in this order:
 
-1. `$SCTX_CONFIG` — explicit path override
-2. `~/.config/structured-context/config.json` (or `$XDG_CONFIG_HOME/structured-context/config.json`)
-3. `./config.json` in the current working directory
+1. `--config <path>`
+2. `$SCTX_CONFIG`
+3. The nearest `.sctx.json`, looking in the working directory and then each parent folder
+4. `~/.config/structured-context/config.json` (or `$XDG_CONFIG_HOME/structured-context/config.json`)
 
-See `config.example.json` for the full structure. Paths in config files are resolved relative to the config file.
+It is recommended to keep a `.sctx.json` at the base of the notes it describes (for example the root of an Obsidian vault), or to use the global config. The CLI and agent sessions look in parent folders only, so run commands from inside the folder that holds the config. To use the spaces from another config file too, list it in `includeSpacesFrom`.
+
+Paths in a config file are relative to the folder that holds that file. In a `.sctx.json` at a vault root, `"path": "."` is the whole vault and `"path": "notes"` is one folder.
+
+`sctx spaces` shows which config file is used and reports problems with it. `sctx spaces --json` returns the same information for tools and hooks.
+
+### Adding a space
+
+```bash
+sctx spaces add wiki notes --schema knowledge_wiki.json
+```
+
+This adds the space to the config file found from the working directory, or to the one named with `--config`. When no `.sctx.json` is found, or only the global config exists, pass `--config <folder>/.sctx.json` (creates the file) or `--global`. If the config file has comments or trailing commas, the command prints the entry to add by hand.
+
+Custom schemas can sit anywhere. Reference them by relative path, for example `./.sctx/schemas/my_wiki.json`; `.sctx/schemas/` is the suggested folder.
+
+See `config.example.json` for the full structure.
 
 ## Spaces
 
@@ -36,7 +53,7 @@ A space is a named directory or single file registered in the config. Example:
 - A plugin schema prefixed with the plugin name (e.g. `sctx-wardley-mapping/wardley_map.json` or `wardley-mapping/wardley_map.json`). Specifying a plugin-prefixed schema automatically loads that plugin for the space.
 - A simple filename (e.g. `wardley_map.json`) provided by a plugin explicitly declared under `plugins`.
 
-**`includeSpacesFrom`** — import space definitions from other config files. Useful for aggregating spaces from multiple projects into a central config. Duplicate space names are not allowed.
+**`includeSpacesFrom`** — import space definitions from other config files, for example a shared team config or your global config (`"~/.config/structured-context/config.json"`; a leading `~` is expanded). A space defined in the including file overrides an included space of the same name; between includes, later entries win. Only `spaces` are taken from an included file.
 
 A config must define at least one of `spaces` or `includeSpacesFrom`. When using `includeSpacesFrom` alone, `spaces` can be omitted entirely.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
@@ -54,11 +54,11 @@
     "postversion": "git push --follow-tags"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.191",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.310",
     "@biomejs/biome": "^2.5.15",
-    "@types/bun": "latest",
+    "@types/bun": "^1.4.4",
     "json-schema-to-ts": "^3.1.1",
-    "lefthook": "^2.1.9"
+    "lefthook": "^2.2.2"
   },
   "peerDependencies": {
     "typescript": "^5"