@llamaventures/cli 2.3.0 → 2.5.0

package/AGENT_BRIEFING.md

@@ -233,3 +233,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,20 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+### 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
+
+- Read Deal artifact text and original bytes through Core with version/hash provenance.
+- Read Wiki uploads and supported page references; paginate text with a pinned source hash.
+- Verify source downloads and refuse to overwrite local files.
+
 ## [2.3.0] - 2026-09-04
 
 ### Changed

package/README.md

@@ -214,3 +214,50 @@ npm run verify:release
 
 Release artifacts are source-SHA certified. Publishing to npm and changing the
 production server's minimum version are separate, explicit release operations.
+
+### Read original source content
+
+Use `llama deal read <dealId> --artifact <artifactId>` to read a listed file's text,
+source hash and page/paragraph anchors. Use `llama wiki read <slug> --format text`
+for a Wiki page or its original uploaded document. `--attachment <referenceId>`
+follows a supported reference listed by the Wiki read. Long reads return
+`nextOffset`; continue with `--offset N --sha256 HASH`. `--output <file>` downloads
+and hash-verifies the original bytes without overwriting a local file.
+
+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

@@ -204,3 +204,36 @@ npm run verify:release
 
 发布包会绑定准确 source SHA。npm publish 与生产服务端强制最低版本是两个
 独立、需要明确授权的 release 动作。
+
+### 读取原始材料
+
+`llama deal read <dealId> --artifact <artifactId>` 读取文件正文、原文件哈希与页码／段落位置。
+`llama wiki read <slug> --format text` 读取 Wiki 正文或上传的原文件；
+`--attachment <referenceId>` 读取页面返回的受支持附件引用。
+长文用 `--offset <nextOffset> --sha256 <source.sha256>` 继续，文件变化时会拒绝拼接。
+`--output <文件路径>` 下载并核验原始字节，不覆盖已有文件。
+
+需要服务端支持正文读取。扫描 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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { buildArtifactReadPath, buildWikiReadPath } from "../lib/content-read.mjs";
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -25,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";
 
@@ -50,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(),
@@ -123,14 +147,27 @@ server.registerTool(
 server.registerTool(
   "read_deal",
   {
-    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.",
+    description: "Read one Deal. Live Page is current human-visible state; Information is memory and never updates Page automatically. Use artifactId to read original source text with page/paragraph anchors. Continue with nextOffset and source.sha256. 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(),
+      artifactId: z.string().uuid().optional(),
+      version: z.number().int().min(1).optional(),
+      offset: z.number().int().min(0).optional(),
+      limit: z.number().int().min(1).max(50000).optional(),
+      sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     },
   },
-  // @core-api-operation GET /api/occam/deals/{dealId}
-  async ({ dealId, detail }) => callApi("GET", buildDealReadPath(dealId, detail || "overview")),
+  async ({ dealId, detail, artifactId, ...options }) => {
+    if (artifactId) {
+      if (detail) throw new Error("Use artifactId or detail, not both");
+      // @core-api-operation GET /api/occam/deals/{dealId}/artifacts/{artifactId}
+      return callApi("GET", buildArtifactReadPath(dealId, artifactId, options));
+    }
+    if (Object.values(options).some(value => value !== undefined)) throw new Error("Content options require artifactId");
+    // @core-api-operation GET /api/occam/deals/{dealId}
+    return callApi("GET", buildDealReadPath(dealId, detail || "overview"));
+  },
 );
 
 server.registerTool(
@@ -344,11 +381,16 @@ server.registerTool(
 server.registerTool(
   "wiki_read",
   {
-    description: "Read one Wiki article by exact slug.",
-    inputSchema: { slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional() },
+    description: "Read one Wiki article. format=text extracts its original upload or page body. attachment follows an ID listed in attachments. Continuations require offset and sha256.",
+    inputSchema: {
+      slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional(),
+      format: z.literal("text").optional(), attachment: z.string().optional(),
+      offset: z.number().int().min(0).optional(), limit: z.number().int().min(1).max(50000).optional(),
+      sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    },
   },
-  async ({ slug, lang }) =>
-    callApi("GET", `/api/wiki/${encodeURIComponent(slug)}?lang=${lang === "zh" ? "zh" : "en"}`),
+  // @core-api-operation GET /api/wiki/{slug}
+  async ({ slug, ...options }) => callApi("GET", buildWikiReadPath(slug, options)),
 );
 
 server.registerTool(

package/bin/llama.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { buildArtifactReadPath, buildWikiReadPath, saveContentSource } from "../lib/content-read.mjs";
 import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import readline from "node:readline";
@@ -43,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);
@@ -70,7 +72,11 @@ Separate preserved domains:
   llama skills list|search|show
   llama pref list|add|approve|retire
   llama explain <url-or-object>
+  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
 
@@ -84,6 +90,15 @@ Exactly four actions:
   llama deal create --json <file|->
   llama deal write --json <file|->
 
+Read original source content:
+  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>]
+
+Artifact reads return source hashes, text and page/paragraph anchors. Continue with
+--offset <nextOffset> --sha256 <source.sha256>. --output saves verified original
+bytes without overwriting existing files. Wiki --format text reads the original
+upload when present; --attachment follows a reference listed by the page.
+
 Before any Page write:
   llama agent bootstrap
   llama page-schema read <field> [field...]
@@ -164,6 +179,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 = [];
@@ -194,6 +226,7 @@ function usage(area) {
     area === "deal" ? HELP_DEAL :
     area === "memory" ? HELP_MEMORY :
     area === "page-schema" ? HELP_PAGE_SCHEMA :
+    area === "feedback" ? HELP_FEEDBACK :
     HELP_ROOT,
   );
 }
