fengming 0.3.10 → 0.3.12

package/docs/platforms/mac/canvas.md

@@ -1,128 +0,0 @@
----
-summary: "Agent-controlled Canvas panel embedded via WKWebView + custom URL scheme"
-read_when:
-  - Implementing the macOS Canvas panel
-  - Adding agent controls for visual workspace
-  - Debugging WKWebView canvas loads
-title: "Canvas"
----
-
-The macOS app embeds an agent-controlled **Canvas panel** using `WKWebView`. It
-is a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive
-UI surfaces.
-
-## Where Canvas lives
-
-Canvas state is stored under Application Support:
-
-- `~/Library/Application Support/FengMing/canvas/<session>/...`
-
-The Canvas panel serves those files via a **custom URL scheme**:
-
-- `fengming-canvas://<session>/<path>`
-
-Examples:
-
-- `fengming-canvas://main/` → `<canvasRoot>/main/index.html`
-- `fengming-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
-- `fengming-canvas://main/widgets/todo/` → `<canvasRoot>/main/widgets/todo/index.html`
-
-If no `index.html` exists at the root, the app shows a **built-in scaffold page**.
-
-## Panel behavior
-
-- Borderless, resizable panel anchored near the menu bar (or mouse cursor).
-- Remembers size/position per session.
-- Auto-reloads when local canvas files change.
-- Only one Canvas panel is visible at a time (session is switched as needed).
-
-Canvas can be disabled from Settings → **Allow Canvas**. When disabled, canvas
-node commands return `CANVAS_DISABLED`.
-
-## Agent API surface
-
-Canvas is exposed via the **Gateway WebSocket**, so the agent can:
-
-- show/hide the panel
-- navigate to a path or URL
-- evaluate JavaScript
-- capture a snapshot image
-
-CLI examples:
-
-```bash
-fengming nodes canvas present --node <id>
-fengming nodes canvas navigate --node <id> --url "/"
-fengming nodes canvas eval --node <id> --js "document.title"
-fengming nodes canvas snapshot --node <id>
-```
-
-Notes:
-
-- `canvas.navigate` accepts **local canvas paths**, `http(s)` URLs, and `file://` URLs.
-- If you pass `"/"`, the Canvas shows the local scaffold or `index.html`.
-
-## A2UI in Canvas
-
-A2UI is hosted by the Gateway canvas host and rendered inside the Canvas panel.
-When the Gateway advertises a Canvas host, the macOS app auto-navigates to the
-A2UI host page on first open.
-
-Default A2UI host URL:
-
-```
-http://<gateway-host>:18789/__fengming__/a2ui/
-```
-
-### A2UI commands (v0.8)
-
-Canvas currently accepts **A2UI v0.8** server→client messages:
-
-- `beginRendering`
-- `surfaceUpdate`
-- `dataModelUpdate`
-- `deleteSurface`
-
-`createSurface` (v0.9) is not supported.
-
-CLI example:
-
-```bash
-cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
-{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
-{"beginRendering":{"surfaceId":"main","root":"root"}}
-EOFA2
-
-fengming nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
-```
-
-Quick smoke:
-
-```bash
-fengming nodes canvas a2ui push --node <id> --text "Hello from A2UI"
-```
-
-## Triggering agent runs from Canvas
-
-Canvas can trigger new agent runs via deep links:
-
-- `fengming://agent?...`
-
-Example (in JS):
-
-```js
-window.location.href = "fengming://agent?message=Review%20this%20design";
-```
-
-The app prompts for confirmation unless a valid key is provided.
-
-## Security notes
-
-- Canvas scheme blocks directory traversal; files must live under the session root.
-- Local Canvas content uses a custom scheme (no loopback server required).
-- External `http(s)` URLs are allowed only when explicitly navigated.
-
-## Related
-
-- [macOS app](/platforms/macos)
-- [WebChat](/web/webchat)

package/docs/platforms/mac/child-process.md

