@bli-cockpit/cli 0.1.33 → 0.2.1

package/README.md

@@ -1,251 +1,168 @@
 # Cockpit CLI
 
-Public BLI Cockpit command-line interface for approved operators and interns.
+Cockpit watches how you and your AI agents work so Edward can coach from evidence instead of screenshots and status pings.
 
-The npm package is public; the Cockpit backend and admin tooling are not. The
-CLI pairs a local laptop with the private Cockpit dashboard, records safe
-work context, uploads consented raw Codex/Claude/diff evidence and explicit
-images attached into agent sessions to durable private storage, and uploads
-metadata refs after dashboard-approved
-device pairing.
+## 90-second speedrun
 
-## One-paste install
-
-Run this in a terminal. If you are inside `~/BLI`, Cockpit suggests that
-workspace root; otherwise it looks for likely roots such as `~/BLI` and asks
-before collecting. Later reruns remember the approved roots:
+Run these three commands on the Mac that should be collected:
 
 ```bash
-npm install -g @bli-cockpit/cli@latest
-cockpit onboard
+$ npm install -g @bli-cockpit/cli@latest
+added <packages> in <seconds>s
 ```
 
-Interactive onboarding prompts for the dashboard email. Enter the approved
-intern/operator email. For reused laptops, VMs, or headless/agent-run setup,
-pass the email and root explicitly:
-
 ```bash
-cockpit onboard --email <APPROVED_EMAIL> --workspace ~/BLI
+$ cockpit onboard
+Cockpit harvest onboarding
+Dashboard: https://bli-cockpit-dashboard.vercel.app
+Ticket: general ambient
+What's your @buildlaunchiterate.ca email? (press enter to skip): ian@buildlaunchiterate.ca
+Signing in as ian@buildlaunchiterate.ca.
+Code sent; valid 1h, resend in 60s by rerunning this command.
+Email code needed:
+  Check your latest Cockpit email for a 6- to 10-digit code.
+What you can do:
+  1) Paste the code here.
+  2) No code yet: wait for the resend window, then rerun this command.
+  3) Can't use email: rerun with --no-auth for manual approval.
+Code: 482913
+Signed in as ian@buildlaunchiterate.ca.
+2/5 Device paired.
+PASS: Cockpit collector is ready for harvest.
+You're live.
+Dashboard: https://bli-cockpit-dashboard.vercel.app/my-work
+Next: cockpit status
 ```
 
-If a work folder contains multiple repos, confirm the parent folder as the
-collection root. In a headless setup, pass it explicitly:
-
 ```bash
-npm install -g @bli-cockpit/cli@latest
-cockpit onboard --email <APPROVED_EMAIL> --workspace ~/BLI
+$ cockpit status
+Install: ready
+Auth: paired
+Upload state: ready
 ```
 