@@ -461,7 +494,7 @@ async function handleWiki(action, rest) {
   if (action === "read") {
     if (!slug) throw new Error("Usage: llama wiki read <slug> [--lang en|zh]");
     // @core-api-operation GET /api/wiki/{slug}
-    print(await request("GET", `/api/wiki/${encodeURIComponent(slug)}?lang=${flags.lang === "zh" ? "zh" : "en"}`));
+    print(await saveContentSource(await request("GET", buildWikiReadPath(slug, flags)), flags.output));
     return;
   }
   if (action === "save") {
@@ -517,6 +550,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;
@@ -657,9 +710,17 @@ async function main() {
   }
   if (area === "deal" && action === "read") {
     const dealId = rest[0];
-    const { flags } = parseFlags(rest.slice(1), ["detail"]);
-    // @core-api-operation GET /api/occam/deals/{dealId}
-    print(await request("GET", buildDealReadPath(dealId, flags.detail === true ? "overview" : flags.detail || "overview")));
+    const { flags } = parseFlags(rest.slice(1), ["detail", "artifact", "version", "format", "offset", "limit", "sha256", "output"]);
+    if (flags.artifact !== undefined) {
+      if (flags.detail !== undefined) throw new Error("Use --artifact or --detail, not both");
+      // @core-api-operation GET /api/occam/deals/{dealId}/artifacts/{artifactId}
+      const result = await request("GET", buildArtifactReadPath(dealId, flags.artifact, flags));
+      print(await saveContentSource(result, flags.output));
+    } else {
+      if (["version", "format", "offset", "limit", "sha256", "output"].some(key => flags[key] !== undefined)) throw new Error("Content options require --artifact");
+      // @core-api-operation GET /api/occam/deals/{dealId}
+      print(await request("GET", buildDealReadPath(dealId, flags.detail === true ? "overview" : flags.detail || "overview")));
+    }
     return;
   }
   if (area === "deal" && ["create", "write"].includes(action)) {

package/contracts/core-api.json

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

package/contracts/required-operations.json

@@ -2,35 +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/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.3.0",
-  "sourceSha": "c68a1849a4c43edbcc340a8f47f21cf16ca615ef",
+  "packageVersion": "2.5.0",
+  "sourceSha": "2f1d1c40ee4a970fb8c028428aa25c2976222486",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "5.3.0",
+    "apiVersion": "5.9.0",
     "openapiVersion": "3.0.3",
-    "sha256": "b793f67038b48cdfbfcc9141153132689c40e84adfbe087b0dbef3a409f5e5d5"
+    "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;
@@ -291,6 +296,7 @@ function inferCommand(method, endpoint) {
   if (pathname === "/api/wiki/search") return "wiki.search";
   if (pathname === "/api/wiki/save") return "wiki.save";
   if (/^\/api\/wiki\/[^/]+$/.test(pathname)) return verb === "GET" ? "wiki.read" : "wiki.write";
+  if (/^\/api\/occam\/deals\/[^/]+\/artifacts\/[^/]+$/.test(pathname)) return "deal.read";
   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";
@@ -360,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({
@@ -601,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/content-read.mjs

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+
+function parameters(options) {
+  const params = new URLSearchParams();
+  const format = options.output ? "source" : options.format || "text";
+  if (!["text", "source"].includes(format)) throw new Error("--format must be text or source");
+  params.set("format", format);
+  for (const [key, min, max] of [["version", 1, Number.MAX_SAFE_INTEGER], ["offset", 0, 2000000], ["limit", 1, 50000]]) {
+    if (options[key] === undefined) continue;
+    if (!/^\d+$/.test(String(options[key])) || !Number.isSafeInteger(Number(options[key])) || Number(options[key]) < min || Number(options[key]) > max) throw new Error(`Invalid --${key}`);
+    params.set(key, String(options[key]));
+  }
+  if (options.sha256 !== undefined) {
+    if (!/^[a-f0-9]{64}$/.test(options.sha256)) throw new Error("Invalid --sha256");
+    params.set("sha256", options.sha256);
+  }
+  if (Number(options.offset) > 0 && !options.sha256) throw new Error("Continuation reads require --sha256 from the first response");
+  if (options.output !== undefined && (typeof options.output !== "string" || !options.output)) throw new Error("--output requires a file path");
+  return params;
+}
+
+export function buildArtifactReadPath(dealId, artifactId, options = {}) {
+  if (typeof dealId !== "string" || !dealId || typeof artifactId !== "string" || !artifactId) throw new Error("Usage: llama deal read <dealId> --artifact <artifactId>");
+  return `/api/occam/deals/${encodeURIComponent(dealId)}/artifacts/${encodeURIComponent(artifactId)}?${parameters(options)}`;
+}
+
+export function buildWikiReadPath(slug, options = {}) {
+  if (typeof slug !== "string" || !slug) throw new Error("Usage: llama wiki read <slug>");
+  const params = options.format || options.output || options.attachment ? parameters(options) : new URLSearchParams();
+  params.set("lang", options.lang === "zh" ? "zh" : "en");
+  if (options.attachment !== undefined) {
+    if (typeof options.attachment !== "string" || !options.attachment) throw new Error("--attachment requires a reference ID from the wiki read");
+    params.set("attachment", options.attachment);
+  }
+  if (options.version !== undefined) throw new Error("Wiki reads pin --sha256, not --version");
+  if (!options.format && !options.output && !options.attachment && [options.offset, options.limit, options.sha256].some(x => x !== undefined)) throw new Error("Use --format text with pagination options");
+  return `/api/wiki/${encodeURIComponent(slug)}?${params}`;
+}
+
+export async function saveContentSource(result, output) {
+  if (!output) return result;
+  if (result?.format !== "source" || typeof result.contentBase64 !== "string") throw new Error("Server did not return original file bytes");
+  const bytes = Buffer.from(result.contentBase64, "base64");
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (sha256 !== result.source?.sha256 || bytes.length !== result.source?.byteSize) throw new Error("Downloaded file hash or size does not match the source");
+  await writeFile(output, bytes, { flag: "wx", mode: 0o600 });
+  return { saved: output, source: result.source, verified: true };
+}

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.3.0",
+  "version": "2.5.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/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",