@productbrain/cli 0.1.0-beta.9 → 0.1.0-beta.9000

package/README.md

@@ -1,142 +1,136 @@
 # 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
+Paste your API key (`pb_sk_...`). Saved to `~/.config/productbrain/.env`.
 
-- **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.
+Or run any command without a key and follow the guided flow.
 
-Config is read from (in order): env vars → `~/.config/productbrain/.env` → `.env.mcp` in the current directory.
+### Onboarding link (`pb connect`)
 
----
+If you received a connect token (`pb_ct_...`) from Product Brain:
 
-## Commands
+```bash
+pb connect pb_ct_...
+```
 
-### Read (no session required)
+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`).
 
-| 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`. |
+- **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`.
 
-### Write (session required — DEC-9)
+## Quick Start
 
-| 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.
+```bash
+# 1. Check your setup
+pb doctor
 
----
+# 2. Orient — see where things stand
+pb orient -b
 
-## `pb handshake` — AI Developer Onboarding
+# 3. Read an entry
+pb get BET-123
 
-One command generates context files for every major AI coding tool:
+# 4. Search the Chain
+pb search "onboarding flow"
 
-```bash
-pb handshake
+# 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
 ```
 
-**What it generates:**
+Running `pb` with no arguments shows contextual guidance based on your setup state.
 
-| File | Purpose |
-|------|---------|
-| `.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
+## Commands
 
-**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`.
+### Read (no session required)
 
-**Governance:** Context export surface per DEC-161 and GLO-63. Architecture: ARCH-63 (surfaces are peers consuming the kernel).
+| Command | Description |
+|---------|-------------|
+| `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 [--json]` | Flywheel health board: M3/M4/M5 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. |
+| `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 entry accept <id>` | Accept a draft entry onto the Chain (commit to SSOT). |
+| `pb entry discard <id> [--reason <text>]` | Discard a draft or current entry; `--reason` is free text in its history note. |
+| `pb entry resolve <id> [--reason <text>]` | Resolve a current entry (moves to Past); `--reason` is free text in its history note. |
+| `pb session close` | Close session, show summary. |
 
-## `pb session` + `pb capture` — Close the Loop
+A checklist field (for example `doneWhen`) takes one item per flag: `pb capture "WP: title" -f doneWhen="first" -f doneWhen="second"`. The server mints the item ids. On `pb update` the flags replace the list; an item whose text is unchanged keeps its tick.
 
-The Chain compounds from every AI coding session. Instead of knowledge dying in chat transcripts (TEN-27), capture it as you work.
+### Profile Management
 
-### Flow
+Config is read from (in order): environment variables, `~/.config/productbrain/.env`, `.env.mcp` in the current directory.
 
 ```bash
-# Start of session
-pb session start          # opens session, refreshes context
+pb login          # Save API key
+pb doctor         # Verify configuration
+pb setup          # Guided first-time setup
+```
 
-# 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"
+### AI Developer Onboarding
 
-# End of session
-pb session close          # shows summary, runs wrapup, refreshes context
+```bash
+pb handshake      # Generate context files for Codex, Cursor, Claude, Copilot
 ```
 
-### How capture works
+Generates `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/chain.mdc`, `.productbrain/context.md`, and more.
 
-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
+## Output Modes
 
-### Options
+WP-744 / 1e-B: piping alone no longer switches modes — the human-readable card is the default
+in every shell, TTY or not. Ask for JSON explicitly.
 
-- `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
+| Context | Output |
+|---------|--------|
+| TTY (terminal) | Human-readable formatting |
+| Piped / non-TTY (no flag, `PB_JSON` unset) | Human-readable formatting |
+| `PB_JSON=1` | JSON |
+| `--json` | Force JSON |
+| `--pretty` | Force human-readable |
 
-### Governance
+## Reference
 
-- 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)
+- `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":""}