@bli-cockpit/cli 0.1.11 → 0.1.12

package/README.md

@@ -15,8 +15,8 @@ Run this from the repo where work will happen:
 
 ```bash
 COCKPIT_DEVICE_NAME="$(scutil --get ComputerName 2>/dev/null || hostname -s)"
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit onboard \
-  --dashboard-url <DASHBOARD_URL> \
+npm install -g @bli-cockpit/cli@latest
+cockpit onboard \
   --email <APPROVED_EMAIL> \
   --device-name "$COCKPIT_DEVICE_NAME" \
   --repo "$PWD"
@@ -27,13 +27,20 @@ If a work folder contains multiple repos, run the same command from the parent:
 ```bash
 cd ~/Downloads/bluepearl-workspace
 COCKPIT_DEVICE_NAME="$(scutil --get ComputerName 2>/dev/null || hostname -s)"
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit onboard \
-  --dashboard-url <DASHBOARD_URL> \
+npm install -g @bli-cockpit/cli@latest
+cockpit onboard \
   --email <APPROVED_EMAIL> \
   --device-name "$COCKPIT_DEVICE_NAME" \
   --repo "$PWD"
 ```
 
+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
+`npm install -g @bli-cockpit/cli@latest`, then run
+`cockpit sync --repo "$PWD" --json`.
+
 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
@@ -48,7 +55,7 @@ being duplicated across repos or dropped.
 
 What happens:
 
-1. npm downloads the public `@bli-cockpit/cli` package.
+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 pending request from Ambient -> Collector approvals, or
@@ -63,8 +70,8 @@ What happens:
 `"Savina MacBook"`, `"Box VM 42"`, or the auto-filled macOS computer name.
 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; a different email or dashboard forces a new
-approval.
+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 must create or approve the email in the
 private dashboard. Default launch path is email + temporary password, handed
@@ -75,12 +82,11 @@ separate invite acceptance step.
 When ticket work starts later:
 
 ```bash
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit start \
+cockpit start \
   --ticket <ticket-id> \
   --repo "$PWD"
 
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit sync \
-  --dashboard-url <DASHBOARD_URL> \
+cockpit sync \
   --repo "$PWD" \
   --json
 ```
@@ -92,7 +98,8 @@ Only pass `--ticket` when the work really belongs to a visible ticket.
 
 Local files:
 
-- `~/.config/bli-cockpit/config.json`: dashboard URL and local install config.
+- `~/.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

package/dist/autostart.js

