@llamaventures/cli 1.17.1 → 1.17.2

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.
+- **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.
 

package/CHANGELOG.md

@@ -6,6 +6,21 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.17.2] - 2026-07-01
+
+### Changed
+- README (en + zh): new "Integrate your AI system" section — the recommended
+  path for wiring external agents/LLM apps through the CLI/MCP layer instead
+  of the raw HTTP API; corrected tool count (58) and command count (100+);
+  de-duplicated the CLI tour examples; removed an obsolete migration note;
+  the zh auth section now documents `llama auth login` (OAuth) as the
+  recommended method, matching en.
+- MCP tool descriptions now defer server-configured option lists to runtime
+  discovery via `agent_bootstrap` instead of hardcoding them in tool text.
+- Agent briefing: added a public-surfaces hygiene rule from the server-owned
+  contract.
+- CI/publish pipeline: additional automated release-gate checks.
+
 ## [1.17.1] - 2026-06-29
 
 ### Changed

package/README.md

@@ -27,6 +27,7 @@
 <p align="center">
   <a href="#install">Install</a> ·
   <a href="#authenticate">Authenticate</a> ·
+  <a href="#integrate-your-ai-system">Integrate your AI</a> ·
   <a href="#cli-tour">CLI</a> ·
   <a href="#mcp-server">MCP</a> ·
   <a href="#external-pitch-no-llama-account-required">External pitch</a> ·
@@ -48,7 +49,7 @@
 ```
 @llamaventures/cli
 ├── bin/llama          interactive CLI for humans + bash
-└── bin/llama-mcp      stdio MCP server, 56 typed tools — for any MCP-native agent
+└── bin/llama-mcp      stdio MCP server, 58 typed tools — for any MCP-native agent
 ```
 
 Both binaries share `lib/client.mjs` — the **same** auth chain, **same** HTTP
@@ -89,12 +90,6 @@ llama auth status     # round-trips against /api/me
 
 The same install puts `llama-mcp` on your `PATH` for the MCP server — no second package.
 
