@llamaventures/cli 2.5.0 → 2.5.1

package/AGENT_BRIEFING.md

@@ -219,8 +219,25 @@ language is invalid. New scalar Page prose is also invalid; historical scalar
 prose is read-compatible only. Information and raw Input retain their original
 language and provenance; do not manufacture a second source quote.
 
-Artifacts use `artifact.put`. Treat them as immutable source material. Read the
-artifact, then decide whether its content deserves Information or a Page patch.
+Artifacts use `artifact.put`. Read the Deal files first. To revise an existing
+file, reuse its `artifactId` and send the complete revised file, preserving
+applicable metadata; this adds an immutable version even when the title changes.
+`page.patch` does not edit file bytes. Omit the ID for a new document without a
+title collision; use a fresh UUID explicitly for a distinct same-name source.
+On `409 OCCAM_CONFLICT`, read the candidate documents and select an existing ID
+or intentionally create a distinct source. Do not treat a title as identity or
+rename a file to bypass the check. Ask only when the intended target remains
+unclear after reading. Verify the returned ID and version; preserve old links.
+Reuse the reference when file and metadata are unchanged. Separately decide
+whether its content supports Information or a Page update.
+
+Send complete bytes and the actual MIME type through `artifact.put`. Core hosts
+`text/html` in Command; never mirror it to Drive or require a Drive link for
+success. Other source files, including original transcripts and recordings, go
+to the Deal's Drive folder; the database retains metadata and references. Do
+not duplicate source-file bodies in Input, Information, Page or metadata. Save
+extracted facts and summaries with source references, preserve the user's
+request, and verify the exact Artifact version and hash through Command.
 
 ## Verification and safety
 

package/CHANGELOG.md

@@ -6,6 +6,18 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [2.5.1] - 2026-09-28
+
+### Fixed
+
+- Align CLI help and MCP guidance with Core storage routing: HTML is hosted in Command; non-HTML source files, including transcripts and recordings, live in Drive. Verify exact versions without requiring a Drive link for HTML.
+
+### Changed
+
+- Clarify when to append a version to an existing artifact versus create a distinct source, preserving document identity and old links.
+
+## [2.5.0] - 2026-09-10
+
 ### Added
 
 - Submit user/agent UX friction with `llama feedback submit` and MCP `feedback_submit`; read your receipt and resolution with `feedback show` / `feedback_show`.

package/README.md

@@ -84,7 +84,15 @@ the initial Live Page and Information, and appends Events atomically.
 - `input.submit` — preserve raw input in the Event Feed.
 - `information.put` — add or update one structured memory unit.
 - `page.patch` — update the human-visible Live Deal Page.
-- `artifact.put` — add an immutable memo/HTML/source artifact.
+- `artifact.put` — create a file or append an immutable version by reusing its `artifactId`.
+
+Read Deal files before uploading revisions. Reuse the existing `artifactId`
+even when renaming; send complete revised bytes and preserve applicable metadata.
+Omitting the ID creates a new file only when no current same-kind/title candidate
+exists. On `409 OCCAM_CONFLICT`, read the candidates and select the intended ID;
+for a genuinely distinct same-name source, explicitly supply a fresh UUID.
+Titles are not document identities. `page.patch` does not edit file bytes.
+Verify the intended ID/version and preserve old source links.
 
 When Page prose is human-visible, write one bilingual field value as
 `{"en":"natural English","zh":"自然中文"}`. The Web language switch selects

package/README.zh-CN.md

@@ -82,7 +82,13 @@ Core 会补上 `operation: deal.create`，创建或复用 Drive 文件夹，并
 - `input.submit`：把完整原始输入保存在 Event Feed；
 - `information.put`：写入一个结构化工作记忆单元；
 - `page.patch`：更新人类直接看到的 Live Deal Page；
-- `artifact.put`：添加不可变的 memo、HTML 或源文件。
+- `artifact.put`：创建文件，或复用 `artifactId` 为已有文件追加不可变版本。
+
+修改文件前先读项目的文件列表；即使改名，也复用原来的 `artifactId`，
+上传完整的新文件并保留适用的 metadata。省略 ID 时，只有不存在当前同类型、
+同标题文件才会新建。遇到 `409 OCCAM_CONFLICT`，读取候选内容来确定目标 ID；
+确实是另一份同名材料时，明确生成新的 UUID 作为 `artifactId`。
+标题不是文件身份，`page.patch` 也不修改文件内容。回读核对 ID 和版本，保留旧链接。
 
 给人看的 Page 文字必须在写入时同时提供自然的中英文：
 `{"en":"natural English","zh":"自然中文"}`。Web 的语言开关从同一个

