structured-context 0.11.0 → 0.12.0

package/dist/space-graph.js

@@ -1,7 +1,9 @@
-/** Build a SpaceGraph from a flat list of SpaceNodes and hierarchy level definitions. */
-export function buildSpaceGraph(nodes, levels) {
+/** Build a SpaceGraph from a flat list of SpaceNodes and the hierarchy to structure it by. */
+export function buildSpaceGraph(nodes, hierarchy) {
+    const levels = hierarchy?.levels ?? [];
     const hierarchyTypes = new Set(levels.map((l) => l.type));
     const rootType = levels[0]?.type;
+    const isHierarchyEdge = (r) => r.source === 'hierarchy' && r.hierarchy === hierarchy?.name;
     const nodesMap = new Map();
     const hierarchyChildrenMap = new Map();
     const childrenMap = new Map();
@@ -22,7 +24,7 @@ export function buildSpaceGraph(nodes, levels) {
                 childrenMap.set(parentRef.title, []);
             childrenMap.get(parentRef.title).push(node);
             // Hierarchy-only map
-            if (parentRef.source === 'hierarchy') {
+            if (isHierarchyEdge(parentRef)) {
                 if (!hierarchyChildrenMap.has(parentRef.title))
                     hierarchyChildrenMap.set(parentRef.title, []);
                 hierarchyChildrenMap.get(parentRef.title).push(node);
@@ -37,7 +39,7 @@ export function buildSpaceGraph(nodes, levels) {
             continue;
         }
         // Only hierarchy-sourced parents determine structural position in the DAG
-        const hierarchyParents = node.resolvedParents.filter((r) => r.source === 'hierarchy');
+        const hierarchyParents = node.resolvedParents.filter(isHierarchyEdge);
         if (hierarchyParents.length === 0) {
             if (nodeType === rootType) {
                 hierarchyRoots.push(node);
@@ -77,6 +79,6 @@ export function buildSpaceGraph(nodes, levels) {
         hierarchyChildren: hierarchyChildrenMap,
         children: childrenMap,
         hierarchyTitles,
-        levels,
+        hierarchy,
     };
 }

package/dist/testing.d.ts

@@ -0,0 +1,33 @@
+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;
+/**
+ * Creates a HierarchyLevel with defaults matching schema metadata normalization.
+ */
+export declare const makeLevel: (type: string, overrides?: Partial<HierarchyLevel>) => HierarchyLevel;
+/**
+ * Creates a named Hierarchy (default name 'main') from normalized levels.
+ */
+export declare const makeHierarchy: (levels: HierarchyLevel[], overrides?: Partial<Hierarchy>) => Hierarchy;
+/**
+ * SchemaMetadata fields for a schema whose only hierarchy is its main hierarchy.
+ */
+export declare const withHierarchy: (levels: HierarchyLevel[], overrides?: Partial<Hierarchy>) => {
+    hierarchy: Hierarchy;
+    hierarchies: Hierarchy[];
+};
+/**
+ * Creates a Relationship with defaults matching schema metadata normalization.
+ */
+export declare const makeRelationship: (parent: string, type: string, overrides?: Partial<Relationship>) => Relationship;
+/**
+ * Creates a BaseNode with sensible defaults for use in tests.
+ */
+export declare const makeNode: (title: string, type: string, extra?: Record<string, unknown>, linkTargets?: string[]) => BaseNode;
+/**
+ * Creates a SpaceNode with sensible defaults for use in tests.
+ */
+export declare const makeSpaceNode: (title: string, type: string, extra?: Record<string, unknown>, linkTargets?: string[], resolvedParents?: ResolvedParentRef[], resolvedLinks?: SpaceNode["resolvedLinks"]) => SpaceNode;

package/dist/testing.js

@@ -0,0 +1,72 @@
+/**
+ * Creates a ResolvedParentRef with sensible defaults for use in tests.
+ * Override any field to represent specific edge contexts.
+ */
+export const makeParentRef = (title, overrides = {}) => {
+    const source = overrides.source ?? 'hierarchy';
+    return {
+        title,
+        field: 'parent',
+        source,
+        ...(source === 'hierarchy' ? { hierarchy: 'main' } : {}),
+        selfRef: false,
+        fieldOn: 'child',
+        ...overrides,
+    };
+};
+/**
+ * Creates a HierarchyLevel with defaults matching schema metadata normalization.
+ */
+export const makeLevel = (type, overrides = {}) => ({
+    type,
+    field: 'parent',
+    fieldOn: 'child',
+    multiple: false,
+    selfRef: false,
+    ...overrides,
+});
+/**
+ * Creates a named Hierarchy (default name 'main') from normalized levels.
+ */
+export const makeHierarchy = (levels, overrides = {}) => ({
+    name: 'main',
+    levels,
+    ...overrides,
+});
+/**
+ * SchemaMetadata fields for a schema whose only hierarchy is its main hierarchy.
+ */
+export const withHierarchy = (levels, overrides = {}) => {
+    const hierarchy = makeHierarchy(levels, overrides);
+    return { hierarchy, hierarchies: [hierarchy] };
+};
+/**
+ * Creates a Relationship with defaults matching schema metadata normalization.
+ */
+export const makeRelationship = (parent, type, overrides = {}) => ({
+    parent,
+    type,
+    field: 'parent',
+    fieldOn: 'child',
+    multiple: false,
+    ...overrides,
+});
+/**
+ * Creates a BaseNode with sensible defaults for use in tests.
+ */
+export const makeNode = (title, type, extra = {}, linkTargets) => ({
+    label: `${title}.md`,
+    title,
+    schemaData: { title, type, ...extra },
+    linkTargets: linkTargets ?? [title],
+    type,
+});
+/**
+ * Creates a SpaceNode with sensible defaults for use in tests.
+ */
+export const makeSpaceNode = (title, type, extra = {}, linkTargets, resolvedParents = [], resolvedLinks = []) => ({
+    ...makeNode(title, type, extra, linkTargets),
+    resolvedType: type,
+    resolvedParents,
+    resolvedLinks,
+});

package/dist/types.d.ts

@@ -40,11 +40,21 @@ export type ResolvedParentRef = {
     field: string;
     /** Whether this edge originates from a hierarchy level or a relationship definition. */
     source: 'hierarchy' | 'relationship';
+    /** Name of the hierarchy the edge belongs to. Set only when source is 'hierarchy'. */
+    hierarchy?: string;
     /** Whether the parent and child are the same node type (self-referential edge). */
     selfRef: boolean;
     /** Whether the edge field is on the child node (default) or on the parent node (fieldOn:'parent' edges). */
     fieldOn: 'child' | 'parent';
 };
+export type SourceLocation = {
+    /** File path relative to the space root. */
+    file: string;
+    /** 1-indexed starting line number in the source file, if available. */
+    line?: number;
+    /** 1-indexed starting column number in the source file, if available. */
+    column?: number;
+};
 export type UnresolvedRef = {
     /** Source identifier of the node containing the broken link. */
     label: string;
@@ -55,6 +65,8 @@ export type UnresolvedRef = {
     reason: 'not_found' | 'ambiguous' | 'invalid_shape';
     /** Human-readable message matching validate-graph output format. */
     message: string;
+    /** Source location of the node containing the broken link, if available. */
+    source?: SourceLocation;
 };
 /**
  * Shared fields for all content link variants.
@@ -107,11 +119,15 @@ export type BaseNode = {
     linkTargets: string[];
     /** Raw type string from content, as written by the user. */
     type: string;
+    /** Body content of the node, if any. First-class accessor mirroring schemaData.content. */
+    content?: string;
     /**
      * Links extracted from content body and non-edge string fields at parse time.
      * Populated by plugins that support content link extraction; absent if not populated.
      */
     contentLinks?: ContentLink[];
+    /** Source location of the node definition in the filesystem. */
+    source?: SourceLocation;
 };
 /**
  * A fully resolved node — enriched by core after plugin parsing.
@@ -143,14 +159,25 @@ export type ParseIssue = {
     type: 'no-type' | 'parse' | string;
     /** Human-readable detail. */
     message?: string;
+    /** 1-indexed line number in source file, if available. */
+    line?: number;
+    /** 1-indexed column number in source file, if available. */
+    column?: number;
 };
 /** Rule categories for organizing executable validation rules */
 export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-practice';
+/**
+ * Rule violation severity. Only `error` fails validation; `warning` and `info` are reported only.
+ * A rule's severity defaults from its category and may be overridden per rule.
+ */
+export type RuleSeverity = 'error' | 'warning' | 'info';
 export type { Rule } from './schema/metadata-contract';
 export type RuleViolation = {
+    /** Node label, or empty string for global-scope rules. */
     file: string;
     ruleId: string;
     category: RuleCategory;
+    severity: RuleSeverity;
     description: string;
 };
 export type GraphViolation = {
@@ -161,11 +188,18 @@ export type GraphViolation = {
     parentTitle: string;
     description: string;
 };
+/** A named hierarchy, normalized from a schema's `$metadata.hierarchy`. */
+export type Hierarchy = {
+    /** Declared short name, defaulting to the declaring schema's file stem. */
+    name: string;
+    levels: HierarchyLevel[];
+    allowSkipLevels?: boolean;
+};
 export type SchemaMetadata = {
-    hierarchy?: {
-        levels: HierarchyLevel[];
-        allowSkipLevels?: boolean;
-    };
+    /** Main hierarchy: used for space_on_a_page parsing, embedding, template-sync and default rendering. */
+    hierarchy?: Hierarchy;
+    /** Every hierarchy in the composed schema (main included), in composition order. Each type belongs to at most one. */
+    hierarchies?: Hierarchy[];
     typeAliases?: Record<string, string>;
     rules?: Rule[];
     relationships?: Relationship[];
@@ -201,21 +235,28 @@ export type SpaceContext = {
     /** Directory of the config file that defines this space. Used for resolving relative paths in plugin configs. */
     configDir: string;
 };
+export interface FileValidationIssue {
+    kind: string;
+    message: string;
+    /** Present for rule violations (`kind: 'rule'`). */
+    severity?: RuleSeverity;
+    /** 1-indexed line number in source file, if available. */
+    line?: number;
+    /** 1-indexed column number in source file, if available. */
+    column?: number;
+}
 export interface FileValidationResult {
     file: string;
     label: string;
     space: string;
     /** Errors keyed by composite id (e.g. `schema:/status:enum:active`, `rule:my-rule-id`). */
-    errors: Record<string, {
-        kind: string;
-        message: string;
-    }>;
+    errors: Record<string, FileValidationIssue>;
     errorCount: number;
-    /** Warnings keyed by composite id. Do not affect exit code or errorCount. */
-    warnings: Record<string, {
-        kind: string;
-        message: string;
-    }>;
+    /**
+     * Warnings keyed by composite id, including `warning` and `info` severity rule violations.
+     * Do not affect exit code or errorCount.
+     */
+    warnings: Record<string, FileValidationIssue>;
     warningCount: number;
     inSpace: true;
 }

package/dist/validate.d.ts

@@ -11,11 +11,13 @@ export interface ValidationResult {
     nodeErrorCount: number;
     nodeErrors: Array<{
         file: string;
+        line?: number;
         errors: ErrorObject[];
         nodeData: Record<string, unknown>;
     }>;
     refErrors: Array<{
         file: string;
+        line?: number;
         parent: string;
         error: string;
     }>;
@@ -23,6 +25,7 @@ export interface ValidationResult {
         title: string;
         files: string[];
     }>;
+    /** All rule violations with their effective severity. Only `error` severity fails validation. */
     ruleViolations: RuleViolation[];
     hierarchyViolations: GraphViolation[];
     orphans: SpaceNode[];

package/dist/validate.js

@@ -121,7 +121,8 @@ export async function validateSpace(context, options = {}) {
         if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
             result.nodeErrorCount++;
             result.nodeErrors.push({
-                file: node.label,
+                file: node.source?.file ?? node.label,
+                ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
                 errors: [
                     {
                         instancePath: '/type',
@@ -143,7 +144,8 @@ export async function validateSpace(context, options = {}) {
         else {
             result.nodeErrorCount++;
             result.nodeErrors.push({
-                file: node.label,
+                file: node.source?.file ?? node.label,
+                ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
                 errors: schemaValidator.errors || [],
                 nodeData: node.schemaData,
             });
@@ -167,9 +169,9 @@ export async function validateSpace(context, options = {}) {
     const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
     result.refErrors.push(...hierarchyValidation.refErrors);
     result.hierarchyViolations = [...hierarchyValidation.violations];
-    // Calculate orphan count (informational, not a validation error)
-    if (metadata.hierarchy) {
-        result.orphans = [...buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans];
+    // Calculate orphans across every hierarchy (informational, not a validation error)
+    for (const hierarchy of metadata.hierarchies ?? []) {
+        result.orphans.push(...buildSpaceGraph(nodes, hierarchy).orphans);
     }
     // Load and execute rules validation if schema defines rules
     if (metadata.rules) {
@@ -230,6 +232,7 @@ export async function validateFile(filePath, config, options = {}) {
     // Pre-extract valid types for early type validation
     const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
     const errors = {};
+    const warnings = {};
     // Schema validation errors for this node
     for (const node of nodes) {
         if (node.label !== label)
@@ -240,6 +243,8 @@ export async function validateFile(filePath, config, options = {}) {
             errors[`schema:type:${validTypes.join(',')}`] = {
                 kind: 'schema',
                 message: `Invalid type "${nodeType}". Valid types are: ${validTypes.sort().join(', ')}`,
+                ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+                ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
             };
             continue;
         }
@@ -247,7 +252,12 @@ export async function validateFile(filePath, config, options = {}) {
         if (!valid) {
             const formatted = formatErrors(schemaValidator.errors ?? [], schema, schemaRefRegistry, node.schemaData);
             for (const { message, dedupeKey } of formatted) {
-                errors[`schema:${dedupeKey}`] = { kind: 'schema', message };
+                errors[`schema:${dedupeKey}`] = {
+                    kind: 'schema',
+                    message,
+                    ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+                    ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
+                };
             }
         }
     }
@@ -279,17 +289,17 @@ export async function validateFile(filePath, config, options = {}) {
             errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
         }
     }
-    // Rule violations for this node
+    // Rule violations for this node — only error severity counts as an error
     if (metadata.rules) {
         const ruleViolations = await validateRules(nodes, metadata.rules);
         for (const v of ruleViolations) {
             if (v.file === label) {
-                errors[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}` };
+                const target = v.severity === 'error' ? errors : warnings;
+                target[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}`, severity: v.severity };
             }
         }
     }
     // Unresolved content links for this node (warnings — do not affect errorCount)
-    const warnings = {};
     const targetNode = nodes.find((n) => n.label === label);
     if (targetNode) {
         const seen = new Set();

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,10 @@ 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
 
@@ -315,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,6 +26,12 @@ 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.
@@ -53,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: