@llamaventures/cli 1.19.0 → 1.22.0

package/AGENT_BRIEFING.md

@@ -8,6 +8,7 @@ You are not just an AI assistant. You're an **extension of a team member** — w
 
 - **Your access scope is whatever your token allows.** Run `llama auth status` first; the response shows your role, identity, and active token source.
 - **All your writes are logged.** `auth_events` and `deal_events` capture everything. Pipeline data can always be traced back to who/what changed it.
+- **Never cue by implication.** A teammate cue creates an LC inbox item and may queue email under the user's identity. Cue a specific person only when the user explicitly authorized it in the current request. Referring to a teammate, ownership, responsibility, or writing their name is not permission.
 - **Public surfaces stay clean.** Anything that leaves the workspace — public repos, npm packages, external artifacts, shared links — must not leak internal people, deals, private URLs, or workflow nuance.
 - **Be direct, terse, action-oriented.** Save your words for the genuine judgment calls.
 - **Critical when thinking, helpful when executing.** Push back on weak logic, then ship the work cleanly.
@@ -63,10 +64,11 @@ A teammate says "I just met them and heard…" or pastes a chunk of notes. Your
 
 1. **Find the deal** — `llama deal search "<name>"` (Pipeline First). New name → offer to create it.
 2. **Split what they gave you into two kinds** — this is the whole data model:
+   - **A source packet with 2+ facts, or facts + a note → ingest once.** Build a JSON object with `source`, `facts`, and optional `note`, then run `llama deal ingest <dealId> --file <packet.json>`. This is the preferred agent path: one atomic, deduplicated, retry-safe commit. Reuse an explicit `idempotencyKey` when retrying the same material. The matching MCP tool is `deal_ingest` and uses the same packet shape.
    - **Verifiable claims → facts.** `llama deal fact add <dealId> --category <cat> --claim "…" --source "<where it came from>" --source-url <url>`. A claim someone *relayed* ("their ARR is $3M", "raised from a16z") is a fact at **unverified** trust — it's hearsay until checked. Pass `--attested` ONLY if you actually verified it against a source yourself. In raw API terms, the fact text field is `claim` (`value` is only a compatibility alias), `source` is the human-readable provenance label, and `sourceUrl` is the canonical URL.
    - **Their judgment / impression → a note.** `llama post <dealId> "…"`. "Founder seemed evasive", "I'd lean pass", "worth a second meeting" — opinion, not fact. Attributed, never "verified".
    - A pasted blob → pull the verifiable claims out as facts, capture their take as a note.
-3. **Read it back before you claim it's saved.** A tool call returning `{ok:true}` is NOT proof the content is where the user will look for it. After filing, run `llama deal feed <dealId>` and confirm your fact/note actually appears, THEN tell the user in plain language what you recorded and where. Never say "记好了 / saved" from the return value alone — the #1 failure is an agent writing to the wrong surface (e.g. the brief, which is the Memo and does NOT appear in the feed) and reporting success anyway. If it's not in the feed, you routed it wrong — fix it.
+3. **Read it back before you claim it's saved.** A generic tool call returning `{ok:true}` is NOT proof the content is where the user will look for it. `deal ingest` is the exception because its response is built from the rows and note block read back after commit: confirm `createdFacts`, `skippedFacts`, `note`, and `summary` in that receipt. For every other write, run `llama deal feed <dealId>` and confirm your fact/note actually appears. Never say "记好了 / saved" from a request acknowledgment alone — the #1 failure is an agent writing to the wrong surface (e.g. the brief, which is the Memo and does NOT appear in the feed) and reporting success anyway. If the authoritative ingest receipt or the feed read-back does not contain the material, fix it before reporting success.
    - **Authorship is automatic, don't fake it.** Everything you write via CLI/MCP is recorded as "via assistant" (you're the accountable human's assistant). You can't and shouldn't make it read as human-typed — that honesty is the feature. Facts you add stay **unverified** until a human confirms them; if you pass `--attested` (only when you actually checked the source) your ceiling is **agent-verified**, never human-vouched. Only a person, signed in at the browser, can vouch. The confirmation IS the trust step — never silently mark something verified.
 
 Why split it: facts and opinions live in different layers so the deal keeps one clean **source of truth** (facts, sourced + trust-rated) separate from people's **takes** (notes). The four layers — facts / notes / brief (AI's synthesis) / timeline — are documented in Llama Command's `docs/SCHEMA.md`.
