structured-context 0.9.1 → 0.9.3

package/README.md

@@ -55,12 +55,13 @@ Install globally (recommended):
 
 ```bash
 bun install -g structured-context
+sctx --help
 ```
 
 Or use directly via `bunx`:
 
 ```bash
-bunx structured-context validate <space>
+bunx structured-context --help
 ```
 
 ## Setup for AI Agents
@@ -179,21 +180,24 @@ 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:
-- zero or one metadata provider may define `hierarchy`
+- `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
 
-If no provider defines `hierarchy`, hierarchy-specific checks are skipped. Reading a `space_on_a_page` file still requires `hierarchy.levels`.
+If no file defines `hierarchy`, hierarchy-specific checks are skipped.
 
 **Customizing Schemas:**
-- **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`) are loaded and used to resolve references (using `$ref`).
+- **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.
 - **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.
 
-Schema resolution order: space config `schema` > global config `schema` > bundled `schemas/general.json`
+Schema resolution order: space config `schema` > global config `schema`. Schema resolution fails if none is configured.
 
 **⚠️ Security Notice: Only use schemas and configuration files from trusted sources.**
 
@@ -322,7 +326,7 @@ Generates a Mermaid Entity Relationship Diagram from a schema:
 
 Example:
 ```bash
-sctx schemas show general --mermaid-erd
+sctx schemas show strategy_general --mermaid-erd
 ```
 
 ### Sync space to Miro

package/dist/commands/spaces.js

@@ -1,5 +1,5 @@
 import { basename, resolve } from 'node:path';
