@davidorex/pi-context 0.26.0

package/samples/schemas/story.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/story",
+  "version": "1.0.0",
+  "title": "Stories",
+  "description": "Top-level user-story / story array-block (FGAP-064 elevation). Stories are a work-altitude between feature and task: a feature decomposes into stories, a story decomposes into tasks. Cross-altitude relationships (feature→story, story→task, story→story dependency, story→gating-item, story→milestone/phase/project-goal) live in relations.json closure-table edges per DEC-0013 — NOT as inline arrays on the story. Sub-shape is structural (id/title/status/description/acceptance_criteria); the Agile user-story form (role/want/benefit) is a future optional enrichment, not imposed (DEC-deferred per FGAP-064 — no role/want/benefit present in current data, none fabricated).",
+  "type": "object",
+  "required": [
+    "stories"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "stories": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "title",
+          "status"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^STORY-\\d{3,}$",
+            "description": "Stable canonical id; STORY-NNN (3+ digits)."
+          },
+          "title": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "proposed",
+              "ready",
+              "in-progress",
+              "in-review",
+              "complete",
+              "blocked"
+            ],
+            "description": "Story lifecycle. Intentionally divergent from pi-context://schemas/status; reconciliation tracked in FGAP-021."
+          },
+          "description": {
+            "type": "string",
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
+          },
+          "acceptance_criteria": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "created_by": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "modified_by": {
+            "type": "string"
+          },
+          "modified_at": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/samples/schemas/tasks.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/tasks",
+  "version": "1.0.0",
+  "title": "Tasks",
+  "description": "Discrete units of work with status lifecycle (planned, in-progress, completed, blocked, cancelled). The operational layer between gaps/requirements and code changes.",
+  "type": "object",
+  "required": ["tasks"],
+  "properties": {
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "description", "status"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^TASK-\\d{3,}$" },
+          "description": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } },
+          "status": { "type": "string", "enum": ["planned", "in-progress", "completed", "blocked", "cancelled"] },
+          "files": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Files this task creates or modifies"
+          },
+          "acceptance_criteria": {
+            "type": "array",
+            "items": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } }
+          },
+          "assigned_agent": { "type": "string", "description": "Agent name if assigned" },
+          "notes": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } }
+        }
+      }
+    }
+  }
+}

package/samples/schemas/verification.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/verification",
+  "version": "1.0.0",
+  "title": "Verification",
+  "description": "Evidence that work meets its criteria. Per-item completion evidence linking implementation to acceptance via a verification_verifies_item edge.",
+  "type": "object",
+  "required": ["verifications"],
+  "properties": {
+    "verifications": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "method"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^VER-\\d{3,}$" },
+          "status": { "type": "string", "enum": ["passed", "failed", "partial", "skipped"] },
+          "method": { "type": "string", "enum": ["command", "inspect", "test"] },
+          "evidence": { "type": "string", "description": "What was checked and what was found" },
+          "timestamp": { "type": "string" },
+          "criteria_results": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["criterion", "status"],
+              "properties": {
+                "criterion": { "type": "string" },
+                "status": { "type": "string", "enum": ["passed", "failed", "skipped"] },
+                "evidence": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/bootstrap.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/bootstrap",
+  "version": "1.0.0",
+  "title": "pi-context bootstrap pointer",
+  "description": "Per-cwd bootstrap pointer at <cwd>/.pi-context.json declaring the substrate dir name. Read by resolveContextDir(cwd) before any substrate operation; substrate dir is config-driven per DEC-0015 (no hardcoded substrate-dir paths anywhere in pi-context, pi-jit-agents, pi-workflows, pi-behavior-monitors). Atomic-safety mechanism per FGAP-026 closure phase 1.1: written for legacy .project/-using repos containing {contextDir: '.project'} so substrate stays reachable when Phase 1.2 lands resolveContextDir replacing PROJECT_DIR + SCHEMAS_DIR constants. For new repos: written by /context init (prompt-required for dirName per DEC-0015; defaulting reintroduces hardcode-dressed-as-default this DEC rejects). Mutable post-init via /context migrate (Phase 10 of FGAP-026 closure) which atomically renames the dir + rewrites this pointer + updates config.root.",
+  "type": "object",
+  "properties": {
+    "contextDir": {
+      "type": "string",
+      "description": "Directory name (relative to cwd) where the substrate lives. User-decided at /context init time per DEC-0015. For pre-existing repos using legacy .project/ convention, value is '.project' until /context migrate runs."
+    },
+    "version": {
+      "type": "string",
+      "description": "Bootstrap pointer format version. '1.0.0' for the initial format. Future format changes increment via semver per FGAP-006 schema versioning discipline; migration registry handles transitions if breaking."
+    },
+    "created_at": {
+      "type": "string",
+      "description": "ISO 8601 timestamp when the bootstrap pointer was first written. Forensic; helps trace when the substrate was bootstrapped for this repo."
+    }
+  },
+  "required": ["contextDir"],
+  "additionalProperties": false
+}

package/schemas/config.schema.json

@@ -0,0 +1,193 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/config",
+	"version": "1.4.0",
+	"title": "pi-context substrate config",
+	"description": "Self-bootstrapping config block. Validates the config that configures the substrate. ConfigBlock is the canonical registry for block kinds, status buckets, relation types, display strings, layers, naming aliases, hierarchy declarations, and lens specs. Closes FGAP-001 (hierarchical block storage), FGAP-013 (status vocabulary registry), issue-089 class (PLAN- prefix collision) by making registries config-driven from line 1.",
+	"type": "object",
+	"required": ["schema_version", "block_kinds"],
+	"additionalProperties": false,
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"pattern": "^\\d+\\.\\d+\\.\\d+$",
+			"description": "Semver of this config schema. Surfaces FGAP-006 at the meta-layer."
+		},
+		"root": {
+			"type": "string",
+			"description": "Optional substrate-dir override. The substrate-dir name is set at /context init and recorded in the .pi-context.json bootstrap pointer (DEC-0015 — no shipped default); adoptConception writes this field at /context accept-all from the init-chosen dir. When absent, projectRoot resolves the substrate via the pointer (resolveContextDir). Not shipped by the packaged conception, which is a template. Closes GitHub issue #3 surface — relocatable per config."
+		},
+		"naming": {
+			"type": "object",
+			"description": "Canonical-id → user-facing-name alias map. Code references canonical ids; UI/macros render configured names. Decouples terminology from code.",
+			"additionalProperties": { "type": "string" }
+		},
+		"layers": {
+			"type": "array",
+			"description": "Work-altitude tier registry (L1..L5 or user-defined). FGAP-016 layer registry surface.",
+			"items": {
+				"type": "object",
+				"required": ["id", "display_name"],
+				"additionalProperties": false,
+				"properties": {
+					"id": { "type": "string" },
+					"display_name": { "type": "string" },
+					"description": { "type": "string" }
+				}
+			}
+		},
+		"block_kinds": {
+			"type": "array",
+			"description": "Canonical block-kind registry. Replaces the previously hardcoded ID_PREFIX_TO_BLOCK table — prefix conflicts surface at config-registration time, not at fixture-write time.",
+			"items": {
+				"type": "object",
+				"required": ["canonical_id", "display_name", "prefix", "schema_path", "array_key", "data_path"],
+				"additionalProperties": false,
+				"properties": {
+					"canonical_id": { "type": "string", "description": "Opaque identifier (e.g. 'decisions-block')" },
+					"display_name": { "type": "string", "description": "Mutable user-facing label (e.g. 'Design Decisions')" },
+					"prefix": { "type": "string", "description": "Id-prefix token (e.g. 'DEC-'). Empty string is valid for slug-id blocks (e.g. conventions) that do not use prefix+number ids — such blocks are excluded from prefix-based id resolution (FGAP-062)." },
+					"schema_path": { "type": "string", "description": "Relative path to schema file" },
+					"array_key": { "type": "string", "description": "Top-level array property in block JSON" },
+					"data_path": { "type": "string", "description": "Relative path to block data file" },
+					"layer": { "type": "string", "description": "FK to layers[].id (optional)" }
+				}
+			}
+		},
+		"status_buckets": {
+			"type": "object",
+			"description": "Per-project status normalization. Maps raw status string → bucket. FGAP-013 closure surface.",
+			"additionalProperties": {
+				"type": "string",
+				"enum": ["complete", "in_progress", "blocked", "todo", "unknown"]
+			}
+		},
+		"display_strings": {
+			"type": "object",
+			"description": "Validation-code / opaque-slug → display label map.",
+			"additionalProperties": { "type": "string" }
+		},
+		"relation_types": {
+			"type": "array",
+			"description": "Canonical relation_type registry (DEC-0013 single-source-of-truth pattern).",
+			"items": {
+				"type": "object",
+				"required": ["canonical_id", "display_name", "category"],
+				"additionalProperties": false,
+				"properties": {
+					"canonical_id": { "type": "string" },
+					"display_name": { "type": "string" },
+					"category": { "type": "string", "enum": ["ordering", "data_flow", "membership"] },
+					"cycle_allowed": { "type": "boolean" },
+					"source_kinds": { "type": "array", "items": { "type": "string" }, "description": "Block_kind canonical_ids this relation's source (edge.parent) may be; literal \"*\" = any kind. Optional; absence => endpoint-kind unchecked." },
+					"target_kinds": { "type": "array", "items": { "type": "string" }, "description": "Block_kind canonical_ids this relation's target (edge.child) may be; literal \"*\" = any kind. Optional; absence => endpoint-kind unchecked." }
+				}
+			}
+		},
+		"invariants": {
+			"type": "array",
+			"description": "Config-declared substrate invariants enforced generically by validateProject. Each names block kinds / relation_types / status values purely as DATA — no vocabulary literal lives in source (DEC-0025). User-overridable: a project ships only the invariants its conception requires. Discriminated by `class`: requires-edge (item must occupy an endpoint on ≥1 edge of a given relation_type) or status-consistency (an item's status bucket must/must-not co-occur with a related item's status bucket across an edge).",
+			"items": {
+				"oneOf": [
+					{
+						"type": "object",
+						"required": ["id", "class", "block", "relation_types", "direction"],
+						"additionalProperties": false,
+						"properties": {
+							"id":           { "type": "string", "description": "Stable invariant id, surfaced in diagnostics + the issue code field." },
+							"class":        { "type": "string", "const": "requires-edge", "description": "Invariant class: qualifying items must occupy an endpoint on an edge of one of relation_types." },
+							"block":        { "type": "string", "description": "Data-file basename of the block whose items the invariant ranges over (matched against ItemLocation.block)." },
+							"where":        { "type": "object", "description": "Optional field-equality predicate. Item qualifies only when EVERY (field,value) matches item[field] === value. Absent → all items qualify.", "additionalProperties": { "type": ["string", "number", "boolean"] } },
+							"relation_types": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "canonical_ids of relation_types that satisfy the invariant. Qualifying item passes if ≥1 incident edge (in direction) has relation_type in this set." },
+							"direction":    { "type": "string", "enum": ["as_parent", "as_child"], "description": "Which endpoint the qualifying item must occupy. as_parent → item.id === edge.parent; as_child → item.id === edge.child." },
+							"severity":     { "type": "string", "enum": ["error", "warning"], "default": "error", "description": "Diagnostic severity when unsatisfied." },
+							"message":      { "type": "string", "description": "Optional message template. Tokens {id} and {block} substitute. Absent → generic default." }
+						}
+					},
+					{
+						"type": "object",
+						"required": ["id", "class", "block", "relation_types", "direction"],
+						"additionalProperties": false,
+						"properties": {
+							"id":           { "type": "string", "description": "Stable invariant id, surfaced in diagnostics + the issue code field." },
+							"class":        { "type": "string", "const": "status-consistency", "description": "Invariant class: a qualifying item's status bucket must (require_target_bucket) or must-not (forbid_target_bucket) co-occur with a related item's status bucket across an incident edge." },
+							"block":        { "type": "string", "description": "Data-file basename of the block whose items the invariant ranges over (matched against ItemLocation.block)." },
+							"relation_types": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "canonical_ids of relation_types whose edges are inspected for the related (target) item." },
+							"direction":    { "type": "string", "enum": ["as_parent", "as_child"], "description": "Which endpoint the qualifying item occupies on the inspected edge; the target item is the other endpoint." },
+							"when_bucket":  { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Optional gate: only items whose own status bucket equals this are checked. Absent → all items in block are checked." },
+							"require_target_bucket": { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Violation when the target item's status bucket differs from this. Mutually exclusive with forbid_target_bucket at runtime." },
+							"forbid_target_bucket":  { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Violation when the target item's status bucket equals this. Mutually exclusive with require_target_bucket at runtime." },
+							"severity":     { "type": "string", "enum": ["error", "warning"], "default": "error", "description": "Diagnostic severity when violated." },
+							"message":      { "type": "string", "description": "Optional message template. Tokens {id} and {block} substitute. Absent → generic default." }
+						}
+					}
+				]
+			}
+		},
+		"hierarchy": {
+			"type": "array",
+			"description": "Constraint declaration: which (parent_block, child_block, relation_type) edges are legal in relations.json.",
+			"items": {
+				"type": "object",
+				"required": ["parent_block", "child_block", "relation_type"],
+				"additionalProperties": false,
+				"properties": {
+					"parent_block": { "type": "string" },
+					"child_block": { "type": "string" },
+					"relation_type": { "type": "string" }
+				}
+			}
+		},
+		"lenses": {
+			"type": "array",
+			"description": "Named projections over a target block (or a composition over multiple). Supports kind=target (single target) and kind=composition (members reference sub-lenses or {from, where} item-filters).",
+			"items": {
+				"type": "object",
+				"required": ["id", "bins"],
+				"additionalProperties": false,
+				"properties": {
+					"id": { "type": "string" },
+					"kind": { "type": "string", "enum": ["target", "composition"] },
+					"target": { "type": "string", "description": "Canonical block id (kind=target)" },
+					"targets": {
+						"type": "array",
+						"description": "Block ids the composition spans (kind=composition)",
+						"items": { "type": "string" }
+					},
+					"members": {
+						"type": "array",
+						"description": "Composition members — sub-lens reference or {from, where} item-filter",
+						"items": {
+							"type": "object",
+							"additionalProperties": false,
+							"properties": {
+								"lens": { "type": "string" },
+								"from": { "type": "string" },
+								"where": {
+									"type": "object",
+									"additionalProperties": {
+										"type": ["string", "number", "boolean"]
+									}
+								}
+							}
+						}
+					},
+					"relation_type": { "type": "string" },
+					"derived_from_field": { "type": ["string", "null"] },
+					"bins": { "type": "array", "items": { "type": "string" } },
+					"render_uncategorized": { "type": "boolean", "default": true }
+				}
+			}
+		},
+		"installed_schemas": {
+			"type": "array",
+			"description": "Schemas the project has opted into via /context install (DEC-0011).",
+			"items": { "type": "string" }
+		},
+		"installed_blocks": {
+			"type": "array",
+			"description": "Blocks the project has opted into via /context install (DEC-0011).",
+			"items": { "type": "string" }
+		}
+	}
+}

package/schemas/layer.schema.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/layer",
+	"version": "1.0.0",
+	"title": "Layer canonical enum",
+	"description": "Opaque canonical layer IDs (work-altitude tiers L1..L5). Display names per project come from config.layers[].display_name.",
+	"type": "string",
+	"enum": ["L1", "L2", "L3", "L4", "L5"]
+}

package/schemas/priority.schema.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/priority",
+	"version": "1.0.0",
+	"title": "Priority canonical enum",
+	"description": "Opaque canonical priority IDs. Display labels per consumer come from config.priority_buckets.",
+	"type": "string",
+	"enum": ["p-low", "p-medium", "p-high", "p-critical"]
+}

package/schemas/relations.schema.json

@@ -0,0 +1,31 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/relations",
+	"version": "1.0.0",
+	"title": "pi-context closure-table relations",
+	"description": "Generic closure-table substrate. One row per (parent, child, relation_type) edge. Multiple parallel hierarchies coexist as different relation_type values. Reassignment is a single field write. The schema is intentionally permissive on edge.parent's namespace — disambiguation between hierarchy edges (parent ∈ canonical ids) and lens edges (parent ∈ lens.bins) is cross-document and lives at substrate-SDK validateRelations(). Cycle detection lives at SDK traversal primitives.",
+	"type": "array",
+	"items": {
+		"type": "object",
+		"required": ["parent", "child", "relation_type"],
+		"additionalProperties": false,
+		"properties": {
+			"parent": {
+				"type": "string",
+				"description": "Either a canonical id (DEC-NNNN, FGAP-NNN, issue-NNN) or a bin name from a lens definition. Mixing is intentional — a lens bin acts as a virtual parent node."
+			},
+			"child": {
+				"type": "string",
+				"description": "Canonical id of the member item."
+			},
+			"relation_type": {
+				"type": "string",
+				"description": "Lens id, hierarchy edge type, or registered relation_type canonical_id. Allows multiple parallel hierarchies over the same items."
+			},
+			"ordinal": {
+				"type": "integer",
+				"description": "Optional sibling-ordering within (parent, relation_type)."
+			}
+		}
+	}
+}

package/schemas/severity.schema.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/severity",
+	"version": "1.0.0",
+	"title": "Severity canonical enum",
+	"description": "Opaque canonical severity IDs. Display labels per consumer come from config.display_strings or equivalent registry.",
+	"type": "string",
+	"enum": ["info", "warning", "error"]
+}

package/schemas/source.schema.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/source",
+	"version": "1.0.0",
+	"title": "Source canonical enum",
+	"description": "Opaque canonical source IDs identifying which actor produced a piece of substrate state (human, agent run, monitor classification, workflow execution).",
+	"type": "string",
+	"enum": ["human", "agent", "monitor", "workflow"]
+}

package/schemas/status.schema.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/status",
+	"version": "1.0.0",
+	"title": "Status canonical enum",
+	"description": "Opaque canonical status IDs. Display labels per consumer come from config.status_buckets normalization. Matches POC-C StatusBucket vocabulary.",
+	"type": "string",
+	"enum": ["todo", "in_progress", "blocked", "complete", "unknown"]
+}

package/schemas/verification-method.schema.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/verification-method",
+	"version": "1.0.0",
+	"title": "Verification method canonical enum",
+	"description": "Opaque canonical verification-method IDs identifying how a verification claim is to be substantiated.",
+	"type": "string",
+	"enum": ["command", "grep", "ast", "inspect", "human", "test"]
+}