@@ -130,8 +132,9 @@ These three look similar but land in different surfaces. Don't infer from the co
 
 | You want to… | Command | Lands in |
 |---|---|---|
+| File a **source packet** with multiple facts and/or one note | `llama deal ingest <dealId> --file packet.json` | Facts + optional note → deal **Feed**, atomically and retry-safe |
 | Record a **sourced, verifiable fact** | `llama deal fact add <dealId> --category <cat> --claim "…" --source "deck p3" --source-url <url>` | Facts → deal **Feed** (FACT card) + citable in the **Memo** |
-| Leave a **comment / opinion / question / reaction** for the team | `llama post <dealId> "…"` (`@name` to notify) | Posts → deal **Feed** (POST card); `@mention` fires email + UI badge |
+| Leave a **comment / opinion / question / reaction** for the team | `llama post <dealId> "…"`; add `--cue` only after explicit permission | Posts → deal **Feed** (POST card); authorized cues create email + UI badge |
 | Write **narrative that belongs in the IC memo** | `llama brief add-text <dealId> --heading "…" --body "…"` | Brief blocks → **Memo tab only — NOT in the Feed** |
 
 ⚠️ The trap: `brief add-text` is **not** visible in the Activity Feed. If the team should see it in the feed, use `llama post`. If it's a claim that needs a source + verification, use `llama deal fact add`. (It's `deal fact add`, not `fact-add`.)
@@ -147,7 +150,7 @@ The table below details the exact CLI for each destination.
 | Insights, decisions, framework improvements | Wiki (markdown) | `llama wiki save <slug> --content "..."` (with attribution — see below) |
 | **HTML wiki entry — standalone HTML page hosted at `/wiki/<slug>`** (sector landscape, market map, dashboard, hand-styled thesis page) | **Wiki (HTML)** | `llama wiki save <slug> --title "..." --file <path.html> --sources "..."`. Auto-detects content_type=html from extension. Public page is full-viewport sandboxed iframe takeover (no wiki chrome). Sources/status/title still required; appears in `wiki search` + backlinks. Use when the user says "deploy this HTML to wiki", "wiki 词条", "make this page a wiki entry". HTML must be self-contained (inline CSS/JS, image data URIs or external URLs) — asset bundles aren't supported on wiki yet. **Native comments + working in-page (#) anchor links are injected automatically** — readers discuss inline and the table of contents scrolls; you don't wire anything up (pages that already embed the comment widget are left as-is). |
 | Large files (deck / PDF / transcript) | Drive deal folder | the deal's `folder_url` (from `llama deal show`) → upload via your filesystem / Drive tool |
-| Cross-team mentions | Inbox + email | `llama post <dealId> "@<teammate> ..."` — server fires email + UI badge to the recipient |
+| Cross-team cues | Inbox + email | `llama post <dealId> "@<teammate> ..." --cue` — use `--cue` only after the user explicitly authorized that recipient |
 
 ### Attribution format (required for wiki writes)
 
@@ -165,8 +168,9 @@ Content. One block, one attribution. Don't mix fact and opinion in a single bloc
 | Level | Type | Behaviour |
 |---|---|---|
 | **L0** | Reads (`search`, `show`, `list`) | Just do it. Don't announce. Integrate the result into your reply. |
-| **L1** | Low-risk writes (timeline post, wiki append, add fact, add tag) | Do it, then tell the user **one line** afterward. |
+| **L1** | Low-risk writes (cue-free timeline post, wiki append, add fact, add tag) | Do it, then tell the user **one line** afterward. |
 | **L2** | Medium-risk writes (new deal, change stage, change owner, new wiki page) | Ask once: "Y/n — I'm about to do X". On yes, execute and report. Don't re-ask details. |
