structured-context 0.9.1 → 0.9.3

package/dist/schemas/{general.json → _strategy_general.json}

@@ -1,8 +1,9 @@
 {
   "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://general",
-  "title": "Strategy and opportunity ladder",
-  "description": "Validates frontmatter for space node files",
+  "$id": "sctx://_strategy_general",
+  // Shared entity definitions for strategy-general schemas.
+  // Provides a default hierarchy, aliases, relationships, and entity type $defs.
+  // Composing schemas can override the hierarchy by defining their own.
   "$metadata": {
     "hierarchy": {
       "levels": [
@@ -41,8 +42,8 @@
       }
     ]
   },
-  "oneOf": [
-    {
+  "$defs": {
+    "dashboard": {
       "type": "object",
       "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
@@ -51,7 +52,7 @@
       "required": ["type"],
       "additionalProperties": true
     },
-    {
+    "ost_on_a_page": {
       "type": "object",
       "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
@@ -60,7 +61,7 @@
       "required": ["type"],
       "additionalProperties": true
     },
-    {
+    "vision": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -79,7 +80,7 @@
         }
       ]
     },
-    {
+    "mission": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -99,7 +100,7 @@
         }
       ]
     },
-    {
+    "goal": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -121,7 +122,7 @@
         }
       ]
     },
-    {
+    "opportunity": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -154,7 +155,7 @@
         }
       ]
     },
-    {
+    "solution": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -187,7 +188,7 @@
         }
       ]
     },
-    {
+    "experiment": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -212,7 +213,7 @@
         }
       ]
     },
-    {
+    "assumption": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -238,7 +239,7 @@
         }
       ]
     },
-    {
+    "problem_statement": {
       "type": "object",
       "allOf": [
         { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
@@ -257,5 +258,5 @@
         }
       ]
     }
-  ]
+  }
 }

package/dist/schemas/knowledge_wiki.json

@@ -3,243 +3,13 @@
   "$id": "sctx://knowledge_wiki",
   "title": "Knowledge Wiki",
   "description": "Lightweight schema for LLM-maintained knowledge wikis. Supports source pages, concept pages, syntheses, and notes. Designed for compounding knowledge bases where the LLM creates and maintains wiki pages from raw sources.\n\nFlat entity model — no hierarchy, no required parent links. Wikilinks between any pages are valid for arbitrary cross-referencing. The schema validates structure and provenance; it does not constrain meaning.\n\nBased on the pattern described in Karpathy's LLM Wiki (2026).",
-  "$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"
-      }
-    ]
-  },
+  "allOf": [{ "$ref": "sctx://_knowledge_wiki" }],
   "oneOf": [
-    {
-      "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"]
-        }
-      ]
-    },
-    {
-      "type": "object",
-      "description": "A concept or entity 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"]
-        }
-      ]
-    },
-    {
-      "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"]
-        }
-      ]
-    },
-    {
-      "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]]"]
-        }
-      ]
-    },
-    {
-      "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"]
-        }
-      ]
-    },
-    {
-      "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"
-        }
-      ]
-    }
+    { "$ref": "sctx://_knowledge_wiki#/$defs/source" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/concept" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/entity" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/synthesis" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/note" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/index" }
   ]
 }

package/dist/schemas/strategy_general.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://strategy_general",
+  "title": "Strategy and opportunity ladder",
+  "description": "Validates frontmatter for space node files. Composes strategy_general entities from the bundled partial. Override the hierarchy in $metadata to customize the level structure.",
+  "allOf": [{ "$ref": "sctx://_strategy_general" }],
+  "oneOf": [
+    { "$ref": "sctx://_strategy_general#/$defs/dashboard" },
+    { "$ref": "sctx://_strategy_general#/$defs/ost_on_a_page" },
+    { "$ref": "sctx://_strategy_general#/$defs/vision" },
+    { "$ref": "sctx://_strategy_general#/$defs/mission" },
+    { "$ref": "sctx://_strategy_general#/$defs/goal" },
+    { "$ref": "sctx://_strategy_general#/$defs/opportunity" },
+    { "$ref": "sctx://_strategy_general#/$defs/solution" },
+    { "$ref": "sctx://_strategy_general#/$defs/experiment" },
+    { "$ref": "sctx://_strategy_general#/$defs/assumption" },
+    { "$ref": "sctx://_strategy_general#/$defs/problem_statement" }
+  ]
+}

