@llamaventures/cli 1.17.1 → 1.17.3

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,33 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.17.3] - 2026-07-01
+
+### Changed
+- README (en + zh) condensed to the essentials — install, auth, AI-system
+  integration, CLI/MCP quick reference, external pitch; removed the
+  architecture diagram and marketing filler.
+- Security reporting now goes through GitHub private vulnerability reporting
+  instead of a personal email (README, SECURITY.md, CONTRIBUTING.md).
+- npm tarball trimmed to runtime files (bin/, lib/, agent briefing,
+  changelog, READMEs, license) — repo docs and CI test assets are no longer
+  published. 18 → 14 files.
+
+## [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

@@ -6,17 +6,15 @@
 
 <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.
+  One package, two binaries: <code>llama</code> — the CLI for humans and scripts —
+  and <code>llama-mcp</code> — a stdio MCP server with 58 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>
 
 <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/Llama-Ventures/llama-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Llama-Ventures/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>
 
@@ -27,285 +25,110 @@
 <p align="center">
   <a href="#install">Install</a> ·
   <a href="#authenticate">Authenticate</a> ·
-  <a href="#cli-tour">CLI</a> ·
+  <a href="#integrate-your-ai-system">Integrate your AI</a> ·
+  <a href="#cli">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="#external-pitch--no-llama-account-required">External pitch</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
-
-```
-@llamaventures/cli
-├── bin/llama          interactive CLI for humans + bash
-└── bin/llama-mcp      stdio MCP server, 56 typed tools — for any MCP-native agent
-```
-
-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
-```
-
----
+> **Public source for low-friction install — not an open-source product.**
+> Most operations require a Llama Ventures team account (tokens are minted by
+> the team admin at `/settings/tokens`). The one exception is the public
+> [`pitch`](#external-pitch--no-llama-account-required) family.
 
 ## Install
 
 ```bash
-npm i -g @llamaventures/cli
-```
-
-Requires **Node 18+** (uses native `fetch` and ESM). CI runs the matrix on 18 / 20 / 22.
-
-Verify:
-
-```bash
+npm i -g @llamaventures/cli    # Node 18+; also puts `llama-mcp` on your PATH
 llama --version
-llama auth status     # round-trips against /api/me
+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
 
-The client tries credentials **in this order**, on every call:
-
-| # | Source | Header sent | Best for |
-|---|--------|-------------|----------|
-| 1 | `llama auth login` (OAuth 2.1, OS Keychain) | `Authorization: Bearer …` | **Recommended for everyone.** One-shot browser login; tokens auto-refresh and survive reboots. |
-| 2 | `gcloud auth print-identity-token` | `Authorization: Bearer …` | Workstations with gcloud already wired (zero config) |
-| 3 | `$LLAMA_TOKEN` env var | `X-Llama-Token` | CI runners, sandboxed cloud agents |
-| 4 | `~/.llama/token` (mode `0600`) | `X-Llama-Token` | Persistent local install (legacy PATs) |
-| 5 | `~/.llama-command/config.json` | `X-Llama-Token` | CLI v0.1 — auto-migrates to `~/.llama/token` |
+Credentials are tried in this order, on every call:
 
-If both Bearer and X-Llama-Token are present, both are sent — the server tries
-Bearer first and falls through to X-Llama-Token on verification failure.
-Inspect the resolved identity any time with `llama auth status`.
-
-### Browser sign-in — recommended
+| # | Source | Best for |
+|---|--------|----------|
+| 1 | `llama auth login` (OAuth, OS keychain, auto-refresh) | **Recommended for everyone** |
+| 2 | `gcloud auth print-identity-token` | Machines already wired with gcloud |
+| 3 | `$LLAMA_TOKEN` env var | CI, sandboxed cloud agents |
+| 4 | `~/.llama/token` (mode `0600`) | Long-lived PATs |
+| 5 | `~/.llama-command/config.json` | v0.1 legacy — auto-migrates |
 
 ```bash
-llama auth login           # opens browser → Google sign-in → consent → done
-llama auth status          # → activeMethod=oauth, scope, identity
-llama deal search acme-ai  # ready
+llama auth login          # browser sign-in; tokens auto-refresh, survive reboots
+llama auth logout         # revokes server-side, clears local storage
+llama token set llc_…     # PAT from /settings/tokens — validated before it lands on disk
+llama auth status         # shows the resolved identity + active method
 ```
 
-`llama auth login` runs an OAuth 2.1 PKCE + RFC 8252 loopback flow against
-`https://command.llamaventures.vc`, exchanges the code for an access + refresh
-token pair, and stores them in the OS Keychain (macOS Keychain / Windows
-Credential Manager / Linux Secret Service via [`@napi-rs/keyring`](https://www.npmjs.com/package/@napi-rs/keyring)).
-Linux containers without libsecret use a 0600-mode file at `~/.llama/oauth.json`
-— same posture `gcloud` / `gh` / `aws` ship with on Linux servers. Refresh
-tokens rotate transparently when the access token nears expiry; a cross-process
-file lock prevents two shells from burning each other's refresh during
-concurrent calls.
-
-`llama auth logout` revokes server-side via RFC 7009 and clears local storage.
-
-### gcloud — for machines already wired with `gcloud auth login`
-
-```bash
-gcloud auth login          # one-time; pick your @llamaventures.vc account
-llama auth status          # → role + email
-llama deal search acme-ai  # ready
-```
+> **No account?** Ask your Llama Ventures contact — any email address can be
+> granted a token.
 
-### Long-lived PAT — for CI / unattended environments
+## Integrate your AI system
 
-1. Sign in to https://command.llamaventures.vc.
-2. Open `/settings/tokens` → **Mint Token**.
-3. Save the `llc_…` value:
+This package is the **supported integration surface** for Llama Command. Wire
+in-house agents and LLM apps through here — **not the raw HTTP API**: the
+CLI/MCP layer owns the auth chain, the stable `Error[…]` contract, and
+forward-compatibility ([SemVer](#stability)); raw API routes carry no such
+promise.
 
-   ```bash
-   llama token set llc_paste_token_here
-   #  → writes ~/.llama/token (mode 0600)
-   #  → round-trips /api/me before saving — bad token never lands on disk
-   ```
+1. **Credentials** — `llama auth login`, or a PAT via `llama token set` /
+   `$LLAMA_TOKEN` for headless systems.
+2. **Install** — `npm i -g @llamaventures/cli`.
+3. **Wire it in** — MCP-native agents point at `llama-mcp`
+   ([per-client config](#mcp-server)); anything else shells out to `llama …`.
+4. **Onboard the agent** — run `llama agent-onboard` (or the MCP
+   `agent_briefing` prompt) at session start. It returns the server-owned
+   Agent Runtime Contract, always in sync with the live server.
+5. **Verify** — `llama auth status`, then `llama deal search "<anything>"`.
 
-   Or, in CI / one-shot environments:
+## CLI
 
-   ```bash
-   export LLAMA_TOKEN=llc_paste_token_here
-   ```
-
-> **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.
-
----
-
-## CLI tour
-
-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.**
+The CLI is the canonical interface — it handles auth, error formatting, and
+schema forward-compatibility. Prefer it even from scripts.
 
 ```bash
-# Auth + tokens
-llama auth status
-llama token set <llc_...>
-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 search "acme ai"            # find deals (deal list takes the same filters)
 llama deal show <dealId>
-
-# 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 feed <dealId>               # every contribution, newest first
+llama deal create "Acme AI" --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
-llama deal enrich <dealId> --executor external_agent --prompt
-llama deal agent run <dealId> --message "collect founder evidence and update typed facts"
-llama deal delete  <dealId>     # soft (audit-logged)
-llama deal restore <dealId>
-
-# Status semantics
-# Interested = record/track before outreach, intro, response, deck submission, or meeting.
-# Outreached = contact/logged, but no response or effective relationship yet.
-# Sourced    = response, intro, meeting, or another real relationship signal exists.
-# sourceDirection is separate:
-# Inbound    = came into the firm.
-# Outbound   = we found/listed/reached out first.
-
-# 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 body" [--link url]
-
-# Agent runtime — live Command + private Llama OS skill gateway
-llama agent bootstrap
-llama skills search "wiki delete tombstone"
-llama skills show llama-command
-llama explain https://command.llamaventures.vc/wiki/some-page
-llama eval bad --last --reason "missed the llamaos weekly note"
-llama eval add "last week llama dev weekly" --expect wiki:llamaos-weekly-2026-06-17
-
-# Wiki
+llama post <dealId> "note body"
+llama brief add-text <dealId> --heading "..." --body "..."
 llama wiki search "<query>"
-llama wiki read   <slug> [--lang en|zh]
-# Markdown entry:
-llama wiki save <slug> --title "..." --content "..." --sources "url1;url2"
-# HTML entry — standalone page at /wiki/<slug> (full-viewport sandboxed iframe):
-llama wiki save <slug> --title "..." --file page.html --sources "..." [--content-type html]
-# Delete / restore (soft, reversible):
-llama wiki delete  <slug> [--lang en|zh]
-llama wiki restore <slug> [--lang en|zh]
-
-# Mentions inbox
+llama wiki save <slug> --title "..." --content "..."
 llama mentions
-llama mentions resolve <mentionId>
+llama agent-onboard                    # server-owned agent workflow contract
 ```
 
-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`.
+Status vocabulary — `Interested`: tracked before any contact ·
+`Outreached`: contacted, no response yet · `Sourced`: real relationship
+signal exists. `sourceDirection` is separate: `Inbound` came to the firm,
+`Outbound` we reached out first.
 
-### Error codes — for agents
+Run `llama --help` for the group index, `llama help all` for the full
+reference (100+ commands). Deletes are soft and audit-logged everywhere.
 
-The CLI's stderr exit messages start with stable, parseable prefixes:
+### Error codes
 
 | 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 |
-
-The MCP server returns the same prefixes inside `isError: true` content so
-agents can pattern-match without parsing prose.
-
----
+| `Error[NO_AUTH]` | No credentials found | `llama auth login` or `llama token set` |
+| `Error[UNAUTHORIZED]` | Server rejected the credentials | Token revoked / expired / wrong account |
 
-### Golden Query Eval feedback
-
-The CLI and MCP server send lightweight client telemetry to Command for each
-authenticated request: client kind/version, detected agent client, local session
-id, normalized command, sanitized args, canonical result ids, status, latency,
-and bounded summaries. It records what Llama Command was asked to do, not the
-user's private Claude Code/Codex/Cursor conversation or local files.
-
-Search commands automatically become eval candidates. Agents can mark the latest
-result explicitly:
-
-```bash
-llama eval good --last
-llama eval bad --last --reason "wrong top wiki"
-llama eval add "AI陪伴" --surface deal --expect deal:<uuid>
-```
-
-MCP-native agents use `record_eval_feedback` for the same flow.
-
----
+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.
 
 ## MCP server
 
-The bundled `llama-mcp` is a **stdio Model Context Protocol** server exposing
-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).
-
-Coverage is grouped around the workflows agents actually need: auth
-diagnostics; live agent bootstrap; authenticated Llama OS skill search/read;
-Command URL/object inspection; deal search/show/create/update/feed; server-side deal agent runs;
-deal enrichment harnesses;
-trust-rated facts; brief blocks and version history; wiki read/write/delete/restore;
-timeline posts and mentions; skill corrections; refresh triggers; external pitch intake;
-memo show/regenerate/save/reset; and deal-scoped HTML docs, versions, bundles, and
-restore/reset.
-
-For the exact live list, smoke-test the server with `tools/list`:
+`llama-mcp` is a stdio Model Context Protocol server exposing 58 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:
 
 ```bash
 printf '%s\n' \
@@ -315,34 +138,14 @@ printf '%s\n' \
   | llama-mcp
 ```
 
-Auth is identical to the CLI's chain (gcloud → `$LLAMA_TOKEN` → `~/.llama/token`).
-The `agent_briefing` MCP **prompt** returns the server-owned Agent Runtime
-Contract when authenticated, so any new agent loading the server can
-self-onboard without leaving the protocol. The bundled
-[`AGENT_BRIEFING.md`](AGENT_BRIEFING.md) is only a fallback if the server
-briefing route is temporarily unavailable.
-
-For current Llama OS skills, use the runtime tools instead of looking for a
-local private repo: `agent_bootstrap`, `skills_search`, `skills_read`, and
-`object_inspect`. The public npm package does not bundle private skill text;
-Command returns only the content visible to the authenticated token.
-
-### Wire into your agent
-
-<details open>
-<summary><strong>Claude Desktop</strong> (macOS path shown — Linux/Windows differ)</summary>
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
-`~/Library/Application Support/Claude/claude_desktop_config.json`:
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
 ```json
-{
-  "mcpServers": {
-    "llama": { "command": "llama-mcp" }
-  }
-}
+{ "mcpServers": { "llama": { "command": "llama-mcp" } } }
 ```
-
-Restart Claude Desktop. Tools appear under the 🛠️ menu.
 </details>
 
 <details>
@@ -351,114 +154,64 @@ Restart Claude Desktop. Tools appear under the 🛠️ menu.
 ```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" }
-  }
-}
-```
 </details>
 
 <details>
-<summary><strong>OpenCode / OpenClaw / Codex / arbitrary stdio MCP client</strong></summary>
+<summary><strong>Cursor / any 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.
+Point the client at the `llama-mcp` binary (`which llama-mcp`). Same JSON
+shape as above; 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 pulls the Command-owned workflow contract — current CLI
-> guidance, attribution grammar, error recovery, and anti-pollution rules.
-
----
+> New agent? `llama agent-onboard` (CLI) or the `agent_briefing` prompt (MCP)
+> pulls the server-owned workflow contract. The bundled
+> [`AGENT_BRIEFING.md`](AGENT_BRIEFING.md) is a fallback copy only.
 
 ## 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.
+Founders, EAs, and prospective hires can pitch without a token: the `pitch`
+commands (and `pitch_*` MCP tools) talk to our public intake agent — the same
+structured 12-dimension intake as the
+[web version](https://command.llamaventures.vc/external-agent), 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
+llama pitch                     # interactive REPL
 ```
 
-Server-enforced rate limits apply (per-IP, per-email, per-session). If you
-hit a limit, the CLI surfaces the server's response message.
-
-This is genuine **agent-to-agent**: your AI helps you tell the story, our
-intake agent extracts the structured fields and produces the verdict.
-
----
+Server-enforced rate limits apply (per-IP, per-email, per-session).
 
 ## Stability
 
-- **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.
-
-See [`CHANGELOG.md`](CHANGELOG.md) for the per-version log.
-
----
+- **[SemVer](https://semver.org).** Renaming/removing a command → major;
+  new tool/command/flag → minor; fixes → patch.
+- **Public contract:** the wire format (Bearer / X-Llama-Token) and the
+  `Error[…]` prefixes don't change inside a major version.
+- **No raw-API passthrough, by design.** If a wrapper you need hasn't landed,
+  open an issue instead of calling the HTTP API directly.
 
 ## Security
 
-- **`@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.
+- Published via npm [Trusted Publishers](https://docs.npmjs.com/trusted-publishers)
+  (OIDC) with `--provenance` — no npm token exists to leak.
+- Zero runtime deps for the CLI; the MCP server depends only on
+  `@modelcontextprotocol/sdk`, pinned exact.
+- Branch protection, Dependabot, secret scanning, push protection enabled.
+- Tokens: `~/.llama/token` mode `0600` locally; sha256 hashes server-side.
 
-Reporting a vulnerability: see [`SECURITY.md`](SECURITY.md). **Do not** file
-public GitHub issues for security bugs.
-
----
+Report vulnerabilities privately via
+[GitHub security advisories](https://github.com/Llama-Ventures/llama-cli/security/advisories/new)
+— not public issues. See [`SECURITY.md`](SECURITY.md).
 
 ## Contributing
 
-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).
-
-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.
-
----
+Internal tool maintained by Llama Ventures; team PRs welcome — see
+[`CONTRIBUTING.md`](CONTRIBUTING.md). External: issues for doc gaps and broken
+flows are welcome; to get your company in front of us, use the
+[pitch path](#external-pitch--no-llama-account-required).
 
 ## License