@@ -1,72 +0,0 @@
----
-summary: "Gateway lifecycle on macOS (launchd)"
-read_when:
-  - Integrating the mac app with the gateway lifecycle
-title: "Gateway lifecycle on macOS"
----
-
-The macOS app **manages the Gateway via launchd** by default and does not spawn
-the Gateway as a child process. It first tries to attach to an already-running
-Gateway on the configured port; if none is reachable, it enables the launchd
-service via the external `fengming` CLI (no embedded runtime). This gives you
-reliable auto-start at login and restart on crashes.
-
-Child-process mode (Gateway spawned directly by the app) is **not in use** today.
-If you need tighter coupling to the UI, run the Gateway manually in a terminal.
-
-## Default behavior (launchd)
-
-- The app installs a per-user LaunchAgent labeled `ai.fengming.gateway`
-  (or `ai.fengming.<profile>` when using `--profile`/`FENGMING_PROFILE`; legacy `com.fengming.*` is supported).
-- When Local mode is enabled, the app ensures the LaunchAgent is loaded and
-  starts the Gateway if needed.
-- Logs are written to the launchd gateway log path (visible in Debug Settings).
-
-Common commands:
-
-```bash
-launchctl kickstart -k gui/$UID/ai.fengming.gateway
-launchctl bootout gui/$UID/ai.fengming.gateway
-```
-
-Replace the label with `ai.fengming.<profile>` when running a named profile.
-
-## Unsigned dev builds
-
-`scripts/restart-mac.sh --no-sign` is for fast local builds when you don't have
-signing keys. To prevent launchd from pointing at an unsigned relay binary, it:
-
-- Writes `~/.fengming/disable-launchagent`.
-
-Signed runs of `scripts/restart-mac.sh` clear this override if the marker is
-present. To reset manually:
-
-```bash
-rm ~/.fengming/disable-launchagent
-```
-
-## Attach-only mode
-
-To force the macOS app to **never install or manage launchd**, launch it with
-`--attach-only` (or `--no-launchd`). This sets `~/.fengming/disable-launchagent`,
-so the app only attaches to an already running Gateway. You can toggle the same
-behavior in Debug Settings.
-
-## Remote mode
-
-Remote mode never starts a local Gateway. The app uses an SSH tunnel to the
-remote host and connects over that tunnel.
-
-## Why we prefer launchd
-
-- Auto-start at login.
-- Built-in restart/KeepAlive semantics.
-- Predictable logs and supervision.
-
-If a true child-process mode is ever needed again, it should be documented as a
-separate, explicit dev-only mode.
-
-## Related
-
-- [macOS app](/platforms/macos)
-- [Gateway runbook](/gateway)

package/docs/platforms/mac/dev-setup.md

@@ -1,112 +0,0 @@
----
-summary: "Setup guide for developers working on the FengMing macOS app"
-read_when:
-  - Setting up the macOS development environment
-title: "macOS dev setup"
----
-
-# macOS developer setup
-
-Build and run the FengMing macOS application from source.
-
-## Prerequisites
-
-Before building the app, ensure you have the following installed:
-
-1. **Xcode 26.2+**: Required for Swift development.
-2. **Node.js 24 & pnpm**: Recommended for the gateway, CLI, and packaging scripts. Node 22 LTS, currently `22.19+`, remains supported for compatibility.
-
-## 1. Install Dependencies
-
-Install the project-wide dependencies:
-
-```bash
-pnpm install
-```
-
-## 2. Build and Package the App
-
-To build the macOS app and package it into `dist/FengMing.app`, run:
-
-```bash
-./scripts/package-mac-app.sh
-```
-
-If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`).
-
-For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README:
-[https://github.com/fengming/fengming/blob/main/apps/macos/README.md](https://github.com/fengming/fengming/blob/main/apps/macos/README.md)
-
-> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
-
-## 3. Install the CLI
-
-The macOS app expects a global `fengming` CLI install to manage background tasks.
-
-**To install it (recommended):**
-
-1. Open the FengMing app.
-2. Go to the **General** settings tab.
-3. Click **"Install CLI"**.
-
-Alternatively, install it manually:
-
-```bash
-npm install -g fengming@<version>
-```
-
-`pnpm add -g fengming@<version>` and `bun add -g fengming@<version>` also work.
-For the Gateway runtime, Node remains the recommended path.
-
-## Troubleshooting
-
-### Build fails: toolchain or SDK mismatch
-
-The macOS app build expects the latest macOS SDK and Swift 6.2 toolchain.
-
-**System dependencies (required):**
-
-- **Latest macOS version available in Software Update** (required by Xcode 26.2 SDKs)
-- **Xcode 26.2** (Swift 6.2 toolchain)
-
-**Checks:**
-
-```bash
-xcodebuild -version
-xcrun swift --version
-```
-
-If versions don't match, update macOS/Xcode and re-run the build.
-
-### App crashes on permission grant
-
-If the app crashes when you try to allow **Speech Recognition** or **Microphone** access, it may be due to a corrupted TCC cache or signature mismatch.
-
-**Fix:**
-
-1. Reset the TCC permissions:
-
-   ```bash
-   tccutil reset All ai.fengming.mac.debug
-   ```
-
-2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/fengming/fengming/blob/main/scripts/package-mac-app.sh) to force a "clean slate" from macOS.
-
-### Gateway "Starting..." indefinitely
-
-If the gateway status stays on "Starting...", check if a zombie process is holding the port:
-
-```bash
-fengming gateway status
-fengming gateway stop
-
-# If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
-lsof -nP -iTCP:18789 -sTCP:LISTEN
-```
-
-If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.
-
-## Related
-
-- [macOS app](/platforms/macos)
-- [Install overview](/install)

package/docs/platforms/mac/health.md

@@ -1,39 +0,0 @@
----
-summary: "How the macOS app reports gateway/Baileys health states"
-read_when:
-  - Debugging mac app health indicators
-title: "Health checks (macOS)"
----
-
-# Health Checks on macOS
-
-How to see whether the linked channel is healthy from the menu bar app.
-
-## Menu bar
-
-- Status dot now reflects Baileys health:
-  - Green: linked + socket opened recently.
-  - Orange: connecting/retrying.
-  - Red: logged out or probe failed.
-- Secondary line reads "linked · auth 12m" or shows the failure reason.
-- "Run Health Check" menu item triggers an on-demand probe.
-
-## Settings
-
-- General tab gains a Health card showing: linked auth age, session-store path/count, last check time, last error/status code, and buttons for Run Health Check / Reveal Logs.
-- Uses a cached snapshot so the UI loads instantly and falls back gracefully when offline.
-- **Channels tab** surfaces channel status + controls for WhatsApp/Telegram (login QR, logout, probe, last disconnect/error).
-
-## How the probe works
-
-- App runs `fengming health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds and reports status without sending messages.
-- Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.
-
-## When in doubt
-
-- You can still use the CLI flow in [Gateway health](/gateway/health) (`fengming status`, `fengming status --deep`, `fengming health --json`) and tail `/tmp/fengming/fengming-*.log` for `web-heartbeat` / `web-reconnect`.
-
-## Related
-
-- [Gateway health](/gateway/health)
-- [macOS app](/platforms/macos)

package/docs/platforms/mac/icon.md