@@ -128,7 +128,10 @@ async function existingWatchPaths(homeDir) {
 function renderPlist(options) {
     // The repo path is shell-quoted because it lands inside a `/bin/zsh -lc "…"`
     // command string; the whole command is then XML-escaped for the <string>.
-    const command = `npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit sync --repo ${shellQuote(options.workDir)} --dashboard-url ${shellQuote(options.dashboardUrl)} --json`;
+    const dashboardArg = options.dashboardUrl === DEFAULT_DASHBOARD_URL
+        ? ""
+        : ` --dashboard-url ${shellQuote(options.dashboardUrl)}`;
+    const command = `cockpit sync --repo ${shellQuote(options.workDir)}${dashboardArg} --json`;
     return [
         '<?xml version="1.0" encoding="UTF-8"?>',
         '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',

package/dist/commands/local.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { createCollectorServer } from "../server.js";
 import { parseLocalArgs, normalizeUrl } from "./local-args.js";
 import { autostartStatus, installAutostartAgent, uninstallAutostartAgent } from "../autostart.js";
-import { getCollectorRuntimePaths, inspectLocalCollectorStatus, installLocalCollector, logoutLocalCollector, pairLocalCollector, readLocalCollectorSessionFile, readLocalSessionReference, startLocalWorkContext } from "../local-state.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, inspectLocalCollectorStatus, installLocalCollector, logoutLocalCollector, pairLocalCollector, readLocalCollectorSessionFile, readLocalSessionReference, startLocalWorkContext } from "../local-state.js";
 import { scanAndAttributeCodexSessions } from "../adapters/codex-attribution.js";
 import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
 import { acquireSyncLock } from "../sync-lock.js";
@@ -82,6 +82,8 @@ export function localCommandHelp(command) {
         "  cockpit sessions [--source codex|claude] [--repo <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit serve [--port <port>] [--repo <path>]",
         "  cockpit autostart [install|uninstall|status] [--repo <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+        "",
+        `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
     ].join("\n");
 }
 function localSubcommandHelp(command) {
@@ -93,6 +95,8 @@ function localSubcommandHelp(command) {
                 "",
                 "Installs, pairs, starts work context(s), syncs once, and prints readiness proof.",
                 "If --repo is a parent folder, scans child git repos/worktrees and rolls them up by repo.",
+                `Omit --dashboard-url for normal production setup (${DEFAULT_DASHBOARD_URL}).`,
+                "Pass --dashboard-url only for staging/custom dashboards or to force a different pairing.",
                 "Run with no flags in a terminal and it prompts for the dashboard email; pass --email to skip the prompt (and on shared/reused machines, where mismatched sessions are re-paired).",
             ],
         ],
@@ -102,6 +106,7 @@ function localSubcommandHelp(command) {
                 "Usage: cockpit install [--dashboard-url <url>] [--repo <path>] [--json]",
                 "",
                 "Writes local collector config. Pair with `cockpit login`, then run `cockpit start` when work begins.",
+                "Omit --dashboard-url for the production dashboard; pass it only for staging/custom dashboards.",
             ],
         ],
         [
@@ -110,6 +115,7 @@ function localSubcommandHelp(command) {
                 "Usage: cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--json]",
                 "",
                 "Starts dashboard device pairing and stores the approved local session.",
+                "Omit --dashboard-url for the production dashboard; pass it only for staging/custom dashboards.",
             ],
         ],
         [
@@ -136,6 +142,7 @@ function localSubcommandHelp(command) {
                 "Usage: cockpit sync [--repo <path>] [--dashboard-url <url>] [--json]",
                 "",
                 "Uploads latest local ambient envelope(s), or spools safe retries if blocked.",
+                "Omit --dashboard-url for normal production sync; pass it only for staging/custom dashboards or forced re-pairing.",
                 "Parent folders sync each child git worktree; Codex AND Claude Code JSONL",
                 "transcripts (and Claude subagent sidecars) are attributed to repos",
                 "deterministically and ambiguous transcripts are retained as unattributed",
@@ -181,6 +188,7 @@ function localSubcommandHelp(command) {
                 "Installs a macOS launchd LaunchAgent that runs `cockpit sync` at login and",
                 "every 30 min (default), surviving reboots — so machines never drift to Stale.",
                 "Action defaults to `install`. `--repo` is the parent work folder to sync.",
+                "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
                 "macOS-only for now; see docs/runbooks/cockpit-launchd-sync.md.",
             ],
         ],

package/dist/commands/public-root.js

@@ -22,7 +22,10 @@ function cockpitHelp() {
     "Usage:",
     localCommandHelp(),
     "",
+    "Install/update: `npm install -g @bli-cockpit/cli@latest`.",
     "Intern path: run `cockpit onboard` from the repo root; add `--ticket <id>` only when work already has a ticket.",
+    "Already onboarded: run `cockpit sync --repo \"$PWD\" --json`.",
+    "Dashboard URL is optional for normal production use; pass `--dashboard-url` only for staging/custom dashboards or forced re-pairing.",
     "Manual collector path: `install`, `login`, `start [--ticket <id>]`, `sync`, `status`.",
   ].join("\n");
 }

package/dist/upload.js

@@ -19,7 +19,7 @@ export async function buildLocalAmbientEnvelope(options = {}) {
     const now = options.now ?? new Date();
     const paths = getCollectorRuntimePaths(options.homeDir);
     const config = await readLocalCollectorConfig(paths).catch(() => {
-        throw new LocalUploadBlockedError("not_installed", "Local collector config missing. Run `cockpit install` before `cockpit sync`.", "cockpit install --dashboard-url <dashboard-url>");
+        throw new LocalUploadBlockedError("not_installed", "Local collector config missing. Install/update the CLI, then run `cockpit onboard` before `cockpit sync`.", "npm install -g @bli-cockpit/cli@latest && cockpit onboard --email <email> --repo \"$PWD\"");
     });
     const sessionFile = await readLocalCollectorSessionFile(paths).catch(() => {
         throw new LocalUploadBlockedError("unpaired", "No paired collector session found. Run `cockpit login` or `cockpit pair` before `cockpit sync`.", "cockpit login");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "private": false,
   "type": "module",
   "bin": {