structured-context 0.11.0 → 0.12.0

package/README.md

@@ -28,10 +28,13 @@ Content and structure
   Schema validation errors                 0
   Broken links                             1
   Duplicate keys                           0
-  Rule violations                          2
+  Rule violations (error)                  0
+  Rule violations (warning)                1
+  Rule violations (info)                   1
   Hierarchy violations                     0
   Orphans (hierarchy nodes - no parent)    1
-  Ignored during parsing                   0
+  Unresolved content links                 0
+  Excluded during parsing                  0
 
 Orphans (hierarchy nodes - no parent):
    Solution looking for a problem.md
@@ -40,13 +43,14 @@ Broken links:
    Steal underpants.md: [[Gnome goals]] → Link target "Gnome goals" in field "related" not found
 
 Rule violations:
-  workflow (1):
-    Build Death Star.md: Opportunities should contribute to at least one Outcome
-  
-  best-practice (1):
-    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for an active target opportunity
+  WARNING (1):
+    Build Death Star.md: Opportunities should contribute to at least one Outcome [workflow: opportunity-has-outcome]
+  INFO (1):
+    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for the target opportunity [best-practice: solution-quantity]
 ```
 
+Rule violations carry a severity (`error`, `warning` or `info`) that defaults from the rule's category. Only errors fail validation — see [docs/rules.md](docs/rules.md#categories-and-severity).
+
 ## Installation
 
 Requires [Bun](https://bun.sh) runtime.
@@ -104,7 +108,7 @@ Schemas define the structure and rules for the entities in a space, allowing cus
 
 Several schemas (`strict_ost`, `knowledge_wiki` and `general`) are included. The general (strategy) schema combines a basic vision/mission/goals hierarchy with a hierarchy loosely based on Opportunity Solution Trees. It is intentionally flexible to support rapid initial adoption. The strict OST schema has a narrower scope, and reflects Teresa Torres' specific recommendations for Opportunity Solution Trees more closely. The knowledge wiki schema defines a flatter set of types used for knowledge bases.
 
-structured-context schemas use a metaschema based on JSON Schema Draft-07 that adds a top-level `$metadata` block:
+structured-context schemas use a metaschema based on JSON Schema 2020-12 that adds a top-level `$metadata` block:
 
 ```json5
 "$metadata": {
@@ -179,23 +183,48 @@ Bare wikilink items (`- [[Existing Node]]`) in any embedding section populate a
 
 With `fieldOn: "parent"`, embedded child nodes (parsed from a matching heading's list or table) are appended as wikilinks to the parent's `field` array, rather than receiving a `parent` field. This matches schemas where the content model naturally lists children on the parent (e.g. `activity.tasks: ["[[Task A]]"]`).
 
-Metadata is composable across `$ref` graphs:
-- `hierarchy`: multiple schema files may define a hierarchy; **last one wins** (root schema overrides partials)
-- `aliases` are shallow-merged (later wins)
-- `rules` merge by `id`; conflicts error unless the later rule sets `override: true`
-- `$metadata.rules` supports `$ref` imports for reusable rule packs
-- `relationships` are collected from all files
+`$ref` reuses JSON Schema definitions for validation only; it brings no metadata. Metadata is composed only through explicit imports:
+
+```json5
+"$metadata": { "imports": ["sctx://core/_strategy_general"] }
+```
+
+- An import brings the whole schema's `$metadata`, and is transitive (the imported schema's own imports come too).
+- Merge order: imports in order, depth-first, then the schema's own metadata last.
+- One rule for every key: a duplicate rule `id`, alias, relationship (same `parent`/`type`/`field`) or hierarchy `name` is an error unless the later entry sets `override: true` (for an alias, write the value as `{ "type": "goal", "override": true }`).
+- `hierarchy`: each schema file declares at most one hierarchy, and every imported hierarchy is kept as a separate named hierarchy (see [Multiple hierarchies](#multiple-hierarchies))
+- Each rule's `category` supplies its default severity (`validation` → `error`, `coherence`/`workflow` → `warning`, `best-practice` → `info`); an optional `severity` field overrides it.
 
 If no file defines `hierarchy`, hierarchy-specific checks are skipped.
 
+#### Multiple hierarchies
+
+A space can have several hierarchies by importing schemas that each declare one. For example, a root schema might import a work hierarchy (`goal → task`) and a skills hierarchy (`skill_area → skill`).
+
+- **Naming**: a hierarchy's `name` defaults to the declaring schema's file stem (e.g. `_skills` for `_skills.json`). Set `"name"` in `$metadata.hierarchy` to override it.
+- **Main hierarchy**: if the root schema declares a hierarchy, it is the main one. If the root declares none and exactly one is imported, that one is the main hierarchy. If several are imported, the root must select one:
+
+  ```json5
+  "$metadata": {
+    "imports": ["sctx://_work", "sctx://_skills"],
+    "hierarchy": { "$ref": "sctx://_work#/$metadata/hierarchy" }
+  }
+  ```
+
+  A root may either declare a hierarchy or select one with `$ref`, not both.
+- **Each type belongs to at most one hierarchy.** A type in two hierarchies is an error. To change an imported hierarchy's levels, declare a hierarchy with the same `name` and `"override": true`.
+- **Validation** (layering, parent types, skip levels, orphans) runs per hierarchy. Relationships can connect types across hierarchies.
+- The main hierarchy drives `space_on_a_page` parsing, hierarchy embedding, `template-sync`, and the default `show`/`diagram`/`render` output. Use `--hierarchy <name>` to render another one.
+
 **Customizing Schemas:**
 - **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`) are loaded and used to resolve references (using `$ref`).
 - **Partials as entity libraries**: Partials can define reusable entity types in `$defs` that composing schemas reference via `$ref`. Bundled partials like `_strategy_general` and `_knowledge_wiki` provide common entity sets for strategy and wiki content.
-- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). This makes them self-contained units that bundle both type definitions and behavioral metadata.
-- **No-metadata partials**: If a partial has no `$metadata`, prefer `$schema: "http://json-schema.org/draft-07/schema#"` so it validates standalone as plain JSON Schema.
-- **Loading priority**: Partial schemas are loaded from both the default schema directory and the directory of your specified target schema.
+- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). A schema gets that metadata only by listing the partial in `$metadata.imports`.
+- **No-metadata partials**: If a partial has no `$metadata`, prefer `$schema: "https://json-schema.org/draft/2020-12/schema"` so it validates standalone as plain JSON Schema.
+- **Loading priority**: Partial schemas are loaded from the default schema directory, configured plugins (`schemas/`), and the directory of your specified target schema.
 - **Transitive resolution**: `$ref` chains are resolved recursively across files/schemas (including nested `allOf` usage in partials).
-- **Unique IDs**: To encourage clean namespacing, local partial schemas **must** have unique `$id`s that do not collide with the default schemas. If a collision is detected, validation will fail with an error.
+- **`$id` namespaces**: All `$id`s use `sctx://`. Bundled schemas are `sctx://core/<name>`, plugin schemas `sctx://<pluginName>/<name>`, and local schemas a single name, `sctx://<name>`. Collisions are errors. Legacy bundled ids (`sctx://<name>`, e.g. `sctx://_sctx_base`) resolve to `sctx://core/` with a deprecation warning until 1.0. See [docs/schemas.md](docs/schemas.md#schema-id-namespaces).
+- **Plugin-contributed schemas**: External plugins can contribute schemas via `<pluginRoot>/schemas/` (or `"sctx": { "schemas": "..." }` in `package.json`). Spaces can reference them using `sctx-plugin/schema.json` or `plugin/schema.json`, or by simple filename if the plugin is declared in `plugins`. Schemas resolve statically without executing plugin JavaScript code.
 
 Schema resolution order: space config `schema` > global config `schema`. Schema resolution fails if none is configured.
 
@@ -216,13 +245,24 @@ Validates markdown files against the JSON schema:
 - Skips files without frontmatter or without a `type` field
 - Reports validation results with counts and per-file errors
 
+### Render space
+
+```bash
+sctx render <space> <format> [--out <dir-or-file>] [--force] [--filter <view>] [--hierarchy <name>] [--data key=value]
+```
+
+Renders a space in a plugin-provided format. Use `sctx render list [space]` to list available formats.
+
+- `markdown.bullets` — Indented bullet list tree (outputs to stdout or `--out <file>`).
+- `markdown.directory` — Markdown space directory with one file per node. Writes to `--out <dir>` (refuses to overwrite existing files unless `--force` is passed). Flat directory by default, or organized into per-type subfolders with `--data folders=type` or when configured with `typeInference.folderMap`. Without `--out`, prints a summary of files to be written.
+
 ### Show space tree
 
 ```bash
-sctx show <space> [--filter <view-or-expression>]
+sctx show <space> [--filter <view-or-expression>] [--hierarchy <name>]
 ```
 
-Prints the space as an indented hierarchy tree. Hierarchy roots are listed first, followed by orphans (nodes in the hierarchy but with no resolved parent) and non-hierarchy nodes.
+Prints the space as an indented hierarchy tree. Hierarchy roots are listed first, followed by orphans (nodes in the hierarchy but with no resolved parent) and non-hierarchy nodes. The main hierarchy is shown by default; `--hierarchy <name>` selects another (see [Multiple hierarchies](#multiple-hierarchies)). `diagram` and `render` accept the same option.
 
 When a node appears under multiple parents (DAG hierarchy), it is printed in full under its first parent. Subsequent appearances with children show a `(*)` marker indicating the subtree is omitted.
 
@@ -254,6 +294,7 @@ The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression
 - **`ancestors[]`** — flat array of ancestor nodes, nearest first, deduplicated. Each entry includes all schema fields of the ancestor node, plus:
   - `_field` — the edge field name that connects to the ancestor
   - `_source` — `'hierarchy'` or `'relationship'`
+  - `_hierarchy` — the hierarchy name, for hierarchy edges
   - `_selfRef` — whether the edge is a same-type (self-referential) link
 - **`descendants[]`** — same structure, for descendant nodes
 
@@ -304,7 +345,7 @@ SELECT relationships(assumption) WHERE resolvedType='opportunity'
 ### Generate Mermaid diagram
 
 ```bash
-sctx diagram <space> [--output path/to/output.mmd]
+sctx diagram <space> [--output path/to/output.mmd] [--hierarchy <name>]
 ```
 
 Generates a Mermaid `graph TD` diagram from validated space nodes:
@@ -321,7 +362,7 @@ sctx schemas show <schema-file> [--mermaid-erd] [--space <name>]
 
 Generates a Mermaid Entity Relationship Diagram from a schema:
 - Shows all entity types and their properties
-- Displays parent-child relationships based on hierarchy metadata
+- Displays parent-child relationships based on the levels of each hierarchy
 - Useful for visualizing schema structure during development
 
 Example:

package/dist/api.d.ts

@@ -19,15 +19,17 @@
  */
 export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
 export type { Config, SpaceConfig } from './config';
-export { loadConfig, setConfigPath } from './config';
+export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { PLUGIN_PREFIX } from './constants';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
-export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
+export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFormat, RenderHook, RenderMultiFileOutput, RenderOptions, RenderResult, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
+export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';
+export { buildTargetIndex, formatWikilink, type ParsedWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
-export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
+export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema';
 export { createSpaceContext, SpaceNotFoundError } from './space-context';
-export type { SpaceGraph } from './space-graph';
-export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationResult, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
+export { buildSpaceGraph, type SpaceGraph } from './space-graph';
+export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
 export type { ValidationResult } from './validate';
 export { validateFile, validateSpace } from './validate';

package/dist/api.js

@@ -17,10 +17,13 @@
  *   const graph = await assembleSpaceGraph(ctx, { readResult });
  *   const validation = await validateSpace(ctx, { readResult });
  */
-export { loadConfig, setConfigPath } from './config';
+export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { PLUGIN_PREFIX } from './constants';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
+export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';
+export { buildTargetIndex, formatWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
 export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
 export { createSpaceContext, SpaceNotFoundError } from './space-context';
+export { buildSpaceGraph } from './space-graph';
 export { validateFile, validateSpace } from './validate';

package/dist/commands/diagram.d.ts

@@ -2,4 +2,5 @@ import type { SpaceContext } from '../types';
 export declare function diagram(context: SpaceContext, options: {
     output?: string;
     filter?: string;
+    hierarchy?: string;
 }): Promise<void>;

package/dist/commands/diagram.js

@@ -1,7 +1,13 @@
 import { writeFileSync } from 'node:fs';
 import { executeRender } from '../render/render';
 export async function diagram(context, options) {
-    const result = await executeRender('mermaid.graph', context, { filter: options.filter });
+    const result = await executeRender('mermaid.graph', context, {
+        filter: options.filter,
+        hierarchy: options.hierarchy,
+    });
+    if (typeof result !== 'string') {
+        throw new Error('Expected string output from mermaid diagram renderer');
+    }
     if (options.output) {
         writeFileSync(options.output, result);
         console.log(`Mermaid diagram written to ${options.output}`);

package/dist/commands/dump.d.ts

@@ -1,2 +1,15 @@
-import type { SpaceContext } from '../types';
-export declare function dump(context: SpaceContext): Promise<void>;
+import type { ReadSpaceResult, SpaceContext } from '../types';
+export interface DumpOptions {
+    /** Named view (resolved via space.views) or a raw filter DSL expression. */
+    filter?: string;
+    /** Hierarchy used when evaluating the filter (default: the main hierarchy). */
+    hierarchy?: string;
+}
+/**
+ * Build the dump payload: every parsed node, or only nodes matched by a filter.
+ *
+ * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ */
+export declare function buildDump(context: SpaceContext, options?: DumpOptions): Promise<ReadSpaceResult>;
+export declare function dump(context: SpaceContext, options?: DumpOptions): Promise<void>;

package/dist/commands/dump.js

@@ -1,6 +1,20 @@
-import JSON5 from 'json5';
+import { assembleSpaceGraph } from '../load-space-graph';
 import { readSpace } from '../read/read-space';
-export async function dump(context) {
-    const { nodes, source, diagnostics } = await readSpace(context);
-    console.log(JSON5.stringify({ nodes, source, diagnostics }, null, 2));
+/**
+ * Build the dump payload: every parsed node, or only nodes matched by a filter.
+ *
+ * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ */
+export async function buildDump(context, options = {}) {
+    const readResult = await readSpace(context);
+    if (!options.filter)
+        return readResult;
+    const graph = await assembleSpaceGraph(context, { ...options, readResult });
+    const nodes = readResult.nodes.filter((node) => graph.nodes.get(node.title) === node);
+    return { ...readResult, nodes };
+}
+export async function dump(context, options = {}) {
+    const { nodes, source, diagnostics } = await buildDump(context, options);
+    console.log(JSON.stringify({ nodes, source, diagnostics }, null, 2));
 }

package/dist/commands/render.d.ts

@@ -1,6 +1,10 @@
 import type { SpaceContext } from '../types';
 export declare function render(context: SpaceContext, format: string, options: {
     filter?: string;
+    hierarchy?: string;
     output?: string;
+    out?: string;
+    force?: boolean;
+    data?: Record<string, unknown>;
 }): Promise<void>;
 export declare function renderList(context?: SpaceContext): Promise<void>;

package/dist/commands/render.js

@@ -1,17 +1,72 @@
-import { writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { discoverPlugins, loadPlugins } from '../plugins/loader';
+import { isRenderMultiFileOutput } from '../plugins/util';
 import { buildFormatRegistry } from '../render/registry';
 import { executeRender } from '../render/render';
 export async function render(context, format, options) {
-    const result = await executeRender(format, context, { filter: options.filter });
-    if (options.output) {
-        writeFileSync(options.output, result);
-        console.error(`Written to ${options.output}`);
+    const result = await executeRender(format, context, {
+        filter: options.filter,
+        hierarchy: options.hierarchy,
+        data: options.data,
+    });
+    const targetPath = options.out ?? options.output;
+    const force = Boolean(options.force);
+    if (typeof result === 'string') {
+        if (targetPath) {
+            const resolved = resolve(targetPath);
+            if (existsSync(resolved)) {
+                if (statSync(resolved).isDirectory()) {
+                    throw new Error(`Output path "${targetPath}" is a directory. Please specify a file path.`);
+                }
+                if (!force) {
+                    throw new Error(`File "${targetPath}" already exists. Use --force to overwrite.`);
+                }
+            }
+            mkdirSync(dirname(resolved), { recursive: true });
+            writeFileSync(resolved, result, 'utf8');
+            console.error(`Written to ${targetPath}`);
+        }
+        else {
+            process.stdout.write(result);
+            if (!result.endsWith('\n'))
+                process.stdout.write('\n');
+        }
+        return;
     }
-    else {
-        process.stdout.write(result);
-        if (!result.endsWith('\n'))
-            process.stdout.write('\n');
+    if (isRenderMultiFileOutput(result)) {
+        if (targetPath) {
+            const targetDir = resolve(targetPath);
+            const conflicts = [];
+            for (const file of result.files) {
+                const fullPath = join(targetDir, file.path);
+                if (existsSync(fullPath)) {
+                    conflicts.push(file.path);
+                }
+            }
+            if (conflicts.length > 0 && !force) {
+                const preview = conflicts
+                    .slice(0, 5)
+                    .map((f) => `  ${f}`)
+                    .join('\n');
+                const extra = conflicts.length > 5 ? `\n  ... and ${conflicts.length - 5} more` : '';
+                throw new Error(`Refusing to overwrite ${conflicts.length} existing file(s) in "${targetPath}" without --force:\n${preview}${extra}`);
+            }
+            for (const file of result.files) {
+                const fullPath = join(targetDir, file.path);
+                mkdirSync(dirname(fullPath), { recursive: true });
+                writeFileSync(fullPath, file.content, 'utf8');
+            }
+            console.error(`Written ${result.files.length} file(s) to ${targetPath}`);
+        }
+        else {
+            console.log(`Rendered ${result.files.length} file(s):`);
+            for (const file of result.files) {
+                const bytes = Buffer.byteLength(file.content, 'utf8');
+                console.log(`  ${file.path} (${bytes} bytes)`);
+            }
+            console.log('\nSpecify --out <dir> to write files to disk.');
+        }
     }
 }
 export async function renderList(context) {

package/dist/commands/schemas.d.ts

@@ -1,6 +1,6 @@
-export declare function listSchemas(): void;
+export declare function listSchemas(): Promise<void>;
 export declare function showSchema(file: string | undefined, options: {
     space?: string;
     raw: boolean;
     mermaidErd?: boolean;
-}): void;
+}): Promise<void>;

package/dist/commands/schemas.js

@@ -1,8 +1,12 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { loadConfig, resolveSchema } from '../config';
-import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema } from '../schema/schema';
+import { dirname, join, resolve } from 'node:path';
+import { loadConfig } from '../config';
+import { discoverPlugins } from '../plugins/loader';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema, } from '../schema/schema';
 import { mergeVariantProperties, resolveRef } from '../schema/schema-refs';
+import { DEFAULT_SEVERITY_BY_CATEGORY } from '../schema/validate-rules';
+import { createSpaceContext } from '../space-context';
 function isBundledPath(schemaPath) {
     return dirname(schemaPath) === bundledSchemasDir;
 }
@@ -73,9 +77,14 @@ function showDefs(defs) {
     }
 }
 function showMetadata(metadata) {
-    if (metadata.hierarchy?.levels.length) {
-        const parts = metadata.hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type));
-        console.log(`\nhierarchy: ${parts.join(' → ')}`);
+    const hierarchies = metadata.hierarchies ?? [];
+    if (hierarchies.length > 0) {
+        console.log('');
+        for (const hierarchy of hierarchies) {
+            const parts = hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type));
+            const main = hierarchy === metadata.hierarchy ? ' (main)' : '';
+            console.log(`hierarchy "${hierarchy.name}"${main}: ${parts.join(' → ')}`);
+        }
     }
     else {
         console.log('\nhierarchy: (none)');
@@ -88,15 +97,16 @@ function showMetadata(metadata) {
         const groups = new Map();
         for (const rule of metadata.rules) {
             const rules = groups.get(rule.category) ?? [];
-            rules.push({ id: rule.id, description: rule.description });
+            rules.push(rule);
             groups.set(rule.category, rules);
         }
         if (groups.size > 0) {
             console.log('\nRules:');
-            for (const [group, items] of groups) {
-                console.log(`  ${group}:`);
-                for (const item of items) {
-                    console.log(`    ${item.id}: ${item.description}`);
+            for (const [category, rules] of groups) {
+                console.log(`  ${category} (default severity: ${DEFAULT_SEVERITY_BY_CATEGORY[category]}):`);
+                for (const rule of rules) {
+                    const override = rule.severity ? ` [severity: ${rule.severity}]` : '';
+                    console.log(`    ${rule.id}: ${rule.description}${override}`);
                 }
             }
         }
@@ -110,7 +120,7 @@ function showMetadata(metadata) {
         }
     }
 }
-function showRegistry(schemaPath, schemaRefRegistry) {
+function showRegistry(schemaPath, schemaRefRegistry, pluginSchemas) {
     const bundledIds = new Set();
     if (existsSync(bundledSchemasDir)) {
         for (const file of readdirSync(bundledSchemasDir).filter((f) => f.endsWith('.json'))) {
@@ -119,9 +129,22 @@ function showRegistry(schemaPath, schemaRefRegistry) {
                 bundledIds.add(s.$id);
         }
     }
+    const pluginIds = new Set();
+    if (pluginSchemas) {
+        for (const { schemasDir } of pluginSchemas) {
+            if (!existsSync(schemasDir))
+                continue;
+            for (const file of readdirSync(schemasDir).filter((f) => f.endsWith('.json'))) {
+                const s = readRawSchema(join(schemasDir, file));
+                if (typeof s.$id === 'string')
+                    pluginIds.add(s.$id);
+            }
+        }
+    }
     console.log(`\nRegistry (${schemaPath}):`);
     for (const [id] of schemaRefRegistry) {
-        console.log(`  [${bundledIds.has(id) ? 'bundled' : 'local'}]  ${id}`);
+        const origin = bundledIds.has(id) ? 'bundled' : pluginIds.has(id) ? 'plugin' : 'local';
+        console.log(`  [${origin}]  ${id}`);
     }
 }
 /**
@@ -130,7 +153,6 @@ function showRegistry(schemaPath, schemaRefRegistry) {
  */
 function generateMermaidErd(metadata, entities) {
     let mmd = 'erDiagram\n';
-    const hierarchyLevels = metadata.hierarchy?.levels ?? [];
     // Generate entity definitions with properties
     for (const entity of entities) {
         const safeName = entity.type.replace(/[^a-zA-Z0-9_]/g, '_');
@@ -145,8 +167,8 @@ function generateMermaidErd(metadata, entities) {
         }
         mmd += '  }\n';
     }
-    // Generate relationships based on hierarchy metadata
-    if (hierarchyLevels.length > 0) {
+    // Generate relationships based on the levels of each hierarchy
+    for (const { levels: hierarchyLevels } of metadata.hierarchies ?? []) {
         for (let i = 0; i < hierarchyLevels.length - 1; i++) {
             const current = hierarchyLevels[i];
             const next = hierarchyLevels[i + 1];
@@ -166,7 +188,7 @@ function generateMermaidErd(metadata, entities) {
     }
     return mmd;
 }
-export function listSchemas() {
+export async function listSchemas() {
     const config = loadConfig();
     // List all schemas known to config
     if (existsSync(bundledSchemasDir)) {
@@ -182,6 +204,23 @@ export function listSchemas() {
             }
         }
     }
+    // List schemas provided by discovered plugins
+    const plugins = await discoverPlugins();
+    for (const p of plugins) {
+        if (p.schemasDir && existsSync(p.schemasDir)) {
+            const files = readdirSync(p.schemasDir)
+                .filter((f) => f.endsWith('.json'))
+                .sort();
+            if (files.length > 0) {
+                console.log(`\nPlugin schemas (${p.name}):`);
+                for (const file of files) {
+                    const schema = readRawSchema(join(p.schemasDir, file));
+                    const id = typeof schema.$id === 'string' ? schema.$id : '(no $id)';
+                    console.log(`  ${file}${file.startsWith('_') ? '  [partial]' : ''}  (${id})`);
+                }
+            }
+        }
+    }
     const configured = [];
     const seen = new Set();
     if (config.schema && !isBundledPath(config.schema)) {
@@ -201,16 +240,23 @@ export function listSchemas() {
         }
     }
 }
-export function showSchema(file, options) {
+export async function showSchema(file, options) {
     const config = loadConfig();
     let schemaPath;
+    let schema;
+    let schemaRefRegistry;
+    let pluginSchemas;
     if (options.space) {
         const space = config.spaces.find((s) => s.name === options.space);
         if (!space) {
             console.error(`Error: Unknown space "${options.space}"`);
             process.exit(1);
         }
-        schemaPath = resolveSchema(config, space);
+        const context = createSpaceContext(options.space, config);
+        schemaPath = context.resolvedSchemaPath;
+        schema = context.schema;
+        schemaRefRegistry = context.schemaRefRegistry;
+        pluginSchemas = resolveSpacePluginSchemas(context.space, config, context.configDir);
     }
     else if (!file) {
         console.error('Error: specify a file argument or use --space');
@@ -220,7 +266,49 @@ export function showSchema(file, options) {
         schemaPath = file;
     }
     else {
-        schemaPath = join(bundledSchemasDir, file.endsWith('.json') ? file : `${file}.json`);
+        // Check discovered plugins
+        const discovered = await discoverPlugins();
+        pluginSchemas = discovered
+            .filter((p) => p.schemasDir)
+            .map((p) => ({ pluginName: shortenPluginName(p.name), schemasDir: p.schemasDir }));
+        let candidatePath;
+        if (file.includes('/')) {
+            const slashIdx = file.indexOf('/');
+            const prefix = file.slice(0, slashIdx);
+            const subPath = file.slice(slashIdx + 1);
+            const norm = normalizePluginName(prefix);
+            const short = shortenPluginName(prefix);
+            const pluginDir = resolvePluginSchemasDir(prefix, process.cwd());
+            if (pluginDir) {
+                candidatePath = resolve(pluginDir, subPath.endsWith('.json') ? subPath : `${subPath}.json`);
+                if (!pluginSchemas.some((ps) => ps.pluginName === short)) {
+                    pluginSchemas.push({ pluginName: short, schemasDir: pluginDir });
+                }
+            }
+            else {
+                const match = discovered.find((p) => (p.name === norm || p.name === short) && p.schemasDir);
+                if (match?.schemasDir) {
+                    candidatePath = resolve(match.schemasDir, subPath.endsWith('.json') ? subPath : `${subPath}.json`);
+                }
+            }
+        }
+        else {
+            for (const p of discovered) {
+                if (p.schemasDir) {
+                    const c = resolve(p.schemasDir, file.endsWith('.json') ? file : `${file}.json`);
+                    if (existsSync(c)) {
+                        candidatePath = c;
+                        break;
+                    }
+                }
+            }
+        }
+        if (candidatePath && existsSync(candidatePath)) {
+            schemaPath = candidatePath;
+        }
+        else {
+            schemaPath = join(bundledSchemasDir, file.endsWith('.json') ? file : `${file}.json`);
+        }
     }
     if (!existsSync(schemaPath)) {
         console.error(`Schema not found: ${schemaPath}`);
@@ -237,7 +325,11 @@ export function showSchema(file, options) {
         process.stdout.write(content);
         return;
     }
-    const { schema, schemaRefRegistry } = loadSchema(schemaPath);
+    if (!schema || !schemaRefRegistry) {
+        const loaded = loadSchema(schemaPath, pluginSchemas);
+        schema = loaded.schema;
+        schemaRefRegistry = loaded.schemaRefRegistry;
+    }
     // Handle --mermaid-erd: generate ERD and exit
     if (options.mermaidErd) {
         const entityInfo = extractEntityInfo(schema, schemaRefRegistry);
@@ -265,5 +357,5 @@ export function showSchema(file, options) {
             console.log(`  ${ref}`);
         }
     }
-    showRegistry(schemaPath, schemaRefRegistry);
+    showRegistry(schemaPath, schemaRefRegistry, pluginSchemas);
 }

package/dist/commands/show.d.ts

@@ -1,4 +1,5 @@
 import type { SpaceContext } from '../types';
 export declare function show(context: SpaceContext, options?: {
     filter?: string;
+    hierarchy?: string;
 }): Promise<void>;

package/dist/commands/show.js

@@ -1,6 +1,12 @@
 import { executeRender } from '../render/render';
 export async function show(context, options) {
-    const result = await executeRender('markdown.bullets', context, { filter: options?.filter });
+    const result = await executeRender('markdown.bullets', context, {
+        filter: options?.filter,
+        hierarchy: options?.hierarchy,
+    });
+    if (typeof result !== 'string') {
+        throw new Error('Expected string output from markdown.bullets renderer');
+    }
     process.stdout.write(result);
     if (!result.endsWith('\n'))
         process.stdout.write('\n');

package/dist/commands/spaces.d.ts

@@ -1 +1,3 @@
-export declare function listSpaces(): void;
+export declare function listSpaces(options?: {
+    json?: boolean;
+}): void;