@@ -1,36 +0,0 @@
----
-summary: "Menu bar icon states and animations for FengMing on macOS"
-read_when:
-  - Changing menu bar icon behavior
-title: "Menu bar icon"
----
-
-# Menu Bar Icon States
-
-Author: steipete · Updated: 2025-12-06 · Scope: macOS app (`apps/macos`)
-
-- **Idle:** Normal icon animation (blink, occasional wiggle).
-- **Paused:** Status item uses `appearsDisabled`; no motion.
-- **Voice trigger (big ears):** Voice wake detector calls `AppState.triggerVoiceEars(ttl: nil)` when the wake word is heard, keeping `earBoostActive=true` while the utterance is captured. Ears scale up (1.9x), get circular ear holes for readability, then drop via `stopVoiceEars()` after 1s of silence. Only fired from the in-app voice pipeline.
-- **Working (agent running):** `AppState.isWorking=true` drives a "tail/leg scurry" micro-motion: faster leg wiggle and slight offset while work is in-flight. Currently toggled around WebChat agent runs; add the same toggle around other long tasks when you wire them.
-
-Wiring points
-
-- Voice wake: runtime/tester call `AppState.triggerVoiceEars(ttl: nil)` on trigger and `stopVoiceEars()` after 1s of silence to match the capture window.
-- Agent activity: set `AppStateStore.shared.setWorking(true/false)` around work spans (already done in WebChat agent call). Keep spans short and reset in `defer` blocks to avoid stuck animations.
-
-Shapes & sizes
-
-- Base icon drawn in `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)`.
-- Ear scale defaults to `1.0`; voice boost sets `earScale=1.9` and toggles `earHoles=true` without changing overall frame (18×18 pt template image rendered into a 36×36 px Retina backing store).
-- Scurry uses leg wiggle up to ~1.0 with a small horizontal jiggle; it's additive to any existing idle wiggle.
-
-Behavioral notes
-
-- No external CLI/broker toggle for ears/working; keep it internal to the app's own signals to avoid accidental flapping.
-- Keep TTLs short (<10s) so the icon returns to baseline quickly if a job hangs.
-
-## Related
-
-- [Menu bar](/platforms/mac/menu-bar)
-- [macOS app](/platforms/macos)

package/docs/platforms/mac/logging.md

@@ -1,62 +0,0 @@
----
-summary: "FengMing logging: rolling diagnostics file log + unified log privacy flags"
-read_when:
-  - Capturing macOS logs or investigating private data logging
-  - Debugging voice wake/session lifecycle issues
-title: "macOS logging"
----
-
-# Logging (macOS)
-
-## Rolling diagnostics file log (Debug pane)
-
-FengMing routes macOS app logs through swift-log (unified logging by default) and can write a local, rotating file log to disk when you need a durable capture.
-
-- Verbosity: **Debug pane → Logs → App logging → Verbosity**
-- Enable: **Debug pane → Logs → App logging → "Write rolling diagnostics log (JSONL)"**
-- Location: `~/Library/Logs/FengMing/diagnostics.jsonl` (rotates automatically; old files are suffixed with `.1`, `.2`, …)
-- Clear: **Debug pane → Logs → App logging → "Clear"**
-
-Notes:
-
-- This is **off by default**. Enable only while actively debugging.
-- Treat the file as sensitive; don't share it without review.
-
-## Unified logging private data on macOS
-
-Unified logging redacts most payloads unless a subsystem opts into `privacy -off`. Per Peter's write-up on macOS [logging privacy shenanigans](https://steipete.me/posts/2025/logging-privacy-shenanigans) (2025) this is controlled by a plist in `/Library/Preferences/Logging/Subsystems/` keyed by the subsystem name. Only new log entries pick up the flag, so enable it before reproducing an issue.
-
-## Enable for FengMing (`ai.fengming`)
-
-- Write the plist to a temp file first, then install it atomically as root:
-
-```bash
-cat <<'EOF' >/tmp/ai.fengming.plist
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>DEFAULT-OPTIONS</key>
-    <dict>
-        <key>Enable-Private-Data</key>
-        <true/>
-    </dict>
-</dict>
-</plist>
-EOF
-sudo install -m 644 -o root -g wheel /tmp/ai.fengming.plist /Library/Preferences/Logging/Subsystems/ai.fengming.plist
-```
-
-- No reboot is required; logd notices the file quickly, but only new log lines will include private payloads.
-- View the richer output with the existing helper, e.g. `./scripts/clawlog.sh --category WebChat --last 5m`.
-
-## Disable after debugging
-
-- Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/ai.fengming.plist`.
-- Optionally run `sudo log config --reload` to force logd to drop the override immediately.
-- Remember this surface can include phone numbers and message bodies; keep the plist in place only while you actively need the extra detail.
-
-## Related
-
-- [macOS app](/platforms/macos)
-- [Gateway logging](/gateway/logging)

package/docs/platforms/mac/menu-bar.md

@@ -1,93 +0,0 @@
----
-summary: "Menu bar status logic and what is surfaced to users"
-read_when:
-  - Tweaking mac menu UI or status logic
-title: "Menu bar"
----
-
-## What is shown
-
-- We surface the current agent work state in the menu bar icon and in the first status row of the menu.
-- Health status is hidden while work is active; it returns when all sessions are idle.
-- A root "Context" submenu contains recent sessions instead of expanding them directly in the root menu.
-- The "Nodes" block in the root menu lists **devices** only (paired nodes via `node.list`), not client/presence entries.
-- A root "Usage" section appears below Context when provider usage snapshots are available, followed by usage-cost details when available.
-
-## State model
-
-- Sessions: events arrive with `runId` (per-run) plus `sessionKey` in the payload. The "main" session is the key `main`; if absent, we fall back to the most recently updated session.
-- Priority: main always wins. If main is active, its state is shown immediately. If main is idle, the most recently active non-main session is shown. We do not flip-flop mid-activity; we only switch when the current session goes idle or main becomes active.
-- Activity kinds:
-  - `job`: high-level command execution (`state: started|streaming|done|error`).
-  - `tool`: `phase: start|result` with `toolName` and `meta/args`.
-
-## IconState enum (Swift)
-
-- `idle`
-- `workingMain(ActivityKind)`
-- `workingOther(ActivityKind)`
-- `overridden(ActivityKind)` (debug override)
-
-### ActivityKind → glyph
-
-- `exec` → 💻
-- `read` → 📄
-- `write` → ✍️
-- `edit` → 📝
-- `attach` → 📎
-- default → 🛠️
-
-### Visual mapping
-
-- `idle`: normal critter.
-- `workingMain`: badge with glyph, full tint, leg "working" animation.
-- `workingOther`: badge with glyph, muted tint, no scurry.
-- `overridden`: uses the chosen glyph/tint regardless of activity.
-
-## Context submenu
-
-- The root menu shows one "Context" row with a session count/status and opens a submenu.
-- The Context submenu header shows the active session count for the last 24 hours.
-- Each session row keeps its token bar, age, preview, thinking/verbose, reset, compact, and delete actions.
-- Loading, disconnected, and session-load error messages appear inside the Context submenu.
-- Provider usage and usage-cost details stay root-level below Context so they remain glanceable without opening the submenu.
-
-## Status row text (menu)
-
-- While work is active: `<Session role> · <activity label>`
-  - Examples: `Main · exec: pnpm test`, `Other · read: apps/macos/Sources/FengMing/AppState.swift`.
-- When idle: falls back to the health summary.
-
-## Event ingestion
-
-- Source: control-channel `agent` events (`ControlChannel.handleAgentEvent`).
-- Parsed fields:
-  - `stream: "job"` with `data.state` for start/stop.
-  - `stream: "tool"` with `data.phase`, `name`, optional `meta`/`args`.
-- Labels:
-  - `exec`: first line of `args.command`.
-  - `read`/`write`: shortened path.
-  - `edit`: path plus inferred change kind from `meta`/diff counts.
-  - fallback: tool name.
-
-## Debug override
-
-- Settings ▸ Debug ▸ "Icon override" picker:
-  - `System (auto)` (default)
-  - `Working: main` (per tool kind)
-  - `Working: other` (per tool kind)
-  - `Idle`
-- Stored via `@AppStorage("iconOverride")`; mapped to `IconState.overridden`.
-
-## Testing checklist
-
-- Trigger main session job: verify icon switches immediately and status row shows main label.
-- Trigger non-main session job while main idle: icon/status shows non-main; stays stable until it finishes.
-- Start main while other active: icon flips to main instantly.
-- Rapid tool bursts: ensure badge does not flicker (TTL grace on tool results).
-- Health row reappears once all sessions idle.
-
-## Related
-
-- [macOS app](/platforms/macos)
-- [Menu bar icon](/platforms/mac/icon)

package/docs/platforms/mac/peekaboo.md

@@ -1,96 +0,0 @@
----
-summary: "PeekabooBridge integration for macOS UI automation"
-read_when:
-  - Hosting PeekabooBridge in FengMing.app
-  - Integrating Peekaboo via Swift Package Manager
-  - Changing PeekabooBridge protocol/paths
-  - Deciding between PeekabooBridge, Codex Computer Use, and cua-driver MCP
-title: "Peekaboo bridge"
----
-
-FengMing can host **PeekabooBridge** as a local, permission-aware UI automation
-broker. This lets the `peekaboo` CLI drive UI automation while reusing the
-macOS app's TCC permissions.
-
-## What this is (and is not)
-
-- **Host**: FengMing.app can act as a PeekabooBridge host.
-- **Client**: use the `peekaboo` CLI (no separate `fengming ui ...` surface).
-- **UI**: visual overlays stay in Peekaboo.app; FengMing is a thin broker host.
-
-## Relationship to Computer Use
-
-FengMing has three desktop-control paths, and they intentionally stay separate:
-
-- **PeekabooBridge host**: FengMing.app can host the local PeekabooBridge socket.
-  The `peekaboo` CLI remains the client and uses FengMing.app's macOS
-  permissions for Peekaboo automation primitives such as screenshots, clicks,
-  menus, dialogs, Dock actions, and window management.
-- **Codex Computer Use**: the bundled `codex` plugin prepares Codex app-server,
-  verifies that Codex's `computer-use` MCP server is available, and then lets
-  Codex own native desktop-control tool calls during Codex-mode turns. FengMing
-  does not proxy those actions through PeekabooBridge.
-- **Direct `cua-driver` MCP**: FengMing can register TryCua's upstream
-  `cua-driver mcp` server as a normal MCP server. That gives agents the CUA
-  driver's own schemas and pid/window/element-index workflow without routing
-  through the Codex marketplace or the PeekabooBridge socket.
-
-Use Peekaboo when you want the broad macOS automation surface and FengMing.app's
-permission-aware bridge host. Use Codex Computer Use when a Codex-mode agent
-should rely on Codex's native computer-use plugin. Use direct `cua-driver mcp`
-when you want the CUA driver exposed to any FengMing-managed runtime as a normal
-MCP server.
-
-## Enable the bridge
-
-In the macOS app:
-
-- Settings → **Enable Peekaboo Bridge**
-
-When enabled, FengMing starts a local UNIX socket server. If disabled, the host
-is stopped and `peekaboo` will fall back to other available hosts.
-
-## Client discovery order
-
-Peekaboo clients typically try hosts in this order:
-
-1. Peekaboo.app (full UX)
-2. Claude.app (if installed)
-3. FengMing.app (thin broker)
-
-Use `peekaboo bridge status --verbose` to see which host is active and which
-socket path is in use. You can override with:
-
-```bash
-export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
-```
-
-## Security and permissions
-
-- The bridge validates **caller code signatures**; an allowlist of TeamIDs is
-  enforced (Peekaboo host TeamID + FengMing app TeamID).
-- Prefer the signed bridge/app identity over a generic `node` runtime for
-  Accessibility. Granting Accessibility to `node` lets any package launched by
-  that Node executable inherit GUI automation access; see
-  [macOS permissions](/platforms/mac/permissions#accessibility-grants-for-node-and-cli-runtimes).
-- Requests time out after ~10 seconds.
-- If required permissions are missing, the bridge returns a clear error message
-  rather than launching System Settings.
-
-## Snapshot behavior (automation)
-
-Snapshots are stored in memory and expire automatically after a short window.
-If you need longer retention, re-capture from the client.
-
-## Troubleshooting
-
-- If `peekaboo` reports "bridge client is not authorized", ensure the client is
-  properly signed or run the host with `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`
-  in **debug** mode only.
-- If no hosts are found, open one of the host apps (Peekaboo.app or FengMing.app)
-  and confirm permissions are granted.
-
-## Related
-
-- [macOS app](/platforms/macos)
-- [macOS permissions](/platforms/mac/permissions)