nodmix 2026.5.25

package/docs/cli/uninstall.md

@@ -0,0 +1,44 @@
+---
+summary: "CLI reference for `nodmix uninstall` (remove gateway service + local data)"
+read_when:
+  - You want to remove the gateway service and/or local state
+  - You want a dry-run first
+title: "Uninstall"
+---
+
+# `nodmix uninstall`
+
+Uninstall the gateway service + local data (CLI remains).
+
+Options:
+
+- `--service`: remove the gateway service
+- `--state`: remove state and config
+- `--workspace`: remove workspace directories
+- `--app`: remove the macOS app
+- `--all`: remove service, state, workspace, and app
+- `--yes`: skip confirmation prompts
+- `--non-interactive`: disable prompts; requires `--yes`
+- `--dry-run`: print actions without removing files
+
+Examples:
+
+```bash
+nodmix backup create
+nodmix uninstall
+nodmix uninstall --service --yes --non-interactive
+nodmix uninstall --state --workspace --yes --non-interactive
+nodmix uninstall --all --yes
+nodmix uninstall --dry-run
+```
+
+Notes:
+
+- Run `nodmix backup create` first if you want a restorable snapshot before removing state or workspaces.
+- `--all` is shorthand for removing service, state, workspace, and app together.
+- `--non-interactive` requires `--yes`.
+
+## Related
+
+- [CLI reference](/cli)
+- [Uninstall](/install/uninstall)

package/docs/cli/update.md

@@ -0,0 +1,242 @@
+---
+summary: "CLI reference for `nodmix update` (safe-ish source update + gateway auto-restart)"
+read_when:
+  - You want to update a source checkout safely
+  - You are debugging `nodmix update` output or options
+  - You need to understand `--update` shorthand behavior
+title: "Update"
+---
+
+# `nodmix update`
+
+Safely update Nodmix and switch between stable/beta/dev channels.
+
+If you installed via **npm/pnpm/bun** (global install, no git metadata),
+updates happen via the package-manager flow in [Updating](/install/updating).
+
+## Usage
+
+```bash
+nodmix update
+nodmix update status
+nodmix update wizard
+nodmix update --channel beta
+nodmix update --channel dev
+nodmix update --tag beta
+nodmix update --tag main
+nodmix update --dry-run
+nodmix update --no-restart
+nodmix update --yes
+nodmix update --json
+nodmix --update
+```
+
+## Options
+
+- `--no-restart`: skip restarting the Gateway service after a successful update. Package-manager updates that do restart the Gateway verify the restarted service reports the expected updated version before the command succeeds.
+- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
+- `--tag <dist-tag|version|spec>`: override the package target for this update only. For package installs, `main` maps to `github:nodmix/nodmix#main`.
+- `--dry-run`: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
+- `--json`: print machine-readable `UpdateRunResult` JSON, including
+  `postUpdate.plugins.warnings` when corrupt or unloadable managed plugins need
+  repair after the core update succeeds, beta-channel plugin fallback details
+  when a plugin has no beta release, and `postUpdate.plugins.integrityDrifts`
+  when npm plugin artifact drift is detected during post-update plugin sync.
+- `--timeout <seconds>`: per-step timeout (default is 1800s).
+- `--yes`: skip confirmation prompts (for example downgrade confirmation).
+
+`nodmix update` does not have a `--verbose` flag. Use `--dry-run` to preview
+the planned channel/tag/install/restart actions, `--json` for machine-readable
+results, and `nodmix update status --json` when you only need channel and
+availability details. If you are debugging Gateway logs around an update,
+console verbosity and file log level are separate: Gateway `--verbose` affects
+terminal/WebSocket output, while file logs require `logging.level: "debug"` or
+`"trace"` in config. See [Gateway logging](/gateway/logging).
+
+<Note>
+In Nix mode (`NODMIX_NIX_MODE=1`), mutating `nodmix update` runs are disabled. Update the Nix source or flake input for this install instead; for nix-nodmix, use the agent-first [Quick Start](https://github.com/nodmix/nix-nodmix#quick-start). `nodmix update status` and `nodmix update --dry-run` remain read-only.
+</Note>
+
+<Warning>
+Downgrades require confirmation because older versions can break configuration.
+</Warning>
+
+## `update status`
+
+Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
+
+```bash
+nodmix update status
+nodmix update status --json
+nodmix update status --timeout 10
+```
+
+Options:
+
+- `--json`: print machine-readable status JSON.
+- `--timeout <seconds>`: timeout for checks (default is 3s).
+
+## `update wizard`
+
+Interactive flow to pick an update channel and confirm whether to restart the Gateway
+after updating (default is to restart). If you select `dev` without a git checkout, it
+offers to create one.
+
+Options:
+
+- `--timeout <seconds>`: timeout for each update step (default `1800`)
+
+## What it does
+
+When you switch channels explicitly (`--channel ...`), Nodmix also keeps the
+install method aligned:
+
+- `dev` → ensures a git checkout (default: `~/nodmix`, override with `NODMIX_GIT_DIR`),
+  updates it, and installs the global CLI from that checkout.
+- `stable` → installs from npm using `latest`.
+- `beta` → prefers npm dist-tag `beta`, but falls back to `latest` when beta is
+  missing or older than the current stable release.
+
+The Gateway core auto-updater (when enabled via config) launches the CLI update path
+outside the live Gateway request handler. Control-plane `update.run` package-manager
+updates also use a managed-service handoff instead of replacing the package tree
+inside the live Gateway process. The Gateway starts a detached helper, exits,
+and the helper runs the normal `nodmix update --yes --json` CLI path from
+outside the Gateway process tree. If that handoff is unavailable, `update.run`
+returns a structured response with the safe shell command to run manually.
+
+For package-manager installs, `nodmix update` resolves the target package
+version before invoking the package manager. npm global installs use a staged
+install: Nodmix installs the new package into a temporary npm prefix, verifies
+the packaged `dist` inventory there, then swaps that clean package tree into the
+real global prefix. If verification fails, post-update doctor, plugin sync, and
+restart work do not run from the suspect tree. Even when the installed version
+already matches the target, the command refreshes the global package install,
+then runs plugin sync, a core-command completion refresh, and restart work. This
+keeps packaged sidecars and channel-owned plugin records aligned with the
+installed Nodmix build while leaving full plugin-command completion rebuilds to
+explicit `nodmix completion --write-state` runs.
+
+When a local managed Gateway service is installed and restart is enabled,
+package-manager updates stop the running service before replacing the package
+tree, then refresh the service metadata from the updated install, restart the
+service, and verify the restarted Gateway reports the expected version before
+reporting `Gateway: restarted and verified.`. On macOS, the post-update check
+also verifies the LaunchAgent is loaded/running for the active profile and the
+configured loopback port is healthy. If the plist is installed but launchd is
+not supervising it, Nodmix re-bootstraps the LaunchAgent automatically, then
+reruns the health/version/channel readiness checks. A fresh bootstrap loads the
+RunAtLoad job directly, so update recovery does not immediately `kickstart -k`
+the newly spawned Gateway. If the Gateway still does not become healthy, the
+command exits non-zero and prints the restart log path plus explicit restart,
+reinstall, and package rollback instructions. If restart cannot run, the command
+prints `Gateway: restart skipped (...)` or `Gateway: restart failed: ...` with a
+manual `nodmix gateway restart` hint. With `--no-restart`,
+package replacement still runs but the managed service is not stopped or
+restarted, so the running Gateway may keep old code until you restart it
+manually.
+
+### Control-plane response shape
+
+When `update.run` is invoked through the Gateway control plane on a
+package-manager install, the handler reports the handoff initiation separately
+from the CLI update that continues after the Gateway exits:
+
+- `ok: true`, `result.status: "skipped"`,
+  `result.reason: "managed-service-handoff-started"`, and
+  `handoff.status: "started"` mean the Gateway created the managed-service
+  handoff and scheduled its own restart so the detached helper can run
+  `nodmix update --yes --json` outside the live service process.
+- `ok: false`, `result.reason: "managed-service-handoff-unavailable"`, and
+  `handoff.status: "unavailable"` mean Nodmix could not find a supervising
+  service boundary for a safe handoff. The response includes
+  `handoff.command`, the shell command to run from outside the Gateway.
+- `ok: false`, `result.reason: "managed-service-handoff-failed"` means the
+  Gateway tried to create the handoff but could not spawn the detached helper.
+
+The `sentinel` payload is still written before the Gateway exits, and the CLI
+handoff updates the same restart sentinel after the managed-service restart
+health checks complete. During the handoff, the sentinel can carry
+`stats.reason: "restart-health-pending"` with no success continuation; the
+restarted Gateway keeps polling it and only fires the continuation after the CLI
+has verified service health and rewritten the sentinel with the final `ok`
+result. `nodmix status` and `nodmix status --all` show an `Update restart`
+row while that sentinel is pending or failed, and `update.status` returns the
+latest cached sentinel.
+
+## Git checkout flow
+
+### Channel selection
+
+- `stable`: checkout the latest non-beta tag, then build and doctor.
+- `beta`: prefer the latest `-beta` tag, but fall back to the latest stable tag when beta is missing or older.
+- `dev`: checkout `main`, then fetch and rebase.
+
+### Update steps
+
+<Steps>
+  <Step title="Verify clean worktree">
+    Requires no uncommitted changes.
+  </Step>
+  <Step title="Switch channel">
+    Switches to the selected channel (tag or branch).
+  </Step>
+  <Step title="Fetch upstream">
+    Dev only.
+  </Step>
+  <Step title="Preflight build (dev only)">
+    Runs the TypeScript build in a temp worktree. If the tip fails, walks back up to 10 commits to find the newest buildable commit. Set `NODMIX_UPDATE_PREFLIGHT_LINT=1` to also run lint during this preflight; lint runs in constrained serial mode because user update hosts are often smaller than CI runners.
+  </Step>
+  <Step title="Rebase">
+    Rebases onto the selected commit (dev only).
+  </Step>
+  <Step title="Install dependencies">
+    Uses the repo package manager. For pnpm checkouts, the updater bootstraps `pnpm` on demand (via `corepack` first, then a temporary `npm install pnpm@11` fallback) instead of running `npm run build` inside a pnpm workspace.
+  </Step>
+  <Step title="Build Control UI">
+    Builds the gateway and the Control UI.
+  </Step>
+  <Step title="Run doctor">
+    `nodmix doctor` runs as the final safe-update check.
+  </Step>
+  <Step title="Sync plugins">
+    Syncs plugins to the active channel. Dev uses bundled plugins; stable and beta use npm. Updates tracked plugin installs.
+  </Step>
+</Steps>
+
+On the beta update channel, tracked npm and ClawHub plugin installs that follow
+the default/latest line try a plugin `@beta` release first. If the plugin has no
+beta release, Nodmix falls back to the recorded default/latest spec and reports
+that as a warning. For npm plugins, Nodmix also falls back when the beta
+package exists but fails install validation. These plugin fallback warnings do
+not make the core update fail. Exact versions and explicit tags are not
+rewritten.
+
+<Warning>
+If an exact pinned npm plugin update resolves to an artifact whose integrity differs from the stored install record, `nodmix update` aborts that plugin artifact update instead of installing it. Reinstall or update the plugin explicitly only after verifying that you trust the new artifact.
+</Warning>
+
+<Note>
+Post-update plugin sync failures that are scoped to a managed plugin and that the sync path can route around (e.g. an unreachable npm registry for a non-essential plugin) are reported as warnings after the core update succeeds. The JSON result keeps the top-level update `status: "ok"` and reports `postUpdate.plugins.status: "warning"` with `nodmix doctor --fix` and `nodmix plugins inspect <id> --runtime --json` guidance. Unexpected updater or sync exceptions still fail the update result. Fix the plugin install or update error, then rerun `nodmix doctor --fix` or `nodmix update`.
+
+After the per-plugin sync step, `nodmix update` runs a mandatory **post-core convergence** pass before the gateway is restarted: it repairs missing configured plugin payloads, validates each _active_ tracked install record on disk, and statically verifies its `package.json` is parseable (and any explicitly-declared `main` exists). Failures from this pass — and an invalid Nodmix config snapshot — return `postUpdate.plugins.status: "error"` and flip the top-level update `status` to `"error"`, so `nodmix update` exits non-zero and the gateway is _not_ restarted with an unverified plugin set. The error includes structured `postUpdate.plugins.warnings[].guidance` lines pointing at `nodmix doctor --fix` and `nodmix plugins inspect <id> --runtime --json` for follow-up. Disabled plugin entries and records that are not trusted-source-linked official sync targets are skipped here, mirroring the `skipDisabledPlugins` policy used by the missing-payload check, so a stale disabled plugin record cannot block an otherwise valid update.
+
+When the updated Gateway starts, plugin loading is verify-only: startup does not
+run package managers or mutate dependency trees. Package-manager `update.run`
+restarts are handed to the CLI managed-service path, so the package swap happens
+outside the old Gateway process and the service health checks decide whether the
+update can be reported as complete.
+
+If pnpm bootstrap still fails, the updater stops early with a package-manager-specific error instead of trying `npm run build` inside the checkout.
+</Note>
+
+## `--update` shorthand
+
+`nodmix --update` rewrites to `nodmix update` (useful for shells and launcher scripts).
+
+## Related
+
+- `nodmix doctor` (offers to run update first on git checkouts)
+- [Development channels](/install/development-channels)
+- [Updating](/install/updating)
+- [CLI reference](/cli)

package/docs/cli/voicecall.md

@@ -0,0 +1,204 @@
+---
+summary: "CLI reference for `nodmix voicecall` (voice-call plugin command surface)"
+read_when:
+  - You use the voice-call plugin and want every CLI entry point
+  - You need flag tables and defaults for setup, smoke, call, continue, speak, dtmf, end, status, tail, latency, expose, and start
+title: "Voicecall"
+---
+
+# `nodmix voicecall`
+
+`voicecall` is a plugin-provided command. It only appears when the voice-call plugin is installed and enabled.
+
+When the Gateway is running, operational commands (`call`, `start`, `continue`, `speak`, `dtmf`, `end`, `status`) are routed to that Gateway's voice-call runtime. If no Gateway is reachable, they fall back to a standalone CLI runtime.
+
+## Subcommands
+
+```bash
+nodmix voicecall setup    [--json]
+nodmix voicecall smoke    [-t <phone>] [--message <text>] [--mode <m>] [--yes] [--json]
+nodmix voicecall call     -m <text> [-t <phone>] [--mode <m>]
+nodmix voicecall start    --to <phone> [--message <text>] [--mode <m>]
+nodmix voicecall continue --call-id <id> --message <text>
+nodmix voicecall speak    --call-id <id> --message <text>
+nodmix voicecall dtmf     --call-id <id> --digits <digits>
+nodmix voicecall end      --call-id <id>
+nodmix voicecall status   [--call-id <id>] [--json]
+nodmix voicecall tail     [--file <path>] [--since <n>] [--poll <ms>]
+nodmix voicecall latency  [--file <path>] [--last <n>]
+nodmix voicecall expose   [--mode <m>] [--path <p>] [--port <port>] [--serve-path <p>]
+```
+
+| Subcommand | Description                                                     |
+| ---------- | --------------------------------------------------------------- |
+| `setup`    | Show provider and webhook readiness checks.                     |
+| `smoke`    | Run readiness checks; place a live test call only with `--yes`. |
+| `call`     | Initiate an outbound voice call.                                |
+| `start`    | Alias for `call` with `--to` required and `--message` optional. |
+| `continue` | Speak a message and wait for the next response.                 |
+| `speak`    | Speak a message without waiting for a response.                 |
+| `dtmf`     | Send DTMF digits to an active call.                             |
+| `end`      | Hang up an active call.                                         |
+| `status`   | Inspect active calls (or one by `--call-id`).                   |
+| `tail`     | Tail `calls.jsonl` (useful during provider tests).              |
+| `latency`  | Summarize turn-latency metrics from `calls.jsonl`.              |
+| `expose`   | Toggle Tailscale serve/funnel for the webhook endpoint.         |
+
+## Setup and smoke
+
+### `setup`
+
+Prints human-readable readiness checks by default. Pass `--json` for scripts.
+
+```bash
+nodmix voicecall setup
+nodmix voicecall setup --json
+```
+
+### `smoke`
+
+Runs the same readiness checks. It will not place a real phone call unless both `--to` and `--yes` are present.
+
+| Flag               | Default                           | Description                             |
+| ------------------ | --------------------------------- | --------------------------------------- |
+| `-t, --to <phone>` | (none)                            | Phone number to call for a live smoke.  |
+| `--message <text>` | `Nodmix voice call smoke test.` | Message to speak during the smoke call. |
+| `--mode <mode>`    | `notify`                          | Call mode: `notify` or `conversation`.  |
+| `--yes`            | `false`                           | Actually place the live outbound call.  |
+| `--json`           | `false`                           | Print machine-readable JSON.            |
+
+```bash
+nodmix voicecall smoke
+nodmix voicecall smoke --to "+15555550123"        # dry run
+nodmix voicecall smoke --to "+15555550123" --yes  # live notify call
+```
+
+<Note>
+For external providers (`twilio`, `telnyx`, `plivo`), `setup` and `smoke` require a public webhook URL from `publicUrl`, a tunnel, or Tailscale exposure. A loopback or private serve fallback is rejected because carriers cannot reach it.
+</Note>
+
+## Call lifecycle
+
+### `call`
+
+Initiate an outbound voice call.
+
+| Flag                   | Required | Default           | Description                                                                |
+| ---------------------- | -------- | ----------------- | -------------------------------------------------------------------------- |
+| `-m, --message <text>` | yes      | (none)            | Message to speak when the call connects.                                   |
+| `-t, --to <phone>`     | no       | config `toNumber` | E.164 phone number to call.                                                |
+| `--mode <mode>`        | no       | `conversation`    | Call mode: `notify` (hang up after message) or `conversation` (stay open). |
+
+```bash
+nodmix voicecall call --to "+15555550123" --message "Hello"
+nodmix voicecall call -m "Heads up" --mode notify
+```
+
+### `start`
+
+Alias for `call` with a different default flag shape.
+
+| Flag               | Required | Default        | Description                              |
+| ------------------ | -------- | -------------- | ---------------------------------------- |
+| `--to <phone>`     | yes      | (none)         | Phone number to call.                    |
+| `--message <text>` | no       | (none)         | Message to speak when the call connects. |
+| `--mode <mode>`    | no       | `conversation` | Call mode: `notify` or `conversation`.   |
+
+### `continue`
+
+Speak a message and wait for a response.
+
+| Flag               | Required | Description       |
+| ------------------ | -------- | ----------------- |
+| `--call-id <id>`   | yes      | Call ID.          |
+| `--message <text>` | yes      | Message to speak. |
+
+### `speak`
+
+Speak a message without waiting for a response.
+
+| Flag               | Required | Description       |
+| ------------------ | -------- | ----------------- |
+| `--call-id <id>`   | yes      | Call ID.          |
+| `--message <text>` | yes      | Message to speak. |
+
+### `dtmf`
+
+Send DTMF digits to an active call.
+
+| Flag                | Required | Description                               |
+| ------------------- | -------- | ----------------------------------------- |
+| `--call-id <id>`    | yes      | Call ID.                                  |
+| `--digits <digits>` | yes      | DTMF digits (e.g. `ww123456#` for waits). |
+
+### `end`
+
+Hang up an active call.
+
+| Flag             | Required | Description |
+| ---------------- | -------- | ----------- |
+| `--call-id <id>` | yes      | Call ID.    |
+
+### `status`
+
+Inspect active calls.
+
+| Flag             | Default | Description                  |
+| ---------------- | ------- | ---------------------------- |
+| `--call-id <id>` | (none)  | Restrict output to one call. |
+| `--json`         | `false` | Print machine-readable JSON. |
+
+```bash
+nodmix voicecall status
+nodmix voicecall status --json
+nodmix voicecall status --call-id <id>
+```
+
+## Logs and metrics
+
+### `tail`
+
+Tail the voice-call JSONL log. Prints the last `--since` lines on start, then streams new lines as they are written.
+
+| Flag            | Default                    | Description                    |
+| --------------- | -------------------------- | ------------------------------ |
+| `--file <path>` | resolved from plugin store | Path to `calls.jsonl`.         |
+| `--since <n>`   | `25`                       | Lines to print before tailing. |
+| `--poll <ms>`   | `250` (minimum 50)         | Poll interval in milliseconds. |
+
+### `latency`
+
+Summarize turn-latency and listen-wait metrics from `calls.jsonl`. Output is JSON with `recordsScanned`, `turnLatency`, and `listenWait` summaries.
+
+| Flag            | Default                    | Description                          |
+| --------------- | -------------------------- | ------------------------------------ |
+| `--file <path>` | resolved from plugin store | Path to `calls.jsonl`.               |
+| `--last <n>`    | `200` (minimum 1)          | Number of recent records to analyze. |
+
+## Exposing webhooks
+
+### `expose`
+
+Enable, disable, or change the Tailscale serve/funnel configuration for the voice webhook.
+
+| Flag                  | Default                                   | Description                                     |
+| --------------------- | ----------------------------------------- | ----------------------------------------------- |
+| `--mode <mode>`       | `funnel`                                  | `off`, `serve` (tailnet), or `funnel` (public). |
+| `--path <path>`       | config `tailscale.path` or `--serve-path` | Tailscale path to expose.                       |
+| `--port <port>`       | config `serve.port` or `3334`             | Local webhook port.                             |
+| `--serve-path <path>` | config `serve.path` or `/voice/webhook`   | Local webhook path.                             |
+
+```bash
+nodmix voicecall expose --mode serve
+nodmix voicecall expose --mode funnel
+nodmix voicecall expose --mode off
+```
+
+<Warning>
+Only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
+</Warning>
+
+## Related
+
+- [CLI reference](/cli)
+- [Voice call plugin](/plugins/voice-call)

package/docs/cli/webhooks.md

@@ -0,0 +1,117 @@
+---
+summary: "CLI reference for `nodmix webhooks` (Gmail Pub/Sub setup and runner)"
+read_when:
+  - You want to wire Gmail Pub/Sub events into Nodmix
+  - You need the full flag list and default values
+title: "Webhooks"
+---
+
+# `nodmix webhooks`
+
+Webhook helpers and integrations. Today this surface is scoped to Gmail Pub/Sub flows that integrate with the bundled `gog` watcher.
+
+## Subcommands
+
+```bash
+nodmix webhooks gmail setup --account <email> [...]
+nodmix webhooks gmail run   [--account <email>] [...]
+```
+
+| Subcommand    | Description                                                                                  |
+| ------------- | -------------------------------------------------------------------------------------------- |
+| `gmail setup` | Configure Gmail watch, Pub/Sub topic/subscription, and the Nodmix webhook delivery target. |
+| `gmail run`   | Run `gog watch serve` plus the watch auto-renew loop.                                        |
+
+## `webhooks gmail setup`
+
+Configure Gmail watch, Pub/Sub, and Nodmix webhook delivery.
+
+```bash
+nodmix webhooks gmail setup --account you@example.com
+nodmix webhooks gmail setup --account you@example.com --project my-gcp-project --json
+nodmix webhooks gmail setup --account you@example.com --hook-url https://gateway.example.com/hooks/gmail
+```
+
+### Required
+
+| Flag                | Description             |
+| ------------------- | ----------------------- |
+| `--account <email>` | Gmail account to watch. |
+
+### Pub/Sub options
+
+| Flag                    | Default                | Description                                          |
+| ----------------------- | ---------------------- | ---------------------------------------------------- |
+| `--project <id>`        | (none)                 | GCP project id (the OAuth client owner).             |
+| `--topic <name>`        | `gog-gmail-watch`      | Pub/Sub topic name.                                  |
+| `--subscription <name>` | `gog-gmail-watch-push` | Pub/Sub subscription name.                           |
+| `--label <label>`       | `INBOX`                | Gmail label to watch.                                |
+| `--push-endpoint <url>` | (none)                 | Explicit Pub/Sub push endpoint. Overrides Tailscale. |
+
+### Nodmix delivery options
+
+| Flag                   | Default | Description                                |
+| ---------------------- | ------- | ------------------------------------------ |
+| `--hook-url <url>`     | (none)  | Nodmix webhook URL.                      |
+| `--hook-token <token>` | (none)  | Nodmix webhook token.                    |
+| `--push-token <token>` | (none)  | Push token forwarded to `gog watch serve`. |
+
+### `gog watch serve` options
+
+| Flag                  | Default         | Description                                                       |
+| --------------------- | --------------- | ----------------------------------------------------------------- |
+| `--bind <host>`       | `127.0.0.1`     | `gog watch serve` bind host.                                      |
+| `--port <port>`       | `8788`          | `gog watch serve` port.                                           |
+| `--path <path>`       | `/gmail-pubsub` | `gog watch serve` path.                                           |
+| `--include-body`      | `true`          | Include email body snippets. Pass `--no-include-body` to disable. |
+| `--max-bytes <n>`     | `20000`         | Max bytes per body snippet.                                       |
+| `--renew-minutes <n>` | `720` (12h)     | Renew Gmail watch every N minutes.                                |
+
+### Tailscale exposure
+
+| Flag                      | Default  | Description                                                      |
+| ------------------------- | -------- | ---------------------------------------------------------------- |
+| `--tailscale <mode>`      | `funnel` | Expose push endpoint via tailscale: `funnel`, `serve`, or `off`. |
+| `--tailscale-path <path>` | (none)   | Path for tailscale serve/funnel.                                 |
+| `--tailscale-target <t>`  | (none)   | Tailscale serve/funnel target (port, `host:port`, or URL).       |
+
+### Output
+
+| Flag     | Description                                       |
+| -------- | ------------------------------------------------- |
+| `--json` | Print a machine-readable summary instead of text. |
+
+## `webhooks gmail run`
+
+Run `gog watch serve` plus the watch auto-renew loop in the foreground.
+
+```bash
+nodmix webhooks gmail run --account you@example.com
+```
+
+`run` accepts the same `gog watch serve`, Nodmix delivery, Pub/Sub, and Tailscale flags as `setup`, except:
+
+- `--account` is **optional** on `run` (it falls back to the configured account).
+- `run` does **not** accept `--project`, `--push-endpoint`, or `--json`.
+- `run` flags have no built-in defaults; missing values fall back to the values written by `setup`.
+
+| Category          | Flags                                                                            |
+| ----------------- | -------------------------------------------------------------------------------- |
+| Pub/Sub           | `--account`, `--topic`, `--subscription`, `--label`                              |
+| Nodmix delivery | `--hook-url`, `--hook-token`, `--push-token`                                     |
+| `gog watch serve` | `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes` |
+| Tailscale         | `--tailscale`, `--tailscale-path`, `--tailscale-target`                          |
+
+<Note>
+For `run`, the `--topic` value is the full Pub/Sub topic path (`projects/.../topics/...`), not just the short topic name.
+</Note>
+
+## End-to-end flow
+
+See [Gmail Pub/Sub integration](/automation/cron-jobs#gmail-pubsub-integration) for the GCP project, OAuth, and gateway-side setup that pairs with these CLI commands.
+
+## Related
+
+- [CLI reference](/cli)
+- [Webhook automation](/automation/webhook)
+- [Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration)