structured-context 0.13.1 → 0.14.0

package/dist/validate.js

@@ -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.1",
+  "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",

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",