structured-context 0.10.0 → 0.12.0

package/docs/concepts.md

@@ -93,6 +93,8 @@ 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 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.
+
 > `space_on_a_page` and `dashboard` are not `space node` types — they are `tooling types`.
 
 ### Embedded node
@@ -111,7 +113,7 @@ A `space node`'s resolved type (`resolvedType`) is its canonical type after alia
 
 ## Typed page
 
-A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`.
+A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`. Body content appearing before any embedded headings (or the entire body when no embedded headings are present) is preserved as the page node's `content`.
 
 Typed pages are distinct from `space on a page` files: a typed page *is* a `space node`; a `space_on_a_page` file is merely a container.
 
@@ -123,7 +125,7 @@ A **schema** defines the valid structure for nodes in a `space`: the fields, typ
 
 The schema handles structural validation. Cross-node and workflow checks are handled by executable `rules` defined in `$metadata.rules`.
 
-Schemas are composable: structural definitions and metadata can be sourced across `$ref` graphs, then merged deterministically (root metadata applied last, single hierarchy provider, aliases merged, rules merged by `id` with explicit override semantics).
+Schemas are composable. Structural definitions are reused with `$ref` (validation only). Metadata is reused only by listing schema `$id`s in `$metadata.imports`: imports merge transitively, in order, with the schema's own metadata last. Hierarchies, relationships, aliases and rules all follow one rule — a duplicate is an error unless the later entry sets `override: true` — and each declared hierarchy is kept as a separate named hierarchy.
 
 ### Rules
 
@@ -141,6 +143,8 @@ Rules may be:
 
 Rules are distinct from schema validation: the schema checks structure; rules check meaning and quality.
 
+Each executable rule has a **category** (`validation`, `coherence`, `workflow`, `best-practice`) that supplies its default **severity** (`error`, `warning`, `info`). A rule may override its category's severity, but categories are the preferred grouping. Only `error` severity violations fail validation.
+
 See [docs/rules.md](rules.md) for the rules reference, including JSONata expression syntax and the full `$metadata` field reference.
 
 ---
@@ -160,6 +164,10 @@ The **hierarchy** is the ordered list of node types in a space, from root to lea
 
 The hierarchy is modelled as a layered DAG: a non-root node may have zero parents (orphaned), one parent, or multiple parents. The `show` command renders this as an indented tree, marking repeated nodes with `(*)` where the subtree is already shown elsewhere.
 