package/bin/llama-mcp.mjs

@@ -113,7 +113,7 @@ const writeDealCommandSchema = z.discriminatedUnion("operation", [
   z.object({
     operation: z.literal("artifact.put"),
     dealId: z.string().uuid(),
-    artifactId: z.string().uuid().optional(),
+    artifactId: z.string().uuid().optional().describe("Reuse the existing ID to append a complete file version, including on rename. Omit for a new document without a title collision, or explicitly use a fresh UUID for a distinct same-name source."),
     kind: z.string().min(1).max(120),
     title: z.string().min(1).max(500),
     mimeType: z.string().min(1).max(240),
@@ -189,7 +189,7 @@ server.registerTool(
 server.registerTool(
   "write_deal",
   {
-    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. Before page.patch, use get_live_deal_page_schema for the exact fields being changed and write bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots. A Llama user's own judgment is human_subjective_view.people or human_subjective_view.business and must carry value.speaker, value.rawText quoted verbatim from origin.originalUserUtterance, and value.summary (the agent's restatement); it is rejected otherwise.",
+    description: "The only Deal mutation tool. Pass one command: input.submit, information.put, page.patch, or artifact.put. Before artifact.put, read Deal files: reuse artifactId for a revision; a same-kind/title collision without an ID returns OCCAM_CONFLICT. Titles are candidates, not identity. Select the intended existing ID from the request/content, or explicitly generate a fresh UUID for a distinct same-name source. Send complete revised bytes, preserve applicable metadata, and verify the ID/version. Core hosts text/html in Command; do not mirror HTML to Drive or require a Drive link. Non-HTML source files, including original transcripts and recordings, go to Drive through artifact.put. Keep source-file bodies out of Input, Information, Page and metadata; save extracted facts and summaries with source references and preserve the user request. page.patch does not edit file bytes. All Page content fields are Agent-writable; author controls attribution, not permission. Before page.patch, use get_live_deal_page_schema for the exact fields being changed and write bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots. A Llama user's own judgment is human_subjective_view.people or human_subjective_view.business and must carry value.speaker, value.rawText quoted verbatim from origin.originalUserUtterance, and value.summary (the agent's restatement); it is rejected otherwise.",
     // 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.

package/bin/llama.mjs

@@ -122,11 +122,29 @@ write JSON (CLI derives idempotencyKey when omitted):
   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","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.
+Before artifact.put, read the Deal files and distinguish a revision from a new source.
+To revise a document, reuse its artifactId and send the complete new file, even
+if its title changes. This appends a version; page.patch does not edit files.
+For a new document, omit artifactId. A current same-kind/title collision returns
+409 OCCAM_CONFLICT: read the candidate files and choose the intended existing ID,
+or supply a fresh UUID as artifactId for a genuinely distinct same-name source.
+A title is only a candidate, not identity. Do not rename just to bypass a conflict.
+Preserve applicable metadata and old links. Verify the same artifactId and an
+increased version (or idempotent replay). Reuse an unchanged file's reference.
+
+Revision example:
+  {"operation":"artifact.put","dealId":"<uuid>","artifactId":"<existing artifact uuid>","kind":"memo","title":"Memo.html","mimeType":"text/html","contentBase64":"<complete revised file, base64>","origin":{"kind":"user","originalUserUtterance":"Revise the memo"}}
+
+artifact.put sends complete bytes as contentBase64 with the actual mimeType.
+Core hosts text/html in Command; do not upload or mirror HTML to Drive.
+Non-HTML files, including original transcripts and recordings, go to the Deal's
+Drive folder; the database keeps metadata and references, not the file bytes.
+Do not copy source-file contents into input.submit, Information, Page or metadata.
+Extract facts and summaries with source references; preserve the user's request.
+Core derives byteSize and sha256. Do not supply a folder, storage key or URL for
+a file you hold. Write the JSON to a file and pass its path. Existing non-HTML
+Drive files may use storageKey and storageUrl plus byteSize and sha256 instead.
+Verify the exact Artifact version and hash; hosted HTML needs no Drive link.
 
 For Information, origin records who caused the write and preserves user words;
 value.source records where the evidence came from.

package/lib/build-manifest.json

@@ -1,8 +1,8 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.5.0",
-  "sourceSha": "2f1d1c40ee4a970fb8c028428aa25c2976222486",
+  "packageVersion": "2.5.1",
+  "sourceSha": "217090ff9e72abff0a7b9b220016f5638b3d925f",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {

package/package.json

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