@davidorex/pi-context 0.30.0 → 0.31.0

package/dist/ops-registry.js

@@ -29,10 +29,10 @@ 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 { samplesCatalog } from "./samples-catalog.js";
@@ -146,6 +146,9 @@ export const ops = [
         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 +186,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" }),
@@ -210,6 +216,9 @@ export const ops = [
             "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)",
+        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" }),
@@ -252,6 +261,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" }),
@@ -286,6 +298,9 @@ export const ops = [
             "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.",
         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" }),
@@ -345,6 +360,9 @@ export const ops = [
             "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",
+        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)",
@@ -382,6 +400,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 +444,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 +485,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 +520,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 +557,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 +579,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 +610,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 +626,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 +649,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 +669,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 +677,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; 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 +707,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 +729,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 +790,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 +817,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 +829,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",
+        examples: [`pi-context context-current-state --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
@@ -791,6 +883,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 +896,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 +920,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 +966,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 +984,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 +1008,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 +1038,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.",
+        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.",
         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 +1117,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 +1135,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 +1153,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.",
+        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) — 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. 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.",
+        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, version pair, per-item failures — and 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)",
+        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 +1266,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 +1279,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 +1305,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 +1337,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 +1362,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 +1381,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 +1401,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 +1446,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 +1469,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 +1489,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 +1502,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 +1513,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).",
         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" }),
@@ -1318,6 +1573,7 @@ export const ops = [
         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).",
         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 +1590,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 +1609,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({
@@ -1376,6 +1634,7 @@ export const ops = [
         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",
+        examples: [`pi-context context-roadmap-load --roadmapId ROADMAP-001 --json`],
         parameters: Type.Object({
             roadmapId: Type.String({ description: "ROADMAP-NNN id from <config.root>/roadmap.json" }),
         }),
@@ -1400,6 +1659,7 @@ export const ops = [
         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",
+        examples: [`pi-context context-roadmap-render --roadmapId ROADMAP-001`],
         parameters: Type.Object({
             roadmapId: Type.String({ description: "ROADMAP-NNN id from <config.root>/roadmap.json" }),
         }),
@@ -1418,6 +1678,7 @@ export const ops = [
         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",
+        examples: [`pi-context context-roadmap-validate --roadmapId ROADMAP-001 --json`],
         parameters: Type.Object({
             roadmapId: Type.Optional(Type.String({ description: "Filter to issues matching this roadmap_id (omit for full-project validation)" })),
         }),
@@ -1435,6 +1696,7 @@ export const ops = [
         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",
+        examples: [`pi-context context-roadmap-list --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {