@productbrain/cli 0.1.0-beta.18 → 0.1.0-beta.1805

package/README.md

@@ -1,228 +1,128 @@
 # Product Brain CLI (`pb`)
 
-CLI for Chain knowledge: read, search, gather context, and **write back**. Uses your Product Brain API key (same as MCP). Write commands require a readwrite key.
+Chain knowledge + write-back in the terminal. Read, search, capture, and update your product knowledge graph.
 
-**Requirements:** Node 18+, API key from Product Brain → Settings → API Keys (`pb_sk_*`).
-
----
+**Requirements:** Node 18+, API key from Product Brain Settings (`pb_sk_*`).
 
 ## Install
 
-### From npm (beta)
-
 ```bash
 npm install -g @productbrain/cli@beta
 ```
 
-Updates require a new publish to npm (and, if you use 2FA, a one-time password). Use this when you want a stable beta from the registry.
-
-### From main (no publish needed)
-
-If you have the repo and want **latest from `main`** without publishing to npm:
+From source (latest main):
 
 ```bash
 git clone https://github.com/synergyai-os/Product-OS.git
-cd Product-OS
-npm ci
+cd Product-OS && npm ci
 cd packages/cli && npm run build && npm install -g .
 ```
 
-After that, `pb` runs from your global path. Pull and re-run the last two commands to update:
+## Login
 
 ```bash
-cd Product-OS && git pull && cd packages/cli && npm run build && npm install -g .
+pb login
 ```
 
