@davidorex/pi-context 0.29.0 → 0.31.0

package/dist/ops-registry.js

@@ -18,10 +18,10 @@
  */
 import path from "node:path";
 import { Type } from "typebox";
-import { appendToBlock, appendToNestedArray, nextId, readBlock, readBlockDir, removeFromBlock, removeFromNestedArray, updateItemInBlock, updateNestedArrayItem, writeBlock, } from "./block-api.js";
+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 { BootstrapNotFoundError, schemaPath, tryResolveContextDir } from "./context-dir.js";
-import { appendRelationByRef, completeTask, contextState, currentState, deriveBootstrapState, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
+import { appendRelationByRef, appendRelationsByRef, completeTask, contextState, currentState, deriveBootstrapState, 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,15 +29,92 @@ 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, serializeForRead } 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";
 import { readSchema, writeSchemaChecked } from "./schema-write.js";
+import { truncateHead } from "./truncate.js";
 import { writeSchemaMigrationExecute } from "./write-schema-migration-tool.js";
+/**
+ * Collapse an {@link OpResult} to the text the default CLI surface + the in-pi
+ * Pi-tool surface emit. This reproduces, byte-for-byte, what each op's `run`
+ * returned before the TASK-012 split: prose → itself; `{json}` →
+ * `JSON.stringify(x, null, 2)`; `{read}` → `renderReadText` (== the old
+ * `serializeForRead().content`).
+ */
+/**
+ * The unbypassable output-boundary cap (TASK-013 / FGAP-015). The 50KB read cap
+ * (`DEFAULT_MAX_BYTES` + `truncateHead`) previously lived ONLY in the `{read}`
+ * channel (structureForRead / renderReadText); the prose `string` and `{json}`
+ * channels emitted unbounded. A `{json}` op embedding substrate content (e.g.
+ * resolve-item-by-id, promote-item) therefore leaked that content uncapped on
+ * BOTH surfaces — the CLI `--json` `output` and the shared text renderer used by
+ * the default CLI surface AND the in-pi Pi-tool surface. These two helpers move
+ * the cap to the emission boundary so it fires for EVERY channel regardless of
+ * which op shape produced the value.
+ *
+ * `{read}` is already fail-closed at structureForRead (over-cap → data null +
+ * tiny metadata / refusal text), so both helpers pass it through untouched — it
+ * is never double-handled here.
+ */
+/** True when `s` exceeds the 50KB read cap (shared byte-count/threshold logic). */
+function overReadCap(s) {
+    const totalBytes = Buffer.byteLength(s, "utf-8");
+    return { over: truncateHead(s).truncated, totalBytes };
+}
+/**
+ * REFUSAL prose for an over-cap `{json}` or prose `string` result — no narrowing
+ * tool/addressing is available at this boundary (unlike `{read}`'s
+ * overCapDirective), so this mirrors renderReadText's REFUSAL wording without a
+ * tool name and returns NO payload body.
+ */
+function overCapRefusalText(totalBytes) {
+    return (`⚠️ OUTPUT REFUSED — this result is ${totalBytes} bytes, over the 50KB read cap. ` +
+        `Nothing was returned (a partial read would mislead). Narrow your read.`);
+}
+/**
+ * Collapse an {@link OpResult} to the text the default CLI surface + the in-pi
+ * Pi-tool surface emit, NOW BOUNDED at the 50KB read cap (TASK-013 / FGAP-015).
+ * `{read}` → renderReadText (already capped); prose `string` → itself when under
+ * cap, else the REFUSAL prose; `{json}` → `JSON.stringify(x, null, 2)` when under
+ * cap, else the REFUSAL prose (no partial body).
+ */
+export function renderOpResultText(r) {
+    if (typeof r === "string") {
+        const { over, totalBytes } = overReadCap(r);
+        return over ? overCapRefusalText(totalBytes) : r;
+    }
+    if ("read" in r)
+        return renderReadText(r.read);
+    const s = JSON.stringify(r.json, null, 2);
+    const { over, totalBytes } = overReadCap(s);
+    return over ? overCapRefusalText(totalBytes) : s;
+}
+/**
+ * The JSON VALUE for the CLI `--json` envelope `output` field, NOW BOUNDED at the
+ * 50KB read cap (TASK-013 / FGAP-015). Prose `string` → itself when under cap,
+ * else the REFUSAL string; `{read}` → its ReadStructured (already fail-closed —
+ * serializes tiny on over-cap); `{json}` → the raw value when under cap, else a
+ * fail-closed envelope that MIRRORS {@link ReadStructured}'s over-cap shape
+ * (`{ data: null, truncated: true, totalBytes, complete: false }`) so `--json`
+ * consumers see one uniform fail-closed envelope across `{read}` and bounded
+ * `{json}`. No partial payload is ever emitted past the cap.
+ */
+export function boundedJsonOutput(r) {
+    if (typeof r === "string") {
+        const { over, totalBytes } = overReadCap(r);
+        return over ? overCapRefusalText(totalBytes) : r;
+    }
+    if ("read" in r)
+        return r.read;
+    const s = JSON.stringify(r.json, null, 2);
+    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
@@ -69,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')" }),
@@ -78,7 +158,7 @@ export const ops = [
             })),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             // Type.Unknown() params may arrive as JSON strings — parse if needed
             if (typeof params.item === "string") {
                 try {
@@ -96,7 +176,7 @@ export const ops = [
             // withBlockLock critical section (block-api assertAppendIdUnique) —
             // the single enforcement point. The prior racy readBlock-then-append
             // tool-layer check was removed in favour of that library guard.
-            appendToBlock(cwd, params.block, params.arrayKey, params.item);
+            appendToBlock(cwd, params.block, params.arrayKey, params.item, ctx);
             const id = params.item?.id ? ` '${params.item.id}'` : "";
             return `Appended item${id} to ${params.block}.${params.arrayKey}`;
         },
@@ -106,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" }),
@@ -115,12 +198,12 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             if (Object.keys(params.updates).length === 0) {
                 throw new Error("No fields to update — updates parameter is empty");
             }
             const matchEntries = Object.entries(params.match);
-            updateItemInBlock(cwd, params.block, params.arrayKey, (item) => matchEntries.every(([k, v]) => item[k] === v), params.updates);
+            updateItemInBlock(cwd, params.block, params.arrayKey, (item) => matchEntries.every(([k, v]) => item[k] === v), params.updates, ctx);
             const matchDesc = matchEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Updated item (${matchDesc}) in ${params.block}.${params.arrayKey}: ${Object.keys(params.updates).join(", ")}`;
         },
@@ -133,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" }),
@@ -140,25 +226,214 @@ export const ops = [
                 description: "Registered relation_type canonical_id / hierarchy edge type / lens id",
             }),
             ordinal: Type.Optional(Type.Integer({ description: "Optional sibling-ordering within (parent, relation_type)" })),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
         }),
         surface: "use",
-        run(cwd, params) {
+        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.
+            // 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,
                 relation_type: params.relation_type,
                 ...(params.ordinal !== undefined ? { ordinal: params.ordinal } : {}),
-            });
+            }, ctx, { dryRun: params.dryRun });
             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}`;
+            }
             return appended
                 ? `Appended relation ${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`
                 : `Relation ${params.parent} -[${params.relation_type}]-> ${params.child} already exists — no-op`;
         },
     },