-> **Upgrading from `npm link`?** The CLI used to live in the `llama-os/cli/`
-> directory and was distributed via `npm link`. As of CLI v1.x it ships as
-> `@llamaventures/cli`. Run `npm i -g @llamaventures/cli@latest`; the legacy
-> directory keeps working during the soak window but is no longer the source
-> of truth. See [`llama-os/cli/DEPRECATED.md`](https://github.com/SoujiOkita98/llama-os/blob/main/cli/DEPRECATED.md).
-
 ---
 
 ## Authenticate
@@ -166,6 +161,39 @@ llama deal search acme-ai  # ready
 
 ---
 
+## Integrate your AI system
+
+This package is the **supported integration surface** for Llama Command. If
+you're wiring an in-house agent, a coding assistant, or any LLM app into the
+workbench, come through here — **not the raw HTTP API**. The CLI/MCP layer owns
+the auth chain, the stable `Error[…]` contract, and forward-compatibility
+across server schema changes ([SemVer](#stability)); raw API routes carry no
+such promise and can change without notice.
+
+The five-minute path:
+
+1. **Get credentials** — a team account signs in with `llama auth login`; for
+   headless systems, have the admin mint a PAT at
+   [`/settings/tokens`](https://command.llamaventures.vc/settings/tokens) and
+   set it via `llama token set` or `$LLAMA_TOKEN`.
+2. **Install** — `npm i -g @llamaventures/cli` (Node 18+).
+3. **Wire it in:**
+   - **MCP-native agent** (Claude, Cursor, any stdio client) → point it at
+     `llama-mcp`: 58 typed tools, no generic passthrough.
+     See [MCP server](#mcp-server) for per-client config.
+   - **Anything else** → shell out to `llama …`. Output is agent-friendly
+     plain text; failures use the stable
+     [`Error[…]` prefixes](#error-codes--for-agents).
+4. **Onboard the agent** — have it run `llama agent-onboard` (or fetch the MCP
+   `agent_briefing` prompt) at session start. It returns the **server-owned
+   Agent Runtime Contract** — current workflow rules, attribution grammar,
+   error recovery — always in sync with the live server, so this README never
+   becomes your integration bottleneck.
+5. **Verify** — `llama auth status` round-trips the resolved identity;
+   `llama deal search "<anything>"` proves read access.
+
+---
+
 ## CLI tour
 
 The CLI is the canonical interface. The HTTP API beneath it is stable, but the
@@ -180,16 +208,12 @@ llama token show
 
 # Pipeline — read
 llama deal search "acme ai"
-llama deal list --owner alex --status Interested
-llama deal list --owner alex --status Outreached
-llama deal list --source-direction Outbound --status Outreached
-llama deal list --owner alex --status Diligence
+llama deal list --owner alex --status Diligence      # same filters as search
 llama deal show <dealId>
+llama deal feed <dealId>                             # every contribution, newest first
 
 # Pipeline — write
-llama deal create "Acme AI" --description "..." --source Gavin --source-direction Outbound --status Interested
-llama deal create "Acme AI" --description "..." --source Gavin --source-direction Outbound --status Outreached
-llama deal create "Acme AI" --description "..." --source Gavin --source-direction Inbound --status Sourced
+llama deal create "Acme AI" --description "..." --source alex --source-direction Outbound --status Interested
 llama deal update <dealId> status Diligence
 llama deal enrich <dealId> --dry-run
 llama deal enrich <dealId> --apply --executor server_agent
@@ -248,10 +272,11 @@ llama mentions
 llama mentions resolve <mentionId>
 ```
 
-Run `llama --help` for the full surface (50+ commands across deals, briefs,
-ownership, timeline, facts, wiki, mentions, skill corrections, and admin event
-feeds). Soft-delete is the default everywhere — every removal is reversible
-and audit-logged via `deal_events`.
+Run `llama --help` for the group index, or `llama help all` for the full
+reference — 100+ commands across deals, briefs, facts, ownership, timeline,
+wiki, memos, deal-scoped HTML artifacts, mentions, skill corrections, evals,
+and admin event feeds. Soft-delete is the default everywhere — every removal
+is reversible and audit-logged via `deal_events`.
 
 ### Error codes — for agents
 
@@ -419,9 +444,9 @@ intake agent extracts the structured fields and produces the verdict.
   the `Error[…]` prefixes are part of the public contract and won't change
   inside a major version.
 - **Server schema drift:** When the API gains an endpoint, the CLI / MCP gain
-  a typed wrapper in the next minor release. While you wait, the `llama` CLI
-  itself ships the full `llama` command surface (40+ commands) — use it for
-  ad-hoc HTTP work that the MCP doesn't yet wrap.
+  a typed wrapper in the next minor release. There is deliberately no raw-API
+  passthrough — if a wrapper you need hasn't landed yet, open an issue rather
+  than calling the HTTP API directly.
 
 See [`CHANGELOG.md`](CHANGELOG.md) for the per-version log.
 

package/README.zh-CN.md

@@ -26,6 +26,7 @@
 
 <p align="center">
   <a href="#给华人创业者-向-llama-pitch">🚀 向 Llama pitch（无需账号）</a> ·
+  <a href="#接入你的-ai-系统">接入你的 AI</a> ·
   <a href="#安装">安装</a> ·
   <a href="#认证">认证</a> ·
   <a href="#cli-速览">CLI</a> ·
@@ -48,7 +49,7 @@
 ```
 @llamaventures/cli
 ├── bin/llama          给人 + bash 用的交互式 CLI
-└── bin/llama-mcp      给 MCP 原生 agent 用的 stdio MCP server，56 个工具
+└── bin/llama-mcp      给 MCP 原生 agent 用的 stdio MCP server，58 个类型化工具
 ```
 
 两个 binary 共享 `lib/client.mjs`——**同一**认证链、**同一** HTTP 客户端、
@@ -133,12 +134,6 @@ llama auth status     # 会跑一次 /api/me 验证
 
 同一次安装会把 `llama-mcp` 也放到 `PATH` 上——MCP server 不用单独装包。
 
-> **从 `npm link` 升级过来？** CLI 以前住在 `llama-os/cli/` 目录，靠 `npm link`
-> 分发。从 v1.x 起改名 `@llamaventures/cli` 走 npm。
-> 跑一次 `npm i -g @llamaventures/cli@latest` 就完事；旧目录在 soak 期间
-> 还能用，但已经不是 source of truth。详见
-> [`llama-os/cli/DEPRECATED.md`](https://github.com/SoujiOkita98/llama-os/blob/main/cli/DEPRECATED.md)。
-
 ---
 
 ## 认证
@@ -147,16 +142,29 @@ llama auth status     # 会跑一次 /api/me 验证
 
 | # | 来源 | 发送的 header | 适合谁 |
 |---|------|--------------|--------|
-| 1 | `gcloud auth print-identity-token` | `Authorization: Bearer …` | Llama 团队成员（零配置） |
-| 2 | `$LLAMA_TOKEN` 环境变量 | `X-Llama-Token` | CI runner、云上 sandbox agent |
-| 3 | `~/.llama/token`（mode `0600`） | `X-Llama-Token` | 本地常驻安装 |
-| 4 | `~/.llama-command/config.json` | `X-Llama-Token` | CLI v0.1 老路径——首次读取自动迁移到 `~/.llama/token` |
+| 1 | `llama auth login`（OAuth 2.1，存 OS Keychain） | `Authorization: Bearer …` | **所有人的推荐方式。** 浏览器一次登录，token 自动刷新、重启不丢 |
+| 2 | `gcloud auth print-identity-token` | `Authorization: Bearer …` | 已经配好 gcloud 的工作机（零配置） |
+| 3 | `$LLAMA_TOKEN` 环境变量 | `X-Llama-Token` | CI runner、云上 sandbox agent |
+| 4 | `~/.llama/token`（mode `0600`） | `X-Llama-Token` | 本地常驻安装（长期 PAT） |
+| 5 | `~/.llama-command/config.json` | `X-Llama-Token` | CLI v0.1 老路径——首次读取自动迁移到 `~/.llama/token` |
 
 如果 Bearer 和 X-Llama-Token 同时存在，两个一起发。服务器先验 Bearer，
 失败后回退到 X-Llama-Token。任何时候都可以用 `llama auth status`
 看当前认证身份。
 
-### 零配置 —— 团队成员推荐
+### 浏览器登录 —— 推荐
+
+```bash
+llama auth login           # 打开浏览器 → Google 登录 → 授权 → 完成
+llama auth status          # → activeMethod=oauth，显示身份与 scope
+llama deal search acme-ai  # 直接用
+```
+
+OAuth 2.1 PKCE 流程，token 存 OS Keychain（macOS Keychain / Windows
+Credential Manager / Linux Secret Service），自动刷新。
+`llama auth logout` 会在服务端吊销并清空本地存储。
+
+### gcloud —— 已配好 gcloud 的机器
 
 ```bash
 gcloud auth login          # 一次性，选你的 @llamaventures.vc 账号
@@ -188,6 +196,34 @@ llama deal search acme-ai  # 直接用
 
 ---
 
+## 接入你的 AI 系统
+
+这个包是 Llama Command 的**官方集成面**。要把自研 agent、编程助手或任何
+LLM 应用接进工作台，请从这里走——**不要直接调 HTTP API**。CLI/MCP 层
+负责认证链、稳定的 `Error[…]` 错误契约、以及服务端 schema 变化时的
+前向兼容（[SemVer](#稳定性)）；裸 API 路由没有这些承诺，随时可能变。
+
+五分钟接入路径：
+
+1. **拿凭证** —— 团队账号直接 `llama auth login`；无人值守系统请管理员在
+   [`/settings/tokens`](https://command.llamaventures.vc/settings/tokens)
+   mint 一个 PAT，再用 `llama token set` 或 `$LLAMA_TOKEN` 配置。
+2. **安装** —— `npm i -g @llamaventures/cli`（Node 18+）。
+3. **接线：**
+   - **MCP 原生 agent**（Claude、Cursor、任何 stdio 客户端）→ 指向
+     `llama-mcp`：58 个类型化工具，无通用 passthrough。
+     各客户端配置见 [MCP server](#mcp-server)。
+   - **其它形态** → 子进程调用 `llama …`。输出是 agent 友好的纯文本；
+     失败带稳定的 `Error[…]` 前缀。
+4. **让 agent 自我入职** —— 会话开始时跑一次 `llama agent-onboard`
+   （或取 MCP 的 `agent_briefing` prompt），拿到**服务端下发的 Agent
+   Runtime Contract**——最新的工作流规则、署名规范、错误恢复——
+   与线上服务器永远同步，README 永远不会成为集成瓶颈。
+5. **验证** —— `llama auth status` 回环确认身份；
+   `llama deal search "<随便什么>"` 证明读权限通了。
+
+---
+
 ## CLI 速览
 
 CLI 是 canonical 接口。底下的 HTTP API 也稳定，但 CLI 帮你处理了认证、错误格式、
@@ -201,16 +237,12 @@ llama token show
 
 # Pipeline——读
 llama deal search "acme ai"
-llama deal list --owner alex --status Interested
-llama deal list --owner alex --status Outreached
-llama deal list --source-direction Outbound --status Outreached
-llama deal list --owner alex --status Diligence
+llama deal list --owner alex --status Diligence      # 与 search 同一套过滤参数
 llama deal show <dealId>
+llama deal feed <dealId>                             # 该 deal 的全部贡献，最新在前
 
 # Pipeline——写
-llama deal create "Acme AI" --description "..." --source Gavin --source-direction Outbound --status Interested
-llama deal create "Acme AI" --description "..." --source Gavin --source-direction Outbound --status Outreached
-llama deal create "Acme AI" --description "..." --source Gavin --source-direction Inbound --status Sourced
+llama deal create "Acme AI" --description "..." --source alex --source-direction Outbound --status Interested
 llama deal update <dealId> status Diligence
 llama deal enrich <dealId> --dry-run
 llama deal enrich <dealId> --apply --executor server_agent
@@ -260,8 +292,9 @@ llama mentions
 llama mentions resolve <mentionId>
 ```
 
-跑 `llama --help` 看完整命令清单（50+ 个命令，覆盖 deals、briefs、ownership、
-timeline、facts、wiki、mentions、skill corrections、admin event feeds）。
+跑 `llama --help` 看分组索引，`llama help all` 看完整命令参考——100+ 个命令,
+覆盖 deals、briefs、facts、ownership、timeline、wiki、memo、deal 级 HTML
+artifacts、mentions、skill corrections、evals、admin event feeds。
 所有删除默认软删除——可恢复，且通过 `deal_events` 留下审计痕迹。
 
 ### 错误码（给 agent 用）
@@ -375,8 +408,8 @@ claude mcp add llama -- llama-mcp
 - **向后兼容：** wire format（Bearer / X-Llama-Token）和 `Error[…]` 前缀
   是公开契约，major 版本内不会变。
 - **服务端 schema 漂移：** 当 API 多了一个端点，下一个 minor 版本会带
-  typed wrapper。在那之前，可以用 `llama` CLI 本身——它自带 40+ 命令
-  覆盖整个 API 表面，足够顶住 MCP 还没包到的端点。
+  typed wrapper。这个包**故意不提供**裸 API passthrough——如果你需要的
+  wrapper 还没落地，开 issue，不要直接调 HTTP API。
 
 详见 [`CHANGELOG.md`](CHANGELOG.md)。
 

package/bin/llama-mcp.mjs

@@ -1032,8 +1032,9 @@ server.registerTool(
   "deal_refresh_persona",
   {
     description:
-      "Regenerate one persona's analysis section for a deal. persona ∈ gavin | kyle | jack | " +
-      "david | bryan | herman | hongjiang | liuyi | kevin. Returns a runId (or null if debounced).",
+      "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(),

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.17.1",
+  "version": "1.17.2",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
     "test": "npm run test:agent-routing",
     "test:agent-routing": "node scripts/verify-agent-routing.mjs",
-    "verify:release": "npm test && npm pack --dry-run"
+    "verify:release": "npm test && node scripts/verify-tarball-clean.mjs && npm pack --dry-run"
   },
   "bin": {
     "llama": "bin/llama.mjs",

package/scripts/verify-agent-routing.mjs

@@ -14,8 +14,8 @@ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."
 const packageJson = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8"));
 assert.equal(
   packageJson.scripts?.["verify:release"],
-  "npm test && npm pack --dry-run",
-  "CLI release gate must run agent routing tests and npm pack dry-run",
+  "npm test && node scripts/verify-tarball-clean.mjs && npm pack --dry-run",
+  "CLI release gate must run agent routing tests, the publish-surface hygiene scan, and npm pack dry-run",
 );
 assert.equal(
   existsSync(path.join(repoRoot, "docs/agent-skills.bundle.json")),
@@ -201,13 +201,13 @@ const server = createServer(async (req, res) => {
             objectId: "missing-page",
             status: "deleted",
             title: "Missing Page",
-            detail: "Deleted by Kevin Yu",
+            detail: "Deleted by Alex Chen",
             url: "https://command.llamaventures.vc/wiki/missing-page",
           },
           lifecycle: [
             {
               action: "deleted",
-              actor_label: "Kevin Yu",
+              actor_label: "Alex Chen",
               created_at: "2026-06-15T19:02:00Z",
               reason: "user_deleted",
             },
@@ -543,7 +543,7 @@ try {
   resetCalls();
   const explainRun = await runCli(["explain", "https://command.llamaventures.vc/wiki/missing-page"], baseUrl, homeDir);
   assert.match(explainRun.stdout, /Status: deleted/);
-  assert.match(explainRun.stdout, /Deleted by Kevin Yu/);
+  assert.match(explainRun.stdout, /Deleted by Alex Chen/);
   assert.deepEqual(paths(), ["GET /api/agent/explain"]);
   assert.equal(businessCalls()[0].query.q, "https://command.llamaventures.vc/wiki/missing-page");