structured-context 0.13.1 → 0.15.0

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/filter/augment-nodes.d.ts

@@ -1,4 +1,4 @@
-import type { SpaceNode } from '../types';
+import type { NodeId, SpaceNode } from '../types';
 /** Edge metadata merged into each ancestor/descendant entry. */
 export type EdgeMetadata = {
     _field: string;
@@ -11,6 +11,7 @@ export type EdgeMetadata = {
 export type AugmentedFlatNode = Record<string, unknown> & {
     resolvedType: string;
     resolvedParentTitles: string[];
+    resolvedParentIds: NodeId[];
     ancestors: Array<Record<string, unknown> & EdgeMetadata>;
     descendants: Array<Record<string, unknown> & EdgeMetadata>;
 };
@@ -18,8 +19,8 @@ export type AugmentedFlatNode = Record<string, unknown> & {
  * Build the augmented flat representation of a node, including pre-computed
  * ancestors[] and descendants[] arrays with edge metadata.
  *
- * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by title.
- * - descendants: BFS via childrenIndex, nearest first, deduplicated by title.
+ * - 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).
  */
-export declare function augmentNode(node: SpaceNode, nodeIndex: ReadonlyMap<string, SpaceNode>, childrenIndex: ReadonlyMap<string, readonly SpaceNode[]>): AugmentedFlatNode;
+export declare function augmentNode(node: SpaceNode, nodeIndex: ReadonlyMap<NodeId, SpaceNode>, childrenIndex: ReadonlyMap<NodeId, readonly SpaceNode[]>): AugmentedFlatNode;

package/dist/filter/augment-nodes.js

@@ -11,7 +11,7 @@ function edgeMetadata(ref) {
 function flattenData(node) {
     return {
         ...node.schemaData,
-        label: node.label,
+        id: node.id,
         title: node.title,
         resolvedType: node.resolvedType,
     };
@@ -20,8 +20,8 @@ function flattenData(node) {
  * Build the augmented flat representation of a node, including pre-computed
  * ancestors[] and descendants[] arrays with edge metadata.
  *
- * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by title.
- * - descendants: BFS via childrenIndex, nearest first, deduplicated by title.
+ * - 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).
  */
 export function augmentNode(node, nodeIndex, childrenIndex) {
@@ -30,7 +30,8 @@ export function augmentNode(node, nodeIndex, childrenIndex) {
     return {
         ...flattenData(node),
         resolvedType: node.resolvedType,
-        resolvedParentTitles: node.resolvedParents.map((r) => r.title),
+        resolvedParentTitles: node.resolvedParents.map((r) => nodeIndex.get(r.id)?.title ?? r.id),
+        resolvedParentIds: node.resolvedParents.map((r) => r.id),
         ancestors,
         descendants,
     };
@@ -41,24 +42,24 @@ function buildAncestors(node, nodeIndex) {
     // BFS queue holds: { parentRef that led to this node, the node itself }
     const queue = [];
     for (const ref of node.resolvedParents) {
-        const parentNode = nodeIndex.get(ref.title);
+        const parentNode = nodeIndex.get(ref.id);
         if (parentNode)
             queue.push({ ref, node: parentNode });
     }
     while (queue.length > 0) {
         const item = queue.shift();
-        const title = item.node.title;
-        if (visited.has(title))
+        const id = item.node.id;
+        if (visited.has(id))
             continue;
-        visited.add(title);
+        visited.add(id);
         result.push({
             ...flattenData(item.node),
             ...edgeMetadata(item.ref),
         });
         // Continue BFS upward
         for (const ref of item.node.resolvedParents) {
-            const parentNode = nodeIndex.get(ref.title);
-            if (parentNode && !visited.has(ref.title)) {
+            const parentNode = nodeIndex.get(ref.id);
+            if (parentNode && !visited.has(ref.id)) {
                 queue.push({ ref, node: parentNode });
             }
         }
@@ -66,31 +67,31 @@ function buildAncestors(node, nodeIndex) {
     return result;
 }
 function buildDescendants(node, childrenIndex) {
-    const nodeTitle = node.title;
+    const nodeId = node.id;
     const visited = new Set();
     const result = [];
     // BFS queue holds: child node + the resolvedParents entry on that child that points to its parent
     const queue = [];
-    const directChildren = childrenIndex.get(nodeTitle) ?? [];
+    const directChildren = childrenIndex.get(nodeId) ?? [];
     for (const child of directChildren) {
-        const ref = child.resolvedParents.find((r) => r.title === nodeTitle);
+        const ref = child.resolvedParents.find((r) => r.id === nodeId);
         if (ref)
             queue.push({ childNode: child, ref });
     }
     while (queue.length > 0) {
         const item = queue.shift();
-        const title = item.childNode.title;
-        if (visited.has(title))
+        const id = item.childNode.id;
+        if (visited.has(id))
             continue;
-        visited.add(title);
+        visited.add(id);
         result.push({
             ...flattenData(item.childNode),
             ...edgeMetadata(item.ref),
         });
-        const grandchildren = childrenIndex.get(title) ?? [];
+        const grandchildren = childrenIndex.get(id) ?? [];
         for (const grandchild of grandchildren) {
-            if (!visited.has(grandchild.title)) {
-                const ref = grandchild.resolvedParents.find((r) => r.title === title);
+            if (!visited.has(grandchild.id)) {
+                const ref = grandchild.resolvedParents.find((r) => r.id === id);
                 if (ref)
                     queue.push({ childNode: grandchild, ref });
             }

package/dist/filter/expand-include.d.ts

@@ -1,4 +1,4 @@
-import type { SpaceNode } from '../types';
+import type { NodeId, SpaceNode } from '../types';
 import type { AugmentedFlatNode } from './augment-nodes';
 export type AncestorsDirective = {
     kind: 'ancestors';
@@ -59,4 +59,4 @@ export declare function parseIncludeSpec(spec: string): IncludeDirective[];
  * @param childrenIndex - Title → direct children (all edges)
  * @param augmented - Title → AugmentedFlatNode with pre-computed ancestors/descendants
  */
-export declare function expandInclude(matchedNodes: SpaceNode[], directives: IncludeDirective[], nodeIndex: ReadonlyMap<string, SpaceNode>, childrenIndex: ReadonlyMap<string, readonly SpaceNode[]>, augmented: Map<string, AugmentedFlatNode>): SpaceNode[];
+export declare function expandInclude(matchedNodes: SpaceNode[], directives: IncludeDirective[], nodeIndex: ReadonlyMap<NodeId, SpaceNode>, childrenIndex: ReadonlyMap<NodeId, readonly SpaceNode[]>, augmented: Map<NodeId, AugmentedFlatNode>): SpaceNode[];

package/dist/filter/expand-include.js

@@ -85,34 +85,33 @@ function parseDirective(item) {
 export function expandInclude(matchedNodes, directives, nodeIndex, childrenIndex, augmented) {
     if (directives.length === 0)
         return matchedNodes;
-    const seen = new Set(matchedNodes.map((n) => n.title));
+    const seen = new Set(matchedNodes.map((n) => n.id));
     const result = [...matchedNodes];
-    function addByTitle(title) {
-        if (seen.has(title))
+    function addById(id) {
+        if (seen.has(id))
             return;
-        const node = nodeIndex.get(title);
+        const node = nodeIndex.get(id);
         if (node) {
-            seen.add(title);
+            seen.add(id);
             result.push(node);
         }
     }
     for (const node of matchedNodes) {
-        const title = node.title;
-        const aug = augmented.get(title);
+        const aug = augmented.get(node.id);
         if (!aug)
             continue;
         for (const directive of directives) {
-            applyDirective(node, aug, directive, childrenIndex, addByTitle);
+            applyDirective(node, aug, directive, childrenIndex, addById);
         }
     }
     return result;
 }
-function applyDirective(node, aug, directive, childrenIndex, addByTitle) {
+function applyDirective(node, aug, directive, childrenIndex, addById) {
     switch (directive.kind) {
         case 'ancestors': {
             for (const a of aug.ancestors) {
                 if (!directive.typeFilter || a.resolvedType === directive.typeFilter) {
-                    addByTitle(a.title);
+                    addById(a.id);
                 }
             }
             break;
@@ -120,7 +119,7 @@ function applyDirective(node, aug, directive, childrenIndex, addByTitle) {
         case 'descendants': {
             for (const d of aug.descendants) {
                 if (!directive.typeFilter || d.resolvedType === directive.typeFilter) {
-                    addByTitle(d.title);
+                    addById(d.id);
                 }
             }
             break;
@@ -128,11 +127,10 @@ function applyDirective(node, aug, directive, childrenIndex, addByTitle) {
         case 'siblings': {
             // Nodes that share at least one parent with the matched node (any edge type)
             for (const parentRef of node.resolvedParents) {
-                const siblings = childrenIndex.get(parentRef.title) ?? [];
+                const siblings = childrenIndex.get(parentRef.id) ?? [];
                 for (const sibling of siblings) {
-                    const siblingTitle = sibling.title;
-                    if (siblingTitle !== node.title) {
-                        addByTitle(siblingTitle);
+                    if (sibling.id !== node.id) {
+                        addById(sibling.id);
                     }
                 }
             }
@@ -142,13 +140,13 @@ function applyDirective(node, aug, directive, childrenIndex, addByTitle) {
             // Relationship-sourced ancestors (matched node is the child side)
             for (const a of aug.ancestors) {
                 if (a._source === 'relationship' && matchesRelSpec(node, a, directive, true)) {
-                    addByTitle(a.title);
+                    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)) {
-                    addByTitle(d.title);
+                    addById(d.id);
                 }
             }
             break;

package/dist/filter/filter-nodes.js

@@ -30,7 +30,7 @@ export async function filterNodes(expression, graph) {
     // Pre-augment all nodes once (ancestors/descendants needed for WHERE predicates and SELECT expansion)
     const augmented = new Map();
     for (const node of nodeIndex.values()) {
-        augmented.set(node.title, augmentNode(node, nodeIndex, childrenIndex));
+        augmented.set(node.id, augmentNode(node, nodeIndex, childrenIndex));
     }
     // Step 1: apply WHERE clause to get the matched set
     let matched;
@@ -48,7 +48,7 @@ export async function filterNodes(expression, graph) {
         }
         matched = [];
         for (const node of nodeIndex.values()) {
-            const current = augmented.get(node.title);
+            const current = augmented.get(node.id);
             if (!current)
                 continue;
             // Spread current node fields at root level so bare field names work in expressions

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/judge/context.js

@@ -25,14 +25,14 @@ function dataWithBody(node, withBody) {
     return data;
 }
 /** The evaluated node as a judge sees it. */
-function judgeNodeView(node, withBody) {
+function judgeNodeView(node, withBody, graph) {
     return {
-        label: node.label,
+        id: node.id,
         title: node.title,
         type: node.type,
         resolvedType: node.resolvedType,
         schemaData: dataWithBody(node, withBody),
-        resolvedParents: node.resolvedParents,
+        parentTitles: node.resolvedParents.map((p) => graph.nodes.get(p.id)?.title ?? p.id),
     };
 }
 function relatedView(node, relation, withBody) {
@@ -50,28 +50,28 @@ export function relatedNodes(graph, node, context) {
         ? []
         : n.resolvedParents
             .filter((p) => p.source === 'hierarchy' && p.hierarchy === hierarchyName)
-            .map((p) => graph.nodes.get(p.title))
+            .map((p) => graph.nodes.get(p.id))
             .filter((p) => p !== undefined);
-    const childrenOf = (n) => graph.hierarchyChildren.get(n.title) ?? [];
+    const childrenOf = (n) => graph.hierarchyChildren.get(n.id) ?? [];
     const found = new Map();
     const add = (other, relation) => {
-        if (other.title === node.title)
+        if (other.id === node.id)
             return;
-        const existing = found.get(other.title);
+        const existing = found.get(other.id);
         if (!existing)
-            found.set(other.title, relatedView(other, relation, withBody));
+            found.set(other.id, relatedView(other, relation, withBody));
         else if (!existing.relations.includes(relation))
             existing.relations.push(relation);
     };
     const reach = (next, relation) => {
-        const seen = new Set([node.title]);
+        const seen = new Set([node.id]);
         let level = next(node);
         while (level.length > 0) {
             const following = [];
             for (const n of level) {
-                if (seen.has(n.title))
+                if (seen.has(n.id))
                     continue;
-                seen.add(n.title);
+                seen.add(n.id);
                 add(n, relation);
                 following.push(...next(n));
             }
@@ -99,7 +99,7 @@ export function relatedNodes(graph, node, context) {
 export function judgeContext(graph, node, context) {
     const related = relatedNodes(graph, node, context);
     return {
-        node: judgeNodeView(node, context.content !== 'none'),
+        node: judgeNodeView(node, context.content !== 'none', graph),
         ...(related.length > 0 && { related }),
     };
 }

package/dist/judge/judge-node.d.ts

@@ -4,9 +4,9 @@ import { type TrimReport } from './trim';
 import type { SemanticJudgeProvider } from './types';
 export type NodeJudgement = {
     rule: Rule;
-    /** True when the verdict fails the rule (it has a severity), or the provider errored. */
-    failed: boolean;
-    /** Severity of the failing verdict; unset for a judge error, which takes the rule's own severity. */
+    /** True when the verdict has a severity (so it reports a violation), or the provider errored. */
+    violated: boolean;
+    /** Severity of the verdict; unset for a judge error, which takes the rule's own severity. */
     severity?: RuleSeverity;
     verdict?: string;
     /** User-facing guidance declared for the failing verdict. */

package/dist/judge/judge-node.js

@@ -7,7 +7,7 @@ function resolveAll(rules) {
 function errorJudgements(rules, message) {
     return rules.map((rule) => ({
         rule,
-        failed: true,
+        violated: true,
         evidence: `Error during evaluation: ${message}`,
         error: message,
     }));
@@ -17,20 +17,20 @@ function interpret(rules, resolved, results) {
         const result = results[rule.id];
         if (!result || isJudgeError(result)) {
             const message = result ? result.error : 'Model provider returned no result for this rule';
-            return { rule, failed: true, evidence: `Error during evaluation: ${message}`, error: message };
+            return { rule, violated: true, evidence: `Error during evaluation: ${message}`, error: message };
         }
         const severity = resolved[i].severities[result.verdict];
         if (severity === undefined && !(result.verdict in resolved[i].spec.verdicts)) {
             const message = `Model provider returned unknown verdict "${result.verdict}" (allowed: ${Object.keys(resolved[i].spec.verdicts).join(', ')})`;
-            return { rule, failed: true, evidence: `Error during evaluation: ${message}`, error: message };
+            return { rule, violated: true, evidence: `Error during evaluation: ${message}`, error: message };
         }
-        const failed = severity !== undefined;
+        const violated = severity !== undefined;
         return {
             rule,
-            failed,
+            violated,
             severity,
             verdict: result.verdict,
-            guidance: failed ? resolved[i].guidance[result.verdict] : undefined,
+            guidance: violated ? resolved[i].guidance[result.verdict] : undefined,
             evidence: result.evidence,
         };
     });
@@ -62,7 +62,7 @@ function planUnits(graph, items, report) {
                 continue;
             }
             if (fitted.trimmed && report) {
-                report.nodes.add(node.label);
+                report.nodes.add(node.id);
                 for (const rule of unitRules)
                     report.ruleIds.add(rule.id);
             }

package/dist/judge/prompt.js

@@ -34,12 +34,12 @@ export function buildJudgeUserPrompt({ node, related = [] }, rule) {
         ...verdictList(rule),
         '',
         '# Node Under Evaluation',
-        `- File / Label: ${node.label}`,
+        `- Id: ${node.id}`,
         `- Title: ${node.title}`,
         `- Type: ${node.type} (resolved: ${node.resolvedType})`,
     ];
-    if (node.resolvedParents && node.resolvedParents.length > 0) {
-        lines.push(`- Parents: ${node.resolvedParents.map((p) => p.title).join(', ')}`);
+    if (node.parentTitles.length > 0) {
+        lines.push(`- Parents: ${node.parentTitles.join(', ')}`);
     }
     lines.push('', '## Node Content & Frontmatter:', '```json', JSON.stringify(node.schemaData, null, 2), '```', '');
     if (related.length > 0) {

package/dist/judge/provider/fake.d.ts

@@ -11,7 +11,7 @@ export type FakeJudgeHandler = (call: {
 type FakeConfig = FakeAnswer | FakeJudgeHandler | Map<string, FakeAnswer> | Record<string, FakeAnswer>;
 /**
  * In-memory fake judge for offline, deterministic tests. Configure with a single answer, a handler,
- * or answers keyed by `ruleId:title`, `ruleId:label` or `ruleId` (most specific wins). Unmatched calls get `pass`,
+ * or answers keyed by `ruleId:title`, `ruleId:id` or `ruleId` (most specific wins). Unmatched calls get `pass`,
  * or the rule's first declared verdict.
  */
 export declare class FakeJudgeProvider implements SemanticJudgeProvider {

package/dist/judge/provider/fake.js

@@ -12,7 +12,7 @@ function normalise(answer) {
 }
 /**
  * In-memory fake judge for offline, deterministic tests. Configure with a single answer, a handler,
- * or answers keyed by `ruleId:title`, `ruleId:label` or `ruleId` (most specific wins). Unmatched calls get `pass`,
+ * or answers keyed by `ruleId:title`, `ruleId:id` or `ruleId` (most specific wins). Unmatched calls get `pass`,
  * or the rule's first declared verdict.
  */
 export class FakeJudgeProvider {
@@ -40,15 +40,12 @@ export class FakeJudgeProvider {
         if (isHandler(config))
             return await config({ node, rule });
         if (config instanceof Map) {
-            return (config.get(`${rule.id}:${node.title}`) ??
-                config.get(`${rule.id}:${node.label}`) ??
-                config.get(rule.id) ??
-                fallback);
+            return (config.get(`${rule.id}:${node.title}`) ?? config.get(`${rule.id}:${node.id}`) ?? config.get(rule.id) ?? fallback);
         }
         if (isAnswer(config))
             return config;
         const rec = config;
-        return rec[`${rule.id}:${node.title}`] ?? rec[`${rule.id}:${node.label}`] ?? rec[rule.id] ?? fallback;
+        return rec[`${rule.id}:${node.title}`] ?? rec[`${rule.id}:${node.id}`] ?? rec[rule.id] ?? fallback;
     }
     clearHistory() {
         this.callHistory = [];

package/dist/judge/provider/jev.js

@@ -109,7 +109,7 @@ function nodeState(node, related = []) {
     return {
         title: node.title,
         type: node.resolvedType,
-        parents: node.resolvedParents?.map((p) => p.title) ?? [],
+        parents: node.parentTitles,
         ...node.schemaData,
         ...(related.length > 0 && {
             relatedNodes: related.map((r) => ({

package/dist/judge/provider/openai-decisions.js

@@ -22,7 +22,7 @@ export class OpenAIDecisionsJudgeProvider {
         const stateLines = [
             `Title: ${node.title}`,
             `Type: ${node.resolvedType}`,
-            ...(node.resolvedParents?.length ? [`Parents: ${node.resolvedParents.map((p) => p.title).join(', ')}`] : []),
+            ...(node.parentTitles.length ? [`Parents: ${node.parentTitles.join(', ')}`] : []),
             ...fieldLines(node.schemaData ?? {}),
             ...(input.related ?? []).flatMap((r) => [
                 '',

package/dist/judge/types.d.ts

@@ -26,7 +26,10 @@ export interface RelatedNode {
  */
 export interface SemanticJudgeInput {
     /** The evaluated node. Its body is in `schemaData.content` only when the rules' `includeContent` asks for it. */
-    node: Pick<SpaceNode, 'label' | 'title' | 'type' | 'resolvedType' | 'schemaData' | 'resolvedParents'>;
+    node: Pick<SpaceNode, 'id' | 'title' | 'type' | 'resolvedType' | 'schemaData'> & {
+        /** Display titles of the node's parents. */
+        parentTitles: string[];
+    };
     /** Nodes the rules' `scope` adds, as a flat list. Absent when the scope is empty. */
     related?: RelatedNode[];
     rules: SemanticRuleSpec[];

package/dist/plugins/markdown/index.d.ts

@@ -32,6 +32,12 @@ export declare const MARKDOWN_CONFIG_SCHEMA: {
         readonly templatePrefix: {
             readonly type: "string";
         };
+        readonly folderIndex: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
         readonly typeInference: {
             readonly type: "object";
             readonly properties: {

package/dist/plugins/markdown/index.js

@@ -18,6 +18,7 @@ export const MARKDOWN_CONFIG_SCHEMA = {
         templateDir: { type: 'string', format: 'path' }, // format is hint to config loader to resolve relative directories
         fieldMap: { type: 'object', additionalProperties: { type: 'string' } },
         templatePrefix: { type: 'string' },
+        folderIndex: { type: 'array', items: { type: 'string' } },
         typeInference: TYPE_INFERENCE_CONFIG_SCHEMA,
     },
     additionalProperties: false,

package/dist/plugins/markdown/parse-embedded.d.ts

@@ -57,10 +57,15 @@ export declare function normalizeHeadingSectionTarget(rawHeadingText: string): s
 export declare function defaultNodeType(stack: StackEntry[], hierarchy: readonly string[]): string;
 export interface ExtractEmbeddedOptions {
     /**
-     * Title of the containing page. If provided (and pageType is not a space_on_a_page type),
+     * The containing page. If provided (and pageType is not a space_on_a_page type),
      * the page acts as a virtual depth-0 parent for first-level embedded headings.
+     * `id` is the page's node id (embedded node ids are `<id>#<title>`); `targets` are its
+     * link targets, most specific first (the first is used in generated parent links).
      */
-    pageTitle?: string;
+    page?: {
+        id: string;
+        targets: string[];
+    };
     /**
      * Node type of the containing page.
      * - If set to a real node type: only headings with an explicit `[type:: x]` field or a