structured-context 0.13.1 → 0.14.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
@@ -138,7 +138,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/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/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/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/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