structured-context 0.13.0 → 0.14.0

package/dist/space-graph.d.ts

@@ -1,4 +1,4 @@
-import type { Hierarchy, SpaceNode } from './types.js';
+import type { Hierarchy, NodeId, SpaceNode } from './types';
 /**
  * A navigable graph over a set of SpaceNodes.
  *
@@ -9,20 +9,20 @@ import type { Hierarchy, SpaceNode } from './types.js';
  * so consumers don't need to build their own indexes.
  */
 export type SpaceGraph = {
-    /** All nodes, keyed by title. Preserves insertion order. */
-    readonly nodes: ReadonlyMap<string, SpaceNode>;
+    /** All nodes, keyed by id. Preserves insertion order. */
+    readonly nodes: ReadonlyMap<NodeId, SpaceNode>;
     /** Hierarchy roots: nodes of the root type with no valid hierarchy parents. */
     readonly hierarchyRoots: readonly SpaceNode[];
     /** Orphans: hierarchy-typed nodes with no valid hierarchy parents in the node set. */
     readonly orphans: readonly SpaceNode[];
     /** Non-hierarchy nodes: type not in the hierarchy levels definition. */
     readonly nonHierarchy: readonly SpaceNode[];
-    /** Hierarchy children map: parent title → direct children connected via this hierarchy's edges only. */
-    readonly hierarchyChildren: ReadonlyMap<string, readonly SpaceNode[]>;
-    /** All-edges children map: parent title → direct children connected via any edge (hierarchy + relationship). */
-    readonly children: ReadonlyMap<string, readonly SpaceNode[]>;
-    /** Set of all node titles that are part of the hierarchy (roots + their descendants + orphans). */
-    readonly hierarchyTitles: ReadonlySet<string>;
+    /** Hierarchy children map: parent id → direct children connected via this hierarchy's edges only. */
+    readonly hierarchyChildren: ReadonlyMap<NodeId, readonly SpaceNode[]>;
+    /** All-edges children map: parent id → direct children connected via any edge (hierarchy + relationship). */
+    readonly children: ReadonlyMap<NodeId, readonly SpaceNode[]>;
+    /** Set of all node ids that are part of the hierarchy (roots + their descendants + orphans). */
+    readonly hierarchyIds: ReadonlySet<NodeId>;
     /** The hierarchy used to build this graph, if the schema has one. */
     readonly hierarchy: Hierarchy | undefined;
 };

package/dist/space-graph.js

@@ -12,22 +12,22 @@ export function buildSpaceGraph(nodes, hierarchy) {
     const nonHierarchy = [];
     // First pass: register all nodes and init adjacency lists
     for (const node of nodes) {
-        nodesMap.set(node.title, node);
-        hierarchyChildrenMap.set(node.title, []);
-        childrenMap.set(node.title, []);
+        nodesMap.set(node.id, node);
+        hierarchyChildrenMap.set(node.id, []);
+        childrenMap.set(node.id, []);
     }
     // Second pass: build children maps (inverted from resolvedParents)
     for (const node of nodes) {
         for (const parentRef of node.resolvedParents) {
             // All-edges map
-            if (!childrenMap.has(parentRef.title))
-                childrenMap.set(parentRef.title, []);
-            childrenMap.get(parentRef.title).push(node);
+            if (!childrenMap.has(parentRef.id))
+                childrenMap.set(parentRef.id, []);
+            childrenMap.get(parentRef.id).push(node);
             // Hierarchy-only map
             if (isHierarchyEdge(parentRef)) {
-                if (!hierarchyChildrenMap.has(parentRef.title))
-                    hierarchyChildrenMap.set(parentRef.title, []);
-                hierarchyChildrenMap.get(parentRef.title).push(node);
+                if (!hierarchyChildrenMap.has(parentRef.id))
+                    hierarchyChildrenMap.set(parentRef.id, []);
+                hierarchyChildrenMap.get(parentRef.id).push(node);
             }
         }
     }
@@ -50,20 +50,20 @@ export function buildSpaceGraph(nodes, hierarchy) {
         }
         else {
             // Check if at least one hierarchy parent is actually in the node set
-            const hasValidParent = hierarchyParents.some((r) => nodesMap.has(r.title));
+            const hasValidParent = hierarchyParents.some((r) => nodesMap.has(r.id));
             if (!hasValidParent) {
                 // All hierarchy parents are dangling — treat as orphan
                 orphans.push(node);
             }
         }
     }
