@llamaventures/cli 2.4.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
 
@@ -233,3 +250,19 @@ artifact, then decide whether its content deserves Information or a Page patch.
 - Wiki, admin audit, external pitch, authentication, and skill discovery are
   separate domains. Deal Memory is also separate. None expands the four-action
   Occam Deal space.
+
+## Report UX friction
+
+When a user, agent or both encounter a concrete obstacle (including a task that
+eventually succeeds), use `llama feedback submit --title ... --body ...
+--experienced-by user|agent|both` or MCP `feedback_submit`. Two fields suffice;
+optional expected/steps/impact/workaround/suggestion explain the obstacle.
+Use `llama help feedback` for JSON input and diagnostics. Versions are captured
+when available; do not guess unknown host/model versions. Separate observation
+from hypothesis, report once per obstacle, and never attach credentials, full
+transcripts, file contents, raw arguments or arbitrary environment variables.
+Only explicitly correlate a request from this task; concurrent agents share
+local telemetry state. Retain submission_id for identical retries, read the
+receipt with `llama feedback show` / `feedback_show`, and never let reporting
+failure block the original task or produce recursive feedback. New tools need
+Core API 5.9.0; do not loop if the server has not added them yet.

package/CHANGELOG.md

@@ -6,6 +6,24 @@ 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`.
+- Capture CLI/build and OS/Node versions, plus available coding-agent host identity/version with explicit provenance. Unknown versions stay absent.
+- Bounded authenticated submissions, retry IDs, credential redaction and no recursive feedback telemetry. New feedback commands require Core API 5.9.0; existing commands retain compatibility.
+
 ## [2.4.0] - 2026-09-09
 
 ### Added

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
@@ -228,3 +236,36 @@ These options require a Core version with source-content reads. Scanned PDFs
 may require OCR; no-text, missing files, unsupported formats and denied storage
 are explicit outcomes, not evidence that a memo has been read. MCP exposes the
 same text reads inside `read_deal` and `wiki_read`.
+
+## UX friction feedback
+
+Report obstacles encountered by a user, agent or both, including tasks that
+succeeded after confusion or unnecessary steps. Two fields are enough:
+
+```bash
+llama feedback submit --title "Confusing empty response" --body "Expected source text, but the successful response was empty." --experienced-by agent
+llama feedback submit --file feedback.json
+llama feedback show <feedback-id>
+llama help feedback
+```
+
+`--file -` reads JSON from stdin. Optional `details` fields: expected, steps,
+impact, workaround, suggestion. `experienced_by` defaults to both. The CLI adds
+its version/build, OS/Node and available agent identity; MCP captures its
+initialized host name/version. `--agent-name`, `--agent-version`, `--model` (or
+`LLAMA_AGENT_CLIENT`, `LLAMA_AGENT_VERSION`, `LLAMA_AGENT_MODEL`) are explicit
+reports. Missing versions stay absent; installed programs are never executed
+to guess a running host version. Automatic metadata describes the submitting
+process; retrospective reports can explicitly supply historical environment
+and `occurred_at` through JSON.
+
+Keep the returned `submission_id` for identical retries (`--submission-id`).
+One report per obstacle per task. `--request-id` is optional and must refer to
+that task and reporter; no global last-command association is inferred. Do not
+include secrets, raw command arguments, environment dumps, full transcripts or
+file contents. Known credential patterns are redacted, not a guarantee that
+arbitrary text is secret-free. Submission failures are explicit and must not
+block the original task or trigger recursive feedback. Calls use a 15-second
+fetch budget and refuse redirects. Requires Core API 5.9.0, existing login and
+write scope; receipt reads require read scope and only return your own reports.
+MCP provides `feedback_submit` and `feedback_show` with the same behavior.

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 的语言开关从同一个
@@ -215,3 +221,25 @@ npm run verify:release
 
 需要服务端支持正文读取。扫描 PDF 不自动 OCR；无文字、缺失文件、不支持的格式、
 权限不足都会明确报告。MCP 在原有 `read_deal` 和 `wiki_read` 中提供相同正文读取能力。
+
+## 用户与 Agent 的 UX friction
+
+即使任务最终成功，困惑、多余步骤、反复尝试也值得反馈：
+
+```bash
+llama feedback submit --title "成功响应没有正文" --body "用户想总结附件，但读取成功后没有返回文本，任务无法继续。" --experienced-by agent
+llama feedback submit --file feedback.json
+llama feedback show <反馈ID>
+llama help feedback
+```
+
+标题和描述必填；`experienced_by` 为 user / agent / both，默认 both。
+CLI 自动附带版本、构建、OS/Node 和可确认的 Agent 身份；MCP 读取宿主声明的名称及版本。
+Agent 版本未知时不猜测。`--agent-name`、`--agent-version`、`--model` 可明确补充信息。
+较早发生的问题可通过 JSON 提供历史环境和 `occurred_at`，自动采集的环境属于当前提交进程。
+可选 details 字段为 expected、steps、impact、workaround、suggestion。
+同一次重试复用 submission_id；同一任务的同一障碍只报一次。
+不附完整对话、文件、命令参数或凭证，不自动关联全局最后一次调用。
+提交失败明确报错，不能声称成功，也不能触发递归反馈或阻塞原任务。
+新命令需要 Core API 5.9.0，沿用现有登录；用户只能读取自己的反馈。
+MCP 对应 feedback_submit / feedback_show。

package/bin/llama-mcp.mjs

@@ -26,6 +26,7 @@ import {
   compactDealWriteResult,
   prepareDealCommand,
 } from "../lib/deal-actions.mjs";
+import { submitFeedback, readFeedback } from "../lib/feedback.mjs";
 import { buildDealMemoryPath } from "../lib/deal-memory-actions.mjs";
 import { buildPageSchemaPath, MAX_PAGE_SCHEMA_FIELDS } from "../lib/page-schema.mjs";
 
@@ -51,6 +52,28 @@ async function callApi(method, path, body, transform = (value) => value) {
   }
 }
 
+server.registerTool("feedback_submit", {
+  description: "Report concrete UX friction experienced by a user, agent or both, even if the task succeeded. Separate observations from guesses. One report per obstacle; never include secrets, transcripts, files or raw command arguments. Failures must not block the original task or trigger recursive reporting. Reuse submission_id for retries. Host identity/version is captured when available; unknown versions stay absent.",
+  inputSchema: {
+    title: z.string().min(1).max(200), body: z.string().min(1).max(8000),
+    experienced_by: z.enum(["user", "agent", "both"]).optional(), submission_id: z.string().uuid().optional(),
+    occurred_at: z.string().datetime({ offset: true }).optional(),
+    details: z.object({ expected: z.string().max(2000).optional(), steps: z.string().max(4000).optional(), impact: z.string().max(2000).optional(), workaround: z.string().max(2000).optional(), suggestion: z.string().max(2000).optional() }).strict().optional(),
+    environment: z.object({ agent_name: z.string().max(120).optional(), agent_version: z.string().max(120).optional(), model: z.string().max(120).optional(), command: z.string().max(160).optional(), error_code: z.string().max(120).optional(), request_id: z.string().max(128).optional() }).strict().optional(),
+  },
+}, async input => {
+  try { return textResult(JSON.stringify(await submitFeedback(input, server.server.getClientVersion()), null, 2)); }
+  catch (error) { return textResult(formatErrorForDisplay(error), true); }
+});
+server.registerTool("feedback_show", {
+  description: "Read your own submitted friction report and resolution using its feedback ID.",
+  inputSchema: { id: z.string().uuid() },
+  annotations: { readOnlyHint: true },
+}, async ({ id }) => {
+  try { return textResult(JSON.stringify(await readFeedback(id), null, 2)); }
+  catch (error) { return textResult(formatErrorForDisplay(error), true); }
+});
+
 const originSchema = z.object({
   kind: z.enum(["user", "agent", "system"]),
   originalUserUtterance: z.string().min(1).optional(),
@@ -90,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),
@@ -166,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

@@ -44,6 +44,7 @@ import {
   buildDealMemoryPath,
   readMarkdownInput,
 } from "../lib/deal-memory-actions.mjs";
+import { submitFeedback, readFeedback, readFeedbackInput } from "../lib/feedback.mjs";
 import { buildPageSchemaPath } from "../lib/page-schema.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
@@ -74,6 +75,8 @@ Separate preserved domains:
   llama deal read <dealId> --artifact <artifactId> [--version N] [--offset N --sha256 HASH] [--limit N] [--output <file>]
   llama wiki read <slug> --format text [--attachment <referenceId>] [--offset N --sha256 HASH] [--output <file>]
   llama wiki search|read|save|delete|restore
+  llama feedback submit --title "..." --body "..." [--experienced-by user|agent|both]
+  llama feedback show <id>
   llama admin auth-events|deal-events|agent-events
   llama pitch start|say|upload|status|finalize|end
 
@@ -119,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.
@@ -176,6 +197,23 @@ Start with list. Before page.patch, read only the exact fields being changed;
 use a section read only when the write genuinely spans that section. This is a
 schema/field-prompt surface, not a fifth Deal action and not Page data.`;
 