+    {
+        name: "remove-relation",
+        label: "Remove Relation",
+        description: "Remove the single closure-table relation (edge) matching parent+child+relation_type from relations.json. " +
+            "Matches on the SAME (parent, child, relation_type) dedup identity append-relation uses, so it is the symmetric " +
+            "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" }),
+            relation_type: Type.String({
+                description: "Registered relation_type canonical_id / hierarchy edge type / lens id",
+            }),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Cycle-5 porcelain: STRING selectors are resolved to structured
+            // EdgeEndpoints, then matched on the identityKey dedup identity. Messaging
+            // uses the raw selectors (params.*), not the resolved structured endpoints.
+            // Under dryRun the byRef fn validates the prospective post-removal
+            // relations + match-checks without writing (TASK-010 shared preview path).
+            const { removed } = removeRelationByRef(cwd, { parent: params.parent, child: params.child, relation_type: params.relation_type }, ctx, { dryRun: params.dryRun });
+            if (params.dryRun) {
+                return removed
+                    ? `would remove relation ${params.parent} -[${params.relation_type}]-> ${params.child}`
+                    : `would no-op (no matching relation): ${params.parent} -[${params.relation_type}]-> ${params.child}`;
+            }
+            return removed
+                ? `Removed relation ${params.parent} -[${params.relation_type}]-> ${params.child}`
+                : `Relation ${params.parent} -[${params.relation_type}]-> ${params.child} — no matching relation — no-op`;
+        },
+    },
+    {
+        name: "replace-relation",
+        label: "Replace Relation",
+        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.",
+        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" }),
+            old_relation_type: Type.String({ description: "relation_type of the edge to remove" }),
+            parent: Type.String({ description: "Parent endpoint selector of the replacement edge" }),
+            child: Type.String({ description: "Child endpoint selector of the replacement edge" }),
+            relation_type: Type.String({ description: "relation_type of the replacement edge" }),
+            ordinal: Type.Optional(Type.Integer({ description: "Optional sibling-ordering within (parent, relation_type) for the new edge" })),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Under dryRun the byRef fn validates the prospective post-replace
+            // relations and computes the same removed/replaced would-decisions
+            // without writing (TASK-010 shared preview path).
+            const { replaced, removed } = replaceRelationByRef(cwd, {
+                old: { parent: params.old_parent, child: params.old_child, relation_type: params.old_relation_type },
+                new: {
+                    parent: params.parent,
+                    child: params.child,
+                    relation_type: params.relation_type,
+                    ...(params.ordinal !== undefined ? { ordinal: params.ordinal } : {}),
+                },
+            }, ctx, { dryRun: params.dryRun });
+            const ordinalNote = params.ordinal !== undefined ? ` (ordinal ${params.ordinal})` : "";
+            const oldDesc = `${params.old_parent} -[${params.old_relation_type}]-> ${params.old_child}`;
+            const newDesc = `${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`;
+            if (params.dryRun) {
+                if (!removed && !replaced) {
+                    return `would no-op — old edge ${oldDesc} absent and new edge ${newDesc} already present`;
+                }
+                if (!removed) {
+                    return `would append new relation ${newDesc} (old ${oldDesc} absent)`;
+                }
+                if (!replaced) {
+                    return `would remove relation ${oldDesc}; new relation ${newDesc} already present (no duplicate written)`;
+                }
+                return `would replace relation ${oldDesc} with ${newDesc}`;
+            }
+            if (!removed && !replaced) {
+                return `Replace relation no-op — old edge ${oldDesc} absent and new edge ${newDesc} already present`;
+            }
+            if (!removed) {
+                return `Old relation ${oldDesc} absent — appended new relation ${newDesc}`;
+            }
+            if (!replaced) {
+                return `Removed relation ${oldDesc}; new relation ${newDesc} already present (no duplicate written)`;
+            }
+            return `Replaced relation ${oldDesc} with ${newDesc}`;
+        },
+    },
+    {
+        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",
+        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)",
+            }),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Type.Unknown() params may arrive as JSON strings — parse if needed.
+            let edges = params.edges;
+            if (typeof edges === "string") {
+                try {
+                    edges = JSON.parse(edges);
+                }
+                catch {
+                    throw new Error(`edges parameter must be a JSON array, got unparseable string`);
+                }
+            }
+            if (!Array.isArray(edges)) {
+                throw new Error(`edges parameter must be a JSON array of { parent, child, relation_type, ordinal? } 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 });
+            return params.dryRun
+                ? `would append ${appended}, skip ${skipped} (duplicates)`
+                : `appended ${appended}, skipped ${skipped} (duplicates)`;
+        },
+    },
+    {
+        name: "upsert-block-item",
+        label: "Upsert Block Item",
+        description: "Append-or-replace an item in a project block array by id: if an item with the same idField value exists it is " +
+            "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')" }),
+            item: Type.Unknown({ description: "Full item object to upsert — must conform to block schema" }),
+            idField: Type.Optional(Type.String({ description: "Field used as the upsert key (default 'id')" })),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview the upsert without writing" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Type.Unknown() params may arrive as JSON strings — parse if needed.
+            if (typeof params.item === "string") {
+                try {
+                    params.item = JSON.parse(params.item);
+                }
+                catch {
+                    throw new Error(`item parameter must be a JSON object, got unparseable string`);
+                }
+            }
+            const idField = params.idField ?? "id";
+            // Under dryRun upsertItemInBlock computes mode + builds + validates the prospective
+            // whole block, writing nothing (TASK-011 shared preview path).
+            const { mode } = upsertItemInBlock(cwd, params.block, params.arrayKey, params.item, idField, ctx, {
+                dryRun: params.dryRun,
+            });
+            const idVal = params.item?.[idField];
+            const idDesc = idVal !== undefined ? ` '${idVal}'` : "";
+            return params.dryRun
+                ? `would upsert item${idDesc} (${mode}) in ${params.block}.${params.arrayKey}`
+                : `Upserted item${idDesc} (${mode}) to ${params.block}.${params.arrayKey}`;
+        },
+    },
     {
         name: "promote-item",
         label: "Promote Item",
@@ -169,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" }),
@@ -180,17 +458,26 @@ export const ops = [
             }, { description: "DispatchContext.writer per pi-context/src/dispatch-context.ts." }),
         }),
         surface: "use",
-        run(cwd, params) {
-            if (!params.writer?.user) {
-                throw new Error("promote-item: writer.user is required.");
+        run(cwd, params, ctx) {
+            // The DispatchContext now arrives via the op contract — registerAll
+            // (in-pi) builds it from the auth-gate-stamped `params.writer`, and the
+            // CLI builds it from its resolved identity. The schema `writer` field is
+            // retained (the in-pi auth-gate stamps it), but lineage attestation reads
+            // the contract ctx, not params.writer.
+            if (!ctx?.writer) {
+                throw new Error("promote-item: a DispatchContext writer is required.");
             }
             const result = promoteItem(cwd, {
                 source: params.source,
                 destinationSubstrate: params.destinationSubstrate,
                 ...(params.newRefname !== undefined ? { newRefname: params.newRefname } : {}),
                 ...(params.dryRun !== undefined ? { dryRun: params.dryRun } : {}),
-            }, { writer: { kind: "human", user: params.writer.user } });
-            return JSON.stringify(result, null, 2);
+            }, ctx);
+            // TASK-013 / FGAP-015: route through {read} so the embedded
+            // ResolvedRef.loc.item is bounded at the 50KB cap; over-cap fails closed
+            // with metadata. Under-cap text stays the same JSON (renderReadText
+            // under-cap returns JSON.stringify(serialized, null, 2) with no footer).
+            return { read: structureForRead(result, { whole: true, label: "promote-item result" }) };
         },
     },
     {
@@ -198,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')" }),
@@ -208,7 +498,7 @@ export const ops = [
             item: Type.Unknown({ description: "Item object to append to the nested array — must conform to schema" }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             if (typeof params.item === "string") {
                 try {
                     params.item = JSON.parse(params.item);
@@ -219,7 +509,7 @@ export const ops = [
             }
             const matchEntries = Object.entries(params.match);
             const predicate = (i) => matchEntries.every(([k, v]) => i[k] === v);
-            appendToNestedArray(cwd, params.block, params.arrayKey, predicate, params.nestedKey, params.item);
+            appendToNestedArray(cwd, params.block, params.arrayKey, predicate, params.nestedKey, params.item, ctx);
             const matchDesc = matchEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             const id = params.item?.id ? ` '${params.item.id}'` : "";
             return `Appended item${id} to ${params.block}.${params.arrayKey}[${matchDesc}].${params.nestedKey}`;
@@ -230,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')" }),
@@ -245,7 +538,7 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             if (Object.keys(params.updates).length === 0) {
                 throw new Error("No fields to update — updates parameter is empty");
             }
@@ -253,7 +546,7 @@ export const ops = [
             const nestedEntries = Object.entries(params.nestedMatch);
             const parentPred = (i) => parentEntries.every(([k, v]) => i[k] === v);
             const nestedPred = (i) => nestedEntries.every(([k, v]) => i[k] === v);
-            updateNestedArrayItem(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred, params.updates);
+            updateNestedArrayItem(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred, params.updates, ctx);
             const parentDesc = parentEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             const nestedDesc = nestedEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Updated nested item (${nestedDesc}) in ${params.block}.${params.arrayKey}[${parentDesc}].${params.nestedKey}: ${Object.keys(params.updates).join(", ")}`;
@@ -264,16 +557,19 @@ 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')" }),
             match: Type.Record(Type.String(), Type.Unknown(), { description: "Fields to match (e.g., { id: 'ISSUE-NNN' })" }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             const matchEntries = Object.entries(params.match);
             const predicate = (i) => matchEntries.every(([k, v]) => i[k] === v);
-            const result = removeFromBlock(cwd, params.block, params.arrayKey, predicate);
+            const result = removeFromBlock(cwd, params.block, params.arrayKey, predicate, ctx);
             const matchDesc = matchEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Removed ${result.removed} item(s) matching (${matchDesc}) from ${params.block}.${params.arrayKey}`;
         },
@@ -283,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')" }),
@@ -295,12 +594,12 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             const parentEntries = Object.entries(params.match);
             const nestedEntries = Object.entries(params.nestedMatch);
             const parentPred = (i) => parentEntries.every(([k, v]) => i[k] === v);
             const nestedPred = (i) => nestedEntries.every(([k, v]) => i[k] === v);
-            const result = removeFromNestedArray(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred);
+            const result = removeFromNestedArray(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred, ctx);
             const parentDesc = parentEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             const nestedDesc = nestedEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Removed ${result.removed} nested item(s) matching (${nestedDesc}) from ${params.block}.${params.arrayKey}[${parentDesc}].${params.nestedKey}`;
@@ -311,14 +610,15 @@ 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')" }),
         }),
         surface: "use",
         run(cwd, params) {
             const result = readBlockDir(cwd, params.subdir);
-            const envelope = serializeForRead(result, { label: `<substrate-dir>/${params.subdir}/` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `<substrate-dir>/${params.subdir}/` });
+            return { read };
         },
     },
     {
@@ -326,13 +626,14 @@ 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')" }),
         }),
         surface: "use",
         run(cwd, params) {
             const result = readBlock(cwd, params.block);
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: `<substrate-dir>/${params.block}.json`,
                 overCapDirective: {
                     tool: "read-block-page",
@@ -340,7 +641,7 @@ export const ops = [
                     hint: "or read-block-item with id=<id>",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -348,15 +649,18 @@ 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" }),
         }),
         surface: "use",
         authGated: true,
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             const data = typeof params.data === "string" ? JSON.parse(params.data) : params.data;
-            writeBlock(cwd, params.block, data);
+            writeBlock(cwd, params.block, data, ctx);
             return `Wrote block '${params.block}' successfully`;
         },
     },
@@ -365,11 +669,24 @@ 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) {
             const result = contextState(cwd);
-            return JSON.stringify(result, null, 2);
+            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) };
         },
     },
     {
@@ -377,11 +694,12 @@ export const ops = [
         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) {
             const result = validateContext(cwd);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -389,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')",
@@ -410,10 +729,14 @@ export const ops = [
                     if (!entry.found) {
                         return `read-config: entry not found in ${params.registry} — ${entry.resolved}`;
                     }
-                    const envEntry = serializeForRead(entry.value, { label: `config.${params.registry}.${params.id}` });
-                    return envEntry.content;
+                    const read = structureForRead(entry.value, {
+                        whole: true,
+                        label: `config.${params.registry}.${params.id}`,
+                    });
+                    return { read };
                 }
-                const envReg = serializeForRead(reg.value, {
+                const read = structureForRead(reg.value, {
+                    whole: true,
                     label: `config.${params.registry}`,
                     overCapDirective: {
                         tool: "read-config",
@@ -421,17 +744,17 @@ export const ops = [
                         hint: "add id=<entry canonical_id>",
                     },
                 });
-                return envReg.content;
+                return { read };
             }
             const result = { config, configPath };
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: configPath ?? "config.json",
                 overCapDirective: {
                     tool: "read-config",
                     hint: "registry=<name> (block_kinds|relation_types|lenses|invariants|…)",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -467,8 +790,8 @@ export const ops = [
                 if (tool === undefined) {
                     return `list-tools: tool not found — name=${params.name}`;
                 }
-                const envOne = serializeForRead(tool, { label: `tool ${params.name}` });
-                return envOne.content;
+                const read = structureForRead(tool, { whole: true, label: `tool ${params.name}` });
+                return { read };
             }
             // Default: compact index (FGAP-101) — name + param count + one-line description.
             const index = all.map((t) => {
@@ -482,11 +805,11 @@ export const ops = [
             // The compact index is one line per tool — small enough to serialize whole
             // (no paging); keep the wrapper fields (active/total) on the result object.
             const result = { tools: index, active, total: all.length, activeCount: active.length };
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: "tool index — pass name= for detail",
                 overCapDirective: { tool: "list-tools", hint: "name=<tool>" },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -494,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')" })),
         }),
@@ -502,13 +826,43 @@ export const ops = [
             // Package-intrinsic: the catalog reads the extension's bundled samples
             // directory, not the project substrate — cwd is unused.
             const catalog = samplesCatalog(params.kind ? { kind: params.kind } : undefined);
-            const envelope = serializeForRead(catalog, {
+            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 envelope.content;
+            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;
         },
     },
     {
@@ -516,11 +870,12 @@ export const ops = [
         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) {
             const state = currentState(cwd);
-            return JSON.stringify(state, null, 2);
+            return { json: state };
         },
     },
     {
@@ -528,11 +883,12 @@ 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) {
             const status = deriveBootstrapState(cwd);
-            return JSON.stringify(status, null, 2);
+            return { json: status };
         },
     },
     {
@@ -540,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" }),
@@ -550,7 +907,7 @@ export const ops = [
         authGated: true,
         run(cwd, params) {
             const report = renameCanonicalId(cwd, params.kind, params.oldId, params.newId, { dryRun: params.dryRun });
-            return JSON.stringify(report, null, 2);
+            return { json: report };
         },
     },
     {
@@ -563,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",
@@ -580,7 +940,7 @@ export const ops = [
         }),
         surface: "use",
         authGated: true,
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             // Type.Unknown() params may arrive as JSON strings. Parse if possible; on
             // failure KEEP the raw string (valid for map-value registries whose value
             // is a bare string, e.g. naming/display_strings/status_buckets).
@@ -593,10 +953,11 @@ export const ops = [
                     /* keep raw string — valid for map-value registries */
                 }
             }
-            const result = amendConfigEntry(cwd, params.registry, params.operation, params.key, entry, undefined, {
+            const result = amendConfigEntry(cwd, params.registry, params.operation, params.key, entry, ctx, {
                 dryRun: params.dryRun,
             });
-            const verb = result.modified ? (params.dryRun ? `would ${result.operation}` : `${result.operation}d`) : "no-op";
+            const pastTense = result.operation === "add" ? "added" : `${result.operation}d`;
+            const verb = result.modified ? (params.dryRun ? `would ${result.operation}` : pastTense) : "no-op";
             return `amend-config: ${verb} ${result.registry}[${result.key}]`;
         },
     },
@@ -605,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')",
@@ -622,11 +984,11 @@ export const ops = [
                 if (!addr.found) {
                     return `read-schema: property not found — ${addr.resolved}`;
                 }
-                const envProp = serializeForRead(addr.value, { label: `${params.schemaName} ${addr.resolved}` });
-                return envProp.content;
+                const read = structureForRead(addr.value, { whole: true, label: `${params.schemaName} ${addr.resolved}` });
+                return { read };
             }
             const result = { schema, schemaPath: schemaPathStr };
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: schemaPathStr,
                 overCapDirective: {
                     tool: "read-schema",
@@ -634,7 +996,7 @@ export const ops = [
                     hint: "path=<dotted json-path>",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -646,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')" }),
@@ -656,7 +1021,7 @@ export const ops = [
         }),
         surface: "use",
         authGated: true,
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             // Type.Unknown() params may arrive as JSON strings. Parse if possible; on
             // failure KEEP the raw value (meta-validation rejects a non-object body).
             let schema = params.schema;
@@ -668,16 +1033,57 @@ export const ops = [
                     /* keep raw string — meta-validation will reject a non-object */
                 }
             }
-            const result = writeSchemaChecked(cwd, params.schemaName, schema, params.operation, undefined, { dryRun: params.dryRun });
+            const result = writeSchemaChecked(cwd, params.schemaName, schema, params.operation, ctx, { dryRun: params.dryRun });
             const verb = result.written ? `${result.operation}d` : `would ${result.operation}`;
             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')." }),
@@ -698,8 +1104,8 @@ export const ops = [
         }),
         surface: "use",
         authGated: true,
-        async run(cwd, params) {
-            const result = await writeSchemaMigrationExecute(cwd, params);
+        async run(cwd, params, ctx) {
+            const result = await writeSchemaMigrationExecute(cwd, params, ctx);
             // writeSchemaMigrationExecute returns the uniform AgentToolResult; the
             // op contract is the text payload, which registerAll re-wraps identically.
             const part = result.content[0];
@@ -711,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.",
@@ -720,7 +1127,7 @@ export const ops = [
         authGated: true,
         run(cwd, params) {
             const result = initProject(cwd, params.contextDir);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -728,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,
@@ -742,7 +1150,58 @@ export const ops = [
                 }
                 throw err;
             }
-            return JSON.stringify(result);
+            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) };
         },
     },
     {
@@ -750,6 +1209,9 @@ export const ops = [
         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.",
@@ -784,14 +1246,14 @@ export const ops = [
             try {
                 if (params.to_previous === true) {
                     const { from, to } = switchToPrevious(cwd, writerIdentity);
-                    return JSON.stringify({ mode: "to_previous", from, to }, null, 2);
+                    return { json: { mode: "to_previous", from, to } };
                 }
                 if (params.create_new === true) {
                     const { created } = switchAndCreate(cwd, params.target_dir, writerIdentity);
-                    return JSON.stringify({ mode: "create_new", target_dir: params.target_dir, created }, null, 2);
+                    return { json: { mode: "create_new", target_dir: params.target_dir, created } };
                 }
                 switchToExisting(cwd, params.target_dir, writerIdentity);
-                return JSON.stringify({ mode: "existing", target_dir: params.target_dir }, null, 2);
+                return { json: { mode: "existing", target_dir: params.target_dir } };
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -804,11 +1266,12 @@ 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) {
             const subs = listSubstrates(cwd);
-            return JSON.stringify(subs, null, 2);
+            return { json: subs };
         },
     },
     {
@@ -816,25 +1279,20 @@ 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.",
             }),
-            writer: Type.Optional(Type.Object({
-                kind: Type.String({
-                    description: "Writer kind discriminator — overwritten by auth-gate to 'human' on confirm.",
-                }),
-                user: Type.String({
-                    description: "Writer user — overwritten by auth-gate to the verified terminal-operator identity on confirm.",
-                }),
-            }, { description: "DispatchContext.writer — stamped by auth-gate on operator confirm." })),
         }),
         surface: "use",
         authGated: true,
         run(cwd, params) {
             try {
                 const { from, to } = archiveSubstrate(cwd, params.target_dir);
-                return JSON.stringify({ from, to }, null, 2);
+                return { json: { from, to } };
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -847,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')",
@@ -866,11 +1325,11 @@ export const ops = [
                 op: params.op,
                 value: params.value,
             });
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: `${params.block} filtered`,
                 overCapDirective: { tool: "read-block-page", hint: "or refine the predicate" },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -878,13 +1337,24 @@ 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" }),
         }),
         surface: "use",
         run(cwd, params) {
             const result = resolveItemById(cwd, params.id);
-            return JSON.stringify(result, null, 2);
+            // TASK-013 / FGAP-015: route through {read} so the embedded full
+            // ItemLocation is bounded at the 50KB cap and over-cap fails closed with
+            // a narrowing directive (mirrors read-block-item). `result` is
+            // ItemLocation | null — structureForRead handles both.
+            return {
+                read: structureForRead(result, {
+                    whole: true,
+                    label: `resolve ${params.id}`,
+                    overCapDirective: { tool: "read-block-item", hint: "narrow to one block" },
+                }),
+            };
         },
     },
     {
@@ -892,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')" }),
@@ -901,8 +1372,8 @@ export const ops = [
             const result = readBlockItem(cwd, params.block, params.id);
             // whole: the item is already the addressed element — don't re-page its
             // intrinsic arrays; preserve the single-item|null output contract.
-            const envelope = serializeForRead(result, { whole: true, label: `${params.block} ${params.id}` });
-            return envelope.content;
+            const read = structureForRead(result, { whole: true, label: `${params.block} ${params.id}` });
+            return { read };
         },
     },
     {
@@ -910,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)" })),
@@ -920,8 +1392,8 @@ export const ops = [
             const result = readBlockPage(cwd, params.block, { offset: params.offset, limit: params.limit });
             // whole: readBlockPage ALREADY paged — preserve the {items,total,hasMore}
             // output contract; do not let serializeForRead re-page the items array.
-            const envelope = serializeForRead(result, { whole: true, label: `${params.block} page` });
-            return envelope.content;
+            const read = structureForRead(result, { whole: true, label: `${params.block} page` });
+            return { read };
         },
     },
     {
@@ -929,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')" }),
@@ -956,14 +1431,14 @@ export const ops = [
                 leftEndpoint: params.leftEndpoint,
                 leftPredicate,
             });
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: `${params.leftBlock} ⋈ ${params.rightBlock}`,
                 overCapDirective: {
                     tool: "join-blocks",
                     hint: "refine the relation/field or pre-filter the left block",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -971,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",
@@ -984,8 +1460,8 @@ export const ops = [
                 obj[id] = loc;
             // whole: an id→location map keyed by arbitrary ids — not a pageable
             // collection; serialize the map verbatim.
-            const envelope = serializeForRead(obj, { whole: true, label: "resolved ids" });
-            return envelope.content;
+            const read = structureForRead(obj, { whole: true, label: "resolved ids" });
+            return { read };
         },
     },
     {
@@ -993,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({
@@ -1000,8 +1479,8 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
-            const result = completeTask(cwd, params.taskId, params.verificationId);
+        run(cwd, params, ctx) {
+            const result = completeTask(cwd, params.taskId, params.verificationId, ctx);
             return `Task '${result.taskId}' completed (was '${result.previousStatus}'). Verification: ${result.verificationId} (${result.verificationStatus})`;
         },
     },
@@ -1010,11 +1489,12 @@ 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) {
             const result = validateContextRelations(cwd);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -1022,14 +1502,52 @@ 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" }),
         }),
         surface: "use",
         run(cwd, params) {
             const result = edgesForLensByName(cwd, params.lensId);
-            const envelope = serializeForRead(result, { label: `edges for lens ${params.lensId}` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `edges for lens ${params.lensId}` });
+            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` }) };
         },
     },
     {
@@ -1037,6 +1555,9 @@ export const ops = [
         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" }),
@@ -1044,7 +1565,7 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = walkLensDescendants(cwd, params.parentId, params.relationType);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -1052,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" }),
@@ -1059,8 +1581,8 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = walkAncestorsByLens(cwd, params.itemId, params.relationType);
-            const envelope = serializeForRead(result, { label: `ancestors of ${params.itemId}` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `ancestors of ${params.itemId}` });
+            return { read };
         },
     },
     {
@@ -1068,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")], {
@@ -1077,8 +1600,8 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = findReferencesInRepo(cwd, params.itemId, params.direction);
-            const envelope = serializeForRead(result, { label: `edges on ${params.itemId}` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `edges on ${params.itemId}` });
+            return { read };
         },
     },
     {
@@ -1086,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({
@@ -1101,8 +1625,8 @@ export const ops = [
             const result = gatherExecutionContext(cwd, params);
             // whole: a structured ContextBundle (unit + perRelationType buckets) —
             // preserve the bundle shape rather than paging any single inner array.
-            const envelope = serializeForRead(result, { whole: true, label: `bundle ${params.unitId}` });
-            return envelope.content;
+            const read = structureForRead(result, { whole: true, label: `bundle ${params.unitId}` });
+            return { read };
         },
     },
     {
@@ -1110,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" }),
         }),
@@ -1117,16 +1642,16 @@ export const ops = [
         run(cwd, params) {
             const view = loadRoadmap(cwd, params.roadmapId);
             if ("error" in view) {
-                const envErr = serializeForRead(view, { whole: true, label: `roadmap ${params.roadmapId} (error)` });
-                return envErr.content;
+                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 envelope = serializeForRead(serializeRoadmapView(view), {
+            const read = structureForRead(serializeRoadmapView(view), {
                 whole: true,
                 label: `roadmap ${params.roadmapId}`,
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -1134,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" }),
         }),
@@ -1141,7 +1667,7 @@ export const ops = [
         run(cwd, params) {
             const view = loadRoadmap(cwd, params.roadmapId);
             if ("error" in view) {
-                return JSON.stringify(view, null, 2);
+                return { json: view };
             }
             const naming = loadContext(cwd).config?.naming;
             return renderRoadmap(view, naming);
@@ -1152,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)" })),
         }),
@@ -1161,7 +1688,7 @@ export const ops = [
             const filtered = params.roadmapId
                 ? result.issues.filter((i) => !i.roadmap_id || i.roadmap_id === params.roadmapId)
                 : result.issues;
-            return JSON.stringify({ status: result.status, issues: filtered }, null, 2);
+            return { json: { status: result.status, issues: filtered } };
         },
     },
     {
@@ -1169,10 +1696,11 @@ 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) {
-            return JSON.stringify(listRoadmaps(cwd), null, 2);
+            return { json: listRoadmaps(cwd) };
         },
     },
 ];
@@ -1187,6 +1715,137 @@ export const ops = [
  * point; this list is the source of pi-context's contribution to it.
  */
 export const gatedTools = ops.filter((o) => o.authGated).map((o) => o.name);
+/**
+ * The FGAP-009 non-exposure allowlist: every library write function that is
+ * deliberately NOT op-backed, with the reason it is withheld. This is the
+ * closure contract γ (TASK-008) WILL consume: γ's parity test — not yet written
+ * (no executable parity test exists in β; β defines the contract, γ implements
+ * the test against it) — WILL assert that EVERY library writer is either op-backed
+ * (appears in {@link ops}, directly or transitively) OR named here, so a
+ * newly-added library writer with neither an op nor an allowlist entry will fail
+ * that test, keeping the op surface and the library write surface in lockstep.
+ *
+ * The `*ForDir` twins of op-backed writers (e.g. `appendRelationForDir`,
+ * `writeRelationsForDir`, `upsertItemInBlockForDir`, `appendToBlockForDir`, …)
+ * are NOT enumerated individually: each is the dir-targeted internal twin of a
+ * cwd-form writer that IS op-backed, and is covered by that cwd-form op (the op
+ * resolves the active substrate dir then delegates to the same shared
+ * typed-file primitive the `*ForDir` twin calls). The contract is that γ's
+ * parity test (TASK-008, not yet written) WILL treat a `*ForDir` writer as
+ * covered when its cwd-form sibling is covered.
+ */
+export const INTENTIONALLY_UNEXPOSED_WRITERS = [
+    { libraryFn: "writeConfig", safeOp: "amend-config", reason: "scoped guarded config mutation" },
+    { libraryFn: "writeSchema", safeOp: "write-schema", reason: "raw bypasses the create/replace + migration check" },
+    { libraryFn: "updateSchema", safeOp: "write-schema", reason: "no mutator-scripting surface" },
+    { libraryFn: "writeBootstrapPointer", safeOp: "context-init", reason: "raw bypasses target validation" },
+    { libraryFn: "flipBootstrapPointer", safeOp: "context-switch", reason: "raw splits the safe switch" },
+    { libraryFn: "writeRegistry", reason: "internal; registry writes flow through registerSubstrate callers" },
+    {
+        libraryFn: "registerSubstrate",
+        reason: "manual/foreign registration is the clone arc (DEC-0002); normal paths auto-register",
+    },
+    {
+        libraryFn: "rollbackBlockFiles",
+        reason: "workflow-executor transactional rollback (graduated-failure undo); internal recovery path with no operator-facing op by design",
+    },
+];
+/**
+ * The five mutually-exhaustive ways a library write function is COVERED by the
+ * FGAP-009 op-surface ↔ library-write-surface parity contract. A writer that
+ * matches NONE of these is a silent gap that γ's (TASK-008) parity test — once
+ * written — MUST fail on. Coverage is the DISJUNCTION over these classes — a
+ * writer needs ANY one, not all.
+ */
+export var CoverageClass;
+(function (CoverageClass) {
+    /** An op's `run` calls the writer directly (e.g. `append-block-item` → `appendToBlock`). */
+    CoverageClass["OpBackedDirect"] = "op-backed-direct";
+    /**
+     * An op's `run` reaches the writer TRANSITIVELY — through any helper / wrapper
+     * chain, not just a direct call. Two sub-shapes both land here:
+     *   - `*ByRef` / SDK relation porcelain: the `remove-relation` / `replace-relation`
+     *     / `append-relations` ops call `removeRelationByRef` / `replaceRelationByRef`
+     *     / `appendRelationsByRef`, which call `writeRelations`.
+     *   - init / switch → internal-helper chains: `context-init` → `initProject` →
+     *     `writeSkeletonConfig`; `context-switch` → `switchToExisting` /
+     *     `switchAndCreate` → `reconcileActiveSubstrateRegistration`. The writer is
+     *     not a `*ByRef` porcelain and is not allowlisted, but it IS reachable from an
+     *     op's `run` via a helper the op calls.
+     * Coverage condition: reachable from some op's `run` via any helper/wrapper chain.
+     */
+    CoverageClass["OpBackedTransitive"] = "op-backed-transitive";
+    /**
+     * A `*ForDir` dir-targeted twin of a covered cwd-form writer (e.g.
+     * `appendToBlockForDir` is the twin of the op-backed `appendToBlock`). Covered
+     * by its cwd-form sibling — both delegate to the same shared typed-file
+     * primitive; the cwd-form op resolves the active dir then calls it.
+     */
+    CoverageClass["ForDirTwin"] = "for-dir-twin";
+    /**
+     * On {@link INTENTIONALLY_UNEXPOSED_WRITERS}: a raw write deliberately given NO
+     * direct op (a scoped op supersedes it, or it is internal/foreign-only).
+     */
+    CoverageClass["IntentionallyUnexposed"] = "intentionally-unexposed";
+    /**
+     * A block-api internal primitive below the op layer — the `*TypedFile` read/
+     * write layer (`readTypedFile` / `writeTypedFile`), `prepareItemIdentityForWrite`,
+     * and the identity / content-hash helpers. Never op-backed by design; the ops
+     * compose over these.
+     */
+    CoverageClass["InternalPrimitive"] = "internal-primitive";
+})(CoverageClass || (CoverageClass = {}));
+/**
+ * The FGAP-009 coverage RULE, made explicit so γ (TASK-008) will import the
+ * contract rather than re-derive it. A library write function is COVERED iff it
+ * matches ANY clause below (the disjunction); a writer matching none is a silent
+ * gap that γ's parity test — when written — MUST fail on. β fixes the contract
+ * here; no executable parity test exists yet (that is γ).
+ *
+ * Why `writeConfig` is allowlisted but `writeRelations` is NOT — the distinction
+ * a strict name-parity reading mis-saw as inconsistent:
+ *   - `writeConfig` has NO direct wholesale-config op. The scoped surface is
+ *     `amend-config` (one-entry-in-one-registry add/replace/remove, AJV-validated),
+ *     which deliberately does NOT expose a raw whole-config overwrite. So
+ *     `writeConfig` is `intentionally-unexposed` (the scoped op supersedes the raw
+ *     writer; a raw wholesale overwrite is withheld by design).
+ *   - `writeRelations` IS reached — transitively — by the relation ops:
+ *     `remove-relation` / `replace-relation` / `append-relations` call
+ *     `removeRelationByRef` / `replaceRelationByRef` / `appendRelationsByRef`, each
+ *     of which calls `writeRelations`. It is therefore `op-backed-transitive`
+ *     and needs NO allowlist entry. The asymmetry is real and correct: one writer
+ *     has an op path (via a helper/wrapper chain), the other does not.
+ *
+ * The `op-backed-transitive` clause covers BOTH the `*ByRef` relation porcelain
+ * AND the init/switch → internal-helper chains: `writeSkeletonConfig` (reached
+ * via `context-init` → `initProject`) and `reconcileActiveSubstrateRegistration`
+ * (reached via `context-switch` → `switchToExisting` / `switchAndCreate`) are
+ * neither `*ByRef` porcelain nor allowlisted, yet each is reachable from an op's
+ * `run` through a helper that op calls — so each classifies cleanly as
+ * `op-backed-transitive`, not as a gap.
+ */
+export const OP_COVERAGE_RULE = [
+    {
+        coverageClass: CoverageClass.OpBackedDirect,
+        test: "an op's run() calls the writer directly",
+    },
+    {
+        coverageClass: CoverageClass.OpBackedTransitive,
+        test: "reachable from some op's run() via any helper/wrapper chain — the *ByRef / SDK relation porcelain (writeRelations via removeRelationByRef / replaceRelationByRef / appendRelationsByRef) OR an init/switch → internal-helper chain (writeSkeletonConfig via context-init → initProject; reconcileActiveSubstrateRegistration via context-switch → switchToExisting / switchAndCreate)",
+    },
+    {
+        coverageClass: CoverageClass.ForDirTwin,
+        test: "a *ForDir twin of a covered cwd-form writer (covered by its cwd-form sibling)",
+    },
+    {
+        coverageClass: CoverageClass.IntentionallyUnexposed,
+        test: "named on INTENTIONALLY_UNEXPOSED_WRITERS — a raw bypass with no direct op",
+    },
+    {
+        coverageClass: CoverageClass.InternalPrimitive,
+        test: "a block-api internal primitive below the op layer (the *TypedFile layer, prepareItemIdentityForWrite, identity / content-hash helpers)",
+    },
+];
 /**
  * The factory PI handle captured at registerAll time. The list-tools op needs
  * the introspection surface (getAllTools / getActiveTools) which lives on
@@ -1196,11 +1855,36 @@ export const gatedTools = ops.filter((o) => o.authGated).map((o) => o.name);
  * threading the handle through every signature.
  */
 let boundPi = null;
+/**
+ * Build the DispatchContext threaded into an op's `run` from the in-pi tool
+ * execute boundary (registerAll). Two derivation branches:
+ *
+ *   - When `params.writer.user` is a non-empty string — the shape the
+ *     pi-agent-dispatch auth-gate stamps onto authGated op params on operator
+ *     confirm — the writer is a human identity. (The smuggle-ops promote-item /
+ *     write-schema-migration / context-switch carry a `writer` schema field
+ *     precisely so the gate has somewhere to stamp; this converts that field
+ *     into the contract ctx the op now consumes via its 3rd `run` arg.)
+ *   - Otherwise the writer is the running agent, identified by the active
+ *     model's id (`ExtensionContext.model.id`); falls back to "pi-agent" when
+ *     no model (or no id) is resolvable.
+ *
+ * Exported for unit testing — the two branches are asserted directly against
+ * synthetic params + a minimal ExtensionContext-shaped object.
+ */
+export function buildDispatchContextFromExecute(params, extCtx) {
+    const writerUser = params?.writer?.user;
+    if (typeof writerUser === "string" && writerUser.length > 0) {
+        return { writer: { kind: "human", user: writerUser } };
+    }
+    const modelId = extCtx.model?.id;
+    return { writer: { kind: "agent", agent_id: modelId && modelId.length > 0 ? modelId : "pi-agent" } };
+}
 /**
  * Register every op in `ops` as a pi tool. Each tool's execute body is the
- * uniform wrapper around the op's run(): coerce params, await run, place the
- * returned string at content[0].text. Behavior-identical to the prior inline
- * registrations.
+ * uniform wrapper around the op's run(): coerce params, build the attestation
+ * DispatchContext from the auth-gate-stamped writer (human) or the running
+ * model (agent), await run, place the returned string at content[0].text.
  */
 export function registerAll(pi) {
     boundPi = pi;
@@ -1212,9 +1896,10 @@ export function registerAll(pi) {
             promptSnippet: op.promptSnippet,
             parameters: op.parameters,
             async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                const dctx = buildDispatchContextFromExecute(params, ctx);
                 return {
                     details: undefined,
-                    content: [{ type: "text", text: await op.run(ctx.cwd, params) }],
+                    content: [{ type: "text", text: renderOpResultText(await op.run(ctx.cwd, params, dctx)) }],
                 };
             },
         });