package/skill-narrative.md

@@ -0,0 +1,130 @@
+---
+name: pi-context
+description: >
+  Schema-driven project state management with typed JSON blocks, schema validation,
+  substrate config, lens views, closure-table relations, and cross-block referential
+  integrity. Use when managing .project/ blocks, scaffolding project structure,
+  installing block kinds from the packaged samples catalog, validating project state,
+  rendering lens views, or adding work items.
+---
+
+<objective>
+pi-context manages structured project state in `.project/` — a directory of JSON block files validated against schemas. The substrate (config + lenses + closure-table relations) is degree-zero state that defines where the rest lives and how items group into views.
+</objective>
+
+<block_files>
+Blocks are JSON files under the substrate root (e.g., `gaps.json`, `decisions.json`). Each block has a corresponding schema in `<root>/schemas/`. When you write to a block via the tools, the data is validated against its schema before persisting. Writes are atomic (tmp file + rename) and serialised per block via `withBlockLock`. The substrate root is the dir chosen at init (recorded in the `.pi-context.json` bootstrap pointer) and written to `config.json`'s `root` field by `/context accept-all`; the framework ships no default (DEC-0015). block-api routes through `resolveContextDir(cwd)` — which resolves `config.root` when set and otherwise falls back to the pointer — so a relocated root reaches every read/write site.
+</block_files>
+
+<schema_validation>
+Every block write validates against `<root>/schemas/<blockname>.schema.json`. If the schema file doesn't exist, writes proceed without validation. Validation errors include the specific JSON Schema violations.
+</schema_validation>
+
+<context_init>
+`/context init <dir>` creates the substrate skeleton: the `.pi-context.json` bootstrap pointer (declaring the substrate-dir name per DEC-0015) plus the substrate root and its `schemas/` directory. Nothing is imposed — no `config.json`, no schemas, and no starter blocks are written (DEC-0011 ship-no-defaults). Idempotent: re-running preserves existing dirs. Populate the substrate next with `/context accept-all` (adopt the canonical conception) followed by `/context install`.
+</context_init>
+
+<context_accept_all>
+`/context accept-all` adopts the package's canonical packaged conception (`samples/conception.json`) as the substrate's `config.json` — the full vocabulary (`block_kinds`, `relation_types`, `lenses`, `invariants`) plus the `installed_schemas` / `installed_blocks` manifest — with `root` set to the actual substrate dir. It writes `config.json` only (run `/context install` after to materialize the schemas + starter blocks) and is idempotent: it never overwrites an existing `config.json` (offer, don't impose). This is the accept-all path; per-entry step-through curation is a separate surface.
+</context_accept_all>
+
+<context_install>
+`/context install` reconciles the substrate against the `installed_schemas` and `installed_blocks` lists declared in `config.json`. For each declared name it copies the matching asset from the package-shipped samples catalog (`samples/schemas/` for schemas, `samples/blocks/` for starter blocks) into the substrate. Default behavior is skip-if-exists (preserves user edits); pass `--update` to overwrite and report the asset as `updated`. Sources missing from the catalog are reported as `notFound`. Empty install lists are not an error — the result is a clean no-op message instructing the user to edit `config.json`.
+
+The installable catalog IS the packaged conception (`samples/conception.json`): its `block_kinds` enumerate the available kinds, each carrying its schema (`samples/schemas/`) and starter block (`samples/blocks/`). The generated installable-catalog table below lists the authoritative names — declare any subset in `installed_*` and run `/context install`, or take the whole conception via `/context accept-all`.
+</context_install>
+
+<substrate_config>
+`.project/config.json` is the substrate bootstrap. Its `root` field declares where every other block, schema, agent, and template lives — closing the GitHub #3 surface where downstream consumers had to assume `.project/`. `naming` aliases canonical block ids to display names (used by `/context view` rendering). `hierarchy` declares legal closure-table edges (parent block → child block via relation_type). `lenses` declares named projections over a target block. `installed_schemas` / `installed_blocks` are the install manifest consumed by `/context install`.
+
+`config.json` and `relations.json` are exempt from `root` redirection — they always live at `.project/` because they are the substrate that defines `root`. All other state lives under `<config.root>/...` per `resolveContextDir(cwd)`. The package ships their schemas in `schemas/` (config.schema.json, relations.schema.json) and resolves them via three-tier search: project override > user override > package-shipped.
+
+The `loadContext(cwd)` SDK returns an mtime-keyed cached snapshot of `{ config, relations, configMtime, relationsMtime }` for one cwd. Consumers must not mutate.
+</substrate_config>
+
+<lens_views>
+Lenses are named projections over a target block. A lens declares `id`, `target` (block name), `relation_type`, `derived_from_field` (optional — synthesizes edges from a per-item field instead of requiring authored edges), `bins` (named groupings), and `render_uncategorized`.
+
+Edges live in `.project/relations.json` as a closure table — each row is `{ parent, child, relation_type }`. `parent` is either a canonical id (hierarchy edges) or a lens.bins value (lens edges); disambiguation lives in `validateRelations`.
+
+The lens-view algorithm: `edgesForLens(lens, items, authoredEdges)` returns synthetic edges (when `derived_from_field` is set) or filtered authored edges (otherwise). `groupByLens(items, lens, lensEdges)` produces a `Map<binName, ItemRecord[]>`. `walkDescendants(parentId, relationType, edges)` traverses the closure table from any parent.
+
+`/context view <lensId>` loads the lens via `loadLensView(cwd, lensId)`, runs `groupByLens`, and renders the result as markdown headings + bullet lines (id + status + title) into the conversation via `renderLensView`. `lens.render_uncategorized: false` omits the uncategorized bucket.
+</lens_views>
+
+<context_lens_curate>
+`/context lens-curate <lensId>` walks items in the lens's target block that have no edge in any declared bin and surfaces bin-assignment suggestions (would-be `relations.json` edge appends) as a follow-up turn. The LLM reads the suggestions and persists the chosen edges via `append-block-item` against `relations.json`. The command itself does not write — curation is a follow-up-turn pattern so the model decides which suggestions to enact.
+</context_lens_curate>
+
+<context_view>
+`/context view <lensId>` renders a configured lens as markdown into the conversation. Bins become headings, items become bullet lines (id + status + title where present). `naming` aliases from config.json are honored for the target block name. Errors (missing config, unknown lens, unreadable target block, no array property in target) surface via `ctx.ui.notify` with severity `error`.
+</context_view>
+
+<substrate_validation>
+`validateRelations(cwd)` (exposed as the `context-validate-relations` tool) checks the closure-table edges in `relations.json` against the config + per-block item snapshots. Diagnostics codes: `edge_unknown_relation_type`, `edge_parent_not_in_bins`, `edge_unresolved_parent`, `edge_unresolved_child`, `edge_parent_wrong_block`, `edge_child_wrong_block`, `edge_cycle_detected`. Returns `{ status: "clean" | "warnings" | "invalid", issues[] }` where each issue carries the offending edge or cycle path.
+
+Two derived substrate tools complement validation: `context-edges-for-lens` returns the materialized `Edge[]` for a named lens (synthetic from `derived_from_field` or filtered authored edges); `context-walk-descendants` returns the transitive descendant id list from a parent under a given relation_type.
+</substrate_validation>
+
+<block_item_reads>
+Item-level reads complement whole-block `read-block` (which is all-or-nothing and caps at the 50KB read limit): `read-block-item` returns one item from a named block by its id (block-scoped — null if absent; distinct from `resolve-item-by-id`, which searches every block by kind-prefixed id). `read-block-page` paginates a block too large to fetch whole — `{ items, total, hasMore }` where `total` is the full item count and pagination uses `offset`/`limit` (defaults 0/50).
+`join-blocks` — one-call cross-block join, EDGE mode (relations.json relation_type, leftEndpoint parent|child) or FIELD mode (shared field value), optional left pre-filter; returns {left, right[]} pairs; replaces N+1 read+resolve.
+</block_item_reads>
+
+<context_status>
+`/context status` derives project state dynamically from the filesystem:
+- Source file count and line count (`.ts` files excluding tests)
+- Test count and test file count
+- Schema count, block count, phase count
+- Block summaries with array item counts and status distributions
+- Requirements summary (total, by status, by priority) — from requirements.json (if installed)
+- Tasks summary (total, by status) — from tasks.json (if installed)
+- Domain entry count — from domain.json (if installed)
+- Verification summary (total, passed, failed) — from verification.json (if installed)
+- Handoff presence — whether handoff.json exists
+- Recent git commits
+- Current phase detection
+</context_status>
+
+<context_add_work>
+`/context add-work` discovers appendable blocks (blocks with array schemas), reads their schemas, and sends a structured instruction to the LLM to extract items from the conversation into the typed blocks. This is a follow-up message that triggers the LLM to use the `append-block-item` tool.
+</context_add_work>
+
+<duplicate_detection>
+`append-block-item` checks for duplicate items by `id` field before appending. If an item with the same `id` already exists in the target array, it returns a message instead of appending.
+</duplicate_detection>
+
+<context_validate>
+Two separate validators address two concerns:
+
+`/context validate` (the `context-validate` tool) checks cross-block referential integrity:
+- task.phase references a valid phase
+- task.depends_on references valid task IDs
+- decision.phase references a valid phase
+- gap.resolved_by references a valid ID
+- requirement.traces_to references valid phase/task IDs
+- requirement.depends_on references valid requirement IDs
+- verification.target references a valid target ID
+- rationale.related_decisions references valid decision IDs
+
+Returns errors (broken dependency references) and warnings (unresolved cross-references).
+
+The `context-validate-relations` tool (see `<substrate_validation>`) validates closure-table edges in `relations.json` — a separate concern from cross-block ID resolution.
+</context_validate>
+
+<update_check>
+On `session_start`, checks npm registry for newer versions of `@davidorex/pi-project-workflows` and notifies via UI if an update is available. Non-blocking — failures are silently ignored.
+</update_check>
+
+<success_criteria>
+- `.project/`, `.project/schemas/`, `.project/phases/`, and `.project/config.json` exist after `/context init`
+- `installed_schemas` / `installed_blocks` declared in `config.json` are reified by `/context install`; `--update` overwrites
+- Block writes validate against schemas — invalid data rejected with specific error
+- `/context status` returns current derived state without errors
+- `/context validate` returns no errors for well-formed cross-block references
+- `context-validate-relations` returns no errors for a well-formed `relations.json`
+- `/context view <lensId>` renders the configured projection; `/context lens-curate <lensId>` surfaces suggestions for uncategorized items
+- `append-block-item` rejects duplicate IDs
+- Schema customizations (field additions, enum changes) take effect on next write
+- A relocated `config.root` reaches every read/write because all path construction routes through `resolveContextDir(cwd)`
+</success_criteria>