+const HELP_FEEDBACK = `Report concrete user or agent UX friction, even when the task succeeds.
+
+  llama feedback submit --title "..." --body "..." [--experienced-by user|agent|both]
+  llama feedback submit --file <feedback.json|->
+  llama feedback show <id>
+
+Optional flags: --expected, --steps, --impact, --workaround, --suggestion,
+--agent-name, --agent-version, --model, --command, --error-code, --request-id,
+--occurred-at (ISO timestamp), --submission-id (reuse for retries).
+
+CLI/build, OS/Node and available agent identity are added automatically. Unknown
+agent versions stay absent. LLAMA_AGENT_CLIENT, LLAMA_AGENT_VERSION and
+LLAMA_AGENT_MODEL are explicit declarations, not inferred installed versions.
+Only attach a request ID from this task. Do not include credentials, full
+transcripts, file contents or raw command arguments. Report once per obstacle;
+feedback failure must not block the task or trigger recursive feedback.`;
+
 function parseFlags(args, allowed = null) {
   const flags = {};
   const positional = [];
@@ -206,6 +244,7 @@ function usage(area) {
     area === "deal" ? HELP_DEAL :
     area === "memory" ? HELP_MEMORY :
     area === "page-schema" ? HELP_PAGE_SCHEMA :
+    area === "feedback" ? HELP_FEEDBACK :
     HELP_ROOT,
   );
 }