-    // Build hierarchyTitles: BFS from roots + orphans through hierarchyChildren
-    const hierarchyTitles = new Set();
+    // Build hierarchyIds: BFS from roots + orphans through hierarchyChildren
+    const hierarchyIds = new Set();
     function addHierarchySubtree(node) {
-        if (hierarchyTitles.has(node.title))
+        if (hierarchyIds.has(node.id))
             return;
-        hierarchyTitles.add(node.title);
-        for (const child of hierarchyChildrenMap.get(node.title) ?? []) {
+        hierarchyIds.add(node.id);
+        for (const child of hierarchyChildrenMap.get(node.id) ?? []) {
             addHierarchySubtree(child);
         }
     }
@@ -78,7 +78,7 @@ export function buildSpaceGraph(nodes, hierarchy) {
         nonHierarchy,
         hierarchyChildren: hierarchyChildrenMap,
         children: childrenMap,
-        hierarchyTitles,
+        hierarchyIds,
         hierarchy,
     };
 }

package/dist/testing.d.ts

@@ -1,9 +1,9 @@
-import type { BaseNode, Hierarchy, HierarchyLevel, Relationship, ResolvedParentRef, SpaceNode } from './types.js';
+import type { BaseNode, Hierarchy, HierarchyLevel, Relationship, ResolvedParentRef, SpaceNode } from './types';
 /**
  * Creates a ResolvedParentRef with sensible defaults for use in tests.
  * Override any field to represent specific edge contexts.
  */
-export declare const makeParentRef: (title: string, overrides?: Partial<ResolvedParentRef>) => ResolvedParentRef;
+export declare const makeParentRef: (id: string, overrides?: Partial<ResolvedParentRef>) => ResolvedParentRef;
 /**
  * Creates a HierarchyLevel with defaults matching schema metadata normalization.
  */

package/dist/testing.js

@@ -2,10 +2,10 @@
  * Creates a ResolvedParentRef with sensible defaults for use in tests.
  * Override any field to represent specific edge contexts.
  */
