@davidorex/pi-context 0.30.0 → 0.32.0

package/dist/ops-registry.js

@@ -19,9 +19,9 @@
 import path from "node:path";
 import { Type } from "typebox";
 import { appendToBlock, appendToNestedArray, nextId, readBlock, readBlockDir, removeFromBlock, removeFromNestedArray, updateItemInBlock, updateNestedArrayItem, upsertItemInBlock, writeBlock, } from "./block-api.js";
-import { adoptConception, amendConfigEntry, loadConfig, loadContext } from "./context.js";
+import { adoptConception, amendConfigEntry, loadConfig } from "./context.js";
 import { BootstrapNotFoundError, schemaPath, tryResolveContextDir } from "./context-dir.js";
-import { appendRelationByRef, appendRelationsByRef, completeTask, contextState, currentState, deriveBootstrapState, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, removeRelationByRef, replaceRelationByRef, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
+import { appendRelationByRef, appendRelationsByRef, completeTask, contextState, currentState, deriveBootstrapState, endpointKey, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, removeRelationByRef, replaceRelationByRef, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
 import { gatherExecutionContext } from "./execution-context.js";
 // initProject + the switch/list/archive helpers are defined in index.ts (shared
 // with the /context command handlers + the context-* tools). This is a cyclic
@@ -29,12 +29,12 @@ import { gatherExecutionContext } from "./execution-context.js";
 // registerAll runs at extension-load time, after both modules' top-level
 // function bindings exist, and the helpers are only referenced inside op `run`
 // closures (lazy), never at this module's top level.
-import { archiveSubstrate, initProject, listSubstrates, switchAndCreate, switchToExisting, switchToPrevious, } from "./index.js";
-import { edgesForLensByName, findReferencesInRepo, validateContextRelations, walkAncestorsByLens, walkLensDescendants, } from "./lens-view.js";
+import { archiveSubstrate, checkStatus, initProject, installContext, listSubstrates, readCatalogSchemaText, resolveBlocked, resolveConflict, switchAndCreate, switchToExisting, switchToPrevious, updateContext, validateBlockItemsAgainstCatalog, } from "./index.js";
+import { edgesForLensByName, findReferencesInRepo, loadLensView, validateContextRelations, walkAncestorsByLens, walkLensDescendants, } from "./lens-view.js";
 import { promoteItem } from "./promote-item.js";
-import { addressInto, renderReadText, structureForRead } from "./read-element.js";
+import { addressInto, pageArray, renderReadText, structureForRead } from "./read-element.js";
 import { renameCanonicalId } from "./rename-canonical-id.js";
-import { listRoadmaps, loadRoadmap, renderRoadmap, validateRoadmaps } from "./roadmap-plan.js";
+import { loadRoadmap, renderRoadmap, validateRoadmap } from "./roadmap-plan.js";
 import { samplesCatalog } from "./samples-catalog.js";
 import { readSchema, writeSchemaChecked } from "./schema-write.js";
 import { truncateHead } from "./truncate.js";
@@ -115,37 +115,15 @@ export function boundedJsonOutput(r) {
     const { over, totalBytes } = overReadCap(s);
     return over ? { data: null, truncated: true, totalBytes, complete: false } : r.json;
 }
-// ── serializeRoadmapView ────────────────────────────────────────────────────
-// Strip non-serializable fields (suggestionTemplate fn, grouped Map) from the
-// embedded LoadedLensView records before tool serialization. Relocated verbatim
-// from the extension factory; consumed by the context-roadmap-load op.
-const serializeRoadmapView = (view) => ({
-    roadmap: view.roadmap,
-    phases: view.phases.map((pv) => ({
-        phase: pv.phase,
-        lensView: "error" in pv.lensView
-            ? pv.lensView
-            : {
-                lens: pv.lensView.lens,
-                items: pv.lensView.items,
-                edges: pv.lensView.edges,
-                grouped: Object.fromEntries(pv.lensView.grouped),
-                uncategorized: pv.lensView.uncategorized,
-            },
-        status: pv.status,
-        ...(pv.milestone ? { milestone: pv.milestone } : {}),
-        ...(pv.milestoneSatisfied !== undefined ? { milestoneSatisfied: pv.milestoneSatisfied } : {}),
-    })),
-    phaseOrder: view.phaseOrder,
-    cycles: view.cycles,
-    edges: view.edges,
-});
 export const ops = [
     {
         name: "append-block-item",
         label: "Append Block Item",
         description: "Append an item to an array in a project block file. Schema validation is automatic. Set autoId:true to allocate the next id from the block's id pattern when the item has no id.",
         promptSnippet: "Append items to project blocks (issues, decisions, or any user-defined block)",
+        examples: [
+            `pi-context append-block-item --block framework-gaps --arrayKey gaps --autoId true --item @/tmp/fgap.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'issues', 'decisions')" }),
             arrayKey: Type.String({ description: "Array key in the block (e.g., 'issues', 'decisions')" }),
@@ -183,6 +161,9 @@ export const ops = [
         label: "Update Block Item",
         description: "Update fields on an item in a project block array. Finds by predicate field match.",
         promptSnippet: "Update items in project blocks — change status, add details, mark resolved",
+        examples: [
+            `pi-context update-block-item --block tasks --arrayKey tasks --match '{"id":"TASK-001"}' --updates '{"status":"in-progress"}' --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'issues', 'decisions')" }),
             arrayKey: Type.String({ description: "Array key in the block" }),
@@ -205,14 +186,30 @@ export const ops = [
     {
         name: "append-relation",
         label: "Append Relation",
-        description: "Append a closure-table relation (edge: parent, child, relation_type, optional ordinal) to relations.json. " +
-            "Shape is AJV-validated; an exact-duplicate edge (same parent+child+relation_type) is a no-op. Reference " +
-            "integrity (endpoints resolve, relation_type registered, no cycle) is NOT checked here — run context-validate " +
-            "after. Creates relations.json if absent.",
-        promptSnippet: "Create a relation/edge between two items (parent→child under a relation_type)",
+        description: "Append a closure-table relation (edge: relation_type, optional ordinal) to relations.json. Orient the edge with " +
+            "EITHER raw --parent/--child OR the role-typed --primary/--counter (which maps to parent/child via the relation's " +
+            "declared role_direction); the two pairs are mutually exclusive. A bare --parent/--child append of a relation that " +
+            "is BOTH role-bearing and orientation-ambiguous (its source/target kinds overlap) is rejected — re-issue with " +
+            "--primary/--counter. Shape is AJV-validated; an exact-duplicate edge (same parent+child+relation_type) is a no-op. " +
+            "Reference integrity (endpoints resolve, relation_type registered, no cycle) is NOT checked here — run " +
+            "context-validate after. Creates relations.json if absent.",
+        promptSnippet: "Create a relation/edge between two items (raw --parent/--child, or role-typed --primary/--counter mapped via role_direction)",
+        examples: [
+            `pi-context append-relation --parent VER-001 --child TASK-001 --relation_type verification_verifies_item --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
-            parent: Type.String({ description: "Canonical id (or lens bin name) of the parent endpoint" }),
-            child: Type.String({ description: "Canonical id of the child endpoint" }),
+            parent: Type.Optional(Type.String({
+                description: "Parent-endpoint selector (canonical id / <alias>:<refname> / lens bin) — RAW orientation. Mutually exclusive with --primary/--counter.",
+            })),
+            child: Type.Optional(Type.String({
+                description: "Child-endpoint selector — RAW orientation. Mutually exclusive with --primary/--counter.",
+            })),
+            primary: Type.Optional(Type.String({
+                description: "Selector of the endpoint holding the relation's PRIMARY semantic role (ROLE-TYPED orientation; mapped to parent/child via the relation's declared role_direction). Requires --counter; the relation_type must declare role_direction.",
+            })),
+            counter: Type.Optional(Type.String({
+                description: "Selector of the endpoint holding the relation's COUNTER role (ROLE-TYPED orientation). Requires --primary.",
+            })),
             relation_type: Type.String({
                 description: "Registered relation_type canonical_id / hierarchy edge type / lens id",
             }),
@@ -222,26 +219,32 @@ export const ops = [
         surface: "use",
         run(cwd, params, ctx) {
             // Cycle-5 porcelain: STRING selectors (bare refname / <alias>:<refname> /
-            // lens-bin) are resolved to structured EdgeEndpoints and written via the
-            // raw plumbing. The param surface stays string-typed; messaging uses the
-            // raw selectors (params.*), not the resolved structured endpoints. Under
-            // dryRun the byRef fn validates the prospective relations + dedup-checks
-            // without writing (TASK-010 shared preview path).
-            const { appended } = appendRelationByRef(cwd, {
-                parent: params.parent,
-                child: params.child,
+            // lens-bin) are resolved to structured EdgeEndpoints and written via the raw
+            // plumbing. The append accepts EITHER raw --parent/--child OR the role-typed
+            // --primary/--counter form (FGAP-113); messaging renders the RESOLVED stored
+            // orientation (endpointKey of the returned edge), so a role-typed call reports
+            // the parent/child it actually filed. Under dryRun the byRef fn validates the
+            // prospective relations + dedup-checks without writing (TASK-010 shared
+            // preview path).
+            const { appended, edge } = appendRelationByRef(cwd, {
+                ...(params.parent !== undefined ? { parent: params.parent } : {}),
+                ...(params.child !== undefined ? { child: params.child } : {}),
+                ...(params.primary !== undefined ? { primary: params.primary } : {}),
+                ...(params.counter !== undefined ? { counter: params.counter } : {}),
                 relation_type: params.relation_type,
                 ...(params.ordinal !== undefined ? { ordinal: params.ordinal } : {}),
             }, ctx, { dryRun: params.dryRun });
+            const from = endpointKey(edge.parent);
+            const to = endpointKey(edge.child);
             const ordinalNote = params.ordinal !== undefined ? ` (ordinal ${params.ordinal})` : "";
             if (params.dryRun) {
                 return appended
-                    ? `would append relation ${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`
-                    : `would no-op (duplicate): relation ${params.parent} -[${params.relation_type}]-> ${params.child}`;
+                    ? `would append relation ${from} -[${params.relation_type}]-> ${to}${ordinalNote}`
+                    : `would no-op (duplicate): relation ${from} -[${params.relation_type}]-> ${to}`;
             }
             return appended
-                ? `Appended relation ${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`
-                : `Relation ${params.parent} -[${params.relation_type}]-> ${params.child} already exists — no-op`;
+                ? `Appended relation ${from} -[${params.relation_type}]-> ${to}${ordinalNote}`
+                : `Relation ${from} -[${params.relation_type}]-> ${to} already exists — no-op`;
         },
     },
     {
@@ -252,6 +255,9 @@ export const ops = [
             "inverse of append-relation (ordinal is NOT part of identity). An absent edge is an idempotent no-op. " +
             "Reference integrity is NOT checked here — run context-validate after if the removal changes resolvability.",
         promptSnippet: "Remove a relation/edge between two items (the inverse of append-relation)",
+        examples: [
+            `pi-context remove-relation --parent VER-001 --child TASK-001 --relation_type verification_verifies_item --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             parent: Type.String({ description: "Canonical id (or lens bin name) of the parent endpoint" }),
             child: Type.String({ description: "Canonical id of the child endpoint" }),
@@ -284,8 +290,13 @@ export const ops = [
         description: "Atomically replace one closure-table relation with another in a SINGLE write (no half-state: the old edge and " +
             "the new edge never coexist on disk). The old edge is matched on the (parent, child, relation_type) dedup identity; " +
             "the new edge is written with its optional ordinal. If the old edge is absent the call is effectively an append of " +
-            "the new edge. Reference integrity is NOT checked here — run context-validate after.",
+            "the new edge. This op takes RAW parent/child (old + new) and BYPASSES the write-time orientation gate that " +
+            "append-relation applies — it writes the endpoints verbatim, so it is the affordance for re-orienting an existing " +
+            "edge; reference integrity is NOT checked here — run context-validate after.",
         promptSnippet: "Atomically swap one relation/edge for another in a single write",
+        examples: [
+            `pi-context replace-relation --old_parent TASK-001 --old_child DEC-0001 --old_relation_type task_informed_by_decision --parent TASK-001 --child DEC-0002 --relation_type task_informed_by_decision --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             old_parent: Type.String({ description: "Parent endpoint selector of the edge to remove" }),
             old_child: Type.String({ description: "Child endpoint selector of the edge to remove" }),
@@ -340,14 +351,20 @@ export const ops = [
     {
         name: "append-relations",
         label: "Append Relations (bulk)",
-        description: "Append MANY closure-table relations to relations.json in a single write. Each edge is an object " +
-            "{ parent, child, relation_type, ordinal? }. Per-(parent, child, relation_type) duplicates are skipped (against " +
-            "on-disk edges AND earlier edges in the same batch). Returns appended/skipped counts. Reference integrity is NOT " +
-            "checked here — run context-validate after. Creates relations.json if absent.",
-        promptSnippet: "Create many relations/edges between items in one write",
+        description: "Append MANY closure-table relations to relations.json in a single write. Each edge is an object with " +
+            "{ relation_type, ordinal? } plus EITHER a raw { parent, child } pair OR the role-typed { primary, counter } pair " +
+            "(mapped to parent/child via the relation's declared role_direction); the two pairs are mutually exclusive per edge, " +
+            "and a bare { parent, child } for an orientation-ambiguous role-bearing relation rejects the whole batch before any " +
+            "write. Per-(parent, child, relation_type) duplicates are skipped (against on-disk edges AND earlier edges in the " +
+            "same batch). Returns appended/skipped counts. Reference integrity is NOT checked here — run context-validate " +
+            "after. Creates relations.json if absent.",
+        promptSnippet: "Create many relations/edges between items in one write (raw or role-typed per edge)",
+        examples: [
+            `pi-context append-relations --edges '[{"parent":"FEAT-008","child":"TASK-042","relation_type":"feature_decomposed_into_task"}]' --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             edges: Type.Unknown({
-                description: "JSON array of { parent, child, relation_type, ordinal? } selector objects (parent/child are id/lens-bin selectors)",
+                description: "JSON array of edge objects. Each edge is { relation_type, ordinal? } plus EITHER a raw { parent, child } pair OR the role-typed { primary, counter } pair (mapped to parent/child via the relation's declared role_direction); the two orientation pairs are mutually exclusive per edge. Selectors are id / <alias>:<refname> / lens-bin.",
             }),
             dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
         }),
@@ -364,12 +381,16 @@ export const ops = [
                 }
             }
             if (!Array.isArray(edges)) {
-                throw new Error(`edges parameter must be a JSON array of { parent, child, relation_type, ordinal? } objects`);
+                throw new Error(`edges parameter must be a JSON array of relation edge objects`);
             }
             // Under dryRun the byRef fn replays the on-disk + in-batch dedup and
             // validates the prospective relations without writing (TASK-010 shared
-            // preview path).
-            const { appended, skipped } = appendRelationsByRef(cwd, edges, ctx, { dryRun: params.dryRun });
+            // preview path). Each edge accepts raw {parent,child} or role-typed
+            // {primary,counter} (FGAP-113); orientation + the ambiguous-bare-append
+            // reject are applied inside appendRelationsByRef before any write.
+            const { appended, skipped } = appendRelationsByRef(cwd, edges, ctx, {
+                dryRun: params.dryRun,
+            });
             return params.dryRun
                 ? `would append ${appended}, skip ${skipped} (duplicates)`
                 : `appended ${appended}, skipped ${skipped} (duplicates)`;
@@ -382,6 +403,9 @@ export const ops = [
             "REPLACED (full-shape replacement, not shallow-merge — use update-block-item for merge); otherwise the item is " +
             "appended. Schema validation is automatic. idField defaults to 'id'.",
         promptSnippet: "Append-or-replace a full block item by id (replacement, not merge)",
+        examples: [
+            `pi-context upsert-block-item --block tasks --arrayKey tasks --item @/tmp/task.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'issues', 'decisions')" }),
             arrayKey: Type.String({ description: "Array key in the block (e.g., 'issues', 'decisions')" }),
@@ -423,6 +447,9 @@ export const ops = [
             "(unresolvable/non-item source, unregistered destination alias, unregistered destination relation_type, refname " +
             "collision) throw. Pass dryRun to compute the destination without writing.",
         promptSnippet: "Promote an item into another substrate as a derived copy with a lineage edge",
+        examples: [
+            `pi-context promote-item --source DEC-0001 --destinationSubstrate .context --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             source: Type.String({ description: "Source item selector (bare refname / <alias>:<refname>)" }),
             destinationSubstrate: Type.String({ description: "Registered destination substrate alias" }),
@@ -461,6 +488,9 @@ export const ops = [
         label: "Append Block Nested Item",
         description: "Append an item to a nested array on a parent-array item in a project block. Schema validation is automatic.",
         promptSnippet: "Append items to nested arrays inside parent items (e.g., findings inside a review)",
+        examples: [
+            `pi-context append-block-nested-item --block spec-reviews --arrayKey reviews --match '{"id":"REVIEW-001"}' --nestedKey findings --item @/tmp/finding.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'spec-reviews')" }),
             arrayKey: Type.String({ description: "Parent array key (e.g., 'reviews')" }),
@@ -493,6 +523,9 @@ export const ops = [
         label: "Update Block Nested Item",
         description: "Update fields on a nested-array item inside a parent-array item in a project block. Finds parent and nested by predicate field match. Throws on parent or nested miss (mirrors update-block-item semantics).",
         promptSnippet: "Update items inside nested arrays — change finding state, mark resolved",
+        examples: [
+            `pi-context update-block-nested-item --block spec-reviews --arrayKey reviews --match '{"id":"REVIEW-001"}' --nestedKey findings --nestedMatch '{"id":"F-001"}' --updates '{"state":"resolved"}' --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'spec-reviews')" }),
             arrayKey: Type.String({ description: "Parent array key (e.g., 'reviews')" }),
@@ -527,6 +560,9 @@ export const ops = [
         label: "Remove Block Item",
         description: "Remove items matching a predicate from a top-level array in a project block. Idempotent — returns { removed: 0 } on no match without throwing. Schema validation runs after removal.",
         promptSnippet: "Remove items from project blocks — prune retracted issues, dedupe entries",
+        examples: [
+            `pi-context remove-block-item --block issues --arrayKey issues --match '{"id":"ISSUE-001"}' --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'issues')" }),
             arrayKey: Type.String({ description: "Top-level array key (e.g., 'issues')" }),
@@ -546,6 +582,9 @@ export const ops = [
         label: "Remove Block Nested Item",
         description: "Remove items matching a predicate from a nested array on a parent-array item in a project block. Throws on parent miss; returns { removed: 0 } on nested miss without throwing.",
         promptSnippet: "Remove nested items — drop rejected findings, retract nested references",
+        examples: [
+            `pi-context remove-block-nested-item --block spec-reviews --arrayKey reviews --match '{"id":"REVIEW-001"}' --nestedKey findings --nestedMatch '{"id":"F-001"}' --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'spec-reviews')" }),
             arrayKey: Type.String({ description: "Parent array key (e.g., 'reviews')" }),
@@ -574,6 +613,7 @@ export const ops = [
         label: "Read Block Dir",
         description: "Enumerate and parse all .json files in a <substrate-dir>/<subdir>/ directory, returned as a sorted array. Missing directories return [].",
         promptSnippet: "Enumerate project block subdirectories (phases, schemas, etc.) as parsed JSON",
+        examples: [`pi-context read-block-dir --subdir phases --json`],
         parameters: Type.Object({
             subdir: Type.String({ description: "Subdirectory under the substrate dir (e.g., 'phases', 'schemas')" }),
         }),
@@ -589,6 +629,7 @@ export const ops = [
         label: "Read Block",
         description: "Read a project block file as structured JSON.",
         promptSnippet: "Read a project block as structured JSON",
+        examples: [`pi-context read-block --block tasks --json`],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'issues', 'tasks', 'requirements')" }),
         }),
@@ -611,6 +652,9 @@ export const ops = [
         label: "Write Block",
         description: "Write or replace an entire project block with schema validation.",
         promptSnippet: "Write or replace a project block with schema validation",
+        examples: [
+            `pi-context write-block --block architecture --data @/tmp/architecture.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'project', 'architecture')" }),
             data: Type.Unknown({ description: "Complete block data — must conform to block schema" }),
@@ -628,6 +672,7 @@ export const ops = [
         label: "Context Status",
         description: "Get derived context state — source metrics, block summaries, planning lifecycle status.",
         promptSnippet: "Get context state — source metrics, block summaries, planning lifecycle status",
+        examples: [`pi-context context-status --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
@@ -635,11 +680,24 @@ export const ops = [
             return { json: result };
         },
     },
+    {
+        name: "context-check-status",
+        label: "Context Check Status",
+        description: "Read-only installed-vs-catalog schema drift report — per installed schema the drift state, the baseline and catalog versions, and for behind schemas (catalog-ahead / both-diverged) the version delta (baseline -> catalog) or the content-only basis when the version string is unchanged. The front of the check-status -> update --dryRun -> update sequence. Like every substrate-lifecycle ceremony it seeds the catalog's config migration declarations into migrations.json (idempotent) before its first config read, so a version-lagging legacy substrate is diagnosable; beyond that seed it writes nothing.",
+        promptSnippet: "Report installed-vs-catalog schema drift + the version gap for behind schemas (read-only)",
+        examples: [`pi-context context-check-status --json`],
+        parameters: Type.Object({}),
+        surface: "use",
+        run(cwd, _params) {
+            return { json: checkStatus(cwd) };
+        },
+    },
     {
         name: "context-validate",
         label: "Context Validate",
         description: "Validate cross-block referential integrity — check that IDs referenced across blocks exist.",
         promptSnippet: "Validate cross-block referential integrity",
+        examples: [`pi-context context-validate --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
@@ -652,6 +710,7 @@ export const ops = [
         label: "Read Config",
         description: "Read the substrate config.json as structured JSON — vocabulary, lenses, relation_types, status_buckets, display_strings, layers, block_kinds, installed_schemas, installed_blocks. Address ONE registry/map via `registry` (e.g. relation_types) and ONE entry within it via `id` (canonical_id) instead of reading the whole config.",
         promptSnippet: "Read project config — vocabulary, lenses, relation_types, status_buckets",
+        examples: [`pi-context read-config --registry block_kinds --id tasks --json`],
         parameters: Type.Object({
             registry: Type.Optional(Type.String({
                 description: "Address ONE config registry/map by key (e.g. 'relation_types', 'lenses', 'block_kinds', 'status_buckets')",
@@ -673,10 +732,14 @@ export const ops = [
                     if (!entry.found) {
                         return `read-config: entry not found in ${params.registry} — ${entry.resolved}`;
                     }
-                    const read = structureForRead(entry.value, { label: `config.${params.registry}.${params.id}` });
+                    const read = structureForRead(entry.value, {
+                        whole: true,
+                        label: `config.${params.registry}.${params.id}`,
+                    });
                     return { read };
                 }
                 const read = structureForRead(reg.value, {
+                    whole: true,
                     label: `config.${params.registry}`,
                     overCapDirective: {
                         tool: "read-config",
@@ -730,7 +793,7 @@ export const ops = [
                 if (tool === undefined) {
                     return `list-tools: tool not found — name=${params.name}`;
                 }
-                const read = structureForRead(tool, { label: `tool ${params.name}` });
+                const read = structureForRead(tool, { whole: true, label: `tool ${params.name}` });
                 return { read };
             }
             // Default: compact index (FGAP-101) — name + param count + one-line description.
@@ -757,6 +820,7 @@ export const ops = [
         label: "Read Samples Catalog",
         description: "Enumerate installable sample block kinds (packaged view): per kind — title, description, item shape, applicable relation_types (as source/target), invariants, lenses — plus top-level relation_type/lens/invariant/layer/status_bucket registries. Package-intrinsic: reads the extension's bundled samples catalog, independent of any project. Optional `kind` returns one packaged kind.",
         promptSnippet: "Discover installable sample block kinds — title, shape, relation_types, invariants, lenses",
+        examples: [`pi-context read-samples-catalog --kind tasks --json`],
         parameters: Type.Object({
             kind: Type.Optional(Type.String({ description: "Filter to one block_kind canonical_id (e.g. 'tasks')" })),
         }),
@@ -768,17 +832,48 @@ export const ops = [
             const read = structureForRead(catalog, {
                 label: params.kind ? `samples kind=${params.kind}` : "samples catalog",
                 // Whole catalog → narrow by kind; a single kind has no finer
-                // addressing (edge → head-leading marker, no directive).
-                ...(params.kind ? {} : { overCapDirective: { tool: "read-samples-catalog", hint: "kind=<canonical_id>" } }),
+                // addressing (edge → head-leading marker, no directive). The
+                // single-kind read is an addressed node — return it whole (capped),
+                // never a 50-item page of an incidental array child.
+                ...(params.kind
+                    ? { whole: true }
+                    : { overCapDirective: { tool: "read-samples-catalog", hint: "kind=<canonical_id>" } }),
             });
             return { read };
         },
     },
+    {
+        name: "read-catalog-schema",
+        label: "Read Catalog Schema",
+        description: "Fetch and print the verbatim catalog schema body (raw JSON Schema: properties/definitions/$id) for a named block kind — diffable locally against the installed `<substrate>/schemas/<name>.schema.json` without touching node_modules. Read-only; the projection-returning sibling is read-samples-catalog.",
+        promptSnippet: "Fetch and print the verbatim catalog schema body for a named block kind (raw JSON Schema, diffable locally)",
+        examples: ["pi-context read-catalog-schema --kind tasks", "pi-context read-catalog-schema --kind tasks --json"],
+        parameters: Type.Object({
+            kind: Type.String({ description: "Catalog block_kind canonical_id (e.g. 'tasks')" }),
+        }),
+        surface: "use",
+        // The catalog schema file carries its own trailing newline (`}\n`); emit the file
+        // bytes exactly — preserving that single newline, appending none — so
+        // `read-catalog-schema --kind <k> | diff <installed> -` shows no phantom line when
+        // content matches (the pre-flag defect was the print path appending a second
+        // newline, doubling it to `}\n\n`).
+        verbatimText: true,
+        run(_cwd, params) {
+            // Package-intrinsic: reads the extension's bundled catalog schema file,
+            // not the project substrate — cwd is unused (like read-samples-catalog).
+            // Returns the RAW TEXT bytes as a prose-string OpResult so the verbatim
+            // catalog body prints as-is (renderOpResultText) and rides the --json
+            // envelope as a string; no {json}/{read} wrap that would re-serialize and
+            // alter the bytes the operator diffs.
+            return readCatalogSchemaText(params.kind).text;
+        },
+    },
     {
         name: "context-current-state",
         label: "Context Current State",
-        description: "Derive 'where are we + what's next' purely from the substrate — focus, in-flight tasks, ranked atomic-next actions (open framework-gaps then unblocked planned tasks), and blocked tasks. No writes; nothing hand-stored.",
-        promptSnippet: "Derive current project state — focus, in-flight, next actions, blocked",
+        description: "Derive 'where are we + what's next' purely from the substrate — focus, in-flight items, ranked atomic-next actions, blocked items, and milestone rollups. Every facet derives from the config-declared `state_derivation` registry: which block kinds + status bucket count as in-flight, the focus fallback kind + bucket, the ordered cross-kind next-actions push order with per-entry ranking (a named field + ordered value list, e.g. gap priority P0..P3) or topo ordering over the blocking-relation graph, the relation_types whose edges contribute blockers (the stock set being `task_depends_on_task` dependencies + `task_gated_by_item` gates), the membership rollups (e.g. milestones over `phase_positioned_in_milestone`) with their complete/incomplete status strings, and the next-actions head-size cap. A blocked item's dependency/gate target that has not reached the complete bucket is reported in blockedBy and held out of nextActions; a target reaching its complete status releases it. A substrate whose config declares no `state_derivation` reports focus 'state-derivation not configured' with empty arrays. No writes; nothing hand-stored.",
+        promptSnippet: "Derive current project state from the config-declared state_derivation registry — focus, in-flight, ranked next actions, blocked, milestone rollups",
+        examples: [`pi-context context-current-state --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
@@ -791,6 +886,7 @@ export const ops = [
         label: "Context Bootstrap State",
         description: "Derive the substrate bootstrap state for the cwd, purely from the filesystem: 'no-pointer' | 'no-config' | 'skeleton' | 'not-installed' | 'ready', plus the resolved contextDir and any declared-but-unmaterialized installed assets. Bootstrap (/context init or /context switch -c <new-dir>) now writes a minimal schema-valid config empty of vocabulary, so a freshly-bootstrapped substrate lands at 'skeleton' — onward via /context accept-all (adopt the packaged catalog, then /context install) OR amend-config / edit (build a custom vocabulary). Unlike every other tool, this NEVER throws on an un-bootstrapped substrate — it returns 'no-pointer' so you can detect a fresh substrate and tell the user to run /context init <substrate-dir> → /context accept-all → /context install (bootstrap requires user authorization via interactive confirmation). No writes.",
         promptSnippet: "Derive substrate bootstrap state — no-pointer | no-config | skeleton | not-installed | ready (never throws pre-bootstrap)",
+        examples: [`pi-context context-bootstrap-state --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
@@ -803,6 +899,7 @@ export const ops = [
         label: "Rename Canonical Id",
         description: "Rename a canonical_id (kind: item | relation_type | lens | layer) from oldId to newId across all substrate surfaces that carry it as DATA — item home block + relations.json edges, or the relevant config registries. Out-of-substrate occurrences (analysis MDs, git history) are REPORTED, never rewritten. block_kind renames are unsupported (filesystem cascade). Use dryRun to preview the would-change counts without writing.",
         promptSnippet: "Rename a canonical_id (item/relation_type/lens/layer) across substrate; dryRun to preview",
+        examples: [`pi-context rename-canonical-id --kind item --oldId TASK-001 --newId TASK-100 --dryRun true --json`],
         parameters: Type.Object({
             kind: Type.String({ description: "One of: item | relation_type | lens | layer" }),
             oldId: Type.String({ description: "Current canonical_id to rename from" }),
@@ -826,6 +923,9 @@ export const ops = [
             "relation_type / lens / layer / block_kind) is NOT checked here — run context-validate after. dryRun previews " +
             "without writing.",
         promptSnippet: "Add/replace/remove one entry in a config.json registry (vocabulary, lenses, invariants, status_buckets)",
+        examples: [
+            `pi-context amend-config --registry relation_types --operation add --key task_blocks_task --entry @/tmp/relation-type.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             registry: Type.String({
                 description: "One of: block_kinds | relation_types | lenses | layers | invariants | status_buckets | display_strings | naming | installed_schemas | installed_blocks | hierarchy",
@@ -869,6 +969,7 @@ export const ops = [
         label: "Read Schema",
         description: "Read a substrate schema by name as parsed JSON. Returns null when the schema file is absent. Address ONE property via `path` (dotted/bracket, e.g. properties.tasks.items.properties.status) instead of reading the whole schema.",
         promptSnippet: "Read a block schema as structured JSON — optionally address one property via `path`",
+        examples: [`pi-context read-schema --schemaName framework-gaps --path properties.gaps.items.required --json`],
         parameters: Type.Object({
             schemaName: Type.String({
                 description: "Schema name without extension (e.g., 'tasks', 'decisions', 'issues')",
@@ -886,7 +987,7 @@ export const ops = [
                 if (!addr.found) {
                     return `read-schema: property not found — ${addr.resolved}`;
                 }
-                const read = structureForRead(addr.value, { label: `${params.schemaName} ${addr.resolved}` });
+                const read = structureForRead(addr.value, { whole: true, label: `${params.schemaName} ${addr.resolved}` });
                 return { read };
             }
             const result = { schema, schemaPath: schemaPathStr };
@@ -910,6 +1011,9 @@ export const ops = [
             "read/write of items declaring an older schema_version throws version-mismatch. Registering the block_kind " +
             "that points at this schema is a separate step (amend-config block_kinds).",
         promptSnippet: "Create or replace a block-kind JSON Schema (meta-validated, atomic)",
+        examples: [
+            `pi-context write-schema --operation create --schemaName tasks --schema @/tmp/tasks.schema.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             operation: Type.String({ description: "create | replace" }),
             schemaName: Type.String({ description: "Schema name without extension (e.g., 'tasks')" }),
@@ -937,11 +1041,52 @@ export const ops = [
             return `write-schema: ${verb} schema '${params.schemaName}' at ${result.schemaPath}`;
         },
     },
+    {
+        name: "resolve-conflict",
+        label: "Resolve Schema Conflict",
+        description: "Commit the reconciliation of a schema merge conflict surfaced by update. Run this AFTER reconciling a both-diverged conflict update reported: it writes the reconciled schema body (meta-validated, atomic, operation 'replace') AND advances the merge base for that schema to the packaged catalog body. Advancing the base is the step a bare write-schema lacks — without it, update's 3-way merge re-derives the SAME conflict on every subsequent run because the base never moves off the original pre-conflict body. With the base advanced to the catalog, the next update sees the schema as locally-modified (base === catalog ≠ your body) and the deterministic merge takes your reconciled body (base === theirs → ours) — auto-merging with zero conflicts and preserving your resolution. If schema is omitted, the current on-disk schema is treated as already reconciled and only the base is advanced. The calling agent runs this; no subordinate resolver is spawned.",
+        promptSnippet: "Commit a reconciled schema conflict: write the resolved body + advance the merge base to the catalog so update stops re-reporting it (run after reconciling an update conflict)",
+        examples: [
+            `pi-context resolve-conflict --schemaName tasks --schema @/tmp/tasks.reconciled.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
+        parameters: Type.Object({
+            schemaName: Type.String({ description: "Schema name without extension (e.g., 'tasks')" }),
+            schema: Type.Optional(Type.Unknown({
+                description: "The reconciled schema body R (whole JSON Schema object, draft-07; accepts a JSON string). If omitted, the current on-disk schema is treated as already reconciled and only the merge base is advanced.",
+            })),
+        }),
+        surface: "use",
+        authGated: true,
+        run(cwd, params, ctx) {
+            const result = resolveConflict(cwd, params.schemaName, params.schema, ctx);
+            return { json: result };
+        },
+    },
+    {
+        name: "resolve-blocked",
+        label: "Resolve Blocked",
+        description: "Commit the resolution of a blocked schema surfaced by update. Run AFTER fixing the block's items (or widening the local schema): when the block file carries git-style failure markers (written by update), strips the full-line marker sentinels first, then re-validates the corrected block against the pinned target schema from the pending-blocked record; on pass registers the migration chain, writes the target schema, advances the merge base to the target (so a subsequent update converges instead of re-blocking), and clears the pending entry; on fail reports the remaining per-item failures and writes nothing. The commit is all-or-nothing: a throw partway through it restores every touched file byte-exact — migrations.json, the installed schema, the block file, config.json, and the pending record — and reports the failure, never a partial commit. On a substrate whose config carries no substrate_id, resolve-blocked establishes the identity at entry (mints, persists, registers) before the commit's stamping write and reports it under substrateIdEstablished.",
+        promptSnippet: "Commit a blocked schema's resolution: strip any git-style failure markers, re-validate the corrected block against the pinned target, then write the target schema + advance the base + clear the pending record (run after fixing the items update reported blocked)",
+        examples: [`pi-context resolve-blocked --schemaName tasks --yes --json`],
+        parameters: Type.Object({
+            schemaName: Type.String({
+                description: "Schema name with a pending-blocked entry (from update's blocked report)",
+            }),
+        }),
+        surface: "use",
+        authGated: true,
+        run(cwd, params, ctx) {
+            return { json: resolveBlocked(cwd, params.schemaName, ctx) };
+        },
+    },
     {
         name: "write-schema-migration",
         label: "Write Schema Migration",
-        description: "Declare a schema version-bump migration into substrate (migrations.json). operation 'create' appends a new declaration; 'replace' overwrites an existing declaration matched by (schemaName, fromVersion); 'remove' drops a declaration. kind='identity' asserts the bump is shape-compatible (no data transform); kind='declarative-transform' carries a TransformSpec of rename/set/delete/coerce operations on dotted JSON paths. The loaded MigrationRegistry resolves the recorded edge at next read/write so block items declaring an older schema_version walk forward without process restart. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer.",
+        description: "Declare a schema version-bump migration into substrate (migrations.json). operation 'create' appends a new declaration; 'replace' overwrites an existing declaration matched by (schemaName, fromVersion); 'remove' drops a declaration. kind='identity' asserts the bump is shape-compatible (no data transform); kind='declarative-transform' carries a TransformSpec of rename/set/delete/coerce/map_each operations on dotted JSON paths; map_each addresses an array — table mode maps each string element through a lookup (unmatched elements become {relation_type, item_endpoint} with parent/child fallback), set-on-each mode sets a field on every object element. The loaded MigrationRegistry resolves the recorded edge at next read/write so block items declaring an older schema_version walk forward without process restart. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer.",
         promptSnippet: "Declare a schema version-bump migration (identity or declarative-transform) into migrations.json",
+        examples: [
+            `pi-context write-schema-migration --operation create --schemaName tasks --fromVersion 1.0.0 --toVersion 1.1.0 --kind identity --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             operation: Type.String({ description: "create | replace | remove" }),
             schemaName: Type.String({ description: "Schema name without extension (e.g., 'tasks')." }),
@@ -975,6 +1120,7 @@ export const ops = [
         label: "Context Init",
         description: "Initialize the substrate dir: bootstrap pointer + dirs + a minimal schema-valid SKELETON config empty of vocabulary. Lands at the 'skeleton' bootstrap state — onward via accept-all (adopt the packaged catalog, then install) OR amend-config / edit (build a custom vocabulary).",
         promptSnippet: "Initialize the substrate dir (bootstrap pointer + dirs + skeleton config; onward via accept-all OR amend-config/edit)",
+        examples: [`pi-context context-init --contextDir .context --json`],
         parameters: Type.Object({
             contextDir: Type.String({
                 description: "Substrate dir name (e.g. .context). Required — no default.",
@@ -992,6 +1138,7 @@ export const ops = [
         label: "Accept-All Conception",
         description: "Adopt the canonical packaged conception (samples/conception.json) as this substrate's config.json (accept-all). Writes config only — run install after. Skeleton-aware: overwrites a SKELETON config (the empty-of-vocabulary config init / switch -c writes) but never a POPULATED one.",
         promptSnippet: "Adopt the canonical conception as config (accept-all)",
+        examples: [`pi-context context-accept-all --json`],
         parameters: Type.Object({}),
         surface: "use",
         authGated: true,
@@ -1009,11 +1156,65 @@ export const ops = [
             return { json: result };
         },
     },
+    {
+        name: "context-install",
+        label: "Context Install",
+        description: "Install (materialize) the schemas and starter blocks declared in config.json's installed_schemas / installed_blocks from the package samples catalog. Default skip-if-exists (installed files never overwritten without --update); populated block data is always preserved (even with --update); empty or absent blocks get the catalog starter. Records the install baseline (config.installed_from: catalog source + per-schema fingerprint) for installed-vs-catalog drift detection (schemas only). A re-install on an unchanged substrate is idempotent. On a substrate whose config carries no substrate_id, install establishes the identity at entry (mints, persists to config.json, registers in the project registry) and reports it under substrateIdEstablished; an established identity is never re-minted.",
+        promptSnippet: "Install declared schemas + starter blocks from the samples catalog (skip-if-exists; --update re-syncs schemas + replaces empty blocks; records the config.installed_from baseline)",
+        examples: ["pi-context context-install --json", "pi-context context-install --update true --json"],
+        parameters: Type.Object({
+            update: Type.Optional(Type.Boolean({
+                description: "When true, re-sync existing installed schemas (migration-aware) and replace empty blocks with the catalog starter; populated block data is never overwritten. When false (default), skip existing files.",
+            })),
+        }),
+        surface: "use",
+        authGated: true,
+        run(cwd, params) {
+            const result = installContext(cwd, { overwrite: params.update === true });
+            if (result.error)
+                return result.error;
+            return { json: result };
+        },
+    },
+    {
+        name: "update",
+        label: "Update Installed Model",
+        description: "Bring the installed substrate model (schemas) current with the packaged catalog. Per installed schema, consults the read-only drift check and routes by state: an already-current (in-sync) schema is a no-op; a schema the package shipped a newer version of (catalog-ahead) is re-synced through the migration-aware path; a schema edited locally (locally-modified / both-diverged) is reconciled by a deterministic 3-way merge of base (the as-installed body in the object store, keyed by the recorded baseline content_hash) × ours (the installed schema) × theirs (the catalog schema) — disjoint edits auto-merge so both the user's and the catalog's changes survive (required / enum / array-valued type nodes merge as sets), and a schema with irreconcilable per-path conflicts is left unmodified — the conflict set is returned in the op output (under conflicts) alongside a readable report, and the calling agent reconciles it then commits via resolve-conflict — which writes the reconciled body AND advances the merge base to the catalog so update stops re-reporting it (no subordinate resolver is spawned); undecidable / absent schemas (no-baseline / missing-catalog / missing-installed) are reported, not touched. Update also additively propagates catalog-new config-registry entries (relation_types / invariants / block_kinds / lenses) that are absent from the substrate config, preserving every user-authored entry and any locally-diverged body of an existing entry (additive-only — present entries are never overwritten). Update reports, under migrationsRegistered, the migration declarations a version-bump resync registers into migrations.json (each as schema / from / to). A blocked (refused) catalog-ahead schema additionally carries its diagnostic detail under blockedDetail (one entry per blocked schema): the refusal reason — no-migration-chain (no shipped chain reaches the catalog version) vs validation-failed (the forward-migrated items fail the catalog schema) vs write-failed (a non-validation throw at the write boundary, e.g. the block writer's duplicate-item-id guard; the failures entry carries the thrown message, the items were NOT flagged invalid, and no markers or pending-blocked record are produced) — the installed -> catalog version pair, and for a validation failure the per-item failures naming the failing item id, field, and constraint. A live blocked resync also persists a pending-blocked record (pinning the target catalog schema + the chain reaching it) consumable by resolve-blocked, which commits the resolution once the block's items are fixed. Pass dryRun to preview the per-schema action plan; dryRun predicts the precise per-schema catalog-ahead outcome (resync / migrate / block / merge / conflict) by running the forward-migration + re-validation in memory, the per-blocked-schema diagnostic detail, the config-registry entries that would be added, AND the migration declarations that would be registered, writing nothing beyond the idempotent ceremony seed of the catalog's config migration declarations into migrations.json (every substrate-lifecycle ceremony seeds at entry, before its first config read, so a version-lagging legacy substrate heals instead of throwing). When a catalog-ahead resync is blocked because the block's items fail the catalog schema (validation-failed), update inscribes git-style failure markers INTO the block file at the offending items (full-line `<<<<<<< BLOCKED …` / `>>>>>>> target: …` sentinels), pinning the pre-marker bytes so resolve-blocked can strip the markers and re-validate; the schema and migrations.json stay byte-unchanged. A dryRun preview writes no markers. Because update applies per-component (a blocked schema rolls back only itself; the additive registry propagation writes regardless), a run that refuses any schema while applying registry additions or other-schema resyncs/migrations/merges reports the partiality under partialApplication — applied and notApplied channel mirrors plus a one-line summary naming what was applied alongside what was refused and why — so a blocked run never reads as a no-op; dryRun reports the predicted partiality in the same shape. On a substrate whose config carries no substrate_id, a LIVE update establishes the identity at entry (mints, persists to config.json, registers in the project registry) before its first identity-stamping write — so a pre-identity substrate heals on the ceremony instead of refusing — and reports it under substrateIdEstablished; an established identity is never re-minted, and dryRun (no stamping writes) establishes nothing.",
+        promptSnippet: "Update the installed schema model from the catalog (3-way merges locally-modified schemas, preserving non-conflicting edits; conflicts → returned in the op output + a report for the calling agent to reconcile and commit via resolve-conflict; a blocked resync carries blockedDetail — reason (no-migration-chain / validation-failed / write-failed for a non-validation write-boundary throw), version pair, per-item failures — and a validation-failed block persists a pending-blocked record (target catalog schema + the chain reaching it) resolved via resolve-blocked once the block's items are fixed; a validation-failed block is marked in place with git-style failure markers (recoverable; stripped + re-validated by resolve-blocked); --dry-run predicts the precise per-schema outcome — resync / migrate / block / merge / conflict — via in-memory forward-migration + re-validation, writing nothing; a run that refuses any schema while applying registry additions or other-schema updates surfaces the partiality under partialApplication with a one-line summary, so a blocked run never reads as a no-op)",
+        examples: [`pi-context update --dryRun true --json`],
+        parameters: Type.Object({
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview the per-schema action plan without writing anything." })),
+        }),
+        surface: "use",
+        run(cwd, params) {
+            const result = updateContext(cwd, { dryRun: params.dryRun === true });
+            if (result.error)
+                return result.error;
+            return { json: result };
+        },
+    },
+    {
+        name: "validate-block-items",
+        label: "Validate Block Items",
+        description: "Validate a block's items against the catalog schema version — returns the per-item failures (item id, field, constraint) without writing. Resolves the block's catalog block_kind, loads the installed block, forward-migrates its items in memory through the shipped chain when the block lags the catalog version (a fresh registry; never warms the project's cache), and validates against the catalog schema body. Returns block / from (the block's declared version) / to (the catalog version) / valid / failures[] (each: itemId — the failing item's id when the instancePath resolves to one — instancePath, keyword, message). Read-only: never overwrites the schema, the block, or migrations.json. An unknown block or a missing installed block file throws.",
+        promptSnippet: "Validate a block's items against the catalog schema version — returns the per-item failures (item id, field, constraint) without writing",
+        examples: [`pi-context validate-block-items --block tasks --json`],
+        parameters: Type.Object({
+            block: Type.String({ description: "Block name (e.g. 'tasks')" }),
+        }),
+        surface: "use",
+        run(cwd, params) {
+            return { json: validateBlockItemsAgainstCatalog(cwd, params.block) };
+        },
+    },
     {
         name: "context-switch",
         label: "Context Switch",
         description: "Flip the bootstrap pointer to a different substrate dir (parallel to git switch). Default: flip to an existing substrate at target_dir (requires config.json present). create_new=true: bootstrap a fresh substrate at target_dir AND flip in one operation. to_previous=true: flip back to the pointer's previous_contextDir (target_dir ignored).",
         promptSnippet: "Switch the bootstrap pointer to a different substrate dir",
+        examples: [
+            `pi-context context-switch --target_dir .context --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             target_dir: Type.String({
                 description: "Substrate dir name to switch to (e.g. '.context'). Required for default + create_new modes; ignored for to_previous mode.",
@@ -1068,6 +1269,7 @@ export const ops = [
         label: "Context List",
         description: "Enumerate top-level dirs under cwd containing a config.json (switchable substrates). Marks the active one with isActive=true. Read-only.",
         promptSnippet: "List switchable substrate dirs under cwd",
+        examples: [`pi-context context-list --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
@@ -1080,6 +1282,9 @@ export const ops = [
         label: "Context Archive",
         description: "Move a non-active substrate dir to archive/<dir>/. Refuses to archive the active substrate (the dir the bootstrap pointer currently names) or to clobber an existing archive/<dir>/.",
         promptSnippet: "Archive a non-active substrate dir to archive/<dir>/",
+        examples: [
+            `pi-context context-archive --target_dir .context-old --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             target_dir: Type.String({
                 description: "Substrate dir name to archive (e.g. '.project'). Refused if it is the active substrate.",
@@ -1103,6 +1308,7 @@ export const ops = [
         label: "Filter Block Items",
         description: "Filter the array items of a block by a single-field predicate (eq / neq / in / matches). Discovers the single top-level array property in the block; items missing the predicate field are never matched. Wraps the canonical readBlock + caller-side filter into one queryable surface; never mutates the block.",
         promptSnippet: "Filter a block's items by a predicate — eq / neq / in / matches against a single field",
+        examples: [`pi-context filter-block-items --block framework-gaps --field status --op eq --value '"open"' --json`],
         parameters: Type.Object({
             block: Type.String({
                 description: "Block name (e.g., 'tasks', 'decisions', 'framework-gaps', 'context-contracts')",
@@ -1134,6 +1340,7 @@ export const ops = [
         label: "Resolve Item By Id",
         description: "Look up the block, array key, and item payload for a given ID across all blocks in the substrate dir. Returns null when no item matches. Mirrors the resolveItemById SDK function and shares its prefix-vs-block invariant — IDs whose prefix maps to a known block but live elsewhere throw at index-build time.",
         promptSnippet: "Resolve a kind-prefixed ID (DEC-/FEAT-/FGAP-/issue-/REQ-/TASK-/etc.) to its owning block and item",
+        examples: [`pi-context resolve-item-by-id --id TASK-001 --json`],
         parameters: Type.Object({
             id: Type.String({ description: "Kind-prefixed ID, e.g., DEC-NNNN / FEAT-NNN / FGAP-NNN / ISSUE-NNN" }),
         }),
@@ -1158,6 +1365,7 @@ export const ops = [
         label: "Read Block Item",
         description: "Read a single item from a named block by its id — returns the item or null. Block-scoped (unlike resolve-item-by-id, which searches all blocks by kind-prefixed id). Avoids fetching a whole large block to get one item.",
         promptSnippet: "Read one item from a block by id (block-scoped; null if absent)",
+        examples: [`pi-context read-block-item --block tasks --id TASK-001 --json`],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'tasks', 'decisions', 'framework-gaps')" }),
             id: Type.String({ description: "Item id within the block (e.g., 'TASK-NNN')" }),
@@ -1176,6 +1384,7 @@ export const ops = [
         label: "Read Block Page",
         description: "Paginate a block's items: returns { items, total, hasMore }. offset default 0, limit default 50. Use for blocks too large to fetch whole (past the 50KB read-block cap). total is the full item count; hasMore signals another page.",
         promptSnippet: "Paginate a block's items — offset + limit; returns {items,total,hasMore}",
+        examples: [`pi-context read-block-page --block tasks --limit 20 --json`],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'framework-gaps', 'decisions', 'issues')" }),
             offset: Type.Optional(Type.Integer({ minimum: 0, description: "Start index (default 0)" })),
@@ -1195,6 +1404,9 @@ export const ops = [
         label: "Join Blocks",
         description: "Join two blocks in one call. EDGE mode: pass `relationType` — pairs left items with right-block items connected by that relations.json edge (`leftEndpoint` parent|child, default parent). FIELD mode: pass `leftField`+`rightField` — pairs where left[leftField] === right[rightField]. Optional left pre-filter via where{Field,Op,Value}. Returns [{left, right:[]}] (right always an array; one-to-many). Use instead of N+1 read-block + resolve calls.",
         promptSnippet: "Join two blocks in one call — by relation edge or shared field; returns {left,right[]} pairs",
+        examples: [
+            `pi-context join-blocks --leftBlock tasks --rightBlock verification --relationType verification_verifies_item --leftEndpoint child --json`,
+        ],
         parameters: Type.Object({
             leftBlock: Type.String({ description: "Left block name (e.g., 'tasks')" }),
             rightBlock: Type.String({ description: "Right block name (e.g., 'verification')" }),
@@ -1237,6 +1449,7 @@ export const ops = [
         label: "Resolve Items By Id (Bulk)",
         description: "Bulk variant of resolve-item-by-id — resolve N kind-prefixed ids against a single buildIdIndex traversal. Returns an object mapping each input id to its ItemLocation (block / arrayKey / item) or null when not found. Coexists with the singular resolve-item-by-id tool; bulk collapses the N×singular-call pattern for callers resolving multiple ids in one render pass.",
         promptSnippet: "Resolve a batch of kind-prefixed ids (DEC-/FGAP-/TASK-/issue-/REQ-/...) in one call",
+        examples: [`pi-context resolve-items-by-id --ids '["TASK-001","DEC-0001","FGAP-042"]' --json`],
         parameters: Type.Object({
             ids: Type.Array(Type.String(), {
                 description: "Array of kind-prefixed ids (DEC-/FGAP-/TASK-/issue-/REQ-/...) to resolve in one call",
@@ -1259,6 +1472,9 @@ export const ops = [
         label: "Complete Task",
         description: "Complete a task with verification gate — requires a passing verification entry targeting the task.",
         promptSnippet: "Complete a task — gates on passing verification before updating status",
+        examples: [
+            `pi-context complete-task --taskId TASK-001 --verificationId VER-001 --writer '{"kind":"human","user":"you@example.com"}' --json`,
+        ],
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ID to complete" }),
             verificationId: Type.String({
@@ -1276,6 +1492,7 @@ export const ops = [
         label: "Context Validate Relations",
         description: "Validate substrate relations.json edges against config-declared lenses + hierarchy + relation_types and the cross-block id index. Returns SubstrateValidationResult with status (clean/warnings/invalid) and per-issue diagnostics.",
         promptSnippet: "Validate substrate relations against config + items",
+        examples: [`pi-context context-validate-relations --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
@@ -1288,6 +1505,7 @@ export const ops = [
         label: "Context Edges For Lens",
         description: "Materialize the Edge[] for a named lens — synthetic edges from derived_from_field for auto-derived lenses; authored edges filtered by relation_type for hand-curated lenses; unioned items from composition members for kind=composition lenses.",
         promptSnippet: "Materialize edges for a named lens (auto-derived or hand-curated)",
+        examples: [`pi-context context-edges-for-lens --lensId feature-decomposition --json`],
         parameters: Type.Object({
             lensId: Type.String({ description: "Lens id from config.lenses[].id" }),
         }),
@@ -1298,11 +1516,51 @@ export const ops = [
             return { read };
         },
     },
+    {
+        name: "context-lens-view",
+        label: "Context Lens View",
+        description: "Project a config-declared lens (config.lenses[]) as a binned item-view. Without --bin, a bin->count summary (always under the read cap). With --bin, that bin's items paged by --offset/--limit. Serves target, composition, and hand-curated lenses.",
+        promptSnippet: "Project a config-declared lens as a binned item-view — bin->count summary, or one bin's items paged",
+        examples: [
+            `pi-context context-lens-view --lensId gaps-by-status --json`,
+            `pi-context context-lens-view --lensId gaps-by-status --bin identified --limit 20 --json`,
+        ],
+        parameters: Type.Object({
+            lensId: Type.String({ description: "Lens id from config.lenses[].id" }),
+            bin: Type.Optional(Type.String({ description: "Return this bin's items paged; omit for a bin->count summary" })),
+            offset: Type.Optional(Type.Integer({ minimum: 0, description: "Per-bin page start index (default 0)" })),
+            limit: Type.Optional(Type.Integer({ minimum: 1, description: "Per-bin page size (default 50)" })),
+        }),
+        surface: "use",
+        run(cwd, params) {
+            const view = loadLensView(cwd, params.lensId);
+            if ("error" in view)
+                throw new Error(view.error); // unknown lens / no-config -> non-zero exit
+            if (params.bin !== undefined) {
+                const items = view.grouped.get(params.bin);
+                if (items === undefined)
+                    throw new Error(`Bin '${params.bin}' not declared on lens '${params.lensId}'. Bins: ${view.lens.bins.join(", ")}`);
+                const page = pageArray(items, { offset: params.offset, limit: params.limit });
+                return { read: structureForRead(page, { whole: true, label: `lens ${params.lensId} bin ${params.bin}` }) };
+            }
+            const summary = {
+                lens: view.lens.id,
+                kind: view.lens.kind ?? "target",
+                bins: Object.fromEntries(view.lens.bins.map((b) => [b, (view.grouped.get(b) ?? []).length])),
+                uncategorized: view.uncategorized.length,
+                total: view.items.length,
+            };
+            return { read: structureForRead(summary, { whole: true, label: `lens ${params.lensId} bins` }) };
+        },
+    },
     {
         name: "context-walk-descendants",
         label: "Context Walk Descendants",
-        description: "Walk closure-table descendants of a parent id under a given relation_type. Returns string[] of descendant ids (may be empty if no children or relations.json absent).",
+        description: "Walk closure-table descendants of a parent id under a given relation_type. Returns string[] of descendant ids (may be empty if no children or relations.json absent). For a DISJOINT-kind relation, querying from the wrong (target-kind) end THROWS naming walk-ancestors instead of silently returning []; same-kind / wildcard relations return [] honestly.",
         promptSnippet: "Walk closure-table descendants under a relation_type",
+        examples: [
+            `pi-context context-walk-descendants --parentId FEAT-008 --relationType feature_decomposed_into_task --json`,
+        ],
         parameters: Type.Object({
             parentId: Type.String({ description: "Parent id (canonical id or lens bin name)" }),
             relationType: Type.String({ description: "Relation type from config.relation_types[].canonical_id" }),
@@ -1316,8 +1574,9 @@ export const ops = [
     {
         name: "walk-ancestors",
         label: "Walk Ancestors",
-        description: "Walk closure-table ancestors of an item id under a given relation_type — reverse-direction counterpart to context-walk-descendants. Returns string[] of ancestor ids (may be empty if no parents or relations.json absent).",
+        description: "Walk closure-table ancestors of an item id under a given relation_type — reverse-direction counterpart to context-walk-descendants. Returns string[] of ancestor ids (may be empty if no parents or relations.json absent). For a DISJOINT-kind relation, querying from the wrong (source-kind) end THROWS naming context-walk-descendants instead of silently returning []; same-kind / wildcard relations return [] honestly.",
         promptSnippet: "Walk closure-table ancestors under a relation_type",
+        examples: [`pi-context walk-ancestors --itemId TASK-042 --relationType feature_decomposed_into_task --json`],
         parameters: Type.Object({
             itemId: Type.String({ description: "Child item id whose ancestors are sought" }),
             relationType: Type.String({ description: "Relation type from config.relation_types[].canonical_id" }),
@@ -1334,6 +1593,7 @@ export const ops = [
         label: "Find References",
         description: "Find all closure-table edges incident on an item id (inbound, outbound, or both). Returns Edge[] preserving relation_type + ordinal per record — edge-level view, not the id-chain projection that walk-ancestors / context-walk-descendants emit.",
         promptSnippet: "Find closure-table edges incident on an item id",
+        examples: [`pi-context find-references --itemId TASK-001 --direction both --json`],
         parameters: Type.Object({
             itemId: Type.String({ description: "Item id whose incident edges are sought" }),
             direction: Type.Optional(Type.Union([Type.Literal("inbound"), Type.Literal("outbound"), Type.Literal("both")], {
@@ -1352,6 +1612,7 @@ export const ops = [
         label: "Gather Execution Context",
         description: "Compose a ContextBundle for a work-unit by reading its context-contract (by unit_kind) and walking declared relation_types bidirectionally per direction semantic. Returns unit + perRelationType buckets of resolved items + traversal_depth + scoped_at. Substrate primitive serving harness-confined dispatch.",
         promptSnippet: "Compose ContextBundle for unit + context-contract-declared bundle_relation_types",
+        examples: [`pi-context gather-execution-context --unitId TASK-001 --kind task --json`],
         parameters: Type.Object({
             unitId: Type.String({ description: "Work-unit id (e.g. TASK-NNN / DEC-NNNN / FGAP-NNN)" }),
             kind: Type.String({
@@ -1374,71 +1635,45 @@ export const ops = [
     {
         name: "context-roadmap-load",
         label: "Context: load roadmap",
-        description: "Load a roadmap by id and return the materialized RoadmapView (phases, lens-views, status rollup, milestone resolution, scoped phase_depends_on edges, topo-ordered phaseOrder + cycles). Phase ordering lives in relations.json with relation_type='phase_depends_on'.",
-        promptSnippet: "Load a roadmap by id",
-        parameters: Type.Object({
-            roadmapId: Type.String({ description: "ROADMAP-NNN id from <config.root>/roadmap.json" }),
-        }),
+        description: "Load the derived roadmap view over the milestone_precedes_milestone DAG: milestone-block items topo-ordered by the authored precedes edges (order + cycles), each milestone carrying its derived status/phaseCount (currentState's milestone rollup), its member phases (parents of phase_positioned_in_milestone edges), each phase's tasks (parents of task_positioned_in_phase edges), and per-phase + per-milestone status rollups. Adjacency comes strictly from the authored edges — never inferred from order. Zero milestones is a valid empty view.",
+        promptSnippet: "Load the derived milestone roadmap view",
+        examples: [`pi-context context-roadmap-load --json`],
+        parameters: Type.Object({}),
         surface: "use",
-        run(cwd, params) {
-            const view = loadRoadmap(cwd, params.roadmapId);
-            if ("error" in view) {
-                const read = structureForRead(view, { whole: true, label: `roadmap ${params.roadmapId} (error)` });
-                return { read };
-            }
-            // whole: a structured RoadmapView (phases + lens-views + rollups) — keep
-            // the view shape intact rather than paging an inner array.
-            const read = structureForRead(serializeRoadmapView(view), {
-                whole: true,
-                label: `roadmap ${params.roadmapId}`,
-            });
+        run(cwd, _params) {
+            const view = loadRoadmap(cwd);
+            // whole: a structured MilestoneRoadmapView (milestones + rollups + edges)
+            // — keep the view shape intact rather than paging an inner array.
+            const read = structureForRead(view, { whole: true, label: "roadmap (derived)" });
             return { read };
         },
     },
     {
         name: "context-roadmap-render",
         label: "Context: render roadmap",
-        description: "Render a roadmap by id as pure-textual markdown — phase order list, per-phase adjacency lines (sourced from view.edges, alphabetically sorted), status rollup counts, milestone resolution, exit criteria. NO mermaid / graph syntax: per-phase **Depends on:** lines come strictly from authored phase_depends_on edges scoped to in-roadmap phases.",
-        promptSnippet: "Render a roadmap as markdown",
-        parameters: Type.Object({
-            roadmapId: Type.String({ description: "ROADMAP-NNN id from <config.root>/roadmap.json" }),
-        }),
+        description: "Render the derived roadmap as pure-textual markdown — milestone order list (topo over the authored milestone_precedes_milestone edges), per-milestone sections with **Preceded by:** adjacency lines sourced strictly from those edges (alphabetically sorted; '—' when none), per-milestone rollup counts, and per-phase task tables. Cycle participants surface under a separate heading with a Cycles-detected line. NO mermaid / graph syntax; adjacency is never inferred from order consecutive pairs.",
+        promptSnippet: "Render the derived milestone roadmap as markdown",
+        examples: [`pi-context context-roadmap-render`],
+        parameters: Type.Object({}),
         surface: "use",
-        run(cwd, params) {
-            const view = loadRoadmap(cwd, params.roadmapId);
+        run(cwd, _params) {
+            const view = loadRoadmap(cwd);
             if ("error" in view) {
                 return { json: view };
             }
-            const naming = loadContext(cwd).config?.naming;
-            return renderRoadmap(view, naming);
+            return renderRoadmap(view);
         },
     },
     {
         name: "context-roadmap-validate",
-        label: "Context: validate roadmap(s)",
-        description: "Validate every roadmap × phase × milestone in <config.root>/roadmap.json. Codes: roadmap_lens_missing, roadmap_phase_dep_missing, roadmap_phase_cycle, roadmap_composition_cycle, roadmap_milestone_evidence_block_missing, roadmap_milestone_query_invalid, roadmap_status_unknown_value. Display strings flow through config.display_strings (pi-context divergence). Optional roadmapId filter restricts issue list to a single roadmap.",
-        promptSnippet: "Validate roadmaps",
-        parameters: Type.Object({
-            roadmapId: Type.Optional(Type.String({ description: "Filter to issues matching this roadmap_id (omit for full-project validation)" })),
-        }),
-        surface: "use",
-        run(cwd, params) {
-            const result = validateRoadmaps(cwd);
-            const filtered = params.roadmapId
-                ? result.issues.filter((i) => !i.roadmap_id || i.roadmap_id === params.roadmapId)
-                : result.issues;
-            return { json: { status: result.status, issues: filtered } };
-        },
-    },
-    {
-        name: "context-roadmap-list",
-        label: "Context: list roadmaps",
-        description: "List every roadmap in <config.root>/roadmap.json with id, title, optional status, and phase count. Returns [] when roadmap.json absent (opt-in block; absence is the truthful answer).",
-        promptSnippet: "List roadmaps",
+        label: "Context: validate roadmap",
+        description: "Validate the derived roadmap over the milestone_precedes_milestone edges. Error codes: roadmap_precedes_endpoint_missing (a precedes-edge endpoint that is not a milestone-block item), roadmap_milestone_cycle (a cycle in the precedes graph), roadmap_milestone_missing (a phase_positioned_in_milestone edge whose child is not a known milestone). Warning: roadmap_status_unknown_value (a member phase whose task rollup buckets unknown with items present). Info: roadmap_milestone_isolated (a milestone with zero precedes edges while others are ordered) — info never affects status: invalid iff any error-code issue, warnings iff any warning-code issue, else clean. Display strings flow through config.display_strings (pi-context divergence).",
+        promptSnippet: "Validate the derived milestone roadmap",
+        examples: [`pi-context context-roadmap-validate --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
-            return { json: listRoadmaps(cwd) };
+            return { json: validateRoadmap(cwd) };
         },
     },
 ];