@llamaventures/cli 1.2.2 → 1.2.3

package/AGENT_BRIEFING.md

@@ -116,11 +116,11 @@ llama post <dealId> "message"
 llama mentions
 ```
 
-Run `llama --help` for the full 39-command surface.
+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` (15 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` (20 typed tools, identical auth chain).
 
 Add to your MCP client config (Claude Desktop / Claude Code / Cursor / OpenClaw / Codex / etc.):
 
@@ -136,6 +136,7 @@ Tools available:
 - `wiki_search` / `wiki_save`
 - `timeline` / `post`
 - `mentions_list`
+- `pitch_start` / `pitch_send_message` / `pitch_upload_file` / `pitch_status` / `pitch_finalize` — public intake (no Llama token needed; for founders / EAs / external agents)
 - `llama_api` — escape hatch for any endpoint not yet wrapped (path must start `/api/`)
 
 You can also fetch this exact briefing as an MCP prompt named `agent_briefing`.

package/README.md

@@ -1,273 +1,386 @@
-# @llamaventures/cli
+<p align="center">
+  <img src="assets/llama-ventures-logo.svg" alt="Llama Ventures" width="280">
+</p>
+
+<h1 align="center">@llamaventures/cli</h1>
+
+<p align="center">
+  <strong>The Llama Ventures CLI &amp; MCP server.</strong><br/>
+  One <code>npm install</code>, one auth chain, two interfaces — humans and AI agents
+  talk to <a href="https://command.llamaventures.vc">command.llamaventures.vc</a>
+  through the same client.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@llamaventures/cli"><img alt="npm" src="https://img.shields.io/npm/v/@llamaventures/cli?label=npm&color=cb3837&logo=npm&logoColor=white"></a>
+  <a href="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://docs.npmjs.com/trusted-publishers"><img alt="Provenance" src="https://img.shields.io/badge/provenance-signed-2e8b57?logo=npm"></a>
+  <a href="https://nodejs.org/"><img alt="Node" src="https://img.shields.io/node/v/@llamaventures/cli?color=339933&logo=nodedotjs&logoColor=white"></a>
+  <a href="https://modelcontextprotocol.io"><img alt="MCP 2024-11-05" src="https://img.shields.io/badge/MCP-2024--11--05-7d3aed"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+</p>
+
+<p align="center">
+  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#authenticate">Authenticate</a> ·
+  <a href="#cli-tour">CLI</a> ·
+  <a href="#mcp-server">MCP</a> ·
+  <a href="#external-pitch-no-llama-account-required">External pitch</a> ·
+  <a href="AGENT_BRIEFING.md">Agent briefing</a> ·
+  <a href="SECURITY.md">Security</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+> **Public source for low-friction install. Not an open-source product.**
+> Most operations require a Llama Ventures team account
+> ([gavin@llamaventures.vc](mailto:gavin@llamaventures.vc) mints tokens). The one
+> exception is the **public `pitch`** family — see
+> [External pitch](#external-pitch-no-llama-account-required).
+
+---
+
+## What's in the box
 
-Llama Ventures team CLI + MCP server for
-[command.llamaventures.vc](https://command.llamaventures.vc).
-
-> Public source for low-friction install. **Not an open-source product** —
-> requires a Llama Ventures team account to do anything useful. See
-> [Authenticate](#authenticate).
+```
+@llamaventures/cli
+├── bin/llama          interactive CLI for humans + bash
+└── bin/llama-mcp      stdio MCP server, 20 tools — for any MCP-native agent
+```
 
-[![CI](https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml)
+Both binaries share `lib/client.mjs` — the **same** auth chain, **same** HTTP
+client, **same** error format. CLI and MCP can never drift on transport or
+identity. Zero runtime dependencies for the CLI itself; the bundled MCP
+server depends only on `@modelcontextprotocol/sdk` (Anthropic-maintained,
+pinned exact).
+
+```mermaid
+flowchart LR
+  Human([🧑‍💻 Human])           --> CLI[bin/llama<br/>argv parser]
+  Agent([🤖 MCP-native agent]) --> MCP[bin/llama-mcp<br/>stdio JSON-RPC]
+  CLI  --> Client[lib/client.mjs<br/>auth · fetch · errors]
+  MCP  --> Client
+  Client -- HTTPS --> API[(command.llamaventures.vc)]
+  classDef src fill:#dcfce7,stroke:#166534,color:#14532d
+  classDef edge fill:#dbeafe,stroke:#1e40af,color:#1e3a8a
+  class Human,Agent edge
+  class CLI,MCP,Client src
+```
 
-## What this ships
+---
 
-This npm package contains two binaries:
+## Install
 
-- **`llama`** — interactive CLI (humans + bash scripts). Zero deps, native fetch.
-- **`llama-mcp`** — stdio [MCP](https://modelcontextprotocol.io) server (Claude Code, Claude Desktop, Cursor, OpenClaw, Codex, any MCP-native agent). Single dep: `@modelcontextprotocol/sdk`.
+```bash
+npm i -g @llamaventures/cli
+```
 
-Both share the same auth chain and HTTP client, so behaviour stays in lockstep.
+Requires **Node 18+** (uses native `fetch` and ESM). CI runs the matrix on 18 / 20 / 22.
 
-## Install
+Verify:
 
 ```bash
-npm i -g @llamaventures/cli
+llama --version
+llama auth status     # round-trips against /api/me
 ```
 
-Requires Node 18+ (uses native `fetch`).
+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
 
-The CLI tries credentials in this order on every call:
+The client tries credentials **in this order**, on every call:
 
-1. **`gcloud auth print-identity-token`** → `Authorization: Bearer …` (zero config; recommended for team members)
-2. **`$LLAMA_TOKEN` env var** → `X-Llama-Token` (preferred for CI / sandboxed agents)
-3. **`~/.llama/token`** (single line, mode `0600`) → `X-Llama-Token`
-4. **`~/.llama-command/config.json`** — legacy from CLI v0.1; auto-migrates to `~/.llama/token` on first read
+| # | Source | Header sent | Best for |
+|---|--------|-------------|----------|
+| 1 | `gcloud auth print-identity-token` | `Authorization: Bearer …` | Team members on a workstation (zero config) |
+| 2 | `$LLAMA_TOKEN` env var | `X-Llama-Token` | CI runners, sandboxed cloud agents |
+| 3 | `~/.llama/token` (mode `0600`) | `X-Llama-Token` | Persistent local install |
+| 4 | `~/.llama-command/config.json` | `X-Llama-Token` | Legacy CLI v0.1 — auto-migrates to `~/.llama/token` on first read |
 
-If both Bearer and X-Llama-Token are present, both are sent. The server tries Bearer first; on verification failure it falls through to X-Llama-Token.
+Both Bearer and X-Llama-Token are sent if both exist. The server tries Bearer
+first; on verification failure it falls through to X-Llama-Token. Inspect the
+resolved identity any time with `llama auth status`.
 
-### Zero-config (recommended)
+### Zero-config — recommended for team members
 
 ```bash
-gcloud auth login          # one-time, pick your @llamaventures.vc account
-llama auth status          # confirm — should show role + email
-llama deal search acme-ai  # ready to go
+gcloud auth login          # one-time; pick your @llamaventures.vc account
+llama auth status          # → role + email
+llama deal search acme-ai  # ready
 ```
 
-### Manual token
+### Manual token — for machines without `gcloud`, or stable CI
 
-For machines without `gcloud`, or for stable CI / agent setups:
-
-1. Sign in to https://command.llamaventures.vc
-2. Visit `/settings/tokens` → click **Mint Token**
-3. Save the `llc_…` value to `~/.llama/token`:
+1. Sign in to https://command.llamaventures.vc.
+2. Open `/settings/tokens` → **Mint Token**.
+3. Save the `llc_…` value:
 
    ```bash
    llama token set llc_paste_token_here
-   # writes ~/.llama/token (mode 0600), round-trips against /api/me before saving
+   #  → writes ~/.llama/token (mode 0600)
+   #  → round-trips /api/me before saving — bad token never lands on disk
    ```
 
-   Or set it as an env var (preferred for CI):
+   Or, in CI / one-shot environments:
 
    ```bash
    export LLAMA_TOKEN=llc_paste_token_here
    ```
 
-A team member without an account: ask
-[gavin@llamaventures.vc](mailto:gavin@llamaventures.vc) to mint one for you (he can mint for any email; it auto-creates an inactive user row that he then activates).
+> **Don't have an account?** Email
+> [gavin@llamaventures.vc](mailto:gavin@llamaventures.vc). Any email — including
+> non-`@llamaventures.vc` — can be granted a token; the system admin
+> mints it via `/settings/tokens`. Token first-use auto-creates the user row.
 
-## External / founder use (no Llama token required)
+---
 
-If you don't have a Llama Command token — you're a founder pitching us, an
-EA, a prospective hire, or just exploring — the CLI ships a separate
-`pitch` command family that talks to our public intake agent at
-[command.llamaventures.vc/external-agent](https://command.llamaventures.vc/external-agent).
-Same conversation, structured intake, same 12-dimension verdict as the web
-flow — but driven from your terminal (or your AI agent over MCP).
+## CLI tour
 
-```bash
-# Bootstrap a session
-llama pitch start --name "Jane Doe" --email "jane@acme.ai"
-
-# Send a message (single-shot, prints reply)
-llama pitch say "We're building an AI dev tool for X..."
-
-# Attach your deck / one-pager
-llama pitch upload ./deck.pdf
-
-# Or open an interactive REPL
-llama pitch
-```
-
-Caps (server-enforced — same as the web flow): 5 sessions/IP/day,
-3 sessions/email/day, 30min idle timeout, 100 messages/session,
-1M tokens/session.
-
-The MCP server exposes the same surface as `pitch_*` tools
-(`pitch_start`, `pitch_send_message`, `pitch_upload_file`, `pitch_status`,
-`pitch_finalize`) — so the founder's own AI agent (Claude / Cursor /
-OpenClaw / etc.) can help them pitch via Llama's intake agent. True A2A.
-
-## CLI command reference
+The CLI is the canonical interface. The HTTP API beneath it is stable, but the
+CLI handles auth, error formatting, and forward-compatibility across server
+schema changes — **prefer the CLI even from inside scripts.**
 
 ```bash
-# Auth diagnostics
+# Auth + tokens
 llama auth status
-
-# Token management
-llama token set <llc_...> [--base https://command.llamaventures.vc]
+llama token set <llc_...>
 llama token show
 
-# Deals — read
-llama deal search <query> [--founder ...] [--owner ...] [--status ...] [--stage ...] [--limit N]
-llama deal list [--owner ...] [--status ...]
+# Pipeline — read
+llama deal search "acme ai"
+llama deal list --owner alex --status Diligence
 llama deal show <dealId>
 
-# Deals — write
-llama deal create "Company" --description "..." [--source ...] [--stage ...] [...]
-llama deal update <dealId> <field> <value>
-llama deal delete <dealId>                  # soft-delete (audit-logged)
+# Pipeline — write
+llama deal create "Acme AI" --description "..." --source Gavin
+llama deal update <dealId> status Diligence
+llama deal delete  <dealId>     # soft (audit-logged)
 llama deal restore <dealId>
-llama deal trash                            # list soft-deleted
 
-# Ownership
-llama claim <dealId>                        # propose self
-llama nominate <dealId> --user <userId>
-llama nominations list
-llama nominations decide <approvalId> accepted|declined
-llama approvals list                        # partner queue
-llama approvals decide <approvalId> approved|rejected [--note "..."]
+# Deal Brief — ordered, typed blocks (text · link · embed · callout)
+llama brief blocks       <dealId>
+llama brief add-text     <dealId> --heading "..." --body "..."
+llama brief add-link     <dealId> --url "..." --label "..."
+llama brief add-callout  <dealId> --tone insight --heading "..." --body "..."
+llama brief edit         <dealId> <blockId> [--heading ...] [--body ...]
+llama brief history      <dealId> <blockId>
+
+# Ownership + approvals
+llama claim       <dealId>
+llama nominate    <dealId> --user <userId>
+llama approvals   list
+llama approvals   decide <approvalId> approved --note "..."
 
 # Timeline + posts
 llama timeline <dealId>
-llama post <dealId> "message" [--link url] [--link-name "name"]
-
-# Brief blocks (ordered, typed: text | link | embed | callout)
-llama brief blocks <dealId>
-llama brief add-text    <dealId> --heading "..." --body "..."
-llama brief add-link    <dealId> --url "..." --label "..." [--description "..."]
-llama brief add-embed   <dealId> --url "..." [--label "..."]
-llama brief add-callout <dealId> --tone insight|info|warning|success --heading "..." --body "..."
-llama brief edit        <dealId> <blockId> [--heading ...] [--body ...] [--url ...] [--label ...] [--tone ...]
-llama brief delete      <dealId> <blockId>            # soft
-llama brief restore     <dealId> <blockId>
-llama brief history     <dealId> <blockId> [--limit 50]
-llama brief restore-version <dealId> <blockId> <historyId>
-
-# Collaborators
-llama deal collab list    <dealId>
-llama deal collab add     <dealId> --user <userId|email>
-llama deal collab remove  <dealId> --user <userId|email>
-llama deal collab restore <dealId> --user <userId|email>
-
-# Links (URLs attached to a deal — Netlify demos, Gamma decks, etc.)
-llama deal link list    <dealId> [--include-deleted]
-llama deal link add     <dealId> --url <url> [--label "..."]
-llama deal link delete  <dealId> <linkId>
-llama deal link restore <dealId> <linkId>
-
-# Brief / persona refresh
-llama deal refresh-brief   <dealId> [--force]
-llama deal refresh-persona <dealId> <persona>
-
-# Deal facts (AI / human-asserted, with verification)
-llama deal fact list   <dealId>
-llama deal fact add    <dealId> --category <cat> --claim "<text>" [--source <url>] [--confidence high|medium|low]
-llama deal fact verify <dealId> <factId> --status confirmed|disputed [--corrected-value "..."]
-
-# Mentions / inbox
-llama mentions                              # my unresolved cues (default)
-llama mentions list [--everyone] [--all]
-llama mentions show <mentionId>
+llama post     <dealId> "message body" [--link url]
+
+# Wiki
+llama wiki search "<query>"
+llama wiki save <slug> --title "..." --content "..."
+
+# Mentions inbox
+llama mentions
 llama mentions resolve <mentionId>
-llama mentions unread                       # badge count
-
-# Skill corrections (persona-owner workflow)
-llama skill-correction list <skill-slug> [--include-deleted]
-llama skill-correction add <skill-slug> "<rule>" [--deal <uuid>] [--block <blockId>]
-llama skill-correction delete <id>
-
-# Wiki (knowledge base)
-llama wiki search <query>
-llama wiki read <slug>
-llama wiki save <slug> --title "..." --content "..." [--sources "url1;url2"]
-
-# Admin event feeds (system admin only)
-llama admin auth-events  [--kind X] [--actor email] [--since 24h] [--limit 100]
-llama admin deal-events  [--kind X] [--deal <uuid>] [--since 24h]
-llama admin agent-events [--kind tool_call|loop_stalled] [--errors-only]
 ```
 
-### Soft-delete
+Run `llama --help` for the full surface (~40 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`.
+
+### Error codes — for agents
+
+The CLI's stderr exit messages start with stable, parseable prefixes:
 
-All deletes through this CLI are non-destructive: brief blocks, collaborators, deal links, and deals themselves use `deleted_at` markers. Default reads filter trashed rows out; pass `--include-deleted` on `deal link list` (or visit `/admin` for the broader trash view) to see them. Every removal and restore writes an audit-log entry.
+| Prefix | Meaning | Recovery |
+|--------|---------|----------|
+| `Error[NO_AUTH]` | No credentials found anywhere | `gcloud auth login` **or** `llama token set` |
+| `Error[UNAUTHORIZED]` | Server rejected the credentials we sent | Token may be revoked / expired / wrong gcloud account |
 
-## MCP server (`llama-mcp`)
+The MCP server returns the same prefixes inside `isError: true` content so
+agents can pattern-match without parsing prose.
 
-The same package ships a stdio MCP server with **16 tools** mirroring the most-used CLI surface. Auth is identical — gcloud → `$LLAMA_TOKEN` → `~/.llama/token`. The server reuses `lib/client.mjs` so the CLI and MCP can never drift on transport or auth.
+---
 
-Tools registered:
+## MCP server
+
+The bundled `llama-mcp` is a **stdio Model Context Protocol** server exposing
+**19 typed tools** that mirror the most-used CLI surface. Every tool is named
+and scoped — there is no generic API passthrough, by design (a public-package
+escape hatch reachable from a prompt-injectable agent context is exactly the
+shape we want to avoid).
 
 ```
-auth_status              deal_search   deal_show
-deal_create              deal_update
-brief_blocks             brief_add_text  brief_add_link  brief_add_callout
-wiki_search              wiki_save
-timeline                 post
+auth_status
+
+deal_search            deal_show
+deal_create            deal_update
+
+brief_blocks           brief_add_text
+brief_add_link         brief_add_callout
+
+timeline               post
+
+wiki_search            wiki_save
+
 mentions_list
-llama_api                # escape hatch — raw HTTP for endpoints not yet wrapped
+
+pitch_start            pitch_send_message
+pitch_upload_file      pitch_status
+pitch_finalize
 ```
 
-`llama_api` is a generic passthrough modeled on the GitHub MCP server pattern: agents discover it via `tools/list` and use it for any endpoint not yet given a typed wrapper. Path must start with `/api/`.
+Auth is identical to the CLI's chain (gcloud → `$LLAMA_TOKEN` → `~/.llama/token`).
+The `agent_briefing` MCP **prompt** also returns
+[`AGENT_BRIEFING.md`](AGENT_BRIEFING.md) verbatim, so any new agent loading the
+server can self-onboard without leaving the protocol.
+
+### Wire into your agent
 
-### Wire into Claude Desktop / Claude Code
+<details open>
+<summary><strong>Claude Desktop</strong> (macOS path shown — Linux/Windows differ)</summary>
 
-`~/.config/claude-desktop/claude_desktop_config.json` (macOS:
-`~/Library/Application Support/Claude/claude_desktop_config.json`):
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "llama": {
-      "command": "llama-mcp"
-    }
+    "llama": { "command": "llama-mcp" }
   }
 }
 ```
 
-Restart Claude Desktop. The 16 tools appear under the 🛠️ menu.
+Restart Claude Desktop. Tools appear under the 🛠️ menu.
+</details>
 
-### Wire into Cursor
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add llama -- llama-mcp
+```
+
+Or edit `~/.claude/claude.json` directly — same JSON shape as Desktop.
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
 
 `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "llama": {
-      "command": "llama-mcp"
-    }
+    "llama": { "command": "llama-mcp" }
   }
 }
 ```