-For multiple unrelated collection roots, repeat `--workspace`:
+The OTP proves you own an approved BLI mailbox. The JWT is used once to register this device and is never saved; the durable local credential remains the existing Cockpit device token.
+
+## Every command, what it does, and why it's called that
+
+You only need three commands (`onboard`, `status`, and `backfill` once). The rest exist for
+recovery and maintenance.
+
+| Command | What it does | Why it exists / why this name |
+|---|---|---|
+| `cockpit onboard` | The everything-command: signs you in (email code), registers this Mac, starts capture, uploads once, installs the 15-min background sync, and prints proof you're live. | You are boarding the crew. Run it once per machine; rerunning is always safe. |
+| `cockpit status` | Prints install / sign-in / capture / upload health in one screen. | The "is it working?" command. Run it whenever you're unsure. |
+| `cockpit backfill --all` | Uploads your HISTORICAL Codex + Claude sessions (from before Cockpit existed on this Mac). | One-time catch-up so your past work counts too. "Backfill" = fill in the back-catalog. |
+| `cockpit sync` | Captures and uploads once, right now. This is what the background agent runs every 15 min — you almost never type it yourself. | Named for what it does: synchronize local session files up to the dashboard. |
+| `cockpit start --ticket <id>` | Tags your CURRENT work with a Linear ticket so sessions attribute to it. `--clear-ticket` returns to general capture. | "Start (working on) X." Agents usually run this for you per the agent rules. |
+| `cockpit login` / `cockpit pair` | Just the sign-in + device-registration step, standalone (onboard already includes it). Two names, one command: `login` is what humans guess, `pair` is what the dashboard's device screen calls it. | Recovery path when a session expires or you switch accounts. |
+| `cockpit logout` | Deletes this machine's session. | The undo of login. |
+| `cockpit update` / `cockpit upgrade` | Updates the CLI itself from npm, then reruns onboard. Two names, one command — aliases because half of people guess each. | Self-update; run when Edward announces a new version. |
+| `cockpit install` | Writes local config only (step 1 of onboard, standalone). | Plumbing; exists so onboard's pieces are individually runnable. You'll likely never type it. |
+| `cockpit sessions` | Read-only: lists your observed sessions and how each attributed. | Debugging "why isn't my session showing up?" without uploading anything. |
+| `cockpit autostart install\|uninstall\|status` | Manages the macOS launchd agent behind the 15-min background sync. | Direct control of the background piece when you need to stop/inspect it. |
+| `cockpit agent-rules install\|uninstall\|status` | Manages the Cockpit ticket-binding text block inside `~/.codex/AGENTS.md` / `~/.claude/CLAUDE.md`. | It's literally "the rules your agents read." Passive markdown — never an executable hook. |
+| `cockpit serve` | Runs a tiny local HTTP status server. | Niche: lets other tools ask the collector how it's doing. |
+| `cockpit logout`, `cockpit release`, `cockpit admin *` | `release` publishes the CLI (maintainer, repo-gated); `admin` (bootstrap/invite) is absent from the public build entirely. | Maintainer surface — interns never touch these. |
+
+Honest naming notes: `update`/`upgrade` and `login`/`pair` are deliberate synonym-aliases (cheap
+forgiveness beats a "command not found"); `install` is a misleading name for "write config" but
+is kept for onboard-step symmetry.
+
+## Flags
+
+Normal setup needs no flags. Use flags only when the default guess is wrong:
 
 ```bash
-cockpit onboard --email <APPROVED_EMAIL> --workspace ~/BLI --workspace ~/side-projects
+cockpit onboard --email <you@buildlaunchiterate.ca> --workspace ~/BLI
+cockpit onboard --workspace ~/BLI --workspace ~/side-projects
+cockpit onboard --device-name "Ian MacBook"
+cockpit onboard --no-auth
 ```
 
-The CLI defaults to the production dashboard. Normal intern/operator setup,
-updates, and syncs omit `--dashboard-url`. Pass `--dashboard-url` only for
-staging, a custom dashboard, or deliberately forcing a different dashboard
-pairing. Already-onboarded users update with `cockpit update` from anywhere. It
-installs the latest public CLI from npm, then reruns onboarding checks to
-refresh pairing, agent rules, autostart, and an initial sync against saved
-roots. `cockpit upgrade` is a compatibility alias. `--repo <path>` remains
-supported for older prompts and the agent ticket-binding guardrail.
-When onboarding reports archived local sessions without a completed backfill,
-follow [`docs/runbooks/cockpit-backfill.md`](../../docs/runbooks/cockpit-backfill.md):
-run `cockpit update`, then run `cockpit backfill --all` as a separate command.
-
-On machines where Codex or Claude agents will do ticketed work, `cockpit
-onboard` refreshes `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` after harvest
-proof. The managed Cockpit ticket-binding block is replaced in place rather
-than duplicated and is scoped to the confirmed root set, so agents should ignore
-it in private chats or unrelated repos.
-
-For intern machines, `cockpit onboard` refreshes the launchd autostart agent so
-Cockpit syncs confirmed roots at login and every 15 minutes. For a manual
-repair path, run `cockpit autostart install --workspace <root>` later.
+- `--email` skips the email prompt.
+- `--workspace` pins one collection root; repeat it for multiple unrelated roots.
+- `--allow-home-root` deliberately collects your whole home folder. Use it only on a company machine where that is intended.
+- `--device-name` changes only the human label shown in Cockpit.
+- `--dashboard-url` is for staging/custom dashboards only. Production is the default.
+- `--no-auth` forces the old manual approval queue.
+- `--repo` still works as a legacy alias for `--workspace`.
+
+`cockpit update` installs the latest public CLI and reruns onboarding checks against saved roots. `cockpit upgrade` is the same command.
+
+## Parent Mode
+
+Use a parent folder such as `~/BLI` when it contains multiple repos. Cockpit scans child git repos/worktrees, creates one stable work context per worktree, and rolls them up under repo rows in the dashboard.
+
+Defaults: 3 folder levels deep, up to 50 repos. Tune with `--max-depth` and `--max-repos`.
+
+## Pairing Recovery
+
+The v2 happy path auto-approves pairing after the email OTP. Manual approval still exists for recovery:
 
 ```bash
-# Repair/manual path.
-cockpit agent-rules install --workspace <root>
+cockpit onboard --no-auth --email <you@buildlaunchiterate.ca> --workspace ~/BLI
 ```
 