@@ -529,6 +568,26 @@ async function main() {
     return;
   }
 
+  if (area === "feedback") {
+    if (action === "show" && rest.length === 1) { print(await readFeedback(rest[0])); return; }
+    if (action !== "submit") throw new Error("Usage: llama feedback submit|show; see llama help feedback");
+    const allowed = ["file", "title", "body", "experienced-by", "expected", "steps", "impact", "workaround", "suggestion", "agent-name", "agent-version", "model", "command", "error-code", "request-id", "occurred-at", "submission-id"];
+    const { flags, positional } = parseFlags(rest, allowed);
+    if (positional.length || Object.values(flags).some(v => typeof v !== "string")) throw new Error("Feedback flags require values; see llama help feedback");
+    let input;
+    if (flags.file) {
+      if (Object.keys(flags).some(k => !["file", "submission-id"].includes(k))) throw new Error("Use --file or field flags, not both");
+      input = await readFeedbackInput(flags.file);
+      if (flags["submission-id"]) input.submission_id = flags["submission-id"];
+    } else {
+      input = { title: flags.title, body: flags.body, details: {}, environment: {} };
+      for (const key of ["experienced-by", "occurred-at", "submission-id"]) if (flags[key]) input[key.replaceAll("-", "_")] = flags[key];
+      for (const key of ["expected", "steps", "impact", "workaround", "suggestion"]) if (flags[key]) input.details[key] = flags[key];
+      for (const key of ["agent-name", "agent-version", "model", "command", "error-code", "request-id"]) if (flags[key]) input.environment[key.replaceAll("-", "_")] = flags[key];
+    }
+    print(await submitFeedback(input)); return;
+  }
+
   assertDealAction(area, action);
 
   if (await handleAuth(area, action, rest)) return;

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "5.8.0",
+  "apiVersion": "5.9.0",
   "openapiVersion": "3.0.3",
