vantage-peers-mcp 2.12.0 → 2.13.0

package/LICENSE

@@ -0,0 +1,110 @@
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+Abbreviation
+
+FSL-1.1-Apache-2.0
+
+Notice
+
+Copyright 2026 VantageOS (ElPi Corp)
+
+Terms and Conditions
+
+Licensor:             VantageOS (ElPi Corp)
+
+Licensed Work:        VantagePeers
+                      The Licensed Work is (c) 2026 VantageOS (ElPi Corp)
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided Your use does not include offering the Licensed
+                      Work to third parties as a hosted or managed service
+                      where the service provides users with access to any
+                      substantial set of the features or functionality of the
+                      Licensed Work.
+
+Change Date:          2028-04-03 (two years from publication)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: contact@vantageos.com
+
+License text below is provided for informational purposes only.
+
+---
+
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+1. Purpose
+
+This license gives you broad permission to use, modify, and share this
+software, with one important condition: you may not use it to compete with us.
+
+2. Acceptance
+
+To use the software, you must agree to these terms. If you do not agree, you
+may not use the software.
+
+3. Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-
+sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+4. Limitations
+
+You may not make the functionality of the software available to third parties
+as a service, or otherwise use the software to provide a service to third
+parties that competes with the licensor.
+
+5. Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license or becomes able to license, to make, have made, use, sell, offer for
+sale, import, and have imported the software, in each case subject to the
+limitations and conditions in this license.
+
+6. Fair Use
+
+This license is not intended to limit any rights you may have under applicable
+fair use or other laws.
+
+7. No Other Rights
+
+These terms do not grant any other rights. The licensor reserves all rights not
+expressly granted.
+
+8. Termination
+
+Your license is automatically terminated if you violate the terms. However, if
+you cure the violation within 30 days of discovering it, your license is
+reinstated retroactively.
+
+9. Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED.
+
+10. Limitation of Liability
+
+TO THE EXTENT PERMITTED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY DAMAGES
+ARISING FROM THE USE OF THE SOFTWARE.
+
+11. Change Date and License
+
+After the Change Date, the licensor grants you the rights under the Change
+License.
+
+12. Definitions
+
+"Compete" means providing a product or service that is substantially similar
+to, or a replacement for, all or a significant portion of the Licensed Work.
+
+---
+
+Apache License, Version 2.0
+
+After the Change Date (2028-04-03), this software will be available under the
+Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0
+for full text.

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`
 
-## Compact payloads and status aliases (v2.11.0 — feature since v2.3.0)
+### 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/server-http.js

@@ -46,8 +46,13 @@ catch {
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
 // ─────────────────────────────────────────────────────────────────────────────
-const PUBLIC_BASE_URL_FALLBACK = process.env.PUBLIC_BASE_URL ??
-    "https://vantage-peers-production.up.railway.app";
+// Day 107 Cédric BLOCKER root cause: previously hardcoded a fallback to the
+// VantagePeers Cloud production URL, which meant Self-host deploys forgetting
+// PUBLIC_BASE_URL silently advertised Sigma's URL in OAuth metadata and broke
+// every Self-host customer's DCR chain with `invalid_client`. Fix: env-only
+// fallback, no implicit cross-tenant default. `resolveIssuer` throws clear
+// error if both Host header AND env are absent.
+const PUBLIC_BASE_URL_FALLBACK = process.env.PUBLIC_BASE_URL ?? null;
 const ACCESS_TOKEN_TTL_SECONDS = 3600; // 1 hour
 const REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 3600; // 30 days
 const AUTH_CODE_TTL_SECONDS = 600; // 10 minutes
@@ -77,7 +82,10 @@ function resolveIssuer(req) {
                 : "https");
         return `${proto}://${host}`;
     }