package/dist/types.d.ts

@@ -86,6 +86,18 @@ export type SpaceNode = BaseNode & {
      */
     resolvedParents: ResolvedParentRef[];
 };
+export type ParseIssue = {
+    /** Source identifier of the file or item (filename or heading title). */
+    file: string;
+    /** error: prevented the file from producing nodes; warning: file was silently excluded. */
+    severity: 'error' | 'warning';
+    /** empty: no content; no-type: no type field;
+     *  parse: parse failure (syntax issue or unexpected content);
+     *  plugins may choose to provide additional types. */
+    type: 'empty' | 'no-type' | 'parse' | string;
+    /** Human-readable detail. */
+    message?: string;
+};
 /** Rule categories for organizing executable validation rules */
 export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-practice';
 export type { Rule } from './schema/metadata-contract';
@@ -118,8 +130,8 @@ export type SchemaWithMetadata = SchemaObject & {
 export type ReadSpaceResult = {
     /** Fully resolved nodes produced by the plugin and enriched by core. */
     nodes: SpaceNode[];
-    /** 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[]>;
     /** Name of the plugin that produced the nodes. */

package/docs/config.md

@@ -20,7 +20,7 @@ A space is a named directory or single file registered in the config. Example:
     {
       "name": "ProductX",
       "path": "/path/to/space",
-      "schema": "general.json"
+      "schema": "strategy_general.json"
     }
   ]
 }

package/docs/schemas.md

@@ -20,11 +20,11 @@ Set `schema` in the space config entry:
 }
 ```
 
-Resolution order: space `schema` > global `schema` > bundled `schemas/general.json`.
+Resolution order: space `schema` > global `schema`. Schema resolution fails if none is configured.
 
 ## Bundled schemas
 
-### `general.json` (default)
+### `strategy_general.json`
 
 Flexible planning schema spanning strategy + OST-like flow.
 
@@ -258,8 +258,9 @@ Metadata is composed across the `$ref` graph with deterministic behavior:
 2. Apply root schema metadata last.
 
 Merge rules:
-- `hierarchy`: zero or one provider allowed. Multiple providers error.
-- `aliases`: shallow merged; later provider wins per key.
+- `hierarchy`: may be defined in partials; **last one wins**. This allows partials to define a default hierarchy that composing schemas can override.
+- `aliases`: shallow merged; later file wins per key.
+- `relationships`: collected from all files; order preserved.
 - `rules`: merged by `id`.
 - Duplicate rule `id` with different payload errors by default.
 - A later rule may replace an earlier one only with `"override": true`.
@@ -309,6 +310,8 @@ Imported rules are normalized into one executable flat list before validation.
 - Local partial `$id` values must not collide with bundled IDs.
 - `$ref` resolution is transitive across files.
 - Partials with no `$metadata` should prefer `$schema: "http://json-schema.org/draft-07/schema#"` so they validate standalone as plain JSON Schema fragments.
+- **Bundled partials as entity libraries**: `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, and `_ost_strict.json` provide reusable entity definitions and metadata. Composing schemas can reference these via `$ref` rather than redefining common entity types.
+- **Partials can carry metadata**: Partials may include `$metadata` (hierarchy, aliases, relationships, rules). This makes them self-contained units that bundle both type definitions and behavioral metadata.
 
 ## Editor expectations
 
@@ -328,7 +331,7 @@ For schemas migrating from older metadata structure:
 3. Move `allowSkipLevels` under `hierarchy`.
 4. Convert grouped rule containers to flat `rules[]` with per-rule `category`.
 5. If duplicate rule IDs are intentional, mark later rules with `override: true`.
-6. Re-run `bunx structured-context schemas show --space <name>` and `validate` to confirm merged metadata/rules.
+6. Re-run `sctx schemas show --space <name>` and `validate` to confirm merged metadata/rules.
 
 ## JSON5 support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Tools for working with Opportunity Solution Tree structures and other product management and strategy frameworks",
   "module": "./dist/index.js",
   "type": "module",