@llamaventures/cli 2.0.2 → 2.1.0

package/AGENT_BRIEFING.md

@@ -44,6 +44,14 @@ working memory; it never becomes Page automatically. Page is the bounded,
 human-visible current projection, so patch the exact semantic fields described
 by the live contract instead of hiding structured analysis in `notes`.
 
+The Markdown Deal Story is a separate sidecar domain, not a sixth Occam
+resource. Use `get_deal_memory` / `llama memory read` for accumulated narrative
+understanding, and `update_deal_memory` / `llama memory write` to replace its
+complete Markdown. Read first and pass the returned opaque version on every
+update; a conflict means read again and reconcile. These calls still go only
+through authenticated Core. Never request AWS credentials or call S3 or the
+sidecar directly.
+
 Every Page content field is Agent-writable. A field's `author` or
 `semanticOwner` describes attribution, not permission. Preserve a real human
 judgment with its author; otherwise label the value as an Agent proposal / 待人确认.
@@ -207,4 +215,5 @@ artifact, then decide whether its content deserves Information or a Page patch.
   `DEAL_COMMAND_RETIRED`. Upgrade the CLI and retry the intended four-action
   command.
 - Wiki, admin audit, external pitch, authentication, and skill discovery are
-  separate domains. They do not expand the Deal action space.
+  separate domains. Deal Memory is also separate. None expands the four-action
+  Occam Deal space.

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+All notable changes to `@llamaventures/cli` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project adheres to [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [2.1.0] - 2026-09-03
+
+### Added
+- Add `llama memory read|write` and matching `get_deal_memory` /
+  `update_deal_memory` MCP tools for one canonical Markdown Deal Story, using
+  the existing Llama login through Core's authenticated sidecar adapter.
+
+### Changed
+- Make the authenticated live bootstrap mandatory before Deal work and clarify
+  that it loads the server-owned two-part private Brain plus the separate Live
+  Deal Page field contract. CLI remains only the tool/transport layer.
+- Teach CLI and MCP Agents that Information never updates Page automatically,
+  every Page content field is Agent-writable, and field authorship controls
+  attribution rather than permission.
+- Pin the additive Deal Memory operations to Core API 5.1.0 while preserving
+  exactly four Occam Deal actions and five Occam resources.
+
+## [2.0.3] - 2026-08-31
+
+- Show Core validation codes and field paths instead of collapsing malformed
+  Deal writes into `Invalid Occam command`.
+- Publish `write_deal` as four operation-specific MCP command shapes while
+  retaining one mutation tool.
+- Add copyable write examples to `llama help deal` and omit the duplicate
+  rendered briefing from structured bootstrap output.
+- Let Core's private Page contract classify prose and enums instead of keeping
+  a second, drifting public-CLI field whitelist.
+- Return a compact `page.patch` revision receipt with exact read-back fields
+  instead of echoing the full Live Deal Page after every write.
+- Turn retired top-level commands such as `llama brief`, `fact`, `post`,
+  `timeline`, `html`, `memo`, and `pipeline` into self-correcting errors that
+  name the CLI 2 replacement and live contract entrypoint.
+
 ## [2.0.2] - 2026-08-31
 
 - Correct the authenticated runtime model: Brain has exactly two private
@@ -33,20 +72,6 @@
 - Keep Wiki, admin audit, external pitch, authentication, preferences, and
   progressive skill discovery as separate non-Deal domains.
 
-All notable changes to `@llamaventures/cli` are documented here.
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
-this project adheres to [Semantic Versioning](https://semver.org).
-
-## [Unreleased]
-
-### Changed
-- Make the authenticated live bootstrap mandatory before Deal work and clarify
-  that it loads the server-owned two-part private Brain plus the separate Live
-  Deal Page field contract. CLI remains only the tool/transport layer.
-- Teach CLI and MCP Agents that Information never updates Page automatically,
-  every Page content field is Agent-writable, and field authorship controls
-  attribution rather than permission.
-
 ## [1.26.0] - 2026-08-11
 
 ### Added

package/README.md

@@ -90,8 +90,9 @@ When Page prose is human-visible, write one bilingual field value as
 `{"en":"natural English","zh":"自然中文"}`. The Web language switch selects
 the reader's version from the same Page revision. Keep language-neutral names,
 enums, URLs, numbers, dates, and source IDs scalar. Information and raw Input
-stay in their original language with provenance. The CLI rejects new scalar
-Page prose and incomplete language pairs before they reach Core; historical
+stay in their original language with provenance. Core rejects new scalar Page
+prose according to its private Page contract; the public CLI catches malformed
+half-localized pairs without maintaining a second field whitelist. Historical
 scalar prose remains readable.
 
 Raw user input example:
@@ -121,6 +122,27 @@ For user-originated work, preserve the exact words in
 Chat and Event are system-owned. There is no caller-controlled Event append or
 general Chat-forging operation.
 
+## Deal Memory sidecar
+
+Deal Memory is a separate domain alongside the five-resource Deal model. Each
+deal can have one canonical, human-readable Markdown Deal Story:
+
+```bash
+llama memory read <dealId>
+llama memory read <dealId> --raw
+llama memory write <dealId> --markdown deal-story.md
+llama memory write <dealId> --markdown deal-story.md --expected-version '"etag-from-read"'
+```
+
+The first write omits `--expected-version`. Updating an existing story requires
+the opaque `version` returned by `read`; a stale value fails instead of losing a
+concurrent edit. This uses the same `llama auth login` identity. CLI calls the
+authenticated Command Core adapter only—it has no sidecar URL, service token,
+S3 credentials, or direct database access.
+
+`llama deal read --detail memory` still means structured Deal Information.
+`llama memory read` means the separate accumulated Markdown Deal Story.
+
 ## Five Deal resources
 
 1. Live Deal Page — current human-visible state.
@@ -148,7 +170,9 @@ Its Deal surface is also exactly four tools:
 - `write_deal`
 
 Authentication, skill discovery, Wiki, admin audit, preferences, and external
-pitch remain separate non-Deal domains.
+pitch remain separate non-Deal domains. Deal Memory likewise has two separate
+MCP tools, `get_deal_memory` and `update_deal_memory`; it does not add a fifth
+Occam Deal tool.
 
 ## Agent bootstrap
 

package/README.zh-CN.md

@@ -116,6 +116,26 @@ llama deal write --json write.json
 Chat 和 Event 由系统拥有。Agent 不能自行伪造 Event 类型、顺序、作者、
 时间，也没有通用的 Chat 写入工具。
 
+## Deal Memory sidecar
+
+Deal Memory 是与五资源 Deal 模型并行、完全解耦的领域。每个 Deal 可以有一个
+人和 Agent 都能直接阅读的 Markdown Deal Story：
+
+```bash
+llama memory read <dealId>
+llama memory read <dealId> --raw
+llama memory write <dealId> --markdown deal-story.md
+llama memory write <dealId> --markdown deal-story.md --expected-version '"read 返回的 etag"'
+```
+
+第一次创建时不传 `--expected-version`；以后更新必须使用前一次 `read` 返回的
+不透明 `version`，旧版本会安全失败，不会覆盖他人的新内容。它复用同一个
+`llama auth login` 身份。CLI 只调用经过认证的 Command Core adapter，不持有
+sidecar URL、service token、S3 凭证，也不直接访问数据库。
+
+`llama deal read --detail memory` 仍表示结构化 Deal Information；
+`llama memory read` 表示独立的 Markdown Deal Story。
+
 ## Deal 只有五种业务资源
 
 1. Live Deal Page：人类看到的当前状态；
@@ -141,7 +161,9 @@ MCP 的 Deal 工具同样恰好四个：
 - `write_deal`
 
 认证、skill discovery、Wiki、admin audit、preferences 和 external pitch
-属于其他独立领域，不会扩大 Deal action space。
+属于其他独立领域，不会扩大 Deal action space。Deal Memory 同样是独立领域，
+对应 `get_deal_memory` 和 `update_deal_memory` 两个 MCP 工具，并不增加第五个
+Occam Deal 工具。
 
 ## Agent 启动
 

package/bin/llama-mcp.mjs

@@ -5,10 +5,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import {
+  formatErrorForDisplay,
   getAuthHeaders,
   readBriefing,
   request,
   setClientRuntime,
+  structuredBootstrapManifest,
 } from "../lib/client.mjs";
 import {
   clearExternalSession,
@@ -20,8 +22,10 @@ import {
 import {
   buildDealReadPath,
   buildDealSearchPath,
+  compactDealWriteResult,
   prepareDealCommand,
 } from "../lib/deal-actions.mjs";
+import { buildDealMemoryPath } from "../lib/deal-memory-actions.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -36,12 +40,12 @@ function textResult(text, isError = false) {
   };
 }
 
-async function callApi(method, path, body) {
+async function callApi(method, path, body, transform = (value) => value) {
   try {
-    const result = await request(method, path, body);
+    const result = transform(await request(method, path, body));
     return textResult(typeof result === "string" ? result : JSON.stringify(result, null, 2));
   } catch (error) {
-    return textResult(`Error: ${error?.message ?? String(error)}`, true);
+    return textResult(formatErrorForDisplay(error), true);
   }
 }
 
@@ -51,6 +55,54 @@ const originSchema = z.object({
   originatingChatRecordId: z.string().uuid().optional(),
 });
 
+const writeDealCommandSchema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("input.submit"),
+    dealId: z.string().uuid(),
+    format: z.string().min(1).max(120).optional(),
+    content: z.any(),
+    source: z.record(z.string(), z.any()).optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+  z.object({
+    operation: z.literal("information.put"),
+    dealId: z.string().uuid(),
+    informationId: z.string().uuid().optional(),
+    type: z.string().min(1).max(120),
+    labels: z.array(z.string()).optional(),
+    subject: z.record(z.string(), z.any()).optional(),
+    value: z.any(),
+    expectedVersion: z.number().int().positive().optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+  z.object({
+    operation: z.literal("page.patch"),
+    dealId: z.string().uuid(),
+    patch: z.record(z.string(), z.any()),
+    expectedRevision: z.number().int().nonnegative().optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+  z.object({
+    operation: z.literal("artifact.put"),
+    dealId: z.string().uuid(),
+    artifactId: z.string().uuid().optional(),
+    kind: z.string().min(1).max(120),
+    title: z.string().min(1).max(500),
+    mimeType: z.string().min(1).max(240),
+    contentBase64: z.string().min(1).optional(),
+    storageKey: z.string().min(1).optional(),
+    storageUrl: z.string().url().optional(),
+    byteSize: z.number().int().nonnegative().optional(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    metadata: z.record(z.string(), z.any()).optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+]);
+
 // Deal is deliberately a closed four-tool surface. Do not add split resource
 // tools here: one more tool is one more branch every agent must reason about.
 server.registerTool(
@@ -70,7 +122,7 @@ server.registerTool(
 server.registerTool(
   "read_deal",
   {
-    description: "Read one Deal. Live Page and its current private field contract are always returned; Information is memory and never updates Page automatically.",
+    description: "Read one Deal. Live Page is current human-visible state; Information is memory and never updates Page automatically. Page field semantics come from agent_bootstrap, not every Deal read.",
     inputSchema: {
       dealId: z.string().min(1),
       detail: z.enum(["overview", "memory", "files", "conversation", "history", "all"]).optional(),
@@ -99,36 +151,48 @@ server.registerTool(
 server.registerTool(
   "write_deal",
   {
-    description: "The only Deal mutation tool: input.submit, information.put, page.patch, or artifact.put. All Page content fields are Agent-writable; author controls attribution, not permission. Use the read/bootstrap field contract and bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots.",
+    description: "The only Deal mutation tool. Pass one command: input.submit, information.put, page.patch, or artifact.put. All Page content fields are Agent-writable; author controls attribution, not permission. Use the bootstrap field contract and bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots.",
+    // MCP SDK 1.30 only publishes object schemas at the tool root. Nesting one
+    // command preserves the real discriminated union instead of flattening four
+    // incompatible operations into false affordances.
+    inputSchema: { command: writeDealCommandSchema },
+  },
+  async ({ command }) => callApi(
+    "POST",
+    "/api/occam/deals/commands",
+    prepareDealCommand("write", command),
+    (result) => compactDealWriteResult(command, result),
+  ),
+);
+
+// Deal Memory is a separate sidecar domain. These do not add an Occam Deal
+// business resource or widen the deliberately closed four-tool Deal surface.
+server.registerTool(
+  "get_deal_memory",
+  {
+    description: "Read the complete canonical Markdown Deal Story and its opaque concurrency version.",
+    inputSchema: { dealId: z.string().uuid() },
+  },
+  // @core-api-operation GET /api/deal-memory/{dealId}/story
+  async ({ dealId }) => callApi("GET", buildDealMemoryPath(dealId)),
+);
+
+server.registerTool(
+  "update_deal_memory",
+  {
+    description: "Create or replace the complete Markdown Deal Story. Existing stories require the version returned by get_deal_memory; stale writes fail safely.",
     inputSchema: {
-      operation: z.enum(["input.submit", "information.put", "page.patch", "artifact.put"]),
       dealId: z.string().uuid(),
-      patch: z.record(z.string(), z.any()).optional(),
-      expectedRevision: z.number().int().nonnegative().optional(),
-      informationId: z.string().uuid().optional(),
-      type: z.string().min(1).max(120).optional(),
-      labels: z.array(z.string()).optional(),
-      subject: z.record(z.string(), z.any()).optional(),
-      value: z.any().optional(),
-      expectedVersion: z.number().int().positive().optional(),
-      format: z.string().min(1).max(120).optional(),
-      content: z.any().optional(),
-      source: z.record(z.string(), z.any()).optional(),
-      artifactId: z.string().uuid().optional(),
-      kind: z.string().min(1).max(120).optional(),
-      title: z.string().min(1).max(500).optional(),
-      mimeType: z.string().min(1).max(240).optional(),
-      contentBase64: z.string().min(1).optional(),
-      storageKey: z.string().min(1).optional(),
-      storageUrl: z.string().url().optional(),
-      byteSize: z.number().int().nonnegative().optional(),
-      sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
-      metadata: z.record(z.string(), z.any()).optional(),
-      origin: originSchema,
-      idempotencyKey: z.string().min(1).max(240).optional(),
+      markdown: z.string().min(1).max(1_048_576),
+      expected_version: z.string().min(1).optional(),
     },
   },
-  async (input) => callApi("POST", "/api/occam/deals/commands", prepareDealCommand("write", input)),
+  // @core-api-operation PUT /api/deal-memory/{dealId}/story
+  async ({ dealId, markdown, expected_version }) => callApi(
+    "PUT",
+    buildDealMemoryPath(dealId),
+    { markdown, ...(expected_version ? { expected_version } : {}) },
+  ),
 );
 
 server.registerTool(
@@ -158,7 +222,12 @@ server.registerTool(
   async ({ limit } = {}) => {
     const params = new URLSearchParams({ clientVersion: PKG_VERSION });
     if (limit) params.set("limit", String(limit));
-    return callApi("GET", `/api/agent/manifest?${params}`);
+    try {
+      const result = await request("GET", `/api/agent/manifest?${params}`);
+      return textResult(JSON.stringify(structuredBootstrapManifest(result), null, 2));
+    } catch (error) {
+      return textResult(formatErrorForDisplay(error), true);
+    }
   },
 );
 

package/bin/llama.mjs

@@ -4,6 +4,7 @@ import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import readline from "node:readline";
 import {
+  formatErrorForDisplay,
   getAuthHeaders,
   getBaseUrl,
   getToken,
@@ -12,6 +13,7 @@ import {
   readCanonicalToken,
   readLegacyConfig,
   request,
+  structuredBootstrapManifest,
   tryGcloudIdentityToken,
   writeCanonicalToken,
   writeLegacyConfig,
@@ -33,9 +35,14 @@ import {
   DEAL_ACTIONS,
   buildDealReadPath,
   buildDealSearchPath,
+  compactDealWriteResult,
   prepareDealCommand,
   readJsonInput,
 } from "../lib/deal-actions.mjs";
+import {
+  buildDealMemoryPath,
+  readMarkdownInput,
+} from "../lib/deal-memory-actions.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -48,6 +55,10 @@ Deal has exactly four actions:
   llama deal create --json <file|->
   llama deal write --json <file|->
 
+Deal Memory is a separate sidecar domain through the same login:
+  llama memory read <dealId> [--raw]
+  llama memory write <dealId> --markdown <file|-> [--expected-version <version>]
+
 Separate preserved domains:
   llama auth status|login|logout
   llama token set|show
@@ -82,13 +93,32 @@ read-modify-write complete Page arrays and preserve sibling slots.
 create JSON:
   {"companyName":"Acme","page":{},"information":[],"origin":{"kind":"user","originalUserUtterance":"..."}}
 
-write operation:
-  input.submit | information.put | page.patch | artifact.put
+write JSON (CLI derives idempotencyKey when omitted):
+  input.submit:    {"operation":"input.submit","dealId":"<uuid>","content":"<original input>","format":"text","source":{},"origin":{"kind":"user","originalUserUtterance":"..."}}
+  information.put:{"operation":"information.put","dealId":"<uuid>","type":"founder_claim","labels":["founder-stated"],"subject":{"topic":"traction"},"value":{"content":"...","source":{"kind":"first_meeting_transcript"}},"origin":{"kind":"user","originalUserUtterance":"..."}}
+  page.patch:      {"operation":"page.patch","dealId":"<uuid>","patch":{"description":{"en":"...","zh":"..."}},"origin":{"kind":"agent"}}
+  artifact.put:    {"operation":"artifact.put","dealId":"<uuid>","kind":"deck","title":"deck.pdf","mimeType":"application/pdf","storageKey":"<drive-file-id>","storageUrl":"https://drive.google.com/...","byteSize":123,"sha256":"<64 hex>","origin":{"kind":"user","originalUserUtterance":"..."}}
+
+For Information, origin records who caused the write and preserves user words;
+value.source records where the evidence came from.
 
 Core owns Chat Records, append-only Deal Events, Drive provisioning, audit,
 and idempotency. User-originated work must preserve exact wording in
 origin.originalUserUtterance or reference origin.originatingChatRecordId.`;
 
+const HELP_MEMORY = `Llama Deal Memory — one canonical Markdown Deal Story
+
+  llama memory read <dealId> [--raw]
+  llama memory write <dealId> --markdown <file|-> [--expected-version <version>]
+
+Read returns the full JSON record, including its opaque version. --raw prints
+only the exact Markdown. A first write creates the story without a version.
+Every later write must pass the version from the preceding read; stale writes
+fail instead of overwriting newer understanding.
+
+This uses your existing Llama authentication. The CLI talks only to Command
+Core and never receives Deal Memory service credentials or AWS access.`;
+
 function parseFlags(args, allowed = null) {
   const flags = {};
   const positional = [];
@@ -115,7 +145,7 @@ function parseFlags(args, allowed = null) {
 }
 
 function usage(area) {
-  console.log(area === "deal" ? HELP_DEAL : HELP_ROOT);
+  console.log(area === "deal" ? HELP_DEAL : area === "memory" ? HELP_MEMORY : HELP_ROOT);
 }
 
 function assertDealAction(area, action) {
@@ -127,6 +157,28 @@ function assertDealAction(area, action) {
   }
 }
 
+const RETIRED_TOP_LEVEL_COMMANDS = Object.freeze({
+  brief: "llama deal write --json  (operation: page.patch)",
+  fact: "llama deal write --json  (operation: information.put)",
+  post: "llama deal write --json  (operation: input.submit)",
+  timeline: "llama deal read <dealId> --detail history",
+  html: "llama deal write --json  (operation: artifact.put)",
+  memo: "llama deal write --json  (operation: artifact.put)",
+  pipeline: "llama deal search|read|create|write",
+});
+
+function unknownCommandError(area, action) {
+  const replacement = RETIRED_TOP_LEVEL_COMMANDS[area];
+  if (replacement) {
+    return new Error(
+      `\`llama ${area}\` was retired in CLI 2.0.\n` +
+      `  → Use: ${replacement}\n` +
+      "  → Contract: llama agent bootstrap",
+    );
+  }
+  return new Error(`Unknown command: llama ${[area, action].filter(Boolean).join(" ")}`);
+}
+
 function onboardingNoAuth() {
   return `Llama team onboarding requires credentials.
 
@@ -441,7 +493,7 @@ async function main() {
     const params = new URLSearchParams({ clientVersion: PKG_VERSION });
     if (flags.limit && flags.limit !== true) params.set("limit", String(flags.limit));
     const manifest = await request("GET", `/api/agent/manifest?${params}`);
-    if (flags.json) print(manifest);
+    if (flags.json) print(structuredBootstrapManifest(manifest));
     else process.stdout.write(`${manifest.briefing || JSON.stringify(manifest, null, 2)}\n`);
     return;
   }
@@ -539,9 +591,37 @@ async function main() {
   if (area === "deal" && ["create", "write"].includes(action)) {
     const { flags } = parseFlags(rest, ["json"]);
     const input = await readJsonInput(flags.json);
-    print(await request("POST", "/api/occam/deals/commands", prepareDealCommand(action, input)));
+    const command = prepareDealCommand(action, input);
+    const response = await request("POST", "/api/occam/deals/commands", command);
+    print(compactDealWriteResult(command, response));
+    return;
+  }
+
+  if (area === "memory" && action === "read") {
+    const { flags, positional } = parseFlags(rest, ["raw"]);
+    const path = buildDealMemoryPath(positional[0]);
+    // @core-api-operation GET /api/deal-memory/{dealId}/story
+    const result = await request("GET", path);
+    if (flags.raw) process.stdout.write(result.markdown);
+    else print(result);
     return;
   }
+  if (area === "memory" && action === "write") {
+    const { flags, positional } = parseFlags(rest, ["markdown", "expected-version"]);
+    const path = buildDealMemoryPath(positional[0]);
+    const markdown = await readMarkdownInput(flags.markdown);
+    // @core-api-operation PUT /api/deal-memory/{dealId}/story
+    print(await request("PUT", path, {
+      markdown,
+      ...(typeof flags["expected-version"] === "string"
+        ? { expected_version: flags["expected-version"] }
+        : {}),
+    }));
+    return;
+  }
+  if (area === "memory") {
+    throw new Error("Memory actions: read, write.");
+  }
 
   if (area === "wiki") {
     await handleWiki(action, rest);
@@ -565,12 +645,12 @@ async function main() {
     return;
   }
 
-  throw new Error(`Unknown command: llama ${[area, action].filter(Boolean).join(" ")}`);
+  throw unknownCommandError(area, action);
 }
 
 main()
   .then(() => maybeNudgeUpdate())
   .catch((error) => {
-    console.error(`Error: ${error.message}`);
+    console.error(formatErrorForDisplay(error));
     process.exit(1);
   });

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "5.0.0",
+  "apiVersion": "5.1.0",
   "openapiVersion": "3.0.3",
-  "sha256": "c48ed580f9930b06445f62b94959a2ca4bf9780e59473f17588e1e6554914014",
-  "pathCount": 110,
-  "operationCount": 136
+  "sha256": "948a8d02ae833e8cfa2302bc3c615fc1d3c792ae774ebc25b16be81fd1b85fee",
+  "pathCount": 111,
+  "operationCount": 138
 }

package/contracts/required-operations.json

@@ -12,6 +12,7 @@
     { "method": "GET", "path": "/api/agent/preferences" },
     { "method": "GET", "path": "/api/agent/skills" },
     { "method": "GET", "path": "/api/agent/skills/{slug}" },
+    { "method": "GET", "path": "/api/deal-memory/{dealId}/story" },
     { "method": "GET", "path": "/api/me" },
     { "method": "GET", "path": "/api/oauth/authorize" },
     { "method": "GET", "path": "/api/occam/deals" },
@@ -28,6 +29,7 @@
     { "method": "POST", "path": "/api/oauth/token" },
     { "method": "POST", "path": "/api/occam/deals/commands" },
     { "method": "POST", "path": "/api/wiki/{slug}/restore" },
-    { "method": "POST", "path": "/api/wiki/save" }
+    { "method": "POST", "path": "/api/wiki/save" },
+    { "method": "PUT", "path": "/api/deal-memory/{dealId}/story" }
   ]
 }

package/lib/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.0.2",
-  "sourceSha": "dc52c43363b050072c70f45144909d93b4f42028",
+  "packageVersion": "2.1.0",
+  "sourceSha": "0a29fd1ecdfb2064a90d36e323549a0445b3a21e",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "5.0.0",
+    "apiVersion": "5.1.0",
     "openapiVersion": "3.0.3",
-    "sha256": "c48ed580f9930b06445f62b94959a2ca4bf9780e59473f17588e1e6554914014"
+    "sha256": "948a8d02ae833e8cfa2302bc3c615fc1d3c792ae774ebc25b16be81fd1b85fee"
   }
 }

package/lib/client.mjs

@@ -294,6 +294,9 @@ function inferCommand(method, endpoint) {
   if (pathname === "/api/occam/deals") return "deal.search";
   if (pathname === "/api/occam/deals/commands") return "deal.write";
   if (/^\/api\/occam\/deals\/[^/]+$/.test(pathname)) return "deal.read";
+  if (/^\/api\/deal-memory\/[^/]+\/story$/.test(pathname)) {
+    return verb === "GET" ? "memory.read" : "memory.write";
+  }
   if (pathname === "/api/me") return "auth.status";
   if (pathname.startsWith("/api/agent/skills")) return "skills.read";
   if (pathname === "/api/agent/manifest") return "agent.bootstrap";
@@ -534,7 +537,21 @@ function apiResponseError(data, status) {
     return error;
   }
   if (data?.code !== "MENTION_APPROVAL_REQUIRED") {
-    const error = new Error(message);
+    const issues = Array.isArray(data?.issues)
+      ? data.issues.map((issue) => {
+          const path = Array.isArray(issue?.path) && issue.path.length
+            ? issue.path.reduce(
+                (result, part) => typeof part === "number"
+                  ? `${result}[${part}]`
+                  : result ? `${result}.${part}` : String(part),
+                "",
+              )
+            : "$";
+          const detail = issue?.message || issue?.code || "Invalid value";
+          return `- ${path}: ${detail}`;
+        })
+      : [];
+    const error = new Error([message, ...issues].join("\n"));
     if (typeof data?.code === "string") error.code = data.code;
     error.details = data;
     error.status = status;
@@ -563,6 +580,21 @@ function apiResponseError(data, status) {
   return error;
 }
 
+export function formatErrorForDisplay(error) {
+  const message = error?.message ?? String(error);
+  if (/^Error(?:\[[^\]]+\])?:/u.test(message)) return message;
+  const code = typeof error?.code === "string" ? `[${error.code}]` : "";
+  return `Error${code}: ${message}`;
+}
+
+export function structuredBootstrapManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return manifest;
+  }
+  const { briefing: _renderedDuplicate, ...structured } = manifest;
+  return structured;
+}
+
 async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
   const authHeaders = await getAuthHeaders();
   if (Object.keys(authHeaders).length === 0) throw noAuthError();

package/lib/deal-actions.mjs

@@ -72,62 +72,6 @@ function validateLocalizedTextPairs(value, path = "page") {
   }
 }
 
-const LANGUAGE_NEUTRAL_PAGE_KEYS = new Set([
-  "companyName", "companyKey", "state", "pipelineStatus", "stage",
-  "theirStage", "ownerUserId", "sourceUserId", "website", "dealOwner",
-  "source", "sourceDirection", "proposedAmount", "roundSize", "valuation",
-  "founders", "deckLink", "location", "foundedYear", "leadInvestor",
-  "dateAdded", "tab", "sourcePerson", "createdByName", "createdByLabel",
-  "createdVia", "id", "name", "key", "slug", "url", "href", "email",
-  "linkedin", "handle", "status", "kind", "type", "tier", "confidence",
-  "currency", "unit", "format", "mimeType", "sha256", "timestamp",
-  "date", "year",
-]);
-const LANGUAGE_NEUTRAL_PAGE_CONTAINERS = new Set([
-  "manualTags", "investors", "founderEmails", "labels", "tags",
-]);
-const OPAQUE_PAGE_CONTAINERS = new Set([
-  "migration", "extra", "fieldProvenance",
-]);
-
-function pathKeys(path) {
-  return path.match(/[^.[\]]+/g)?.filter((part) => !/^\d+$/u.test(part)) ?? [];
-}
-
-function isLanguageNeutralPagePath(path) {
-  const keys = pathKeys(path);
-  if (keys.some((key) => OPAQUE_PAGE_CONTAINERS.has(key))) return true;
-  if (keys.some((key) => LANGUAGE_NEUTRAL_PAGE_CONTAINERS.has(key))) return true;
-  const key = keys.at(-1) ?? "";
-  if (LANGUAGE_NEUTRAL_PAGE_KEYS.has(key)) return true;
-  return /(?:Id|Ids|URL|Url|URI|Uri|Link|Email|Emails|At|Date|Year|Key|Slug|Hash)$/u.test(key);
-}
-
-function validateAgentAuthoredPageProse(value, path = "page") {
-  if (typeof value === "string") {
-    if (!isLanguageNeutralPagePath(path)) {
-      throw new Error(
-        `${path} agent-authored prose must be one value with non-empty en and zh`,
-      );
-    }
-    return;
-  }
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => validateAgentAuthoredPageProse(item, `${path}[${index}]`));
-    return;
-  }
-  if (!value || typeof value !== "object") return;
-  if (
-    Object.prototype.hasOwnProperty.call(value, "en") ||
-    Object.prototype.hasOwnProperty.call(value, "zh")
-  ) {
-    return;
-  }
-  for (const [key, child] of Object.entries(value)) {
-    validateAgentAuthoredPageProse(child, `${path}.${key}`);
-  }
-}
-
 export async function readJsonInput(path, stdin = process.stdin) {
   if (!path || path === true) throw new Error("--json <file|-> is required");
   const text = path === "-"
@@ -170,6 +114,32 @@ export function buildDealReadPath(dealId, detail = "overview") {
   return `/api/occam/deals/${encodeURIComponent(dealId)}${expansion ? `?expand=${expansion}` : ""}`;
 }
 
+/**
+ * page.patch previously echoed the entire Live Deal Page after every write.
+ * Keep the authoritative revision receipt and tell the Agent exactly what to
+ * read back, without paying another full-page context cost before verification.
+ */
+export function compactDealWriteResult(command, response) {
+  if (command?.operation !== "page.patch" || !response?.result?.page) return response;
+  const page = response.result.page;
+  return {
+    ...response,
+    result: {
+      idempotent: Boolean(response.result.idempotent),
+      page: {
+        id: page.id,
+        revision: page.revision,
+        updatedAt: page.updatedAt,
+      },
+      verify: {
+        dealId: command.dealId,
+        fields: Object.keys(command.patch ?? {}),
+        command: `llama deal read ${command.dealId}`,
+      },
+    },
+  };
+}
+
 export function prepareDealCommand(action, input) {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     throw new Error("Mutation JSON must be an object");
@@ -183,11 +153,9 @@ export function prepareDealCommand(action, input) {
   }
   if (action === "create") {
     validateLocalizedTextPairs(command.page ?? {});
-    validateAgentAuthoredPageProse(command.page ?? {});
   }
   if (action === "write" && command.operation === "page.patch") {
     validateLocalizedTextPairs(command.patch ?? {});
-    validateAgentAuthoredPageProse(command.patch ?? {});
   }
   return ensureIdempotencyKey(validateCommandOrigin(command));
 }

package/lib/deal-memory-actions.mjs

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+
+export const MAX_DEAL_STORY_BYTES = 1_048_576;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function buildDealMemoryPath(dealId) {
+  if (!UUID.test(String(dealId || ""))) {
+    throw new Error("Deal Memory requires a valid deal UUID");
+  }
+  return `/api/deal-memory/${encodeURIComponent(dealId)}/story`;
+}
+
+export async function readMarkdownInput(path, stdin = process.stdin) {
+  if (!path || path === true) throw new Error("--markdown <file|-> is required");
+  const markdown = path === "-"
+    ? await new Promise((resolve, reject) => {
+        let value = "";
+        stdin.setEncoding("utf8");
+        stdin.on("data", (chunk) => { value += chunk; });
+        stdin.on("end", () => resolve(value));
+        stdin.on("error", reject);
+      })
+    : await readFile(path, "utf8");
+  if (!markdown) throw new Error("Deal Story Markdown cannot be empty");
+  const bytes = Buffer.byteLength(markdown, "utf8");
+  if (bytes > MAX_DEAL_STORY_BYTES) {
+    throw new Error(`Deal Story is ${bytes} bytes; maximum is ${MAX_DEAL_STORY_BYTES}`);
+  }
+  return markdown;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
     "test": "npm run test:agent-routing && npm run test:contract",
     "test:agent-routing": "node scripts/verify-agent-routing.mjs",
-    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/deal-actions-cli.test.mjs scripts/deal-actions.test.mjs scripts/mcp-four-action-surface.test.mjs scripts/server-compatibility.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
+    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/deal-actions-cli.test.mjs scripts/deal-actions.test.mjs scripts/deal-memory-actions-cli.test.mjs scripts/deal-memory-actions.test.mjs scripts/mcp-four-action-surface.test.mjs scripts/server-compatibility.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
     "verify:artifact": "node scripts/verify-release-artifact.mjs",
     "verify:release": "npm test && npm run verify:artifact && node scripts/verify-tarball-clean.mjs",
     "prepack": "node scripts/prepare-build-manifest.mjs",