zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/main.py

@@ -0,0 +1,2534 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import difflib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from datetime import date, datetime
+from pathlib import Path
+
+from zeno_core import (
+    SessionPoint,
+    StreakResult,
+    fit_babysitting_tax_curve,
+    has_logged_today,
+    read_streak_from_local_storage,
+    render_curve_ascii,
+    render_weekly_table,
+    save_curve_png,
+    weekly_summary,
+)
+from zeno_core.rtlx_s import RTLXS_AUTONOMY_CONDITIONS, run_rtlxs_survey_tui
+from zeno_sdk import Zeno, auth
+from zeno_sdk._generated.client import ApiError, ZenoApiClient
+
+from .doctor import (
+    STATUS_FAIL,
+    STATUS_PASS,
+    STATUS_WARN,
+    doctor_exit_code,
+    run_doctor,
+)
+from .version import version_string
+
+DEFAULT_API_BASE_URL = os.environ.get(
+    "ZENO_API_BASE_URL", "https://zeno-api-364453955482.us-west1.run.app"
+)
+
+# Default dashboard CLI-authorize bridge for `zeno login`. Canonical copy lives
+# in zeno_cli.login.DEFAULT_AUTHORIZE_URL; duplicated here (same env var) so the
+# hot `zeno status` path - which builds the full parser - does not have to
+# import the login module (http.server / webbrowser) just to set a default.
+DEFAULT_AUTHORIZE_URL = os.environ.get(
+    "ZENO_LOGIN_AUTHORIZE_URL", "https://app.zeno.center/cli/authorize"
+)
+
+
+def resolve_api_token() -> str | None:
+    """Resolve the API bearer token, env override first, then the OS keyring.
+
+    ZENO_API_TOKEN wins so existing overrides + tests keep working as-is.
+    Otherwise fall back to the Clerk JWT stored by `zeno login`
+    (zeno_sdk.auth keyring). Returns None when neither is set (free-tier /
+    not logged in), which callers treat as "local-only / offline".
+    """
+    token = os.environ.get("ZENO_API_TOKEN")
+    if token:
+        return token
+    return auth.get_token()
+
+
+# Default location of the cognitive-state cache mirror written by the API
+# (see apps/api/src/zeno_api/cognitive_state.py). Read by `zeno status`
+# and `zeno doctor`; tunable via ZENO_HOME just like the SQLite DB.
+DEFAULT_COGNITIVE_STATE_CACHE = (
+    Path(os.environ.get("ZENO_HOME", str(Path.home() / ".zeno"))).expanduser()
+    / "cognitive-state.json"
+)
+
+# Default location of the local SQLite DB (matches packages/sdk-python/config.py).
+# Doctor uses this directly so it can probe before the SDK is initialized.
+DEFAULT_DB_PATH = Path(
+    os.environ.get(
+        "ZENO_DB_PATH",
+        str(Path(os.environ.get("ZENO_HOME", str(Path.home() / ".zeno"))).expanduser() / "zeno.db"),
+    )
+).expanduser()
+
+# Daily-rotating tip pool. Index = day-of-year % len(TIPS). Keep tips short,
+# action-verb-first, focused on free-tier value (local measurement + the curve).
+TIPS: tuple[str, ...] = (
+    "Run a survey after every coding session: 'zeno survey'. The RTLX-S 5-item probe "
+    "calibrates your supervision-vs-execution split faster than passive logging.",
+    "Check 'zeno curve' once a week to see where your babysitting tax kicks in. "
+    "Optimal-N drops by 1 agent every time it shifts; act on it.",
+    "Open the dashboard for weekly trends - 'zeno weekly' prints a digest, but "
+    "the dashboard at zeno.center plots quality decay across runs.",
+)
+
+
+def _color(text: str, code: str, *, enabled: bool) -> str:
+    """Wrap text in an ANSI color code, no-op if colors are disabled."""
+    if not enabled:
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+
+def _colors_enabled() -> bool:
+    """Match the rich convention: respect NO_COLOR; default on for ttys."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    return True
+
+
+def _print(text: str = "") -> None:
+    """Plain print. Kept as a seam so rich-based output can be swapped in if
+    the env has rich available.
+
+    rich's `print` interprets ``[...]`` as console-markup tags, so bracketed
+    status labels (``[dry-run]``, ``[high-intent, signed: ...]``) get silently
+    eaten before reaching the terminal. Every call site here emits plain text,
+    never rich markup, so we escape the literal first: the bracket survives to
+    the terminal instead of being parsed as a tag. This function applies no
+    color itself - it is a plain-text seam, not a styling layer."""
+    try:
+        from rich import print as rprint
+        from rich.markup import escape
+
+        rprint(escape(text))
+    except ImportError:
+        print(text)
+
+
+# Top-level subcommand verbs, kept as the single source of truth for the
+# "did you mean" suggester and the shell-completion generator. Mirrors the
+# choices registered on the subparsers below; keep in sync by hand (cheap).
+TOP_LEVEL_COMMANDS: tuple[str, ...] = (
+    "survey",
+    "report",
+    "curve",
+    "weekly",
+    "status",
+    "tips",
+    "onboard",
+    "doctor",
+    "version",
+    "billing",
+    "ingest",
+    "usage",
+    "metrics",
+    "hook",
+    "hud",
+    "email",
+    "outreach",
+    "completion",
+)
+
+
+class _ZenoArgumentParser(argparse.ArgumentParser):
+    """argparse parser that turns the wall-of-text 'invalid choice' error into
+    an actionable one-liner: a 'did you mean X?' suggestion (difflib) plus a
+    pointer to the grouped index. The default argparse message dumps the full
+    choice list with no nearest-match hint, which is poor UX for a typo."""
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        typo = _extract_invalid_choice(message)
+        if typo is not None:
+            suggestion = _closest_command(typo)
+            lines = [f"zeno: unknown command '{typo}'."]
+            if suggestion:
+                lines.append(f"  Did you mean '{suggestion}'?")
+            lines.append("  Run 'zeno' for the command index or 'zeno --help' for full usage.")
+            print("\n".join(lines), file=sys.stderr)
+            raise SystemExit(2)
+        # Fall back to argparse's default for everything else (missing required
+        # subcommand args, bad flags, etc.).
+        super().error(message)
+
+
+def _extract_invalid_choice(message: str) -> str | None:
+    """Pull the offending token out of argparse's 'invalid choice: 'X'' message
+    for the top-level command argument only (nested subparsers keep the default
+    error, which already names their own choices)."""
+    marker = "argument command: invalid choice: '"
+    if marker not in message:
+        return None
+    rest = message.split(marker, 1)[1]
+    end = rest.find("'")
+    return rest[:end] if end != -1 else None
+
+
+def _closest_command(token: str) -> str | None:
+    """Nearest top-level command to a typo, or None if nothing is close."""
+    matches = difflib.get_close_matches(token, TOP_LEVEL_COMMANDS, n=1, cutoff=0.5)
+    return matches[0] if matches else None
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _ZenoArgumentParser(prog="zeno")
+    parser.add_argument(
+        "--no-probes",
+        action="store_true",
+        help="Disable probe prompts and log skips.",
+    )
+    # Top-level --version is the universal CLI convention (git/curl/gh).
+    # Mirror it as `zeno version` further down for callers who prefer the
+    # subcommand shape (doctl, fly, kubectl all expose both).
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"zeno {version_string()}",
+    )
+
+    # Subparsers intentionally NOT required: bare `zeno` defaults to `zeno
+    # status`. Matches the gh / doctl / fly convention where the zero-arg
+    # surface is a fast "where am I" view, not a usage error. See research
+    # prompt #24 (RESEARCH_PROMPTS_2026-06-07.md).
+    subparsers = parser.add_subparsers(dest="command")
+    survey = subparsers.add_parser(
+        "survey",
+        help="Run RTLX-S 5-item probe and store response.",
+    )
+    survey.add_argument("--project", default="default-project", help="Project identifier.")
+    survey.add_argument("--harness", default="cli", help="Harness name for session tracking.")
+    survey_condition = survey.add_mutually_exclusive_group()
+    survey_condition.add_argument(
+        "--autonomy",
+        choices=list(RTLXS_AUTONOMY_CONDITIONS),
+        default=None,
+        help=(
+            "Randomized SCED condition for this session (high_autonomy / "
+            "low_autonomy / control). Assign per your pre-registered schedule. "
+            "Stores the condition in the clear - use --sced for the blinded v2 flow."
+        ),
+    )
+    survey_condition.add_argument(
+        "--sced",
+        action="store_true",
+        help=(
+            "Blinded SCED mode (rating-time concealment, pre-reg Section 12): never "
+            "shows or stores the condition, randomizes item order, and asks a forced "
+            "condition guess + confidence after the load items. Use with --sced-index; "
+            "dotfiles/scripts/sced-next.sh sets this and seals the true condition."
+        ),
+    )
+    survey.add_argument(
+        "--sced-index",
+        type=int,
+        default=None,
+        dest="sced_index",
+        help="Locked-schedule slot (1-indexed) for a --sced blinded session.",
+    )
+
+    report = subparsers.add_parser("report", help="Print the last-session summary.")
+    report.add_argument("--project", default="default-project", help="Project identifier.")
+
+    curve = subparsers.add_parser("curve", help="Render Babysitting Tax curve and save PNG.")
+    curve.add_argument("--project", default="default-project", help="Project identifier.")
+    curve.add_argument(
+        "--png",
+        default="zeno-curve.png",
+        help="Path to save curve PNG.",
+    )
+
+    weekly = subparsers.add_parser("weekly", help="Print weekly digest summary.")
+    weekly.add_argument("--project", default="default-project", help="Project identifier.")
+
+    status = subparsers.add_parser(
+        "status",
+        help="Print a one-screen summary: tier, last session, calibration state.",
+    )
+    status.add_argument("--project", default="default-project", help="Project identifier.")
+    status.add_argument(
+        "--base-url",
+        default=DEFAULT_API_BASE_URL,
+        help="Zeno API base URL (default: ZENO_API_BASE_URL or https://zeno-api-364453955482.us-west1.run.app).",
+    )
+
+    subparsers.add_parser(
+        "tips",
+        help="Print a daily-rotating tip about getting more value out of zeno.",
+    )
+
+    # zeno onboard: the one-command fast-path for a new dogfooder. Orchestrates
+    # `hook install` + `hud install` + `doctor` end-to-end (idempotent, --dry-run,
+    # off-tailnet safe), then prints a BLUF summary. See onboard.py.
+    onboard = subparsers.add_parser(
+        "onboard",
+        help="One command to set up a fresh dogfooder: capture hook + HUD + doctor.",
+    )
+    onboard.add_argument(
+        "--base-url",
+        default=DEFAULT_API_BASE_URL,
+        help="Zeno API base URL (default: ZENO_API_BASE_URL or https://zeno-api-364453955482.us-west1.run.app).",
+    )
+    onboard.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print exactly what would change; write nothing.",
+    )
+    onboard.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace an existing non-zeno statusLine with the zeno line.",
+    )
+    onboard.add_argument(
+        "--settings-path",
+        default=None,
+        help="Override settings.json (default resolves symlinks to settings.local.json).",
+    )
+    onboard.add_argument(
+        "--ccstatusline-path",
+        default=None,
+        help="Override the ccstatusline settings.json path.",
+    )
+
+    # zeno doctor: one-shot diagnostic. Mirrors brew/rustup/gh's UX -
+    # operator hits this when something feels off and gets a colored,
+    # row-per-check report + a non-zero exit when a hard dep is broken.
+    doctor = subparsers.add_parser(
+        "doctor",
+        help="Run diagnostic checks against the local install + API.",
+    )
+    doctor.add_argument(
+        "--base-url",
+        default=DEFAULT_API_BASE_URL,
+        help="Zeno API base URL (default: ZENO_API_BASE_URL or https://zeno-api-364453955482.us-west1.run.app).",
+    )
+
+    # zeno version: dual to top-level --version. Mar's muscle memory may
+    # reach for the subcommand (kubectl style) before the flag, and the
+    # generated SDK + git SHA make the output worth keeping verbatim.
+    subparsers.add_parser(
+        "version",
+        help="Print zeno-cli version + git SHA when available.",
+    )
+
+    # Account: authenticate the CLI against Clerk so the API attributes requests
+    # per user. `login` runs a browser + loopback flow (state-CSRF, no PKCE) and stores the
+    # Clerk JWT in the OS keyring; `logout` clears it; `whoami` echoes the
+    # identity the API sees. The dashboard `/cli/authorize` bridge that mints the
+    # token is a documented follow-up (see login.py); --authorize-url + the
+    # ZENO_LOGIN_AUTHORIZE_URL env make it injectable for testing pre-bridge.
+    login_p = subparsers.add_parser(
+        "login",
+        help="Authenticate the CLI via the browser; store the token in the OS keyring.",
+    )
+    login_p.add_argument(
+        "--authorize-url",
+        default=DEFAULT_AUTHORIZE_URL,
+        help=(
+            "Dashboard CLI-authorize bridge URL (default: ZENO_LOGIN_AUTHORIZE_URL "
+            "or https://app.zeno.center/cli/authorize)."
+        ),
+    )
+    login_p.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Print the authorize URL instead of opening a browser (SSH / headless).",
+    )
+
+    subparsers.add_parser(
+        "logout",
+        help="Clear the stored Clerk token from the OS keyring.",
+    )
+
+    whoami_p = subparsers.add_parser(
+        "whoami",
+        help="Show the identity + tier the API attributes to the stored token.",
+    )
+    whoami_p.add_argument(
+        "--base-url",
+        default=DEFAULT_API_BASE_URL,
+        help="Zeno API base URL (default: ZENO_API_BASE_URL or https://zeno-api-364453955482.us-west1.run.app).",
+    )
+
+    # Billing subcommands hit the public Stage 1 follow-up endpoints
+    # (recommend-tier + preview-checkout). No auth, no Stripe round-trip -
+    # they read the API's configured tier catalog. Useful for sanity-checking
+    # which Stripe SKUs are wired and what each tier resolves to.
+    billing = subparsers.add_parser("billing", help="Inspect Stage 1 billing catalog.")
+    billing_sub = billing.add_subparsers(dest="billing_command", required=True)
+
+    recommend = billing_sub.add_parser(
+        "recommend-tier", help="Recommend the cheapest tier for N engineers."
+    )
+    recommend.add_argument("--engineers", type=int, default=1, help="Engineer count.")
+    recommend.add_argument(
+        "--base-url",
+        default=DEFAULT_API_BASE_URL,
+        help="Zeno API base URL (default: ZENO_API_BASE_URL or https://zeno-api-364453955482.us-west1.run.app).",
+    )
+
+    preview = billing_sub.add_parser(
+        "preview-tier", help="Show the configured Stripe price for (tier, period)."
+    )
+    preview.add_argument(
+        "--tier",
+        choices=["pro"],
+        default="pro",
+    )
+    preview.add_argument(
+        "--period",
+        choices=["monthly", "annual"],
+        default="monthly",
+    )
+    preview.add_argument(
+        "--base-url",
+        default=DEFAULT_API_BASE_URL,
+        help="Zeno API base URL (default: ZENO_API_BASE_URL or https://zeno-api-364453955482.us-west1.run.app).",
+    )
+
+    # Session-intelligence folded in from the standalone zeno-ingest / zeno-usage
+    # entry points. Thin pass-through wrappers: add_help=False + REMAINDER so all
+    # args (incl. --help) forward verbatim to the sub-CLI, which owns parsing and
+    # the --write-live live-DB guard. Lazy-imported in the handler.
+    ingest = subparsers.add_parser(
+        "ingest",
+        help="Ingest coding-agent transcripts into the local capture DB (zeno-ingest).",
+        add_help=False,
+    )
+    ingest.add_argument(
+        "ingest_args",
+        nargs=argparse.REMAINDER,
+        help="forwarded to zeno-ingest (--tools, --db, --write-live, ...); try 'ingest --help'.",
+    )
+
+    usage = subparsers.add_parser(
+        "usage",
+        help="Session-intelligence rollups + full-text search over transcripts (zeno-usage).",
+        add_help=False,
+    )
+    usage.add_argument(
+        "usage_args",
+        nargs=argparse.REMAINDER,
+        help="forwarded to zeno-usage: --search, --limit, --db, ... (try 'usage --help').",
+    )
+
+    # Metrics: emit a usage event to the Stage 1.5 meter (POST /v1/usage/emit).
+    # Paid-tier endpoint; the API records what the caller asserts (event_type +
+    # credits + optional metadata). Downstream rollups compute P90 / margin
+    # erosion / the customer usage dashboard. See PLAN.md track #7.
+    metrics = subparsers.add_parser("metrics", help="Emit usage events to the meter.")
+    metrics_sub = metrics.add_subparsers(dest="metrics_command", required=True)
+
+    metrics_emit = metrics_sub.add_parser(
+        "emit",
+        help="Record a usage event (POST /v1/usage/emit).",
+    )
+    metrics_emit.add_argument(
+        "--event",
+        required=True,
+        help="Event type, e.g. 'session.completed' (1-64 chars).",
+    )
+    metrics_emit.add_argument(
+        "--quantity",
+        type=int,
+        default=1,
+        help="Credits to record for this event (default: 1).",
+    )
+    metrics_emit.add_argument(
+        "--metadata",
+        action="append",
+        metavar="KEY=VALUE",
+        default=None,
+        help="Optional metadata pair; repeatable (e.g. --metadata model=opus --metadata tool=cli).",
+    )
+    metrics_emit.add_argument(
+        "--base-url",
+        default=DEFAULT_API_BASE_URL,
+        help="Zeno API base URL (default: ZENO_API_BASE_URL or https://zeno-api-364453955482.us-west1.run.app).",
+    )
+
+    # Capture-hook installer: write/remove the cc-bridge hook in
+    # ~/.claude/settings.json. zeno owns the read-merge-write (see hook_install.py).
+    hook = subparsers.add_parser(
+        "hook",
+        help="Install/remove the Claude Code capture hook in ~/.claude/settings.json.",
+    )
+    hook_sub = hook.add_subparsers(dest="hook_command", required=True)
+
+    hook_install_p = hook_sub.add_parser(
+        "install", help="Write the capture hook into settings.json (idempotent, backed up)."
+    )
+    hook_install_p.add_argument(
+        "--settings-path",
+        default=None,
+        help="Override the settings.json path (default: ~/.claude/settings.json).",
+    )
+    hook_install_p.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace an existing non-zeno statusLine (statusLine allows only one).",
+    )
+    hook_install_p.add_argument(
+        "--no-hud",
+        action="store_true",
+        help="Install only the capture hook; do not set the zeno-hud statusLine.",
+    )
+
+    hook_uninstall_p = hook_sub.add_parser(
+        "uninstall", help="Remove zeno's hook entries from settings.json."
+    )
+    hook_uninstall_p.add_argument("--settings-path", default=None)
+    hook_uninstall_p.add_argument(
+        "--restore",
+        action="store_true",
+        help="Restore settings.json from the latest zeno backup instead of surgical removal.",
+    )
+
+    hook_status_p = hook_sub.add_parser(
+        "status", help="Show which capture-hook events are installed."
+    )
+    hook_status_p.add_argument("--settings-path", default=None)
+
+    # `run` is dispatched by the fast-path passthrough in main(); registered here
+    # only so it shows up in `zeno hook --help`.
+    hook_sub.add_parser(
+        "run",
+        help="(internal) Exec the bundled capture hook; called by Claude Code per event.",
+    )
+
+    # The cognition HUD add-on: a single differentiated line (`zeno-hud-bar`) that
+    # stacks UNDER whatever popular HUD the user already runs (claude-hud /
+    # ccstatusline), plus the install/uninstall orchestrator that wires it in. See
+    # docs/HUD_ADDON.md. The `bar` subcommand is dispatched by a fast-path in main()
+    # (like `hook run`) for clean stdin + speed; registered here for `zeno hud --help`.
+    hud = subparsers.add_parser(
+        "hud",
+        help="Stack the zeno cognition line under your existing HUD (claude-hud / ccstatusline).",
+    )
+    hud_sub = hud.add_subparsers(dest="hud_command", required=True)
+    hud_sub.add_parser(
+        "bar",
+        help="(internal) Render the one cognition line from session JSON on stdin.",
+    )
+
+    hud_install_p = hud_sub.add_parser(
+        "install", help="Wire the zeno cognition line into your HUD (auto-detect by default)."
+    )
+    hud_install_p.add_argument(
+        "--target",
+        choices=["auto", "ccstatusline", "claude-hud"],
+        default="auto",
+        help="Which adapter to use (default: auto - ccstatusline if configured, else claude-hud).",
+    )
+    hud_install_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print exactly what would change; write nothing.",
+    )
+    hud_install_p.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace an existing non-zeno statusLine (claude-hud target only).",
+    )
+    hud_install_p.add_argument(
+        "--settings-path",
+        default=None,
+        help="Override settings.json (claude-hud target; default resolves symlinks to "
+        "settings.local.json).",
+    )
+    hud_install_p.add_argument(
+        "--ccstatusline-path",
+        default=None,
+        help="Override the ccstatusline settings.json path.",
+    )
+
+    hud_uninstall_p = hud_sub.add_parser(
+        "uninstall", help="Remove the zeno cognition line from both adapters (idempotent)."
+    )
+    hud_uninstall_p.add_argument("--settings-path", default=None)
+    hud_uninstall_p.add_argument("--ccstatusline-path", default=None)
+    hud_uninstall_p.add_argument(
+        "--restore",
+        action="store_true",
+        help="Restore each config from its latest zeno backup (byte-for-byte) instead of "
+        "surgical removal.",
+    )
+
+    hud_status_p = hud_sub.add_parser(
+        "status", help="Show which HUD is detected and whether the zeno line is wired in."
+    )
+    hud_status_p.add_argument("--settings-path", default=None)
+    hud_status_p.add_argument("--ccstatusline-path", default=None)
+
+    # Email DNS verification: surface SPF/DKIM/DMARC/MX/A status for the
+    # configured sending domain (zeno.center by default). Stdlib + dig only.
+    # See docs/EMAIL_DNS_SETUP.md for the records this checks against.
+    email = subparsers.add_parser("email", help="Email infrastructure helpers.")
+    email_sub = email.add_subparsers(dest="email_command", required=True)
+
+    check_dns = email_sub.add_parser(
+        "check-dns",
+        help="Run dig against the email DNS records for the sending domain.",
+    )
+    check_dns.add_argument(
+        "--domain",
+        default="zeno.center",
+        help="Sending domain (default: zeno.center).",
+    )
+    check_dns.add_argument(
+        "--dkim-selector",
+        default="bunmail",
+        help="DKIM selector (default: bunmail; matches bunmail's default).",
+    )
+    check_dns.add_argument(
+        "--mail-host",
+        default=None,
+        help="Mail hostname to check A + PTR for (default: mail.<domain>).",
+    )
+
+    # Outreach: rolodex-driven friendly intro mail via bunmail. Dry-run by
+    # default - actual sends require --confirm AND an interactive y/N. The
+    # CSV input is the rolodex repo's canonical_contacts_*.csv, the template
+    # lives in zeno_api.email_templates. See outreach.py for the safety
+    # contract.
+    outreach = subparsers.add_parser(
+        "outreach",
+        help="Rolodex-driven outreach via bunmail (dry-run by default).",
+    )
+    outreach_sub = outreach.add_subparsers(dest="outreach_command", required=True)
+
+    outreach_send = outreach_sub.add_parser(
+        "send",
+        help="Send (or dry-run) a templated outreach mail to filtered contacts.",
+    )
+    outreach_send.add_argument(
+        "--csv",
+        required=True,
+        help="Path to rolodex canonical_contacts_*.csv file.",
+    )
+    outreach_send.add_argument(
+        "--template",
+        required=True,
+        help="Template id from zeno_api.email_templates (e.g. outreach_intro_zeno).",
+    )
+    outreach_send.add_argument(
+        "--filter-tag",
+        default=None,
+        help="Only contacts with this tag (case-insensitive).",
+    )
+    outreach_send.add_argument(
+        "--max-sends",
+        type=int,
+        default=10,
+        help="Hard cap on number of mails per run (CLI default 10, max 100).",
+    )
+    outreach_send.add_argument(
+        "--exclude-recent-days",
+        type=int,
+        default=30,
+        help="Drop contacts mailed within this many days (default 30).",
+    )
+    outreach_send.add_argument(
+        "--confirm",
+        action="store_true",
+        help="Required to actually send. Without it, prints a dry-run plan.",
+    )
+
+    # Waitlist-driven first-100-customer interview invites. Same safety
+    # contract as `outreach send`: dry-run by default, --confirm + y/N
+    # to actually ship, hard cap on --max, ZENO_BUNMAIL_API_KEY +
+    # ZENO_BUNMAIL_BASE_URL required to even dry-run. Renders the
+    # customer_interview_invite template from zeno_api.email_templates.
+    invite = outreach_sub.add_parser(
+        "invite-interviews",
+        help=(
+            "Mail the customer_interview_invite template to waitlist signups (dry-run by default)."
+        ),
+    )
+    invite.add_argument(
+        "--csv",
+        required=True,
+        help=(
+            "Path to a waitlist export CSV. Required columns: email. "
+            "Optional: first_name, role, intent, why, signed_up_at."
+        ),
+    )
+    invite.add_argument(
+        "--max",
+        type=int,
+        default=10,
+        dest="max_invites",
+        help="Hard cap on invites per run (CLI default 10, max 50).",
+    )
+    invite.add_argument(
+        "--only-since-days",
+        type=int,
+        default=None,
+        help=(
+            "Only signups newer than N days (requires signed_up_at "
+            "column). Default: no recency filter."
+        ),
+    )
+    invite.add_argument(
+        "--confirm",
+        action="store_true",
+        help="Required to actually send. Without it, prints a dry-run plan.",
+    )
+
+    # zeno completion <shell>: emit a static completion script to stdout, the
+    # gh / kubectl / rustup pattern. Dependency-free (no argcomplete): the
+    # subcommand list is baked from TOP_LEVEL_COMMANDS at generation time.
+    completion = subparsers.add_parser(
+        "completion",
+        help="Print a shell-completion script (eval it or save to your completions dir).",
+    )
+    completion.add_argument(
+        "shell",
+        choices=["bash", "zsh", "fish"],
+        help="Target shell. e.g. 'zeno completion zsh > ~/.zsh/completions/_zeno'.",
+    )
+
+    return parser
+
+
+def _project_id(project: str) -> str:
+    return str(uuid.uuid5(uuid.NAMESPACE_URL, project))
+
+
+def _load_session_points(zeno: Zeno, project: str) -> list[SessionPoint]:
+    raw = asyncio.run(zeno.storage.get_session_points(_project_id(project)))
+    points: list[SessionPoint] = []
+    for row in raw:
+        ended_at = None
+        if row["ended_at"]:
+            ended_at = datetime.fromisoformat(row["ended_at"])
+        points.append(
+            SessionPoint(
+                session_id=row["session_id"],
+                n_agents_active=row["n_agents_active"],
+                composite_load=row["composite_load"],
+                output_quality=row["output_quality"],
+                ended_at=ended_at,
+            )
+        )
+    return points
+
+
+def _post_rtlxs_response(
+    *,
+    base_url: str,
+    session_id: str,
+    payload: dict[str, object],
+) -> tuple[bool, str]:
+    """Best-effort POST of an RTLX-S response to the API.
+
+    Returns (success, note). Free-tier users without ZENO_API_TOKEN keep
+    the response locally - the API call is skipped, but the survey is
+    still logged in the local SQLite store. Network errors degrade
+    silently so the CLI never blocks on the server being down.
+    """
+    token = resolve_api_token()
+    if not token:
+        return False, "no ZENO_API_TOKEN set; response stored locally only"
+    client = ZenoApiClient(base_url=base_url, bearer_token=token, timeout_seconds=3.0)
+    try:
+        client._request(
+            "POST",
+            f"/v1/sessions/{session_id}/rtlxs",
+            json_body=payload,
+        )
+        return True, "POSTed to API"
+    except (ApiError, OSError) as exc:
+        return False, f"API POST skipped: {exc}"
+
+
+def _run_survey(
+    *,
+    project: str,
+    harness: str,
+    no_probes: bool,
+    autonomy: str | None = None,
+    sced_blinded: bool = False,
+    sced_session_index: int | None = None,
+) -> int:
+    if sced_blinded and sced_session_index is None:
+        _print("error: --sced requires --sced-index <N> (the locked-schedule slot).")
+        return 2
+    zeno = Zeno(project=project)
+    if no_probes:
+        zeno.config.probes_enabled = False
+
+    with zeno.session(harness=harness) as session:
+        if no_probes:
+            session.prompt_load_probe(subscales=None, skipped=True)
+            _print("Probes disabled. Logged LoadProbe(skipped=True).")
+            zeno.shutdown()
+            return 0
+
+        # RTLX-S 5-item probe (research 1, 2026-06-07 PM3). Replaces the
+        # legacy 10-subscale NASA-TLX-S TUI. Non-tty contexts return None
+        # so background daemons / piped invocations skip the probe cleanly.
+        #
+        # Behavioral anchors for Stage 2a (research 3, 2026-06-10): resolve
+        # the most-recent session with actual agent activity (within the
+        # last 2 hours) and pull its interrupt + turn counts + estimated
+        # verification seconds. The survey opens a fresh session for its
+        # own bookkeeping, so the work-session telemetry has to be looked
+        # up explicitly. If no recent work session exists, anchors stay
+        # None and the rtlxs_responses row carries NULL for all three.
+        work_session_id = asyncio.run(
+            zeno.storage.find_recent_activity_session_id(window_minutes=120)
+        )
+        anchors: dict[str, int | None] = {
+            "agent_interrupts_count": None,
+            "agent_turns_count": None,
+            "verification_seconds": None,
+        }
+        if work_session_id is not None:
+            stats = asyncio.run(zeno.storage.compute_session_stats(work_session_id))
+            if stats.agent_turns_count > 0:
+                anchors = {
+                    "agent_interrupts_count": stats.interrupt_count,
+                    "agent_turns_count": stats.agent_turns_count,
+                    "verification_seconds": stats.verification_seconds,
+                }
+        response = run_rtlxs_survey_tui(
+            session_id=session.session_id,
+            agent_interrupts_count=anchors["agent_interrupts_count"],
+            agent_turns_count=anchors["agent_turns_count"],
+            verification_seconds=anchors["verification_seconds"],
+            autonomy_condition=autonomy,
+            sced_blinded=sced_blinded,
+            sced_session_index=sced_session_index,
+        )
+        if response is None:
+            session.prompt_load_probe(subscales=None, skipped=True)
+            _print("Survey skipped.")
+        else:
+            # Persist locally first (preserves the legacy LoadProbe wire
+            # so the local curve fit still sees a probe row). The 5 raw
+            # values are stored under the load_probe subscales JSON column
+            # for now - the canonical wire format is the new
+            # rtlxs_responses table at the API.
+            local_subscales = {
+                "mental_demand": response.mental_demand,
+                "effort": response.effort,
+                "frustration": response.frustration,
+                "supervision_load": response.supervision_load,
+                "execution_load": response.execution_load,
+            }
+            session.prompt_load_probe(subscales=local_subscales, skipped=False)
+            ok, note = _post_rtlxs_response(
+                base_url=DEFAULT_API_BASE_URL,
+                session_id=session.session_id,
+                payload=response.to_payload(),
+            )
+            status_word = "submitted" if ok else "submitted locally"
+            _print(f"RTLX-S {status_word} for session {session.session_id} ({note}).")
+
+    zeno.shutdown()
+    return 0
+
+
+def _run_report(*, project: str) -> int:
+    zeno = Zeno(project=project)
+    tier = _fetch_remote_tier(DEFAULT_API_BASE_URL)
+    session_id = asyncio.run(zeno.storage.latest_session_id(_project_id(project)))
+    if session_id is None:
+        _print("No sessions found yet.")
+        _print_tier_footer(tier)
+        zeno.shutdown()
+        return 0
+
+    stats = asyncio.run(zeno.storage.compute_session_stats(session_id))
+    points = _load_session_points(zeno, project)
+    curve = fit_babysitting_tax_curve(points)
+    if curve.calibration_in_progress or curve.optimal_n_agents is None:
+        _print(
+            f"Last session avg agents: {stats.avg_n_agents:.1f}. "
+            "Calibration in progress: need at least 10 sessions."
+        )
+    else:
+        _print(
+            f"You were a {int(round(stats.avg_n_agents))}-agent operator today; "
+            f"tax kicked in at agent {curve.optimal_n_agents}."
+        )
+    _print_tier_footer(tier)
+    zeno.shutdown()
+    return 0
+
+
+def _run_curve(*, project: str, png: str) -> int:
+    zeno = Zeno(project=project)
+    points = _load_session_points(zeno, project)
+    curve = fit_babysitting_tax_curve(points)
+    _print(render_curve_ascii(curve))
+    if not curve.calibration_in_progress and curve.xs:
+        output = Path(png).expanduser()
+        save_curve_png(curve, output)
+        _print(f"Saved curve PNG to {output}.")
+    zeno.shutdown()
+    return 0
+
+
+def _run_weekly(*, project: str) -> int:
+    zeno = Zeno(project=project)
+    points = _load_session_points(zeno, project)
+    summary = weekly_summary(points)
+    _print(render_weekly_table(summary))
+    zeno.shutdown()
+    return 0
+
+
+def _fetch_remote_streak(base_url: str) -> StreakResult | None:
+    """Hit /v1/me/streak; return parsed StreakResult, or None on any failure.
+
+    Free-tier offline users won't have a token wired up - they get None and
+    the CLI falls back to the local SQLite computation. Network or auth
+    errors degrade silently for the same reason; the CLI should NEVER block
+    on the API to render `zeno status`.
+    """
+    token = resolve_api_token()
+    client = ZenoApiClient(base_url=base_url, bearer_token=token, timeout_seconds=2.0)
+    try:
+        result = client.me_streak()
+    except (ApiError, OSError):
+        return None
+    current = result.get("current")
+    longest = result.get("longest")
+    if not isinstance(current, int) or not isinstance(longest, int):
+        return None
+    last = result.get("last_response_at")
+    return StreakResult(
+        current=current,
+        longest=longest,
+        last_response_at=last if isinstance(last, str) else None,
+    )
+
+
+def _fetch_remote_tier(base_url: str) -> str:
+    """Hit /v1/me with whatever token is in the env; return a tier string or
+    "offline" when the API isn't reachable or returns an auth error.
+
+    Free-tier users don't have a token wired up, so "offline" is the expected
+    common case. Treat it as a soft signal, not an error.
+    """
+    token = resolve_api_token()
+    client = ZenoApiClient(base_url=base_url, bearer_token=token, timeout_seconds=2.0)
+    try:
+        result = client.me()
+        tier = result.get("tier")
+        if isinstance(tier, str) and tier:
+            return tier
+        return "offline"
+    except (ApiError, OSError):
+        return "offline"
+
+
+def _print_tier_footer(tier: str) -> None:
+    """Trailing line on report: name the current tier + what's locked behind paid."""
+    colors = _colors_enabled()
+    if tier in {"free", "offline"}:
+        label = _color("free tier", "33", enabled=colors)
+        _print(
+            f"On {label}. Paid tiers unlock cloud sync, AI recommendations, "
+            "and the weekly email digest. Run 'zeno status' for details."
+        )
+    else:
+        label = _color(tier, "32", enabled=colors)
+        _print(f"On {label} tier. All Pro features active.")
+
+
+def _run_status(*, project: str, base_url: str) -> int:
+    """One-screen summary. Hits local SQLite + a 2s remote probe.
+
+    Layout (free-tier first-class):
+      Tier:            <free|pro|offline>
+      Last session:    <ISO timestamp or "none">
+      Sessions logged: <N>
+      Tax curve:       <optimal-N or "calibrating (N/10)">
+      Survey streak:   <N day(s)>  (longest: <M>)   <- research 1 PM3
+      [warning if no response since today's 03:00 cutoff]
+      Tip:             <upgrade nudge for free, /usage pointer for paid>
+
+    Streak source-of-truth order: remote API (paid users, online) ->
+    local SQLite (free + offline). Both share the algorithm in
+    zeno_core.streak so the displayed value is identical when the user
+    has been online and synced.
+    """
+    colors = _colors_enabled()
+    zeno = Zeno(project=project)
+    project_uuid = _project_id(project)
+
+    tier = _fetch_remote_tier(base_url)
+    session_id = asyncio.run(zeno.storage.latest_session_id(project_uuid))
+    last_iso = "none"
+    if session_id is not None:
+        row = asyncio.run(
+            zeno.storage._fetchone(
+                "SELECT end_at FROM sessions WHERE id = ?",
+                (session_id,),
+            )
+        )
+        if row is not None and row[0]:
+            last_iso = str(row[0])
+
+    count_row = asyncio.run(
+        zeno.storage._fetchone(
+            "SELECT COUNT(*) FROM sessions WHERE project_id = ?",
+            (project_uuid,),
+        )
+    )
+    session_count = int(count_row[0]) if count_row is not None else 0
+
+    points = _load_session_points(zeno, project)
+    curve = fit_babysitting_tax_curve(points)
+    if curve.calibration_in_progress or curve.optimal_n_agents is None:
+        n_points = len(points)
+        tax_label = _color(f"calibrating ({n_points}/10)", "33", enabled=colors)
+    else:
+        tax_label = _color(f"optimal-N = {curve.optimal_n_agents}", "32", enabled=colors)
+
+    # Streak: prefer remote (single source of truth across machines), fall
+    # back to local SQLite when offline. The two should match once a user is
+    # synced; for free-tier offline users only the local view exists.
+    streak = _fetch_remote_streak(base_url)
+    if streak is None:
+        streak = asyncio.run(read_streak_from_local_storage(zeno.storage, project_uuid))
+
+    # Compute today's "have you logged today" warning from local probe
+    # rows (the API endpoint doesn't yet return per-day flags). Free-tier
+    # users who never sync see exactly the same warning as paid users.
+    local_probe_rows = asyncio.run(
+        zeno.storage._fetchall(
+            """
+            SELECT lp.responded_at, lp.prompted_at
+            FROM load_probes lp
+            JOIN sessions s ON s.id = lp.session_id
+            WHERE s.project_id = ? AND lp.skipped = 0
+            """,
+            (project_uuid,),
+        )
+    )
+    local_timestamps: list[datetime] = []
+    for r in local_probe_rows:
+        raw = r[0] or r[1]
+        if not raw:
+            continue
+        try:
+            local_timestamps.append(datetime.fromisoformat(str(raw)))
+        except ValueError:
+            continue
+    logged_today = has_logged_today(local_timestamps, today=datetime.now().date())
+
+    if tier == "offline":
+        tier_label = _color("offline", "31", enabled=colors)
+    elif tier == "free":
+        tier_label = _color("free", "33", enabled=colors)
+    else:
+        tier_label = _color(tier, "32", enabled=colors)
+
+    # Streak coloring: green for an active streak, yellow for none. We
+    # intentionally never red the streak even if broken - the longest still
+    # shows a personal best to beat (BJ Fogg "celebrate small wins").
+    if streak.current >= 1:
+        streak_value = _color(
+            f"{streak.current} day{'s' if streak.current != 1 else ''}",
+            "32",
+            enabled=colors,
+        )
+    else:
+        streak_value = _color("0 days", "33", enabled=colors)
+    streak_label = f"{streak_value} (longest: {streak.longest})"
+
+    # Today's survey response: explicit yes/no so the operator sees the
+    # dogfood-discipline state in the status snapshot, not just a warning
+    # buried under the streak. Same data source as `logged_today`.
+    if logged_today:
+        survey_today_label = _color("yes", "32", enabled=colors)
+    else:
+        survey_today_label = _color("no", "33", enabled=colors)
+
+    # Cognitive-state row reads the ~/.zeno/cognitive-state.json mirror
+    # written by the API (research 2 DPSC-CP Phase 0). Free-tier users who
+    # never hit /v1/cognitive-state won't have a cache file and we render
+    # "unknown" - that's the explicit UNKNOWN state in the DPSC-CP enum
+    # and the right answer rather than hiding the row.
+    cog = _read_cognitive_state_cache(DEFAULT_COGNITIVE_STATE_CACHE)
+    if cog is None:
+        cog_label = _color("unknown", "33", enabled=colors) + " (no cache)"
+    else:
+        state, age = cog
+        color_for_state = {
+            "FRESH": "32",
+            "NEUTRAL": "36",
+            "DEGRADED": "33",
+            "UNKNOWN": "33",
+        }
+        cog_label = _color(state, color_for_state.get(state, "0"), enabled=colors) + f" ({age})"
+
+    _print(f"Tier:            {tier_label}")
+    _print(f"Last session:    {last_iso}")
+    _print(f"Sessions logged: {session_count}")
+    _print(f"Tax curve:       {tax_label}")
+    _print(f"Survey streak:   {streak_label}")
+    _print(f"Survey today:    {survey_today_label}")
+    _print(f"Cognitive:       {cog_label}")
+    if not logged_today and streak.current >= 1:
+        # Streak is alive but today is empty - that's the surgical nudge.
+        # Phrasing follows the "don't break the chain" frame; the action is
+        # one command away (`zeno survey`).
+        _print(
+            _color(
+                "                 You have not logged today. Run 'zeno survey' to keep the streak.",
+                "33",
+                enabled=colors,
+            )
+        )
+    elif not logged_today and streak.current == 0 and streak.longest >= 1:
+        _print(
+            _color(
+                "                 Streak broken. Run 'zeno survey' to start a "
+                f"new run at your personal best of {streak.longest}.",
+                "33",
+                enabled=colors,
+            )
+        )
+    if tier in {"free", "offline"}:
+        _print(
+            "Tip:             Run 'zeno billing recommend-tier --engineers <N>' to size up to Pro."
+        )
+    else:
+        _print("Tip:             Open the /usage dashboard for credit + event trends.")
+
+    zeno.shutdown()
+    return 0
+
+
+def _run_tips() -> int:
+    """Print today's tip. Rotation = ordinal day-of-year mod len(TIPS)."""
+    index = date.today().toordinal() % len(TIPS)
+    colors = _colors_enabled()
+    header = _color("Today's tip", "36", enabled=colors)
+    _print(f"{header}: {TIPS[index]}")
+    return 0
+
+
+def _run_session_intel_passthrough(module_name: str, argv: list[str]) -> int:
+    """Delegate to a zeno_session_intel sub-CLI (ingest / analytics), lazy-imported.
+
+    Folds the standalone `zeno-ingest` / `zeno-usage` entry points under the main
+    CLI as `zeno ingest` / `zeno usage`. The import is deferred so it costs nothing
+    on the hot path and degrades cleanly: zeno-session-intel is a workspace package,
+    NOT bundled into the zeno-cli wheel, so a bare wheel install prints a hint
+    instead of a traceback. The sub-CLI parses its own args (so --tools, --db,
+    --write-live, --search, --limit all work unchanged, and the live-DB write
+    guard inside ingest.main stays in force).
+    """
+    import importlib  # noqa: PLC0415
+
+    try:
+        mod = importlib.import_module(module_name)
+    except ImportError:
+        _print(
+            "This command needs the zeno-session-intel package, which isn't bundled "
+            "in this install.\nRun it from the zeno workspace, or install "
+            "zeno-session-intel alongside the CLI."
+        )
+        return 1
+    return int(mod.main(argv))
+
+
+def _parse_metadata_pairs(pairs: list[str] | None) -> dict[str, str]:
+    """Parse repeated --metadata KEY=VALUE flags into a dict.
+
+    Raises ValueError on a malformed pair so the caller can surface a clean
+    message instead of a traceback. The API expects dict[str, str], so values
+    are kept as strings (the meter records what the caller asserts).
+    """
+    out: dict[str, str] = {}
+    for raw in pairs or []:
+        if "=" not in raw:
+            raise ValueError(f"metadata must be KEY=VALUE, got: {raw!r}")
+        key, value = raw.split("=", 1)
+        if not key:
+            raise ValueError(f"metadata key must be non-empty, got: {raw!r}")
+        out[key] = value
+    return out
+
+
+def _run_metrics_emit(
+    *, event: str, quantity: int, metadata: list[str] | None, base_url: str
+) -> int:
+    """Emit one usage event to the Stage 1.5 meter and print the response."""
+    try:
+        event_metadata = _parse_metadata_pairs(metadata)
+    except ValueError as exc:
+        _print(f"Error: {exc}")
+        return 2
+
+    payload: dict[str, object] = {"event_type": event, "credits": quantity}
+    if event_metadata:
+        payload["event_metadata"] = event_metadata
+
+    client = ZenoApiClient(base_url=base_url, bearer_token=resolve_api_token())
+    try:
+        result = client.usage_emit(payload=payload)
+    except ApiError as exc:
+        _print(f"Error emitting usage event: {exc}")
+        return 1
+    _print(json.dumps(result, indent=2))
+    return 0
+
+
+def _run_billing_recommend_tier(*, engineers: int, base_url: str) -> int:
+    client = ZenoApiClient(base_url=base_url)
+    result = client.billing_recommend_tier(engineers=str(engineers))
+    _print(json.dumps(result, indent=2))
+    return 0
+
+
+def _run_billing_preview_tier(*, tier: str, period: str, base_url: str) -> int:
+    client = ZenoApiClient(base_url=base_url)
+    result = client.billing_preview_checkout(tier=tier, billing_period=period)
+    _print(json.dumps(result, indent=2))
+    return 0
+
+
+def _run_version() -> int:
+    """Print the version banner. Same output `zeno --version` produces, but
+    reachable via the subcommand shape for muscle-memory parity with
+    kubectl/docker/doctl. Always returns 0."""
+    _print(f"zeno {version_string()}")
+    return 0
+
+
+def _run_login(*, authorize_url: str, open_browser: bool) -> int:
+    """Run the browser + loopback login flow and store the Clerk JWT.
+
+    On success the token lands in the OS keyring (via zeno_sdk.auth) and the
+    CLI echoes the signed-in identity decoded (UNVERIFIED) from the JWT - the
+    API is the source of truth for authz; this is a local convenience print.
+    """
+    from . import login as login_mod  # noqa: PLC0415
+
+    try:
+        token = login_mod.run_loopback_login(authorize_url, open_browser=open_browser)
+    except login_mod.LoginError as exc:
+        _print(f"Login failed: {exc}")
+        return 1
+    except OSError as exc:
+        _print(f"Login failed: could not start the local callback server: {exc}")
+        return 1
+
+    login_mod.store_token(token)
+    claims = login_mod._decode_jwt_unverified(token)
+    who = claims.get("email") or claims.get("sub") or claims.get("user_id")
+    if who:
+        _print(f"Logged in as {who}. Token stored in the OS keyring.")
+    else:
+        _print("Logged in. Token stored in the OS keyring.")
+    return 0
+
+
+def _run_logout() -> int:
+    """Clear the stored Clerk token from the OS keyring (idempotent)."""
+    from . import login as login_mod  # noqa: PLC0415
+
+    login_mod.clear_token()
+    _print("Logged out. Cleared the stored Clerk token from the OS keyring.")
+    return 0
+
+
+def _run_whoami(*, base_url: str) -> int:
+    """Resolve the stored token and print the identity + tier the API sees.
+
+    Hits GET /v1/me with the resolved bearer token. Returns 1 (with a clear
+    message) when no token is stored or the token is rejected (401), so this
+    doubles as a quick "is my login still good?" check.
+    """
+    token = resolve_api_token()
+    if not token:
+        _print("Not logged in. Run 'zeno login' to authenticate.")
+        return 1
+    client = ZenoApiClient(base_url=base_url, bearer_token=token, timeout_seconds=5.0)
+    try:
+        result = client.me()
+    except ApiError as exc:
+        if exc.status_code == 401:
+            _print("Stored token was rejected (401). Run 'zeno login' to re-authenticate.")
+            return 1
+        _print(f"Error calling /v1/me: {exc}")
+        return 1
+    except OSError as exc:
+        _print(f"Could not reach the API at {base_url}: {exc}")
+        return 1
+    user = result.get("user_id") or result.get("sub") or "<unknown>"
+    tier = result.get("tier") or "<unknown>"
+    _print(f"Logged in as {user} (tier: {tier}).")
+    return 0
+
+
+def _run_doctor(*, base_url: str) -> int:
+    """Render the doctor checks as a left-aligned table + summary line.
+
+    Each row is `<label-padded>  <colored-status>  <detail>`. The summary
+    line counts PASS/WARN/FAIL totals so the operator sees the shape
+    without scanning. Exit code mirrors `doctor_exit_code` from
+    doctor.py: 0 unless any FAIL row appears.
+    """
+    colors = _colors_enabled()
+    color_for = {STATUS_PASS: "32", STATUS_WARN: "33", STATUS_FAIL: "31"}
+
+    checks = run_doctor(
+        base_url=base_url,
+        db_path=DEFAULT_DB_PATH,
+        cache_path=DEFAULT_COGNITIVE_STATE_CACHE,
+    )
+    label_width = max((len(c.label) for c in checks), default=20)
+
+    _print(f"zeno doctor (base url: {base_url})")
+    _print("")
+    for check in checks:
+        colored = _color(check.status, color_for.get(check.status, "0"), enabled=colors)
+        _print(f"  {check.label.ljust(label_width)}  {colored}  {check.detail}")
+    _print("")
+
+    n_pass = sum(1 for c in checks if c.status == STATUS_PASS)
+    n_warn = sum(1 for c in checks if c.status == STATUS_WARN)
+    n_fail = sum(1 for c in checks if c.status == STATUS_FAIL)
+    summary = (
+        f"{_color(f'{n_pass} pass', '32', enabled=colors)}, "
+        f"{_color(f'{n_warn} warn', '33', enabled=colors)}, "
+        f"{_color(f'{n_fail} fail', '31', enabled=colors)}"
+    )
+    _print(f"Summary: {summary}")
+    return doctor_exit_code(checks)
+
+
+def _run_onboard(
+    *,
+    base_url: str,
+    dry_run: bool,
+    force: bool,
+    settings_path: str | None,
+    ccstatusline_path: str | None,
+) -> int:
+    """One-command setup: capture hook + HUD line + doctor, then a BLUF summary.
+
+    Delegates the orchestration to onboard.run_onboard (which composes the
+    existing installers + doctor) and renders the result here. Exit code is 0
+    unless doctor found a FAIL row - matching `zeno doctor`'s contract, so an
+    off-tailnet local-only onboard still exits 0.
+    """
+    from .onboard import run_onboard  # noqa: PLC0415
+
+    colors = _colors_enabled()
+    res = run_onboard(
+        base_url=base_url,
+        settings_path=settings_path,
+        ccstatusline_path=ccstatusline_path,
+        dry_run=dry_run,
+        force=force,
+    )
+
+    tag = "(dry-run) " if res.dry_run else ""
+    header = _color(f"{tag}zeno onboard", "36", enabled=colors)
+    _print(f"{header} - wiring you up for AI-supervision capture.")
+    _print("")
+    for step in res.steps:
+        _print(f"  {_color(step.name, '36', enabled=colors)}: {step.status}")
+        for note in step.notes:
+            _print(f"      {note}")
+    _print("")
+
+    if res.dry_run:
+        _print(
+            _color(
+                "Dry-run: nothing was written. Re-run without --dry-run to apply.",
+                "33",
+                enabled=colors,
+            )
+        )
+        return 0
+
+    # BLUF summary line: verdict first.
+    if res.doctor_ran:
+        summary = (
+            f"{_color(f'{res.doctor_pass} pass', '32', enabled=colors)}, "
+            f"{_color(f'{res.doctor_warn} warn', '33', enabled=colors)}, "
+            f"{_color(f'{res.doctor_fail} fail', '31', enabled=colors)}"
+        )
+        _print(f"Doctor: {summary}")
+
+    if res.doctor_fail:
+        _print(
+            _color(
+                "Setup wired, but doctor found a hard failure. Run 'zeno doctor' for the "
+                "row-by-row detail and fix it before relying on capture.",
+                "31",
+                enabled=colors,
+            )
+        )
+        return 1
+
+    ok = _color("You're set up.", "32", enabled=colors)
+    _print(f"{ok} Start a NEW Claude Code session so capture begins, then code as normal.")
+    _print(
+        "  Next: run 'zeno survey' after a session to calibrate your curve; "
+        "'zeno status' anytime."
+    )
+    _print("  Undo with: zeno hook uninstall && zeno hud uninstall")
+    return 0
+
+
+def _read_cognitive_state_cache(cache_path: Path) -> tuple[str, str] | None:
+    """Read ~/.zeno/cognitive-state.json and return (state, age-string), or
+    None if the file is missing or unreadable.
+
+    Phase 0 cache is a JSON document written by the API on every authed
+    GET /v1/cognitive-state for the local operator. `state` mirrors the
+    DPSC-CP state enum (FRESH / NEUTRAL / DEGRADED / UNKNOWN). The age
+    string ("3m ago", "stale 47m") is computed from the file mtime, not
+    the payload's as_of - mtime is cheap and matches the freshness model
+    `zeno doctor` already uses.
+    """
+    if not cache_path.exists():
+        return None
+    try:
+        payload = json.loads(cache_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    state = payload.get("state")
+    if not isinstance(state, str):
+        return None
+    try:
+        mtime = datetime.fromtimestamp(cache_path.stat().st_mtime)
+    except OSError:
+        return state, "age unknown"
+    age = datetime.now() - mtime
+    minutes = int(age.total_seconds() // 60)
+    if minutes < 1:
+        return state, "just now"
+    return state, f"{minutes}m ago"
+
+
+def _dig(record_type: str, name: str) -> tuple[int, str]:
+    """Run `dig +short <type> <name>` and return (exit_code, stripped_stdout).
+
+    Exit code reflects dig's own status, not record presence. Empty stdout
+    means no record published yet.
+    """
+    proc = subprocess.run(
+        ["dig", "+short", record_type, name],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    return proc.returncode, proc.stdout.strip()
+
+
+def _dig_reverse(ip: str) -> tuple[int, str]:
+    """Run `dig -x <ip> +short` (PTR lookup) and return (exit_code, stripped_stdout)."""
+    proc = subprocess.run(
+        ["dig", "-x", ip, "+short"],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    return proc.returncode, proc.stdout.strip()
+
+
+def _grade_email_dns(
+    *,
+    domain: str,
+    dkim_selector: str,
+    mail_host: str,
+) -> tuple[list[tuple[str, str, str]], bool]:
+    """Run all five email-DNS checks and return (rows, all_pass).
+
+    Each row is (record_label, status, detail). status is one of:
+      PASS - record present and looks well-formed
+      WARN - record present but suspicious (multiple SPF, p=none DMARC, etc.)
+      FAIL - record missing
+    """
+    rows: list[tuple[str, str, str]] = []
+
+    # A record for mail host
+    _, a_out = _dig("A", mail_host)
+    if a_out:
+        rows.append(("A " + mail_host, "PASS", a_out.splitlines()[0]))
+        mail_ip = a_out.splitlines()[0]
+    else:
+        rows.append(("A " + mail_host, "FAIL", "no A record"))
+        mail_ip = ""
+
+    # MX record
+    _, mx_out = _dig("MX", domain)
+    if mx_out:
+        rows.append(("MX " + domain, "PASS", mx_out.splitlines()[0]))
+    else:
+        rows.append(("MX " + domain, "WARN", "no MX (OK if inbound disabled)"))
+
+    # SPF TXT (must have exactly one record containing v=spf1)
+    _, txt_out = _dig("TXT", domain)
+    spf_records = [line for line in txt_out.splitlines() if "v=spf1" in line.lower()]
+    if len(spf_records) == 0:
+        rows.append(("SPF " + domain, "FAIL", "no v=spf1 TXT record"))
+    elif len(spf_records) > 1:
+        rows.append(
+            (
+                "SPF " + domain,
+                "FAIL",
+                f"{len(spf_records)} SPF records (must be exactly 1)",
+            )
+        )
+    else:
+        rows.append(("SPF " + domain, "PASS", spf_records[0][:80]))
+
+    # DKIM TXT at <selector>._domainkey.<domain>
+    dkim_name = f"{dkim_selector}._domainkey.{domain}"
+    _, dkim_out = _dig("TXT", dkim_name)
+    if dkim_out and "v=DKIM1" in dkim_out:
+        rows.append(("DKIM " + dkim_name, "PASS", dkim_out[:60] + "..."))
+    elif dkim_out:
+        rows.append(("DKIM " + dkim_name, "WARN", "TXT present but no v=DKIM1"))
+    else:
+        rows.append(("DKIM " + dkim_name, "FAIL", "no DKIM TXT record"))
+
+    # DMARC TXT at _dmarc.<domain>
+    dmarc_name = f"_dmarc.{domain}"
+    _, dmarc_out = _dig("TXT", dmarc_name)
+    if dmarc_out and "v=DMARC1" in dmarc_out:
+        if "p=none" in dmarc_out.lower():
+            rows.append(("DMARC " + dmarc_name, "WARN", "p=none (monitor-only; OK while warming)"))
+        else:
+            rows.append(("DMARC " + dmarc_name, "PASS", dmarc_out[:80]))
+    else:
+        rows.append(("DMARC " + dmarc_name, "FAIL", "no DMARC TXT record"))
+
+    # Reverse DNS for the sending IP - only if A record resolved
+    if mail_ip:
+        _, ptr_out = _dig_reverse(mail_ip)
+        if ptr_out and mail_host in ptr_out:
+            rows.append(("PTR " + mail_ip, "PASS", ptr_out.splitlines()[0]))
+        elif ptr_out:
+            rows.append(
+                ("PTR " + mail_ip, "WARN", f"PTR is {ptr_out.splitlines()[0]} (want {mail_host}.)")
+            )
+        else:
+            rows.append(("PTR " + mail_ip, "FAIL", "no PTR (request via AWS support)"))
+    else:
+        rows.append(("PTR <unknown>", "FAIL", "skipped (no A record to lookup)"))
+
+    all_pass = all(status == "PASS" for _, status, _ in rows)
+    return rows, all_pass
+
+
+def _run_email_check_dns(
+    *,
+    domain: str,
+    dkim_selector: str,
+    mail_host: str | None,
+) -> int:
+    """Verify SPF/DKIM/DMARC/MX/A/PTR for the configured sending domain."""
+    if shutil.which("dig") is None:
+        _print("dig not found in PATH. Install bind-tools / dnsutils first.")
+        return 2
+
+    mail_host = mail_host or f"mail.{domain}"
+    rows, all_pass = _grade_email_dns(
+        domain=domain,
+        dkim_selector=dkim_selector,
+        mail_host=mail_host,
+    )
+
+    colors = _colors_enabled()
+    color_for = {"PASS": "32", "WARN": "33", "FAIL": "31"}
+    label_width = max((len(label) for label, _, _ in rows), default=20)
+    _print(f"Email DNS check for {domain} (mail host: {mail_host})")
+    _print("")
+    for label, status, detail in rows:
+        colored_status = _color(status, color_for.get(status, "0"), enabled=colors)
+        _print(f"  {label.ljust(label_width)}  {colored_status}  {detail}")
+    _print("")
+    if all_pass:
+        _print(_color("All records pass. Ready to send.", "32", enabled=colors))
+        return 0
+
+    _print(
+        _color(
+            "Some records failing or in warn state. See docs/EMAIL_DNS_SETUP.md.",
+            "33",
+            enabled=colors,
+        )
+    )
+    return 1
+
+
+def _run_outreach_send(
+    *,
+    csv_path: str,
+    template_id: str,
+    filter_tag: str | None,
+    max_sends: int,
+    exclude_recent_days: int,
+    confirm: bool,
+) -> int:
+    """Dry-run-first outreach. See apps/cli/src/zeno_cli/outreach.py docstring.
+
+    Layout:
+      1. Validate env (ZENO_BUNMAIL_API_KEY required to even dry-run -
+         we want callers to confirm bunmail config before they look at
+         a long contact list).
+      2. Load CSV + suppression, filter, sort.
+      3. Print dry-run plan (first 5 + full first-mail render).
+      4. If --confirm: interactive y/N -> iterate sends, sleep, log.
+      5. Always write outreach-runs/YYYY-MM-DD-HHMM.csv as audit.
+    """
+    # Imports inside the function so plain `zeno --help` doesn't pay the
+    # cost of loading outreach.py + the template registry. The CLI loads
+    # fast for the common cases (status, tips, survey).
+    from zeno_api.email_templates import TEMPLATES  # noqa: PLC0415
+
+    from .outreach import (  # noqa: PLC0415
+        DEFAULT_SEND_PAUSE_SECS,
+        HARD_MAX_SENDS,
+        OutreachError,
+        filter_contacts,
+        first_name,
+        load_contacts_csv,
+        load_suppression_list,
+        render_personal_hook,
+        send_one,
+        write_run_log,
+    )
+
+    colors = _colors_enabled()
+
+    api_key = os.environ.get("ZENO_BUNMAIL_API_KEY", "").strip()
+    if not api_key:
+        _print(
+            _color(
+                "ZENO_BUNMAIL_API_KEY is not set. Refusing to run.",
+                "31",
+                enabled=colors,
+            )
+        )
+        return 2
+
+    if max_sends <= 0:
+        _print("--max-sends must be positive.")
+        return 2
+    if max_sends > HARD_MAX_SENDS:
+        _print(f"--max-sends {max_sends} exceeds hard cap of {HARD_MAX_SENDS}. Refusing to run.")
+        return 2
+
+    bunmail_base_url = os.environ.get("ZENO_BUNMAIL_BASE_URL", "").strip()
+    if not bunmail_base_url:
+        _print(
+            _color(
+                "ZENO_BUNMAIL_BASE_URL is not set. Refusing to run.",
+                "31",
+                enabled=colors,
+            )
+        )
+        return 2
+
+    sender = os.environ.get(
+        "ZENO_OUTREACH_SENDER",
+        "Mar <mar@zeno.center>",
+    )
+
+    if template_id not in TEMPLATES:
+        _print(
+            _color(
+                f"Unknown template_id: {template_id!r}. Available: {sorted(TEMPLATES)}",
+                "31",
+                enabled=colors,
+            )
+        )
+        return 2
+
+    csv_path_obj = Path(csv_path).expanduser()
+    if not csv_path_obj.exists():
+        _print(_color(f"CSV not found: {csv_path_obj}", "31", enabled=colors))
+        return 2
+
+    # Suppression list lives in apps/cli/data/ so it ships with the CLI
+    # source and the operator can edit + commit it. Path is relative to
+    # this file's parents - apps/cli/src/zeno_cli/main.py -> apps/cli/
+    suppression_path = Path(__file__).resolve().parents[2] / "data" / "outreach_suppression.txt"
+    suppression = load_suppression_list(suppression_path)
+
+    all_contacts = load_contacts_csv(csv_path_obj)
+    filtered = filter_contacts(
+        all_contacts,
+        filter_tag=filter_tag,
+        exclude_recent_days=exclude_recent_days,
+        suppression=suppression,
+    )
+
+    capped = filtered[:max_sends]
+    n = len(capped)
+
+    _print(
+        _color(
+            f"Loaded {len(all_contacts)} contacts, "
+            f"{len(filtered)} pass filters, {n} after --max-sends.",
+            "36",
+            enabled=colors,
+        )
+    )
+    _print("")
+    _print(f"Would send to {n} contacts:")
+    for c in capped[:5]:
+        _print(
+            f"  - {c.full_name} <{c.primary_email}>  "
+            f"[{c.tier or 'no-tier'}, score={c.relationship_score}]"
+        )
+    if n > 5:
+        _print(f"  ... and {n - 5} more.")
+    _print("")
+
+    if n == 0:
+        _print("Nothing to send. Exiting.")
+        return 0
+
+    # Render the first mail in FULL so the operator sees what's about
+    # to ship before they type "y". This is the most important guard
+    # against a bad template / bad hook.
+    first = capped[0]
+    variables = {
+        "first_name": first_name(first),
+        "personal_hook": render_personal_hook(first),
+    }
+    rendered = TEMPLATES[template_id].render(variables)
+    _print(_color("--- First mail preview ---", "36", enabled=colors))
+    _print(f"From:    {sender}")
+    _print(f"To:      {first.primary_email}")
+    _print(f"Subject: {rendered['subject']}")
+    _print("")
+    _print(rendered["text"])
+    _print(_color("--- end preview ---", "36", enabled=colors))
+    _print("")
+
+    if not confirm:
+        _print(
+            _color(
+                "Dry-run mode. Pass --confirm to send. Nothing was mailed.",
+                "33",
+                enabled=colors,
+            )
+        )
+        return 0
+
+    # Interactive y/N. Default to N on anything other than "y" / "yes".
+    try:
+        answer = input(f"Send to {n} contacts? [y/N]: ").strip().lower()
+    except EOFError:
+        answer = ""
+    if answer not in ("y", "yes"):
+        _print("Aborted. Nothing was mailed.")
+        return 0
+
+    out_dir = Path.cwd() / "outreach-runs"
+    outcomes = []
+    aborted = False
+    for i, contact in enumerate(capped, start=1):
+        variables = {
+            "first_name": first_name(contact),
+            "personal_hook": render_personal_hook(contact),
+        }
+        rendered = TEMPLATES[template_id].render(variables)
+        try:
+            outcome = send_one(
+                bunmail_base_url=bunmail_base_url,
+                bunmail_api_key=api_key,
+                sender=sender,
+                contact=contact,
+                subject=rendered["subject"],
+                text=rendered["text"],
+                html=rendered.get("html"),
+                confirmed=True,
+            )
+        except OutreachError as exc:
+            _print(
+                _color(
+                    f"[{i}/{n}] STOPPING on 4xx from bunmail: {exc}",
+                    "31",
+                    enabled=colors,
+                )
+            )
+            aborted = True
+            break
+        outcomes.append(outcome)
+        _print(f"[{i}/{n}] {outcome.status} {contact.primary_email} (id={outcome.email_id or '-'})")
+        if i < n:
+            time.sleep(DEFAULT_SEND_PAUSE_SECS)
+
+    log_path = write_run_log(out_dir, outcomes)
+    _print("")
+    _print(_color(f"Wrote run log: {log_path}", "32", enabled=colors))
+    return 1 if aborted else 0
+
+
+def _run_invite_interviews(
+    *,
+    csv_path: str,
+    max_invites: int,
+    only_since_days: int | None,
+    confirm: bool,
+) -> int:
+    """Waitlist-driven interview invites. Sibling of `outreach send`.
+
+    Layout (mirrors the rolodex flow on purpose, so the operator's
+    muscle memory carries):
+      1. Validate env (ZENO_BUNMAIL_API_KEY required to even dry-run).
+      2. Load CSV, apply suppression + optional recency filter, cap.
+      3. Print dry-run plan (first 5 + full first-mail render).
+      4. If --confirm: interactive y/N -> iterate, sleep, log.
+      5. On --confirm, write outreach-runs/YYYY-MM-DD-HHMM.csv as an audit
+         trail (dry-run / abort / nothing-to-send paths write nothing).
+    """
+    from zeno_api.email_templates import TEMPLATES  # noqa: PLC0415
+
+    from .interview_invites import (  # noqa: PLC0415
+        HARD_MAX_INVITES,
+        InviteSendConfig,
+        filter_signups,
+        first_name_or_default,
+        load_signups_csv,
+        render_signup_context,
+        send_invites,
+    )
+    from .outreach import (  # noqa: PLC0415
+        OutreachError,
+        load_suppression_list,
+        write_run_log,
+    )
+
+    colors = _colors_enabled()
+    template_id = "customer_interview_invite"
+
+    api_key = os.environ.get("ZENO_BUNMAIL_API_KEY", "").strip()
+    if not api_key:
+        _print(
+            _color(
+                "ZENO_BUNMAIL_API_KEY is not set. Refusing to run.",
+                "31",
+                enabled=colors,
+            )
+        )
+        return 2
+
+    if max_invites <= 0:
+        _print("--max must be positive.")
+        return 2
+    if max_invites > HARD_MAX_INVITES:
+        _print(f"--max {max_invites} exceeds hard cap of {HARD_MAX_INVITES}. Refusing to run.")
+        return 2
+
+    bunmail_base_url = os.environ.get("ZENO_BUNMAIL_BASE_URL", "").strip()
+    if not bunmail_base_url:
+        _print(
+            _color(
+                "ZENO_BUNMAIL_BASE_URL is not set. Refusing to run.",
+                "31",
+                enabled=colors,
+            )
+        )
+        return 2
+
+    sender = os.environ.get(
+        "ZENO_OUTREACH_SENDER",
+        "Mar at Zeno <hello@zeno.center>",
+    )
+
+    csv_path_obj = Path(csv_path).expanduser()
+    if not csv_path_obj.exists():
+        _print(_color(f"CSV not found: {csv_path_obj}", "31", enabled=colors))
+        return 2
+
+    suppression_path = Path(__file__).resolve().parents[2] / "data" / "outreach_suppression.txt"
+    suppression = load_suppression_list(suppression_path)
+
+    all_signups = load_signups_csv(csv_path_obj)
+    filtered = filter_signups(
+        all_signups,
+        suppression=suppression,
+        only_since_days=only_since_days,
+    )
+    capped = filtered[:max_invites]
+    n = len(capped)
+
+    _print(
+        _color(
+            f"Loaded {len(all_signups)} signups, {len(filtered)} pass filters, {n} after --max.",
+            "36",
+            enabled=colors,
+        )
+    )
+    _print("")
+    _print(f"Would invite {n} signups:")
+    for s in capped[:5]:
+        date_label = s.signed_up_at.isoformat() if s.signed_up_at else "no-date"
+        _print(f"  - {s.email}  [{s.intent or 'no-intent'}, signed: {date_label}]")
+    if n > 5:
+        _print(f"  ... and {n - 5} more.")
+    _print("")
+
+    if n == 0:
+        _print("Nothing to send. Exiting.")
+        return 0
+
+    first = capped[0]
+    variables = {
+        "first_name": first_name_or_default(first),
+        "signup_context": render_signup_context(first),
+    }
+    rendered = TEMPLATES[template_id].render(variables)
+    _print(_color("--- First mail preview ---", "36", enabled=colors))
+    _print(f"From:    {sender}")
+    _print(f"To:      {first.email}")
+    _print(f"Subject: {rendered['subject']}")
+    _print("")
+    _print(rendered["text"])
+    _print(_color("--- end preview ---", "36", enabled=colors))
+    _print("")
+
+    if not confirm:
+        _print(
+            _color(
+                "Dry-run mode. Pass --confirm to send. Nothing was mailed.",
+                "33",
+                enabled=colors,
+            )
+        )
+        return 0
+
+    try:
+        answer = input(f"Send to {n} signups? [y/N]: ").strip().lower()
+    except EOFError:
+        answer = ""
+    if answer not in ("y", "yes"):
+        _print("Aborted. Nothing was mailed.")
+        return 0
+
+    def _render_for(signup) -> dict[str, str]:
+        return TEMPLATES[template_id].render(
+            {
+                "first_name": first_name_or_default(signup),
+                "signup_context": render_signup_context(signup),
+            }
+        )
+
+    config = InviteSendConfig(
+        bunmail_base_url=bunmail_base_url,
+        bunmail_api_key=api_key,
+        sender=sender,
+    )
+    try:
+        outcomes, aborted = send_invites(capped, render=_render_for, config=config)
+    except OutreachError as exc:
+        _print(_color(f"STOPPING on 4xx from bunmail: {exc}", "31", enabled=colors))
+        outcomes, aborted = [], True
+
+    for i, outcome in enumerate(outcomes, start=1):
+        _print(f"[{i}/{n}] {outcome.status} {outcome.email} (id={outcome.email_id or '-'})")
+
+    out_dir = Path.cwd() / "outreach-runs"
+    log_path = write_run_log(out_dir, outcomes)
+    _print("")
+    _print(_color(f"Wrote run log: {log_path}", "32", enabled=colors))
+    return 1 if aborted else 0
+
+
+def _run_hook_install(settings_path: Path, *, force: bool, with_hud: bool = True) -> int:
+    from .hook_install import HookInstallError, install  # noqa: PLC0415
+
+    statusline = "zeno-hud" if with_hud else None
+    try:
+        result = install(settings_path, statusline_command=statusline, force=force)
+    except HookInstallError as exc:
+        _print(f"Error: {exc}")
+        return 1
+    _print(f"Installed the zeno capture hook into {settings_path}")
+    _print(f"  events:     {', '.join(result['events'])}")
+    if with_hud:
+        if result["statusline"] == "set":
+            _print("  statusLine: zeno-hud")
+        elif result["statusline"] == "skipped-existing":
+            _print(
+                "  statusLine: kept your existing one (pass --force to replace it with zeno-hud)"
+            )
+    if result["backup"]:
+        _print(f"  backup:     {result['backup']}")
+    _print("  Start a new Claude Code session for capture to begin.")
+    _print("  Undo with: zeno hook uninstall")
+    return 0
+
+
+def _run_hook_uninstall(settings_path: Path, *, restore: bool) -> int:
+    from .hook_install import HookInstallError, uninstall  # noqa: PLC0415
+
+    try:
+        result = uninstall(settings_path, restore=restore)
+    except HookInstallError as exc:
+        _print(f"Error: {exc}")
+        return 1
+    if restore:
+        _print(f"Restored {settings_path} from {result['restored_from']}.")
+        return 0
+    if result["removed_events"] or result["statusline_removed"]:
+        _print(f"Removed zeno entries from {settings_path}")
+        if result["removed_events"]:
+            _print(f"  events:     {', '.join(result['removed_events'])}")
+        if result["statusline_removed"]:
+            _print("  statusLine: removed")
+        if result["backup"]:
+            _print(f"  backup:     {result['backup']}")
+    else:
+        _print(f"No zeno hook entries found in {settings_path}; nothing to remove.")
+    return 0
+
+
+def _run_hook_status(settings_path: Path) -> int:
+    from .hook_install import status  # noqa: PLC0415
+
+    result = status(settings_path)
+    colors = _colors_enabled()
+    if result["all_events_installed"]:
+        label = _color("installed", "32", enabled=colors)
+        _print(f"zeno capture hook: {label} ({settings_path})")
+    elif result["events_installed"]:
+        label = _color("partial", "33", enabled=colors)
+        _print(f"zeno capture hook: {label} ({settings_path})")
+        _print(f"  installed events: {', '.join(result['events_installed'])}")
+    else:
+        label = _color("not installed", "33", enabled=colors)
+        _print(f"zeno capture hook: {label} ({settings_path})")
+        _print("  Run 'zeno hook install' to start capturing Claude Code sessions.")
+    return 0
+
+
+def _warn_if_no_capture_hook(hud_install_mod, settings_path: str | None) -> None:
+    """The cognition line is read-only; without the capture hook nothing writes
+    cognition_samples, so the bar shows '--'. Nudge the user to install the hook."""
+    if not hud_install_mod.capture_hook_present(settings_path):
+        _print("  note: the cognition line is read-only; run 'zeno hook install' so the")
+        _print("        capture hook writes att/eff/drv (without it the bar shows --).")
+
+
+def _run_hud_install(
+    *,
+    target: str,
+    dry_run: bool,
+    force: bool,
+    settings_path: str | None,
+    ccstatusline_path: str | None,
+) -> int:
+    from .hud import hud_install as H  # noqa: PLC0415
+
+    ccpath = Path(ccstatusline_path).expanduser() if ccstatusline_path else None
+    res = H.install(
+        target,
+        settings_path=settings_path,
+        ccstatusline_path=ccpath,
+        dry_run=dry_run,
+        force=force,
+    )
+    # Use the (dry-run) form to match `zeno onboard`; with _print now escaping
+    # markup the bracketed form would also survive, but one convention is clearer.
+    tag = "(dry-run) " if dry_run else ""
+    chosen = res["target"]
+
+    if chosen == "none":
+        _print("No supported HUD detected (ccstatusline config or claude-hud plugin).")
+        _print("  Install one, then re-run 'zeno hud install' (or pass --target explicitly):")
+        _print("    ccstatusline: https://github.com/sirmalloc/ccstatusline")
+        _print("    claude-hud:   https://github.com/jarrodwatts/claude-hud")
+        return 0  # auto-detect is a friendly no-op
+
+    if chosen == "ccstatusline":
+        if res["action"] == "not-found":
+            _print(f"ccstatusline config not found at {res['config']}.")
+            _print("  Configure ccstatusline first, or run 'zeno hud install --target claude-hud'.")
+            return 1  # explicit, impossible target
+        _print(f"{tag}ccstatusline: a dedicated custom-command line running the zeno bar:")
+        _print(f"  command: {res['command']}")
+        _print(f"  config:  {res['config']}  (action: {res['action']})")
+        if not dry_run and res.get("backup"):
+            _print(f"  backup:  {res['backup']}")
+        if not dry_run:
+            _warn_if_no_capture_hook(H, settings_path)
+            _print("  Open a new Claude Code session to see it under your ccstatusline rows.")
+            _print("  Undo with: zeno hud uninstall")
+        return 0
+
+    # claude-hud
+    _print(f"{tag}claude-hud: set statusLine to the zeno wrapper (claude-hud, then the bar):")
+    _print(f"  wrapper:  {res['wrapper']}")
+    _print(f"  settings: {res.get('settings_resolved', res.get('settings_path'))}")
+    _print(f"  bar:      {res['bar_command']}")
+    found = res.get("claude_hud_found")
+    ch_note = (
+        f"found at {found}"
+        if found
+        else "not detected yet (wrapper shows bar-only until installed)"
+    )
+    _print(f"  claude-hud: {ch_note}")
+    if res.get("node_missing"):
+        _print("  note: node is not on PATH; the wrapper shows bar-only until node is available.")
+    if not dry_run:
+        if res.get("statusline") == "skipped-existing":
+            _print("  Kept your existing statusLine (pass --force to replace it with the wrapper).")
+            return 0
+        if res.get("backup"):
+            _print(f"  backup:   {res['backup']}")
+        _warn_if_no_capture_hook(H, settings_path)
+        _print("  Open a new Claude Code session to see claude-hud + the zeno line stacked.")
+        _print("  Undo with: zeno hud uninstall")
+    return 0
+
+
+def _run_hud_uninstall(
+    *, settings_path: str | None, ccstatusline_path: str | None, restore: bool
+) -> int:
+    from .hud import hud_install as H  # noqa: PLC0415
+
+    ccpath = Path(ccstatusline_path).expanduser() if ccstatusline_path else None
+    try:
+        res = H.uninstall(settings_path=settings_path, ccstatusline_path=ccpath, restore=restore)
+    except H.HudInstallError as exc:
+        _print(f"Error: {exc}")
+        return 1
+    cc, ch = res["ccstatusline"], res["claude_hud"]
+    if restore:
+        if cc.get("restored_from"):
+            _print(f"Restored ccstatusline config from {cc['restored_from']}.")
+        if ch.get("restored_from"):
+            _print(f"Restored {res['settings_path']} from {ch['restored_from']}.")
+        if not cc.get("restored_from") and not ch.get("restored_from"):
+            _print("No zeno backups found to restore.")
+        return 0
+    did = False
+    if cc.get("removed"):
+        _print(f"Removed the zeno cognition line from ccstatusline ({cc['config']}).")
+        did = True
+    if ch.get("statusline_removed"):
+        _print(f"Removed the zeno statusLine from {res['settings_path']}.")
+        did = True
+    if ch.get("wrapper_removed"):
+        _print("Removed the zeno-hud-wrapper script.")
+        did = True
+    if not did:
+        _print("No zeno HUD entries found; nothing to remove.")
+    return 0
+
+
+def _run_hud_status(*, settings_path: str | None, ccstatusline_path: str | None) -> int:
+    from .hud import hud_install as H  # noqa: PLC0415
+
+    ccpath = Path(ccstatusline_path).expanduser() if ccstatusline_path else None
+    s = H.detect_status(ccstatusline_path=ccpath, settings_path=settings_path)
+    colors = _colors_enabled()
+
+    def yn(b: bool) -> str:
+        return _color("yes", "32", enabled=colors) if b else _color("no", "33", enabled=colors)
+
+    _print("zeno HUD add-on status")
+    _print("")
+    _print(
+        f"  ccstatusline present:   {yn(s['ccstatusline_present'])}  ({s['ccstatusline_config']})"
+    )
+    _print(f"  ccstatusline wired:     {yn(s['ccstatusline_installed'])}")
+    ch_path = f"  ({s['claude_hud_path']})" if s["claude_hud_path"] else ""
+    _print(f"  claude-hud present:     {yn(s['claude_hud_present'])}{ch_path}")
+    _print(f"  claude-hud wired:       {yn(s['claude_hud_installed'])}")
+    _print(f"  (statusLine target:     {s['settings_path']})")
+    _print(f"  wrapper script present: {yn(s['wrapper_present'])}")
+    _print(f"  capture hook installed: {yn(s['capture_hook_present'])}  (writes att/eff/drv)")
+    _print(f"  recommended adapter:    {s['recommended']}")
+    if not s["capture_hook_present"]:
+        _print(
+            "  note: without the capture hook the read-only bar shows --; run 'zeno hook install'."
+        )
+    return 0
+
+
+def _print_subcommand_index() -> None:
+    """Grouped subcommand index, printed after the zero-args status snapshot.
+
+    Grouped by purpose so the operator scans 6 sections (4-5 commands each)
+    instead of one flat 14-item list. Matches the gh / doctl pattern of
+    "core" group first, "extras" later. Reuses the same labels as the
+    argparse help; keep these in sync by hand (cheap, low-churn).
+    """
+    colors = _colors_enabled()
+    header = _color("Subcommands:", "36", enabled=colors)
+    _print(header)
+    groups: list[tuple[str, list[tuple[str, str]]]] = [
+        (
+            "Measure",
+            [
+                ("survey", "Run the RTLX-S 5-item probe."),
+                ("report", "Print the last-session summary."),
+                ("curve", "Render the Babysitting Tax curve + save PNG."),
+                ("weekly", "Print the weekly digest table."),
+            ],
+        ),
+        (
+            "Inspect",
+            [
+                ("status", "One-screen tier + streak + cognitive snapshot."),
+                ("tips", "Print today's rotating tip."),
+                ("doctor", "Run diagnostic checks against local + API."),
+                ("version", "Print the version banner."),
+            ],
+        ),
+        (
+            "Account",
+            [
+                ("login", "Authenticate the CLI via the browser."),
+                ("logout", "Clear the stored Clerk token."),
+                ("whoami", "Show the identity + tier the API sees."),
+            ],
+        ),
+        (
+            "Setup",
+            [
+                ("onboard", "One command: capture hook + HUD + doctor (start here)."),
+                ("hook install", "Install the Claude Code capture hook."),
+                ("hook status", "Show whether capture is wired up."),
+                ("completion", "Print a bash/zsh/fish completion script."),
+            ],
+        ),
+        (
+            "Billing + metering",
+            [
+                ("billing recommend-tier", "Recommend a tier for N engineers."),
+                ("billing preview-tier", "Show configured Stripe price for (tier, period)."),
+                ("metrics emit", "Record a usage event to the meter."),
+            ],
+        ),
+        (
+            "Session intelligence",
+            [
+                ("ingest", "Ingest coding-agent transcripts into the capture DB."),
+                ("usage", "Rollups + full-text search over ingested transcripts."),
+            ],
+        ),
+        (
+            "Mail + outreach",
+            [
+                ("email check-dns", "Verify SPF/DKIM/DMARC for sending domain."),
+                ("outreach send", "Rolodex-driven outreach via bunmail (dry-run)."),
+                ("outreach invite-interviews", "Mail waitlist signups (dry-run)."),
+            ],
+        ),
+    ]
+    for title, commands in groups:
+        _print(f"  {_color(title, '36', enabled=colors)}")
+        col_width = max(len(name) for name, _ in commands)
+        for name, blurb in commands:
+            _print(f"    {name.ljust(col_width)}  {blurb}")
+        _print("")
+
+
+# Second-level verbs per top-level command, used only by the completion
+# generator (the passthrough commands ingest/usage own their own completion,
+# so they are intentionally flat here).
+_NESTED_COMMANDS: dict[str, tuple[str, ...]] = {
+    "billing": ("recommend-tier", "preview-tier"),
+    "metrics": ("emit",),
+    "hook": ("install", "uninstall", "status", "run"),
+    "hud": ("bar", "install", "uninstall", "status"),
+    "email": ("check-dns",),
+    "outreach": ("send", "invite-interviews"),
+    "completion": ("bash", "zsh", "fish"),
+}
+
+
+def _completion_script(shell: str) -> str:
+    """Return a static completion script for bash/zsh/fish.
+
+    Dependency-free: top-level verbs and their direct sub-verbs are baked in at
+    generation time. Completes the first verb and, for the few nested commands,
+    the second verb. Flags are intentionally left out (they churn and argparse
+    already documents them via --help)."""
+    top = " ".join(TOP_LEVEL_COMMANDS)
+    if shell == "bash":
+        # Build a case arm per nested command so `zeno hook <tab>` completes.
+        nested_arms = "\n".join(
+            f'        {cmd}) COMPREPLY=( $(compgen -W "{" ".join(subs)}"' ' -- "$cur") ); return ;;'
+            for cmd, subs in _NESTED_COMMANDS.items()
+        )
+        return (
+            "# zeno bash completion. Install: zeno completion bash > /etc/bash_completion.d/zeno\n"
+            '# or for one shell:           eval "$(zeno completion bash)"\n'
+            "_zeno_complete() {\n"
+            "    local cur prev words cword\n"
+            '    cur="${COMP_WORDS[COMP_CWORD]}"\n'
+            '    if [ "$COMP_CWORD" -eq 1 ]; then\n'
+            f'        COMPREPLY=( $(compgen -W "{top}" -- "$cur") ); return\n'
+            "    fi\n"
+            '    case "${COMP_WORDS[1]}" in\n'
+            f"{nested_arms}\n"
+            "    esac\n"
+            "}\n"
+            "complete -F _zeno_complete zeno\n"
+        )
+    if shell == "zsh":
+        nested_arms = "\n".join(
+            f"            {cmd}) compadd {' '.join(subs)} ;;"
+            for cmd, subs in _NESTED_COMMANDS.items()
+        )
+        return (
+            "#compdef zeno\n"
+            '# zeno zsh completion. Install: zeno completion zsh > "${fpath[1]}/_zeno"\n'
+            '# or for one shell:          eval "$(zeno completion zsh)"\n'
+            "_zeno() {\n"
+            "    if (( CURRENT == 2 )); then\n"
+            f"        compadd {top}\n"
+            "        return\n"
+            "    fi\n"
+            "    if (( CURRENT == 3 )); then\n"
+            '        case "${words[2]}" in\n'
+            f"{nested_arms}\n"
+            "        esac\n"
+            "    fi\n"
+            "}\n"
+            "compdef _zeno zeno\n"
+        )
+    # fish
+    lines = [
+        "# zeno fish completion. Install:",
+        "#   zeno completion fish > ~/.config/fish/completions/zeno.fish",
+        "# Top-level commands (only when no subcommand is typed yet):",
+    ]
+    for cmd in TOP_LEVEL_COMMANDS:
+        lines.append(f"complete -c zeno -n '__fish_use_subcommand' -a '{cmd}'")
+    for cmd, subs in _NESTED_COMMANDS.items():
+        for sub in subs:
+            lines.append(f"complete -c zeno -n '__fish_seen_subcommand_from {cmd}' -a '{sub}'")
+    return "\n".join(lines) + "\n"
+
+
+def main() -> None:
+    # Pass-through subcommands forward EVERYTHING after the verb (including
+    # --help and leading options) to the folded session-intel sub-CLI. Done
+    # before argparse on purpose: argparse.REMAINDER mishandles a remainder that
+    # starts with an option (e.g. `zeno usage --search x` would route --search to
+    # the top-level parser and error). The subparsers are still registered in
+    # _build_parser so they appear in `zeno --help` and the subcommand index.
+    argv = sys.argv[1:]
+    if argv and argv[0] == "ingest":
+        raise SystemExit(_run_session_intel_passthrough("zeno_session_intel.ingest", argv[1:]))
+    if argv and argv[0] == "usage":
+        raise SystemExit(_run_session_intel_passthrough("zeno_session_intel.analytics", argv[1:]))
+    # `zeno hook run` is fired by Claude Code on every captured event, so handle
+    # it before building the full parser (fast path + clean stdin passthrough). It
+    # execs the bundled cc-bridge hook and never blocks CC.
+    if argv[:2] == ["hook", "run"]:
+        from .hook_install import run as _hook_run  # noqa: PLC0415
+
+        raise SystemExit(_hook_run())
+    # `zeno hud bar` is fired by Claude Code on every statusLine render (the
+    # `zeno hud bar` install form). Handle it before argparse for a fast path +
+    # clean stdin passthrough, exactly like `hook run`. bar_main is crash-safe
+    # (prints an empty line + exit 0 on any error) so it never breaks the host HUD.
+    if argv[:2] == ["hud", "bar"]:
+        from .hud.zeno_hud import bar_main as _bar_main  # noqa: PLC0415
+
+        _bar_main()
+        raise SystemExit(0)
+
+    parser = _build_parser()
+    args = parser.parse_args()
+    if args.command is None:
+        # Zero-args default: print a one-line greeter, then run status,
+        # then a grouped subcommand index. Matches gh / doctl / fly: the
+        # bare CLI invocation should answer "where am I" and "what can I do"
+        # in one screen. See research prompt #24.
+        colors = _colors_enabled()
+        header = _color("zeno", "36", enabled=colors)
+        _print(f"{header} - measure the supervision cost of AI-assisted work.")
+        _print("Run 'zeno --help' for the full command surface.")
+        _print("")
+        exit_code = _run_status(project="default-project", base_url=DEFAULT_API_BASE_URL)
+        _print("")
+        _print_subcommand_index()
+        raise SystemExit(exit_code)
+    if args.command == "survey":
+        raise SystemExit(
+            _run_survey(
+                project=args.project,
+                harness=args.harness,
+                no_probes=args.no_probes,
+                autonomy=args.autonomy,
+                sced_blinded=args.sced,
+                sced_session_index=args.sced_index,
+            )
+        )
+    if args.command == "report":
+        raise SystemExit(_run_report(project=args.project))
+    if args.command == "curve":
+        raise SystemExit(_run_curve(project=args.project, png=args.png))
+    if args.command == "weekly":
+        raise SystemExit(_run_weekly(project=args.project))
+    if args.command == "status":
+        raise SystemExit(_run_status(project=args.project, base_url=args.base_url))
+    if args.command == "tips":
+        raise SystemExit(_run_tips())
+    if args.command == "onboard":
+        raise SystemExit(
+            _run_onboard(
+                base_url=args.base_url,
+                dry_run=args.dry_run,
+                force=args.force,
+                settings_path=args.settings_path,
+                ccstatusline_path=args.ccstatusline_path,
+            )
+        )
+    if args.command == "doctor":
+        raise SystemExit(_run_doctor(base_url=args.base_url))
+    if args.command == "version":
+        raise SystemExit(_run_version())
+    if args.command == "completion":
+        # Write the script raw (not via _print): completion scripts must not be
+        # markup-escaped or rich-styled - they are sourced by the shell verbatim.
+        sys.stdout.write(_completion_script(args.shell))
+        raise SystemExit(0)
+    if args.command == "login":
+        raise SystemExit(
+            _run_login(authorize_url=args.authorize_url, open_browser=not args.no_browser)
+        )
+    if args.command == "logout":
+        raise SystemExit(_run_logout())
+    if args.command == "whoami":
+        raise SystemExit(_run_whoami(base_url=args.base_url))
+    if args.command == "billing":
+        if args.billing_command == "recommend-tier":
+            raise SystemExit(
+                _run_billing_recommend_tier(engineers=args.engineers, base_url=args.base_url)
+            )
+        if args.billing_command == "preview-tier":
+            raise SystemExit(
+                _run_billing_preview_tier(
+                    tier=args.tier, period=args.period, base_url=args.base_url
+                )
+            )
+    if args.command == "metrics":
+        if args.metrics_command == "emit":
+            raise SystemExit(
+                _run_metrics_emit(
+                    event=args.event,
+                    quantity=args.quantity,
+                    metadata=args.metadata,
+                    base_url=args.base_url,
+                )
+            )
+    if args.command == "hook":
+        from . import hook_install  # noqa: PLC0415
+
+        settings_path = (
+            Path(args.settings_path).expanduser()
+            if args.settings_path
+            else hook_install.default_settings_path()
+        )
+        if args.hook_command == "install":
+            raise SystemExit(
+                _run_hook_install(settings_path, force=args.force, with_hud=not args.no_hud)
+            )
+        if args.hook_command == "uninstall":
+            raise SystemExit(_run_hook_uninstall(settings_path, restore=args.restore))
+        if args.hook_command == "status":
+            raise SystemExit(_run_hook_status(settings_path))
+        if args.hook_command == "run":
+            raise SystemExit(hook_install.run())
+    if args.command == "hud":
+        if args.hud_command == "install":
+            raise SystemExit(
+                _run_hud_install(
+                    target=args.target,
+                    dry_run=args.dry_run,
+                    force=args.force,
+                    settings_path=args.settings_path,
+                    ccstatusline_path=args.ccstatusline_path,
+                )
+            )
+        if args.hud_command == "uninstall":
+            raise SystemExit(
+                _run_hud_uninstall(
+                    settings_path=args.settings_path,
+                    ccstatusline_path=args.ccstatusline_path,
+                    restore=args.restore,
+                )
+            )
+        if args.hud_command == "status":
+            raise SystemExit(
+                _run_hud_status(
+                    settings_path=args.settings_path,
+                    ccstatusline_path=args.ccstatusline_path,
+                )
+            )
+        if args.hud_command == "bar":
+            # parity path (the fast-path in main() normally handles `hud bar` first)
+            from .hud.zeno_hud import bar_main as _bar_main  # noqa: PLC0415
+
+            _bar_main()
+            raise SystemExit(0)
+    if args.command == "email":
+        if args.email_command == "check-dns":
+            raise SystemExit(
+                _run_email_check_dns(
+                    domain=args.domain,
+                    dkim_selector=args.dkim_selector,
+                    mail_host=args.mail_host,
+                )
+            )
+    if args.command == "outreach":
+        if args.outreach_command == "send":
+            raise SystemExit(
+                _run_outreach_send(
+                    csv_path=args.csv,
+                    template_id=args.template,
+                    filter_tag=args.filter_tag,
+                    max_sends=args.max_sends,
+                    exclude_recent_days=args.exclude_recent_days,
+                    confirm=args.confirm,
+                )
+            )
+        if args.outreach_command == "invite-interviews":
+            raise SystemExit(
+                _run_invite_interviews(
+                    csv_path=args.csv,
+                    max_invites=args.max_invites,
+                    only_since_days=args.only_since_days,
+                    confirm=args.confirm,
+                )
+            )
+
+
+if __name__ == "__main__":
+    main()