structured-context 0.13.0 → 0.14.0

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.d.ts

@@ -1,4 +1,4 @@
-import type { SemanticJudgeInput, SemanticJudgeResult, SemanticRuleSpec } from '../types.js';
+import type { SemanticJudgeInput, SemanticJudgeResult, SemanticRuleSpec } from './types';
 /** System prompt: a strict judge that answers with one verdict from a closed set, as JSON. */
 export declare function buildJudgeSystemPrompt(): string;
 /** User prompt for one rule on one node. */

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/trim.d.ts

@@ -1,4 +1,4 @@
-import type { SemanticJudgeInput } from '../types.js';
+import type { SemanticJudgeInput } from './types';
 /** The per-node input cap: estimated tokens of one node's input (the node and its related nodes), the same for every provider. */
 export declare const PER_NODE_INPUT_CAP_TOKENS = 32000;
 /** Estimated tokens of a value: its JSON length divided by 4. Provider-independent, and roughly right is enough. */

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/judge/verdicts.d.ts

@@ -1,5 +1,5 @@
 import type { Rule, RuleSeverity } from '../types';
-import type { SemanticJudgeResult, SemanticRuleSpec } from '../types.js';
+import type { SemanticJudgeResult, SemanticRuleSpec } from './types';
 /** Verdicts for a semantic rule that declares none. */
 export declare const DEFAULT_VERDICTS: Record<string, string>;
 /** A semantic rule resolved for evaluation: what the judge sees, and what each verdict means for the user. */

package/dist/load-space-graph.d.ts

