structured-context 0.12.0 → 0.13.0

package/docs/config.md

@@ -1,4 +1,8 @@
-# structured-context Configuration Reference
+---
+title: "Configuration Reference"
+---
+
+# Configuration Reference
 
 ## Config file location
 
@@ -61,6 +65,71 @@ All plugin names must start with `sctx-` (the prefix is optional in config and n
 
 Plugins can also contribute schemas and partials via a `<pluginRoot>/schemas/` directory (or `"sctx": { "schemas": "..." }` in `package.json`). If a space specifies a plugin-prefixed schema (e.g. `"sctx-wardley-mapping/wardley_map.json"`), schemas are resolved statically without executing plugin code, and the plugin's code hooks are loaded when parsing or rendering.
 
+## Model providers and semantic rules
+
+structured-context evaluates [semantic rules](semantic-rules.md) with a **model provider**: a named definition that says which wire API to speak, which model to use and where. A provider definition combines an `api`, explicit values or environment-variable names, and the key source.
+
+**Bundled providers** work without any configuration: a fixed model per vendor chosen by this project, plus `-env` variants that also read the vendor's usual model and endpoint variables (`OPENAI_MODEL`, `OPENAI_BASE_URL`, `ANTHROPIC_MODEL`), falling back to the bundle's defaults where a variable is unset. Bundles without `-env` read no environment beyond the key: they behave the same on every machine.
+
+Run `sctx providers` for the authoritative list of bundled and configured providers with their effective API, endpoint, model and key variable. Keys are never shown. `bun run test:models` checks that each bundled model resolves on its endpoint.
+
+### Wire APIs and bundled-provider conventions
+
+A provider's `api` names the **request shape**, potentially supported by multiple vendors.
+
+| API | Shape | Bundled providers |
+|---|---|---|
+| `openrouter-decisions` | Decisions API, closed-set `choice` questions, answers with confidence and probabilities | `openrouter-jev`, `openrouter-openai-decisions` |
+| `typesafe-systemone` | Same decisions shape (currently) | `typesafe-jev` |
+| `openai-decisions` | OpenAI's Decisions API: same concept, its own request/response shape | `openai-decisions` |
+| `anthropic-messages` | Chat: structured JSON verdict | `anthropic`, `anthropic-haiku-5-5`, `anthropic-env` |
+| `openai-completions` | Chat: OpenAI-compatible; works with Ollama, vLLM and OpenRouter | `openai`, `openai-env`, `openrouter-openai` |
+
+Bundled provider names follow the pattern:
+
+- `<vendor>` — this project's recommended model for that vendor; can change between releases.
+- `<vendor>-<model>` (e.g. `anthropic-haiku-5-5`) — pins a model id, so it does not drift when the `<vendor>` bundle's recommendation moves.
+- `<vendor>-env` — hydrates model, endpoint etc from the vendor's usual environment variables.
+- `openrouter-<vendor>-<purpose>` (e.g. `openrouter-openai-decisions`) — aggregating vendor's endpoint variant
+
+**Configured providers** live in `modelProviders` at the top level, and replace a bundled provider of the same name. Fields a configured provider leaves out still take the API defaults:
+
+```json
+{
+  "modelProviders": {
+    "mine": { "api": "openrouter-decisions", "apiKeyEnv": "MY_JEV_KEY" },
+    "local": { "api": "openai-completions", "endpoint": "http://localhost:11434/v1" }
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `api` | **Required.** The wire API (see the table above and [Choosing a model provider](semantic-rules.md#choosing-a-model-provider)), or `fake` (for tests). |
+| `model` | A fixed model. Its default depends on the API. |
+| `modelEnv` | Environment variable holding a model override. An explicit `model` wins; a variable set but empty is an error. |
+| `endpoint` | A fixed API URL. |
+| `endpointEnv` | Environment variable holding an endpoint override. Same precedence as `modelEnv`. |
+| `apiKeyEnv` | The environment variable that holds the key. Defaults to the API's usual variable (see the table above). A local `openai-completions` endpoint can need no key. |
+| `apiKey` | The key itself. Use `apiKeyEnv` instead, so that keys stay out of config files. |
+
+Resolution per field: the explicit value wins, then the named environment variable, then the API default. Provider implementations read no environment; all hydration happens before one runs.
+
+The environment holds only keys and the variables a `-env` bundle names. No environment variable selects a provider.
+
+The top-level `semantic.provider` names the model provider that evaluates semantic rules: a bundled provider or an entry in `modelProviders`. A space can set its own `semantic`, which replaces the top-level one for that space, for example to keep a private space on a local model:
+
+```json
+{
+  "semantic": { "provider": "openrouter-jev" },
+  "spaces": [
+    { "name": "private-notes", "path": "/path/to/notes", "semantic": { "provider": "local" } }
+  ]
+}
+```
+
+Config does not turn semantic evaluation on. Each run asks for it with `--semantic`. `--semantic <provider>` also selects a different provider for that run.
+
 ## Markdown plugin config
 
 Set under `plugins.markdown` per space.

package/docs/rules.md

@@ -1,6 +1,15 @@
+---
+title: "Executable Rules"
+---
+
 # Executable Rules
 
-Rules are JSONata expressions in schema metadata (`$metadata.rules`). They run after structural JSON Schema validation and let you enforce cross-node checks and workflow constraints.
+Rules check content after JSON Schema validation, for example cross-node checks and workflow constraints. A schema declares rules in `$metadata.rules`. A rule has an `expression`, a `semantic` part, or both:
+
+- An **`expression`** is a JSONata test that must return `true`.
+- A **`semantic`** part asks a model to evaluate a node. See [Semantic rules](semantic-rules.md).
+
+A rule with neither is a schema error.
 
 For metadata structure and composition behavior, see [docs/schemas.md](schemas.md).
 
@@ -14,26 +23,13 @@ Rules are a flat array.
     "id": "active-outcome-count",
     "category": "workflow",
     "description": "Only one outcome should be active at a time",
-    "scope": "global",
-    "check": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
+    "global": true,
+    "expression": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
   }
 ]
 ```
 
-| Field | Required | Description |
-|---|---|---|
-| `id` | yes | Unique rule identifier |
-| `category` | yes | `validation` \| `coherence` \| `workflow` \| `best-practice` |
-| `severity` | no | `error` \| `warning` \| `info`; overrides the category default (see [Severity](#severity)) |
-| `description` | yes | Human-readable rule intent |
-| `check` | yes | JSONata expression; must evaluate to `true` |
-| `type` | no | Restrict rule to nodes of this `resolvedType` |
-| `scope` | no | Use `"global"` to evaluate once for the whole space |
-| `override` | no | Only for merge conflicts: allows later duplicate `id` to replace earlier |
-
-## Categories and severity
-
-Categories describe a rule's intent and supply its default severity. They do not change expression execution semantics.
+Every rule has a category, which describes its intent and supplies a default severity.
 
 | Category | Typical use | Default severity |
 |---|---|---|
@@ -42,9 +38,7 @@ Categories describe a rule's intent and supply its default severity. They do not
 | `workflow` | Process/operating-discipline checks | `warning` |
 | `best-practice` | Advisory quality checks | `info` |
 
-### Severity
-
-Every rule violation is reported with a severity:
+Severity can also be set per rule. It applies to a failed `expression` and to the default `fail` verdict of a [semantic rule](semantic-rules.md#severity).
 
 | Severity | Meaning | Fails validation |
 |---|---|---|
@@ -63,25 +57,42 @@ Prefer choosing the right category and relying on its default. Set `severity` on
   "severity": "error",
   "description": "Goals must not be left blocked",
   "type": "goal",
-  "check": "current.status != 'blocked'"
+  "expression": "current.status != 'blocked'"
 }
 ```
 
 `sctx schemas show` lists each category with its default severity and marks rules that override it.
 
-### Output
+## Selecting nodes
 
-- **`sctx validate`** — the summary counts rule violations per severity, and details are grouped by severity with each line showing the rule's category and id.
-- **`sctx validate --json`** — `errors` includes only `error` severity rule violations (keyed `rule:<id>`, with a `severity` field). A `ruleViolations` array lists every violation with `file`, `ruleId`, `category`, `severity` and `description` (`file` is empty for global rules).
-- **`sctx validate-file`** — `error` severity violations appear under `errors`; `warning` and `info` violations appear under `warnings`. Rule entries carry a `severity` field.
+- A rule with `global: true` runs once for the space. It needs an `expression`, and it cannot have `when`, `type` or `semantic`.
+- Other rules run once for each node.
+- `type` limits a rule to nodes with that `resolvedType`.
+- `when` limits a rule to nodes where the applicability condition returns `true`. See [Conditional rules](#conditional-rules-when).
+
+### Conditional rules (`when`)
+
+`when` is the rule's applicability condition: a JSONata test that determines whether a rule applies to a node. It has the same context as `expression` and runs before it. Use `when` when `type` cannot select the nodes a rule applies to:
+
+```json
+{ "id": "ready-has-owner", "category": "workflow", "type": "task",
+  "description": "Ready tasks have an owner",
+  "when": "current.status = 'ready'", "expression": "$exists(current.owner)" }
+```
+
+`when` costs almost nothing, so use it to stop an expensive rule from running where it does not apply. For a semantic rule, this saves a model call on each node that `when` excludes.
+
+### 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.
 
-## Evaluation model
+An error in a `when` or `expression` is reported as a non-gating `error` violation.
 
-- Rules with `scope: "global"` run once.
-- Other rules run per applicable node.
-- If `type` is set, only nodes with matching `resolvedType` are evaluated.
+## Writing expressions
 
-## Expression context
+An `expression` (and `when`) is JSONata. This section covers what an expression can see and how to write expressions.
+
+### Expression context
 
 Each evaluation receives:
 
@@ -99,7 +110,7 @@ Useful resolved fields on nodes:
 
 Prefer `resolvedType` over raw `type` so aliases are handled correctly.
 
-## Predicate scoping (`$$`)
+### Predicate scoping (`$$`)
 
 Inside `nodes[...]`, bare names refer to each candidate node. Use `$$` to reference outer variables:
 
@@ -107,9 +118,33 @@ Inside `nodes[...]`, bare names refer to each candidate node. Use `$$` to refere
 $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution'])
 ```
 
-## Reusing rules
+### Common patterns
+
+```jsonata
+$exists(current.metric) = true
+$count(current.sources) >= 1
+$count(nodes[resolvedType='outcome' and status='active']) <= 1
+current.status != 'active' or $exists(parent) = false or parent.status = 'active'
+```
+
+#### Dates and times
+
+Dates and datetimes reach rules as ISO 8601 strings. Convert with `$toMillis()` to compare them, including date against datetime, and use `$millis()` for the current time:
+
+```jsonata
+$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.
+
+The same applies to [filter expressions](concepts.md#filter-expressions): compare dates with `$toMillis()`, not as strings.
+
+## Sharing rules
 
-To share rules, put them in a schema's `$metadata.rules` and list that schema's `$id` in `$metadata.imports`. An import brings the whole schema's metadata, including its own imports:
+To share rules, put them in a schema's `$metadata.rules` and list that schema's `$id` in `$metadata.imports`. An import brings the whole schema's metadata, including its own imports. Merged rules combine by `id`; a duplicate `id` is an error, and a later rule replaces an earlier one only with `override: true`.
+
+### Overriding rules
 
 ```json5
 "$metadata": {
@@ -117,13 +152,6 @@ To share rules, put them in a schema's `$metadata.rules` and list that schema's
 }
 ```
 
-## Merge and conflict behavior
-
-When metadata is merged from imports (imports in order, then the schema's own metadata):
-- Rules are merged by `id`.
-- A duplicate `id` is an error.
-- A later rule may replace an earlier one only with `override: true`.
-
 Example override:
 
 ```json5
@@ -132,16 +160,79 @@ Example override:
   "override": true,
   "category": "workflow",
   "description": "Require exactly one active outcome",
-  "scope": "global",
-  "check": "$count(nodes[resolvedType='outcome' and status='active']) = 1"
+  "global": true,
+  "expression": "$count(nodes[resolvedType='outcome' and status='active']) = 1"
 }
 ```
 
-## Common patterns
+## 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:
+
+- **Schema validation failure** 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.
+
+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
+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.
+
+### Coverage output
+
+`sctx validate` reports gating as **coverage gates**: which node's failure (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
+(JSON output via `--json`, under `coverageGates`).
+
+Use `--include-gated` to evaluate rules on gated nodes anyway (still reported as gated) —
+useful for surfacing cheap, bottom-up checks (e.g. orphan detection, content quality) that
+don't depend on an ancestor being valid.
+
+### Single-file validation
+
+`sctx validate-file <path>` applies the same gating as `sctx validate`, so a file's rule results match its entry in a full run.
+
+- Expressions are evaluated for the whole space; the output is restricted to the file.
+- Semantic parts are evaluated only for the file and its gating ancestors (see [Semantic rules](semantic-rules.md#how-semantic-evaluation-works)).
+- If the file is gated, its rules are skipped and a `gated:<file>` entry under `warnings` names the blocker, so a gated file doesn't read as clean. `--include-gated` evaluates the file's rules anyway.
+
+## Controlling validation runs
+
+These options restrict which rules run, without changing rule definitions.
+
+### Filtering rules
+
+`--rule-filter <dimension>=<value>[,<value>]` runs only the rules that match. It works on `sctx validate` and `sctx validate-file`.
+
+- Dimensions: `category`, `severity`, `type` and `id`.
+- Values in one dimension combine with OR. Repeat the option to add a dimension; dimensions combine with AND.
+- A rule matches each severity that it can report, including the severities in a semantic verdict map.
+- Gating comes only from the rules that ran.
+
+For example, `--rule-filter category=workflow,coherence --rule-filter severity=error` runs only workflow and coherence rules that can report an error.
+
+### Depth-limited evaluation
+
+`--depth <n>` restricts validation to hierarchy nodes within `n` breadth-first levels from
+the top (roots and orphans are depth 1). This is a manual, coarser control than cascade
+gating — intended for staged workflows (e.g. an agent fixes the top level, then requests
+the next). Excluded nodes are reported under `skippedByDepth`, separate from gated nodes.
+
+## Output
+
+- **`sctx validate`** — the summary counts rule violations per severity, and details are grouped by severity with each line showing the rule's category and id.
+- **`sctx validate --json`** — `errors` includes only `error` severity rule violations (keyed `rule:<id>`, with a `severity` field). A `ruleViolations` array lists every violation with `file`, `ruleId`, `category`, `severity` and `description` (`file` is empty for global rules). A violation from a failed `expression` has the evidence `expression failed: <expression>` when the rule also has a `semantic` part, and no verdict.
+- **`sctx validate-file`** — `error` severity violations appear under `errors`; `warning` and `info` violations appear under `warnings`. Rule entries carry a `severity` field.
+
+Gated files: see [Single-file validation](#single-file-validation).
 
-```jsonata
-$exists(current.metric) = true
-$count(current.sources) >= 1
-$count(nodes[resolvedType='outcome' and status='active']) <= 1
-current.status != 'active' or $exists(parent) = false or parent.status = 'active'
-```

package/docs/schemas.md

@@ -1,3 +1,7 @@
+---
+title: "Schemas"
+---
+
 # Schemas
 
 This document explains schema usage, metadata shape, and composition semantics in `structured-context`.
@@ -53,13 +57,31 @@ Main types:
 
 This schema reuses shared structural defs from partials via `$ref` and imports its hierarchy and rules from `_ost_strict` via `$metadata.imports`.
 
+### `knowledge_wiki.json`
+
+Flat, LLM-maintained knowledge base (after Karpathy's LLM Wiki pattern). No hierarchy or required parent links; wikilinks between any pages are valid. Validates structure and provenance, not meaning.
+
+Main types:
+- `source`
+- `concept`
+- `entity`
+- `synthesis`
+- `note`
+- `index`
+
+### `okf.json`
+
+[Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) (OKF v0.2) bundles, validated as plain markdown spaces. Any concept `type` is accepted and unknown fields are tolerated; provenance (`sources`), trust (`generated`, `verified`), lifecycle (`status`, `stale_after`) and the Attested Computation contract are checked when present. An Attested Computation needs its computation: a `computation` field, or a `# Computation` section in the body (found by matching that line in the body text, so a `# Computation` line inside a code fence also counts). Reserved `index.md` and `log.md` are reported as excluded during parsing.
+
 ## Custom format annotations
 
 `structured-context` registers the following `format` annotations beyond standard JSON Schema. All apply to `string` properties and are validated at schema validation time.
 
 | Format | Validates | Example |
 |--------|-----------|---------|
-| `date` | ISO 8601 date (`YYYY-MM-DD`) | `"2026-03-31"` |
+| `date` | ISO 8601 calendar date (`YYYY-MM-DD`) | `"2026-03-31"` |
+| `date-time` | ISO 8601 datetime with seconds and a UTC offset (`Z` or `±HH:MM`) | `"2026-03-31T09:15:00+10:00"` |
+| `date-or-date-time` | A date, or a datetime where seconds and offset are optional (as Obsidian's datetime property writes) | `"2026-03-31"`, `"2026-03-31T09:15"`, `"2026-03-31T09:15:00Z"` |
 | `path` | Non-empty filesystem path — absolute, relative, or a plain name | `"notes"`, `"./subdir/file.md"`, `"/abs/path"` |
 | `wikilink` | Obsidian wikilink syntax (`[[...]]`) | `"[[Parent Node]]"` |
 
@@ -75,15 +97,16 @@ Using `format` directly is more concise when the full definition isn't needed:
 { "type": "string", "format": "wikilink" }
 ```
 
-### Date coercion
+### Dates and datetimes
 
-YAML parsers (gray-matter, js-yaml) coerce unquoted ISO dates to JavaScript `Date` objects:
+The markdown plugin reads frontmatter and embedded YAML blocks without YAML's timestamp type, so unquoted dates and datetimes stay as the strings written, at any depth (including inside lists):
 
 ```yaml
-published_date: 2026-03-31   # parsed as a Date object by gray-matter
+published_date: 2026-03-31          # "2026-03-31"
+updated: 2026-06-20T22:53:05+10:00  # "2026-06-20T22:53:05+10:00", offset kept
 ```
 
-The markdown plugin automatically coerces `Date` objects to `YYYY-MM-DD` strings before validation, so unquoted dates in frontmatter and embedded YAML blocks work correctly with `format: "date"` fields.
+Validate them with `format: "date"` or `format: "date-time"` when a field needs one precision, or `format: "date-or-date-time"` to accept either, and compare them in rules with JSONata's `$toMillis()` (see [Rules](rules.md#dates-and-times)).
 
 ## Metadata dialect
 
@@ -116,8 +139,8 @@ Top-level metadata shape:
         "id": "active-outcome-count",
         "category": "workflow",
         "description": "Only one outcome should be active at a time",
-        "scope": "global",
-        "check": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
+        "global": true,
+        "expression": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
       }
     ]
   }
@@ -136,7 +159,7 @@ Top-level metadata shape:
 | `hierarchy.allowSkipLevels` | `boolean` | Optional; allows parent to be any ancestor level |
 | `relationships` | `Relationship[]` | Optional; defines related node links outside the primary hierarchy. A relationship may set `override: true` |
 | `aliases` | `Record<string, string \| { type, override }>` | Optional type alias map. Use `{ "type": "goal", "override": true }` to replace an imported alias |
-| `rules` | `Rule[]` | Optional flat rule array |
+| `rules` | `Rule[]` | Optional flat rule array. A rule has an `expression` (a JSONata test), a `semantic` part (evaluated by a model against a rubric), or both; see [Rules](rules.md) |
 
 ### Relationships
 
@@ -148,9 +171,9 @@ Relationships define links between node types that are not part of the primary s
 | `type` | `string` | **Required** | The child's canonical type name |
 | `field` | `string` | `"parent"` | The frontmatter field that holds the wikilink(s) for this relationship |
 | `fieldOn` | `string` | `"child"` | `"child"` (child holds a link to parent) or `"parent"` (parent holds an array of child links) |
-| `format` | `string` | `"page"` | Hint for `template-sync`: `"table"`, `"list"`, or `"heading"` |
+| `templateFormat` | `string` | `"page"` | Hint for `template-sync`: `"table"`, `"list"`, or `"heading"` |
 | `matchers` | `string[]` | `[]` | Heading text to match (strings or `/regex/`). Case-insensitive. |
-| `embeddedTemplateFields` | `string[]` | `[]` | Field names to include in templates when `format` is `"table"` |
+| `embeddedTemplateFields` | `string[]` | `[]` | Field names to include in templates when `templateFormat` is `"table"` |
 | `multiple` | `boolean` | `true` | Whether multiple children are expected |
 
 **`fieldOn: "child"` (default)** — child node has a field pointing to its parent. Embedded parsing sets this field on each child node; validation checks that it resolves to a node of the declared parent type.
@@ -164,7 +187,7 @@ Relationships define links between node types that are not part of the primary s
   {
     "parent": "opportunity",
     "type": "assumption",
-    "format": "table",
+    "templateFormat": "table",
     "matchers": ["Assumptions", "/assum.*/"],
     "embeddedTemplateFields": ["assumption", "status", "confidence"]
   }
@@ -180,7 +203,7 @@ Relationships define links between node types that are not part of the primary s
     "type": "task",
     "field": "tasks",
     "fieldOn": "parent",
-    "format": "list",
+    "templateFormat": "list",
     "matchers": ["Tasks"],
     "multiple": true
   }
@@ -199,7 +222,7 @@ With this configuration, embedded task items under an Activity's "Tasks" heading
 | `multiple` | `false` | Field contains array of wikilinks |
 | `selfRef` | `false` | Allows same-type parent |
 | `selfRefField` | _undefined_ | Separate field for same-type parent links |
-| `format` | _undefined_ | Embedding hint: `"list"`, `"table"`, or `"heading"` — enables hierarchy embedding when set |
+| `templateFormat` | _undefined_ | Embedding hint: `"list"`, `"table"`, or `"heading"` — enables hierarchy embedding when set |
 | `matchers` | _undefined_ | Heading text patterns (strings or `/regex/`) to detect embedding sections |
 | `embeddedTemplateFields` | _undefined_ | Column/field names for table stubs generated by `template-sync` |
 
@@ -208,7 +231,7 @@ String shorthand (`"goal"`) normalizes to:
 
 ### Hierarchy embedding
 
-When a hierarchy level has `format` and `matchers`, it participates in **hierarchy embedding** — the same section-based parsing used for relationships. Two patterns are supported:
+When a hierarchy level has `templateFormat` and `matchers`, it participates in **hierarchy embedding** — the same section-based parsing used for relationships. Two patterns are supported:
 
 **Child-level embedding** — a typed-page heading signals that following content should produce nodes of the child type (next level in hierarchy):
 
@@ -219,7 +242,7 @@ When a hierarchy level has `format` and `matchers`, it participates in **hierarc
     "type": "opportunity",
     "field": "parent",
     "fieldOn": "child",
-    "format": "list",
+    "templateFormat": "list",
     "matchers": ["Opportunities", "User Opportunities"]
   }
 ]
@@ -261,6 +284,8 @@ With this config, an application page may include `### capability` with wikilink
 - [[Zephyr]]             ← populates application.tools (fieldOn: parent)
 ```
 
+A node's body becomes its `content`; see [Node content](concepts.md#node-content).
+
 ## Composition and merge semantics
 
 `$ref` and `$defs` are for **validation only**: a `$ref` to another schema (or to one of its `$defs`) reuses its JSON Schema definitions but brings none of its `$metadata`.
@@ -344,8 +369,8 @@ How hierarchies are used:
         "override": true,
         "category": "workflow",
         "description": "Require exactly one active outcome",
-        "scope": "global",
-        "check": "$count(nodes[resolvedType='outcome' and status='active']) = 1"
+        "global": true,
+        "expression": "$count(nodes[resolvedType='outcome' and status='active']) = 1"
       }
     ]
   }
@@ -373,7 +398,7 @@ Every schema `$id` uses the `sctx://` scheme. The shape of the `$id` says where
 - `$id` values follow the [namespace rules](#schema-id-namespaces) and must not collide across bundled, plugin and local schemas.
 - `$ref` resolution is transitive across files.
 - Partials with no `$metadata` should prefer `$schema: "https://json-schema.org/draft/2020-12/schema"` so they validate standalone as plain JSON Schema fragments.
-- **Bundled partials as entity libraries**: `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, and `_ost_strict.json` provide reusable entity definitions and metadata. Composing schemas can reference their entity types via `$ref` rather than redefining them.
+- **Bundled partials as entity libraries**: `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, `_okf.json`, and `_ost_strict.json` provide reusable entity definitions and metadata. Composing schemas can reference their entity types via `$ref` rather than redefining them.
 - **Partials can carry metadata**: Partials may include `$metadata` (hierarchy, aliases, relationships, rules). A schema gets it only by listing the partial in `$metadata.imports`; `$ref` alone brings none.
 
 ## Plugin-contributed schemas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
@@ -41,6 +41,8 @@
     "diagram": "bun run src/index.ts diagram",
     "test": "bun test tests/",
     "test:smoke": "bun test smoke/",
+    "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/",
     "test:hook:e2e": "bun test hook-test/hooks.test.ts",
     "test:all": "bun test",
@@ -52,9 +54,8 @@
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.191",
-    "@biomejs/biome": "^2.5.1",
+    "@biomejs/biome": "^2.5.15",
     "@types/bun": "latest",
-    "@types/js-yaml": "^4.0.9",
     "json-schema-to-ts": "^3.1.1",
     "lefthook": "^2.1.9",
     "tsc-alias": "^1.9.1"
@@ -65,10 +66,10 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "chokidar": "^5.0.0",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.4.3",
     "json5": "^2.2.3",
     "jsonata": "^2.2.1",
     "mdast-util-to-string": "^4.0.0",

package/schemas/_knowledge_wiki.json

@@ -50,14 +50,14 @@
         "category": "coherence",
         "description": "Syntheses should reference at least one contributing source in their sources array",
         "type": "synthesis",
-        "check": "$exists(current.sources) and $count(current.sources) >= 1"
+        "expression": "$exists(current.sources) and $count(current.sources) >= 1"
       },
       {
         "id": "concept-has-summary",
         "category": "best-practice",
         "description": "Concept pages should have a short summary for index discoverability",
         "type": "concept",
-        "check": "$exists(current.summary) and $length(current.summary) > 0"
+        "expression": "$exists(current.summary) and $length(current.summary) > 0"
       }
     ]
   },
@@ -89,7 +89,7 @@
         },
         "published_date": {
           "type": "string",
-          "format": "date",
+          "format": "date-or-date-time",
           "description": "Original publication date"
         },
         "source_type": {
@@ -213,7 +213,7 @@
         "type": { "const": "note" },
         "date": {
           "type": "string",
-          "format": "date",
+          "format": "date-or-date-time",
           "description": "Date this entry was created or relates to"
         }
       },