stndp-cli 0.1.0__py3-none-any.whl

stndp/main.py

@@ -0,0 +1,2969 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata
+import json
+import os
+import re
+import secrets
+import subprocess
+import sys
+import tempfile
+import time
+import webbrowser
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+# v0.1.0
+app = typer.Typer(
+    no_args_is_help=True,
+    help=(
+        "stndp — shared, durable memory for engineering teams and their AI agents.\n\n"
+        "New here? Run `stn guide` for the workflow playbook, `stn agent setup` to wire up "
+        "a coding agent, and `stn <command> --help` for any command."
+    ),
+)
+team_app = typer.Typer(no_args_is_help=True)
+app.add_typer(team_app, name="team",
+              help="Manage teams: list, create, invite/remove members, accept invites.")
+workspace_app = typer.Typer(no_args_is_help=True)
+app.add_typer(workspace_app, name="workspace",
+              help="Switch between the workspaces you belong to (list, use, current).")
+decision_app = typer.Typer(no_args_is_help=True)
+app.add_typer(decision_app, name="decision",
+              help="Inspect and curate decisions: show, confirm pending, edit.")
+episode_app = typer.Typer(no_args_is_help=True)
+app.add_typer(episode_app, name="episode",
+              help="Episodic memory: open/close the arc of a unit of work (plan → done → result).")
+bug_app = typer.Typer(no_args_is_help=True)
+app.add_typer(bug_app, name="bug",
+              help="First-class bugs: record and curate symptom → cause → fix → where.")
+ai_app = typer.Typer(no_args_is_help=True)
+app.add_typer(ai_app, name="ai", help="Turn AI draft-assist on or off (opt-in, paid).")
+hooks_app = typer.Typer(no_args_is_help=True)
+app.add_typer(hooks_app, name="hooks",
+              help="Install/remove the git post-commit hook that captures context (stn glob).")
+schedule_app = typer.Typer(no_args_is_help=True)
+app.add_typer(schedule_app, name="schedule",
+              help="Manage standup / checkpoint / resume reminder schedules.")
+graph_app = typer.Typer(no_args_is_help=True)
+app.add_typer(graph_app, name="graph",
+              help="Query the context graph: a node's neighbors or a relation chain.")
+agent_app = typer.Typer(no_args_is_help=True)
+app.add_typer(agent_app, name="agent",
+              help="Set up coding agents (MCP server + rules + SessionStart hook).")
+
+# Force UTF-8 on stdout/stderr so rich glyphs (e.g. the ⚙ agent-authored marker,
+# em dashes, arrows) render instead of crashing with UnicodeEncodeError on a legacy
+# Windows code page (cp1252) when output is piped or redirected. Must run before
+# Console() so rich picks up the utf-8 stream encoding.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):  # non-reconfigurable / already-wrapped stream
+        pass
+
+# legacy_windows=False keeps rich off the Win32 console API (SetConsoleTextAttribute /
+# cp1252 encode), which crashes on non-Latin-1 glyphs regardless of the stream
+# encoding; it emits ANSI to the (now utf-8) stream instead. safe_box avoids a few
+# box glyphs that some terminals can't encode. Together these make output robust on
+# Windows whether piped or attached to a console.
+console = Console(legacy_windows=False, safe_box=True)
+CONFIG_PATH = Path.home() / ".config" / "stndp" / "config.json"
+CACHE_ROOT = Path.home() / ".stndp"
+# Endpoints resolve from the environment (see _resolve_urls): production by
+# default, localhost when STNDP_DEV is set. The web app (Django) serves /auth/*;
+# the API is mounted under /api on the same origin. Locally that single origin is
+# the dev reverse proxy (docker-compose `proxy`, default :8080) — exactly the prod
+# shape, so `STNDP_DEV=1` points at the same /api path the deployed CLI uses.
+# `python dev.py up` writes these explicit URLs (honoring a custom proxy port) to
+# ~/.config/stndp/.env, so STNDP_DEV is just the zero-config default-port shortcut.
+PROD_API_URL = "https://stndp.io/api"
+PROD_WEB_URL = "https://stndp.io"
+# 127.0.0.1, not "localhost": on Windows "localhost" resolves to IPv6 ::1 first, and
+# the dev proxy listens on IPv4 — so every request burns the ~10s connection timeout
+# before falling back. Pinning IPv4 keeps local calls sub-second. (STNDP_API_URL /
+# STNDP_WEB_URL still override for non-standard setups.)
+DEV_API_URL = "http://127.0.0.1:8080/api"
+DEV_WEB_URL = "http://127.0.0.1:8080"
+DEFAULT_CONFIG = {
+    "token": None,
+    "email": None,
+    "user_id": None,
+    "team_id": None,
+    "handle": None,
+    # The workspace (org) the CLI acts in. Sent as the X-Stndp-Workspace header so the
+    # API scopes requests (e.g. which workspace a new team belongs to) to it. Unset →
+    # the server uses the user's current workspace. `stn workspace use` sets these.
+    "workspace_slug": None,
+    "workspace_id": None,
+}
+
+
+def _load_dotenv(path: Path) -> None:
+    """Load KEY=VALUE lines from a .env file into os.environ.
+
+    Mirrors the Django app's loader (standup/settings.py) so the CLI picks up the
+    same convention: a local .env points dev at localhost (STNDP_DEV=1 or explicit
+    STNDP_API_URL/STNDP_WEB_URL), while production relies on real env vars. Real
+    environment variables always win — these are only defaults (setdefault).
+    """
+    if not path.exists():
+        return
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+# Load dev env files at startup from the per-user config dir ONLY. A project-local
+# (CWD) .env is intentionally NOT auto-loaded: the CLI sends a bearer token on
+# every API call (and runs from arbitrary repos, including a git post-commit hook),
+# so a malicious repo could ship a .env pointing STNDP_API_URL at an attacker host
+# and capture the token. Real environment variables still win (setdefault), so
+# `STNDP_DEV=1 stn …` from your shell remains the way to target localhost.
+_load_dotenv(CONFIG_PATH.parent / ".env")
+
+
+def _resolve_urls() -> tuple[str, str]:
+    """API and web base URLs, resolved from the environment.
+
+    Production by default; localhost when STNDP_DEV is set. STNDP_API_URL and
+    STNDP_WEB_URL override either explicitly (e.g. non-standard dev ports).
+    """
+    dev = bool(os.environ.get("STNDP_DEV"))
+    api = os.environ.get("STNDP_API_URL") or (DEV_API_URL if dev else PROD_API_URL)
+    web = os.environ.get("STNDP_WEB_URL") or (DEV_WEB_URL if dev else PROD_WEB_URL)
+    return api, web
+
+
+def _stdin_is_tty() -> bool:
+    """Whether stdin is an interactive terminal. Wrapped so command code can be
+    tested independently of however the test runner wires up stdin."""
+    try:
+        return sys.stdin.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def _require(value: str | None, label: str, *, hint: str) -> str:
+    """Return `value`, or prompt for it interactively.
+
+    When there's no value AND no interactive input (a coding agent, a pipe, a git
+    hook), `typer.prompt` aborts on EOF with no explanation — an opaque failure for an
+    agent. Catch that and exit with an actionable message naming the argument to pass.
+    Interactive humans (and tests that pipe input) still get the normal prompt.
+    """
+    if value:
+        return value
+    try:
+        return typer.prompt(label)
+    except (EOFError, typer.Abort):
+        console.print(f"[red]{label} is required when not running interactively. {hint}[/red]")
+        raise typer.Exit(2) from None
+
+
+VALID_SEVERITIES = ("low", "normal", "high", "critical")
+
+
+def _validate_severity(severity: str | None) -> None:
+    """Reject an unknown severity client-side with a clear message, rather than
+    sending a typo (e.g. 'hgih') that silently loses the high+ immediate-relay
+    behavior the help text promises."""
+    if severity is not None and severity not in VALID_SEVERITIES:
+        console.print(
+            f"[red]Invalid severity {severity!r}. Choose one of: "
+            f"{', '.join(VALID_SEVERITIES)}.[/red]")
+        raise typer.Exit(2)
+
+
+def _safe_filename(*parts: Any) -> str:
+    """A filesystem-safe name from server-supplied parts: strip anything but word
+    chars, dot and dash so a stray path separator (or drive prefix) in an API value
+    can't make an `export` write escape the output directory."""
+    raw = "-".join(str(p) for p in parts)
+    return re.sub(r"[^A-Za-z0-9._-]", "_", raw) or "item"
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Write text atomically (temp file in the same dir + os.replace) so a crash or
+    interrupt mid-write can't leave a truncated file that a later read chokes on."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        try:
+            ver = importlib.metadata.version("stndp-cli")
+        except importlib.metadata.PackageNotFoundError:  # raw source run, not installed
+            ver = "unknown"
+        console.print(ver)
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False, "--version", help="Show the stndp CLI version and exit.",
+        callback=_version_callback, is_eager=True,
+    ),
+) -> None:
+    # Root callback: hosts the global --version option. The app's help text is set
+    # on the Typer() constructor above, so this intentionally has no docstring.
+    ...
+
+
+@app.command()
+def init() -> None:
+    """Create a local CLI config file. Run `stn login` to authenticate."""
+    _save_config({})
+    console.print(f"config written to {CONFIG_PATH}")
+
+
+def _poll_cli_login(config: dict[str, Any], session: str, verifier: str) -> dict[str, Any] | None:
+    """One quiet poll of cli-poll. Returns the JSON dict, or None on any transient
+    error — so a single network blip / 5xx during the polling window doesn't abort
+    the whole login; we keep trying until the overall timeout."""
+    url = f"{config['web_url'].rstrip('/')}/auth/cli-poll"
+    try:
+        resp = httpx.get(url, params={"session": session, "verifier": verifier}, timeout=10)
+        resp.raise_for_status()
+        return resp.json()
+    except (httpx.HTTPError, ValueError):
+        return None
+
+
+@app.command()
+def login() -> None:
+    """Authenticate by opening the browser and completing login on the website."""
+    config = _load_config()
+    # PKCE: send sha256(verifier) on start and present the verifier when polling, so
+    # possession of the browser-visible session id alone can never redeem the token.
+    # The server requires the challenge (a challenge-less start is rejected).
+    verifier = secrets.token_urlsafe(32)
+    challenge = hashlib.sha256(verifier.encode()).hexdigest()
+    response = _web_request("POST", "/auth/cli-start", config=config, json={"challenge": challenge})
+    session = response["session"]
+    # The browser authorize page shows this same code and asks the user to confirm it
+    # matches the one here — the check that stops a phished authorize link from minting
+    # a token for the wrong person. The server returns it; fall back to computing it
+    # locally (sha256(session)[:6], mirroring the server's _cli_user_code) so the code
+    # is always shown even against an older server.
+    user_code = response.get("user_code") or hashlib.sha256(session.encode()).hexdigest()[:6].upper()
+    next_path = quote(f"/auth/cli-complete?session={session}", safe='')
+    login_url = f"{config['web_url'].rstrip('/')}/auth/sign-in?next={next_path}"
+
+    # Show the match code in a box so it's impossible to miss: the browser authorize
+    # page shows the same code and asks the user to confirm it matches the one here —
+    # the check that stops a phished authorize link from approving the wrong person.
+    console.print()
+    console.print(Panel(f"[bold cyan]{user_code}[/bold cyan]",
+                        title="authorize code",
+                        subtitle="this must match the code on the browser page",
+                        expand=False, padding=(0, 3)))
+    console.print("\nOpening your browser to approve this login…")
+    webbrowser.open(login_url)
+    console.print(f"[dim]If it doesn't open, visit:[/dim] {login_url}")
+
+    # A single in-place spinner instead of one "waiting..." line per poll — the
+    # status updates silently until the browser side completes (or we time out).
+    with console.status("Waiting for verification in your browser..."):
+        for _ in range(90):
+            time.sleep(2)
+            poll = _poll_cli_login(config, session, verifier)
+            if poll and poll.get("status") == "ready":
+                _save_auth_response(config, poll)
+                console.print(f"logged in as @{poll['user']['handle']}")
+                return
+
+    console.print("login timed out")
+    raise typer.Exit(1)
+
+
+@app.command()
+def profile(handle: str = typer.Option(..., "--handle")) -> None:
+    """Set display handle."""
+    config = _load_config()
+    response = _web_request("POST", "/auth/profile", config=config, auth=True, json={"handle": handle})
+    _save_auth_response(config, response)
+    console.print(f"handle set to @{response['user']['handle']}")
+
+
+@app.command()
+def whoami() -> None:
+    """Show local CLI identity."""
+    config = _load_config()
+    if not config.get("user_id"):
+        console.print("not logged in — run `stn login`")
+        console.print(f"api: {config['api_url']}")
+        console.print(f"web: {config['web_url']}")
+        return
+    console.print(f"@{config['handle']} user={config['user_id']} team={config['team_id']}")
+    if config.get("email"):
+        console.print(config["email"])
+    if config.get("workspace_slug"):
+        console.print(f"workspace: {config['workspace_slug']}")
+    console.print(f"api: {config['api_url']}")
+    console.print(f"web: {config['web_url']}")
+
+
+@app.command()
+def push(
+    team: str = typer.Argument(..., help="Team slug or name to post to (see `stn team list`)."),
+    content: str | None = typer.Argument(None),
+    blocked: bool | None = typer.Option(
+        None, "--blocked/--no-blocked",
+        help="Flag as a blocker; @mention who's blocking you inline in the text.",
+    ),
+    severity: str | None = typer.Option(
+        None, "--severity",
+        help="Blocker triage: low | normal | high | critical (high+ relays immediately).",
+    ),
+    auto: bool = typer.Option(
+        False, "--auto",
+        help="Draft from your local git activity; you edit & confirm before it posts.",
+    ),
+    from_checkpoint: int | None = typer.Option(
+        None, "--from", help="Promote a checkpoint id into this team update.",
+    ),
+    update: int | None = typer.Option(
+        None, "--update",
+        help="Edit an existing entry id (fix a typo or change its status).",
+    ),
+    replace: bool = typer.Option(
+        False, "--replace",
+        help="With --update: overwrite in place without saving a version (typos).",
+    ),
+    context: bool = typer.Option(
+        False, "--context",
+        help="Attach your current git snapshot (branch/commit) to the update.",
+    ),
+) -> None:
+    """Post today's update to a team — or edit one with --update.
+
+    @mention teammates inline (e.g. "blocked by @alice on x"); every @handle must
+    be a real user or the push is rejected. Add --blocked to mark it a blocker.
+    A normal --update keeps the prior text as a version; --replace discards it.
+    With --auto, an AI draft from your local git activity is offered to edit first.
+    """
+    _validate_severity(severity)
+    if from_checkpoint is not None and update is None and not content:
+        ck = _api_request("GET", f"/v1/checkpoints/{from_checkpoint}")
+        content = ck["focus"]
+    if auto and update is None and not content:
+        if not _stdin_is_tty():
+            # `typer.prompt(default=...)` returns the default WITHOUT confirmation
+            # when stdin isn't a TTY — which would auto-POST a machine-generated
+            # guess unreviewed. A human always approves: refuse to guess here.
+            console.print(
+                "[red]--auto needs an interactive terminal to edit & confirm the "
+                "AI draft. Pass explicit content (`stn push TEAM \"...\"`) when "
+                "running non-interactively.[/red]")
+            raise typer.Exit(2)
+        draft = _api_request("POST", "/v1/drafts",
+                             json={"snapshot": capture_git(), "mode": "standup"})
+        content = typer.prompt("draft (edit & confirm)", default=draft["draft_text"])
+    text = _require(content, "Update", hint='Pass it as an argument: stn push TEAM "your update".')
+    if update is not None:
+        body: dict[str, Any] = {"content": text, "replace": replace}
+        if blocked is not None:        # only touch status when explicitly set
+            body["blocked"] = blocked
+        entry = _api_request("PATCH", f"/v1/entries/{update}", json=body)
+        _write_cache(entry)
+        console.print(_pushed_line(entry, verb="updated"))
+    else:
+        # Stamp with the poster's *local* date — the server clock is UTC, so
+        # without this a late-night push would land on the previous day.
+        json_body: dict[str, Any] = {
+            "content": text, "blocked": bool(blocked), "date": date.today().isoformat(),
+        }
+        if severity:
+            json_body["severity"] = severity
+        if from_checkpoint is not None:
+            json_body["from_checkpoint"] = from_checkpoint
+        if context:
+            json_body["context"] = capture_git()
+        entry = _api_request("POST", "/v1/entries", params={"team": team}, json=json_body)
+        _write_cache(entry)
+        console.print(_pushed_line(entry, verb="posted"))
+
+
+@app.command()
+def block(
+    team: str = typer.Argument(..., help="Team slug or name."),
+    content: str | None = typer.Argument(None, help="What you're blocked on; @mention who can clear it."),
+    severity: str = typer.Option("normal", "--severity", help="low | normal | high | critical."),
+) -> None:
+    """Raise a blocker — an alias for `push --blocked`. high/critical relay immediately."""
+    _validate_severity(severity)
+    text = _require(content, "Blocked on", hint='Pass it as an argument: stn block TEAM "what blocks you".')
+    entry = _api_request(
+        "POST", "/v1/entries", params={"team": team},
+        json={"content": text, "blocked": True, "severity": severity,
+              "date": date.today().isoformat()},
+    )
+    _write_cache(entry)
+    console.print(_pushed_line(entry, verb="posted"))
+
+
+@app.command()
+def resolve(
+    entry_id: int,
+    note: str | None = typer.Argument(None, help="How the block was cleared (required)."),
+    blocker: str | None = typer.Option(
+        None, "--blocker", help="Admin: clear a specific blocker by @handle.",
+    ),
+) -> None:
+    """Clear a block with a note explaining how it was resolved.
+
+    You must be a named blocker (clears your own part) or a team admin (clears any
+    blocker via --blocker, or every remaining one at once). A block with several
+    blockers stays active until each has cleared their part.
+    """
+    text = _require(note, "Resolution note", hint="Pass it as an argument: stn resolve ID \"how it was cleared\".")
+    body: dict[str, Any] = {"content": text}
+    if blocker:
+        body["blocker"] = blocker.lstrip("@")
+    entry = _api_request("POST", f"/v1/entries/{entry_id}/resolve", json=body)
+    remaining = _unresolved_blockers(entry)
+    if remaining:
+        who = ", ".join(f"@{h}" for h in remaining)
+        console.print(f"resolved your part of entry {entry_id} — still blocked by {who}")
+    else:
+        console.print(f"resolved the block on entry {entry_id}")
+
+
+@app.command()
+def unresolve(
+    entry_id: int,
+    blocker: str | None = typer.Option(
+        None, "--blocker", help="Admin: re-open a specific blocker by @handle.",
+    ),
+) -> None:
+    """Re-open a block you previously resolved (drops its resolution note)."""
+    body: dict[str, Any] = {}
+    if blocker:
+        body["blocker"] = blocker.lstrip("@")
+    _api_request("POST", f"/v1/entries/{entry_id}/resolve",
+                 params={"unresolve": True}, json=body)
+    console.print(f"re-opened the block on entry {entry_id}")
+
+
+@app.command()
+def versions(entry_id: int) -> None:
+    """Show an entry's edit history (its superseded versions, oldest first)."""
+    vs = _api_request("GET", f"/v1/entries/{entry_id}/versions")
+    if not vs:
+        console.print(f"entry {entry_id} has no prior versions")
+        return
+    table = Table(box=None)
+    table.add_column("v", justify="right")
+    table.add_column("saved")
+    table.add_column("content")
+    for v in vs:
+        table.add_row(str(v["version_num"]), v["created_at"][:19].replace("T", " "), v["content"])
+    console.print(table)
+
+
+@app.command()
+def log(
+    team: str = typer.Argument(..., help="Team slug or name."),
+    week: bool = False,
+    from_date: str | None = typer.Option(None, "--from"),
+) -> None:
+    """Show your entries in a team."""
+    start = date.today() - timedelta(days=6)
+    if week:
+        today = date.today()
+        start = today - timedelta(days=today.weekday())
+    if from_date:
+        start = _parse_date(from_date)
+    _print_entries(_api_request("GET", "/v1/entries", params={"team": team, "from": start.isoformat()}))
+
+
+@app.command()
+def status(team: str = typer.Argument(..., help="Team slug or name.")) -> None:
+    """Show today's entry in a team."""
+    today = date.today().isoformat()
+    entries = _api_request("GET", "/v1/entries", params={"team": team, "from": today, "to": today})
+    _print_entries(entries)
+
+
+@app.command()
+def edit(
+    entry_id: int,
+    content: str | None = typer.Argument(None),
+    replace: bool = typer.Option(
+        False, "--replace", help="Overwrite without saving a version (for typos).",
+    ),
+) -> None:
+    """Edit an entry. Keeps the prior text as a version unless --replace."""
+    text = _require(content, "Update", hint='Pass it as an argument: stn edit ID "new text".')
+    entry = _api_request("PATCH", f"/v1/entries/{entry_id}",
+                         json={"content": text, "replace": replace})
+    _write_cache(entry)
+    console.print(f"updated entry {entry_id}")
+
+
+@app.command()
+def delete(entry_id: int) -> None:
+    """Delete an entry."""
+    _api_request("DELETE", f"/v1/entries/{entry_id}")
+    console.print(f"deleted entry {entry_id}")
+
+
+@app.command()
+def show(entry_id: int) -> None:
+    """Show a single entry by id, with its block resolutions if any."""
+    _print_feed([_api_request("GET", f"/v1/entries/{entry_id}")])
+
+
+@app.command()
+def inbox(
+    unresolved: bool = typer.Option(
+        False, "--unresolved", "-u",
+        help="Only blocks that name you and that you haven't cleared yet.",
+    ),
+) -> None:
+    """Show entries across your teams that @mention you (things put on you)."""
+    entries = _api_request("GET", "/v1/mentions", params={"unresolved": unresolved})
+    _print_feed(entries)
+
+
+@team_app.command("feed")
+def team_feed(
+    team: str = typer.Argument(..., help="Team slug or name."),
+    week: bool = False,
+) -> None:
+    """Show a team's feed, with each block's resolutions nested beneath it."""
+    entries = _api_request("GET", "/v1/team/feed", params={"team": team, "week": week})
+    _print_feed(entries)
+
+
+@team_app.command("list")
+def team_list() -> None:
+    """List all teams you're part of, with their members."""
+    teams = _api_request("GET", "/v1/teams")
+    if not teams:
+        console.print("no teams")
+        return
+    for team in teams:
+        owner = " (owner)" if team["is_owner"] else ""
+        console.print(f"[bold]~/{team['name']}[/bold]{owner}  id={team['id']}  slug={team['slug']}")
+        table = Table(box=None)
+        table.add_column("member")
+        table.add_column("email")
+        table.add_column("role")
+        table.add_column("status")
+        for member in team["members"]:
+            handle = f"@{member['handle']}" if member["handle"] else "—"
+            table.add_row(handle, member["email"], member["role"], member["status"])
+        console.print(table)
+        console.print("")
+
+
+@team_app.command("use")
+def team_use(team: str = typer.Argument(..., help="Team slug, name, or id to make current.")) -> None:
+    """Set your current team, so team-scoped commands no longer need --team.
+
+    Resolves a slug/name/id against the teams you're in and saves it locally; until
+    now the current team was only ever set at login. `stn whoami` shows the result.
+    """
+    teams = _api_request("GET", "/v1/teams") or []
+    key = team.strip().lstrip("~/").lower()
+    match = next(
+        (t for t in teams
+         if str(t["id"]) == key or str(t.get("slug", "")).lower() == key
+         or str(t.get("name", "")).lower() == key),
+        None,
+    )
+    if match is None:
+        names = ", ".join(t.get("slug") or str(t["id"]) for t in teams) or "(none)"
+        console.print(f"[red]not on a team matching {team!r}. Your teams: {names}[/red]")
+        raise typer.Exit(1)
+    config = _load_config()
+    config["team_id"] = match["id"]
+    config["team_slug"] = match.get("slug")
+    _save_config(config)
+    console.print(f"current team set to ~/{match['name']} (id={match['id']}, slug={match['slug']})")
+
+
+@team_app.command("create")
+def team_create(name: str = typer.Argument(...)) -> None:
+    """Create a team you own."""
+    team = _api_request("POST", "/v1/teams", json={"name": name})
+    console.print(f"created team ~/{team['name']} (id={team['id']}, slug={team['slug']})")
+
+
+# ── workspaces (the org you act in) ───────────────────────────────────────────
+
+@workspace_app.command("list")
+def workspace_list() -> None:
+    """List the workspaces you belong to and your role in each."""
+    workspaces = _api_request("GET", "/v1/workspaces") or []
+    if not workspaces:
+        console.print("no workspaces")
+        return
+    table = Table(box=None)
+    table.add_column("")
+    table.add_column("workspace")
+    table.add_column("slug")
+    table.add_column("role")
+    for w in workspaces:
+        marker = "[green]●[/green]" if w["is_current"] else " "
+        table.add_row(marker, w["name"], w["slug"], w["role"])
+    console.print(table)
+    console.print("[dim]● = current. `stn workspace use <slug>` to switch.[/dim]")
+
+
+@workspace_app.command("current")
+def workspace_current() -> None:
+    """Show the workspace the CLI is acting in."""
+    config = _load_config()
+    slug = config.get("workspace_slug")
+    if slug:
+        console.print(f"workspace: {slug} (id={config.get('workspace_id')})")
+    else:
+        console.print("workspace: (server default — your current workspace)")
+
+
+@workspace_app.command("use")
+def workspace_use(
+    workspace: str = typer.Argument(..., help="Workspace slug, name, or id to switch to."),
+) -> None:
+    """Switch the workspace you act in (web + CLI follow). Resolves a slug/name/id
+    against the workspaces you belong to, sets it as your current workspace server-
+    side, and remembers it locally so requests carry it."""
+    workspaces = _api_request("GET", "/v1/workspaces") or []
+    key = workspace.strip().lower()
+    match = next(
+        (w for w in workspaces
+         if str(w["id"]) == key or str(w.get("slug", "")).lower() == key
+         or str(w.get("name", "")).lower() == key),
+        None,
+    )
+    if match is None:
+        names = ", ".join(w.get("slug") or str(w["id"]) for w in workspaces) or "(none)"
+        console.print(f"[red]no workspace matching {workspace!r}. Yours: {names}[/red]")
+        raise typer.Exit(1)
+    # Persist server-side (so every surface follows) and locally (for the header).
+    result = _api_request("POST", "/v1/workspaces/current", json={"workspace": match["slug"]})
+    config = _load_config()
+    config["workspace_slug"] = result["slug"]
+    config["workspace_id"] = result["id"]
+    _save_config(config)
+    console.print(f"current workspace set to {result['name']} "
+                  f"(slug={result['slug']}, role={result['role']})")
+
+
+@team_app.command("delete")
+def team_delete(
+    team_id: int = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Delete a team you own."""
+    if not yes and not typer.confirm(f"delete team {team_id}?"):
+        raise typer.Exit(0)
+    _api_request("DELETE", f"/v1/teams/{team_id}")
+    console.print(f"deleted team {team_id}")
+
+
+@team_app.command("invite")
+def team_invite(
+    email: str = typer.Argument(...),
+    team_id: int | None = typer.Option(None, "--team", help="Team id (defaults to current team)"),
+) -> None:
+    """Invite a user by email to a team you own."""
+    tid = team_id or _current_team()
+    result = _api_request("POST", f"/v1/teams/{tid}/invites", json={"email": email})
+    kind = "existing user" if result["registered"] else "new user"
+    note = "emailed" if result["notified"] else "pending in-app invite"
+    console.print(f"invited {result['email']} to team {tid} — {kind}, {note}")
+
+
+@team_app.command("remove")
+def team_remove(
+    email: str = typer.Argument(...),
+    team_id: int | None = typer.Option(None, "--team", help="Team id (defaults to current team)"),
+) -> None:
+    """Remove a user by email from a team you own."""
+    tid = team_id or _current_team()
+    _api_request("DELETE", f"/v1/teams/{tid}/members", params={"email": email})
+    console.print(f"removed {email} from team {tid}")
+
+
+@team_app.command("invites")
+def team_invites() -> None:
+    """List pending team invites you've received."""
+    invites = _api_request("GET", "/v1/invites")
+    if not invites:
+        console.print("no pending invites")
+        return
+    table = Table(box=None)
+    table.add_column("team")
+    table.add_column("slug")
+    table.add_column("id", justify="right")
+    table.add_column("role")
+    for invite in invites:
+        table.add_row(f"~/{invite['team_name']}", invite["team_slug"], str(invite["team_id"]), invite["role"])
+    console.print(table)
+    console.print("\naccept with `stn team accept <id>` or decline with `stn team decline <id>`")
+
+
+@team_app.command("accept")
+def team_accept(team_id: int = typer.Argument(..., help="Team id from `stn team invites`.")) -> None:
+    """Accept a pending invite and join the team."""
+    team = _api_request("POST", f"/v1/teams/{team_id}/accept")
+    console.print(f"joined team ~/{team['name']} (id={team['id']}, slug={team['slug']})")
+
+
+@team_app.command("decline")
+def team_decline(team_id: int = typer.Argument(..., help="Team id from `stn team invites`.")) -> None:
+    """Decline a pending invite."""
+    _api_request("POST", f"/v1/teams/{team_id}/decline")
+    console.print(f"declined the invite to team {team_id}")
+
+
+@app.command()
+def checkpoint(
+    text: str | None = typer.Argument(None, help="What you're working on."),
+    reason: str | None = typer.Option(None, "--reason", help="Why you're on this."),
+    next_: str | None = typer.Option(None, "--next", help="Next step (your resume hint)."),
+    team: str | None = typer.Option(None, "--team", help="Team this work is about (optional)."),
+    status: str = typer.Option("active", "--status", help="active | parked | done."),
+    no_context: bool = typer.Option(False, "--no-context", help="Skip local git capture."),
+    shell: bool = typer.Option(False, "--shell", help="Attach recent shell history (opt-in, redacted)."),
+    ai_session: str | None = typer.Option(None, "--ai-session", help="Path to an AI session log to attach."),
+    github: bool = typer.Option(False, "--github", help="Attach GitHub review/commit context via your local gh (network)."),
+    editor: bool = typer.Option(False, "--editor", help="Attach editor context (active/open files from a VSCode extension, plus recently-edited)."),
+    draft: bool = typer.Option(False, "--draft", help="AI-draft the focus from git; you edit & confirm."),
+) -> None:
+    """Save your private working state — with local git context — for `stn resume`.
+
+    Private to you: never posted to any team, no daily cap. Run it at a context
+    switch; reload it later with `stn resume`.
+    """
+    if draft and not text:
+        d = _api_request("POST", "/v1/drafts",
+                        json={"snapshot": None if no_context else capture_git(), "mode": "checkpoint"})
+        text = typer.prompt("draft (edit & confirm)", default=d["draft_text"])
+    focus = _require(text, "Working on", hint='Pass it as an argument: stn checkpoint "what you are on".')
+    body: dict[str, Any] = {"focus": focus, "status": status, "kind": "state"}
+    if reason:
+        body["reason"] = reason
+    if next_:
+        body["next_step"] = next_
+    snap = _capture_context(no_context, shell, ai_session, github, editor)
+    if snap:
+        body["snapshot"] = snap
+    params: dict[str, Any] = {"team": team} if team else {}
+    ep_id = _open_episode_id()
+    if ep_id:
+        params["episode"] = ep_id
+    ckpt = _api_request("POST", "/v1/checkpoints", params=(params or None), json=body)
+    _mirror_checkpoint(ckpt)
+    snap = ckpt.get("snapshot")
+    where = f" on {snap['git_branch']}" if snap and snap.get("git_branch") else ""
+    console.print(f"checkpoint #{ckpt['id']} saved{where}")
+
+
+@app.command()
+def glob(
+    team: str | None = typer.Option(None, "--team", help="Team this work is about (optional)."),
+    no_github: bool = typer.Option(False, "--no-github", help="Skip the GitHub activity capture (no network)."),
+    force: bool = typer.Option(False, "--force", help="Capture even if nothing changed since the last glob."),
+) -> None:
+    """Capture this session's context once — git snapshot, repo, recent commits and your
+    GitHub activity — into the context graph.
+
+    Idempotent: re-running on the same commit/branch the same day is a no-op, so it's
+    safe to wire to session start / a post-login hook. Unlike `checkpoint` it carries no
+    human focus and never surfaces in `stn resume`.
+    """
+    res = _glob_capture(team=team, no_github=no_github, force=force)
+    if res["status"] == "not_a_repo":
+        console.print("not inside a git repo — nothing to glob")
+    elif res["status"] == "skipped":
+        console.print("context unchanged since the last glob — skipped (use --force to re-capture)")
+    else:
+        snid = res.get("snapshot_id")
+        console.print(f"globbed {res['repo']} @ {res.get('branch') or '—'}"
+                      + (f" (snapshot #{snid})" if snid else ""))
+
+
+def _glob_capture(team: str | None = None, no_github: bool = False,
+                  force: bool = False) -> dict[str, Any]:
+    """Capture this session's git/GitHub context as a `kind='glob'` checkpoint, once.
+    Shared by the `glob` CLI command and the MCP `glob` tool. Idempotent per repo via
+    the local glob-state marker; returns a status dict (never prints)."""
+    snap = _capture_context(False, False, None, not no_github, False)
+    if not snap or not (snap.get("repo_name") or snap.get("git_remote_url")):
+        return {"status": "not_a_repo"}
+    key = snap.get("git_remote_url") or snap.get("repo_name") or "repo"
+    cur = {"sha": snap.get("git_commit_sha", ""), "branch": snap.get("git_branch", ""),
+           "dirty": bool(snap.get("git_dirty"))}
+    state = _glob_state_path(key)
+    if not force and _glob_seen(state, cur):
+        return {"status": "skipped", "reason": "unchanged"}
+    body = {
+        "focus": f"session context: {snap.get('repo_name') or key} @ {snap.get('git_branch') or '—'}",
+        "status": "active", "kind": "glob", "snapshot": snap,
+    }
+    params = {"team": team} if team else None
+    ckpt = _api_request("POST", "/v1/checkpoints", params=params, json=body)
+    _glob_record(state, cur)
+    return {"status": "captured", "repo": snap.get("repo_name") or key,
+            "branch": snap.get("git_branch"), "snapshot_id": (ckpt.get("snapshot") or {}).get("id")}
+
+
+def _glob_state_path(key: str) -> Path:
+    """Per-repo local marker of the last globbed context — keyed by a hash of the repo
+    remote/name so the idempotency check never has to hit the network."""
+    return CACHE_ROOT / "glob" / f"{hashlib.sha256(key.encode()).hexdigest()[:16]}.json"
+
+
+def _glob_seen(path: Path, cur: dict[str, Any]) -> bool:
+    """True when this exact (sha, branch, dirty) was already globbed today."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    return (data.get("sha") == cur["sha"] and data.get("branch") == cur["branch"]
+            and data.get("dirty") == cur["dirty"] and data.get("date") == date.today().isoformat())
+
+
+def _glob_record(path: Path, cur: dict[str, Any]) -> None:
+    _atomic_write_text(path, json.dumps({**cur, "date": date.today().isoformat()}))
+
+
+@app.command()
+def resume(
+    team: str | None = typer.Option(None, "--team", help="Scope to one team."),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    offline: bool = typer.Option(False, "--offline", help="Read the last local checkpoint mirror."),
+    github: bool = typer.Option(True, "--github/--no-github", help="Also show your GitHub review queue (gh)."),
+) -> None:
+    """Reload your working state: last checkpoint, the why, next step, open blockers.
+
+    If `gh` is installed, also shows PRs awaiting your review and resolves any
+    GitHub PR links — your live queue, surfaced where you reload context.
+    """
+    if offline:
+        data = _read_mirror()
+    else:
+        params = {"team": team} if team else None
+        data = _api_request("GET", "/v1/resume", params=params)
+        if github and gh_available():
+            data["review_queue"] = gh_review_queue()
+            _resolve_github_links(data.get("links") or [])
+    if json_out:
+        console.print(json.dumps(data, indent=2, default=str))
+        return
+    _render_resume(data, offline=offline)
+
+
+@app.command()
+def timeline(
+    team: str = typer.Argument(..., help="Team slug or name."),
+    days: int = typer.Option(14, "--days", help="How far back to look."),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable output."),
+) -> None:
+    """A unified, time-ordered feed of your recent context in a team — your entries
+    and checkpoints plus the team's decisions, episodes and bugs, merged into one
+    timeline (the CLI view of the dashboard timeline). The merge happens server-side
+    (one request), so this stays fast no matter how much context a team accumulates."""
+    rows = _api_request("GET", "/v1/timeline", params={"team": team, "days": days}) or []
+    if json_out:
+        print(json.dumps(rows, indent=2))
+        return
+    if not rows:
+        console.print("(nothing in this window)")
+        return
+    for row in rows:
+        at, typ, text = row.get("at", ""), row.get("type", ""), row.get("text", "")
+        head = ((text or "").strip().splitlines() or [""])[0][:100]
+        console.print(f"[dim]{at[:10]}[/dim]  [cyan]{typ:<14}[/cyan] {head}")
+
+
+def _repo_from_url(url: str) -> str | None:
+    m = re.search(r"github\.com/([\w.-]+/[\w.-]+)/pull/", url or "")
+    return m.group(1) if m else None
+
+
+def _resolve_github_links(links: list[dict[str, Any]]) -> None:
+    """Fill title/state on github PR links via the local gh (surface #4)."""
+    for lk in links:
+        if str(lk.get("provider", "")).startswith("github") and not lk.get("title"):
+            pr = gh_pr(lk.get("external_id", ""), _repo_from_url(lk.get("url", "")))
+            if pr:
+                lk["title"] = pr.get("title", "")
+                lk["state"] = pr.get("state", "")
+
+
+@app.command()
+def dump(
+    text: str | None = typer.Argument(None, help="A quick private note."),
+    show: bool = typer.Option(False, "--show", help="Show your recent notes."),
+    since: str | None = typer.Option(None, "--from", help="YYYY-MM-DD (with --show)."),
+) -> None:
+    """Jot a private note — a contextless checkpoint, visible only to you. Use it to
+    capture progress through the day, then frame your real `stn push` later."""
+    if show:
+        params: dict[str, Any] = {"kind": "note"}
+        if since:
+            params["since"] = _parse_date(since).isoformat()
+        items = _api_request("GET", "/v1/checkpoints", params=params)
+        if not items:
+            console.print("no notes")
+            return
+        for c in items:
+            when = str(c.get("created_at", ""))[:16].replace("T", " ")
+            console.print(f"[dim]{when}[/dim] {c['focus']}")
+        return
+    note = _require(text, "Note", hint='Pass it as an argument: stn dump "your note".')
+    c = _api_request("POST", "/v1/checkpoints", json={"focus": note, "kind": "note"})
+    console.print(f"noted (#{c['id']})")
+
+
+@app.command()
+def checkpoints(
+    team: str | None = typer.Option(None, "--team"),
+    since: str | None = typer.Option(None, "--since", help="YYYY-MM-DD"),
+) -> None:
+    """List your recent checkpoints (most recent first)."""
+    params: dict[str, Any] = {}
+    if team:
+        params["team"] = team
+    if since:
+        params["since"] = _parse_date(since).isoformat()
+    _print_checkpoints(_api_request("GET", "/v1/checkpoints", params=params or None))
+
+
+@schedule_app.command("list")
+def schedule_list(
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+) -> None:
+    """Show the reminders that apply to you on a team: team defaults + your overrides."""
+    tid = team or str(_current_team())
+    rows = _api_request("GET", "/v1/schedules", params={"team": tid})
+    if not rows:
+        console.print("no reminders set")
+        return
+    table = Table(box=None, pad_edge=False)
+    for col in ("id", "kind", "at", "days", "tz", "scope", "on"):
+        table.add_column(col)
+    for r in rows:
+        table.add_row(str(r["id"]), r["kind"], r["at"], r["days"], r["tz"],
+                      r["scope"], "yes" if r["enabled"] else "no")
+    console.print(table)
+
+
+@schedule_app.command("set")
+def schedule_set(
+    kind: str = typer.Argument(..., help="standup | blocker | checkpoint | resume"),
+    at: str = typer.Option(..., "--at", help="Local fire time, HH:MM (24h)."),
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+    days: str = typer.Option("0,1,2,3,4", "--days", help="Weekday ints, Mon=0..Sun=6."),
+    tz: str = typer.Option("UTC", "--tz", help="IANA timezone for the fire time."),
+    team_wide: bool = typer.Option(False, "--team-wide", help="Set the team default (admin only)."),
+) -> None:
+    """Set (or update) a reminder. `checkpoint` nudges you at EOD to capture state;
+    `resume` nudges you in the morning to reload it."""
+    tid = team or str(_current_team())
+    body = {"kind": kind, "at": at, "days": days, "tz": tz,
+            "scope": "team" if team_wide else "user", "enabled": True}
+    s = _api_request("POST", "/v1/schedules", params={"team": tid}, json=body)
+    console.print(f"{s['kind']} reminder set for {s['at']} {s['tz']} ({s['scope']})")
+
+
+def _toggle_schedule(team: str | None, kind: str, enabled: bool, team_wide: bool) -> None:
+    tid = team or str(_current_team())
+    scope = "team" if team_wide else "user"
+    rows = _api_request("GET", "/v1/schedules", params={"team": tid})
+    match = next((r for r in rows if r["kind"] == kind and r["scope"] == scope), None)
+    if match is None:
+        console.print(f"[red]no {scope} {kind} reminder to change[/red]")
+        raise typer.Exit(1)
+    _api_request("POST", "/v1/schedules", params={"team": tid},
+                 json={"kind": kind, "at": match["at"], "days": match["days"],
+                       "tz": match["tz"], "scope": scope, "enabled": enabled})
+    console.print(f"{kind} reminder {'on' if enabled else 'off'}")
+
+
+@schedule_app.command("off")
+def schedule_off(
+    kind: str = typer.Argument(..., help="standup | blocker | checkpoint | resume"),
+    team: str | None = typer.Option(None, "--team"),
+    team_wide: bool = typer.Option(False, "--team-wide"),
+) -> None:
+    """Pause a reminder without deleting it (keeps the time for later)."""
+    _toggle_schedule(team, kind, False, team_wide)
+
+
+@schedule_app.command("on")
+def schedule_on(
+    kind: str = typer.Argument(..., help="standup | blocker | checkpoint | resume"),
+    team: str | None = typer.Option(None, "--team"),
+    team_wide: bool = typer.Option(False, "--team-wide"),
+) -> None:
+    """Re-enable a paused reminder."""
+    _toggle_schedule(team, kind, True, team_wide)
+
+
+@schedule_app.command("remove")
+def schedule_remove(
+    schedule_id: int = typer.Argument(..., help="Reminder id (from `stn schedule list`)."),
+) -> None:
+    """Delete a reminder rule by id."""
+    _api_request("DELETE", f"/v1/schedules/{schedule_id}")
+    console.print("removed")
+
+
+@app.command()
+def decide(
+    title: str = typer.Argument(..., help="The decision, in one line."),
+    why: str | None = typer.Option(None, "--why", help="The rationale / body."),
+    kind: str = typer.Option("decision", "--kind", help="decision | learning."),
+    tag: list[str] = typer.Option([], "--tag", help="Tag (repeatable)."),
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+    supersedes: int | None = typer.Option(None, "--supersedes", help="Decision id this revises."),
+) -> None:
+    """Log a durable, team-visible decision or learning — searchable later.
+
+    @mention teammates inline in the rationale; the title is the one-liner, the
+    --why is the trade-offs. A --supersedes revises an earlier decision.
+    """
+    body = _require(why, "Why (rationale)", hint='Pass it with --why: stn decide "the choice" --why "the rationale".')
+    tid = team or str(_current_team())
+    payload: dict[str, Any] = {"title": title, "body": body, "kind": kind, "tags": list(tag)}
+    if supersedes:
+        payload["supersedes_id"] = supersedes
+    params: dict[str, Any] = {"team": tid}
+    ep_id = _open_episode_id()
+    if ep_id:
+        params["episode"] = ep_id
+    d = _api_request("POST", "/v1/decisions", params=params, json=payload)
+    console.print(f"logged decision #{d['id']}: {d['title']}")
+    if d.get("nudge"):
+        console.print(f"[yellow]nudge:[/yellow] {d['nudge']}")
+
+
+@app.command()
+def decisions(
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+    tag: str | None = typer.Option(None, "--tag"),
+    kind: str | None = typer.Option(None, "--kind"),
+    mine: bool = typer.Option(False, "--mine"),
+    agent: bool = typer.Option(False, "--agent", help="Only agent-authored decisions, for review."),
+    pending: bool = typer.Option(False, "--pending", help="Only decisions awaiting confirmation."),
+) -> None:
+    """List a team's decisions (most recent first). Use --agent or --pending to
+    review what your coding agents logged and confirm it with `stn decision confirm`."""
+    tid = team or str(_current_team())
+    params: dict[str, Any] = {"team": tid, "mine": mine, "agent": agent, "pending": pending}
+    if tag:
+        params["tag"] = tag
+    if kind:
+        params["kind"] = kind
+    _print_decisions(_api_request("GET", "/v1/decisions", params=params))
+
+
+@decision_app.command("show")
+def decision_show(decision_id: int) -> None:
+    """Show a single decision with its full rationale."""
+    _print_decision_full(_api_request("GET", f"/v1/decisions/{decision_id}"))
+
+
+@decision_app.command("confirm")
+def decision_confirm(decision_id: int) -> None:
+    """Confirm a pending (agent-authored or auto-extracted) decision — promote it
+    from a suggestion into the team's record. See `stn decisions --pending`."""
+    d = _api_request("POST", f"/v1/decisions/{decision_id}/confirm")
+    console.print(f"confirmed decision #{d['id']}: {d['title']}")
+
+
+@decision_app.command("edit")
+def decision_edit(
+    decision_id: int,
+    body: str | None = typer.Argument(None, help="New rationale text."),
+    title: str | None = typer.Option(None, "--title"),
+    replace: bool = typer.Option(False, "--replace", help="Don't keep a version (typos)."),
+) -> None:
+    """Edit a decision; keeps the prior text as a version unless --replace."""
+    payload: dict[str, Any] = {"replace": replace}
+    if title is not None:
+        payload["title"] = title
+    if body is not None:
+        payload["body"] = body
+    if "body" not in payload and "title" not in payload:
+        payload["body"] = typer.prompt("New rationale")
+    d = _api_request("PATCH", f"/v1/decisions/{decision_id}", json=payload)
+    console.print(f"updated decision #{d['id']}")
+
+
+# ── Episodes (the arc of a unit of work: plan → done → result) ───────────────
+@episode_app.command("start")
+def episode_start(
+    title: str = typer.Argument(..., help="The unit of work, in one line."),
+    plan: str | None = typer.Option(None, "--plan", help="What you intend to do (& why)."),
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+) -> None:
+    """Open an episode — the arc of one non-trivial unit of work (plan → done → result).
+
+    Reserved for genuine multi-step work whose plan→done delta is worth keeping; most
+    work needs none — a lone decision or bug should be recorded standalone. Private
+    while open; `stn episode close` promotes it to team-visible. Checkpoints/decisions
+    /bugs recorded while it's open auto-attach to it."""
+    tid = team or str(_current_team())
+    payload: dict[str, Any] = {"title": title}
+    if plan:
+        payload["plan"] = plan
+    ep = _api_request("POST", "/v1/episodes", params={"team": tid}, json=payload)
+    _set_open_episode(ep)
+    console.print(f"opened episode #{ep['id']}: {ep['title']} [dim](private until closed)[/dim]")
+
+
+@episode_app.command("close")
+def episode_close(
+    episode_id: int,
+    did: str | None = typer.Option(None, "--did", help="What actually happened."),
+    result: str | None = typer.Option(None, "--result", help="The observable result."),
+    surprise: str | None = typer.Option(
+        None, "--surprise", help="What changed from the plan — the learning."),
+) -> None:
+    """Close an episode and promote it to team-visible: record outcome, result, and the
+    surprise (the plan→done delta — the durable learning)."""
+    payload: dict[str, Any] = {}
+    if did is not None:
+        payload["outcome"] = did
+    if result is not None:
+        payload["result"] = result
+    if surprise is not None:
+        payload["surprise"] = surprise
+    ep = _api_request("POST", f"/v1/episodes/{episode_id}/close", json=payload)
+    _clear_open_episode(episode_id)
+    flag = " [yellow](outcome pending confirmation)[/yellow]" if ep.get("pending") else ""
+    console.print(f"closed episode #{ep['id']} — now team-visible{flag}")
+
+
+@episode_app.command("abandon")
+def episode_abandon(episode_id: int) -> None:
+    """Abandon an open episode — it stays private (it never became shared memory)."""
+    ep = _api_request("POST", f"/v1/episodes/{episode_id}/abandon")
+    _clear_open_episode(episode_id)
+    console.print(f"abandoned episode #{ep['id']}")
+
+
+@episode_app.command("confirm")
+def episode_confirm(episode_id: int) -> None:
+    """Confirm an episode's agent-asserted outcome/result (clears the pending flag)."""
+    ep = _api_request("POST", f"/v1/episodes/{episode_id}/confirm")
+    console.print(f"confirmed episode #{ep['id']}: {ep['title']}")
+
+
+@episode_app.command("show")
+def episode_show(episode_id: int) -> None:
+    """Show one episode's full arc (plan → outcome → result → surprise)."""
+    _print_episode_full(_api_request("GET", f"/v1/episodes/{episode_id}"))
+
+
+@app.command()
+def episodes(
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+    open_: bool = typer.Option(False, "--open", help="Only open episodes."),
+    mine: bool = typer.Option(False, "--mine"),
+    pending: bool = typer.Option(False, "--pending", help="Only episodes awaiting confirmation."),
+) -> None:
+    """List a team's episodes (most recent first). Open ones are private to you until
+    closed; closed ones are team-visible shared memory."""
+    tid = team or str(_current_team())
+    params: dict[str, Any] = {"team": tid, "mine": mine, "pending": pending}
+    if open_:
+        params["status"] = "open"
+    _print_episodes(_api_request("GET", "/v1/episodes", params=params))
+
+
+# ── Bugs (first-class symptom → root cause → fix → where) ────────────────────
+@bug_app.command("add")
+def bug_add(
+    symptom: str = typer.Argument(..., help="What went wrong (the observed symptom)."),
+    cause: str | None = typer.Option(None, "--cause", help="Root cause."),
+    fix: str | None = typer.Option(None, "--fix", help="How it was fixed."),
+    where: str | None = typer.Option(None, "--where", help="File / commit / area."),
+    episode: int | None = typer.Option(
+        None, "--episode", help="Attach to this episode (defaults to the open one)."),
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+) -> None:
+    """Record a bug hit (and usually fixed) during the work — team-visible memory a
+    future agent can search by {symptom, cause, fix, where}. Defaults to 'fixed' when
+    a --fix is given, else 'open'."""
+    tid = team or str(_current_team())
+    payload: dict[str, Any] = {"symptom": symptom}
+    if cause is not None:
+        payload["root_cause"] = cause
+    if fix is not None:
+        payload["fix"] = fix
+    if where is not None:
+        payload["where_ref"] = where
+    payload["episode_id"] = episode if episode is not None else _open_episode_id()
+    b = _api_request("POST", "/v1/bugs", params={"team": tid}, json=payload)
+    console.print(f"logged bug #{b['id']} [dim]({b['status']})[/dim]: {b['symptom'][:60]}")
+
+
+@bug_app.command("list")
+def bug_list(
+    team: str | None = typer.Option(None, "--team", help="Team (defaults to current)."),
+    open_: bool = typer.Option(False, "--open", help="Only open (unfixed) bugs."),
+    pending: bool = typer.Option(False, "--pending", help="Only bugs awaiting confirmation."),
+    episode: int | None = typer.Option(None, "--episode", help="Only bugs in this episode."),
+) -> None:
+    """List a team's bugs (most recent first)."""
+    tid = team or str(_current_team())
+    params: dict[str, Any] = {"team": tid, "pending": pending}
+    if open_:
+        params["status"] = "open"
+    if episode is not None:
+        params["episode"] = episode
+    _print_bugs(_api_request("GET", "/v1/bugs", params=params))
+
+
+@bug_app.command("fix")
+def bug_fix(
+    bug_id: int,
+    fix: str | None = typer.Argument(None, help="How it was fixed."),
+    cause: str | None = typer.Option(None, "--cause", help="Root cause."),
+) -> None:
+    """Mark a bug fixed, recording the fix (and optionally the root cause)."""
+    payload: dict[str, Any] = {"status": "fixed"}
+    if fix is not None:
+        payload["fix"] = fix
+    if cause is not None:
+        payload["root_cause"] = cause
+    b = _api_request("PATCH", f"/v1/bugs/{bug_id}", json=payload)
+    console.print(f"fixed bug #{b['id']}")
+
+
+@bug_app.command("confirm")
+def bug_confirm(bug_id: int) -> None:
+    """Confirm a bug's agent-asserted root cause/fix (clears the pending flag)."""
+    b = _api_request("POST", f"/v1/bugs/{bug_id}/confirm")
+    console.print(f"confirmed bug #{b['id']}")
+
+
+@bug_app.command("show")
+def bug_show(bug_id: int) -> None:
+    """Show one bug in full (symptom → cause → fix → where)."""
+    _print_bug_full(_api_request("GET", f"/v1/bugs/{bug_id}"))
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="What to find."),
+    type_: str | None = typer.Option(
+        None, "--type",
+        help="Restrict to one kind: decision | entry | checkpoint | repo | workitem "
+             "| file | user | team | … (any entity type the server can return).",
+    ),
+    team: str | None = typer.Option(None, "--team"),
+    since: str | None = typer.Option(None, "--since", help="YYYY-MM-DD"),
+    limit: int = typer.Option(20, "--limit"),
+    semantic: bool = typer.Option(
+        True, "--semantic/--keyword",
+        help="Blend semantic ranking when available (--keyword for exact-match only).",
+    ),
+) -> None:
+    """Search everything you can reach — decisions, entries, your checkpoints, and
+    (when the server has it on) every other entity by identity: repos, work items,
+    files, people, teams … — with the connected context (tickets/PRs, supersession)
+    shown beneath each hit."""
+    params: dict[str, Any] = {"q": query, "limit": limit, "semantic": semantic}
+    if type_:
+        params["type"] = type_
+    if team:
+        params["team"] = team
+    if since:
+        params["since"] = _parse_date(since).isoformat()
+    _print_search(_api_request("GET", "/v1/search", params=params))
+
+
+@app.command()
+def brag(
+    period: str = typer.Option("monthly", "--period", help="weekly | monthly | quarterly."),
+    from_: str | None = typer.Option(None, "--from"),
+    to: str | None = typer.Option(None, "--to"),
+    team: str | None = typer.Option(None, "--team"),
+    github: bool = typer.Option(True, "--github/--no-github", help="Include GitHub reviews + commits (gh)."),
+    narrate: bool = typer.Option(
+        False, "--narrate",
+        help="Narrate your accomplishments into connective prose with AI (paid + `stn ai on`).",
+    ),
+) -> None:
+    """Generate a brag doc (Markdown) of your work over a period — for 1:1s/reviews.
+
+    With `gh` installed, adds the PRs you reviewed and the commits you authored in
+    the period — review work that's invisible to a commit-only brag. With --narrate,
+    your own accomplishments are rewritten into a short prose summary by AI (gated to
+    paid + opt-in; the draft is yours to edit, never auto-shared).
+    """
+    params: dict[str, Any] = {}
+    if from_:
+        params["from"] = _parse_date(from_).isoformat()
+    else:
+        days = {"weekly": 7, "monthly": 30, "quarterly": 90}.get(period, 30)
+        params["from"] = (date.today() - timedelta(days=days)).isoformat()
+    if to:
+        params["to"] = _parse_date(to).isoformat()
+    if team:
+        params["team"] = team
+    md = _brag_markdown(_api_request("GET", "/v1/brag", params=params))
+    if github and gh_available():
+        since = params["from"]
+        md += "\n\n" + _brag_github_markdown(gh_reviewed(since=since), gh_my_commits(since=since))
+    if narrate:
+        draft = _api_request("POST", "/v1/drafts", json={"mode": "brag", "text": md})
+        console.print(f"*(AI-narrated from your activity — review before sharing)*\n\n"
+                      f"{draft['draft_text']}")
+        return
+    console.print(md)
+
+
+@app.command()
+def token(
+    name: str = typer.Argument(..., help="A label for the token."),
+    scope: list[str] = typer.Option(["decisions:read", "entries:read"], "--scope",
+                                    help="Read scope (repeatable)."),
+) -> None:
+    """Create a scoped API token for programmatic read access (shown once)."""
+    t = _api_request("POST", "/v1/tokens", json={"name": name, "scopes": list(scope)})
+    console.print(f"created token [bold]{t['name']}[/bold] — copy it now, it won't be shown again:")
+    console.print(f"  {t['token']}")
+
+
+@app.command()
+def tokens() -> None:
+    """List your API tokens (prefixes only)."""
+    items = _api_request("GET", "/v1/tokens")
+    if not items:
+        console.print("no API tokens")
+        return
+    table = Table(box=None)
+    table.add_column("id", justify="right")
+    table.add_column("name")
+    table.add_column("prefix")
+    table.add_column("scopes")
+    table.add_column("revoked")
+    for t in items:
+        table.add_row(str(t["id"]), t["name"], t["prefix"] + "…",
+                      ",".join(t.get("scopes") or []), "yes" if t.get("revoked") else "")
+    console.print(table)
+
+
+@ai_app.command("on")
+def ai_on() -> None:
+    """Enable AI draft-assist for your account (off by default)."""
+    _api_request("POST", "/v1/ai/optin", json={"enabled": True})
+    console.print("AI draft-assist enabled — try `stn push --auto`")
+
+
+@ai_app.command("off")
+def ai_off() -> None:
+    """Disable AI draft-assist for your account."""
+    _api_request("POST", "/v1/ai/optin", json={"enabled": False})
+    console.print("AI draft-assist disabled")
+
+
+@app.command()
+def link(
+    object_id: int = typer.Argument(..., help="The entry / checkpoint / decision id."),
+    ref: str = typer.Argument(..., help="Ticket key (PROJ-123), a PR url, or any url."),
+    type_: str = typer.Option("entry", "--type", help="entry | checkpoint | decision."),
+) -> None:
+    """Attach an external object (ticket/PR/url) to an entry, checkpoint, or decision."""
+    linked = _api_request("POST", "/v1/links",
+                          json={"object_type": type_, "object_id": object_id, "ref": ref})
+    console.print(f"linked {linked['provider']}:{linked['external_id']} to {type_} #{object_id}")
+
+
+@app.command()
+def repos() -> None:
+    """List the repos your work touches — the codebase axis of the context graph."""
+    data = _api_request("GET", "/v1/repos")
+    if not data:
+        console.print("(no repos yet — capture work with git context: stn checkpoint)")
+        return
+    for r in data:
+        console.print(f"  #{r['id']}  [bold]{r['full_name']}[/bold]  [dim]{r['host']}[/dim]")
+
+
+@app.command()
+def repo(repo_id: int = typer.Argument(..., help="Repo id (from `stn repos`).")) -> None:
+    """Show a repo: branches, the tracker projects it tracks (with mapping confidence),
+    and the work connected to it."""
+    data = _api_request("GET", f"/v1/repos/{repo_id}")
+    console.print(f"[bold]{data['full_name']}[/bold]  [dim]{data['canonical_url']}[/dim]")
+    for p in data.get("projects", []):
+        conf = p.get("mapping_confidence") or "?"
+        console.print(f"  ~ tracks {p['provider']}:{p['key'] or p['name']} ({conf})")
+    if data.get("branches"):
+        console.print("  branches: " + ", ".join(b["name"] for b in data["branches"][:20]))
+    edges = [e for e in (data.get("neighbors") or {}).get("edges", [])
+             if e["direction"] == "in" and e["rel"] == "in_repo"]
+    for e in edges:
+        console.print(f"  - {e['node_type']} #{e['node_id']} {e.get('label', '')}")
+
+
+@app.command()
+def projects() -> None:
+    """List the tracker projects (Jira/ClickUp/Monday/Linear/…) you can see."""
+    data = _api_request("GET", "/v1/projects")
+    if not data:
+        console.print("(no tracker projects yet)")
+        return
+    for p in data:
+        console.print(f"  #{p['id']}  [bold]{p['name'] or p['key']}[/bold]  [dim]{p['provider']}[/dim]")
+
+
+@app.command()
+def project(
+    project_id: int = typer.Argument(..., help="Project id (from `stn projects`)."),
+) -> None:
+    """Show a tracker project: its work items and the repos that track it."""
+    data = _api_request("GET", f"/v1/projects/{project_id}")
+    console.print(f"[bold]{data['name'] or data['key']}[/bold]  [dim]{data['provider']}[/dim]")
+    if data.get("repos"):
+        console.print("  repos: " + ", ".join(r["full_name"] for r in data["repos"]))
+    for w in data.get("work_items", []):
+        state = f" ({w['state']})" if w.get("state") else ""
+        console.print(f"  - {w['external_id']}{state} {w.get('title', '')}")
+
+
+@app.command("files")
+def files(
+    repo_id: int = typer.Argument(..., help="Repo id (from `stn repos`)."),
+    prefix: str = typer.Option("", "--prefix", help="Directory to list ('' = repo root)."),
+) -> None:
+    """Browse a repo's file tree — sub-directories and files under a directory (Act V)."""
+    data = _api_request("GET", "/v1/files", params={"repo": repo_id, "prefix": prefix})
+    dirs, fs = data.get("directories", []), data.get("files", [])
+    if not dirs and not fs:
+        console.print("(no files indexed here yet — capture work with git context: stn checkpoint)")
+        return
+    for d in dirs:
+        console.print(f"  [bold]{d['path']}/[/bold]")
+    for f in fs:
+        console.print(f"  #{f['id']}  {f['path']}")
+
+
+@app.command("file-context")
+def file_context(
+    path: str = typer.Argument(..., help="Repo-relative file/dir path, or path#symbol."),
+    repo_id: int | None = typer.Option(None, "--repo", help="Repo id; omit to match any visible repo."),
+    limit: int = typer.Option(20, "--limit", help="Max touchers to show."),
+) -> None:
+    """Show what's known about a file: decisions, who touched it and why, linked PRs/tickets."""
+    params: dict[str, Any] = {"path": path, "limit": limit}
+    if repo_id is not None:
+        params["repo"] = repo_id
+    data = _api_request("GET", "/v1/files/context", params=params)
+    kind = "directory" if data.get("is_directory") else "file"
+    sym = f"#{data['symbol']}" if data.get("symbol") else ""
+    console.print(f"[bold]{data['path'] or '/'}{sym}[/bold]  [dim]{kind}, "
+                  f"{data.get('file_count', 0)} file(s)[/dim]")
+    items = data.get("items", [])
+    if not items:
+        console.print("  (no recorded context yet)")
+        return
+    for it in items:
+        who = f"@{it['handle']}" if it.get("handle") else it["type"]
+        s = f" [{it['symbol']}]" if it.get("symbol") else ""
+        console.print(f"  - {it['type']} #{it['id']}{s} [dim]{who}[/dim] {it.get('title', '')}")
+        for e in (it.get("context") or {}).get("edges", []):
+            if e["node_type"] in ("decision", "workitem"):
+                console.print(f"      → {e['rel']} {e['node_type']} #{e['node_id']} {e.get('label', '')}")
+        for lk in (it.get("context") or {}).get("links", []):
+            console.print(f"      ~ {lk['provider']}:{lk['external_id']} {lk.get('title', '')}")
+
+
+@graph_app.command("neighbors")
+def graph_neighbors(
+    type_: str = typer.Argument(..., help="entry | decision | checkpoint."),
+    node_id: int = typer.Argument(..., help="The node id."),
+    rel: str | None = typer.Option(None, "--rel", help="Filter to one relation."),
+) -> None:
+    """Show what's connected to a node — linked decisions/entries and external tickets/PRs."""
+    params: dict[str, Any] = {"type": type_, "id": node_id}
+    if rel:
+        params["rel"] = rel
+    data = _api_request("GET", "/v1/graph/neighbors", params=params)
+    label = data.get("label") or ""
+    console.print(f"[bold]{data['type']} #{data['id']}[/bold] {label}")
+    if not data["edges"] and not data["links"]:
+        console.print("  (no connections yet)")
+        return
+    for e in data["edges"]:
+        arrow = "->" if e["direction"] == "out" else "<-"
+        console.print(f"  {arrow} {e['rel']} {e['node_type']} #{e['node_id']} {e.get('label', '')}")
+    for lk in data["links"]:
+        state = f" [{lk['state']}]" if lk.get("state") else ""
+        console.print(f"  ~ {lk['provider']}:{lk['external_id']}{state} {lk.get('title', '')}")
+
+
+@graph_app.command("path")
+def graph_path(
+    type_: str = typer.Argument(..., help="entry | decision | checkpoint."),
+    node_id: int = typer.Argument(..., help="The node id."),
+    rel: str = typer.Option("supersedes", "--rel", help="Relation to follow."),
+    depth: int = typer.Option(10, "--depth", help="Max hops to walk."),
+) -> None:
+    """Walk a chain of one relation (e.g. a decision's supersession history)."""
+    data = _api_request("GET", "/v1/graph/path",
+                        params={"type": type_, "id": node_id, "rel": rel, "depth": depth})
+    if not data:
+        console.print("(no chain)")
+        return
+    for n in data:
+        console.print(f"  {n['depth']}. {n['type']} #{n['id']} {n.get('label', '')}")
+
+
+_HOOK_MARKER = "# stndp ambient capture"
+
+
+@hooks_app.command("install")
+def hooks_install() -> None:
+    """Install a post-commit hook that captures each commit's context into the graph.
+
+    Runs `stn glob` after every commit — anchoring the commit/branch/repo to the
+    context platform (the same capture `agent setup`'s SessionStart hook performs).
+    `glob` is idempotent per commit, so it only writes new context. (Earlier versions
+    wrote to a local-only log via `stn capture`, which never reached the server.)
+    """
+    git_dir = _git(["rev-parse", "--absolute-git-dir"], str(Path.cwd()))
+    if not git_dir:
+        console.print("not a git repository")
+        raise typer.Exit(1)
+    hooks_dir = Path(git_dir) / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook = hooks_dir / "post-commit"
+    if hook.exists() and _HOOK_MARKER not in hook.read_text(encoding="utf-8", errors="replace"):
+        console.print(f"a post-commit hook already exists at {hook}; not overwriting")
+        raise typer.Exit(1)
+    hook.write_text(
+        f"#!/bin/sh\n{_HOOK_MARKER}\nstn glob --no-github >/dev/null 2>&1 || true\n",
+        encoding="utf-8",
+    )
+    try:
+        hook.chmod(0o755)
+    except OSError:
+        pass
+    console.print(f"installed post-commit context capture (stn glob) at {hook}")
+
+
+@hooks_app.command("uninstall")
+def hooks_uninstall() -> None:
+    """Remove the stndp post-commit hook."""
+    git_dir = _git(["rev-parse", "--absolute-git-dir"], str(Path.cwd()))
+    if not git_dir:
+        console.print("not a git repository")
+        raise typer.Exit(1)
+    hook = Path(git_dir) / "hooks" / "post-commit"
+    if hook.exists() and _HOOK_MARKER in hook.read_text(encoding="utf-8", errors="replace"):
+        hook.unlink()
+        console.print("removed ambient capture hook")
+    else:
+        console.print("no stndp hook installed")
+
+
+@app.command()
+def integrations() -> None:
+    """List connected integrations (Jira/GitHub/…) reachable to you."""
+    items = _api_request("GET", "/v1/integrations")
+    if not items:
+        console.print("no integrations connected — connect them on the dashboard")
+        return
+    table = Table(box=None)
+    table.add_column("provider")
+    table.add_column("name")
+    table.add_column("scope")
+    table.add_column("status")
+    for i in items:
+        table.add_row(i["provider"], i.get("display_name") or "—", i["scope"], i["status"])
+    console.print(table)
+
+
+# Every dashboard surface the web app exposes, mapped to the `stn` command that shows
+# the same data (so every dashboard is reachable from the terminal) and its web path
+# (open with `stn dashboards --open <name>`). Grouped to mirror the dashboard's own nav.
+_DASHBOARDS: list[tuple[str, str, str, str, str]] = [
+    # (group, name, web_path, cli_command, what it shows)
+    ("the daily standup", "overview", "/dashboard/", "stn resume",
+     "your working state: last checkpoint, the why, next step, open blockers"),
+    ("the daily standup", "feed", "/dashboard/feed/", "stn team feed <team>",
+     "the team's standup feed, with blocks and their resolutions"),
+    ("the daily standup", "brief", "/dashboard/brief/", "stn team feed <team>",
+     "the feed condensed to one line per person"),
+    ("the daily standup", "wall", "/dashboard/wall/", "stn team feed <team>",
+     "the feed as a card wall"),
+    ("the daily standup", "tail", "/dashboard/tail/", "stn team feed <team>",
+     "the feed as a newest-first activity tail"),
+    ("the daily standup", "grid", "/dashboard/grid/", "stn team feed <team>",
+     "the feed as a who×day grid"),
+    ("the daily standup", "pulse", "/dashboard/pulse/", "stn team feed <team>",
+     "team posting cadence at a glance"),
+    ("the context platform", "search", "/dashboard/search/", "stn search <query>",
+     "one search over decisions, standups and your checkpoints"),
+    ("the context platform", "graph", "/dashboard/graph/", "stn graph neighbors <type> <id>",
+     "the context graph — nodes and the edges between them"),
+    ("the context platform", "decisions", "/dashboard/decisions/", "stn decisions",
+     "the team's durable decisions and learnings"),
+    ("the context platform", "repos", "/dashboard/repos/", "stn repos",
+     "the repos your work touches"),
+    ("the context platform", "projects", "/dashboard/projects/", "stn projects",
+     "tracker projects (Jira/Linear/ClickUp/…) you can see"),
+    ("the context platform", "timeline", "/dashboard/timeline/", "stn timeline <team>",
+     "entries + decisions merged into one chronological thread"),
+    ("the context platform", "integrations", "/dashboard/integrations/", "stn integrations",
+     "connected integrations (GitHub/Slack/Jira/…)"),
+    ("the context platform", "tokens", "/dashboard/tokens/", "stn tokens",
+     "your scoped API tokens"),
+    ("the context platform", "webhooks", "/dashboard/webhooks/", "",
+     "inbound webhook endpoints (create/manage on the web)"),
+    ("the teams", "teams", "/dashboard/settings/", "stn team list",
+     "your teams and their members (the settings page)"),
+]
+
+
+@app.command()
+def dashboards(
+    open_: str | None = typer.Option(
+        None, "--open", help="Open a dashboard by name in your browser (e.g. --open graph)."),
+    web: bool = typer.Option(False, "--web", help="Also print the web URL for each dashboard."),
+) -> None:
+    """List every dashboard the web app exposes and the `stn` command that shows the
+    same data from the terminal — so no dashboard is web-only-by-surprise. Use
+    `--open <name>` to open one in your browser."""
+    config = _load_config()
+    base = config["web_url"].rstrip("/")
+    if open_ is not None:
+        match = next((d for d in _DASHBOARDS if d[1] == open_.strip().lower()), None)
+        if match is None:
+            names = ", ".join(d[1] for d in _DASHBOARDS)
+            console.print(f"[red]unknown dashboard {open_!r}. Choose one of: {names}[/red]")
+            raise typer.Exit(2)
+        url = f"{base}{match[2]}"
+        console.print(f"opening [cyan]{match[1]}[/cyan] → {url}")
+        webbrowser.open(url)
+        return
+    last_group = None
+    for group, name, path, cli_cmd, desc in _DASHBOARDS:
+        if group != last_group:
+            console.print(f"\n[bold]{group}[/bold]")
+            last_group = group
+        cli = cli_cmd if cli_cmd else "[dim](web only)[/dim]"
+        suffix = f"   [dim]{base}{path}[/dim]" if web else ""
+        console.print(f"  [cyan]{name:<13}[/cyan] {desc}")
+        console.print(f"               [dim]→[/dim] {cli}{suffix}")
+    console.print("\n[dim]open any in your browser:[/dim] stn dashboards --open <name>")
+
+
+@app.command()
+def export(
+    team: str | None = typer.Argument(None, help="Team slug or name."),
+    output: Path = Path("stndp-export"),
+    me: bool = typer.Option(False, "--me", help="Export your private checkpoints instead of team entries."),
+) -> None:
+    """Export your entries as Markdown — or, with --me, your private checkpoints."""
+    output.mkdir(parents=True, exist_ok=True)
+    if me:
+        items = _api_request("GET", "/v1/checkpoints", params={"team": team} if team else None)
+        for c in items:
+            (output / f"checkpoint-{_safe_filename(c['id'])}.md").write_text(
+                _checkpoint_markdown(c), encoding="utf-8")
+        console.print(f"exported {len(items)} checkpoints to {output}")
+        return
+    if not team:
+        console.print("pass a TEAM, or use --me to export your checkpoints")
+        raise typer.Exit(1)
+    entries = _api_request("GET", "/v1/entries", params={"team": team})
+    for entry in entries:
+        path = output / f"{_safe_filename(entry['date'], entry['entry_num'])}.md"
+        path.write_text(_entry_markdown(entry), encoding="utf-8")
+    console.print(f"exported {len(entries)} entries to {output}")
+
+
+@app.command()
+def mcp() -> None:
+    """Run a local MCP server (stdio) exposing stndp to coding agents.
+
+    Add it to your agent once — e.g. .mcp.json: {"command": "stn", "args": ["mcp"]} —
+    and the agent can resume, search, decide, and checkpoint your shared context.
+    `stn agent setup` writes that config for you.
+    """
+    from stndp.mcp_server import serve
+
+    serve()
+
+
+_MCP_SERVER = {"command": "stn", "args": ["mcp"]}
+_RULES_MARKER = "## stndp — shared context"
+# Sentinel closing the managed block so `stn agent setup` can REFRESH it in place when
+# the rules change, instead of skipping (stale) or appending a duplicate.
+_RULES_END_MARKER = "<!-- stndp:end -->"
+# ── stndp usage guide — the single source of truth ────────────────────────────
+# This is the ONE place the "how to use stndp" workflow lives. `stn guide` prints it,
+# the MCP `guide` tool serves it, and the CLAUDE.md/AGENTS.md rules block is derived
+# from it (below) — so the CLI, the MCP server, and the rules files can never drift.
+GUIDE_INTRO = (
+    "stndp is this project's shared memory layer — decisions, episodes (the arc of one "
+    "unit of work), bugs, working state, blockers, and a context graph linking repos ↔ "
+    "branches ↔ files ↔ commits ↔ tickets/PRs ↔ decisions. Use it by DEFAULT on every "
+    "task: prefer what stndp already records over reasoning from scratch, and write back "
+    "what you learn so the next agent/human inherits it. The same actions are available "
+    "via the `stndp` MCP server and the `stn` CLI."
+)
+
+# Ordered (key, title, body). CLI command names are used; the MCP tool names match
+# (file_context ↔ file-context, bug ↔ bug add). `stn guide <key>` prints one section.
+GUIDE_TOPICS: list[tuple[str, str, str]] = [
+    ("start", "Start of every task — load context first", """\
+- `resume` — your last working state, any OPEN episode (the arc you were mid-flight on)
+  and its plan, your open bugs, the why, the next step, and the open blockers on you.
+- `search <topic>` — BEFORE reasoning, proposing, or "starting fresh", check what was
+  already decided, tried, or explicitly rejected (`search --type bug <symptom>` finds a
+  bug someone already diagnosed). Don't re-derive what the graph knows.
+- `glob` captures this session's git/repo/commit/GitHub context into the graph; the
+  SessionStart hook runs it automatically — run it yourself if you're not hooked up."""),
+    ("files", "Before editing code — read the file's history", """\
+- `file-context <path>` (also `path#symbol`, or a directory) — the decisions, prior
+  changes, who-touched-it-and-why, and linked PRs/tickets for that file. Do this before
+  changing any non-trivial file so you don't quietly undo a deliberate choice."""),
+    ("record", "While working — record at the right altitude", """\
+ONE ATOMIC CLAIM PER NODE. LINK, DON'T NARRATE. Don't fuse a decision + its design + an
+impl detail + the result into one record — that blob is unsearchable noise. Pick the
+smallest primitive that fits what you're recording:
+- `decide "<choice>" --why "<rationale>"` — when you PICK between alternatives or REJECT
+  an approach (especially "why we did NOT do X"). Just the choice + why.
+- `bug add "<symptom>" --cause "…" --fix "…" --where "…"` — when you hit and fix a
+  non-obvious bug. {symptom → cause → fix → where} is exactly what a future agent searches
+  for; it's the single highest-value thing to record, so do it every time.
+- `episode start …` then `episode close` (with the **surprise** — what changed from plan
+  to reality) — ONLY for a genuine multi-step arc whose plan→done delta is worth keeping.
+  Checkpoints/decisions/bugs recorded while it's open auto-attach to it. MOST WORK NEEDS
+  NO EPISODE — never wrap a lone decision, bug, or one-shot change in one.
+- `checkpoint "<what you're on>" --next "<next step>"` — a heartbeat at each pause, so
+  state survives context loss and `resume` brings it back.
+- `link <id> <ref>` — attach a ticket/PR (PROJ-123 or a PR URL); mentioning a key/PR URL
+  inline in any record auto-links it too. Raise blockers with `block`, clear with `resolve`."""),
+    ("standup", "Posting the user's standup — draft, then ASK (never auto-post)", """\
+A standup update (`stn push`) is the user's own voice to their team — don't post one on
+your own initiative, and never auto-send one you generated. When asked to write their
+standup: gather the raw material first (`resume`, `brag`, the last `checkpoint`s/episodes,
+recent commits/GitHub activity), draft an update from it, SHOW the draft to the user, and
+run `stn push` only after they approve or edit it. The same goes for a `block` posted in
+their name. (Recording decisions, bugs, episodes and checkpoints as you work is the
+opposite — do that freely; agent-authored claims land `pending` for a human to confirm.)
+
+Decisions/bugs/links/blocks are team-visible; checkpoints are private, and an episode is
+private while open and becomes team-visible when you close it. When in doubt, record it in
+stndp rather than only in your own context — unrecorded context is lost."""),
+    ("discover", "Finding your way around stndp", """\
+- `stn guide [topic]` — this playbook (topics: start, files, record, standup, discover).
+- `stn --help` and `stn <command> --help` — every command, its flags and arguments.
+- `stn whoami` — who you're acting as and which team writes land under; `stn team use
+  <team>` changes the current team so commands no longer need `--team`.
+- Over MCP: call the `guide` tool for this same playbook, and `whoami` to check identity."""),
+]
+GUIDE_KEYS = [k for k, _, _ in GUIDE_TOPICS]
+
+
+def _guide_text(sections: list[tuple[str, str, str]], *, with_intro: bool) -> str:
+    """Render guide sections to plain text — shared by `stn guide` and the MCP tool."""
+    parts = [GUIDE_INTRO, ""] if with_intro else []
+    for _, title, body in sections:
+        parts += [title, body, ""]
+    return "\n".join(parts).rstrip() + "\n"
+
+
+# The rules block is DERIVED from the guide: golden rules + a pointer to the live
+# `stn guide`, so an onboarded repo's CLAUDE.md/AGENTS.md stays a thin, stable summary
+# while the full, current workflow is always one `stn guide` away.
+_RULES_BLOCK = f"""\
+## stndp — shared context (agents + humans)
+
+{GUIDE_INTRO}
+
+**The loop, every task:**
+1. `resume` + `search <topic>` BEFORE reasoning — inherit what's already decided or tried.
+2. `file-context <path>` before editing a non-trivial file.
+3. Record as you go, one atomic claim per node: `decide … --why …`, `bug add …`,
+   `checkpoint … --next …`; wrap a genuine multi-step arc in `episode start`/`episode close`.
+4. NEVER auto-post the user's standup (`push`/`block`) — draft it, show it, and post only
+   on their approval. Agent-authored decisions/bugs/episodes land `pending` for a human.
+
+**Learn the workflow at runtime:** run `stn guide` for the full playbook (or
+`stn guide <topic>` for one of: {', '.join(GUIDE_KEYS)}), and `stn <command> --help` for
+any command. The same actions are on the `stndp` MCP server — call its `guide` tool.
+<!-- stndp:end -->
+"""
+
+
+@app.command()
+def guide(
+    topic: str | None = typer.Argument(
+        None, help=f"One section: {', '.join(GUIDE_KEYS)}. Omit for the whole playbook."),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable output for agents."),
+) -> None:
+    """How to use stndp: load context → record as you go → draft the standup.
+
+    The single source of truth for the workflow — the CLAUDE.md/AGENTS.md rules block
+    and the MCP `guide` tool render this same content. New here? Start with `stn guide`,
+    then `stn <command> --help` for any specific command.
+    """
+    sections = GUIDE_TOPICS
+    if topic:
+        key = topic.strip().lower()
+        sections = [t for t in GUIDE_TOPICS if t[0] == key]
+        if not sections:
+            console.print(f"[red]unknown topic {topic!r}. Choose one of: {', '.join(GUIDE_KEYS)}[/red]")
+            raise typer.Exit(2)
+    if json_out:
+        payload = {"intro": GUIDE_INTRO,
+                   "topics": [{"key": k, "title": ti, "body": b} for k, ti, b in sections]}
+        # Plain stdout, NOT console.print: rich would word-wrap long lines and parse
+        # `[...]` as markup, both of which corrupt machine-readable JSON.
+        print(json.dumps(payload, indent=2))
+        return
+    console.print(_guide_text(sections, with_intro=not topic))
+    if not topic:
+        console.print("[dim]one section: stn guide <topic>  ·  any command: stn <command> --help[/dim]")
+
+
+# The rules block lives in the file each agent reads natively. Claude Code → CLAUDE.md;
+# Cursor/Codex/Windsurf read AGENTS.md; Gemini CLI reads GEMINI.md. (`auto` dedupes, so a
+# project gets each file once.)
+_RULES_FILE = {"claude": "CLAUDE.md", "cursor": "AGENTS.md", "codex": "AGENTS.md",
+               "gemini": "GEMINI.md", "windsurf": "AGENTS.md"}
+
+# Targets whose MCP config uses the standard `{"mcpServers": {...}}` JSON shape. claude,
+# cursor, and gemini write a PROJECT-local file; windsurf a GLOBAL one (see below).
+_JSON_MCP_TARGETS = ("claude", "cursor", "gemini", "windsurf")
+
+# Codex configures MCP servers in a TOML file (not JSON), global under ~/.codex
+# (overridable via CODEX_HOME). One table per server.
+_CODEX_MARKER = "[mcp_servers.stndp]"
+_CODEX_BLOCK = '[mcp_servers.stndp]\ncommand = "stn"\nargs = ["mcp"]\n'
+
+
+def _mcp_config_path(cwd: Path, target: str) -> Path | None:
+    """Where each target reads its `mcpServers` JSON. Project-local for claude/cursor/
+    gemini; global for windsurf (it has no per-project MCP config)."""
+    if target == "claude":
+        return cwd / ".mcp.json"
+    if target == "cursor":
+        return cwd / ".cursor" / "mcp.json"
+    if target == "gemini":          # Gemini CLI: project settings, `mcpServers` key.
+        return cwd / ".gemini" / "settings.json"
+    if target == "windsurf":
+        return _windsurf_config_path()
+    return None
+
+
+def _codex_config_path() -> Path:
+    """Codex reads `~/.codex/config.toml` (overridable via CODEX_HOME)."""
+    home = os.environ.get("CODEX_HOME") or str(Path.home() / ".codex")
+    return Path(home) / "config.toml"
+
+
+def _home() -> Path:
+    """The user's home dir — a seam so tests can redirect the global agent configs
+    (Codex/Gemini/Windsurf) away from the real home without monkeypatching pathlib."""
+    return Path.home()
+
+
+def _windsurf_config_path() -> Path:
+    """Windsurf (Cascade) reads a single GLOBAL MCP config at
+    `~/.codeium/windsurf/mcp_config.json` — the `{"mcpServers": {...}}` shape."""
+    return _home() / ".codeium" / "windsurf" / "mcp_config.json"
+
+
+def _merge_mcp_config(path: Path) -> None:
+    """Add the stndp server under `mcpServers`, preserving any existing config."""
+    data: dict[str, Any] = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            data = {}
+    data.setdefault("mcpServers", {})["stndp"] = _MCP_SERVER
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write_text(path, json.dumps(data, indent=2) + "\n")
+
+
+def _write_codex_config(path: Path) -> bool:
+    """Append the stndp server table to Codex's TOML config (idempotent by marker).
+    A plain append, not a TOML rewrite — we don't pull a toml writer for one table,
+    and appending never disturbs the user's existing config."""
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    if _CODEX_MARKER in existing:
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write_text(path, (existing.rstrip() + "\n\n" + _CODEX_BLOCK)
+                       if existing.strip() else _CODEX_BLOCK)
+    return True
+
+
+def _write_rules_block(cwd: Path, filename: str) -> bool:
+    """Write (or refresh) the managed stndp block in CLAUDE.md / AGENTS.md. Idempotent:
+    a no-op when the current block is already present; an in-place replace when the rules
+    have changed (so re-running `stn agent setup` upgrades an onboarded repo instead of
+    appending a duplicate); otherwise appended, preserving any existing content."""
+    path = cwd / filename
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    if _RULES_MARKER in existing:
+        start = existing.index(_RULES_MARKER)
+        end_tok = existing.find(_RULES_END_MARKER, start)
+        # Replace the old block: between the markers if the end sentinel is present, else
+        # from the start marker to EOF (a legacy block written before the sentinel).
+        end = end_tok + len(_RULES_END_MARKER) if end_tok != -1 else len(existing)
+        updated = existing[:start] + _RULES_BLOCK.rstrip() + existing[end:]
+        if updated == existing:
+            return False
+        _atomic_write_text(path, updated)
+        return True
+    _atomic_write_text(path, (existing.rstrip() + "\n\n" + _RULES_BLOCK)
+                       if existing.strip() else _RULES_BLOCK)
+    return True
+
+
+# Claude Code runs hooks from .claude/settings.json. A SessionStart hook that runs
+# `stn glob` makes every session capture git/repo/commit context into stndp with no
+# action from the agent — the deterministic half of autonomous capture (the model
+# can forget the rules; a hook can't).
+_GLOB_HOOK_CMD = "stn glob"
+
+
+def _write_claude_hooks(cwd: Path) -> bool:
+    """Add a SessionStart → `stn glob` hook to .claude/settings.json, preserving any
+    existing config. Idempotent: a no-op if the same hook is already wired."""
+    path = cwd / ".claude" / "settings.json"
+    data: dict[str, Any] = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            data = {}
+    session_start = data.setdefault("hooks", {}).setdefault("SessionStart", [])
+    for group in session_start:
+        if any(h.get("command") == _GLOB_HOOK_CMD for h in group.get("hooks", [])):
+            return False
+    session_start.append({"hooks": [{"type": "command", "command": _GLOB_HOOK_CMD}]})
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write_text(path, json.dumps(data, indent=2) + "\n")
+    return True
+
+
+@agent_app.command("setup")
+def agent_setup(
+    target: str = typer.Option(
+        "auto", "--target",
+        help="auto | claude | cursor | codex | gemini | windsurf."),
+    rules: bool = typer.Option(True, "--rules/--no-rules",
+                               help="Also write a CLAUDE.md / AGENTS.md / GEMINI.md rules block."),
+    hooks: bool = typer.Option(True, "--hooks/--no-hooks",
+                               help="Also wire a Claude Code SessionStart hook to `stn glob`."),
+) -> None:
+    """Wire up the stndp MCP server for your coding agent (one config line), a rules
+    block, and a SessionStart hook so every session auto-captures context.
+
+    `auto` always configures Claude Code + Cursor (their config is project-local and
+    harmless), and adds Codex / Gemini CLI / Windsurf when it detects you use them.
+    """
+    cwd = Path.cwd()
+    if target == "auto":
+        targets = ["claude", "cursor"]
+        # Add the global-config agents only when detected, so we never drop a config
+        # file for a tool the user doesn't run.
+        if _codex_config_path().parent.exists():
+            targets.append("codex")
+        if (_home() / ".gemini").exists():
+            targets.append("gemini")
+        if _windsurf_config_path().parent.exists():
+            targets.append("windsurf")
+    else:
+        targets = [target]
+    written: list[str] = []
+    rules_files: set[str] = set()
+    for t in targets:
+        if t == "codex":
+            path = _codex_config_path()
+            if _write_codex_config(path):
+                written.append(str(path))
+        elif t in _JSON_MCP_TARGETS:
+            path = _mcp_config_path(cwd, t)
+            _merge_mcp_config(path)
+            # Project-local paths show relative; global ones (windsurf) show absolute.
+            try:
+                written.append(str(path.relative_to(cwd)).replace("\\", "/"))
+            except ValueError:
+                written.append(str(path))
+            if t == "claude" and hooks and _write_claude_hooks(cwd):
+                written.append(".claude/settings.json")
+        else:
+            console.print(f"unknown target: {t}")
+            continue
+        rules_files.add(_RULES_FILE.get(t, "AGENTS.md"))
+    if rules:
+        for fn in sorted(rules_files):
+            if _write_rules_block(cwd, fn):
+                written.append(fn)
+    if written:
+        console.print("configured " + ", ".join(written)
+                      + " — restart your agent to load the stndp tools")
+        console.print("[dim]verify with `stn agent doctor`; learn the workflow with `stn guide`[/dim]")
+    else:
+        console.print("nothing to configure")
+
+
+@agent_app.command("doctor")
+def agent_doctor() -> None:
+    """Verify this repo + machine are wired for agents: login, the MCP server, the rules
+    block, the MCP config, and the SessionStart hook. Prints a checklist and exits
+    non-zero if a critical piece (login or the MCP server) is missing."""
+    cwd = Path.cwd()
+    ok, bad, warn = "[green]✓[/green]", "[red]✗[/red]", "[yellow]•[/yellow]"
+    critical_failed = False
+
+    config = _load_config()
+    if config.get("token") and config.get("user_id"):
+        console.print(f"{ok} logged in as @{config.get('handle')} (team={config.get('team_id')})")
+    else:
+        console.print(f"{bad} not logged in — run `stn login`")
+        critical_failed = True
+
+    try:
+        from stndp.mcp_server import handle_message
+        init = handle_message({"jsonrpc": "2.0", "id": 1, "method": "initialize"})
+        name = (((init or {}).get("result") or {}).get("serverInfo") or {}).get("name")
+        if name == "stndp":
+            tools = handle_message({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+            n = len(((tools or {}).get("result") or {}).get("tools") or [])
+            console.print(f"{ok} MCP server starts ({n} tools) — `stn mcp`")
+        else:
+            console.print(f"{bad} MCP server did not initialize")
+            critical_failed = True
+    except Exception as exc:  # noqa: BLE001 — report any import/runtime failure as a check
+        console.print(f"{bad} MCP server failed to start: {exc}")
+        critical_failed = True
+
+    # Project-local JSON configs (relative) + global ones (absolute), all carrying our
+    # server entry. Windsurf's path is global; codex is a TOML table.
+    names: list[str] = []
+    for t in ("claude", "cursor", "gemini"):
+        p = _mcp_config_path(cwd, t)
+        if p and p.exists() and "stndp" in p.read_text(encoding="utf-8", errors="replace"):
+            names.append(str(p.relative_to(cwd)).replace("\\", "/"))
+    wind = _windsurf_config_path()
+    if wind.exists() and "stndp" in wind.read_text(encoding="utf-8", errors="replace"):
+        names.append("~/.codeium/windsurf/mcp_config.json")
+    codex = _codex_config_path()
+    if codex.exists() and _CODEX_MARKER in codex.read_text(encoding="utf-8", errors="replace"):
+        names.append("~/.codex/config.toml")
+    if names:
+        console.print(f"{ok} MCP config: {', '.join(names)}")
+    else:
+        console.print(f"{warn} no MCP config in this repo — run `stn agent setup`")
+
+    rules_here = [fn for fn in ("CLAUDE.md", "AGENTS.md", "GEMINI.md")
+                  if (cwd / fn).exists()
+                  and _RULES_MARKER in (cwd / fn).read_text(encoding="utf-8", errors="replace")]
+    if rules_here:
+        console.print(f"{ok} rules block: {', '.join(rules_here)}")
+    else:
+        console.print(f"{warn} no stndp rules block here — run `stn agent setup`")
+
+    settings = cwd / ".claude" / "settings.json"
+    hook_ok = False
+    if settings.exists():
+        try:
+            data = json.loads(settings.read_text(encoding="utf-8"))
+            hook_ok = any(h.get("command") == _GLOB_HOOK_CMD
+                          for grp in data.get("hooks", {}).get("SessionStart", [])
+                          for h in grp.get("hooks", []))
+        except (ValueError, OSError, AttributeError):
+            hook_ok = False
+    console.print(f"{ok} SessionStart hook -> stn glob" if hook_ok
+                  else f"{warn} no SessionStart hook (Claude Code) — `stn agent setup`")
+
+    if critical_failed:
+        raise typer.Exit(1)
+    console.print("\n[green]ready[/green] — agents can use stndp here. Learn the workflow: stn guide")
+
+
+_LOOPBACK_HOSTS = ("127.0.0.1", "::1", "localhost")
+
+
+def _assert_token_transport_safe(url: str) -> None:
+    """Refuse to attach the bearer token to a non-https host that isn't loopback.
+
+    STNDP_API_URL/STNDP_WEB_URL come from the environment with no scheme/host
+    check, and the token is sent on every API call. A plain-http endpoint on a
+    public host would leak the token in clear text (and an attacker-controlled
+    one would simply capture it), so allow http ONLY for loopback (dev), and
+    require https everywhere else.
+    """
+    from urllib.parse import urlsplit
+
+    parts = urlsplit(url)
+    scheme = (parts.scheme or "").lower()
+    host = (parts.hostname or "").lower()
+    if scheme == "https":
+        return
+    if scheme == "http" and host in _LOOPBACK_HOSTS:
+        return
+    console.print(
+        f"[red]refusing to send your auth token to {scheme or '?'}://{host or '?'}: "
+        f"only https (or http on localhost) is allowed.[/red]")
+    raise typer.Exit(1)
+
+
+def _api_request(method: str, path: str, **kwargs: Any) -> Any:
+    config = _load_config()
+    url = f"{config['api_url'].rstrip('/')}{path}"
+    headers = _headers(config) | kwargs.get("headers", {})
+    if "Authorization" in headers:
+        _assert_token_transport_safe(url)
+    kwargs["headers"] = headers
+    return _request(method, url, **kwargs)
+
+
+def _web_request(method: str, path: str, *, config: dict[str, Any] | None = None, auth: bool = False, **kwargs: Any) -> Any:
+    config = config or _load_config()
+    url = f"{config['web_url'].rstrip('/')}{path}"
+    if auth:
+        headers = _headers(config) | kwargs.get("headers", {})
+        if "Authorization" in headers:
+            _assert_token_transport_safe(url)
+        kwargs["headers"] = headers
+    return _request(method, url, **kwargs)
+
+
+def _request(method: str, url: str, **kwargs: Any) -> Any:
+    try:
+        response = httpx.request(method, url, timeout=10, **kwargs)
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        # Surface the API's friendly `detail` (e.g. unknown-handle message) plainly.
+        detail = exc.response.text
+        try:
+            detail = exc.response.json().get("detail", detail)
+        except (ValueError, AttributeError):
+            # non-JSON body, or JSON that isn't an object — keep the raw text.
+            pass
+        console.print(f"[red]{detail}[/red]")
+        raise typer.Exit(1) from exc
+    except httpx.HTTPError as exc:
+        console.print(f"API request failed: {exc}")
+        raise typer.Exit(1) from exc
+    if response.status_code == 204:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        console.print("[red]Unexpected non-JSON response from the API.[/red]")
+        raise typer.Exit(1) from None
+
+
+def _load_config() -> dict[str, Any]:
+    config = DEFAULT_CONFIG.copy()
+    if CONFIG_PATH.exists():
+        try:
+            data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+        except (ValueError, OSError):
+            console.print("[yellow]Config is unreadable — run `stn login` to recreate it.[/yellow]")
+            data = {}
+        if isinstance(data, dict):
+            config |= data
+    # api_url/web_url are always environment-derived, never read from disk.
+    config["api_url"], config["web_url"] = _resolve_urls()
+    return config
+
+
+def _save_config(config: dict[str, Any]) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    # Endpoints are resolved from the environment, so never persist them.
+    config = {k: v for k, v in config.items() if k not in ("api_url", "web_url")}
+    if config.get("handle"):
+        config["handle"] = str(config["handle"]).lower()
+    data = json.dumps(DEFAULT_CONFIG | config, indent=2)
+    # Write atomically with owner-only perms from creation: the file holds a bearer
+    # token, so it must never exist world-readable, even briefly between write and
+    # chmod. mkstemp creates the temp file mode 0o600 (POSIX); os.replace swaps it
+    # in atomically so a crash mid-write can't truncate the existing config.
+    fd, tmp = tempfile.mkstemp(dir=str(CONFIG_PATH.parent), prefix=".config-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(data)
+        try:
+            os.chmod(tmp, 0o600)
+        except OSError:
+            pass
+        os.replace(tmp, CONFIG_PATH)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+    # Belt-and-suspenders on the final path. NOTE: on Windows chmod only toggles the
+    # read-only bit, not a real ACL — the token's protection there is the user's
+    # profile directory permissions, not this call.
+    try:
+        CONFIG_PATH.chmod(0o600)
+    except OSError:
+        pass
+
+
+def _save_auth_response(config: dict[str, Any], response: dict[str, Any]) -> None:
+    user = response["user"]
+    team = response.get("team")
+    config.update(
+        {
+            "token": response["token"],
+            "email": user["email"],
+            "user_id": user["id"],
+            "team_id": team["id"] if team else None,
+            "handle": user["handle"],
+            "team_slug": team["slug"] if team else None,
+        }
+    )
+    _save_config(config)
+
+
+def _current_team() -> int:
+    config = _load_config()
+    team_id = config.get("team_id")
+    if not team_id:
+        console.print("no current team set; pass --team TEAM_ID")
+        raise typer.Exit(1)
+    return int(team_id)
+
+
+def _headers(config: dict[str, Any]) -> dict[str, str]:
+    token = config.get("token")
+    if not token:
+        console.print("not logged in; run stn login")
+        raise typer.Exit(1)
+    headers = {"Authorization": f"Bearer {token}"}
+    # Scope requests to the selected workspace (the API validates membership and
+    # falls back to the user's current workspace when absent).
+    if slug := config.get("workspace_slug"):
+        headers["X-Stndp-Workspace"] = str(slug)
+    return headers
+
+
+def _write_cache(entry: dict[str, Any]) -> None:
+    date = str(entry.get("date") or "")
+    # Validate the shape before using it in a path: this both prevents a malformed
+    # date from crashing the command *after* a successful push (the cache is just
+    # local bookkeeping) and stops a stray path separator from escaping CACHE_ROOT.
+    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", date):
+        if date:
+            console.print(f"[yellow]skipping local cache: unexpected date {date!r}[/yellow]")
+        return
+    year, month = date[:4], date[5:7]
+    try:
+        path = CACHE_ROOT / year / month / f"{date}.md"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        existing = path.read_text(encoding="utf-8") if path.exists() else ""
+        path.write_text((existing + "\n\n" if existing else "") + _entry_markdown(entry),
+                        encoding="utf-8")
+    except OSError as exc:
+        # Never fail an already-successful push on local cache I/O.
+        console.print(f"[yellow]could not write local cache: {exc}[/yellow]")
+
+
+def _pushed_line(entry: dict[str, Any], *, verb: str) -> str:
+    is_blocked = entry.get("kind") == "blocked"
+    label = "blocker" if is_blocked else "entry"
+    # Show the entry's real id (not the per-day entry_num): it's the handle every
+    # other command takes — `stn edit/delete/show/resolve/link <id>`.
+    line = f"{verb} {label} #{entry['id']} for {entry['date']}"
+    mentions = entry.get("mentions") or []
+    if mentions:
+        who = ", ".join(f"@{h}" for h in mentions)
+        line += f" — blocked by {who}" if is_blocked else f" — mentions {who}"
+    return line
+
+
+def _entry_markdown(entry: dict[str, Any]) -> str:
+    return (
+        "---\n"
+        f"date: {entry['date']}\n"
+        f"author: @{entry['handle']}\n"
+        f"entry: {entry['entry_num']}\n"
+        "---\n\n"
+        f"{entry['content']}\n"
+    )
+
+
+def _print_entries(entries: list[dict[str, Any]]) -> None:
+    if not entries:
+        console.print("no entries")
+        return
+
+    table = Table(box=None)
+    table.add_column("date")
+    table.add_column("author")
+    table.add_column("id", justify="right")
+    table.add_column("update")
+    for entry in entries:
+        table.add_row(entry["date"], f"@{entry['handle']}", str(entry["id"]), entry["content"])
+    console.print(table)
+
+
+def _unresolved_blockers(entry: dict[str, Any]) -> list[str]:
+    """Named blockers on a block who haven't cleared their part yet."""
+    resolved = {r["blocker"] for r in (entry.get("resolutions") or [])}
+    return [h for h in (entry.get("mentions") or []) if h not in resolved]
+
+
+def _print_feed(entries: list[dict[str, Any]]) -> None:
+    """Render a team feed line-by-line, with each block's resolution entries
+    hanging off it like a file tree (├─ / └─)."""
+    if not entries:
+        console.print("no entries")
+        return
+    for entry in entries:
+        head = (
+            f"[cyan]@{entry['handle']}[/cyan] "
+            f"[dim]{entry['date']} #{entry['id']}[/dim]"
+        )
+        if entry.get("kind") == "blocked":
+            tag = "[red][blocked][/red]" if _unresolved_blockers(entry) else "[green][resolved][/green]"
+            sev = entry.get("severity", "normal")
+            if sev and sev != "normal":
+                tag += f" [yellow]\\[{sev}][/yellow]"
+            head += f" {tag}"
+        console.print(f"{head}  {entry['content']}")
+        resolutions = entry.get("resolutions") or []
+        for i, res in enumerate(resolutions):
+            branch = "└─" if i == len(resolutions) - 1 else "├─"
+            console.print(
+                f"   [dim]{branch}[/dim] [green]resolved[/green] @{res['blocker']}"
+                f" [dim]by @{res['by']}[/dim]: {res['content']}"
+            )
+
+
+def _parse_date(value: str) -> date:
+    try:
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        console.print("--from must be YYYY-MM-DD")
+        raise typer.Exit(1) from exc
+
+
+# ── checkpoint / resume helpers ──────────────────────────────────────────────
+_GIT_TIMEOUT = 2.0  # hard cap (seconds) on any single git call
+_REMOTE_CREDS_RE = re.compile(r"//[^/@\s]+@")  # strip user[:pass]@ from a remote URL
+
+
+def _redact_remote(url: str | None) -> str | None:
+    return _REMOTE_CREDS_RE.sub("//", url) if url else url
+
+
+def _git(args: list[str], cwd: str) -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", *args], cwd=cwd, capture_output=True, text=True, timeout=_GIT_TIMEOUT,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout.strip() if out.returncode == 0 else None
+
+
+def capture_git(cwd: Path | str | None = None) -> dict[str, Any] | None:
+    """Capture local git context for a checkpoint (branch, HEAD, dirtiness, recent
+    commits). Pure-local, no network, each git call hard-timeouts; returns None
+    outside a repo. Credentials in the remote URL are redacted."""
+    cwd = str(cwd or Path.cwd())
+    if _git(["rev-parse", "--is-inside-work-tree"], cwd) != "true":
+        return None
+    branch = _git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)
+    sha = _git(["rev-parse", "HEAD"], cwd)
+    subject = _git(["log", "-1", "--pretty=%s"], cwd)
+    remote = _redact_remote(_git(["remote", "get-url", "origin"], cwd))
+    status_out = _git(["status", "--porcelain"], cwd) or ""
+    dirty = bool(status_out.strip())
+    recently_edited = [line[3:].strip() for line in status_out.splitlines() if line.strip()][:20]
+    recent = (_git(["log", "-10", "--pretty=%h %s"], cwd) or "").splitlines()
+    repo = remote.rstrip("/").rsplit("/", 1)[-1].removesuffix(".git") if remote else None
+    return {
+        "git_branch": branch or None,
+        "git_commit_sha": sha or None,
+        "git_commit_msg": subject or None,
+        "git_remote_url": remote or None,
+        "repo_name": repo or None,
+        "git_dirty": dirty,
+        "source_tool": "git",
+        "raw": {
+            "git": {
+                "branch": branch,
+                "head": {"sha": sha, "subject": subject},
+                "remote": remote,
+                "dirty": dirty,
+                "recent_commits": [c for c in recent if c],
+            },
+            # Editor signal without an editor: files touched in the working tree.
+            "editor": {"recently_edited": recently_edited},
+        },
+    }
+
+
+def _read_editor_state() -> dict[str, Any] | None:
+    """Read editor state a VSCode/editor extension may have written — the integration
+    contract: JSON at $STNDP_EDITOR_STATE (or ~/.stndp/editor.json), shaped
+    {"tool": "vscode", "active_file": "...", "open_files": ["...", ...]}."""
+    path = os.environ.get("STNDP_EDITOR_STATE") or str(Path.home() / ".stndp" / "editor.json")
+    try:
+        p = Path(path)
+        if not p.exists():
+            return None
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def capture_editor(cwd: Path | str | None = None) -> dict[str, Any]:
+    """Editor context for a checkpoint. Always derives `recently_edited` from the
+    working tree (git status), so it works with no extension; enriches it with the
+    active/open files when a VSCode (or other) extension has written a state file."""
+    cwd = str(cwd or Path.cwd())
+    status_out = _git(["status", "--porcelain"], cwd) or ""
+    editor: dict[str, Any] = {
+        "tool": "git",
+        "recently_edited": [ln[3:].strip() for ln in status_out.splitlines() if ln.strip()][:20],
+    }
+    state = _read_editor_state()
+    if state:
+        editor["tool"] = state.get("tool") or "vscode"
+        if state.get("active_file"):
+            editor["active_file"] = str(state["active_file"])
+        if isinstance(state.get("open_files"), list):
+            editor["open_files"] = [str(f) for f in state["open_files"][:50]]
+        # Active symbol (class/function the cursor is in) — the symbol facet (Act V).
+        # The editor/agent already knows it, so we just pass the string through; it
+        # stamps the file's `touches` edge so context can be queried at `path#symbol`.
+        if state.get("active_symbol"):
+            editor["active_symbol"] = str(state["active_symbol"])[:200]
+    return editor
+
+
+# ── Novel context sources (opt-in, local-first, secret-redacted) ─────────────
+# Redaction rules applied to captured shell history before it leaves the machine.
+# Catch keyword=value (incl. env-var names like AWS_SECRET_ACCESS_KEY), bearer
+# tokens, and known high-entropy token shapes even without a keyword.
+_REDACT_RULES = [
+    (re.compile(r"(?i)([\w.\-]*(?:secret|token|password|passwd|api[_-]?key|auth)[\w.\-]*\s*[=:]\s*)(\S+)"),
+     r"\1***"),
+    (re.compile(r"(?i)(\bbearer\s+)\S+"), r"\1***"),
+    (re.compile(r"\b(?:gh[pousr]_[A-Za-z0-9]{16,}|sk-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16})\b"), "***"),
+    (re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+"), "***"),
+]
+
+
+def _redact_secrets(line: str) -> str:
+    for pattern, repl in _REDACT_RULES:
+        line = pattern.sub(repl, line)
+    return line
+
+
+def capture_shell(limit: int = 20, history_path: Path | str | None = None) -> list[str]:
+    """Recent shell commands (opt-in) — the truest record of what you did, invisible
+    to git. Secret-redacted; local-only. Returns [] if no history is found."""
+    candidates = (
+        [Path(history_path)] if history_path
+        else [Path.home() / ".bash_history", Path.home() / ".zsh_history"]
+    )
+    for path in candidates:
+        try:
+            if not path.exists():
+                continue
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+        cmds = [ln.strip() for ln in lines if ln.strip()][-limit:]
+        return [_redact_secrets(c) for c in cmds]
+    return []
+
+
+def capture_ai_session(path: Path | str) -> list[str]:
+    """Extract the prompts from an AI-assistant session log (jsonl or plain text) —
+    your prompts are your intent (design §8.5). Opt-in; truncated per line."""
+    path = Path(path)
+    if not path.exists():
+        return []
+    prompts: list[str] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            obj = None
+        if isinstance(obj, dict):
+            # A structured message — keep only the user's prompts, skip the rest.
+            if obj.get("role") == "user" and obj.get("content"):
+                prompts.append(str(obj["content"])[:500])
+            continue
+        prompts.append(line[:500])   # plain-text line
+    return prompts[:50]
+
+
+def _capture_context(no_context: bool, shell: bool, ai_session: str | None,
+                     github: bool = False, editor: bool = False) -> dict[str, Any] | None:
+    """Build a snapshot from git plus any opt-in novel sources (shell/AI/GitHub/editor)."""
+    snap = None if no_context else capture_git()
+    extra: dict[str, Any] = {}
+    if shell:
+        extra["shell"] = capture_shell()
+    if ai_session:
+        extra["ai_session"] = capture_ai_session(ai_session)
+    if github:
+        gh = capture_github()
+        if gh:
+            extra["github"] = gh
+    if not extra and not editor:
+        return snap
+    if snap is None:
+        snap = {"source_tool": "cli", "raw": {}}
+    snap.setdefault("raw", {})
+    snap["raw"].update(extra)
+    if editor:
+        snap["raw"]["editor"] = capture_editor()
+    return snap
+
+
+# ── GitHub via the user's `gh` CLI (network; opt-in / non-blocking surfaces) ──
+_GH_TIMEOUT = 8.0
+
+
+def _gh(args: list[str], timeout: float = _GH_TIMEOUT) -> str | None:
+    """Run a `gh` command, returning stdout on success or None (absent/error)."""
+    try:
+        out = subprocess.run(["gh", *args], capture_output=True, text=True, timeout=timeout)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout if out.returncode == 0 else None
+
+
+def _gh_json(args: list[str]) -> list[dict[str, Any]]:
+    out = _gh(args)
+    if not out:
+        return []
+    try:
+        data = json.loads(out)
+        return data if isinstance(data, list) else []
+    except (json.JSONDecodeError, ValueError):
+        return []
+
+
+def gh_available() -> bool:
+    """True if `gh` is installed and authenticated."""
+    return _gh(["auth", "status"], timeout=4.0) is not None
+
+
+def gh_review_queue(limit: int = 20) -> list[dict[str, Any]]:
+    """PRs awaiting YOUR review (review-requested:@me, open)."""
+    return _gh_json(["search", "prs", "review-requested:@me", "--state", "open",
+                     "--json", "number,title,url,repository", "--limit", str(limit)])
+
+
+def gh_reviewed(since: str | None = None, limit: int = 30) -> list[dict[str, Any]]:
+    """PRs you reviewed (reviewed-by:@me)."""
+    query = "reviewed-by:@me"
+    if since:
+        query += f" updated:>={since}"
+    return _gh_json(["search", "prs", query, "--state", "all",
+                     "--json", "number,title,url,repository", "--limit", str(limit)])
+
+
+def gh_my_commits(since: str | None = None, limit: int = 30) -> list[dict[str, Any]]:
+    """Commits you authored. `@me` only resolves via the --author flag (not in a raw
+    `author:` query qualifier for commit search), so use the flag form."""
+    args = ["search", "commits", "--author", "@me",
+            "--json", "sha,commit,repository,url", "--limit", str(limit)]
+    if since:
+        args += ["--author-date", f">={since}"]
+    return _gh_json(args)
+
+
+def _valid_pr_ref(number_or_url: str) -> bool:
+    """True only for a bare PR number or a github PR URL.
+
+    `external_id` flows here from the server into `gh pr view <id>` as a
+    positional arg. An id starting with `-` would be parsed by gh as a flag
+    (argument injection), so reject anything that isn't a plain number (optionally
+    `#`-prefixed) or a recognizable github .../pull/<n> URL.
+    """
+    s = str(number_or_url).strip()
+    if re.fullmatch(r"#?\d+", s):
+        return True
+    return _repo_from_url(s) is not None
+
+
+def gh_pr(number_or_url: str, repo: str | None = None) -> dict[str, Any] | None:
+    """Resolve a single PR's title/state via gh."""
+    ref = str(number_or_url).strip()
+    if not _valid_pr_ref(ref):
+        return None
+    args = ["pr", "view", ref.lstrip("#"), "--json", "number,title,state,url"]
+    # Only attach --repo for a bare number; a full URL already pins the repo, and
+    # a bad repo value (also server-derived) shouldn't widen the positional.
+    if repo and re.fullmatch(r"#?\d+", ref):
+        args += ["--repo", repo]
+    out = _gh(args)
+    if not out:
+        return None
+    try:
+        return json.loads(out)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+def capture_github() -> dict[str, Any] | None:
+    """Local GitHub context via the user's `gh` CLI: your review queue, recent
+    reviews, and recent commits. Network — returns None if gh is absent/unauthed."""
+    if not gh_available():
+        return None
+    return {
+        "review_queue": gh_review_queue(),
+        "recent_reviews": gh_reviewed(),
+        "recent_commits": gh_my_commits(),
+    }
+
+
+def _checkpoint_dir() -> Path:
+    path = CACHE_ROOT / "checkpoints"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+# ── Open-episode pointer ──────────────────────────────────────────────────────
+# A genuine arc spans many checkpoints/decisions/bugs. Tracking the open episode
+# locally lets `checkpoint`/`decide`/`bug` auto-attach to it (the API stays stateless;
+# a stale pointer is silently ignored server-side). `episode start` writes it; `close`
+# /`abandon` clear it.
+def _open_episode_path() -> Path:
+    return CACHE_ROOT / "episode" / "open.json"
+
+
+def _set_open_episode(ep: dict[str, Any]) -> None:
+    _atomic_write_text(
+        _open_episode_path(),
+        json.dumps({"id": ep["id"], "team_id": ep.get("team_id"), "title": ep.get("title", "")}),
+    )
+
+
+def _current_open_episode() -> dict[str, Any] | None:
+    p = _open_episode_path()
+    if not p.exists():
+        return None
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, ValueError, OSError):
+        return None
+
+
+def _open_episode_id() -> int | None:
+    ep = _current_open_episode()
+    return ep.get("id") if ep else None
+
+
+def _clear_open_episode(episode_id: int | None = None) -> None:
+    """Forget the open-episode pointer. With `episode_id`, only clear when it matches —
+    so closing an older arc never drops a pointer to one you've opened since."""
+    p = _open_episode_path()
+    if not p.exists():
+        return
+    if episode_id is not None:
+        cur = _current_open_episode()
+        if cur and cur.get("id") != episode_id:
+            return
+    try:
+        p.unlink()
+    except OSError:
+        pass
+
+
+def _mirror_checkpoint(ckpt: dict[str, Any]) -> None:
+    """Mirror a checkpoint locally so `stn resume --offline` works without a network."""
+    root = _checkpoint_dir()
+    payload = json.dumps(ckpt)
+    # Atomic writes so an interrupted mirror can't leave a truncated JSON file that
+    # `stn resume --offline` (when you're least able to debug) then crashes on.
+    _atomic_write_text(root / f"{_safe_filename(ckpt['id'])}.json", payload)
+    key = _safe_filename(ckpt.get("team_id") or "personal")
+    _atomic_write_text(root / f"latest-{key}.json", payload)
+
+
+def _read_mirror() -> dict[str, Any]:
+    """The most recently mirrored checkpoint (newest `latest-*.json`), for offline resume."""
+    empty = {"checkpoint": None, "blockers_on_me": [], "my_open_blocks": []}
+    root = CACHE_ROOT / "checkpoints"
+    files = (
+        sorted(root.glob("latest-*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+        if root.exists() else []
+    )
+    # Try newest-first and skip any corrupt/truncated mirror rather than crashing
+    # the offline resume on a bad file.
+    for f in files:
+        try:
+            ckpt = json.loads(f.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, ValueError, OSError):
+            continue
+        return {"checkpoint": ckpt, "blockers_on_me": [], "my_open_blocks": []}
+    return empty
+
+
+def _render_resume(data: dict[str, Any], *, offline: bool = False) -> None:
+    ckpt = data.get("checkpoint")
+    if not ckpt:
+        console.print("no active checkpoint — run `stn checkpoint`")
+    else:
+        when = str(ckpt.get("created_at", ""))[:16].replace("T", " ")
+        tag = " [dim](offline)[/dim]" if offline else ""
+        console.print(f"[bold]resuming[/bold] checkpoint #{ckpt['id']} [dim]{when}[/dim]{tag}")
+        console.print(f"  focus: {ckpt['focus']}")
+        if ckpt.get("reason"):
+            console.print(f"  why:   {ckpt['reason']}")
+        if ckpt.get("next_step"):
+            console.print(f"  next:  {ckpt['next_step']}")
+        snap = ckpt.get("snapshot")
+        if snap and snap.get("git_branch"):
+            dirty = " [yellow]*dirty*[/yellow]" if snap.get("git_dirty") else ""
+            sha = (snap.get("git_commit_sha") or "")[:7]
+            console.print(f"  git:   {snap['git_branch']} @ {sha}{dirty}")
+    for lk in (data.get("links") or []):
+        state = f" — {lk['state']}" if lk.get("state") else ""
+        console.print(f"  link:  {lk['provider']}:{lk['external_id']}{state}")
+    on_me = data.get("blockers_on_me") or []
+    if on_me:
+        console.print("\n[red]blocking you:[/red]")
+        for e in on_me:
+            console.print(f"  #{e['id']} @{e['handle']}: {e['content']}")
+    mine = data.get("my_open_blocks") or []
+    if mine:
+        console.print("\n[yellow]your open blocks:[/yellow]")
+        for e in mine:
+            console.print(f"  #{e['id']}: {e['content']}")
+    queue = data.get("review_queue") or []
+    if queue:
+        console.print("\n[blue]awaiting your review:[/blue]")
+        for pr in queue:
+            repo = (pr.get("repository") or {}).get("name") or ""
+            console.print(f"  #{pr.get('number')} {pr.get('title', '')} [dim]{repo}[/dim]")
+
+
+def _print_checkpoints(items: list[dict[str, Any]]) -> None:
+    if not items:
+        console.print("no checkpoints")
+        return
+    table = Table(box=None)
+    table.add_column("id", justify="right")
+    table.add_column("when")
+    table.add_column("status")
+    table.add_column("focus")
+    for c in items:
+        when = str(c.get("created_at", ""))[:16].replace("T", " ")
+        table.add_row(str(c["id"]), when, c["status"], c["focus"])
+    console.print(table)
+
+
+def _checkpoint_markdown(c: dict[str, Any]) -> str:
+    lines = ["---", f"id: {c['id']}", f"created: {c.get('created_at', '')}",
+             f"status: {c['status']}", "---", "", c["focus"]]
+    if c.get("reason"):
+        lines += ["", f"**Why:** {c['reason']}"]
+    if c.get("next_step"):
+        lines += ["", f"**Next:** {c['next_step']}"]
+    return "\n".join(lines) + "\n"
+
+
+# ── episode / bug renderers ───────────────────────────────────────────────────
+def _print_episodes(items: list[dict[str, Any]]) -> None:
+    if not items:
+        console.print("no episodes")
+        return
+    table = Table(box=None)
+    table.add_column("id", justify="right")
+    table.add_column("status")
+    table.add_column("by")
+    table.add_column("title")
+    for e in items:
+        flag = ""
+        if e.get("is_private"):
+            flag += " [dim](private)[/dim]"
+        if e.get("pending"):
+            flag += " [yellow](pending — confirm)[/yellow]"
+        by = f"@{e['handle']}"
+        if e.get("agent_label"):
+            by += f" [cyan]⚙{e['agent_label']}[/cyan]"
+        table.add_row(str(e["id"]), e["status"], by, e["title"] + flag)
+    console.print(table)
+
+
+def _print_episode_full(e: dict[str, Any]) -> None:
+    flags = []
+    if e.get("is_private"):
+        flags.append("private")
+    if e.get("pending"):
+        flags.append("pending — confirm")
+    tag = f" [yellow]({', '.join(flags)})[/yellow]" if flags else ""
+    console.print(f"[bold]#{e['id']} {e['title']}[/bold] [dim]({e['status']})[/dim]{tag}")
+    console.print(f"[dim]@{e['handle']}[/dim]")
+    for label, key in (("plan", "plan"), ("outcome", "outcome"),
+                       ("result", "result"), ("surprise", "surprise")):
+        if e.get(key):
+            console.print(f"  {label:<9}{e[key]}")
+
+
+def _print_bugs(items: list[dict[str, Any]]) -> None:
+    if not items:
+        console.print("no bugs")
+        return
+    table = Table(box=None)
+    table.add_column("id", justify="right")
+    table.add_column("status")
+    table.add_column("by")
+    table.add_column("symptom")
+    for b in items:
+        flag = " [yellow](pending — confirm)[/yellow]" if b.get("pending") else ""
+        by = f"@{b['handle']}"
+        if b.get("agent_label"):
+            by += f" [cyan]⚙{b['agent_label']}[/cyan]"
+        table.add_row(str(b["id"]), b["status"], by, (b["symptom"][:60]) + flag)
+    console.print(table)
+
+
+def _print_bug_full(b: dict[str, Any]) -> None:
+    tag = " [yellow](pending — confirm)[/yellow]" if b.get("pending") else ""
+    console.print(f"[bold]#{b['id']}[/bold] [dim]({b['status']})[/dim]{tag}")
+    console.print(f"[dim]@{b['handle']}[/dim]")
+    console.print(f"  symptom: {b['symptom']}")
+    if b.get("root_cause"):
+        console.print(f"  cause:   {b['root_cause']}")
+    if b.get("fix"):
+        console.print(f"  fix:     {b['fix']}")
+    if b.get("where_ref"):
+        console.print(f"  where:   {b['where_ref']}")
+    if b.get("episode_id"):
+        console.print(f"  episode: #{b['episode_id']}")
+
+
+# ── decisions / search / brag helpers ────────────────────────────────────────
+def _print_decisions(items: list[dict[str, Any]]) -> None:
+    if not items:
+        console.print("no decisions")
+        return
+    table = Table(box=None)
+    table.add_column("id", justify="right")
+    table.add_column("kind")
+    table.add_column("by")
+    table.add_column("title")
+    for d in items:
+        flag = " [dim](superseded)[/dim]" if d.get("status") == "superseded" else ""
+        if d.get("pending"):
+            flag += " [yellow](pending — confirm)[/yellow]"
+        by = f"@{d['handle']}"
+        if d.get("agent_label"):
+            by += f" [cyan]⚙{d['agent_label']}[/cyan]"   # agent-authored
+        title = d["title"] + flag
+        if d.get("category"):
+            title += f" [magenta]\\[{d['category']}][/magenta]"
+        table.add_row(str(d["id"]), d["kind"], by, title)
+    console.print(table)
+
+
+def _print_decision_full(d: dict[str, Any]) -> None:
+    flag = " [dim](superseded)[/dim]" if d.get("status") == "superseded" else ""
+    console.print(f"[bold]#{d['id']} {d['title']}[/bold]{flag}")
+    meta = f"[dim]{d['kind']} · @{d['handle']} · {str(d.get('decided_on', ''))}[/dim]"
+    if d.get("category"):
+        sfx = " (unconfirmed)" if d.get("category_pending") else ""
+        meta += f"  [magenta]{d['category']}{sfx}[/magenta]"
+    tags = d.get("tags") or []
+    if tags:
+        meta += "  " + " ".join(f"[cyan]#{t}[/cyan]" for t in tags)
+    console.print(meta)
+    console.print("")
+    console.print(d["body"])
+
+
+def _print_search(results: list[dict[str, Any]]) -> None:
+    if not results:
+        console.print("nothing found")
+        return
+    for r in results:
+        when = str(r.get("when", ""))[:10]
+        who = f" @{r['handle']}" if r.get("handle") else ""
+        console.print(
+            f"[magenta]{r['type']:<16}[/magenta] [dim]{when}{who}[/dim] "
+            f"#{r['id']}  {r['snippet']}"
+        )
+        ctx = r.get("context") or {}
+        bits = [f"{lk['provider']}:{lk['external_id']}" for lk in ctx.get("links", [])]
+        bits += [f"{e['rel']} {e['node_type']}#{e['node_id']}" for e in ctx.get("edges", [])]
+        if bits:
+            console.print(f"             [dim]> {'  '.join(bits[:5])}[/dim]")
+
+
+def _brag_markdown(data: dict[str, Any]) -> str:
+    lines = [f"# Brag — {data['from']} to {data['to']}", ""]
+    acc = data.get("accomplishments") or []
+    if acc:
+        lines.append("## Shipped")
+        lines += [f"- {a['date']}: {a['content']}" for a in acc]
+        lines.append("")
+    dec = data.get("decisions") or []
+    if dec:
+        lines.append("## Decisions")
+        lines += [f"- #{d['id']} {d['title']} ({d['kind']})" for d in dec]
+        lines.append("")
+    blk = data.get("blocks_cleared") or []
+    if blk:
+        lines.append("## Unblocked others")
+        lines += [f"- {b['content']}" for b in blk]
+        lines.append("")
+    lines.append(f"_Checkpoints captured: {data.get('checkpoints', 0)}_")
+    return "\n".join(lines)
+
+
+def _brag_github_markdown(reviewed: list[dict[str, Any]], commits: list[dict[str, Any]]) -> str:
+    lines = ["## GitHub"]
+    if reviewed:
+        lines.append(f"- Reviewed {len(reviewed)} PRs:")
+        lines += [
+            f"  - {p.get('title', '')} ({(p.get('repository') or {}).get('name', '')})"
+            for p in reviewed[:10]
+        ]
+    if commits:
+        lines.append(f"- Authored {len(commits)} commits")
+    if len(lines) == 1:
+        lines.append("- (no GitHub activity in range)")
+    return "\n".join(lines)