-import { configPath, loadConfig, resolveSchema } from '../config';
+import { configPath, loadConfig } from '../config';
 function renderConfigValue(v) {
     if (typeof v === 'object' && v !== null)
         return JSON.stringify(v);
@@ -12,7 +12,8 @@ export function listSpaces() {
     for (const space of config.spaces) {
         console.log(`${space.name}`);
         console.log(`  path:    ${space.path}`);
-        console.log(`  schema:  ${basename(resolveSchema(config, space))}`);
+        const schema = space.schema ?? config.schema;
+        console.log(`  schema:  ${schema ? basename(schema) : '(none)'}`);
         if (space.miroBoardId)
             console.log(`  miro:    configured`);
         const plugins = space.plugins ?? {};

package/dist/commands/validate.js

@@ -97,7 +97,7 @@ export async function validate(context, options = {}) {
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
     const readResult = await readSpace(context);
-    const { nodes, parseIgnored } = readResult;
+    const { nodes, parseIssues } = readResult;
     const result = {
         validCount: 0,
         nodeErrorCount: 0,
@@ -107,7 +107,7 @@ export async function validate(context, options = {}) {
         ruleViolations: [],
         hierarchyViolations: [],
         orphans: [],
-        parseIgnored: parseIgnored || [],
+        parseIssues,
     };
     for (const node of nodes) {
         const valid = schemaValidator(node.schemaData);
@@ -180,7 +180,8 @@ export async function validate(context, options = {}) {
         for (const v of result.hierarchyViolations) {
             addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description);
         }
-        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0);
+        const parseErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
+        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) + parseErrorCount;
         console.log(JSON.stringify({
             space: context.space.name,
             valid: errorCount === 0,
@@ -188,7 +189,7 @@ export async function validate(context, options = {}) {
             errorCount,
             errors: errorsByFile,
             orphanCount: result.orphans.length,
-            parseIgnored: result.parseIgnored,
+            parseIssues: result.parseIssues,
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
     }
@@ -224,16 +225,19 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Rule violations', result.ruleViolations.length, true));
     console.log(fmt('  Hierarchy violations', result.hierarchyViolations.length, true));
     console.log(fmt('  Orphans (hierarchy nodes - no parent)', result.orphans.length, true, true));
-    console.log(fmt('  Ignored during parsing', result.parseIgnored.length, true, true));
+    const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
+    console.log(fmt('  Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0));
     if (result.orphans.length > 0) {
         console.log(`\nOrphans (hierarchy nodes - no parent):`);
         for (const node of result.orphans)
             console.log(`   ${node.label}`);
     }
-    if (result.parseIgnored.length > 0) {
-        console.log(`\nIgnored during parsing:`);
-        for (const f of result.parseIgnored)
-            console.log(`   ${f}`);
+    if (result.parseIssues.length > 0) {
+        console.log(`\nExcluded during parsing:`);
+        for (const issue of result.parseIssues) {
+            const detail = issue.message ? ` - ${issue.message}` : '';
+            console.log(`   ${issue.file}: ${issue.severity} - ${issue.type}${detail}`);
+        }
     }
     if (result.nodeErrors.length > 0) {
         console.log(`\nSchema validation errors:`);
@@ -290,7 +294,8 @@ export async function validate(context, options = {}) {
         result.refErrors.length > 0 ||
         result.duplicateErrors.length > 0 ||
         result.ruleViolations.length > 0 ||
-        result.hierarchyViolations.length > 0) {
+        result.hierarchyViolations.length > 0 ||
+        parseIssueErrorCount > 0) {
         return 1;
     }
     return 0;

package/dist/config.d.ts

@@ -28,7 +28,7 @@ export declare function configPath(): string;
 export declare function loadConfig(): Config;
 /** Get the full space config entry by name. Throws if not found. */
 export declare function getSpaceConfig(name: string, config: Config): SpaceConfig;
-/** Resolve schema path: CLI arg > space-level config > global config > hardcoded default. */
+/** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
 export declare function resolveSchema(config: Config, space?: SpaceConfig): string;
 type StringFields<T> = {
     [K in keyof T]: T[K] extends string | undefined ? K : never;

package/dist/config.js

@@ -170,9 +170,13 @@ export function getSpaceConfig(name, config) {
     }
     return space;
 }
-/** Resolve schema path: CLI arg > space-level config > global config > hardcoded default. */
+/** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
 export function resolveSchema(config, space) {
-    return space?.schema ?? config.schema ?? join(bundledSchemasDir, 'general.json');
+    const schema = space?.schema ?? config.schema;
+    if (!schema) {
+        throw new Error('No schema configured. Set "schema" in the space config or at the top level of the config file.');
+    }
+    return schema;
 }
 /** Update a string field on a space entry and persist config. */
 export function updateSpaceField(spaceName, field, value) {

package/dist/plugin-api.d.ts

@@ -9,4 +9,4 @@ export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
 export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
 export type { SpaceGraph } from './space-graph';
-export type { BaseNode, EdgeDefinition, HierarchyLevel, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, } from './types';
+export type { BaseNode, EdgeDefinition, HierarchyLevel, ParseIssue, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, } from './types';

package/dist/plugins/markdown/read-space.js

@@ -25,7 +25,13 @@ export function readSpaceOnAPage(context) {
         pageType: 'space_on_a_page',
         metadata,
     });
-    return { nodes, parseIgnored: terminatedHeadings, diagnostics: { kind: 'page', preambleNodeCount } };
+    const parseIssues = terminatedHeadings.map((heading) => ({
+        file: heading,
+        severity: 'warning',
+        type: 'terminated',
+        message: 'Ignored headings detected beyond end of hierarchy.',
+    }));
+    return { nodes, parseIssues, diagnostics: { kind: 'page', preambleNodeCount } };
 }
 export async function readSpaceDirectory(context, options) {
     const { space, schema: { metadata }, } = context;
@@ -38,17 +44,33 @@ export async function readSpaceDirectory(context, options) {
     const knownTypes = typeInferenceCfg?.mode !== 'off' ? extractSchemaTypeNames(context.schema, context.schemaRefRegistry) : undefined;
     const files = await Array.fromAsync(new Glob('**/*.md').scan({ cwd: directory, followSymlinks: true }));
     const nodes = [];
-    const skipped = [];
-    const nonSpace = [];
+    const parseIssues = [];
     for (const file of files) {
         const absoluteFilePath = resolve(directory, file);
         if (absoluteTemplateDir && absoluteFilePath.startsWith(absoluteTemplateDir)) {
             continue;
         }
         const content = readFileSync(join(directory, file), 'utf-8');
-        const parsed = matter(content);
+        let parsed;
+        try {
+            parsed = matter(content);
+        }
+        catch (err) {
+            // gray-matter caches parsed YAML and has a known bug where a caught exception
+            // corrupts its internal cache, causing subsequent parses to silently return {}.
+            // Clear the cache after any parse error to avoid stale state.
+            // See: https://github.com/jonschlinkert/gray-matter/issues/166
+            matter.clearCache();
+            parseIssues.push({
+                file,
+                severity: 'error',
+                type: 'parse',
+                message: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            skipped.push(file);
+            parseIssues.push({ file, severity: 'warning', type: 'empty' });
             continue;
         }
         const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
@@ -56,7 +78,7 @@ export async function readSpaceDirectory(context, options) {
             data.type = inferTypeFromPath(file, typeInferenceCfg, knownTypes, context.schema.metadata.typeAliases);
         }
         if (!data.type) {
-            nonSpace.push(file);
+            parseIssues.push({ file, severity: 'warning', type: 'no-type' });
             continue;
         }
         if (ON_A_PAGE_TYPES.includes(data.type) && !options?.includeOnAPageFiles) {
@@ -81,9 +103,14 @@ export async function readSpaceDirectory(context, options) {
             });
             nodes.push(...embedded);
             for (const heading of terminatedHeadings) {
-                nonSpace.push(`${file} > ${heading}`);
+                parseIssues.push({
+                    file: `${file} > ${heading}`,
+                    severity: 'warning',
+                    type: 'terminated',
+                    message: 'Ignored headings detected beyond end of hierarchy.',
+                });
             }
         }
     }
-    return { nodes, parseIgnored: [...skipped, ...nonSpace], diagnostics: { kind: 'directory' } };
+    return { nodes, parseIssues, diagnostics: { kind: 'directory' } };
 }

package/dist/plugins/util.d.ts

@@ -1,6 +1,6 @@
 import type { AnySchemaObject } from 'ajv';
 import type { SpaceGraph } from '../space-graph';
-import type { BaseNode, SpaceContext } from '../types';
+import type { BaseNode, ParseIssue, SpaceContext } from '../types';
 export declare const PLUGIN_PREFIX = "sctx-";
 export declare const CONFIG_PLUGINS_DIR = "plugins";
 /** Normalize a plugin name to its canonical prefixed form. */
@@ -11,8 +11,8 @@ export type PluginContext = SpaceContext & {
 };
 export type ParseResult = {
     nodes: BaseNode[];
-    /** Paths/items the plugin skipped during parsing, for any reason. */
-    parseIgnored: string[];
+    /** Issues encountered while parsing files — excluded files with reason and severity. */
+    parseIssues: ParseIssue[];
     /** Plugin diagnostics: keyed scalar or list values. */
     diagnostics: Record<string, number | string | string[]>;
 };

package/dist/read/read-space.js

@@ -12,7 +12,7 @@ export async function readSpace(context) {
             return {
                 nodes,
                 source: plugin.name,
-                parseIgnored: result.parseIgnored,
+                parseIssues: result.parseIssues,
                 diagnostics: result.diagnostics,
                 unresolvedRefs,
             };

package/dist/schema/schema.js

@@ -255,17 +255,14 @@ function areRulesEquivalent(left, right) {
 }
 function extractMetadata(schema, schemaRefRegistry) {
     const metadataProviders = collectMetadataProviders(schema, schemaRefRegistry);
-    let hierarchyProvider;
     let mergedHierarchy;
     const mergedAliases = {};
     const mergedRules = new Map();
     const mergedRelationships = [];
     for (const provider of metadataProviders) {
         if (provider.metadata.hierarchy) {
-            if (mergedHierarchy) {
-                throw new Error(`Multiple metadata providers define "$metadata.hierarchy": "${hierarchyProvider}" and "${provider.schemaId}". Exactly one provider is allowed.`);
-            }
-            hierarchyProvider = provider.schemaId;
+            // Later providers (including root schema) override earlier ones (e.g. partials).
+            // This allows partials to define a default hierarchy that composing schemas can override.
             mergedHierarchy = provider.metadata.hierarchy;
         }
         if (provider.metadata.aliases) {
@@ -294,6 +291,14 @@ function extractMetadata(schema, schemaRefRegistry) {
             }
         }
     }
+    // Collect valid type names from the schema's oneOf list for validation
+    const validTypeNames = extractSchemaTypeNames(schema, schemaRefRegistry);
+    // Validate and filter metadata references against valid type names
+    validateMetadataReferences({ mergedHierarchy, mergedAliases, mergedRules, mergedRelationships }, validTypeNames);
+    // Filter relationships to only include those where both parent and child types are valid
+    const filteredRelationships = mergedRelationships.filter((rel) => {
+        return validTypeNames.has(rel.parent) && validTypeNames.has(rel.type);
+    });
     const levels = mergedHierarchy?.levels.map((entry) => {
         if (typeof entry === 'string') {
             return { type: entry, field: 'parent', fieldOn: 'child', multiple: false, selfRef: false };
@@ -321,8 +326,8 @@ function extractMetadata(schema, schemaRefRegistry) {
             : undefined,
         typeAliases: Object.keys(mergedAliases).length > 0 ? mergedAliases : undefined,
         rules: mergedRules.size > 0 ? [...mergedRules.values()].map(({ rule }) => normalizeRule(rule)) : undefined,
-        relationships: mergedRelationships.length > 0
-            ? mergedRelationships.map((rel) => ({
+        relationships: filteredRelationships.length > 0
+            ? filteredRelationships.map((rel) => ({
                 ...rel,
                 field: rel.field ?? 'parent',
                 fieldOn: rel.fieldOn === 'parent' ? 'parent' : 'child',
@@ -331,6 +336,38 @@ function extractMetadata(schema, schemaRefRegistry) {
             : undefined,
     };
 }
+function validateMetadataReferences(metadata, validTypes) {
+    // Skip validation if no types are defined (e.g., schemas without oneOf or placeholder schemas)
+    if (validTypes.size === 0) {
+        return;
+    }
+    const errors = [];
+    // Validate hierarchy level types
+    if (metadata.mergedHierarchy?.levels) {
+        for (const level of metadata.mergedHierarchy.levels) {
+            const typeName = typeof level === 'string' ? level : level.type;
+            if (!validTypes.has(typeName)) {
+                errors.push(`Hierarchy level "${typeName}" is not a valid type in the schema's oneOf list`);
+            }
+        }
+    }
+    // Validate alias targets (the values)
+    for (const [alias, target] of Object.entries(metadata.mergedAliases)) {
+        if (!validTypes.has(target)) {
+            errors.push(`Alias "${alias}" → "${target}" references type "${target}" which is not in the schema's oneOf list`);
+        }
+    }
+    // Note: relationships are filtered (not validated) - see extractMetadata
+    // Validate rule types
+    for (const { rule } of metadata.mergedRules.values()) {
+        if (rule.type && !validTypes.has(rule.type)) {
+            errors.push(`Rule "${rule.id}" has type "${rule.type}" which is not in the schema's oneOf list`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Schema metadata validation failed:\n  - ${errors.join('\n  - ')}`);
+    }
+}
 export function extractEntityInfo(schema, schemaRefRegistry) {
     if (!Array.isArray(schema.oneOf))
         return [];

package/dist/schemas/_knowledge_wiki.json

@@ -0,0 +1,246 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://_knowledge_wiki",
+  // Shared entity definitions for knowledge wiki schemas.
+  // Provides aliases, relationships, rules, and entity type $defs.
+  // This partial has no hierarchy — wiki entities are flat with no required parent links.
+  "$metadata": {
+    "aliases": {
+      "source_summary": "source",
+      "study": "source",
+      "article": "source",
+      "paper": "source",
+      "research": "source",
+      "comparison": "synthesis",
+      "query": "synthesis"
+    },
+    "relationships": [
+      {
+        "parent": "source",
+        "type": "source",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "source",
+        "type": "synthesis",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "source",
+        "type": "entity",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "concept",
+        "type": "synthesis",
+        "field": "concepts",
+        "fieldOn": "child",
+        "multiple": true
+      }
+    ],
+    "rules": [
+      {
+        "id": "synthesis-references-sources",
+        "category": "coherence",
+        "description": "Syntheses should reference at least one contributing source in their sources array",
+        "type": "synthesis",
+        "check": "$exists(current.sources) and $count(current.sources) >= 1"
+      },
+      {
+        "id": "concept-has-summary",
+        "category": "best-practice",
+        "description": "Concept pages should have a short summary for index discoverability",
+        "type": "concept",
+        "check": "$exists(current.summary) and $length(current.summary) > 0"
+      }
+    ]
+  },
+  "$defs": {
+    "source": {
+      "type": "object",
+      "description": "A processed summary of a raw source (article, paper, book, video, thread, podcast, etc.). Captures key information from the source in structured form with provenance.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "source" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "url": {
+          "type": "string",
+          "description": "URL of the original source"
+        },
+        "local_copy": {
+          "$ref": "sctx://_sctx_base#/$defs/wikilink",
+          "description": "Wikilink to a local copy of the source (e.g. a saved PDF or clipped note)"
+        },
+        "author": {
+          "type": "string",
+          "description": "Author or creator of the source"
+        },
+        "book": {
+          "type": "string",
+          "description": "Book title and author if the source is a book"
+        },
+        "published_date": {
+          "type": "string",
+          "format": "date",
+          "description": "Original publication date"
+        },
+        "source_type": {
+          "type": "string",
+          "description": "Kind of source material. Free-form — common values include article, paper, book, video, podcast, thread, substack, tweet, website. Not enum-constrained to allow evolving vocabulary."
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to other source pages that this one references or extends"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "source",
+          "author": "Joe Bloggs",
+          "url": "https://example.com/design-of-yesterday-things",
+          "source_type": "book",
+          "tags": ["design", "ux", "psychology"]
+        }
+      ]
+    },
+    "concept": {
+      "type": "object",
+      "description": "A concept page — defines and frames a specific idea, mechanism, or domain term. May draw from multiple sources. The building blocks of the wiki's knowledge graph.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "concept" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages that contributed to this concept"
+        },
+        "related": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to related concept or synthesis pages"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "concept",
+          "summary": "A property of an object that signals how it can be used, first described by Gibson and popularised in design by Norman",
+          "tags": ["design", "ux"]
+        }
+      ]
+    },
+    "entity": {
+      "type": "object",
+      "description": "A concrete entity — a person, organisation, product, model, or other named thing. The building blocks of the wiki's knowledge graph alongside concepts. Entities are distinct from concepts: a concept frames an idea or mechanism; an entity is a specific, identifiable thing in the world.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "entity" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages that contributed to this entity page"
+        },
+        "related": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to related entity, concept, or synthesis pages"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "entity",
+          "summary": "AI safety research lab founded by Dario Amodei and Daniela Amodei",
+          "tags": ["company", "ai", "safety"]
+        }
+      ]
+    },
+    "synthesis": {
+      "type": "object",
+      "description": "A synthesis page — connects multiple concepts and sources into a coherent model, framework, or thesis. The highest-value pages in a knowledge wiki. Must reference contributing sources.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "synthesis" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages this synthesis draws from"
+        },
+        "concepts": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to concept pages this synthesis connects"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "synthesis",
+          "summary": "How Norman's affordance model and feedback principles combine to explain intuitive vs confusing interfaces",
+          "sources": ["[[The Design of Everyday Things - Don Norman]]"],
+          "concepts": ["[[Affordance]]", "[[Feedback loop]]"]
+        }
+      ]
+    },
+    "note": {
+      "type": "object",
+      "description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "note" },
+        "date": {
+          "type": "string",
+          "format": "date",
+          "description": "Date this entry was created or relates to"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "note",
+          "date": "2024-03-15",
+          "tags": ["reading-log"]
+        }
+      ]
+    },
+    "index": {
+      "type": "object",
+      "description": "The wiki index — a catalog of all pages with links, summaries, and metadata. Updated by the agent on ingest. Used as the primary navigation entry point.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "index" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "index"
+        }
+      ]
+    }
+  }
+}