structured-context 0.9.0 → 0.9.1

package/README.md

@@ -1,11 +1,58 @@
 # structured-context
 
-Tools for working with Opportunity Solution Tree structures and other product management and strategy frameworks
+Keep your content clean and your thinking clear.
+
+`structured-context` provides assistive tools for working with structured content, including knowledge wikis (a la [Karpathy](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)), product/strategy frameworks (like [Teresa Torres' Opportunity Solution Trees](https://www.producttalk.org/opportunity-solution-trees/) and [Martin et al's strategy cascade](https://rogerlmartin.com/thought-pillars/strategy), and more. Great for flat sets of documents, hierarchical or layered context trees, or any kind of knowledge graph.
+
+Assign a schema to your markdown content to give humans and AI agents consistent structure and content guidelines. 
+
+In Claude Code:
+```
+❯ Use /structured-context to configure 'my-research' as a knowledge wiki, then organise it
+
+⏺ Skill(structured-context)
+  ⎿  Successfully loaded skill
+
+...
+
+```
+
+Command line tools:
+```
+> sctx validate strategy
+
+Space Validation Results
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Content and structure
+  Valid                                   16
+  Schema validation errors                 0
+  Broken links                             1
+  Duplicate keys                           0
+  Rule violations                          2
+  Hierarchy violations                     0
+  Orphans (hierarchy nodes - no parent)    1
+  Ignored during parsing                   0
+
+Orphans (hierarchy nodes - no parent):
+   Solution looking for a problem.md
+
+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
+```
 
 ## Installation
 
 Requires [Bun](https://bun.sh) runtime.
 
+Install globally (recommended):
+
 ```bash
 bun install -g structured-context
 ```
@@ -18,10 +65,11 @@ bunx structured-context validate <space>
 
 ## Setup for AI Agents
 
-A Claude Code plugin is included at `plugin/`. It provides validation hooks, slash commands, and agent skills. Install it with:
+Claude Code plugin, providing validation hooks, slash commands, and agent skills. Install it with:
 
 ```
-claude plugin install mindsocket/structured-context
+claude plugin marketplace add mindsocket/structured-context
+claude plugin install structured-context
 ```
 
 Skills can also be installed standalone without the plugin:
@@ -38,31 +86,24 @@ See [docs/concepts.md](docs/concepts.md) for the full terminology reference, inc
 
 `structured-context` looks for its config file in this order:
 
-1. `$SCTX_CONFIG` — explicit path override
-2. `~/.config/structured-context/config.json` (or `$XDG_CONFIG_HOME/structured-context/config.json`)
-3. `./config.json` in the current working directory
+1. `--config` command line argument
+2. `$SCTX_CONFIG` env var
+3. `~/.config/structured-context/config.json` (or `$XDG_CONFIG_HOME/structured-context/config.json`)
+4. `./config.json` in the current working directory
 
-See `config.example.json` for the full structure. The config maps space names to paths, with optional Miro integration fields and global defaults. Paths in config files are resolved relative to the config file.
+See `config.example.json` for the full structure. The config maps space names to paths, with optional additional configuration options for parsing and integrations. Paths in config files are resolved relative to the config file.
 
 **Including spaces from other configs:** Use `includeSpacesFrom` to import space definitions from other config files. This is useful for aggregating spaces from multiple projects into a central config, reducing the need to specify `--config` on CLI commands. Duplicate space names are not allowed.
 
 **Plugins and markdown plugin config:** See `sctx docs config` for the full reference including `fieldMap`, `typeInference`, `templateDir`, filter views, and plugin loading rules.
 
-### Spaces
-
-A space is a named directory or single file registered in the config. Spaces let you reference content by name instead of path:
-
-```bash
-sctx validate ProductX
-```
-
 ### Schemas
 
 Schemas define the structure and rules for the entities in a space, allowing customisation and extension to different models.
 
-Two schemas (`general` and `strict_ost`) are included. The general 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.
+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.
 
-sctx 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 Draft-07 that adds a top-level `$metadata` block:
 
 ```json5
 "$metadata": {
@@ -91,8 +132,6 @@ sctx schemas use a metaschema based on JSON Schema Draft-07 that adds a top-leve
 }
 ```
 
-Rules are a flat array (`rules[]`) with per-rule `category`.
-
 Schema hierarchy levels support DAG (multi-parent) relationships via configurable edge fields. Each entry in `$metadata.hierarchy.levels` can be a plain type name string (defaults to `parent` field on child nodes) or an object:
 
 ```json5

package/dist/commands/validate.js

@@ -106,7 +106,7 @@ export async function validate(context, options = {}) {
         duplicateErrors: [],
         ruleViolations: [],
         hierarchyViolations: [],
-        orphanCount: 0,
+        orphans: [],
         parseIgnored: parseIgnored || [],
     };
     for (const node of nodes) {
@@ -143,7 +143,7 @@ export async function validate(context, options = {}) {
     result.hierarchyViolations = [...hierarchyValidation.violations];
     // Calculate orphan count (informational, not a validation error)
     if (metadata.hierarchy) {
-        result.orphanCount = buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans.length;
+        result.orphans = [...buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans];
     }
     // Load and execute rules validation if schema defines rules
     if (metadata.rules) {
@@ -187,7 +187,7 @@ export async function validate(context, options = {}) {
             validCount: result.validCount,
             errorCount,
             errors: errorsByFile,
-            orphanCount: result.orphanCount,
+            orphanCount: result.orphans.length,
             parseIgnored: result.parseIgnored,
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
@@ -223,8 +223,13 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Duplicate keys', result.duplicateErrors.length, true));
     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.orphanCount, true, 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));
+    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)

package/dist/config.js

@@ -98,13 +98,24 @@ function resolveRelativePaths(config, configDir) {
             return p;
         return resolve(configDir, p);
     };
+    const relSchema = (p) => {
+        if (!p || isAbsolute(p) || isUrl(p))
+            return p;
+        if (!p.includes('/') && !p.includes('\\')) {
+            const localPath = resolve(configDir, p);
+            if (existsSync(localPath))
+                return localPath;
+            return join(bundledSchemasDir, p);
+        }
+        return resolve(configDir, p);
+    };
     return {
         ...config,
-        schema: rel(config.schema),
+        schema: relSchema(config.schema),
         spaces: config.spaces.map((s) => ({
             ...s,
             path: rel(s.path),
-            schema: rel(s.schema),
+            schema: relSchema(s.schema),
             plugins: normalizePlugins(s.plugins),
         })),
     };

package/dist/schemas/knowledge_wiki.json

@@ -9,7 +9,9 @@
       "study": "source",
       "article": "source",
       "paper": "source",
-      "research": "source"
+      "research": "source",
+      "comparison": "synthesis",
+      "query": "synthesis"
     },
     "relationships": [
       {
@@ -26,6 +28,13 @@
         "fieldOn": "child",
         "multiple": true
       },
+      {
+        "parent": "source",
+        "type": "entity",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
       {
         "parent": "concept",
         "type": "synthesis",
@@ -134,6 +143,36 @@
         }
       ]
     },
+    {
+      "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.",

package/package.json

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

package/schemas/knowledge_wiki.json

@@ -9,7 +9,9 @@
       "study": "source",
       "article": "source",
       "paper": "source",
-      "research": "source"
+      "research": "source",
+      "comparison": "synthesis",
+      "query": "synthesis"
     },
     "relationships": [
       {
@@ -26,6 +28,13 @@
         "fieldOn": "child",
         "multiple": true
       },
+      {
+        "parent": "source",
+        "type": "entity",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
       {
         "parent": "concept",
         "type": "synthesis",
@@ -134,6 +143,36 @@
         }
       ]
     },
+    {
+      "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.",