-export const makeParentRef = (title, overrides = {}) => {
+export const makeParentRef = (id, overrides = {}) => {
     const source = overrides.source ?? 'hierarchy';
     return {
-        title,
+        id: id,
         field: 'parent',
         source,
         ...(source === 'hierarchy' ? { hierarchy: 'main' } : {}),
@@ -55,7 +55,7 @@ export const makeRelationship = (parent, type, overrides = {}) => ({
  * Creates a BaseNode with sensible defaults for use in tests.
  */
 export const makeNode = (title, type, extra = {}, linkTargets) => ({
-    label: `${title}.md`,
+    id: title,
     title,
     schemaData: { title, type, ...extra },
     linkTargets: linkTargets ?? [title],

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
-import type { Config, SpaceConfig } from './config.js';
-import type { MetadataContractHierarchyLevel, MetadataContractRelationship, Rule, SharedEdgeFields } from './schema/metadata-contract.js';
+import type { Config, SpaceConfig } from './config';
+import type { MetadataContractHierarchyLevel, MetadataContractRelationship, Rule, SharedEdgeFields } from './schema/metadata-contract';
 /**
  * Minimal normalized edge for graph resolution.
  * Derives routing fields from SharedEdgeFields to stay in sync with the schema.
@@ -28,14 +28,18 @@ export type Relationship = Omit<MetadataContractRelationship, 'field' | 'fieldOn
     fieldOn: 'child' | 'parent';
     multiple: boolean;
 };
+/** Unique key of a node within a space. Supplied by the plugin that produced the node. */
+export type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
 /**
- * A resolved parent reference, capturing not just the parent title but the edge context
+ * A resolved parent reference, capturing not just the parent id but the edge context
  * from which it was resolved. All hierarchy levels and relationships produce entries of
  * this type, forming a single labelled graph rather than separate structures.
  */
 export type ResolvedParentRef = {
-    /** Canonical title of the parent node. */
-    title: string;
+    /** Id of the parent node. */
+    id: NodeId;
     /** The field name that contained the wikilink (e.g. 'parent', 'key_activities', 'produces_data'). */
     field: string;
     /** Whether this edge originates from a hierarchy level or a relationship definition. */
@@ -56,8 +60,8 @@ export type SourceLocation = {
     column?: number;
 };
 export type UnresolvedRef = {
-    /** Source identifier of the node containing the broken link. */
-    label: string;
+    /** Id of the node containing the broken link. */
+    id: NodeId;
     /** Raw wikilink value (or String(rawField) for invalid_shape). */
     ref: string;
     /** Field name that contained the link. */
@@ -109,9 +113,9 @@ export type ResolvedContentLink = ContentLinkBase & {
  * Core enriches this into a SpaceNode after parsing.
  */
 export type BaseNode = {
-    /** Source identifier for error messages (filename or heading title) */
-    label: string;
-    /** Canonical title of the node (from schemaData.title). First-class accessor. */
+    /** Unique key of the node: graph key, parent lookup, gating, duplicate detection and the file in messages. Supplied by the plugin. */
+    id: NodeId;
+    /** Display title (from schemaData.title). May repeat across nodes. */
     title: string;
     /** Fields validated against the active schema. */
     schemaData: Record<string, unknown>;
@@ -138,7 +142,7 @@ export type SpaceNode = BaseNode & {
     resolvedType: string;
     /**
      * Resolved parent references derived from all edge fields (hierarchy levels + relationships).
-     * Each entry carries the parent title, the field it came from, and its edge context.
+     * Each entry carries the parent id, the field it came from, and its edge context.
      * Always present, empty if no parents resolved.
      */
     resolvedParents: ResolvedParentRef[];
@@ -171,10 +175,10 @@ export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-pract
  * A rule's severity defaults from its category and may be overridden per rule.
  */
 export type RuleSeverity = 'error' | 'warning' | 'info';
-export type { CoverageGate, GatingSeed } from './schema/gating.js';
-export type { Rule } from './schema/metadata-contract.js';
+export type { CoverageGate, GatingSeed } from './schema/gating';
+export type { Rule } from './schema/metadata-contract';
 export type RuleViolation = {
-    /** Node label, or empty string for global-scope rules. */
+    /** Node id, or empty string for global-scope rules. */
     file: string;
     ruleId: string;
     category: RuleCategory;

package/dist/validate.d.ts

@@ -1,9 +1,9 @@
 import type { ErrorObject } from 'ajv';
-import type { Config, SpaceConfig } from './config.js';
-import type { SemanticJudgeProvider } from './judge/types.js';
-import { type RuleFilter } from './schema/rule-filter.js';
-import { extractEntityInfo } from './schema/schema.js';
-import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types.js';
+import type { Config, SpaceConfig } from './config';
+import type { SemanticJudgeProvider } from './judge/types';
+import { type RuleFilter } from './schema/rule-filter';
+import { extractEntityInfo } from './schema/schema';
+import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
@@ -24,7 +24,7 @@ export interface ValidationResult {
         error: string;
     }>;
     duplicateErrors: Array<{
-        title: string;
+        id: NodeId;
         files: string[];
     }>;
     /** All rule violations with their effective severity. Only `error` severity fails validation. */

package/dist/validate.js

@@ -1,12 +1,12 @@
 import { isAbsolute, relative, resolve } from 'node:path';
-import { readSpace } from './read/read-space.js';
-import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating.js';
-import { filterRules } from './schema/rule-filter.js';
-import { extractEntityInfo } from './schema/schema.js';
-import { validateGraph } from './schema/validate-graph.js';
-import { validateRules } from './schema/validate-rules.js';
-import { createSpaceContext } from './space-context.js';
-import { buildSpaceGraph } from './space-graph.js';
+import { readSpace } from './read/read-space';
+import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating';
+import { filterRules } from './schema/rule-filter';
+import { extractEntityInfo } from './schema/schema';
+import { validateGraph } from './schema/validate-graph';
+import { validateRules } from './schema/validate-rules';
+import { createSpaceContext } from './space-context';
+import { buildSpaceGraph } from './space-graph';
 /**
  * Format AJV errors for better readability.
  * Groups related errors and extracts helpful context like allowed values.
@@ -182,17 +182,17 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
             result.nodeFailures.push({ node, errors: schemaValidator.errors || [] });
         }
     }
-    // Detect duplicate node keys (titles)
-    const titleToFiles = new Map();
+    // Detect duplicate node ids. Display titles may repeat.
+    const idToFiles = new Map();
     for (const node of nodes) {
-        if (!titleToFiles.has(node.title)) {
-            titleToFiles.set(node.title, []);
+        if (!idToFiles.has(node.id)) {
+            idToFiles.set(node.id, []);
         }
-        titleToFiles.get(node.title).push(node.label);
+        idToFiles.get(node.id).push(node.id);
     }
-    for (const [title, files] of titleToFiles) {
+    for (const [id, files] of idToFiles) {
         if (files.length > 1) {
-            result.duplicateErrors.push({ title, files });
+            result.duplicateErrors.push({ id, files });
         }
     }
     // Validate all hierarchy constraints (field references and structure)
@@ -207,10 +207,9 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     if (metadata.rules) {
         const seeds = [
             ...result.nodeFailures.map(({ node }) => {
-                const file = node.source?.file ?? node.label;
-                return { file, title: String(node.schemaData.title ?? file), reason: 'schema' };
+                return { file: node.source?.file ?? node.id, id: node.id, reason: 'schema' };
             }),
-            ...result.hierarchyViolations.map((v) => ({ file: v.file, title: v.nodeTitle, reason: 'hierarchy' })),
+            ...result.hierarchyViolations.map((v) => ({ file: v.file, id: v.file, reason: 'hierarchy' })),
         ];
         const trimReport = { nodes: new Set(), ruleIds: new Set() };
         const { violations, gates } = await evaluateSpaceRules(nodes, metadata, seeds, { ...options, trimReport });
@@ -223,10 +222,10 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     for (const node of nodes) {
         for (const link of node.resolvedLinks) {
             if (link.location === 'internal') {
-                const key = `${node.label}::${link.target}`;
+                const key = `${node.id}::${link.target}`;
                 if (!seen.has(key)) {
                     seen.add(key);
-                    result.unresolvedContentLinks.push({ file: node.label, target: link.target });
+                    result.unresolvedContentLinks.push({ file: node.id, target: link.target });
                 }
             }
         }
@@ -249,9 +248,9 @@ export async function validateSpace(context, options = {}) {
         const depths = computeHierarchyDepths(fullGraph);
         const included = [];
         for (const node of nodes) {
-            const nodeDepth = depths.get(node.title);
+            const nodeDepth = depths.get(node.id);
             if (nodeDepth !== undefined && nodeDepth > options.depth) {
-                skippedByDepth.push({ file: node.label, title: node.title });
+                skippedByDepth.push({ file: node.id, title: node.title });
             }
             else {
                 included.push(node);
@@ -268,7 +267,7 @@ export async function validateSpace(context, options = {}) {
         validCount: result.validCount,
         nodeErrorCount: result.nodeFailures.length,
         nodeErrors: result.nodeFailures.map(({ node, errors }) => ({
-            file: node.source?.file ?? node.label,
+            file: node.source?.file ?? node.id,
             ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
             errors,
             nodeData: node.schemaData,
@@ -308,7 +307,7 @@ function issuesForFile(result, label, context, includeGated) {
     const errors = {};
     const warnings = {};
     for (const { node, errors: ajvErrors, invalidType } of result.nodeFailures) {
-        if (node.label !== label)
+        if (node.id !== label)
             continue;
         const position = {
             ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
@@ -328,13 +327,13 @@ function issuesForFile(result, label, context, includeGated) {
         }
     }
     // Duplicate key errors — include if this file is one of the duplicates
-    for (const { title, files } of result.duplicateErrors) {
+    for (const { id, files } of result.duplicateErrors) {
         if (!files.includes(label))
             continue;
         const others = files.filter((f) => f !== label);
-        errors[`duplicate:${title}`] = {
+        errors[`duplicate:${id}`] = {
             kind: 'duplicate',
-            message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
+            message: `Duplicate id "${id}" also exists in: ${others.join(', ')}`,
         };
     }
     // Broken links and hierarchy violations from this file

package/docs/concepts.md

@@ -97,12 +97,30 @@ A **space node** (or **node** for short) is a single entity in a `space` — a n
 
 Node types are defined by the schema in use and may vary across schemas. Examples from the default schema: `vision`, `mission`, `goal`, `opportunity`, `solution`. The tooling is not prescriptive about which types exist — schemas are designed to be extended and replaced.
 
+Each node has an `id` (its unique key), a `title` (its display name) and `linkTargets` (the names wikilinks may use to reach it). See [Node key](#node-key).
+
 Each node retains its physical `source` location (`file`, and `line` / `column` where available) so that validation diagnostics, edge errors, and downstream tooling pinpoint the exact location in the vault.
 
 A node's `content` is the markdown source of its body; see [Node content](#node-content).
 
 > `space_on_a_page` and `dashboard` are not `space node` types — they are `tooling types`.
 
+### Node key
+
+Three values on every node do separate jobs:
+
+| Value | Job | Unique? | Markdown source |
+|---|---|---|---|
+| `id` | Identifies the node: graph key, parent lookup, gating, duplicate detection, and the file shown in messages | Yes. Two nodes with the same `id` are a duplicate error | Path relative to the space root, with extension (`projects/alpha/Overview.md`). Embedded nodes use `<page id>#<heading>` |
+| `title` | Display name in `show`, rendered output and judge prompts | No | `title:` frontmatter, else the containing folder's name for a [folder index](#folder-index), else the file's basename |
+| `linkTargets` | The names a wikilink may use to reach the node | Per name. A name shared by several nodes is reported as ambiguous where a link uses it | The explicit `title:`, the basename, and every path suffix without `.md` |
+
+A wikilink is looked up in `linkTargets`, and the result is stored as the target node's `id`. Other values hold the rest of the picture: `source` is where the node is defined, `resolvedParents` lists parents by `id`, and `resolvedLinks` classifies content links. A parent field resolves exactly as a link does.
+
+### Folder index
+
+A **folder index** is a page that stands for its folder: `Overview.md` or `index.md` inside `projects/alpha/`. Obsidian has no container pages, so a node with child pages is a folder plus an index page. Listing the index basenames in the markdown plugin's [`folderIndex`](config.md#folderindex) config gives each folder index the folder's name as its `title`. The derived title is for display only and never a link target.
+
 ### Embedded node
 
 An **embedded node** is a `space node` defined *within* a containing document rather than as its own file. Embedded nodes are declared using markdown heading syntax with inline field annotations (e.g. `[type:: goal]`) or `anchor-implied types`, and are extracted at parse time.
@@ -187,9 +205,9 @@ The **per-node input cap** limits the input for one evaluated node and its relat
 
 ### Cascade gating
 
-**Cascade gating** is the mechanism by which a schema failure, hierarchy structure violation, or blocking rule violation on a node suppresses rule evaluation for that node's `hierarchy` subtree. It exists so downstream checks — especially costly semantic (model-judged) rules — aren't run against inputs already known to be invalid.
+**Cascade gating** is the mechanism by which a schema validation error, hierarchy structure violation, or gating rule violation on a node suppresses rule evaluation for that node's `hierarchy` subtree. It exists so downstream checks — especially costly semantic (model-judged) rules — aren't run against inputs already known to be invalid.
 
-A **coverage gate** records one instance of this: the gating node, what kind of failure triggered it (`schema`, `hierarchy`, or a specific rule `id`), and the set of nodes whose rules were suppressed as a result. `sctx validate` reports coverage gates so both humans and agents can see the validation "edge" — where evaluation stopped and why. See [docs/rules.md](rules.md#cascade-gating) for the full model, including the per-rule `gatesDescendants` field and the `--include-gated` / `--depth` CLI options.
+A **coverage gate** records one instance of this: the gating node, what kind of violation triggered it (`schema`, `hierarchy`, or a specific rule `id`), and the set of nodes whose rules were suppressed as a result. `sctx validate` reports coverage gates so both humans and agents can see the validation "edge" — where evaluation stopped and why. See [docs/rules.md](rules.md#cascade-gating) for the full model, including the per-rule `gatesDescendants` field and the `--include-gated` / `--depth` CLI options.
 
 ---
 
@@ -288,7 +306,7 @@ A **wikilink** is the `[[Title]]` linking syntax (compatible with Obsidian) used
 
 | Form | Example | Resolves to |
 |---|---|---|
-| Plain title | `[[My Goal]]` | The `space node` whose title equals `My Goal` |
+| Name or path | `[[My Goal]]`, `[[alpha/Overview]]` | The `space node` with that name in its `linkTargets`. A bare name shared by several nodes is ambiguous; add enough of the path to make it unique, as Obsidian does |
 | Anchor ref | `[[vision_page#^goal1]]` | The `embedded node` with `anchor` `goal1` inside `vision_page.md` |
 
 ### Resolved parents
@@ -299,7 +317,7 @@ Each entry is a `ResolvedParentRef` object:
 
 | Field | Type | Description |
 |---|---|---|
-| `title` | `string` | The parent node's title |
+| `id` | `NodeId` | The parent node's `id` |
 | `field` | `string` | The frontmatter field that held the wikilink |
 | `source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy level or a relationship |
 | `hierarchy` | `string` | Name of the hierarchy the edge belongs to; present only when `source` is `'hierarchy'` |
@@ -356,12 +374,12 @@ Keywords (`WHERE`, `SELECT`) are case-insensitive.
 
 ### Predicate context
 
-The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression evaluated per node. Node fields (from `schemaData`) are accessible directly — e.g. `resolvedType`, `status`. `label` (relative file path, e.g. `"solutions/My Solution.md"`) and `title` are always available regardless of schema. Additionally, two pre-computed traversal arrays are available:
+The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression evaluated per node. Node fields (from `schemaData`) are accessible directly — e.g. `resolvedType`, `status`. `id` (e.g. `"solutions/My Solution.md"`) and `title` are always available regardless of schema. `resolvedParentIds` lists the `id` of each parent and `resolvedParentTitles` their titles. Additionally, two pre-computed traversal arrays are available:
 
 | Field | Description |
 |-------|-------------|
-| `ancestors[]` | Flat array of ancestor nodes, nearest first, deduplicated by title |
-| `descendants[]` | Flat array of descendant nodes, nearest first, deduplicated by title |
+| `ancestors[]` | Flat array of ancestor nodes, nearest first, deduplicated by `id` |
+| `descendants[]` | Flat array of descendant nodes, nearest first, deduplicated by `id` |
 
 Each entry in `ancestors[]` or `descendants[]` includes all schema fields of the target node, plus edge metadata:
 

package/docs/config.md

@@ -147,6 +147,14 @@ Maps file/frontmatter field names to canonical schema field names:
 - `templateDir` — directory containing template files (used by `template-sync` and excluded when parsing)
 - `templatePrefix` — filename prefix for templates (default blank)
 
+### `folderIndex`
+
+Names the pages that stand for their folder (see [Folder index](concepts.md#folder-index)). A page whose basename matches, case-insensitively, takes the containing folder's name as its `title` (eg `Project A/index.md` is parsed to `Project A`). An explicit `title:` still wins. A match at the space root keeps its basename. When empty or absent, titles come from the basename.
+
+```json
+{ "plugins": { "markdown": { "folderIndex": ["Overview", "index"] } } }
+```
+
 ### `typeInference`
 
 Automatically assigns a node type based on folder structure when no `type` field is present in frontmatter. Explicit `type:` always takes precedence.

package/docs/rules.md

@@ -84,7 +84,9 @@ Prefer choosing the right category and relying on its default. Set `severity` on
 
 ### Order within a rule
 
-A rule runs its parts in this order: `when`, then `expression`, then the `semantic` part. If the `expression` fails, the `semantic` part does not run on that node.
+A rule runs its parts in this order: `when`, then `expression`, then the `semantic` part. If the `expression` does not return `true`, the `semantic` part does not run on that node.
+
+A node with a [gating](#cascade-gating) violation from an `expression` has none of its `semantic` parts evaluated. A non-gating violation, such as `info`, does not stop them.
 
 An error in a `when` or `expression` is reported as a non-gating `error` violation.
 
@@ -105,8 +107,9 @@ Each evaluation receives:
 
 Useful resolved fields on nodes:
 - `resolvedType`
-- `resolvedParentTitle`
-- `resolvedParentTitles`
+- `id`: the node's unique key. Compare nodes by `id`, since titles may repeat.
+- `resolvedParentId`, `resolvedParentIds`: the `id` of the first parent, and of all parents
+- `resolvedParentTitle`, `resolvedParentTitles`: the display titles of the same parents
 
 Prefer `resolvedType` over raw `type` so aliases are handled correctly.
 
@@ -115,7 +118,7 @@ Prefer `resolvedType` over raw `type` so aliases are handled correctly.
 Inside `nodes[...]`, bare names refer to each candidate node. Use `$$` to reference outer variables:
 
 ```jsonata
-$count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution'])
+$count(nodes[resolvedParentId=$$.current.id and resolvedType='solution'])
 ```
 
 ### Common patterns
@@ -136,7 +139,7 @@ $not($exists(current.due)) or $toMillis(current.due) > $millis()
 $toMillis(current.stale_after) > $toMillis(current.generated.at)
 ```
 
-A datetime without an offset (`2026-07-01T00:00:00`) is read in the machine's local time zone, so require an offset with `format: "date-time"` when results must not depend on where validation runs. `$toMillis()` also needs seconds: it cannot parse a minute-precision datetime such as `2026-07-01T09:15`, which `format: "date-or-date-time"` accepts. A value `$toMillis()` cannot parse makes the rule fail.
+A datetime without an offset (`2026-07-01T00:00:00`) is read in the machine's local time zone, so require an offset with `format: "date-time"` when results must not depend on where validation runs. `$toMillis()` also needs seconds: it cannot parse a minute-precision datetime such as `2026-07-01T09:15`, which `format: "date-or-date-time"` accepts. A value `$toMillis()` cannot parse makes the expression fail.
 
 The same applies to [filter expressions](concepts.md#filter-expressions): compare dates with `$toMillis()`, not as strings.
 
@@ -168,27 +171,28 @@ Example override:
 ## Cascade gating
 
 When a schema uses `$metadata.hierarchy`, rule evaluation cascades top-down through the
-hierarchy tree (breadth-first from roots and orphans). A **gate** occurs when a node fails
-in a way that makes its descendants' rules untrustworthy or wasteful to run:
+hierarchy tree (breadth-first from roots and orphans). A **gate** occurs when a node has
+a violation that makes its descendants' rules untrustworthy or wasteful to run:
 
-- **Schema validation failure** on a node — always gates. The node's own rules are
+- **Schema validation error** on a node — always gates. The node's own rules are
   suppressed too, since its data is structurally invalid.
 - **Hierarchy structure violation** on a node (e.g. an invalid parent) — always gates the
   node's subtree, though the node's own rules still run.
-- **A rule failure with `gatesDescendants: true`** — gates the node's subtree, though the
-  failing node's own other rules still run.
+- **A gating rule violation** — a violation with `error` severity, or any violation of a rule with
+  `gatesDescendants: true`. It gates the node's subtree and skips the node's own semantic rules; its other
+  expressions still run.
 
 Gating exists so that expensive or semantic downstream rules (see [Semantic rules](semantic-rules.md)) aren't wasted
 evaluating nodes whose ancestors are already known-bad, and so noise doesn't drown out the
-actionable failure. It is per-subtree: once a node is gated, its descendants inherit the same
+actionable violation. It is per-subtree: once a node is gated, its descendants inherit the same
 gate (the original blocker), rather than each generating a new one. Cascade gating only applies to nodes within the
 hierarchy DAG.
 
-A rule has one `gatesDescendants` setting. It applies to whichever part failed, the `expression` or the `semantic` part. Its default comes from the severity of that failure: `true` for `error`, and `false` for `warning` and `info`. Set it explicitly when that default doesn't fit.
+A rule has one `gatesDescendants` setting. It applies to whichever part reported the violation, the `expression` or the `semantic` part. Its default comes from the severity of that violation: `true` for `error`, and `false` for `warning` and `info`. Set it explicitly when that default doesn't fit.
 
 ### Coverage output
 
-`sctx validate` reports gating as **coverage gates**: which node's failure (schema,
+`sctx validate` reports gating as **coverage gates**: which node's violation (schema,
 hierarchy, or a specific `ruleId`) suppressed rule evaluation, and the list of files gated
 as a result. This makes the validation "edge" visible — e.g. "this blocked goal means all
 opportunities beneath it were not evaluated" — for both human reading and agent consumption

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
@@ -35,12 +35,13 @@
     "clean": "rm -rf dist",
     "generate:schema-meta": "bun run scripts/generate-schema-meta.ts",
     "typecheck": "tsc --noEmit",
-    "build": "bun run clean && bun run generate:schema-meta && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && cp -r schemas dist/ && chmod +x dist/index.js",
+    "build": "bun run clean && bun run generate:schema-meta && tsc -p tsconfig.build.json && cp -r schemas dist/ && chmod +x dist/index.js",
     "prepublishOnly": "bun run build",
     "validate": "bun run src/index.ts validate",
     "diagram": "bun run src/index.ts diagram",
     "test": "bun test tests/",
     "test:smoke": "bun test smoke/",
+    "test:package": "bash scripts/test-package.sh",
     "test:judge": "SCTX_LIVE_JUDGE_TESTS=1 bun test tests/judge/live.test.ts",
     "test:models": "SCTX_MODEL_VALIDATION=1 bun test tests/judge/model-validation.test.ts",
     "test:hook": "bun test hook-test/unit/",
@@ -48,7 +49,7 @@
     "test:all": "bun test",
     "lint": "biome check",
     "lint:fix": "biome check --write",
-    "preversion": "bun run generate:schema-meta && bun run lint:fix && bun run test",
+    "preversion": "bun run generate:schema-meta && bun run lint:fix && bun run test && bun run test:package",
     "version": "bun run generate:schema-meta --release && git add -A",
     "postversion": "git push --follow-tags"
   },
@@ -57,8 +58,7 @@
     "@biomejs/biome": "^2.5.15",
     "@types/bun": "latest",
     "json-schema-to-ts": "^3.1.1",
-    "lefthook": "^2.1.9",
-    "tsc-alias": "^1.9.1"
+    "lefthook": "^2.1.9"
   },
   "peerDependencies": {
     "typescript": "^5"

package/schemas/_ost_strict.json

@@ -34,7 +34,7 @@
         "category": "best-practice",
         "description": "Explore multiple candidate solutions (aim for at least three) for the target opportunity",
         "type": "opportunity",
-        "expression": "(current.status != 'exploring' and current.status != 'active') or $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution']) >= 3"
+        "expression": "(current.status != 'exploring' and current.status != 'active') or $count(nodes[resolvedParentId=$$.current.id and resolvedType='solution']) >= 3"
       },
       {
         "id": "opportunity-customer-voice",