@@ -1,6 +1,6 @@
-import type { Config } from './config.js';
-import { type SpaceGraph } from './space-graph.js';
-import type { ReadSpaceResult, SpaceContext } from './types.js';
+import type { Config } from './config';
+import { type SpaceGraph } from './space-graph';
+import type { ReadSpaceResult, SpaceContext } from './types';
 export interface AssembleSpaceGraphOptions {
     /** Named view (resolved via space.views) or a raw filter DSL expression. */
     filter?: string;

package/dist/load-space-graph.js

@@ -1,7 +1,7 @@
-import { filterNodes } from './filter/filter-nodes.js';
-import { readSpace } from './read/read-space.js';
-import { createSpaceContext } from './space-context.js';
-import { buildSpaceGraph } from './space-graph.js';
+import { filterNodes } from './filter/filter-nodes';
+import { readSpace } from './read/read-space';
+import { createSpaceContext } from './space-context';
+import { buildSpaceGraph } from './space-graph';
 /**
  * Assemble a SpaceGraph from a space context: read the space, drop nodes that
  * fail schema validation, build the graph for the selected hierarchy (the main

package/dist/plugins/loader.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020';
 import { getConfigSourceFiles } from '../config';
-import { builtinPlugins } from '../index.js';
+import { builtinPlugins } from '.';
 import { CONFIG_PLUGINS_DIR, normalizePluginName, PLUGIN_PREFIX, shortenPluginName, } from './util';
 /**
  * Walk a plugin's configSchema and resolve any string fields annotated with

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

package/dist/plugins/markdown/parse-embedded.js

@@ -42,7 +42,7 @@ function appendParentField(parentNode, field, linkRef) {
         fieldValue.push(linkRef);
     }
     else {
-        throw new Error(`Cannot append child link to field '${field}' on node '${parentNode.label}': ` +
+        throw new Error(`Cannot append child link to field '${field}' on node '${parentNode.id}': ` +
             `field exists but is not an array (found ${typeof fieldValue}). ` +
             `Child link: ${linkRef}`);
     }
@@ -219,7 +219,7 @@ function isFieldOnlyLine(line) {
         return hasBracketed;
     return /^[a-zA-Z][a-zA-Z0-9_-]*:: *.*$/.test(cleanText);
 }
-function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset, walk) {
+function processListItem(item, parentRef, contentTarget, nodes, makeId, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset, walk) {
     const itemEnd = offsetsOf(item).end;
     const firstPara = item.children.find((c) => c.type === 'paragraph');
     if (!firstPara) {
@@ -270,7 +270,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             : undefined;
         const linkTargets = buildLinkTargets(title);
         const newNode = {
-            label: makeLabel(title),
+            id: makeId(title),
             title,
             schemaData,
             linkTargets,
@@ -294,7 +294,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
                 continue;
             if (child.type === 'list') {
                 for (const subItem of child.children) {
-                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset, walk);
+                    processListItem(subItem, nestedParentRef, newNode, nodes, makeId, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset, walk);
                 }
             }
             else {
@@ -316,7 +316,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
  * (directory) to find embedded sub-nodes within a page's content.
  */
 export function extractEmbeddedNodes(body, options) {
-    const { pageTitle, pageType, metadata, fieldMap } = options;
+    const { page, pageType, metadata, fieldMap } = options;
     const levels = metadata.hierarchy?.levels ?? [];
     const hierarchy = levels.map((l) => l.type);
     const relationships = metadata.relationships ?? [];
@@ -325,7 +325,7 @@ export function extractEmbeddedNodes(body, options) {
     const nodes = [];
     // Preamble/root content sink - never added to nodes
     const rootNode = {
-        label: '_root_',
+        id: '_root_',
         title: '_root_',
         schemaData: { type: 'space_on_a_page' },
         linkTargets: [],
@@ -335,8 +335,8 @@ export function extractEmbeddedNodes(body, options) {
     const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
     // In typed-page mode: stack starts with the page's own virtual entry (depth 0).
     // In space_on_a_page mode: stack starts empty (first heading has no parent).
-    const stack = !isOnAPageMode && pageTitle !== undefined
-        ? [{ depth: 0, title: pageTitle, nodeType: pageType, refTarget: pageTitle }]
+    const stack = !isOnAPageMode && page !== undefined
+        ? [{ depth: 0, title: page.targets[0] ?? page.id, nodeType: pageType, refTarget: page.targets[0] ?? page.id }]
         : [];
     let parseState = isOnAPageMode ? 'preamble' : 'active';
     let preambleNodeCount = 0;
@@ -442,8 +442,8 @@ export function extractEmbeddedNodes(body, options) {
         }
         return undefined;
     }
-    function makeLabel(title) {
-        return title;
+    function makeId(title) {
+        return (page ? `${page.id}#${title}` : title);
     }
     /**
      * Walk the stack backwards to find the deepest typed node entry (nodeType !== '').
@@ -486,24 +486,26 @@ export function extractEmbeddedNodes(body, options) {
         return g.headingNode;
     }
     function buildHeadingLinkTargets(rawHeadingText, title, anchor) {
-        if (!pageTitle) {
+        if (!page) {
             return [title];
         }
         const targets = [];
         const sectionTarget = normalizeHeadingSectionTarget(rawHeadingText);
         if (sectionTarget) {
-            targets.push(`${pageTitle}#${sectionTarget}`);
+            for (const pageTarget of page.targets)
+                targets.push(`${pageTarget}#${sectionTarget}`);
         }
         if (anchor) {
-            targets.push(`${pageTitle}#^${anchor}`);
+            for (const pageTarget of page.targets)
+                targets.push(`${pageTarget}#^${anchor}`);
         }
         return targets.length > 0 ? targets : [title];
     }
     function buildListItemLinkTargets(title) {
-        if (!pageTitle)
+        if (!page)
             return [title];
         const normalized = normalizeHeadingSectionTarget(title);
-        return normalized ? [`${pageTitle}#${normalized}`] : [title];
+        return normalized ? page.targets.map((pageTarget) => `${pageTarget}#${normalized}`) : [title];
     }
     let grouping = null;
     let activeNode = rootNode;
@@ -604,7 +606,7 @@ export function extractEmbeddedNodes(body, options) {
                 : undefined;
             const linkTargets = buildHeadingLinkTargets(rawText, title, anchor);
             const headingNode = {
-                label: makeLabel(title),
+                id: makeId(title),
                 title,
                 schemaData,
                 linkTargets,
@@ -655,14 +657,14 @@ export function extractEmbeddedNodes(body, options) {
                     : undefined;
                 const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset, walk);
+                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeId, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset, walk);
                 }
                 grouping = null;
             }
             else {
                 const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset, walk);
+                    processListItem(item, parentRef, activeNode, nodes, makeId, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset, walk);
                 }
             }
         }
@@ -755,7 +757,7 @@ export function extractEmbeddedNodes(body, options) {
                             : undefined;
                         const linkTargets = buildListItemLinkTargets(title);
                         const rowNode = {
-                            label: makeLabel(title),
+                            id: makeId(title),
                             title,
                             schemaData,
                             linkTargets,
@@ -788,7 +790,7 @@ export function extractEmbeddedNodes(body, options) {
                 const { fields: unbracketedFields } = extractUnbracketedFields(afterBracketed);
                 const allFields = applyFieldMap({ ...unbracketedFields, ...bracketedFields }, fieldMap);
                 if ('type' in allFields) {
-                    throw new Error(`Type override via paragraph field is not supported at "${activeNode.schemaData.title ?? activeNode.label}". ` +
+                    throw new Error(`Type override via paragraph field is not supported at "${activeNode.schemaData.title ?? activeNode.id}". ` +
                         `Put [type:: ${allFields.type}] directly in the heading text.`);
                 }
                 Object.assign(activeNode.schemaData, allFields);
@@ -817,7 +819,7 @@ export function extractEmbeddedNodes(body, options) {
                     consumeBlock(activeNode);
                 }
                 else if (Array.isArray(parsed)) {
-                    throw new Error(`YAML block must be an object at "${activeNode.label}".`);
+                    throw new Error(`YAML block must be an object at "${activeNode.id}".`);
                 }
                 else {
                     claimBlock(activeNode);

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

@@ -5,7 +5,7 @@ import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
 import { extractLinksFromBody, extractLinksFromFrontmatter, getEdgeFieldNames } from './extract-content-links';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
-import { applyFieldMap, inferTypeFromPath, MATTER_OPTIONS } from './util';
+import { applyFieldMap, defaultPageTitle, inferTypeFromPath, MATTER_OPTIONS, pathLinkTargets } from './util';
 export function readSpaceOnAPage(context) {
     const { space, resolvedSchemaPath, schema: { metadata }, } = context;
     const filePath = resolve(space.path);
@@ -20,12 +20,11 @@ export function readSpaceOnAPage(context) {
     if (!hierarchyLevels || hierarchyLevels.length === 0) {
         throw new Error(`Schema at ${resolvedSchemaPath} must define "$metadata.hierarchy.levels" to read a space_on_a_page file.`);
     }
-    const pageTitle = basename(filePath, '.md');
     const fmMatch = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
     const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
     const fileName = basename(filePath);
     const { nodes, preambleNodeCount, terminatedHeadings } = extractEmbeddedNodes(body, {
-        pageTitle,
+        page: { id: fileName, targets: pathLinkTargets(fileName) },
         pageType: 'space_on_a_page',
         metadata,
         file: fileName,
@@ -98,15 +97,17 @@ export async function readSpaceDirectory(context, options) {
             continue;
         }
         const pageType = data.type;
-        const fileBase = basename(file, '.md');
-        const title = data.title ?? fileBase;
+        const explicitTitle = data.title;
+        const title = explicitTitle ?? defaultPageTitle(file, mdCfg.folderIndex);
+        const pathTargets = pathLinkTargets(file);
         const fmMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
         const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
         const pageNode = {
-            label: file,
+            id: file,
             title,
             schemaData: { title, ...data },
-            linkTargets: [title, fileBase],
+            // A title derived from a folder index is display only, never a link target.
+            linkTargets: [...new Set([...(explicitTitle !== undefined ? [explicitTitle] : []), ...pathTargets])],
             type: pageType,
             source: { file, line: 1 },
             ...(data.content !== undefined ? { content: data.content } : {}),
@@ -114,7 +115,7 @@ export async function readSpaceDirectory(context, options) {
         };
         if (!ON_A_PAGE_TYPES.includes(pageType)) {
             const { nodes: embedded, preambleContent, preambleFields, terminatedHeadings, } = extractEmbeddedNodes(parsed.content, {
-                pageTitle: fileBase,
+                page: { id: file, targets: pathTargets },
                 pageType,
                 metadata,
                 fieldMap,

package/dist/plugins/markdown/render-bullets.js

@@ -6,14 +6,14 @@ export function renderBullets(graph) {
         const indent = '  '.repeat(depth);
         const type = node.resolvedType;
         const title = node.title;
-        const nodeChildren = children.get(title) ?? [];
-        if (seen.has(title)) {
+        const nodeChildren = children.get(node.id) ?? [];
+        if (seen.has(node.id)) {
             if (nodeChildren.length > 0) {
                 lines.push(`${indent}- ${type}: ${title} (*)`);
             }
             return;
         }
-        seen.add(title);
+        seen.add(node.id);
         lines.push(`${indent}- ${type}: ${title}`);
         for (const child of nodeChildren) {
             renderNode(child, depth + 1);

package/dist/plugins/markdown/render-directory.js

@@ -1,6 +1,6 @@
 import { posix } from 'node:path';
 import matter from 'gray-matter';
-import { getMarkdownConfig } from '../../index.js';
+import { getMarkdownConfig } from './index';
 import { invertFieldMap, MATTER_OPTIONS } from './util';
 /**
  * Sanitize a node title into a valid filesystem filename.

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

@@ -1,5 +1,5 @@
 import { type DumpOptions, type Schema } from 'js-yaml';
-import type { TypeInferenceConfig } from '../../index.js';
+import type { TypeInferenceConfig } from '.';
 export declare function inferTypeFromPath(filePath: string, config: TypeInferenceConfig, knownTypes: Set<string>, typeAliases: Record<string, string> | undefined): string | undefined;
 /**
  * YAML schema for frontmatter and embedded YAML blocks: YAML 1.2 Core schema extended with
@@ -38,3 +38,14 @@ export declare function applyFieldMap(data: Record<string, unknown>, fieldMap: R
  * Used for write operations (e.g. template-sync) to translate back to file field names.
  */
 export declare function invertFieldMap(fieldMap: Record<string, string>): Record<string, string>;
+/**
+ * Link targets for a page, most specific first: the space-relative path without `.md` and every shorter
+ * path suffix down to the basename. Obsidian writes these when a bare name is ambiguous.
+ */
+export declare function pathLinkTargets(file: string): string[];
+/**
+ * Display title for a page without an explicit `title`: the containing folder's name when the file is a
+ * folder index (its basename is listed in `folderIndex`, case-insensitively), otherwise the basename.
+ * An index at the space root has no folder to name it and keeps its basename.
+ */
+export declare function defaultPageTitle(file: string, folderIndex: string[] | undefined): string;

package/dist/plugins/markdown/util.js

@@ -119,3 +119,24 @@ export function applyFieldMap(data, fieldMap) {
 export function invertFieldMap(fieldMap) {
     return Object.fromEntries(Object.entries(fieldMap).map(([src, canonical]) => [canonical, src]));
 }
+/**
+ * Link targets for a page, most specific first: the space-relative path without `.md` and every shorter
+ * path suffix down to the basename. Obsidian writes these when a bare name is ambiguous.
+ */
+export function pathLinkTargets(file) {
+    const segments = file.replace(/\\/g, '/').replace(/\.md$/i, '').split('/');
+    return segments.map((_, i) => segments.slice(i).join('/'));
+}
+/**
+ * Display title for a page without an explicit `title`: the containing folder's name when the file is a
+ * folder index (its basename is listed in `folderIndex`, case-insensitively), otherwise the basename.
+ * An index at the space root has no folder to name it and keeps its basename.
+ */
+export function defaultPageTitle(file, folderIndex) {
+    const segments = file.replace(/\\/g, '/').replace(/\.md$/i, '').split('/');
+    const base = segments[segments.length - 1];
+    const folder = segments[segments.length - 2];
+    if (folder !== undefined && folderIndex?.some((name) => name.toLowerCase() === base.toLowerCase()))
+        return folder;
+    return base;
+}

package/dist/plugins/mermaid/render-mermaid.js

@@ -15,7 +15,7 @@ function safeNodeId(id) {
     return id.replace(/[^a-zA-Z0-9_-]/g, '_');
 }
 export function renderMermaid(graph) {
-    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet } = graph;
+    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyIds: hierarchyNodeSet } = graph;
     const levels = graph.hierarchy?.levels ?? [];
     let mmd = 'graph TD\n';
     for (let i = 0; i < levels.length; i++) {
@@ -25,21 +25,20 @@ export function renderMermaid(graph) {
     }
     const addedNodes = new Set();
     function addNodeAndChildren(node) {
-        const nodeId = node.title;
+        const nodeId = node.id;
         if (addedNodes.has(nodeId))
             return;
         addedNodes.add(nodeId);
         const type = node.resolvedType;
         const priority = node.schemaData.priority;
-        const label = priority ? `${nodeId} (${priority})` : nodeId;
+        const label = priority ? `${node.title} (${priority})` : node.title;
         const safeId = safeNodeId(nodeId);
         const escapedLabel = escapeMermaidString(label);
         mmd += `  ${safeId}["${escapedLabel}"]:::${type}\n`;
         const nodeChildren = children.get(nodeId) ?? [];
         for (const child of nodeChildren) {
-            const childTitle = child.title;
-            if (hierarchyNodeSet.has(childTitle)) {
-                const safeChildId = safeNodeId(childTitle);
+            if (hierarchyNodeSet.has(child.id)) {
+                const safeChildId = safeNodeId(child.id);
                 mmd += `  ${safeId} --> ${safeChildId}\n`;
                 addNodeAndChildren(child);
             }

package/dist/plugins/miro/cache.js

@@ -30,7 +30,7 @@ export function computeNodeHash(node) {
         status: node.schemaData.status,
         summary: node.schemaData.summary,
         priority: node.schemaData.priority,
-        parents: node.resolvedParents.filter((r) => r.source === 'hierarchy').map((r) => r.title),
+        parents: node.resolvedParents.filter((r) => r.source === 'hierarchy').map((r) => r.id),
     };
     return createHash('sha256').update(JSON.stringify(relevant)).digest('hex').slice(0, 16);
 }

package/dist/plugins/miro/sync.js

@@ -17,7 +17,7 @@ export async function miroSync(context, graph, options) {
         throw new Error('No frameId in miro plugin config. Pass --new-frame "Title" to create one.');
     // 3. Filter to hierarchy nodes only (graph already built by caller)
     const levels = graph.hierarchy?.levels ?? [];
-    const nodes = [...graph.nodes.values()].filter((n) => graph.hierarchyTitles.has(n.title));
+    const nodes = [...graph.nodes.values()].filter((n) => graph.hierarchyIds.has(n.id));
     if (nodes.length === 0) {
         return 'No space nodes found.';
     }
@@ -257,9 +257,10 @@ export async function miroSync(context, graph, options) {
     const desiredEdges = new Map();
     for (const node of nodes) {
         const childTitle = node.title;
-        for (const { title: parentTitle, source, hierarchy } of node.resolvedParents) {
+        for (const { id: parentId, source, hierarchy } of node.resolvedParents) {
             if (source !== 'hierarchy' || hierarchy !== graph.hierarchy?.name)
                 continue;
+            const parentTitle = graph.nodes.get(parentId)?.title ?? parentId;
             // Both endpoints must have verified cards on the board
             if (verifiedCardIds.has(parentTitle) && verifiedCardIds.has(childTitle)) {
                 const key = `${parentTitle}\u2192${childTitle}`;