+| **L2-cue** | Any assistant-authored write that resolves to a teammate cue | Require explicit permission for the resolved people and inbox/email channels. Retry the exact write with `--cue` only after yes. If the user already explicitly asked to cue them, do not ask twice. |
 | **L3** | High-risk (delete deal, bulk change, overwrite someone else's wiki, force-push, regulatory-relevant) | Detailed explanation + explicit confirmation. Provide a dry-run / undo path when possible. |
 
 When in doubt, lean to a higher level (more confirmation), not lower.
@@ -288,7 +292,8 @@ llama wiki restore <slug> [--lang en|zh]
 
 # Timeline + posts
 llama timeline <dealId>
-llama post <dealId> "message"
+llama post <dealId> "message"             # cue-free note
+llama post <dealId> "@name respond" --cue # only after explicit user approval
 
 # Mentions inbox
 llama mentions
@@ -298,7 +303,7 @@ Run `llama --help` for the full surface (~40 commands).
 
 ## MCP-native agents
 
-If you support [MCP](https://modelcontextprotocol.io), **prefer the MCP server over parsing CLI output.** The same package ships `llama-mcp` (59 typed tools, identical auth chain).
+If you support [MCP](https://modelcontextprotocol.io), **prefer the MCP server over parsing CLI output.** The same package ships `llama-mcp` (55 typed tools, identical auth chain).
 
 Add to your MCP client config (Claude Desktop / Claude Code / Cursor / OpenClaw / Codex / etc.):
 

package/CHANGELOG.md

@@ -6,6 +6,52 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.22.0] - 2026-07-28
+
+### Added
+- Consume Llama Command's server-owned CLI/MCP compatibility headers on every
+  shared API request. Recommended upgrades are surfaced on stderr at most once
+  per day, including for non-TTY coding agents, while structured stdout remains
+  unchanged.
+- Surface hard `CLI_VERSION_UNSUPPORTED` responses with a stable error code,
+  exact upgrade command, and retry instruction.
+
+## [1.21.0] - 2026-07-24
+
+### Added
+- Add explicit `--cue` (CLI) and `cueAuthorized` (MCP) authorization for
+  teammate cues in posts and brief writes. Cue-free writes remain unchanged;
+  agents must obtain permission for the resolved recipients before setting it.
+
+### Changed
+- Agent onboarding now treats teammate cues as approval-required outbound
+  actions rather than ordinary low-risk timeline posts. Structured
+  `MENTION_APPROVAL_REQUIRED` errors retain recipient and channel context.
+
+## [1.20.0] - 2026-07-22
+
+### Added
+- Add `llama deal ingest <dealId> --file <packet.json>` and the matching
+  `deal_ingest` MCP tool for atomic, retry-safe source packets containing up to
+  50 facts and an optional Feed note.
+- Add `llama pref list|add|retire|approve` and the `pref_list` / `pref_add` /
+  `pref_set_status` MCP tools for standing agent preferences (Core API 3.1.0).
+  Own user scope activates immediately; team scope requires system-admin
+  approval. Content is hard-capped at 280 chars.
+
+### Changed
+- Prefer packet ingest for multi-fact agent writes; Core now canonicalizes fact
+  categories and skips exact source-aware duplicates before committing.
+- Pin the Core API consumer contract to 3.1.0.
+
+### Removed
+- Remove the retired generated-persona refresh and skill-correction commands
+  from the CLI, MCP tool registry, and required Core operation inventory.
+  Llama Command keeps authenticated historical reads and 410 compatibility
+  tombstones, but new clients can no longer invoke the retired workflow.
+- Remove `llama eval` and the `record_eval_feedback` MCP tool; the server-side
+  Golden Query Eval candidate pipeline was retired with Core API 3.0.0.
+
 ## [1.19.0] - 2026-07-16
 
 ### Added
@@ -520,7 +566,9 @@ assistant-drafted (🤖) and enforces the AI trust ceiling.
 
 ---
 
-[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.18.1...HEAD
+[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.22.0...HEAD
+[1.22.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.21.0...v1.22.0
+[1.21.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.20.0...v1.21.0
 [1.18.1]: https://github.com/Llama-Ventures/llama-cli/compare/v1.18.0...v1.18.1
 [1.18.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.3...v1.18.0
 [1.17.3]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.2...v1.17.3

package/README.md

@@ -7,7 +7,7 @@
 <p align="center">
   <strong>The Llama Ventures CLI &amp; MCP server.</strong><br/>
   One package, two binaries: <code>llama</code> — the CLI for humans and scripts —
-  and <code>llama-mcp</code> — a stdio MCP server with 59 typed tools for any
+  and <code>llama-mcp</code> — a stdio MCP server with 55 typed tools for any
   MCP-native agent. Both share the same auth chain, HTTP client, and error
   format, and talk to <a href="https://command.llamaventures.vc">command.llamaventures.vc</a>.
 </p>
@@ -98,9 +98,11 @@ llama deal feed <dealId>               # every contribution, newest first
 llama activity new-deals --since 24h   # recent deal creations
 llama activity updated-deals --since 7d # meaningful updates grouped by deal
 llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
+llama deal ingest <dealId> --file packet.json  # atomic multi-fact + optional Feed note; retry-safe
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "note body"
+llama post <dealId> "@name please respond" --cue  # only after explicit approval
 llama brief add-text <dealId> --heading "..." --body "..."
 llama wiki search "<query>"
 llama wiki save <slug> --title "..." --content "..."
@@ -113,6 +115,13 @@ Status vocabulary — `Interested`: tracked before any contact ·
 signal exists. `sourceDirection` is separate: `Inbound` came to the firm,
 `Outbound` we reached out first.
 
+For a deck, meeting note, email, or research packet, prefer `deal ingest` over a
+loop of `deal fact add` calls. The JSON object accepts `source`, up to 50
+`facts`, an optional `note`, and an optional `idempotencyKey`. The server commits
+the packet atomically, maps common category aliases into the canonical taxonomy,
+and skips exact source-aware duplicates. `deal fact add` remains the simple path
+for one fact.
+
 Facts use `claim` for the fact text. `source` is a readable provenance label
 and `sourceUrl` is the canonical evidence URL; both round-trip from the API.
 For deal owners, use an exact `/api/field-options` `dealOwner` value, a user
@@ -129,12 +138,11 @@ reference (100+ commands). Deletes are soft and audit-logged everywhere.
 | `Error[UNAUTHORIZED]` | Server rejected the credentials | Token revoked / expired / wrong account |
 
 The MCP server returns the same prefixes inside `isError: true` content.
-Authenticated calls send bounded, content-redacted telemetry to Command;
-`llama eval good|bad --last` turns real searches into eval feedback.
+Authenticated calls send bounded, content-redacted telemetry to Command.
 
 ## MCP server
 
-`llama-mcp` is a stdio Model Context Protocol server exposing 59 typed tools
+`llama-mcp` is a stdio Model Context Protocol server exposing 55 typed tools
 that mirror the most-used CLI surface. Every tool is named and scoped — there
 is deliberately no generic API passthrough. Auth is identical to the CLI's
 chain. For the exact live list, pipe `tools/list` through it:

package/README.zh-CN.md

@@ -7,7 +7,7 @@
 <p align="center">
   <strong>Llama Ventures 的 CLI 与 MCP server。</strong><br/>
   一个包、两个可执行文件：<code>llama</code>——给人和脚本用的 CLI；
-  <code>llama-mcp</code>——带 59 个类型化工具的 stdio MCP server，任何
+  <code>llama-mcp</code>——带 55 个类型化工具的 stdio MCP server，任何
   MCP 原生 agent 都能接。两者共享同一认证链、同一 HTTP 客户端、同一错误格式，
   连接 <a href="https://command.llamaventures.vc">command.llamaventures.vc</a>。
 </p>
@@ -120,9 +120,11 @@ llama deal feed <dealId>               # 该 deal 的全部贡献，最新在前
 llama activity new-deals --since 24h   # 最近新建的 deal
 llama activity updated-deals --since 7d # 按 deal 聚合的实质更新
 llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
+llama deal ingest <dealId> --file packet.json  # 多条 facts + 可选 Feed note，一次提交且可安全重试
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "备注内容"
+llama post <dealId> "@name 请回复" --cue  # 仅在用户明确授权后使用
 llama brief add-text <dealId> --heading "..." --body "..."
 llama wiki search "<查询词>"
 llama wiki save <slug> --title "..." --content "..."
@@ -134,6 +136,11 @@ Status 语义——`Interested`：接触前先记录关注 · `Outreached`：已
 尚无回应 · `Sourced`：已有真实关系信号。`sourceDirection` 是独立维度：
 `Inbound` 流入，`Outbound` 我们主动。
 
+处理 deck、会议笔记、邮件或研究材料时，优先使用 `deal ingest`，不要循环调用
+`deal fact add`。JSON 对象支持 `source`、最多 50 条 `facts`、可选 `note` 和可选
+`idempotencyKey`。服务端会原子提交整个材料包、把常见 category 别名归一到固定分类，
+并跳过来源一致的精确重复。只有真正的单条事实才用 `deal fact add`。
+
 Facts 的正文用 `claim`。`source` 是人可读来源标签，`sourceUrl` 是 canonical
 证据 URL；两者都会从 API 回显。`dealOwner` 请用 `/api/field-options`
 里的精确 `dealOwner` 值、用户邮箱，或数字 user id。
@@ -153,7 +160,7 @@ MCP server 在 `isError: true` 内容里返回相同前缀。认证请求会向
 
 ## MCP server
 
-`llama-mcp` 是 stdio MCP server，59 个类型化工具镜像 CLI 最常用的命令面。
+`llama-mcp` 是 stdio MCP server，55 个类型化工具镜像 CLI 最常用的命令面。
 每个工具具名、有边界——**故意不提供**通用 API passthrough。认证链与 CLI
 完全一致。精确工具清单以 `tools/list` 为准：
 

package/bin/llama-mcp.mjs

@@ -15,7 +15,6 @@ import { z } from "zod";
 import {
   getAuthHeaders,
   getBaseUrl,
-  getLastAgentEvent,
   readBriefing,
   request,
   requestSse,
@@ -84,20 +83,6 @@ function splitSources(value) {
     .filter(Boolean);
 }
 
-function expectedIds(value) {
-  const expected = { dealIds: [], wikiSlugs: [], raw: [] };
-  if (!value) return expected;
-  const items = Array.isArray(value) ? value : String(value).split(",");
-  for (const item of items.map((s) => String(s).trim()).filter(Boolean)) {
-    const [kind, ...rest] = item.split(":");
-    const id = rest.join(":").trim();
-    if (kind === "deal" && id) expected.dealIds.push(id);
-    else if ((kind === "wiki" || kind === "slug") && id) expected.wikiSlugs.push(id);
-    else expected.raw.push(item);
-  }
-  return expected;
-}
-
 function buildEnrichmentAgentMessage(args = {}) {
   if (args.message) return String(args.message);
   const sources = splitSources(args.sources) ?? [
@@ -176,7 +161,7 @@ async function runDealAgentTool({ dealId, message, title = "MCP agent run" }) {
 // full-array PUTs (no POST), so we GET current blocks, prepend the new
 // one (matches UI default since 2026-05-03), and PUT the merged array.
 // Server stamps identity meta on PUT; we don't send any.
-async function addBriefBlock(dealId, block) {
+async function addBriefBlock(dealId, block, cueAuthorized = false) {
   try {
     const id = globalThis.crypto.randomUUID();
     const cur = await request("GET", `/api/deals/${encodeURIComponent(dealId)}/blocks`);
@@ -184,7 +169,7 @@ async function addBriefBlock(dealId, block) {
     const result = await request(
       "PUT",
       `/api/deals/${encodeURIComponent(dealId)}/blocks`,
-      { blocks: [{ id, ...block }, ...existing] }
+      { blocks: [{ id, ...block }, ...existing], cue_authorized: cueAuthorized === true }
     );
     const text = JSON.stringify(
       { ok: result?.ok ?? true, id, count: result?.count ?? existing.length + 1 },
@@ -257,41 +242,6 @@ server.registerTool(
   }
 );
 
-server.registerTool(
-  "record_eval_feedback",
-  {
-    description:
-      "Mark the latest llama CLI/MCP result as good/bad or add a real query " +
-      "to the Golden Query Eval candidate pool. Use when the user says a " +
-      "Llama Command search/result was right, wrong, missing a source, or should be regression-tested.",
-    inputSchema: {
-      action: z.enum(["good", "bad", "add"]).describe("feedback action"),
-      eventId: z.number().optional().describe("agent_client_events id; defaults to latest local event"),
-      query: z.string().optional().describe("required for manual add when no source event is available"),
-      surface: z.string().optional().describe("deal, wiki, activity, people, or manual"),
-      expect: z
-        .union([z.string(), z.array(z.string())])
-        .optional()
-        .describe("expected ids like wiki:llamaos-weekly-2026-06-17 or deal:<uuid>"),
-      reason: z.string().optional().describe("why this was good/bad or should be tracked"),
-      privacyLevel: z.string().optional().describe("default internal"),
-    },
-  },
-  async ({ action, eventId, query, surface, expect, reason, privacyLevel }) => {
-    const last = getLastAgentEvent();
-    const body = {
-      action,
-      eventId: eventId ?? last?.lastEventId,
-      query,
-      surface: surface ?? last?.lastSurface,
-      expected: expectedIds(expect),
-      reason,
-      privacyLevel: privacyLevel ?? "internal",
-    };
-    return callApi("POST", "/api/agent/eval-feedback", body);
-  }
-);
-
 server.registerTool(
   "skills_search",
   {
@@ -311,6 +261,60 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "pref_list",
+  {
+    description:
+      "List standing agent preferences (team scope + the caller's user scope). " +
+      "These are injected into every server-side agent turn. Use status=proposed " +
+      "to review pending proposals awaiting approval.",
+    inputSchema: {
+      status: z.enum(["active", "proposed", "retired", "all"]).optional()
+        .describe("filter; defaults to active"),
+    },
+  },
+  async ({ status }) => {
+    const params = new URLSearchParams();
+    if (status) params.set("status", status);
+    return callApi("GET", `/api/agent/preferences${params.toString() ? `?${params}` : ""}`);
+  }
+);
+
+server.registerTool(
+  "pref_add",
+  {
+    description:
+      "Save a standing preference so every Llama agent follows it from the next " +
+      "turn on. Use when the user states a durable way they want agents to work " +
+      "(style, workflow, defaults). Content is hard-capped at 280 chars — if it " +
+      "does not fit, it is a procedure and belongs in a skill. Team scope needs " +
+      "system-admin approval; own user scope activates immediately.",
+    inputSchema: {
+      key: z.string().describe("short slug, e.g. reply-style.conclusion-first"),
+      content: z.string().describe("the preference, max 280 chars"),
+      scope: z.enum(["user", "team"]).optional().describe("default user (the caller)"),
+      evidence: z.string().optional().describe("what prompted this (run, correction)"),
+    },
+  },
+  async ({ key, content, scope, evidence }) =>
+    callApi("POST", "/api/agent/preferences", { key, content, scope, evidence })
+);
+
+server.registerTool(
+  "pref_set_status",
+  {
+    description:
+      "Approve (activate) or retire a standing preference by id. Own user scope " +
+      "is self-service; team scope requires a system admin.",
+    inputSchema: {
+      id: z.number().describe("preference id from pref_list"),
+      status: z.enum(["active", "retired"]).describe("new status"),
+    },
+  },
+  async ({ id, status }) =>
+    callApi("PATCH", `/api/agent/preferences/${encodeURIComponent(String(id))}`, { status })
+);
+
 server.registerTool(
   "skills_read",
   {
@@ -509,6 +513,50 @@ server.registerTool(
 // Deal facts (research substrate + trust ladder)
 // ============================================================
 
+server.registerTool(
+  "deal_ingest",
+  {
+    description:
+      "Preferred write tool when one source yields multiple facts, or facts plus a Feed note. " +
+      "Commits the packet atomically, canonicalizes fact categories, skips exact source-aware " +
+      "duplicates, and is safe to retry with the same idempotencyKey. Use deal_fact_add only " +
+      "for a genuinely single fact. Canonical categories: company_basics, team, product, market, " +
+      "financials, fundraise, risk, milestone, meta.",
+    inputSchema: {
+      dealId: z.string(),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe("Stable key for retries. If omitted, the server derives one from packet content."),
+      source: z
+        .object({
+          kind: z.enum(["deck", "web", "meeting_note", "email", "human", "agent_inference"]).optional(),
+          title: z.string().optional(),
+          url: z.string().optional(),
+          contentHash: z.string().optional(),
+        })
+        .optional(),
+      facts: z
+        .array(z.object({
+          category: z.string(),
+          claim: z.string(),
+          source: z.string().optional(),
+          sourceUrl: z.string().optional(),
+          sourceKind: z.enum(["deck", "web", "meeting_note", "email", "human", "agent_inference"]).optional(),
+          confidence: z.enum(["high", "medium", "low"]).optional(),
+          attested: z.boolean().optional(),
+        }))
+        .max(50)
+        .optional(),
+      note: z.string().optional().describe("Opinion, impression, or context to add to the deal Feed."),
+    },
+  },
+  async ({ dealId, ...packet }) => {
+    // @core-api-operation POST /api/deals/{dealId}/ingest
+    return callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/ingest`, packet);
+  }
+);
+
 server.registerTool(
   "deal_fact_list",
   {
@@ -613,7 +661,7 @@ server.registerTool(
       "accountable person, null only for principal-less system writes) and `agent` " +
       "(the assistant/system label when an AI did the writing, null when a human " +
       "typed it) so you can tell human-typed from assistant-drafted. The AI's " +
-      "regenerable brief/persona synthesis is NOT here (that's the Memo) — only " +
+      "regenerable brief synthesis is NOT here (that's the Memo) — only " +
       "facts + discussion notes. Each item: kind (fact|note), ts, who, agent, " +
       "origin, text, and for facts: source + trust rung + category.",
     inputSchema: {
@@ -633,10 +681,13 @@ server.registerTool(
       dealId: z.string(),
       heading: z.string().optional().describe("optional block heading"),
       body: z.string().describe("markdown body"),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, heading, body }) =>
-    addBriefBlock(dealId, { type: "text", heading: heading ?? "", body })
+  async ({ dealId, heading, body, cueAuthorized }) =>
+    addBriefBlock(dealId, { type: "text", heading: heading ?? "", body }, cueAuthorized)
 );
 
 server.registerTool(
@@ -648,10 +699,13 @@ server.registerTool(
       dealId: z.string(),
       url: z.string(),
       label: z.string().optional().describe("optional human-readable label"),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, url, label }) =>
-    addBriefBlock(dealId, { type: "link", url, label: label ?? "" })
+  async ({ dealId, url, label, cueAuthorized }) =>
+    addBriefBlock(dealId, { type: "link", url, label: label ?? "" }, cueAuthorized)
 );
 
 server.registerTool(
@@ -664,10 +718,13 @@ server.registerTool(
       tone: z.string().describe("insight | warning | info | success"),
       heading: z.string().optional(),
       body: z.string(),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, tone, heading, body }) =>
-    addBriefBlock(dealId, { type: "callout", tone, heading: heading ?? "", body })
+  async ({ dealId, tone, heading, body, cueAuthorized }) =>
+    addBriefBlock(dealId, { type: "callout", tone, heading: heading ?? "", body }, cueAuthorized)
 );
 
 server.registerTool(
@@ -690,9 +747,12 @@ server.registerTool(
       locked: z.boolean().optional(),
       hidden: z.boolean().optional(),
       sourceSection: z.string().optional(),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, blockId, heading, body, url, label, description, tone, locked, hidden, sourceSection }) => {
+  async ({ dealId, blockId, heading, body, url, label, description, tone, locked, hidden, sourceSection, cueAuthorized }) => {
     const patch = {};
     for (const [k, v] of Object.entries({ heading, body, url, label, description, tone })) {
       if (v !== undefined) patch[k] = v;
@@ -702,6 +762,7 @@ server.registerTool(
     if (hidden !== undefined) meta.hidden = hidden;
     if (sourceSection !== undefined) meta.sourceSection = sourceSection;
     if (Object.keys(meta).length > 0) patch.meta = meta;
+    if (cueAuthorized === true) patch.cue_authorized = true;
     return callApi(
       "PATCH",
       `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}`,
@@ -940,16 +1001,22 @@ server.registerTool(
   "post",
   {
     description:
-      "Post a message to a deal's timeline. Message can include @-mentions " +
-      "(e.g. @<first-name> or @<email@llamaventures.vc>) — the system fires " +
-      "email + inbox notifications to mentioned users.",
+      "Post a message to a deal's timeline. Cue-free posts are autonomous. " +
+      "Explicit or implicit teammate cues create inbox/email notifications and require " +
+      "cueAuthorized=true only after explicit user permission.",
     inputSchema: {
       dealId: z.string(),
       message: z.string(),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved cueing every resolved recipient",
+      ),
     },
   },
-  async ({ dealId, message }) =>
-    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/posts`, { message })
+  async ({ dealId, message, cueAuthorized }) =>
+    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/posts`, {
+      message,
+      cue_authorized: cueAuthorized === true,
+    })
 );
 
 // ============================================================
@@ -993,63 +1060,7 @@ server.registerTool(
 );
 
 // ============================================================
-// Skill corrections (persona-owner pushback workflow)
-// ============================================================
-
-server.registerTool(
-  "skill_correction_list",
-  {
-    description:
-      "List the recorded corrections (long-term rules) for a persona/skill. These shape how " +
-      "that persona's analysis is generated.",
-    inputSchema: {
-      skillSlug: z.string(),
-      includeDeleted: z.boolean().optional(),
-    },
-  },
-  async ({ skillSlug, includeDeleted }) => {
-    const params = new URLSearchParams({ skill: skillSlug });
-    if (includeDeleted) params.set("include_deleted", "1");
-    return callApi("GET", `/api/skill-corrections?${params}`);
-  }
-);
-
-server.registerTool(
-  "skill_correction_add",
-  {
-    description:
-      "Record a long-term correction rule for a persona/skill (e.g. 'always check burn multiple " +
-      "before commenting on efficiency'). ALWAYS reconfirm the distilled rule with the user before " +
-      "calling — this changes how the persona behaves going forward. Optionally tie it to the deal/" +
-      "block where it came up.",
-    inputSchema: {
-      skillSlug: z.string(),
-      correctionText: z.string(),
-      dealUuid: z.string().optional(),
-      blockId: z.string().optional(),
-    },
-  },
-  async ({ skillSlug, correctionText, dealUuid, blockId }) =>
-    callApi("POST", "/api/skill-corrections", {
-      skill_slug: skillSlug,
-      correction_text: correctionText,
-      triggered_in_deal_uuid: dealUuid ?? null,
-      triggered_in_block_id: blockId ?? null,
-    })
-);
-
-server.registerTool(
-  "skill_correction_delete",
-  {
-    description: "Soft-delete a recorded skill correction by id.",
-    inputSchema: { id: z.union([z.string(), z.number()]) },
-  },
-  async ({ id }) =>
-    callApi("DELETE", `/api/skill-corrections/${encodeURIComponent(String(id))}`)
-);
-
-// ============================================================
-// Brief / persona refresh (signal-driven re-evaluation)
+// Brief refresh (signal-driven re-evaluation)
 // ============================================================
 
 server.registerTool(
@@ -1070,22 +1081,6 @@ server.registerTool(
     )
 );
 
-server.registerTool(
-  "deal_refresh_persona",
-  {
-    description:
-      "Regenerate one persona's analysis section for a deal. persona = a server-configured " +
-      "persona key (unknown keys are rejected; discover the roster via agent_bootstrap). " +
-      "Returns a runId (or null if debounced).",
-    inputSchema: {
-      dealId: z.string(),
-      persona: z.string(),
-    },
-  },
-  async ({ dealId, persona }) =>
-    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/refresh-persona`, { persona })
-);
-
 server.registerTool(
   "deal_agent_run",
   {