-  "sha256": "ec68e92362c9f60eee94b81d73fb7cff2868c80d7c17c24a9e3122cc2743e7ad",
-  "pathCount": 113,
-  "operationCount": 140
+  "sha256": "619d4cabf0fa078bab2cdbb669fc9066701fc68ce194809a37c00a431bb66d35",
+  "pathCount": 117,
+  "operationCount": 144
 }

package/contracts/required-operations.json

@@ -2,36 +2,137 @@
   "format": "llama.cli-core-api-operations.v1",
   "coreApiContract": "contracts/core-api.json",
   "requiredOperations": [
-    { "method": "DELETE", "path": "/api/wiki/{slug}" },
-    { "method": "GET", "path": "/api/admin/agent-events" },
-    { "method": "GET", "path": "/api/admin/auth-events" },
-    { "method": "GET", "path": "/api/admin/deal-events" },
-    { "method": "GET", "path": "/api/agent/briefing" },
-    { "method": "GET", "path": "/api/agent/explain" },
-    { "method": "GET", "path": "/api/agent/manifest" },
-    { "method": "GET", "path": "/api/agent/page-schema" },
-    { "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" },
-    { "method": "GET", "path": "/api/occam/deals/{dealId}" },
-    { "method": "GET", "path": "/api/occam/deals/{dealId}/artifacts/{artifactId}" },
-    { "method": "GET", "path": "/api/wiki/{slug}" },
-    { "method": "GET", "path": "/api/wiki/search" },
-    { "method": "PATCH", "path": "/api/agent/preferences/{id}" },
-    { "method": "POST", "path": "/api/agent/client-events" },
-    { "method": "POST", "path": "/api/agent/preferences" },
-    { "method": "POST", "path": "/api/external/chat" },
-    { "method": "POST", "path": "/api/external/start-session" },
-    { "method": "POST", "path": "/api/external/upload" },
-    { "method": "POST", "path": "/api/oauth/revoke" },
-    { "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": "PUT", "path": "/api/deal-memory/{dealId}/story" }
+    {
+      "method": "DELETE",
+      "path": "/api/wiki/{slug}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/admin/agent-events"
+    },
+    {
+      "method": "GET",
+      "path": "/api/admin/auth-events"
+    },
+    {
+      "method": "GET",
+      "path": "/api/admin/deal-events"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/briefing"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/explain"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/manifest"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/page-schema"
+    },
+    {
+      "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/feedback/{id}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/me"
+    },
+    {
+      "method": "GET",
+      "path": "/api/oauth/authorize"
+    },
+    {
+      "method": "GET",
+      "path": "/api/occam/deals"
+    },
+    {
+      "method": "GET",
+      "path": "/api/occam/deals/{dealId}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/occam/deals/{dealId}/artifacts/{artifactId}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/wiki/search"
+    },
+    {
+      "method": "GET",
+      "path": "/api/wiki/{slug}"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/agent/preferences/{id}"
+    },
+    {
+      "method": "POST",
+      "path": "/api/agent/client-events"
+    },
+    {
+      "method": "POST",
+      "path": "/api/agent/preferences"
+    },
+    {
+      "method": "POST",
+      "path": "/api/external/chat"
+    },
+    {
+      "method": "POST",
+      "path": "/api/external/start-session"
+    },
+    {
+      "method": "POST",
+      "path": "/api/external/upload"
+    },
+    {
+      "method": "POST",
+      "path": "/api/feedback"
+    },
+    {
+      "method": "POST",
+      "path": "/api/oauth/revoke"
+    },
+    {
+      "method": "POST",
+      "path": "/api/oauth/token"
+    },
+    {
+      "method": "POST",
+      "path": "/api/occam/deals/commands"
+    },
+    {
+      "method": "POST",
+      "path": "/api/wiki/save"
+    },
+    {
+      "method": "POST",
+      "path": "/api/wiki/{slug}/restore"
+    },
+    {
+      "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.4.0",
-  "sourceSha": "5f2e08c216a111bc568e7dee925aa198674c6255",
+  "packageVersion": "2.5.1",
+  "sourceSha": "217090ff9e72abff0a7b9b220016f5638b3d925f",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "5.8.0",
+    "apiVersion": "5.9.0",
     "openapiVersion": "3.0.3",
-    "sha256": "ec68e92362c9f60eee94b81d73fb7cff2868c80d7c17c24a9e3122cc2743e7ad"
+    "sha256": "619d4cabf0fa078bab2cdbb669fc9066701fc68ce194809a37c00a431bb66d35"
   }
 }

