vantage-peers-mcp 2.12.1 → 2.13.0

package/README.md

@@ -25,6 +25,7 @@ Day 92 VP MCP quality overhaul (mission `k57a36y8w5t085bqr23dsmvb2d882506`, PR #
 - **C1 — 87 Zod `outputSchema` exports** following the per-family envelope standard (`create_*` → `{id,...}`, `list_*` → `{items,cursor}`, `delete_*` → `{id,deleted:true}`, etc.) based on the `whoamiOutputSchema` precedent (commit `5231811`).
 - **C2 — Unicode NFC normalization + case-insensitive orchestrator-ID matching** applied at all write paths and filter comparisons; closes the NFD/NFC silent mismatch class discovered in the Hélios/helios production regression.
 - **C3 — 97 tool descriptions standardized** (1-line summary + WHEN clause + concrete EXAMPLE, 80–500 chars) + 10 canonical aliases aligned to the `verb_noun_snake` whitelist.
+- **PR-J (Day 113) — canonical 114-tool snapshot quality gate** (`mcp-server/src/__tests__/tools-descriptions-canonical.test.ts`): inventory floor ≥100, length floor ≥60 chars, placeholder ban, category contracts (every `list_*` mentions `limit` + `cap`/`default 20`/`default 100`; every recall-class tool carries the PR-H VP-Sources doctrine verbatim). 15 `list_*` descriptions amended in T-GREEN `41944dc` to add the paging qualifier `Default limit N. cap M.` aligned with PR-A/B/C/E precedent.
 - **C4 — `claude-peers` legacy references removed** from source and docs + grep-gate CI check to prevent reintroduction.
 - **A3 — `whoami` LECTURE tool** (PR #661, commit `5231811`) — returns `suggested_orchestrator_id`, `scope_profile`, and `namespace_read_prefixes` so skills auto-resolve identity without prompting the user.
 - **F1 — `validate_task_payload` validator tool** (commit `cf6c961`) — client-side payload validation before any write reaches Convex.
@@ -96,8 +97,87 @@ The server also reads `CONVEX_URL` from `.env.local` in the parent directory if
 ### Profiles (3)
 `get_profile`, `update_profile`, `list_peers`
 
-### Tasks (10)
-`create_task`, `list_tasks`, `list_tasks_by_mission`, `update_task`, `start_task`, `complete_task`, `checkout_task`, `delete_task`, `block_task`, `add_task_dependency`
+### Tasks (11)
+`create_task`, `list_tasks`, `list_tasks_by_mission`, `update_task`, `start_task`, `complete_task`, `checkout_task`, `delete_task`, `block_task`, `add_task_dependency`, `bulk_complete_tasks`
+
+#### `list_tasks` — args schema + `excludeAutoGenerated` filter (PR-E)
+
+```
+list_tasks(assignedTo?, status?, missionId?, createdBy?, updatedSince?, createdBefore?, limit?, cursor?, fields?, excludeAutoGenerated?)
+```
+
+| Arg | Type | Default | Notes |
+|-----|------|---------|-------|
+| `assignedTo` | string | — | Filter by assignee (e.g. `"pi"`). |
+| `status` | string \| string[] \| alias | — | Single status, array, or alias (`"open"`, `"active"`, `"all"`). |
+| `missionId` | string | — | Filter to tasks in a specific mission. |
+| `createdBy` | string | — | Filter by creator (e.g. `"sigma"`). |
+| `updatedSince` | number | — | Epoch ms. Returns tasks with `updatedAt >= this`. |
+| `createdBefore` | number | — | Epoch ms. Pagination anchor (legacy; prefer `cursor`). |
+| `limit` | number 1–200 | `50` | Page size. |
+| `cursor` | string | — | Opaque token from prior `nextCursor`. |
+| `fields` | `"lite"\|"full"` | `"full"` | `"lite"` returns `{_id, _creationTime, title, status, priority, assignedTo, missionId}`. |
+| `excludeAutoGenerated` | boolean | `false` | When `true`, filters tasks where `createdBy ~ /^cron-/i` OR `title ~ /^\/?check-messages$/i`. Default `false` — backward-compatible. |
+
+**`excludeAutoGenerated` cron contract:**
+- `createdBy` matches `/^cron-/i` (dash mandatory): `cron-bot` is filtered, `cronus` is **not** filtered.
+- `title` matches `/^\/?check-messages$/i` (whole-string, optional leading slash, case-insensitive).
+- Filter applied in-memory after existing query filters, before envelope assembly.
+- **Post-filter pages may be smaller than `limit`** — filtered rows do not count toward limit. Acceptable for cron-spam catalog (small, narrowly targeted).
+
+Example — Pi queue cleaned of cron-spam:
+```json
+{
+  "tool": "list_tasks",
+  "arguments": { "assignedTo": "pi", "status": "open", "excludeAutoGenerated": true, "limit": 50 }
+}
+```
+
+Returns `{ items: Task[], nextCursor: string | null }`. `nextCursor` is `null` on the last page.
+
+#### `bulk_complete_tasks` — args schema + dry-run-default safety (PR-F)
+
+```
+bulk_complete_tasks(filter, dryRun?, completionNoteTemplate?, callerOrchestrator?)
+```
+
+| Arg | Type | Default | Notes |
+|-----|------|---------|-------|
+| `filter` | object | (required) | Filter object. Currently: `{ autoGeneratedOnly?: boolean }`. |
+| `filter.autoGeneratedOnly` | boolean | `false` | When `true`, matches tasks where `createdBy ~ /^cron-/i` OR `title ~ /^\/?check-messages$/i`. |
+| `dryRun` | boolean | `true` | **Safety default.** When `true`, returns a preview `{count, sampleIds, bulkRunId}` without mutating. Pass `false` explicitly to commit. |
+| `completionNoteTemplate` | string | (see below) | Template string for the `completionNote` written to each closed task. Supports `{{day}}`, `{{bulkRunId}}`, `{{executedAt}}` interpolation. Default: `"bulk-cleanup: cron-spam day {{day}} runId={{bulkRunId}} executedAt={{executedAt}}"`. |
+| `callerOrchestrator` | string | — | Caller identity for RBAC. When provided and not `"system"`, every matched task must have `createdBy` or `assignedTo` equal to the caller — otherwise throws `RBAC_DENIED`. |
+
+**`dryRun` safety note:** `bulk_complete_tasks` always defaults `dryRun` to `true`. Calling the tool without `dryRun=false` never mutates the database. This mirrors the two-step pattern required for all destructive bulk operations: preview first, then commit.
+
+**`excludeAutoGenerated` cron contract** (same as `list_tasks`):
+- `createdBy` matches `/^cron-/i` (dash mandatory): `cron-bot` is filtered, `cronus` is **not** filtered.
+- `title` matches `/^\/?check-messages$/i` (whole-string, optional leading slash, case-insensitive).
+- Filter applied in-memory against all non-done tasks.
+- **Post-filter count may be smaller than expected** — same trade-off as `list_tasks excludeAutoGenerated`.
+
+Examples:
+
+```json
+// Step 1 — dry-run preview (default dryRun=true)
+{
+  "tool": "bulk_complete_tasks",
+  "arguments": { "filter": { "autoGeneratedOnly": true }, "callerOrchestrator": "system" }
+}
+// → { "count": 152, "sampleIds": ["k17...", "k18..."], "bulkRunId": "bulk-1782050000000-a3f2" }
+
+// Step 2 — commit (explicit dryRun=false)
+{
+  "tool": "bulk_complete_tasks",
+  "arguments": { "filter": { "autoGeneratedOnly": true }, "dryRun": false, "callerOrchestrator": "system" }
+}
+// → { "count": 152, "sampleIds": ["k17...", "k18..."], "bulkRunId": "bulk-1782050000000-a3f2", "executedAt": 1782050000000 }
+```
+
+Returns `{ count, sampleIds, bulkRunId, executedAt? }`:
+- `dryRun=true` — `{ count, sampleIds, bulkRunId }` (no `executedAt`).
+- `dryRun=false` — `{ count, sampleIds, bulkRunId, executedAt }` — `bulkRunId` is the Day-76 evidence token; `executedAt` is the mutation epoch ms.
 
 ### Missions (6)
 `create_mission`, `list_missions`, `update_mission`, `update_mission_status`, `get_mission_template`, `get_mission`
@@ -114,9 +194,45 @@ The server also reads `CONVEX_URL` from `.env.local` in the parent directory if
 ### Briefing Notes (2)
 `create_briefing_note`, `list_briefing_notes`
 
+#### `list_briefing_notes` — VP-Sources doctrine (PR-H)
+
+Exports `LIST_BRIEFING_NOTES_TOOL_DESCRIPTION` from `mcp-server/src/tools.ts`.
+
+Same two advisory VP-Sources doctrine paragraphs appended after the existing description (identical strings, see `recall` in Search / RAG above).
+
+#### `search_briefing_notes_by_keyword` — VP-Sources doctrine (PR-H)
+
+Exports `SEARCH_BRIEFING_NOTES_BY_KEYWORD_TOOL_DESCRIPTION` from `mcp-server/src/tools.ts`.
+
+Same two advisory VP-Sources doctrine paragraphs appended after the existing description (identical strings, see `recall` in Search / RAG above).
+
 ### Search / RAG (3)
 `search_fix_patterns_by_semantic` (alias `search_fix_patterns`), `search_memories_by_keyword` (alias `text_search`), `hybrid_search`
 
+#### `recall` — VP-Sources doctrine (PR-H)
+
+Alias of `search_memories_by_semantic`. Exports `RECALL_TOOL_DESCRIPTION` from `mcp-server/src/tools.ts`.
+
+The description now embeds two advisory VP-Sources doctrine paragraphs appended after the existing text:
+
+> VP-Sources doctrine: MUST be called before any factual claim about fleet state, audits, dette tooling, mission/task/client status, incident history, doctrine references.
+>
+> Cite returned ids in the answer footer as 'VP-Sources: recall("\<q\>")→[ids] | none-needed:\<reason\>'.
+
+Doctrine is advisory-only — no hook blocks on absence. Client LLMs read the doctrine at tool-list time.
+
+#### `text_search` — VP-Sources doctrine (PR-H)
+
+Alias of `search_memories_by_keyword`. Exports `TEXT_SEARCH_TOOL_DESCRIPTION` from `mcp-server/src/tools.ts`.
+
+Same two advisory VP-Sources doctrine paragraphs appended after the existing description (identical strings, see `recall` above).
+
+#### `hybrid_search` — VP-Sources doctrine (PR-H)
+
+Exports `HYBRID_SEARCH_TOOL_DESCRIPTION` from `mcp-server/src/tools.ts`.
+
+Same two advisory VP-Sources doctrine paragraphs appended after the existing description (identical strings, see `recall` above).
+
 ### Issues (6)
 `get_issue`, `list_issues`, `update_issue_status`, `verify_issue`, `issue_stats`, `link_commit_to_issue`
 
@@ -227,12 +343,58 @@ Example:
 ### Deployments & Repos (5)
 `add_deployment`, `remove_deployment`, `list_repo_mappings`, `add_repo_mapping`, `remove_repo_mapping`
 
+#### `list_repo_mappings` — args schema + defaults (PR-C)
+
+```
+list_repo_mappings(limit?, cursor?, fields?)
+```
+
+| Arg | Type | Default | Notes |
+|-----|------|---------|-------|
+| `limit` | number 1–200 | `20` | Page size. Capped at `200` server-side. |
+| `cursor` | string | — | Opaque token from prior `nextCursor`. |
+| `fields` | `"lite"\|"full"` | `"full"` | `"lite"` returns `{_id, _creationTime, repo, orchestrator, project}`. `"full"` returns complete mapping object (including `active`, `lastDeployedSHA`, `lastDeployedAt`). |
+
+Returns `{ items: RepoMapping[], nextCursor: string | null }`. `nextCursor` is `null` on the last page.
+
 ### Business Units (5)
 `create_bu`, `list_bus`, `get_bu`, `update_bu`, `delete_bu`
 
+#### `list_bus` — args schema + defaults (PR-A)
+
+```
+list_bus(orchestratorId?, status?, limit?, cursor?, fields?)
+```
+
+| Arg | Type | Default | Notes |
+|-----|------|---------|-------|
+| `orchestratorId` | string | — | Filter by lead orchestrator (e.g. `"sigma"`). |
+| `status` | `"idea"\|"building"\|"live"\|"revenue"` | — | Filter by lifecycle status. |
+| `limit` | number 1–200 | `20` | Page size. Capped at `200` server-side. |
+| `cursor` | string | — | Opaque token from prior `nextCursor`. |
+| `fields` | `"lite"\|"full"` | `"full"` | `"lite"` returns `{_id, name, status, orchestratorId, _creationTime}`. `"full"` returns complete BU object (18+ keys). |
+
+Returns `{ items: BusinessUnit[], nextCursor: string | null }`. `nextCursor` is `null` on the last page.
+
 ### Components (6)
 `register_component`, `list_components`, `get_component`, `update_component`, `delete_component`, `search_components_by_keyword` (alias `search_components`)
 
+#### `list_components` — args schema + defaults (PR-B)
+
+```
+list_components(type?, team?, limit?, cursor?, fields?)
+```
+
+| Arg | Type | Default | Notes |
+|-----|------|---------|-------|
+| `type` | `"agent"\|"skill"\|"hook"\|"plugin"` | — | Filter by component type. |
+| `team` | string | — | Filter by team (e.g. `"development"`). |
+| `limit` | number 1–200 | `20` | Page size. Capped at `200` server-side. |
+| `cursor` | string | — | Opaque token from prior `nextCursor`. |
+| `fields` | `"lite"\|"full"` | `"full"` | `"lite"` returns `{_id, _creationTime, name, type, team}`. `"full"` returns complete component object. |
+
+Returns `{ items: Component[], nextCursor: string | null }`. `nextCursor` is `null` on the last page.
+
 ### Mandates (6)
 `create_mandate`, `list_mandates`, `accept_mandate`, `update_mandate`, `validate_mandate_spending`, `settle_mandate`
 
@@ -242,11 +404,61 @@ Example:
 ### Session (1)
 `set_summary`
 
+### Observability (1)
+`improvisation_digest`
+
+#### `improvisation_digest` — weekly advisory digest (PR-I)
+
+Scans a rolling time window of VP tasks, messages, and memories for records carrying fleet/state tokens (commit SHA, PR#, VP id, decisive verb) with **no VP-Sources footer** — the Eta heuristic proxy for "made a fleet-state claim without a prior `recall` upstream".
+
+```
+improvisation_digest(windowDays?, orchestrators?)
+```
+
+| Arg | Type | Default | Notes |
+|-----|------|---------|-------|
+| `windowDays` | number | `7` | Days to look back. |
+| `orchestrators` | string[] | — | Scope to these roles only (e.g. `["sigma","pi"]`). Omit for all orchestrators. |
+
+**Returns:**
+
+```ts
+{
+  countsByOrch: Record<string, number>,      // hit count per orchestrator
+  countsByCategory: Record<string, number>,  // hit count per record type (task/message/memory)
+  samples: Array<{
+    id: string,
+    category: string,
+    orchestrator: string,
+    snippet: string
+  }>                                         // up to 50 representative snippets
+}
+```
+
+**ADVISORY-only.** Pure read query — never blocks any action. Results are informational: a high improvisation rate suggests a team should increase VP-Sources citation hygiene, but the tool itself takes no automated action.
+
+**V1 scope (Option C):** scans VP records (tasks + messages + memories) only. Per Pi Day-113 arbitration (msg `k97a0pp6kq1axkj6cmc4pecpy989ce1w`), fallback if V1 misses too many = **Option B** (new dedicated `sessions` Convex table), not Option A (JSONL replay).
+
+**Detection heuristic (Eta A5 scope filter):**
+- Flag condition 1: record body contains a durable-artifact token (7–40 hex SHA, `#NNN`, Convex ID prefix, or decisive verb `merged/deployed/approved/shipped/released/fixed`).
+- Flag condition 2: record body does NOT contain the `VP-Sources:` footer substring.
+- A5 scope: excludes `system`, `cron-*`, and webhook-sourced entries.
+
+Examples:
+
+```json
+// Default 7-day window, all orchestrators
+{ "tool": "improvisation_digest", "arguments": { "windowDays": 7 } }
+
+// Scoped to one orchestrator
+{ "tool": "improvisation_digest", "arguments": { "windowDays": 14, "orchestrators": ["sigma"] } }
+```
+
 ## Compact payloads and status aliases (v2.12.0 — feature since v2.3.0)
 
 ### `fields=lite` — reduced token payloads
 
-`list_tasks`, `list_tasks_by_mission`, `list_missions`, and `list_briefing_notes` accept an optional `fields` parameter:
+`list_tasks`, `list_tasks_by_mission`, `list_missions`, `list_briefing_notes`, `list_bus`, `list_components`, and `list_repo_mappings` accept an optional `fields` parameter:
 
 | Value | Behaviour |
 |-------|-----------|
@@ -260,6 +472,9 @@ Lite projections per entity:
 | `list_tasks` / `list_tasks_by_mission` | `_id`, `_creationTime`, `title`, `status`, `priority`, `assignedTo`, `missionId` |
 | `list_missions` | `_id`, `_creationTime`, `name`, `status`, `pilot`, `priority`, `project` |
 | `list_briefing_notes` | `_id`, `_creationTime`, `topic`, `title`, `participants`, `createdBy` |
+| `list_bus` | `_id`, `_creationTime`, `name`, `status`, `orchestratorId` — PR-A activated actual projection (was no-op since v2.4.12) |
+| `list_components` | `_id`, `_creationTime`, `name`, `type`, `team` — PR-B activated actual projection (was no-op — returned full row) |
+| `list_repo_mappings` | `_id`, `_creationTime`, `repo`, `orchestrator`, `project` — PR-C activated actual projection (excludes `active`, `lastDeployedSHA`, `lastDeployedAt`) |
 
 Example (tasks lite):
 ```json

package/dist/src/paging.d.ts

@@ -1,3 +1,24 @@
+import { z } from "zod";
+export declare const pagingArgsSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodEnum<{
+        lite: "lite";
+        full: "full";
+    }>>;
+}, z.core.$strip>;
+export type PagingArgs = z.infer<typeof pagingArgsSchema>;
+export interface PagingDefaults {
+    limit: number;
+    cap: number;
+    fields: "lite" | "full";
+}
+export declare const DEFAULT_PAGING: PagingDefaults;
+export declare function applyPagingDefaults(args: PagingArgs, defaults?: PagingDefaults): {
+    limit: number;
+    cursor: string | undefined;
+    fields: "lite" | "full";
+};
 /**
  * Shared paging utility for VP MCP `list_*` tools (S3.3 B8).
  *

package/dist/src/paging.js

@@ -1,3 +1,29 @@
+import { z } from "zod";
+// ─────────────────────────────────────────────────────────────────────────────
+// PR-A envelope safety — shared schema + applyPagingDefaults helper
+// Reusable by list_bus, list_tasks (PR-B), list_memories (PR-C) etc.
+// ─────────────────────────────────────────────────────────────────────────────
+export const pagingArgsSchema = z.object({
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().optional(),
+    fields: z.enum(["lite", "full"]).optional(),
+});
+export const DEFAULT_PAGING = {
+    limit: 20,
+    cap: 200,
+    fields: "full",
+};
+export function applyPagingDefaults(args, defaults = DEFAULT_PAGING) {
+    const requested = args.limit ?? defaults.limit;
+    const clamped = Math.min(requested, defaults.cap);
+    const limit = Math.max(1, clamped);
+    return {
+        limit,
+        cursor: args.cursor,
+        fields: args.fields ?? defaults.fields,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
 /**
  * Shared paging utility for VP MCP `list_*` tools (S3.3 B8).
  *

package/dist/src/tools/exportOkfBundle.d.ts

@@ -6,8 +6,11 @@
  * Claude Code, Codex, IDE…) via the public VantagePeers Cloud surface.
  *
  * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
- * Self-host). Phase 1 namespace is verrouillé to `project/elpi-corp`; the
- * Convex action enforces the gate, the wrapper only forwards arguments.
+ * Self-host). The Convex action enforces auth — caller must match the
+ * namespace tail when an identity is attached (cross-tenant export
+ * forbidden). The Phase 1 hard lock to `project/elpi-corp` was relaxed by
+ * B3 (mission k5779qbxh, task k17f3407) so any `team/<orgId>/*` tenant can
+ * export their own bundle.
  *
  * RFC parent: decisions/okf-bridge-phase-1-rfc-2026-06-18.md (commit 6613610).
  * ADR:        decisions/adr-okf-exporter-arch.md (commit 2cd357e).

package/dist/src/tools/exportOkfBundle.js

@@ -6,8 +6,11 @@
  * Claude Code, Codex, IDE…) via the public VantagePeers Cloud surface.
  *
  * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
- * Self-host). Phase 1 namespace is verrouillé to `project/elpi-corp`; the
- * Convex action enforces the gate, the wrapper only forwards arguments.
+ * Self-host). The Convex action enforces auth — caller must match the
+ * namespace tail when an identity is attached (cross-tenant export
+ * forbidden). The Phase 1 hard lock to `project/elpi-corp` was relaxed by
+ * B3 (mission k5779qbxh, task k17f3407) so any `team/<orgId>/*` tenant can
+ * export their own bundle.
  *
  * RFC parent: decisions/okf-bridge-phase-1-rfc-2026-06-18.md (commit 6613610).
  * ADR:        decisions/adr-okf-exporter-arch.md (commit 2cd357e).
@@ -22,7 +25,11 @@ import { z } from "zod";
 export const exportOkfBundleArgsSchema = {
     namespace: z
         .string()
-        .describe("OKF export namespace. Phase 1 verrouillé to 'project/elpi-corp'."),
+        .describe("OKF export namespace prefix. Any prefix the caller has write scope on " +
+        "is accepted (e.g. 'project/elpi-corp', 'team/<orgId>', 'org/<slug>'). " +
+        "Identity-attached callers must match the namespace tail (cross-tenant " +
+        "export forbidden). The 'project/elpi-corp' Phase 1 hard lock was " +
+        "removed by B3 (mission k5779qbxh) for multi-tenant Cloud dashboards."),
     types: z
         .array(z.string())
         .nullable()

package/dist/src/tools/importOkfBundle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP tool: import_okf_bundle (OKF Phase 2 — B2 / T-OKF-PHASE2-B).
+ *
+ * Thin proxy around the Convex `okfBundleNode:importOkfBundle` action. Imports
+ * memories / briefing-notes / tasks from an OKF v0.1 bundle into the target
+ * namespace, deduplicating by content equality so replays of the same bundle
+ * are no-ops.
+ *
+ * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
+ * Self-host). The Convex action gates cross-tenant writes via the same
+ * fail-closed null-identity guard that protects exportOkfBundle (Eta REVISE
+ * iter-2 on #888). This wrapper only forwards arguments.
+ *
+ * Mission: k5779qbxhwrfjmj02t31yvehns8911jp.
+ * Task:    k17fja9v7pgnf25yvzkwrj5ch5891bb3.
+ *
+ * Orchestrator: Sigma — VantagePeers | 2026-06-20
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConvexHttpClient } from "convex/browser";
+import { z } from "zod";
+export interface ImportOkfBundleResult {
+    imported: {
+        memories: number;
+        briefings: number;
+        tasks: number;
+    };
+    skipped: number;
+    conflicts: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+export declare const importOkfBundleArgsSchema: {
+    bundleUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    storageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    targetNamespace: z.ZodString;
+    mode: z.ZodEnum<{
+        "dry-run": "dry-run";
+        merge: "merge";
+        replace: "replace";
+    }>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+};
+export declare function registerImportOkfBundle(server: McpServer, convex: ConvexHttpClient): void;

package/dist/src/tools/importOkfBundle.js

@@ -0,0 +1,81 @@
+/**
+ * MCP tool: import_okf_bundle (OKF Phase 2 — B2 / T-OKF-PHASE2-B).
+ *
+ * Thin proxy around the Convex `okfBundleNode:importOkfBundle` action. Imports
+ * memories / briefing-notes / tasks from an OKF v0.1 bundle into the target
+ * namespace, deduplicating by content equality so replays of the same bundle
+ * are no-ops.
+ *
+ * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
+ * Self-host). The Convex action gates cross-tenant writes via the same
+ * fail-closed null-identity guard that protects exportOkfBundle (Eta REVISE
+ * iter-2 on #888). This wrapper only forwards arguments.
+ *
+ * Mission: k5779qbxhwrfjmj02t31yvehns8911jp.
+ * Task:    k17fja9v7pgnf25yvzkwrj5ch5891bb3.
+ *
+ * Orchestrator: Sigma — VantagePeers | 2026-06-20
+ */
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+export const importOkfBundleArgsSchema = {
+    bundleUrl: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Signed HTTPS URL to a tarball OKF v0.1 bundle. Mutually exclusive with storageId."),
+    storageId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Convex `_storage` document ID of a previously-uploaded tarball. Mutually exclusive with bundleUrl."),
+    targetNamespace: z
+        .string()
+        .describe("Destination namespace, e.g. 'team/<orgId>' or 'project/<slug>'. Cross-tenant writes are denied."),
+    mode: z
+        .enum(["dry-run", "merge", "replace"])
+        .describe("dry-run = preview counts, no writes. merge = insert new + dedup by content. replace = reserved."),
+    idempotencyKey: z
+        .string()
+        .optional()
+        .describe("Caller-supplied replay token. Same key + same content = no duplicate inserts."),
+};
+export function registerImportOkfBundle(server, convex) {
+    server.tool("import_okf_bundle", "Import an OKF v0.1 bundle (memories + briefing-notes + tasks) into a target VantagePeers namespace. " +
+        "WHEN: use to restore a snapshot, migrate workspace data between tenants, or replay an export. " +
+        "EXAMPLE: import_okf_bundle storageId='abc...' targetNamespace='team/iris-rh' mode='merge'.", importOkfBundleArgsSchema, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Import OKF bundle",
+    }, async ({ bundleUrl, storageId, targetNamespace, mode, idempotencyKey }) => {
+        try {
+            const result = (await convex.action("okfBundleNode:importOkfBundle", {
+                bundleUrl: bundleUrl ?? null,
+                storageId: storageId ?? null,
+                targetNamespace,
+                mode,
+                idempotencyKey,
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            console.error("[import_okf_bundle] action failed", {
+                targetNamespace,
+                mode,
+                errorMessage: message,
+            });
+            throw new McpError(ErrorCode.InternalError, message);
+        }
+    });
+}

package/dist/src/tools/validateOkfBundle.d.ts

@@ -0,0 +1,43 @@
+/**
+ * MCP tool: validate_okf_bundle (OKF Phase 2 — B1 / T-OKF-PHASE2-A).
+ *
+ * Thin proxy around the Convex `okfBundleNode:validateOkfBundle` action. Lets
+ * any MCP client (Claude.ai, ChatGPT, Claude Code, Codex, IDE…) verify a bundle's
+ * conformance to OKF v0.1 (RFC §3.5) before importing it. Read-only — never
+ * mutates the database.
+ *
+ * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
+ * Self-host). The Convex action enforces auth; this wrapper only forwards
+ * arguments.
+ *
+ * RFC parent: decisions/okf-bridge-phase-1-rfc-2026-06-18.md (commit 6613610).
+ * Mission:    k5779qbxhwrfjmj02t31yvehns8911jp (VP Cloud Dashboard).
+ * Task:       k1796g7g7y03gn9rd6z7psenk98910vt.
+ *
+ * Orchestrator: Sigma — VantagePeers | 2026-06-20
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConvexHttpClient } from "convex/browser";
+import { z } from "zod";
+export interface ValidateOkfBundleResult {
+    valid: boolean;
+    schemaVersion: "0.1";
+    stats: {
+        memoryCount: number;
+        briefingCount: number;
+        taskCount: number;
+    };
+    errors?: Array<{
+        path: string;
+        rule: string;
+        message: string;
+    }>;
+}
+export declare const validateOkfBundleArgsSchema: {
+    bundleUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    storageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+/**
+ * Register the `validate_okf_bundle` MCP tool against an McpServer instance.
+ */
+export declare function registerValidateOkfBundle(server: McpServer, convex: ConvexHttpClient): void;

package/dist/src/tools/validateOkfBundle.js

@@ -0,0 +1,80 @@
+/**
+ * MCP tool: validate_okf_bundle (OKF Phase 2 — B1 / T-OKF-PHASE2-A).
+ *
+ * Thin proxy around the Convex `okfBundleNode:validateOkfBundle` action. Lets
+ * any MCP client (Claude.ai, ChatGPT, Claude Code, Codex, IDE…) verify a bundle's
+ * conformance to OKF v0.1 (RFC §3.5) before importing it. Read-only — never
+ * mutates the database.
+ *
+ * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
+ * Self-host). The Convex action enforces auth; this wrapper only forwards
+ * arguments.
+ *
+ * RFC parent: decisions/okf-bridge-phase-1-rfc-2026-06-18.md (commit 6613610).
+ * Mission:    k5779qbxhwrfjmj02t31yvehns8911jp (VP Cloud Dashboard).
+ * Task:       k1796g7g7y03gn9rd6z7psenk98910vt.
+ *
+ * Orchestrator: Sigma — VantagePeers | 2026-06-20
+ */
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+// ─────────────────────────────────────────────────────────────────────────────
+// Zod input schema (RFC §3.5)
+// ─────────────────────────────────────────────────────────────────────────────
+export const validateOkfBundleArgsSchema = {
+    bundleUrl: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Optional signed bundle URL — fetched via global `fetch`. " +
+        "Mutually exclusive with `storageId`; at least one is required."),
+    storageId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Optional Convex storage id (`_storage` id) — resolved server-side. " +
+        "Mutually exclusive with `bundleUrl`; at least one is required."),
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Registration
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Register the `validate_okf_bundle` MCP tool against an McpServer instance.
+ */
+export function registerValidateOkfBundle(server, convex) {
+    server.tool("validate_okf_bundle", "Validate an OKF v0.1 bundle (tarball) against the spec (RFC §3.5) without " +
+        "importing it. WHEN: use as a preview check before calling import_okf_bundle, " +
+        "or to audit a bundle for schema conformance. EXAMPLE: validate_okf_bundle " +
+        "storageId='kg2anjqa…' OR validate_okf_bundle bundleUrl='https://…/bundle.tar'.", validateOkfBundleArgsSchema, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Validate OKF bundle",
+    }, async ({ bundleUrl, storageId }) => {
+        try {
+            const result = (await convex.action("okfBundleNode:validateOkfBundle", {
+                bundleUrl: bundleUrl ?? null,
+                storageId: storageId ?? null,
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            console.error("[validate_okf_bundle] action failed", {
+                hasBundleUrl: bundleUrl !== undefined && bundleUrl !== null,
+                hasStorageId: storageId !== undefined && storageId !== null,
+                errorMessage: message,
+            });
+            throw new McpError(ErrorCode.InternalError, message);
+        }
+    });
+}