docs(peek-cli): document connect + sessions search; refresh whats-new + THREATMODEL header

.changeset/peek-cli-readme-connect-search.md

@@ -0,0 +1,5 @@
+---
+"@peekdev/cli": patch
+---
+
+docs(peek-cli): document the peek connect and peek sessions search commands in the README

apps/peek-docs/src/pages/whats-new.astro

@@ -144,6 +144,61 @@ import Layout from '../layouts/Layout.astro';
     See it: <a href="/recipes/reproduce-bug-from-teammate-peek-session">Reproduce a bug from a teammate&rsquo;s peek session</a>.
   </p>
 
+  <h2>5. Find sessions and verify integrity from the CLI</h2>
+  <p>
+    Two CLI additions make the local store easier to triage and audit:
+  </p>
+  <ul>
+    <li>
+      <code>peek sessions search</code> lets your agent (or you) filter sessions
+      by text (<code>--q</code>), origin, time window (<code>--since</code> /
+      <code>--until</code>), status, and error type (<code>--errors
+      console|network|any</code>) &mdash; narrowing thousands of recorded
+      sessions down to the one that matters, without opening a viewer. The
+      <code>search_sessions</code> MCP tool exposes the same facets to agents
+      directly.
+    </li>
+    <li>
+      <code>peek audit verify</code> recomputes the hash chain of the action
+      audit log and exits non-zero on any gap, reorder, edit, or truncation.
+      The <code>verify_audit_log</code> MCP tool exposes the same check so an
+      agent can assert chain integrity as part of a workflow.
+    </li>
+    <li>
+      <code>peek audit bundle</code> / <code>peek audit verify</code> (the bundle
+      variant) packages the audit log alongside a session export so a recipient
+      can verify the chain independently.
+    </li>
+  </ul>
+
+  <h2>6. Delegated connectors &mdash; supervised background daemons</h2>
+  <p>
+    <code>peek connect</code> is a supervised connector daemon: register a
+    surface (currently <strong>Slack</strong>), run it once interactively to
+    capture tokens, then <code>peek connect start</code> spawns a detached
+    supervisor that keeps each connector alive and auto-restarts it on exit.
+    Per-connector logs stream to <code>~/.peek/connect/logs/</code>; the
+    supervisor PID and each connector&rsquo;s state are visible via
+    <code>peek connect status</code>. Connectors extend peek&rsquo;s reach
+    beyond the browser &mdash; a Slack connector turns channel messages into
+    queryable local sessions the same way the extension turns browser activity
+    into sessions.
+  </p>
+
+  <h2>7. Claude Code plugin</h2>
+  <p>
+    peek is now a one-line Claude Code plugin install:
+  </p>
+  <pre><code>/plugin install peekdev@peek</code></pre>
+  <p>
+    This drops the peek MCP server and the Claude Code skill into place in a
+    single command &mdash; no <code>peek init</code> required for MCP
+    configuration. The plugin is hosted in the
+    <a href="https://github.com/Cubenest/rrweb-stack/tree/main/plugins" rel="noopener">public repo</a>
+    and installable via the community catalog
+    (<code>/plugin marketplace add Cubenest/rrweb-stack</code>).
+  </p>
+
   <h2>The honest part</h2>
   <p>
     peek is local-first: <strong>peek uploads nothing &mdash; what your MCP

docs/peek/THREATMODEL.md

@@ -1,8 +1,12 @@
-# peek — threat model (DRAFT)
+# peek — threat model
 
-**Status:** stub. To be filled in before public Chrome Web Store submission
-(Phase 5 launch gate). Existence-tracking only — the gap is intentionally
-visible.
+**Status:** substantive — all eight attack surfaces enumerated, existing
+mitigations documented, and outstanding items tracked with explicit scope
+labels. The extension is live on the Chrome Web Store. Residual gaps
+(content-script isolation hardening, native-host fuzz coverage, CWS
+publisher 2FA recovery, CDP-debugger UX wording, `execute_action` schema
+versioning) are accepted pre-1.0 scope and tracked below under
+[Outstanding mitigations](#outstanding-mitigations).
 
 **Owner:** harry-harish.
 
@@ -12,11 +16,6 @@ Cross-referenced from [`SECURITY.md`](../../SECURITY.md) and the
 project's pre-launch supply-chain hygiene controls (see
 `docs/SUSTAINABILITY.md` §"Pre-launch hygiene controls").
 
-When this stub is replaced, follow the format described in the OSS
-Maintenance Field Manual §5.3 — one surface per row in each table,
-explicit grade (`mitigated` / `partial` / `accepted` / `open`), and a
-"why we live with it" column for any accepted risk.
-
 ## Attack surfaces to cover
 
 1. **Chrome MV3 service-worker compromise** — what happens if an attacker

packages/peek-cli/README.md