+</details>
+
+<details>
+<summary><strong>OpenCode / OpenClaw / Codex / arbitrary stdio MCP client</strong></summary>
+
+Most clients accept a `command` + `args` pair. Locate the binary
+(`which llama-mcp` → typically `/usr/local/bin/llama-mcp` or
+`~/.npm-global/bin/llama-mcp`) and point the client at it. No protocol
+extensions, no transport flags.
+</details>
+
+> If you're new and want the agent to onboard itself, run
+> `llama agent-onboard` from the CLI or fetch the `agent_briefing` prompt from
+> the MCP server. It's the workflow contract — autonomy levels, attribution
+> grammar, error recovery, anti-pollution rules.
+
+---
+
+## External pitch — no Llama account required
+
+If you're a **founder pitching us, an EA, or a prospective hire** without a
+Llama Command token, the CLI ships a `pitch` command family (and the parallel
+`pitch_*` MCP tools) that talks to our public intake agent at
+[command.llamaventures.vc/external-agent](https://command.llamaventures.vc/external-agent).
+Same conversation, same structured 12-dimension verdict — driven from your
+terminal or your own AI agent.
+
+```bash
+llama pitch start --name "Jane Doe" --email "jane@acme.ai"
+llama pitch say "We're building an AI dev tool for X..."
+llama pitch upload ./deck.pdf
+llama pitch                       # interactive REPL
+```
+
+Server-enforced caps (same as the web flow): 5 sessions/IP/day,
+3 sessions/email/day, 30 min idle timeout, 100 messages/session,
+1 M tokens/session.
+
+This is genuine **agent-to-agent**: your AI helps you tell the story, our
+intake agent extracts the structured fields and produces the verdict.
+
+---
+
+## Stability
 
-### Wire into a Codex / OpenClaw / arbitrary stdio MCP client
+- **Versioning:** [SemVer](https://semver.org). Renaming or removing a CLI
+  command bumps **major**. Adding a tool, command, or flag bumps minor.
+  Bugfixes bump patch. The CLI prints `--version`; the MCP server reports
+  the same value in its `serverInfo`.
+- **Backwards compatibility:** The wire format (Bearer / X-Llama-Token) and
+  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.
 
-Most clients accept a `command` + `args` config. Run `which llama-mcp` to find the binary path (`/usr/local/bin/llama-mcp` or `~/.npm-global/bin/llama-mcp`) and point the client at it. Any agent that speaks MCP over stdio works.
+See [`CHANGELOG.md`](CHANGELOG.md) for the per-version log.
 
-## Error codes (for agents)
+---
 
-CLI errors include a stable prefix so agents can pattern-match and recover:
+## Security
 
-- `Error[NO_AUTH]` — no credentials found. Direct the user to `gcloud auth login` or `llama token set`.
-- `Error[UNAUTHORIZED]` — server rejected our credentials. Token revoked, expired, or wrong account selected in gcloud.
+- **`@llamaventures/cli` is published via npm
+  [Trusted Publishers](https://docs.npmjs.com/trusted-publishers)** — no
+  `NPM_TOKEN` lives in repo secrets. Each release ships with `--provenance`
+  (sigstore-signed); the npm registry shows a **Provenance** badge traceable
+  to the exact GitHub Action workflow + commit.
+- **Minimal dependency tree.** The CLI is zero-deps. The MCP server depends
+  only on `@modelcontextprotocol/sdk`, pinned exact.
+- **Branch protection** on `main`; Dependabot, secret scanning, and
+  push-protection are enabled.
+- **Tokens:** stored locally at `~/.llama/token` mode `0600`. Server-side they
+  are stored as sha256 hashes — plaintext only ever exists in the user's
+  possession.
 
-The MCP server returns the same errors as `isError: true` content with the same prefix.
+Reporting a vulnerability: see [`SECURITY.md`](SECURITY.md). **Do not** file
+public GitHub issues for security bugs.
 
-## Versioning
+---
 
-Semver. Breaking changes to CLI command shape (renamed flags, removed commands) bump major. Adding a tool or flag bumps minor. Bug fixes bump patch.
+## Contributing
 
-The CLI prints its version under `llama --version`. MCP server reports the same version in its `serverInfo`.
+This is an internal tool maintained by Llama Ventures. PRs from team members
+are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the local dev loop,
+release flow (Trusted Publishers + GitHub Releases), and the conventions we
+follow (zero-deps, lockstep CLI/MCP, stable `Error[…]` prefixes).
 
-## Reporting security issues
+External contributions: feel free to open issues for documentation gaps or
+broken flows. Feature requests for non-team workflows are best directed at
+the [external pitch path](#external-pitch-no-llama-account-required) instead.
 
-**Do not file public GitHub issues for security bugs.** Email
-[gavin@llamaventures.vc](mailto:gavin@llamaventures.vc). See
-[SECURITY.md](./SECURITY.md) for scope, response SLA, and the
-supply-chain posture (Trusted Publishers + provenance + zero-deps CLI).
+---
 
 ## License
 
-[MIT](./LICENSE).
+[MIT](LICENSE) — © 2026 Llama Ventures, Inc.

package/README.zh-CN.md

@@ -0,0 +1,392 @@
+<p align="center">
+  <img src="assets/llama-ventures-logo.svg" alt="Llama Ventures" width="280">
+</p>
+
+<h1 align="center">@llamaventures/cli</h1>
+
+<p align="center">
+  <strong>Llama Ventures 官方 CLI 与 MCP server。</strong><br/>
+  一行 <code>npm install</code>，一套统一的认证链，两个接口——
+  团队成员和 AI agent 都通过同一份客户端访问
+  <a href="https://command.llamaventures.vc">command.llamaventures.vc</a>。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@llamaventures/cli"><img alt="npm" src="https://img.shields.io/npm/v/@llamaventures/cli?label=npm&color=cb3837&logo=npm&logoColor=white"></a>
+  <a href="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://docs.npmjs.com/trusted-publishers"><img alt="Provenance" src="https://img.shields.io/badge/provenance-signed-2e8b57?logo=npm"></a>
+  <a href="https://nodejs.org/"><img alt="Node" src="https://img.shields.io/node/v/@llamaventures/cli?color=339933&logo=nodedotjs&logoColor=white"></a>
+  <a href="https://modelcontextprotocol.io"><img alt="MCP 2024-11-05" src="https://img.shields.io/badge/MCP-2024--11--05-7d3aed"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <strong>简体中文</strong>
+</p>
+
+<p align="center">
+  <a href="#给华人创业者-向-llama-pitch">🚀 向 Llama pitch（无需账号）</a> ·
+  <a href="#安装">安装</a> ·
+  <a href="#认证">认证</a> ·
+  <a href="#cli-速览">CLI</a> ·
+  <a href="#mcp-server">MCP</a> ·
+  <a href="AGENT_BRIEFING.md">Agent 协议</a> ·
+  <a href="SECURITY.md">安全</a> ·
+  <a href="CHANGELOG.md">更新日志</a>
+</p>
+
+> **公开源码、低摩擦安装；不是开源产品。** 大多数命令需要 Llama Ventures
+> 团队账号（联系 [gavin@llamaventures.vc](mailto:gavin@llamaventures.vc)
+> 发 token）。**唯一例外是公开的 `pitch` 命令族**——任何创业者、EA、
+> 行政助理都能用，不需要 token，详见下方
+> [给华人创业者：向 Llama pitch](#给华人创业者-向-llama-pitch)。
+
+---
+
+## 包里有什么
+
+```
+@llamaventures/cli
+├── bin/llama          给人 + bash 用的交互式 CLI
+└── bin/llama-mcp      给 MCP 原生 agent 用的 stdio MCP server，20 个工具
+```
+
+两个 binary 共享 `lib/client.mjs`——**同一**认证链、**同一** HTTP 客户端、
+**同一**错误格式。CLI 与 MCP 不可能在身份或传输上漂移。CLI 自身零依赖；
+MCP server 仅依赖 `@modelcontextprotocol/sdk`（Anthropic 维护，pin 死版本）。
+
+```mermaid
+flowchart LR
+  Human([🧑‍💻 团队成员])         --> CLI[bin/llama<br/>argv 解析]
+  Agent([🤖 MCP 原生 agent]) --> MCP[bin/llama-mcp<br/>stdio JSON-RPC]
+  CLI  --> Client[lib/client.mjs<br/>认证 · fetch · 错误]
+  MCP  --> Client
+  Client -- HTTPS --> API[(command.llamaventures.vc)]
+  classDef src fill:#dcfce7,stroke:#166534,color:#14532d
+  classDef edge fill:#dbeafe,stroke:#1e40af,color:#1e3a8a
+  class Human,Agent edge
+  class CLI,MCP,Client src
+```
+
+---
+
+## 给华人创业者：向 Llama pitch
+
+如果你是创业者、EA、或者帮老板探索的助理，**不需要 token、不需要找认识的人介绍**——
+我们专门为外部 pitch 留了一条公开通道。它跟你在
+[command.llamaventures.vc/external-agent](https://command.llamaventures.vc/external-agent)
+上看到的网页版聊的是同一个 intake agent，结构化提取、12 维投资判断都是同一套，
+只是入口换成了你的终端，或者你自己的 AI 助手。
+
+```bash
+# 1. 装 CLI（不需要 Llama 账号）
+npm i -g @llamaventures/cli
+
+# 2. 起一个 session
+llama pitch start --name "张三" --email "you@yourstartup.com"
+
+# 3. 跟 agent 聊——单条消息
+llama pitch say "我们做 X，目标 Y，团队背景 Z..."
+
+# 4. 把 deck / 一页纸传上来
+llama pitch upload ./deck.pdf
+
+# 5. 或者直接进交互式 REPL
+llama pitch
+```
+
+**也可以让你自己的 AI agent 帮你 pitch（A2A）。** 把这个仓库的 MCP server
+挂到 Claude / Cursor / Codex / OpenClaw 上（任何能跑 MCP 的 agent 都行），
+然后告诉它"帮我 pitch Llama Ventures"。它会用 `pitch_start`、
+`pitch_send_message`、`pitch_upload_file`、`pitch_finalize` 这五个工具
+跟我们的 intake agent 对话。配置见 [MCP server](#mcp-server)。
+
+**会被服务端约束的上限**（跟网页版一样）：
+- 单 IP 每天 5 个 session
+- 单邮箱每天 3 个 session
+- 30 分钟无活动自动结束
+- 单 session 100 条消息 / 1M token
+
+**Pitch 完成后**：agent 会调 `finalize_intake` 写入结构化档案，自动给我们团队
+排进 inbox。我们看到后会主动联系你——不需要你再追。
+
+> 想了解 Llama Ventures 在投什么？看 [llamaventures.vc](https://llamaventures.vc)。
+> AI、Pre-seed 到 Series A、$3-5M 票，跨美中。**懂得用 AI 写代码、懂得让 AI
+> 帮你 pitch 的 founder——我们爱看。**
+
+---
+
+## 安装
+
+```bash
+npm i -g @llamaventures/cli
+```
+
+需要 **Node 18+**（用了原生 `fetch` 与 ESM）。CI 矩阵覆盖 18 / 20 / 22。
+
+验证：
+
+```bash
+llama --version
+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)。
+
+---
+
+## 认证
+
+客户端**按下面这个顺序**寻找凭证，每次调用都查一遍：
+
+| # | 来源 | 发送的 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` |
+
+如果 Bearer 和 X-Llama-Token 同时存在，两个一起发。服务器先验 Bearer，
+失败后回退到 X-Llama-Token。任何时候都可以用 `llama auth status`
+看当前认证身份。
+
+### 零配置 —— 团队成员推荐
+
+```bash
+gcloud auth login          # 一次性，选你的 @llamaventures.vc 账号
+llama auth status          # → 显示 role + email
+llama deal search acme-ai  # 直接用
+```
+
+### 手动 token —— 适合无 gcloud / 稳定 CI
+
+1. 登录 https://command.llamaventures.vc。
+2. 打开 `/settings/tokens` → **Mint Token**。
+3. 保存 `llc_…` 值：
+
+   ```bash
+   llama token set llc_paste_token_here
+   #  → 写入 ~/.llama/token (mode 0600)
+   #  → 落盘前会先打一次 /api/me，无效的 token 不会落到磁盘上
+   ```
+
+   或在 CI / 一次性环境里：
+
+   ```bash
+   export LLAMA_TOKEN=llc_paste_token_here
+   ```
+
+> **没账号？** 邮件 [gavin@llamaventures.vc](mailto:gavin@llamaventures.vc)。
+> 任何邮箱（包括非 `@llamaventures.vc`）都能拿 token；system admin
+> 在 `/settings/tokens` 里 mint，token 第一次使用时自动建 user 行。
+
+---
+
+## CLI 速览
+
+CLI 是 canonical 接口。底下的 HTTP API 也稳定，但 CLI 帮你处理了认证、错误格式、
+schema 前向兼容——**即使你写脚本，也优先用 CLI**。
+
+```bash
+# 认证 + token
+llama auth status
+llama token set <llc_...>
+llama token show
+
+# Pipeline——读
+llama deal search "acme ai"
+llama deal list --owner alex --status Diligence
+llama deal show <dealId>
+
+# Pipeline——写
+llama deal create "Acme AI" --description "..." --source Gavin
+llama deal update <dealId> status Diligence
+llama deal delete  <dealId>     # 软删除（审计日志记录）
+llama deal restore <dealId>
+
+# Deal Brief——有序的、有类型的 block（text · link · embed · callout）
+llama brief blocks       <dealId>
+llama brief add-text     <dealId> --heading "..." --body "..."
+llama brief add-link     <dealId> --url "..." --label "..."
+llama brief add-callout  <dealId> --tone insight --heading "..." --body "..."
+llama brief edit         <dealId> <blockId> [--heading ...] [--body ...]
+llama brief history      <dealId> <blockId>
+
+# Ownership + 审批
+llama claim       <dealId>
+llama nominate    <dealId> --user <userId>
+llama approvals   list
+llama approvals   decide <approvalId> approved --note "..."
+
+# 时间线 + 帖子
+llama timeline <dealId>
+llama post     <dealId> "消息内容" [--link url]
+
+# Wiki
+llama wiki search "<query>"
+llama wiki save <slug> --title "..." --content "..."
+
+# Mentions 收件箱
+llama mentions
+llama mentions resolve <mentionId>
+```
+
+跑 `llama --help` 看完整命令清单（约 40 个命令，覆盖 deals、briefs、ownership、
+timeline、facts、wiki、mentions、skill corrections、admin event feeds）。
+所有删除默认软删除——可恢复，且通过 `deal_events` 留下审计痕迹。
+
+### 错误码（给 agent 用）
+
+CLI 在 stderr 里抛错时带稳定的、可解析的前缀：
+
+| 前缀 | 含义 | 怎么恢复 |
+|------|------|---------|
+| `Error[NO_AUTH]` | 一个凭证都没找到 | `gcloud auth login` **或** `llama token set` |
+| `Error[UNAUTHORIZED]` | 服务端拒绝了我们发出去的凭证 | token 可能被 revoke / 过期 / gcloud 选错账号 |
+
+MCP server 在 `isError: true` 内容里返回相同的前缀，agent 不用解析自然语言就能 pattern-match。
+
+---
+
+## MCP server
+
+随包发布的 `llama-mcp` 是一个 **stdio Model Context Protocol** server，
+暴露 **19 个 typed tools**——基本镜像 CLI 最常用的命令。每个 tool 都是
+具名、scoped 的；**没有**通用的 API passthrough，这是有意设计的（公开
+package 里一个能被 prompt-injection 触达的逃生通道，正是我们要避开的形状）。
+
+```
+auth_status
+
+deal_search            deal_show
+deal_create            deal_update
+
+brief_blocks           brief_add_text
+brief_add_link         brief_add_callout
+
+timeline               post
+
+wiki_search            wiki_save
+
+mentions_list
+
+pitch_start            pitch_send_message
+pitch_upload_file      pitch_status
+pitch_finalize
+```
+
+认证链跟 CLI 完全一样（gcloud → `$LLAMA_TOKEN` → `~/.llama/token`）。
+`agent_briefing` 这个 MCP **prompt** 还会原样吐出
+[`AGENT_BRIEFING.md`](AGENT_BRIEFING.md)——刚装上 server 的 agent
+不用离开协议就能给自己 onboard。
+
+### 接到你的 agent 上
+
+<details open>
+<summary><strong>Claude Desktop</strong>（macOS 路径示例）</summary>
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "llama": { "command": "llama-mcp" }
+  }
+}
+```
+
+重启 Claude Desktop。工具会出现在 🛠️ 菜单里。
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add llama -- llama-mcp
+```
+
+或直接编辑 `~/.claude/claude.json`——JSON 结构和 Desktop 一样。
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+`~/.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "llama": { "command": "llama-mcp" }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>OpenCode / OpenClaw / Codex / 任何其它 stdio MCP 客户端</strong></summary>
+
+大部分客户端都接受 `command` + `args`。先 `which llama-mcp` 找到可执行路径
+（一般是 `/usr/local/bin/llama-mcp` 或 `~/.npm-global/bin/llama-mcp`），
+把客户端指过去就行。无需协议扩展、无需 transport flag。
+</details>
+
+> 想让 agent 自己 onboard？跑 `llama agent-onboard`，或者从 MCP server
+> 拉 `agent_briefing` prompt——那是 AI agent 的工作合约（autonomy 等级、
+> attribution 语法、错误恢复、anti-pollution 规则）。
+
+---
+
+## 稳定性
+
+- **版本号：** 走 [SemVer](https://semver.org)。重命名或删除 CLI 命令 → **major**。
+  新增 tool / command / flag → minor。修 bug → patch。CLI 自带 `--version`；
+  MCP server 在 `serverInfo` 里报告同一个值。
+- **向后兼容：** wire format（Bearer / X-Llama-Token）和 `Error[…]` 前缀
+  是公开契约，major 版本内不会变。
+- **服务端 schema 漂移：** 当 API 多了一个端点，下一个 minor 版本会带
+  typed wrapper。在那之前，可以用 `llama` CLI 本身——它自带 40+ 命令
+  覆盖整个 API 表面，足够顶住 MCP 还没包到的端点。
+
+详见 [`CHANGELOG.md`](CHANGELOG.md)。
+
+---
+
+## 安全
+
+- **`@llamaventures/cli` 通过 npm
+  [Trusted Publishers](https://docs.npmjs.com/trusted-publishers) 发布**——
+  仓库里**没有** `NPM_TOKEN`，发不出来 token 也就泄漏不了。
+  每个版本带 `--provenance`（sigstore 签名），npm 会显示 **Provenance** 徽章，
+  可追溯到具体的 GitHub Action workflow 和 commit。
+- **依赖树最小化。** CLI 本身零依赖；MCP server 只依赖
+  `@modelcontextprotocol/sdk`，pin 死版本。
+- **Branch protection** 锁 `main`；Dependabot、secret scanning、
+  push protection 都开了。
+- **Token：** 本地存在 `~/.llama/token`，mode `0600`。服务端只存 sha256 hash——
+  明文只会在用户手里出现，永远不在数据库里。
+
+报告漏洞：见 [`SECURITY.md`](SECURITY.md)。**不要**在公开 issue 里报安全 bug。
+
+---
+
+## 贡献
+
+这是 Llama Ventures 内部维护的工具。团队成员的 PR 欢迎——
+详见 [`CONTRIBUTING.md`](CONTRIBUTING.md)（本地开发环、发版流程、
+项目约定：零依赖、CLI/MCP 同步、稳定的 `Error[…]` 前缀）。
+
+外部贡献：文档错漏、流程报告类的 issue 欢迎。如果你想做的事是
+"我想让 Llama Ventures 看到我的项目"——请走
+[向 Llama pitch](#给华人创业者-向-llama-pitch) 那条路。
+
+---
+
+## License
+
+[MIT](LICENSE) — © 2026 Llama Ventures, Inc.

package/bin/llama-mcp.mjs

@@ -7,10 +7,14 @@
 // agent's MCP config — see README for snippets. Auth is identical to the
 // CLI: gcloud (preferred) → $LLAMA_TOKEN → ~/.llama/token.
 
+import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { getAuthHeaders, readBriefing, request } from "../lib/client.mjs";
+
+const requireFromHere = createRequire(import.meta.url);
+const { version: PKG_VERSION } = requireFromHere("../package.json");
 import {
   clearExternalSession,
   getExternalSessionStatus,
@@ -38,7 +42,7 @@ async function callApi(method, path, body) {
 
 const server = new McpServer({
   name: "llama-mcp",
-  version: "1.0.0",
+  version: PKG_VERSION,
 });
 
 // ============================================================
@@ -350,39 +354,6 @@ server.registerTool(
   }
 );
 
-// ============================================================
-// Escape hatch
-// ============================================================
-
-server.registerTool(
-  "llama_api",
-  {
-    description:
-      "Generic Llama Command HTTP API passthrough. Use this for endpoints that " +
-      "don't yet have a typed tool. Returns raw JSON. Path must start with /api/. " +
-      "See https://github.com/SoujiOkita98/llama-cli for the wrapped tool list.",
-    inputSchema: {
-      method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
-      path: z.string().describe("path starting with /api/"),
-      body: z
-        .any()
-        .optional()
-        .describe(
-          "request body — only used on POST / PUT / PATCH; should be a JSON-serializable object"
-        ),
-    },
-  },
-  async ({ method, path, body }) => {
-    if (typeof path !== "string" || !path.startsWith("/api/")) {
-      return {
-        content: [{ type: "text", text: "Error: path must start with /api/" }],
-        isError: true,
-      };
-    }
-    return callApi(method, path, body);
-  }
-);
-
 // ============================================================
 // External pitch (founder intake) — no Llama Command token required
 // ============================================================

package/bin/llama.mjs

@@ -500,6 +500,13 @@ async function runPitchRepl() {
 
 async function main() {
   const [area, action, ...rest] = process.argv.slice(2);
+  if (area === "--version" || area === "-v" || area === "version") {
+    const { createRequire } = await import("module");
+    const requireFromHere = createRequire(import.meta.url);
+    const { version } = requireFromHere("../package.json");
+    console.log(version);
+    return;
+  }
   if (!area || area === "help" || area === "--help" || area === "-h") {
     usage();
     return;
@@ -608,7 +615,7 @@ https://command.llamaventures.vc/settings/tokens, run
           throw new Error(`Verify call failed: HTTP ${res.status}. Not saving.`);
         }
       } catch (e) {
-        if (e instanceof Error && e.message.startsWith("Server rejected") || e.message.startsWith("Verify call failed")) {
+        if (e instanceof Error && (e.message.startsWith("Server rejected") || e.message.startsWith("Verify call failed"))) {
           throw e;
         }
         // Network / DNS failure — surface but let the user override.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Llama Ventures CLI + MCP server. Internal team tool for command.llamaventures.vc.",
   "type": "module",
   "bin": {
@@ -28,15 +28,23 @@
   },
   "keywords": [
     "llama-ventures",
+    "venture-capital",
+    "investment-pipeline",
     "cli",
     "mcp",
-    "modelcontextprotocol"
+    "mcp-server",
+    "modelcontextprotocol",
+    "agent",
+    "ai-agent",
+    "anthropic"
   ],
   "author": "Llama Ventures, Inc.",
+  "funding": "https://github.com/SoujiOkita98/llama-cli",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^4.4.3"
   }
 }