@llamaventures/cli 1.26.0 → 2.0.0

package/README.md

@@ -1,262 +1,165 @@
-<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 package, two binaries: <code>llama</code> — the CLI for humans and scripts —
-  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>
-
-<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="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="#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="CHANGELOG.md">Changelog</a>
-</p>
-
-> **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
+# Llama Command CLI 2
 
-```bash
-npm i -g @llamaventures/cli    # Node 18+; also puts `llama-mcp` on your PATH
-llama --version
-llama version --json           # package, source commit, and pinned Core API contract
-llama auth status              # round-trips against /api/me
-```
-
-## Authenticate
+The small authenticated agent interface for Llama Command.
 
-Credentials are tried in this order, on every call:
+CLI 2 replaces the split Deal command surface with exactly four actions. Core
+owns database writes, Drive provisioning, audit Events, provenance, and
+idempotency. Agents never touch PostgreSQL directly.
 
-| # | 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 |
+## Install or upgrade
 
 ```bash
-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
+npm i -g @llamaventures/cli@latest
+llama --version
+llama auth status
 ```
 
-> **No account?** Ask your Llama Ventures contact — any email address can be
-> granted a token.
-
-## Integrate your AI system
+Llama Command requires CLI 2 for authenticated CLI/MCP requests. A 1.x client
+receives `426 CLI_VERSION_UNSUPPORTED` with the upgrade command; it does not
+fall back to legacy Deal APIs.
 
-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.
+Authentication is discovered in this order:
 
-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>"`.
+1. OAuth credentials from `llama auth login`.
+2. A local Google identity from `gcloud auth login`.
+3. `LLAMA_TOKEN`.
+4. `~/.llama/token`.
 
-## CLI
-
-The CLI is the canonical interface — it handles auth, error formatting, and
-schema forward-compatibility. Prefer it even from scripts.
+## Exactly four Deal actions
 
 ```bash
-llama deal search "acme ai"            # find deals (deal list takes the same filters)
-llama deal show <dealId>
-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 workflow show <dealId>
-llama workflow initialize <dealId> --reason "Migrate legacy workflow state without changing stage"
-llama workflow proceed <dealId> --transition begin_preliminary --reason "Ready to begin research"
-llama workflow execution-status <dealId> invested --reason "Wire confirmed"
-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 "..."
-llama mentions
-llama agent-onboard                    # server-owned agent workflow contract
+llama deal search "Acme" --limit 10
+llama deal read <dealId> --detail overview
+llama deal create --json create.json
+llama deal write --json write.json
 ```
 
-System admins can run the read-only production integrity auditor against one
-Workflow V2 deal or every persisted V2 snapshot:
+`read` is progressive:
 
 ```bash
-llama admin workflow audit --deal <dealId>
-llama admin workflow audit --all
+llama deal read <dealId> --detail memory
+llama deal read <dealId> --detail files
+llama deal read <dealId> --detail conversation
+llama deal read <dealId> --detail history
+llama deal read <dealId> --detail all
 ```
 
-For the two supported false-green intake checks, remediation is preview-first
-and one deal at a time. Apply requires the exact revision returned by preview:
-
-```bash
-llama admin workflow remediate --deal <dealId> --guard intake.reason_why
-llama admin workflow remediate --deal <dealId> --guard intake.reason_why \
-  --apply --expected-revision <revision> --reason "Confirmed missing canonical evidence"
-```
-
-The server can only invalidate a system-generated green. It cannot advance a
-deal, satisfy a check, change status/ownership, or override a human resolution.
-
-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.
-
-Deal stage is controlled only by Investment Workflow V2. Direct
-`deal update ... status ...` and legacy `stage_gates` writes are rejected;
-use `llama workflow show` followed by the matching formal workflow command.
-
-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
-email, or a numeric user id.
+The Live Deal Page is always returned. Expand only what the task needs.
 
-Run `llama --help` for the group index, `llama help all` for the full
-reference (100+ commands). Deletes are soft and audit-logged everywhere.
+### Create
 