-The direct command updates `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` with
-the Cockpit rule to bind known Linear tickets before edits, or ask once when
-the ticket ID is missing inside that workspace. That binding starts attributing
-the session's work to the specific ticket in Cockpit. It checks for managed or
-equivalent guidance first, so current files are left unchanged and stale Cockpit
-ticket-binding sections are replaced.
-
-Parent mode scans child git repos/worktrees (3 folder levels deep, up to 50
-repos by default — tune with `--max-depth` / `--max-repos`; a warning prints
-if the repo cap truncates discovery), creates one stable work context per
-worktree, and the dashboard rolls them up under one repo row with worktree
-drilldown. Repos cloned later are picked up automatically: `cockpit sync`
-starts a general ambient work context for newly discovered repos on its own. Device approval is still one time per laptop/dashboard/email. Codex
-JSONL transcripts are attributed to a repo/worktree deterministically (session
-cwd, workspace roots, git origin/branch/commit signals) and upload only into
-that repo's evidence lane; transcripts that cannot be attributed to exactly one
-worktree are reported as ambiguous/unattributed with reason labels instead of
-being duplicated across repos or dropped.
-
-What happens:
-
-1. npm installs or updates the public `@bli-cockpit/cli` package.
-2. `cockpit onboard` writes local user config.
-3. Cockpit prints a dashboard pairing URL and code.
-4. Admin approves the persistent email access request from Ambient -> Collector
-   approvals. Pair codes still expire, but the access request remains. If the
-   terminal is still polling, approval pairs it immediately; if not, the intern
-   reruns `cockpit onboard --email <APPROVED_EMAIL> --workspace ~/BLI` or
-   simply `cockpit onboard` after roots are saved, and the stored approval
-   auto-pairs without another Admin action. Admin can still paste the printed
-   code there as a rescue path. The signed-in intern can still use the printed
-   URL. If the claimed email is not an app user yet, a super admin approval
-   creates the user, adds team membership, and sends the Supabase invite flow
-   automatically.
-5. The CLI starts general ambient capture, uploads private raw evidence objects
-   when present (chunked and resumable, with identical content acknowledged
-   instead of re-uploaded), then uploads one safe metadata/ref envelope. Text
-   evidence with secret-shaped values is sanitized before storage and marked as
-   partial evidence with redaction metadata; env files are still never read.
-6. The CLI prints `PASS: Cockpit collector is ready for harvest.` and a final
-   `You're live.` block with collection roots, pairing state, background sync
-   state, dashboard link, and `cockpit status` as the next command.
-
-`--device-name` is optional and only a readable label in Cockpit. Pass it only
-when you want a specific label such as `"Savina MacBook"` or `"Box VM 42"`.
-On reused laptops or VMs, keep `--email <APPROVED_EMAIL>` in the command.
-`cockpit onboard` skips pairing only when the existing valid session belongs to
-that same email and dashboard URL (the production default unless overridden); a
-different email or dashboard forces a new approval.
-
-Before the command runs, an Admin does not need to open Supabase or pre-create
-ordinary interns in Settings -> Team. Approval of the claimed email in Ambient
-creates the missing app user and stores the durable access approval. Settings
--> Team remains available for manual pre-provisioning, including
-temporary-password launch. For temporary-password accounts, the intern signs in
-directly; there is no separate invite acceptance step.
-
-When ticket work starts later:
+Use that when the mailbox is unavailable, auth routes are down, or Edward has added an exact non-domain email exception. Cockpit prints a URL and code; Admin approves from Ambient -> Collector approvals. If the code expires, rerun `cockpit onboard` after approval and the durable access row will auto-pair.
 
-```bash
-cockpit start \
-  --ticket <ticket-id> \
-  --workspace "$PWD"
+If this is a reused laptop or VM, keep `--email` set. Cockpit reuses an existing session only when it belongs to that same email and dashboard URL.
 
-cockpit sync \
-  --workspace "$PWD" \
-  --json
-```
+## Ticket Semantics
+
+Setup is general ambient capture. Do not invent a ticket for onboarding.
 
-No ticket is required for setup, chatting, planning, or general ambient capture.
-Only pass `--ticket` when the work really belongs to a visible ticket.
-Omitting `--ticket` preserves any existing ticket binding; run
-`cockpit start --clear-ticket --workspace "$PWD"` when you intentionally want
-to return a previously bound work context to general ambient capture.
+When real ticket work starts:
 
-When the work is important but ticketless, label it explicitly before syncing so
-later analysis does not have to guess the topic:
+```bash
+cockpit start --ticket <ticket-id> --workspace "$PWD"
+cockpit sync --workspace "$PWD" --json
+```
+
+For important ticketless work:
 
 ```bash
 cockpit start \
   --workspace "$PWD" \
-  --topic "lead ingestion rewrite planning" \
+  --topic "lead ingestion planning" \
   --intent planning \
   --phase discovery \
   --intent-confidence 0.9
-
-cockpit sync \
-  --workspace "$PWD" \
-  --json
 ```
 
-Supported `--intent` values are `implementation`, `bug_fix`,
-`root_cause_analysis`, `planning`, `discovery`, `review`, `testing`,
-`documentation`, `release`, `learning`, `coordination`, `maintenance`,
-`analysis`, `unknown`, and `other`. Supported `--phase` values are `planning`,
-`discovery`, `implementation`, `debugging`, `review`, `testing`,
-`documentation`, `release`, `handoff`, `analysis`, `unknown`, and `other`.
-Use `--topic-summary` only for short redacted summaries, not transcript text.
+`cockpit onboard` also refreshes managed ticket-binding guidance in `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` so agents bind visible Linear tickets before edits inside the confirmed workspace.
 
-## What gets saved
+## Storage Layout
 
 Local files:
 
-- `~/.config/bli-cockpit/config.json`: dashboard URL (production default unless
-  overridden) and local install config.
-- `~/.config/bli-cockpit/session.json`: normal paired device session.
-- `~/.local/state/bli-cockpit/spool/`: safe retry records when upload fails.
-- `~/.local/state/bli-cockpit/cursors/raw-evidence.json`: hashes and labels of
-  already-durable evidence so repeated syncs skip re-uploading the same
-  content (no raw content is stored in the cursor).
-- `~/.local/state/bli-cockpit/cursors/backfill.json`: high-water progress for
-  the explicit `cockpit backfill` command.
-- `.codex-autorunner/contextspace/active_context.md` in the work repo when a
-  work context is active.
-
-Remote dashboard:
-
-- approved user and device identity;
-- repo/worktree fingerprints, branch, head SHA, optional ticket, source
-  availability, risk flags, and upload timestamps;
-- raw evidence refs accepted by `/api/ambient/ingest`;
-- durable private Storage objects accepted by the chunked
-  `/api/ambient/evidence/upload/begin|chunk|commit` endpoints, tracked in a
-  durable per-object upload ledger. When deterministic sanitization was
-  applied, the evidence ref stores the redaction metadata and sanitized object
-  hash/size;
-- attached image artifact metadata accepted by `/api/ambient/agent-artifacts`
-  for screenshots/images explicitly attached into Codex or Claude sessions;
-- Codex session attribution records (session id, file hash, attribution state
-  and reason labels, scores) accepted by `/api/ambient/codex-sessions`.
-  The local collector scans both active `~/.codex/sessions` files and archived
-  `~/.codex/archived_sessions` files, using only `session_meta` and
-  `turn_context` metadata for attribution. Transcript bytes are sanitized or
-  blocked later by raw evidence collection before upload.
-
-New raw evidence object keys are readable from the Storage browser:
-
-```text
-operators/<operator-slug>-<operator-short>/repos/<repo-slug>/worktrees/<worktree-slug>/tickets/<ticket-id-or-unbound>/dates/<YYYY-MM-DD>/sessions/<session-slug>/ids/<operator_user_id>/<work_context_id>/<source>/<source-path>
-```
+- `~/.config/bli-cockpit/config.json`: dashboard URL, device label, collection roots.
+- `~/.config/bli-cockpit/session.json`: paired device token and owner metadata.
+- `~/.local/state/bli-cockpit/spool/`: safe retry records.
+- `~/.local/state/bli-cockpit/cursors/`: upload/backfill cursors, no raw content.
+- `.codex-autorunner/contextspace/active_context.md`: current work context inside a repo.
 
-The readable folders are for humans. The canonical join still lives in
-`ambient_evidence_refs.raw_evidence_pointer_id`, `storage_bucket`, and
-`object_key`. For SQL recipes that reconstruct a day of work by operator, date,
-repo, ticket, and raw JSONL object, see
-[`docs/runbooks/cockpit-data-traceability.md`](../../docs/runbooks/cockpit-data-traceability.md).
+Remote data:
 