-See [Deployment strategy — CLI vs MCP](../../docs/deployment-strategy.md#cli-vs-mcp-distribution) for why this avoids `cli:publish` / OTP.
-
----
-
-## First run
-
-- **No key yet:** Run any command (e.g. `pb orient -b`). You’ll get a short guided flow: “Do you have an API key? (y/n)” → paste key → saved to `~/.config/productbrain/.env`. Your command then runs.
-- **Or:** Run `pb login` to paste and save your key once. Get a key: Product Brain app → Settings → API Keys.
+Paste your API key (`pb_sk_...`). Saved to `~/.config/productbrain/.env`.
 
-Config is read from (in order): env vars → `~/.config/productbrain/.env` → `.env.mcp` in the current directory.
+Or run any command without a key and follow the guided flow.
 
-## Terminal-native contract
+### Onboarding link (`pb connect`)
 
-Use `pb` with two explicit modes:
+If you received a connect token (`pb_ct_...`) from Product Brain:
 
-- **Read mode** for `orient`, `get`, `search`, `context`, and repo grounding
-- **Write mode** for `capture`, `relate`, `update`, and other Chain writes
+```bash
+pb connect pb_ct_...
+```
 
-The Chain is the live source of truth. Generated files such as `AGENTS.md`, `.productbrain/context.md`, `.productbrain/briefing.md`, and `.codex/skills/*` are local projections for grounding, not the authoring source.
+Redemption always targets a cloud Convex deployment (HTTP Actions are cloud-hosted, even during local dev). Resolution order: `--gateway` → `PB_CONNECT_GATEWAY_URL` → `CONVEX_SITE_URL` → production default (`gateway.productbrain.io`).
 
-In non-TTY usage, `pb` defaults to machine-readable JSON. Use `--json` to force JSON and `--pretty` to force human formatting.
+- **Dev deployments:** Set `CONVEX_SITE_URL` to your `*.convex.site` URL, or use `--gateway`.
+- If a token fails, the CLI hints about setting `CONVEX_SITE_URL` or using `--gateway`.
 
-Recommended default loop:
+## Quick Start
 
 ```bash
+# 1. Check your setup
+pb doctor
+
+# 2. Orient — see where things stand
 pb orient -b
-pb get <ID>
-# read projected repo context as needed
-pb session start   # only when entering write-heavy work
-pb capture "INS: ..."
-pb session close
-```
 
-Projected files such as `AGENTS.md`, `.productbrain/context.md`, and `.productbrain/briefing.md` are startup aids and mirrors. Use live `pb` reads when you need current truth from the Chain.
+# 3. Read an entry
+pb get BET-123
 
-### Recommended terminal-native startup loop
+# 4. Search the Chain
+pb search "onboarding flow"
 
-1. `pb orient -b`
-2. `pb get <ID>` before bet-, decision-, or standard-scoped implementation
-3. read projected repo context (`AGENTS.md`, `.productbrain/context.md`, `.productbrain/briefing.md`)
-4. stay in read mode while exploring
-5. `pb session start` only when you are entering write-heavy work
-6. `pb capture ...`
-7. `pb session close`
+# 5. Start a write session and capture knowledge
+pb session start
+pb capture "DEC: chose X because Y"
+pb capture "TEN: blocked by missing API"
+pb session close
+```
 
----
+Running `pb` with no arguments shows contextual guidance based on your setup state.
 
 ## Commands
 
 ### Read (no session required)
 
 | Command | Description |
-|--------|-------------|
-| `pb orient` | Workspace stage, bets, governance, tensions. Use `-b` for a brief view. |
-| `pb search <query>` | Full-text search across the Chain. |
-| `pb get <entry-id>` | Full entry (data, relations, last 10 history events). |
-| `pb context <entry-id>` | Constellation context (pipe-friendly markdown when not a TTY). |
-| `pb handshake` | Generate context files for AI developer tools. See below. |
-| `pb login` | Save your API key to `~/.config/productbrain/.env`. |
-
-Read mode is the default for grounding, repo tracing, and spec lookup. Do not start a write session until you actually intend to write back to the Chain.
-
-**Internal (Product-OS repo only):** `pb brand-pack` forwards to `scripts/brand-pack.mjs` — structured community marketing JSON via **OpenRouter** (`OPENROUTER_API_KEY`, not the Product Brain API key). Use `npm run brand-pack -- --help` from repo root for script options. Not published behavior for global npm installs unless built from this monorepo.
-
-### Write (session required — DEC-9)
+|---------|-------------|
+| `pb orient [-b]` | Workspace overview. `-b` for brief, `--task` for task-grounded context. |
+| `pb get <id>` | Full entry: data, relations, history. |
+| `pb search <query>` | Full-text search across all collections. |
+| `pb context <id>` | Constellation context for an entry. |
+| `pb fields <collection>` | Field definitions for a collection. |
+| `pb constellation <id>` | Entry + all related entries grouped by relation type. |
+| `pb collections list` | All collections with field counts. |
+| `pb glossary` | Key Product Brain CLI terms. |
+| `pb scoreboard [--task <task>] [--json]` | Flywheel health board: M1/M2/M3 metrics, materialization age, and diagnosis. `--json` for the structured agent shape. |
+| `pb doctor` | Check configuration and connectivity. |
+
+### Write (session required)
 
 | Command | Description |
-|--------|-------------|
-| `pb session start` | Open a tracked write session. Refreshes context files. |
-| `pb capture "<text>"` | Capture a decision, tension, insight, or any knowledge to the Chain. Auto-classifies. |
-| `pb session close` | Close the session. Shows captured entries, runs wrapup, refreshes context. |
-
-`pb --help` for options.
-
-### Mixed-surface switching
-
-If you use Codex, Cursor, or Claude on the same stretch of work:
-
-1. let one surface own writes at a time
-2. let other surfaces read freely
-3. close the current write stretch before a different surface becomes the writer
-
-Do not treat force-close or overlapping write sessions as normal workflow. The goal is clear attribution, not concurrent write ownership.
-
-### Delivery + Chain (when you ship code in Product-OS)
-
-Progressive delivery and deploy ordering are documented in the monorepo — not inside the `pb` binary:
-
-| SSOT | Purpose |
-|------|---------|
-| [`docs/system/design/progressive-delivery-thesis.md`](../../docs/system/design/progressive-delivery-thesis.md) | Ladder (dark launch → GA), rollback (**STA-10**), flags, edge/Cloudflare notes |
-| **MAP-13** on the Chain | Map entry pointing at the thesis — `pb get MAP-13` / `pb context MAP-13` |
-| [`docs/deployment-strategy.md`](../../docs/deployment-strategy.md) | CI target, Convex vs Railway, CLI vs MCP distribution |
+|---------|-------------|
+| `pb session start` | Open a tracked write session. |
+| `pb capture "<text>"` | Capture knowledge. Auto-classifies to the right collection. |
+| `pb update <id>` | Update fields on an existing entry. |
+| `pb relate <from> <type> <to>` | Add a typed relation between entries. |
+| `pb promote <id>` | Promote entry from draft to active. |
+| `pb session close` | Close session, show summary. |
 
-**BR-157:** If your push includes changes under `convex/`, run **`npx convex deploy`** (correct deployment) **before** `git push origin main` so Railway never serves a frontend that calls missing Convex functions.
+### Profile Management
 
-**Typical ship loop with `pb`:**
+Config is read from (in order): environment variables, `~/.config/productbrain/.env`, `.env.mcp` in the current directory.
 
 ```bash
-pb session start
-# … commit, merge, push per .productbrain/skills/commit-to-main …
-pb capture "DEC: Shipped <short>. Rollback: <flag OFF | Railway revert | …>. Convex deploy before push: <yes | N/A>."
-pb session close
-# If you changed .productbrain rules or skills:
-cd ../.. && pb handshake   # from repo root
+pb login          # Save API key
+pb doctor         # Verify configuration
+pb setup          # Guided first-time setup
 ```
 
----
-
-## `pb handshake` — AI Developer Onboarding
-
-One command generates context files for every major AI coding tool:
+### AI Developer Onboarding
 
 ```bash
-pb handshake
+pb handshake      # Generate context files for Codex, Cursor, Claude, Copilot
 ```
 
-**What it generates:**
-
-| File | Purpose |
-|------|---------|
-| `AGENTS.md` | Adapter for Codex / terminal-native agents |
-| `.codex/skills/*.md` | Product Brain skill projections for Codex |
-| `.productbrain/context.md` | Workspace briefing — stage, bets, governance, architecture, tensions |
-| `.productbrain/briefing.md` | Chain entries matched to this specific repo |
-| `CLAUDE.md` | Adapter for Claude Code |
-| `.cursor/rules/chain.mdc` | Adapter for Cursor |
-| `.github/copilot-instructions.md` | Adapter for GitHub Copilot |
-
-**Options:**
-
-- `--force` — Overwrite adapter files even if they have custom content
-- `--dry-run` — Preview what would be generated without writing files
-
-**Safety:** Adapter files are marked with `auto-generated by pb handshake`. If you customize one and remove the marker, future runs skip it (unless `--force`). The `.productbrain/` directory contains workspace-specific context and should be in `.gitignore`.
-
-**Governance:** Context export surface per DEC-161 and GLO-63. Architecture: ARCH-63 (surfaces are peers consuming the kernel).
-
-Projected files are adapters and mirrors, not the authoring source of truth. Use live `pb` reads when you need current Chain truth or are verifying governed product behavior.
-
----
-
-## `pb session` + `pb capture` — Close the Loop
-
-The Chain compounds from every AI coding session. Instead of knowledge dying in chat transcripts (TEN-27), capture it as you work.
-
-### Flow
-
-```bash
-# Start of session
-pb session start          # opens session, refreshes context
-
-# During work — capture what you learn
-pb capture "TEN: topology query returns stale containers when initiatives are archived"
-pb capture "DEC: excluded archived initiatives at the query level, not the UI filter"
-pb capture "INS: learned that the containerIds array references soft-deleted entries"
-
-# End of session
-pb session close          # shows summary, runs wrapup, refreshes context
-```
-
-### How capture works
-
-1. Text is sent to the Chain's classification pipeline — auto-assigns collection
-2. Entry is created as a **draft** (nothing auto-commits)
-3. Receipt shows: entry ID, collection, confidence, reasoning, alternatives
-4. You review and commit drafts in Product Brain Studio
-
-### Options
-
-- `pb capture --collection tensions "text"` — skip auto-classification, use explicit collection
-- `pb capture --name "Short title" --description "Full explanation"` — separate name and description
-- `pb session close --force` — clear local session state even if server close fails
-
-### Governance
-
-- Write access requires a tracked session (DEC-9, BR-8)
-- Session attribution via API key; `clientKind: 'cli'` discriminator per DEC-184 (pending schema extension)
-- All captures are drafts — human reviews and commits (TEN-374)
-- Solves TEN-264 (CLI write access session attribution) with explicit session token in `.productbrain/session.json`
-- Addresses TEN-27 (strategic conversations generate decisions that never reach the Chain)
-- Implements INS-80 (proactive capture during coding)
+Generates `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/chain.mdc`, `.productbrain/context.md`, and more.
 
-## JSON output contract
+## Output Modes
 
-`pb` treats output mode as part of the terminal-native surface contract:
+| Context | Output |
+|---------|--------|
+| TTY (terminal) | Human-readable formatting |
+| Piped / non-TTY | JSON |
+| `--json` | Force JSON |
+| `--pretty` | Force human-readable |
 
-- non-TTY output defaults to JSON
-- TTY output defaults to human-readable formatting
-- `--json` forces machine-readable JSON
-- `--pretty` forces human-readable output even when piped
+## Reference
 
-For automation, prefer calling `pb` directly instead of wrappers that add extra stdout noise. Changes to output shape should be treated as compatibility-sensitive for machine consumers.
+- `pb --help` for full command list
+- `pb <command> --help` for command-specific options
+- `pb glossary` for key terms
+- Chain: WP-302 (CLI Maturity)

package/dist/__tests__/adapters.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapters.test.d.ts.map

package/dist/__tests__/adapters.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/adapters.test.ts"],"names":[],"mappings":""}