-### Error codes
-
-| Prefix | Meaning | Recovery |
-|--------|---------|----------|
-| `Error[NO_AUTH]` | No credentials found | `llama auth login` or `llama token set` |
-| `Error[UNAUTHORIZED]` | Server rejected the credentials | Token revoked / expired / wrong account |
+```json
+{
+  "companyName": "Acme",
+  "page": {
+    "website": "https://example.com",
+    "stage": "Diligence"
+  },
+  "information": [
+    {
+      "type": "traction.claim",
+      "labels": ["founder_reported", "unverified"],
+      "subject": {"company": "Acme"},
+      "value": {"arrUsd": 320000}
+    }
+  ],
+  "origin": {
+    "kind": "user",
+    "originalUserUtterance": "Acme says ARR is about $320k."
+  }
+}
+```
 
-The MCP server returns the same prefixes inside `isError: true` content.
-Authenticated calls send bounded, content-redacted telemetry to Command.
+```bash
+llama deal create --json create.json
+```
 
-## MCP server
+Core adds `operation: deal.create`, creates or reuses the Drive folder, writes
+the initial Live Page and Information, and appends Events atomically.
 
-`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:
+### Write
 
-```bash
-printf '%s\n' \
-  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"dev","version":"1"}}}' \
-  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
-  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
-  | llama-mcp
-```
+`write` accepts only four operation choices:
 
-<details>
-<summary><strong>Claude Desktop</strong></summary>
+- `input.submit` — preserve raw input in the Event Feed.
+- `information.put` — add or update one structured memory unit.
+- `page.patch` — update the human-visible Live Deal Page.
+- `artifact.put` — add an immutable memo/HTML/source artifact.
 
-`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+Raw user input example:
 
 ```json
-{ "mcpServers": { "llama": { "command": "llama-mcp" } } }
+{
+  "operation": "input.submit",
+  "dealId": "<uuid>",
+  "format": "text",
+  "content": "the complete input",
+  "source": {"kind": "meeting_note"},
+  "origin": {
+    "kind": "user",
+    "originalUserUtterance": "the complete input"
+  }
+}
 ```
-</details>
-
-<details>
-<summary><strong>Claude Code</strong></summary>
 
 ```bash
-claude mcp add llama -- llama-mcp
+llama deal write --json write.json
 ```
-</details>
 
-<details>
-<summary><strong>Cursor / any stdio MCP client</strong></summary>
+For user-originated work, preserve the exact words in
+`origin.originalUserUtterance` or reference the canonical
+`origin.originatingChatRecordId`. An agent summary never replaces the source.
 
-Point the client at the `llama-mcp` binary (`which llama-mcp`). Same JSON
-shape as above; no protocol extensions, no transport flags.
-</details>
+Chat and Event are system-owned. There is no caller-controlled Event append or
+general Chat-forging operation.
 
-> 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.
+## Five Deal resources
 
-## External pitch — no Llama account required
+1. Live Deal Page — current human-visible state.
+2. Deal Information — structured, labelled, provenance-linked agent memory.
+3. Artifacts — immutable uploaded source material.
+4. Chat Records — append-only group and human-agent conversation.
+5. Deal Events — append-only, ordered, replayable history.
 
-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.
+Fact, opinion, founder, status, archive, trash, memo section, and artifact kind
+are labels or fields inside these resources, not extra tools or tables.
+
+## MCP
+
+Run the bundled stdio server:
 
 ```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-mcp
 ```
 
-Server-enforced rate limits apply (per-IP, per-email, per-session).
+Its Deal surface is also exactly four tools:
 
-## Stability
+- `search_deals`
+- `read_deal`
+- `create_deal`
+- `write_deal`
 
-- **[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.
+Authentication, skill discovery, Wiki, admin audit, preferences, and external
+pitch remain separate non-Deal domains.
 
-## Security
+## Agent bootstrap
 
-- 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.
-
-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).
+```bash
+llama agent bootstrap
+llama skills search "<task>"
+llama skills show <slug>
+```
 
-## Contributing
+The live server briefing is authoritative. The bundled
+`AGENT_BRIEFING.md` is an offline fallback with the same four-action contract.
 
-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).
+## Development
 
-## License
+```bash
+npm install
+npm test
+npm run verify:release
+```
 
-[MIT](LICENSE) — © 2026 Llama Ventures, Inc.
+Release artifacts are source-SHA certified. Publishing to npm and changing the
+production server's minimum version are separate, explicit release operations.