-    return PUBLIC_BASE_URL_FALLBACK;
+    if (PUBLIC_BASE_URL_FALLBACK) {
+        return PUBLIC_BASE_URL_FALLBACK;
+    }
+    throw new Error("Server misconfigured: cannot determine public base URL (no Host header and PUBLIC_BASE_URL env var unset). Self-host deploys MUST set PUBLIC_BASE_URL.");
 }
 function randomOpaqueToken() {
     // 256-bit entropy via getRandomValues (32 bytes → 64 hex chars).

package/dist/src/auth.js

@@ -163,8 +163,28 @@ export function bearerAuthMiddleware() {
         // the param MUST be `resource_metadata=` (not `resource=`). Claude.ai's OAuth
         // connector looks for `resource_metadata=` to bootstrap PRM discovery; with
         // `resource=` the entire DCR chain breaks before any token is issued.
-        const publicBaseUrl = process.env.PUBLIC_BASE_URL ??
-            "https://vantage-peers-production.up.railway.app";
+        //
+        // Day 107 Cédric BLOCKER root cause: a hardcoded fallback to the
+        // VantagePeers Cloud production URL ("vantage-peers-production.up.railway.app")
+        // meant Self-host deploys that forgot PUBLIC_BASE_URL silently advertised
+        // Sigma's PRM endpoint, breaking every Self-host customer's DCR chain with
+        // `invalid_client`. Fix: derive from the incoming request (RFC 8414 §2 —
+        // issuer MUST be the URL the client used). Fall back to PUBLIC_BASE_URL env
+        // only if Host header is absent (curl smoke). Fail closed if neither is set.
+        const host = c.req.header("host");
+        const xfProto = c.req.header("x-forwarded-proto");
+        const proto = xfProto ??
+            (host?.startsWith("localhost") || host?.startsWith("127.")
+                ? "http"
+                : "https");
+        const publicBaseUrl = host
+            ? `${proto}://${host}`
+            : (process.env.PUBLIC_BASE_URL ?? null);
+        if (!publicBaseUrl) {
+            return c.json({
+                error: "Server misconfigured: cannot determine public base URL (no Host header and PUBLIC_BASE_URL env var unset).",
+            }, 500);
+        }
         const wwwAuthHeader = `Bearer resource_metadata="${publicBaseUrl}/.well-known/oauth-protected-resource"`;
         const authHeader = c.req.header("Authorization");
         if (!authHeader?.startsWith("Bearer ")) {

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

@@ -0,0 +1,54 @@
+/**
+ * MCP tool: export_okf_bundle (Phase 1 — T3).
+ *
+ * Thin proxy around the Convex `okfBundle:exportOkfBundle` action. The MCP
+ * tool wrapper exposes the export to any MCP client (Claude.ai, ChatGPT,
+ * Claude Code, Codex, IDE…) via the public VantagePeers Cloud surface.
+ *
+ * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
+ * 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).
+ *
+ * Orchestrator: Sigma — VantagePeers | 2026-06-19
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConvexHttpClient } from "convex/browser";
+import { z } from "zod";
+export interface ExportOkfBundleResult {
+    bundleUrl: string;
+    storageId: string;
+    size: number;
+    fileCount: number;
+    manifest: {
+        types: {
+            memoryCount: number;
+            briefingCount: number;
+            taskCount: number;
+        };
+        truncated: boolean;
+        urlExpiresAt: string;
+    };
+}
+export declare const exportOkfBundleArgsSchema: {
+    namespace: z.ZodString;
+    types: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    format: z.ZodEnum<{
+        tarball: "tarball";
+        tree: "tree";
+    }>;
+    since: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    urlTtl: z.ZodOptional<z.ZodNumber>;
+};
+/**
+ * Register the `export_okf_bundle` MCP tool against an McpServer instance.
+ *
+ * Call this from `tools.ts` (or directly from `server.ts`) alongside the other
+ * `server.tool(...)` registrations.
+ */
+export declare function registerExportOkfBundle(server: McpServer, convex: ConvexHttpClient): void;

package/dist/src/tools/exportOkfBundle.js

@@ -0,0 +1,107 @@
+/**
+ * MCP tool: export_okf_bundle (Phase 1 — T3).
+ *
+ * Thin proxy around the Convex `okfBundle:exportOkfBundle` action. The MCP
+ * tool wrapper exposes the export to any MCP client (Claude.ai, ChatGPT,
+ * Claude Code, Codex, IDE…) via the public VantagePeers Cloud surface.
+ *
+ * **VantagePeers Cloud, multi-tenant**: this is the Cloud product (NOT
+ * 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).
+ *
+ * Orchestrator: Sigma — VantagePeers | 2026-06-19
+ */
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+// ─────────────────────────────────────────────────────────────────────────────
+// Zod input schema (RFC §3.1)
+// ─────────────────────────────────────────────────────────────────────────────
+export const exportOkfBundleArgsSchema = {
+    namespace: z
+        .string()
+        .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()
+        .optional()
+        .describe("Optional type filter — null/omitted exports all 3 families. " +
+        "Tokens: 'memory-*' (all subtypes), 'memory-<sub>' (literal), " +
+        "'briefing-note', 'task'."),
+    format: z
+        .enum(["tarball", "tree"])
+        .describe("Bundle format. Phase 1 supports 'tarball' only; 'tree' is reserved " +
+        "for Phase 2."),
+    since: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Optional ISO 8601 timestamp — only entries updated on/after are " +
+        "included. Anticipation Phase 2."),
+    urlTtl: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional signed URL TTL in seconds (default 3600 = 1 hour). The " +
+        "storage object is purged at TTL expiry."),
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Registration
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Register the `export_okf_bundle` MCP tool against an McpServer instance.
+ *
+ * Call this from `tools.ts` (or directly from `server.ts`) alongside the other
+ * `server.tool(...)` registrations.
+ */
+export function registerExportOkfBundle(server, convex) {
+    server.tool("export_okf_bundle", "Export a VantagePeers namespace as an OKF v0.1 bundle (tarball). " +
+        "WHEN: use to ship a snapshot to Knowledge Catalog / RAG bridge / audit. " +
+        "EXAMPLE: export_okf_bundle namespace='project/elpi-corp' format='tarball'.", exportOkfBundleArgsSchema, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Export OKF bundle",
+    }, async ({ namespace, types, format, since, urlTtl }) => {
+        try {
+            const result = (await convex.action("okfBundleNode:exportOkfBundle", {
+                namespace,
+                types: types ?? null,
+                format,
+                since: since ?? null,
+                urlTtl,
+            }));
+            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);
+            // Surface structured OKF_* error codes verbatim — the action emits
+            // them as prefix tokens in the Error message.
+            console.error("[export_okf_bundle] action failed", {
+                namespace,
+                format,
+                errorMessage: message,
+            });
+            throw new McpError(ErrorCode.InternalError, message);
+        }
+    });
+}