package/lib/client.mjs

@@ -148,6 +148,11 @@ export function setClientRuntime(opts = {}) {
   if (opts.agentClient) runtimeAgentClient = String(opts.agentClient);
 }
 
+export function getFeedbackRuntime() {
+  const agent = detectAgentClient();
+  return { client: runtimeClient, agent, agentSource: runtimeAgentClient || process.env.LLAMA_AGENT_CLIENT ? "reported" : agent === "unknown" ? "unknown" : "detected" };
+}
+
 function detectAgentClient() {
   if (runtimeAgentClient) return runtimeAgentClient;
   if (process.env.LLAMA_AGENT_CLIENT) return process.env.LLAMA_AGENT_CLIENT;
@@ -361,7 +366,7 @@ function summarizeResult(data) {
 function shouldSkipTelemetry(endpoint) {
   if (process.env.LLAMA_TELEMETRY === "0") return true;
   const pathname = parseEndpoint(endpoint)?.pathname || endpoint;
-  return pathname === "/api/agent/client-events" || pathname === "/api/agent/eval-feedback";
+  return pathname === "/api/feedback" || pathname.startsWith("/api/feedback/") || pathname === "/api/agent/client-events" || pathname === "/api/agent/eval-feedback";
 }
 
 async function recordClientTelemetry({
@@ -602,6 +607,8 @@ async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
   const command = inferCommand(method, endpoint);
   const start = Date.now();
   const res = await fetch(`${getBaseUrl()}${endpoint}`, {
+    signal: opts.signal,
+    redirect: opts.redirect,
     method,
     headers: {
       "Content-Type": "application/json",

package/lib/feedback.mjs

@@ -0,0 +1,104 @@
+import os from "node:os";
+import { createReadStream } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { getBuildInfo } from "./build-info.mjs";
+import { getFeedbackRuntime, request } from "./client.mjs";
+
+const TOP = ["submission_id", "title", "body", "experienced_by", "occurred_at", "details", "environment"];
+const DETAILS = { expected: 2000, steps: 4000, impact: 2000, workaround: 2000, suggestion: 2000 };
+const ENV = { surface: 12, cli_version: 80, cli_source_sha: 80, agent_name: 120, agent_version: 120,
+  agent_name_source: 12, agent_version_source: 12, model: 120, model_source: 12,
+  os: 80, os_version: 120, arch: 40, node_version: 80, command: 160, error_code: 120, request_id: 128 };
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function redactFeedbackText(text) {
+  return text.replace(/\b(?:llc_|sk-|ghp_|github_pat_|ya29\.)[A-Za-z0-9_.-]+/g, "[redacted]")
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "[redacted]")
+    .replace(/\b(Bearer)\s+[^\s,;\x22\x27]+/gi, "$1 [redacted]")
+    .replace(/\b((?:access[_-]?token|refresh[_-]?token|api[_-]?key|token|secret|password|authorization|cookie)[\x22\x27]?\s*[:=]\s*)[^\r\n]+/gi, "$1[redacted]")
+    .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[redacted]@");
+}
+function object(value, allowed, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${name} field: ${key}`);
+  return value;
+}
+function text(value, max, name) {
+  if (typeof value !== "string" || !value.trim() || value.trim().length > max) throw new Error(`${name} requires 1–${max} characters`);
+  return redactFeedbackText(value.trim());
+}
+function strings(value, fields, name) {
+  const result = {};
+  for (const [key, val] of Object.entries(object(value, Object.keys(fields), name))) result[key] = text(val, fields[key], `${name}.${key}`);
+  return result;
+}
+export function feedbackId(id) {
+  if (typeof id !== "string" || !UUID.test(id)) throw new Error("Feedback ID must be a UUID");
+  return id;
+}
+export async function readFeedbackInput(file, stdin = process.stdin) {
+  const stream = file === "-" ? stdin : createReadStream(file);
+  let size = 0; const chunks = [];
+  for await (const chunk of stream) {
+    const bytes = Buffer.from(chunk); size += bytes.length;
+    if (size > 32768) { stream.destroy(); throw new Error("Feedback exceeds 32 KiB"); }
+    chunks.push(bytes);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+  catch { throw new Error("Feedback file must contain valid JSON"); }
+}
+export function prepareFeedback(input, host) {
+  object(input, TOP, "feedback");
+  const runtime = getFeedbackRuntime(); const build = getBuildInfo();
+  const supplied = strings(input.environment ?? {}, ENV, "environment");
+  const environment = {
+    surface: runtime.client, cli_version: build.packageVersion, cli_source_sha: build.sourceSha,
+    os: os.platform(), os_version: os.release(), arch: os.arch(), node_version: process.version,
+    agent_name: runtime.agent, agent_name_source: runtime.agentSource,
+    ...(host?.name ? { agent_name: host.name, agent_name_source: "host" } : {}),
+    ...(host?.version ? { agent_version: host.version, agent_version_source: "host" } : {}),
+    ...(process.env.LLAMA_AGENT_VERSION ? { agent_version: process.env.LLAMA_AGENT_VERSION, agent_version_source: "reported" } : {}),
+    ...(process.env.LLAMA_AGENT_MODEL ? { model: process.env.LLAMA_AGENT_MODEL, model_source: "reported" } : {}),
+    ...supplied,
+  };
+  if (supplied.agent_name && host?.name && supplied.agent_name !== host.name && !supplied.agent_version && !process.env.LLAMA_AGENT_VERSION) {
+    delete environment.agent_version;
+    delete environment.agent_version_source;
+  }
+  // Explicit overrides are declarations, not observations of the running host.
+  for (const key of ["agent_name", "agent_version", "model"]) {
+    if (supplied[key] && !supplied[`${key}_source`]) environment[`${key}_source`] = "reported";
+  }
+  for (const key of ["agent_name_source", "agent_version_source", "model_source"]) {
+    if (environment[key] && !["detected", "host", "reported", "unknown"].includes(environment[key])) throw new Error(`Invalid ${key}`);
+  }
+  if (!["cli", "mcp", "web", "api"].includes(environment.surface)) throw new Error("Invalid environment.surface");
+  const experiencedBy = input.experienced_by ?? "both";
+  if (!["user", "agent", "both"].includes(experiencedBy)) throw new Error("experienced_by must be user, agent or both");
+  if (input.occurred_at && (typeof input.occurred_at !== "string" || !/^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(input.occurred_at) || !Number.isFinite(Date.parse(input.occurred_at)))) throw new Error("occurred_at must be an ISO timestamp with timezone");
+  const result = {
+    submission_id: input.submission_id ? feedbackId(input.submission_id) : randomUUID(),
+    title: text(input.title, 200, "title"), body: text(input.body, 8000, "body"), experienced_by: experiencedBy,
+    ...(input.occurred_at ? { occurred_at: input.occurred_at } : {}),
+    details: strings(input.details ?? {}, DETAILS, "details"), environment: strings(environment, ENV, "environment"),
+  };
+  if (Buffer.byteLength(JSON.stringify(result)) > 32768) throw new Error("Feedback exceeds 32 KiB");
+  return result;
+}
+export async function submitFeedback(input, host) {
+  const body = prepareFeedback(input, host);
+  const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 15000);
+  try {
+    return await request("POST", "/api/feedback", body, { signal: controller.signal, redirect: "error" });
+  } catch (error) {
+    const wrapped = new Error(`Error[FEEDBACK_NOT_CONFIRMED]: Feedback submission is not confirmed. ${redactFeedbackText(error.message)}\nRetry the same report with submission_id=${body.submission_id}. Do not recursively report this failure.`);
+    wrapped.code = "FEEDBACK_NOT_CONFIRMED";
+    throw wrapped;
+  } finally { clearTimeout(timer); }
+}
+export async function readFeedback(id) {
+  const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 15000);
+  try {
+    // @core-api-operation GET /api/feedback/{id}
+    return await request("GET", `/api/feedback/${feedbackId(id)}`, undefined, { signal: controller.signal, redirect: "error" });
+  } finally { clearTimeout(timer); }
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "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/content-read.test.mjs 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/page-schema-cli.test.mjs scripts/page-schema.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/feedback.test.mjs scripts/content-read.test.mjs 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/page-schema-cli.test.mjs scripts/page-schema.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",