-## Read or debug captured data
+- approved user/device identity;
+- repo/worktree fingerprints, branch, head SHA, optional ticket, source counts;
+- private raw evidence objects and `ambient_evidence_refs` pointers;
+- Codex/Claude session attribution metadata.
 
-Local attribution preview:
+Never provide service-role keys, raw DB URLs, cookies, root env files, or deployment tokens to this CLI. The collector never reads env files and does not collect random desktop screenshots or screen recordings.
+
+## Debug
 
 ```bash
 cockpit sessions --workspace "$PWD" --json
+cockpit status --workspace "$PWD" --json
+cockpit sync --workspace "$PWD" --json
 ```
 
-This preview includes both active and archived Codex sessions in the bounded
-scan window, plus Claude Code sessions when Claude collection is enabled. Use
-`--since-days N` or `--all` when debugging older local history.
-
-Remote metadata path:
+If `cockpit update` fails with npm `EACCES`, fix Homebrew global-package ownership once:
 
-1. Query `ambient_evidence_refs` by `operator_user_id`, `received_at`, and
-   optional `ticket_id`.
-2. Join `ambient_work_sessions` only for current labels such as repo, worktree,
-   branch, and collector version.
-3. Open the `ambient-raw-evidence` object only after SQL identifies the exact
-   row and `object_key`.
-
-Never provide Supabase service-role keys, raw DB URLs, root env files, cookies,
-or deployment tokens to this CLI. The collector must never read env files and
-does not collect random desktop screenshots or screen recordings.
-
-## Public package boundary
+```bash
+sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit
+```
 
-This public package intentionally excludes Cockpit admin bootstrap commands,
-service-role credential handling, source maps, tests, and internal runbooks.
-Clean `npm pack` and `npm publish` run the public CLI build before packaging so
-`dist/cli.js` is present in emergency releases.
-When collector changes depend on new telemetry-core exports, publish
-`@bli-cockpit/telemetry-core` first, then publish `@bli-cockpit/cli`.
+Do not use `sudo npm i -g`; it recreates the ownership problem.

package/dist/commands/local-args.js

@@ -56,10 +56,12 @@ function parseOnboardLikeArgs(args, command) {
             "--ticket",
             "--branch",
             "--json",
+            "--no-auth",
             "--poll-interval-ms",
             "--timeout-ms",
             "--max-depth",
             "--max-repos",
+            "--allow-home-root",
         ],
         valueFlags: [
             "--home",
@@ -87,11 +89,13 @@ function parseOnboardLikeArgs(args, command) {
         deviceName: optionalNonEmpty(values.flags.get("--device-name")),
         activeTicketId: optionalNonEmpty(values.flags.get("--ticket")),
         branch: optionalNonEmpty(values.flags.get("--branch")),
+        noAuth: values.booleans.has("--no-auth"),
         json: values.booleans.has("--json"),
         pollIntervalMs: optionalPositiveInteger(values.flags.get("--poll-interval-ms"), "--poll-interval-ms"),
         timeoutMs: optionalPositiveInteger(values.flags.get("--timeout-ms"), "--timeout-ms"),
         maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
         maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
+        allowHomeRoot: values.booleans.has("--allow-home-root"),
     };
 }
 function parseOnboardArgs(args) {
@@ -113,6 +117,7 @@ function parseInstallArgs(args) {
             "--dashboard-url",
             "--supabase-url",
             "--json",
+            "--allow-home-root",
         ],
         valueFlags: [
             "--home",
@@ -130,6 +135,7 @@ function parseInstallArgs(args) {
         dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
         supabaseUrl: optionalNonEmpty(values.flags.get("--supabase-url")),
         json: values.booleans.has("--json"),
+        allowHomeRoot: values.booleans.has("--allow-home-root"),
     };
 }
 function parseReleaseArgs(args) {
@@ -164,6 +170,7 @@ function parseLoginArgs(args) {
             "--email",
             "--device-name",
             "--json",
+            "--no-auth",
             "--poll-interval-ms",
             "--timeout-ms",
         ],
@@ -184,6 +191,7 @@ function parseLoginArgs(args) {
         claimedOwnerEmail: optionalEmail(values.flags.get("--email")),
         deviceName: optionalNonEmpty(values.flags.get("--device-name")),
         json: values.booleans.has("--json"),
+        noAuth: values.booleans.has("--no-auth"),
         pollIntervalMs: optionalPositiveInteger(values.flags.get("--poll-interval-ms"), "--poll-interval-ms"),
         timeoutMs: optionalPositiveInteger(values.flags.get("--timeout-ms"), "--timeout-ms"),
     };