+A space may have **several hierarchies**, one for each imported schema that declares one. Each hierarchy has a **name** (defaulting to the declaring schema's file stem), and each type belongs to at most one hierarchy. Structural validation runs per hierarchy; relationships may connect types across hierarchies.
+
+The **main hierarchy** is the one declared by the root schema; failing that, the only imported hierarchy; failing that, the one the root selects with `"hierarchy": { "$ref": ... }`. The main hierarchy drives `space on a page` parsing, hierarchy embedding, template sync, and default rendering. `show`, `diagram` and `render` take `--hierarchy <name>` to render another. See [docs/schemas.md](schemas.md#multiple-hierarchies).
+
 Each non-root level uses the shared `field`, `fieldOn`, and `multiple` edge options (see [Graph edges](#graph-edges)). Hierarchy-specific options:
 
 | Option | Default | Meaning |
@@ -250,9 +258,33 @@ Each entry is a `ResolvedParentRef` object:
 | `title` | `string` | The parent node's title |
 | `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'` |
 | `selfRef` | `boolean` | Whether the edge is a same-type (self-referential) parent link |
 
-The `source` label lets downstream consumers distinguish edge types without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set.
+The `source` and `hierarchy` labels let downstream consumers distinguish edge types and hierarchies without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks within their own hierarchy (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set.
+
+### Content links
+
+**Content links** (`resolvedLinks` on `SpaceNode`) are all links extracted from a node's content at parse time — both from frontmatter non-edge fields and from the body text. They are distinct from graph edges: they are never used to infer structure, but are available to consumers for rendering, auditing, or navigation.
+
+Each entry is a `ResolvedContentLink` object:
+
+| Field | Type | Description |
+|---|---|---|
+| `text` | `string` | Display text of the link |
+| `target` | `string` | Raw link target (URL or wikilink path) |
+| `action` | `'link' \| 'embed'` | Whether the link navigates or transcludes |
+| `anchor` | `string?` | Fragment component (heading or block ref) if present |
+| `location` | `'node' \| 'internal' \| 'external' \| 'system' \| 'protocol'` | Resolved location classification |
+
+**Location classification:**
+- `node` — wikilink resolved to a known space node
+- `internal` — wikilink or relative path to an in-source target that is not a space node
+- `external` — `http://` or `https://` URL
+- `system` — `file://` URL
+- `protocol` — any other scheme (e.g. `obsidian://`)
+
+**Sources:** Both wikilink syntax (`[[Target]]`, `![[Image]]`) and markdown link syntax (`[text](url)`, `![alt](url)`) are extracted. Bare URLs in frontmatter string fields are also captured. Graph edge fields (hierarchy `parent`, relationship fields) are excluded — those are graph edges, not content links.
 
 ### Anchor
 
@@ -292,7 +324,8 @@ Each entry in `ancestors[]` or `descendants[]` includes all schema fields of the
 | Metadata field | Type | Description |
 |----------------|------|-------------|
 | `_field` | `string` | The edge field name that connects to this ancestor/descendant |
-| `_source` | `'hierarchy' \| 'relationship'` | Whether the edge came from the hierarchy or a relationship |
+| `_source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy or a relationship |
+| `_hierarchy` | `string` | Hierarchy name; present only for hierarchy edges |
 | `_selfRef` | `boolean` | Whether the edge is a same-type (self-referential) link |
 
 ### SELECT spec

package/docs/config.md

@@ -26,8 +26,16 @@ A space is a named directory or single file registered in the config. Example:
 }
 ```
 
+**`schema`** — the schema used to validate nodes in the space. Can be:
+- A bundled schema name (e.g. `strategy_general.json`, `strict_ost.json`)
+- A local path relative to the config file (e.g. `./schemas/custom.json`) or absolute path
+- A plugin schema prefixed with the plugin name (e.g. `sctx-wardley-mapping/wardley_map.json` or `wardley-mapping/wardley_map.json`). Specifying a plugin-prefixed schema automatically loads that plugin for the space.
+- A simple filename (e.g. `wardley_map.json`) provided by a plugin explicitly declared under `plugins`.
+
 **`includeSpacesFrom`** — import space definitions from other config files. Useful for aggregating spaces from multiple projects into a central config. Duplicate space names are not allowed.
 
+A config must define at least one of `spaces` or `includeSpacesFrom`. When using `includeSpacesFrom` alone, `spaces` can be omitted entirely.
+
 ## Plugins
 
 Use `plugins` to load parse plugins that read spaces from non-markdown sources. The built-in markdown plugin is always available without any declaration. Plugins are tried in order; the first to return a result wins. The `plugins` field is a map of plugin name to plugin config, and can be declared at the top level (applies to all spaces) or per-space (overrides the top level):
@@ -51,6 +59,8 @@ Use `plugins` to load parse plugins that read spaces from non-markdown sources.
 
 All plugin names must start with `sctx-` (the prefix is optional in config and normalised on load). The special name `markdown` refers to the built-in markdown plugin. External plugins are resolved in order: config-adjacent (`{configDir}/plugins/{name}`), then npm. Each plugin must export a `configSchema` JSON Schema; config is validated against it on load. Fields annotated `format: 'path'` in a plugin's `configSchema` are resolved relative to the config file directory.
 
+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.
+
 ## Markdown plugin config
 
 Set under `plugins.markdown` per space.

package/docs/rules.md

@@ -24,22 +24,56 @@ Rules are a flat array.
 |---|---|---|
 | `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
+## Categories and severity
 
-Categories label violations for reporting. They do not change expression execution semantics.
+Categories describe a rule's intent and supply its default severity. They do not change expression execution semantics.
 
-| Category | Typical use |
-|---|---|
-| `validation` | Hard correctness constraints |
-| `coherence` | Cross-node consistency checks |
-| `workflow` | Process/operating-discipline checks |
-| `best-practice` | Advisory quality checks |
+| Category | Typical use | Default severity |
+|---|---|---|
+| `validation` | Hard correctness constraints | `error` |
+| `coherence` | Cross-node consistency checks | `warning` |
+| `workflow` | Process/operating-discipline checks | `warning` |
+| `best-practice` | Advisory quality checks | `info` |
+
+### Severity
+
+Every rule violation is reported with a severity:
+
+| Severity | Meaning | Fails validation |
+|---|---|---|
+| `error` | Content is wrong | yes |
+| `warning` | Content is likely inconsistent or incomplete | no |
+| `info` | Content could be better | no |
+
+Only `error` violations fail validation: `sctx validate` and `sctx validate-file` exit non-zero, and JSON output reports `valid: false`. Warnings and info violations are reported but don't fail, so a work-in-progress space can still pass while advisory checks remain visible.
+
+Prefer choosing the right category and relying on its default. Set `severity` on an individual rule only when that rule genuinely differs from the rest of its category:
+
+```json5
+{
+  "id": "goal-not-blocked",
+  "category": "workflow",
+  "severity": "error",
+  "description": "Goals must not be left blocked",
+  "type": "goal",
+  "check": "current.status != 'blocked'"
+}
+```
+
+`sctx schemas show` lists each category with its default severity and marks rules that override it.
+
+### 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).
+- **`sctx validate-file`** — `error` severity violations appear under `errors`; `warning` and `info` violations appear under `warnings`. Rule entries carry a `severity` field.
 
 ## Evaluation model
 
@@ -73,28 +107,21 @@ Inside `nodes[...]`, bare names refer to each candidate node. Use `$$` to refere
 $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution'])
 ```
 
-## Rule imports (`$ref`)
+## Reusing rules
 
-`$metadata.rules` can include `$ref` entries that import:
-- one rule
-- a rule-set object with `rules: []`
-
-Example:
+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:
 
 ```json5
-"rules": [
-  { "$ref": "sctx://rule-pack#/$defs/workflowRule" },
-  { "$ref": "sctx://rule-pack#/$defs/coreRuleSet" }
-]
+"$metadata": {
+  "imports": ["sctx://_rule-pack"]
+}
 ```
 
-Imported entries are normalized into the same flat runtime list.
-
 ## Merge and conflict behavior
 
-When metadata is composed across `$ref`:
+When metadata is merged from imports (imports in order, then the schema's own metadata):
 - Rules are merged by `id`.
-- Different payloads for the same `id` are an error by default.
+- A duplicate `id` is an error.
 - A later rule may replace an earlier one only with `override: true`.
 
 Example override:

package/docs/schemas.md

@@ -6,7 +6,7 @@ This document explains schema usage, metadata shape, and composition semantics i
 
 A **schema** defines the valid structure for nodes in a `space`: entity types, field constraints, hierarchy behavior, type aliases, and executable rules.
 
-`structured-context` uses JSON Schema Draft-07 plus a custom top-level `$metadata` keyword.
+`structured-context` uses JSON Schema 2020-12 plus a custom top-level `$metadata` keyword.
 
 ## Selecting a schema
 
@@ -20,6 +20,11 @@ Set `schema` in the space config entry:
 }
 ```
 
+A schema can be specified as:
+- **Bundled schema**: simple filename like `strategy_general.json` or `strict_ost.json`.
+- **Local file**: relative path starting with `./` or `../` (resolved against config file directory), or absolute path.
+- **Plugin schema**: prefixed with the plugin name, e.g. `sctx-wardley-mapping/wardley_map.json` or `wardley-mapping/wardley_map.json`. When prefixed, structured-context automatically loads the plugin for that space. Alternatively, if the plugin is already declared under `plugins`, the simple filename (e.g. `wardley_map.json`) resolves directly from that plugin.
+
 Resolution order: space `schema` > global `schema`. Schema resolution fails if none is configured.
 
 ## Bundled schemas
@@ -46,7 +51,7 @@ Main types:
 - `solution`
 - `assumption_test`
 
-This schema composes shared structural defs and strict metadata/rules from partials.
+This schema reuses shared structural defs from partials via `$ref` and imports its hierarchy and rules from `_ost_strict` via `$metadata.imports`.
 
 ## Custom format annotations
 
@@ -61,7 +66,7 @@ This schema composes shared structural defs and strict metadata/rules from parti
 `path` and `wikilink` are also available as shared `$ref` definitions in `_sctx_base.json`:
 
 ```json
-{ "$ref": "sctx://_sctx_base#/$defs/wikilink" }
+{ "$ref": "sctx://core/_sctx_base#/$defs/wikilink" }
 ```
 
 Using `format` directly is more concise when the full definition isn't needed:
@@ -82,9 +87,12 @@ The markdown plugin automatically coerces `Date` objects to `YYYY-MM-DD` strings
 
 ## Metadata dialect
 
-Schemas use this metaschema URL:
+The dialect is JSON Schema 2020-12 plus the top-level `$metadata` keyword. Schemas set `$schema` to the metaschema URL:
+
+- `https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json` follows the newest dialect.
+- `https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/<version>/_structured_context_schema_meta.json` pins the dialect to the structured-context release that first shipped it. Versioned files never change once released. Releases that don't change the dialect add no folder, so a version number only appears when the dialect changed.
 
-- `https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json`
+Because the dialect is 2020-12, keywords may sit beside `$ref`, and `unevaluatedProperties: false` can close an object composed through `allOf`.
 
 Top-level metadata shape:
 
@@ -120,11 +128,14 @@ Top-level metadata shape:
 
 | Field | Type | Notes |
 |---|---|---|
-| `hierarchy` | object | Optional per provider; at most one provider may define it after composition |
+| `imports` | `string[]` | Optional; `$id`s of schemas whose metadata is merged into this one. See [Composition and merge semantics](#composition-and-merge-semantics) |
+| `hierarchy` | object | Optional; declares this schema's hierarchy, or (root schema only) selects the main hierarchy with `{ "$ref": "<schema $id>#/$metadata/hierarchy" }`. See [Multiple hierarchies](#multiple-hierarchies) |
+| `hierarchy.name` | `string` | Optional short name; defaults to the declaring schema's file stem |
+| `hierarchy.override` | `boolean` | Optional; replaces an imported hierarchy with the same name |
 | `hierarchy.levels` | `(string \| HierarchyLevel)[]` | Ordered root→leaf types |
 | `hierarchy.allowSkipLevels` | `boolean` | Optional; allows parent to be any ancestor level |
-| `relationships` | `Relationship[]` | Optional; defines related node links outside the primary hierarchy |
-| `aliases` | `Record<string, string>` | Optional type alias map |
+| `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 |
 
 ### Relationships
@@ -252,37 +263,75 @@ With this config, an application page may include `### capability` with wikilink
 
 ## Composition and merge semantics
 
-Metadata is composed across the `$ref` graph with deterministic behavior:
+`$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`.
+
+Metadata travels only through **`$metadata.imports`**, a list of schema `$id`s:
+
+```json5
+"$metadata": {
+  "imports": ["sctx://core/_strategy_general"],
+  "rules": [ /* this schema's own rules */ ]
+}
+```
 
-1. Traverse external `$ref` graph in DFS order.
-2. Apply root schema metadata last.
+- An import brings the imported schema's whole `$metadata` (hierarchy, relationships, aliases, rules).
+- Imports are transitive: an imported schema's own imports come too.
+- Merge order: imports in the order listed, depth-first, then the schema's own metadata last. Each schema is merged at most once.
+- An unresolvable import `$id` is an error.
 
-Merge rules:
-- `hierarchy`: may be defined in partials; **last one wins**. This allows partials to define a default hierarchy that composing schemas can override.
-- `aliases`: shallow merged; later file wins per key.
-- `relationships`: collected from all files; order preserved.
-- `rules`: merged by `id`.
-- Duplicate rule `id` with different payload errors by default.
-- A later rule may replace an earlier one only with `"override": true`.
+One merge rule applies to every key. **A duplicate is an error unless the later entry sets `"override": true`**, in which case it replaces the earlier entry.
+
+| Key | Identity | How to mark `override` |
+|---|---|---|
+| `rules` | `id` | `"override": true` on the rule |
+| `relationships` | `parent` + `type` + `field` (default `"parent"`) | `"override": true` on the relationship |
+| `aliases` | alias name | `{ "type": "<target>", "override": true }` as the alias value |
+| `hierarchy` | `name` | `"override": true` on the hierarchy declaration |
+
+Overriding a hierarchy by name is how a schema replaces the levels of an imported hierarchy (declare it with the same `name` and `"override": true`).
 
 When no provider defines `hierarchy`, hierarchy-based behavior is disabled (`show` tree shape, hierarchy validation, parent-edge checks). `space_on_a_page` parsing still requires hierarchy and will error without it.
 
-### Rule imports via `$ref`
+### Multiple hierarchies
 
-Inside `$metadata.rules`, entries can be inline rules or `$ref` imports:
+A space has several hierarchies when its schema imports several schemas that each declare one. Each schema declares at most one hierarchy.
+
+- **Every imported schema contributes its hierarchy.** Each is kept as a separate named hierarchy; levels are never merged.
+- **Naming.** `hierarchy.name` defaults to the declaring schema's file stem (`_ost_strict` for `_ost_strict.json`). A duplicate name is an error unless the later hierarchy sets `"override": true`.
+- **Main hierarchy.**
+  - If the root schema declares a hierarchy, it is the main hierarchy.
+  - If the root declares none and exactly one hierarchy is imported, that one is the main hierarchy (for example `strict_ost`, which imports `_ost_strict`).
+  - If the root declares none and several are imported, the root must select one with `"hierarchy": { "$ref": "<schema $id>#/$metadata/hierarchy" }`, otherwise loading the schema fails.
+  - A root that both declares a hierarchy and uses `$ref` is an error.
+- **Each type belongs to at most one hierarchy.** A type claimed by two hierarchies is an error. To change an imported hierarchy's levels, override it by name.
+- **Selections are not imported.** A `hierarchy: { "$ref" }` selection only applies when its schema is the root, so an imported schema stays usable standalone as another space's root.
 
 ```json5
-"rules": [
-  { "$ref": "sctx://my-pack#/$defs/workflowRule" },
-  { "$ref": "sctx://my-pack#/$defs/ruleSet" }
-]
+{
+  "$id": "sctx://team",
+  "oneOf": [
+    { "$ref": "sctx://_work#/$defs/goal" },
+    { "$ref": "sctx://_work#/$defs/task" },
+    { "$ref": "sctx://_skills#/$defs/skill_area" },
+    { "$ref": "sctx://_skills#/$defs/skill" }
+  ],
+  "$metadata": {
+    // _work.json and _skills.json each declare a hierarchy; select the main one.
+    "imports": ["sctx://_work", "sctx://_skills"],
+    "hierarchy": { "$ref": "sctx://_work#/$metadata/hierarchy" }
+  }
+}
 ```
 
-Import targets may be:
-- a single rule object
-- an object containing `rules: []`
+How hierarchies are used:
 
-Imported rules are normalized into one executable flat list before validation.
+| Behaviour | Hierarchies used |
+|---|---|
+| Layering, parent-type, skip-level and orphan checks | Each hierarchy, independently. A hierarchy edge whose parent belongs to another hierarchy is an invalid parent. |
+| Relationships | Connect types across hierarchies, as before |
+| `space_on_a_page` parsing, hierarchy embedding, `template-sync` | Main hierarchy |
+| `show`, `diagram`, `render` | Main hierarchy by default; `--hierarchy <name>` selects another |
+| `resolvedParents` | Hierarchy edges carry the `hierarchy` name |
 
 ### Override example
 
@@ -303,22 +352,48 @@ Imported rules are normalized into one executable flat list before validation.
 }
 ```
 
+## Schema `$id` namespaces
+
+Every schema `$id` uses the `sctx://` scheme. The shape of the `$id` says where the schema comes from:
+
+| `$id` shape | Source | Example |
+|---|---|---|
+| `sctx://core/<name>` | Bundled with structured-context | `sctx://core/_sctx_base` |
+| `sctx://<plugin>/<name>` | Contributed by a plugin (its short name, without `sctx-`) | `sctx://wardley-mapping/_wardley` |
+| `sctx://<name>` | Local to a space's schema directory — a single name, no path | `sctx://team` |
+
+- Two schemas loaded for the same space may not share an `$id`; a collision is an error naming both sources.
+- `core` is reserved: no plugin may use it as its namespace.
+- **Legacy bundled ids:** before 1.0, bundled schemas used `sctx://<name>` (e.g. `sctx://_sctx_base`, `sctx://strategy_general`). References to those ids in `$ref` and `$metadata.imports` still resolve to their `sctx://core/` equivalents with a deprecation warning, and local schemas may not use them as their own `$id`. The aliases will be removed in 1.0.
+
 ## Partials and `$ref`
 
 - Files starting with `_` are auto-loaded partials.
-- Both bundled partials and local schema-directory partials are registered.
-- Local partial `$id` values must not collide with bundled IDs.
+- Bundled partials, local schema-directory partials, and partials from loaded plugins are all registered.
+- `$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: "http://json-schema.org/draft-07/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 these via `$ref` rather than redefining common entity types.
-- **Partials can carry metadata**: Partials may include `$metadata` (hierarchy, aliases, relationships, rules). This makes them self-contained units that bundle both type definitions and behavioral metadata.
+- 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.
+- **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
+
+Plugins contribute schemas and partials by standard directory convention: placing schema files in `<pluginRoot>/schemas/` (or declaring `"sctx": { "schemas": "./path" }` in `package.json`).
+
+Because schemas are resolved statically by convention from the filesystem, structured-context does not need to execute plugin JavaScript code during schema validation, context creation, or schema inspection.
+
+When a space uses a plugin schema:
+- **Registry registration**: All partials (`_*`) in the plugin's `schemas/` directory are automatically indexed in the schema registry.
+- **Namespace conventions**: Schemas contributed by a plugin must use `sctx://<pluginName>/...` for their `$id` (e.g. `sctx://wardley-mapping/_wardley`), where the prefix is the plugin's short name (without the `sctx-` prefix). See [Schema `$id` namespaces](#schema-id-namespaces).
+- **Collision protection**: If two plugins register schemas with the same `$id`, or a plugin or local schema collides with a bundled schema, schema loading throws an error.
+- **Imports and $ref**: Plugin schemas can `$ref` or `$metadata.imports` bundled schemas (e.g. `sctx://core/_sctx_base`) as well as other partials within their own namespace. Schema composition rules from #122 apply.
 
 ## Editor expectations
 
-Use the shipped metaschema URL in `$schema` for best cross-tool behavior.
+Use the shipped metaschema URL in `$schema` for best cross-tool behavior; pin a `<version>` URL if you need the dialect to stay fixed.
 
 Notes:
-- Custom `$id` values like `sctx://...` are still supported by the CLI registry.
+- `sctx://` `$id`s are resolved by the CLI registry (see [Schema `$id` namespaces](#schema-id-namespaces)).
 - Some generic editors may not resolve custom URI schemes for `$ref`; CLI behavior is authoritative.
 - Do not rely on editor-only mappings for runtime correctness.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
@@ -25,13 +25,17 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "scripts": {
     "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 && cp -r schemas dist/ && chmod +x dist/index.js",
+    "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",
     "prepublishOnly": "bun run build",
     "validate": "bun run src/index.ts validate",
     "diagram": "bun run src/index.ts diagram",
@@ -43,29 +47,30 @@
     "lint": "biome check",
     "lint:fix": "biome check --write",
     "preversion": "bun run generate:schema-meta && bun run lint:fix && bun run test",
-    "version": "git add -A",
+    "version": "bun run generate:schema-meta --release && git add -A",
     "postversion": "git push --follow-tags"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.92",
-    "@biomejs/biome": "^2.4.10",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.191",
+    "@biomejs/biome": "^2.5.1",
     "@types/bun": "latest",
     "@types/js-yaml": "^4.0.9",
     "json-schema-to-ts": "^3.1.1",
-    "lefthook": "^2.1.4"
+    "lefthook": "^2.1.9",
+    "tsc-alias": "^1.9.1"
   },
   "peerDependencies": {
     "typescript": "^5"
   },
   "dependencies": {
-    "ajv": "^8.18.0",
+    "ajv": "^8.20.0",
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.1",
     "json5": "^2.2.3",
-    "jsonata": "^2.1.0",
+    "jsonata": "^2.2.1",
     "mdast-util-to-string": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",