@@ -46,6 +46,7 @@ Then you install the **Peek Chrome extension** — available on the [Chrome Web
 peek init                                  # interactive install (see above)
 peek status                                # health check — extension connected? DB writable?
 peek sessions list [--origin <url>] [--limit <n>] [--json]  # list recent sessions
+peek sessions search [--q <text>] [--origin <url>] [--since <dur|iso>] [--until <dur|iso>] [--status <active|finalized>] [--errors <console|network|any>] [--limit <n>] [--json]  # search sessions by metadata/facets
 peek sessions show <id>                    # print one session as Markdown (metadata + errors)
 peek sessions export <id> [--format <markdown|json|playwright|bundle>] [--out <file>]  # export (default markdown); --format bundle writes a portable *.peekbundle
 peek sessions import <file> [--keep-id] [--force]  # import a *.peekbundle into the local store (local-first, masked-at-capture, no cloud)
@@ -56,7 +57,15 @@ peek retention show                        # print the configured policy
 peek retention preview [overrides…]        # dry-run: what the policy would prune (non-destructive)
 peek retention apply [--yes] [--include-stale-active] [overrides…]  # prune per the policy (asks to confirm)
 peek audit log [--since <dur>] [--tool <name>] [--client <name>] [--json]  # act-tool audit log
-peek audit verify [--json]                 # verify the audit log hash chain (exit 0 ok, 1 anomaly, 2 tampered)
+peek audit verify [--dir <path>] [--bundle <file>] [--json]  # verify the audit log hash chain, or a received *.peekaudit archive (exit 0 ok, 1 anomaly, 2 tampered)
+peek audit bundle [--dir <path>] [--out <file>]  # package the audit log + head into a portable *.peekaudit evidence archive
+peek connect add <surface> [--name <n>] [--command <c>] [--args=<arg>]  # register a connector (surface: slack)
+peek connect list                          # list configured connectors
+peek connect remove <name>                 # remove a connector from the registry
+peek connect start                         # start the detached supervisor daemon
+peek connect stop                          # stop the running supervisor daemon
+peek connect status [name]                 # show supervisor and per-connector status
+peek connect logs [name] [--follow] [--lines <n>]  # print or tail connector logs
 peek <cmd> --help                          # usage for any subcommand
 ```
 
@@ -78,7 +87,7 @@ A policy can prune by age (`--max-age`), by total event-blob size (`--max-size`,
 
 The audit log (`~/.peek/audit.log`) is hash-chained: each JSONL entry carries a `seq` counter and a `prevHash` field (SHA-256 of the previous line), written under a file lock. A small sidecar (`audit.head.json`) records the tail hash so that tail truncation is also detectable.
 
-`peek audit verify [--json]` recomputes the chain and reports:
+`peek audit verify [--dir <path>] [--bundle <file>] [--json]` recomputes the chain and reports:
 
 | Status | Meaning | Exit code |
 |---|---|:---:|
@@ -93,6 +102,28 @@ The audit log (`~/.peek/audit.log`) is hash-chained: each JSONL entry carries a
 
 The audit log is **tamper-evident, not tamper-proof.** It detects accidental corruption, truncation, reordering, and edits, but does not stop a determined local attacker who recomputes the whole chain. There are no keys, no external anchor, and no egress.
 
+`peek audit bundle [--dir <path>] [--out <file>]` packages the audit log and its head sidecar into a portable `*.peekaudit` evidence archive (with a SHA-256 integrity manifest); a recipient verifies it independently with `peek audit verify --bundle <file>`.
+
+### Connector daemon
+
+`peek connect` manages a supervised connector daemon — a long-running background process that spawns and monitors per-surface connector subprocesses (e.g. a Slack connector that streams workspace events into the local store). Connector registrations are stored in `~/.peek/connect/connectors.json`; the daemon runs detached and logs each connector's stdout/stderr to a per-connector file under `~/.peek/connect/logs/`.
+
+```sh
+# First, register a connector for a surface (currently: slack).
+# Run it interactively once to capture tokens and pair the connection,
+# then start the daemon so it supervises and auto-restarts it.
+peek connect add slack --name my-slack
+peek connect start            # spawns the detached supervisor
+
+# Ongoing management
+peek connect status            # show supervisor uptime + connector states
+peek connect logs my-slack     # last N lines of the connector's log
+peek connect logs my-slack --follow  # tail -f the log (Ctrl-C to stop)
+peek connect stop              # graceful SIGTERM to the supervisor
+```
+
+The `--args=<arg>` flag on `connect add` is repeatable — pass it multiple times to build the connector's argv. `--command` overrides the default binary for the surface (useful for a custom connector binary).
+
 ## Querying from an AI agent
 
 After `peek init`, the `peek-mcp` server is available to your AI client as an MCP toolset. Sample queries: