@llamaventures/cli 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -6,6 +6,23 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [2.1.2] - 2026-09-03
+
+### Fixed
+- Publish the minimal Deal Memory writing contract through CLI and MCP help:
+  coherent whole-file rewrites, required frontmatter, read-before-write
+  versioning (including placeholders), the no-material-improvement rule, and
+  the distinction from structured Deal Information.
+
+## [2.1.1] - 2026-09-03
+
+### Changed
+- `llama help deal` no longer hardcodes the Page field count; the count is
+  live in `llama agent bootstrap`.
+- Show `contentBase64` as the primary `artifact.put` example. Core stores the
+  bytes in the Deal's Drive folder and derives `byteSize` / `sha256` itself;
+  `storageKey` remains only for artifacts that already live elsewhere.
+
 ## [2.1.0] - 2026-09-03
 
 ### Added

package/README.md

@@ -134,11 +134,19 @@ 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.
+Always read before writing. If `read` returns any Story, including an empty
+placeholder, pass its opaque `version`; only a `404` means creation may omit
+`--expected-version`. A stale value fails instead of losing a concurrent edit.
+Rewrite the complete document as one coherent current understanding rather than
+appending an update log. Do not restate Live Deal Page or Deal Information
+fields, and do not write when the understanding would not materially improve.
+
+The Markdown needs a non-empty body and YAML frontmatter with `deal_id`, `uuid`,
+`created`, and `updated`. The first three values never change; `updated` must be
+an ISO 8601 timestamp with an offset and strictly advance on every write. 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.

package/README.zh-CN.md

@@ -128,10 +128,17 @@ 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 凭证，也不直接访问数据库。
+每次写入前都先读取。如果 `read` 返回任何 Story（包括空 placeholder），写入时
+必须传回其不透明 `version`；只有 `404` 才表示创建时可以省略
+`--expected-version`。旧版本会安全失败，不会覆盖他人的新内容。每次写入都要
+重写一份连贯的当前理解，不要追加更新日志，不要重复 Live Deal Page 或 Deal
+Information 字段；如果理解没有实质改善，就不要写。
+
+Markdown 必须有非空正文和 YAML frontmatter，其中包含 `deal_id`、`uuid`、
+`created`、`updated`。前三项不可更改；`updated` 必须是带时区偏移的 ISO 8601
+时间，并在每次写入时严格递增。它复用同一个 `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。

package/bin/llama-mcp.mjs

@@ -170,7 +170,7 @@ server.registerTool(
 server.registerTool(
   "get_deal_memory",
   {
-    description: "Read the complete canonical Markdown Deal Story and its opaque concurrency version.",
+    description: "Read the complete canonical Markdown Deal Story and its opaque concurrency version. A returned placeholder is an existing Story whose version is required for a write; only 404 means no Story exists.",
     inputSchema: { dealId: z.string().uuid() },
   },
   // @core-api-operation GET /api/deal-memory/{dealId}/story
@@ -180,7 +180,7 @@ server.registerTool(
 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.",
+    description: "Replace the complete Markdown Deal Story with one coherent current understanding; never append an update log, restate Live Deal Page/Deal Information fields, or write when understanding would not materially improve. Frontmatter must contain matching deal_id plus stable uuid and created timestamps; updated must strictly advance. Pass the version from get_deal_memory for every returned Story, including a placeholder; only 404 permits creation without expected_version.",
     inputSchema: {
       dealId: z.string().uuid(),
       markdown: z.string().min(1).max(1_048_576),

package/bin/llama.mjs

@@ -55,6 +55,8 @@ Deal has exactly four actions:
   llama deal create --json <file|->
   llama deal write --json <file|->
 
+Here --detail memory means structured Deal Information, not Deal Memory.
+
 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>]
@@ -85,8 +87,9 @@ Before any Page write:
 
 The authenticated bootstrap contains the two-part private Llama Brain:
 Investment Framework V3 plus the Llama Command operating skill. It also
-contains the separate current 61-field Page contract. CLI is the tool, not
-Brain. Information never updates Page automatically. page.patch is JSON
+contains the separate current Page field contract; its field count is live,
+so read it there. CLI is the tool, not Brain. Information never updates
+Page automatically. page.patch is JSON
 Merge Patch: objects merge, null deletes, and arrays replace whole arrays, so
 read-modify-write complete Page arrays and preserve sibling slots.
 
@@ -97,7 +100,13 @@ 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":"..."}}
+  artifact.put:    {"operation":"artifact.put","dealId":"<uuid>","kind":"deck","title":"deck.pdf","mimeType":"application/pdf","contentBase64":"<file bytes, base64>","origin":{"kind":"user","originalUserUtterance":"..."}}
+
+artifact.put sends the bytes as contentBase64; Core stores them in the Deal's
+own Drive folder and derives byteSize and sha256 itself. Do not supply a
+folder, storage key or URL for a file you hold. Write the JSON to a file and
+pass its path. Only an artifact that already lives elsewhere is referenced
+with storageKey (+ optional storageUrl) plus byteSize and sha256 instead.
 
 For Information, origin records who caused the write and preserves user words;
 value.source records where the evidence came from.
@@ -112,9 +121,23 @@ const HELP_MEMORY = `Llama Deal Memory — one canonical Markdown Deal Story
   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.
+only the exact Markdown. Always read before writing. If read returns a Story,
+including an empty placeholder, pass its version with --expected-version. Only
+a 404 means creation may omit the version; stale writes fail safely.
+
+Write one coherent current Story: replace the complete document instead of
+appending an update log. Do not restate Live Deal Page or Deal Information
+fields. If the understanding would not materially improve, do not write.
+
+The Markdown must have a non-empty body and YAML frontmatter containing:
+  deal_id: the route Deal UUID; never changes
+  uuid:     the Story UUID; never changes
+  created:  ISO 8601 with offset; never changes
+  updated:  ISO 8601 with offset; must strictly advance on every write
+
+Use authorized evidence, preserve uncertainty, and never invent information.
+llama deal read --detail memory reads structured Deal Information; it does not
+read this Story.
 
 This uses your existing Llama authentication. The CLI talks only to Command
 Core and never receives Deal Memory service credentials or AWS access.`;

package/lib/build-manifest.json

@@ -1,8 +1,8 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.1.0",
-  "sourceSha": "0a29fd1ecdfb2064a90d36e323549a0445b3a21e",
+  "packageVersion": "2.1.2",
+  "sourceSha": "bc642686f5c52df26bd927f7829303e5b10d3ce7",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {