create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/docs/coding-agent-hooks-architecture.md

@@ -0,0 +1,418 @@
+# Coding Agent Hooks Architecture
+
+Date: 2026-05-28
+
+## Purpose
+
+CTM runs several external coding agents as terminal sessions: Claude Code,
+Codex, and Gemini CLI. Those agents own their terminal UI and provider runtime,
+but CTM needs reliable lifecycle signals to render status, drive mobile status
+lanes, preserve session context, and eventually trigger memory capture at the
+right boundaries.
+
+Hooks are the bridge. They are small user-approved entries in each agent's own
+configuration that call back into CTM when an agent starts, stops, waits, or
+uses tools. They complement, but do not replace, transcripts, PTY activity,
+OpenTelemetry, and CTM's own session database.
+
+## External Contracts
+
+### Claude Code
+
+Claude Code supports hooks in JSON settings files. Its docs describe a
+read-only `/hooks` browser, user/project/local/plugin/session/built-in hook
+sources, and command hooks that receive JSON on stdin. Common input fields
+include `session_id`, `transcript_path`, `cwd`, and `permission_mode`.
+
+CTM uses user-level `~/.claude/settings.json` so the integration applies to
+Claude Code sessions launched through CTM without requiring project files to be
+modified.
+
+Source: https://code.claude.com/docs/en/hooks
+
+### Codex
+
+Codex has a different contract. CTM uses two surfaces:
+
+- OTLP log export, configured through an `[otel]` block.
+- The top-level `notify = [...]` command array, which Codex invokes on agent
+  turn completion.
+
+The Codex source defines `notify` as an optional command vector and shows it
+invoked with an `agent-turn-complete` JSON payload. Current Codex config docs
+also expose lifecycle-hook policy controls such as `allow_managed_hooks_only`
+for managed environments.
+
+Sources:
+
+- https://github.com/openai/codex/blob/main/codex-rs/core/src/config/mod.rs
+- https://github.com/openai/codex/blob/main/docs/config.md
+
+### Gemini CLI
+
+Gemini CLI uses JSON settings files, with user-level config at
+`~/.gemini/settings.json` and project-level config at `.gemini/settings.json`.
+Its hook settings include events such as `BeforeAgent`, `AfterAgent`,
+`Notification`, `SessionStart`, `SessionEnd`, `BeforeTool`, and `AfterTool`.
+The hook-writing guide emphasizes the same basic execution model CTM relies on:
+hooks receive JSON on stdin, should log to stderr, and should reserve stdout for
+JSON hook output.
+
+Sources:
+
+- https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md
+- https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/writing-hooks.md
+
+### OpenTelemetry
+
+OpenTelemetry OTLP defines HTTP endpoints such as `/v1/logs` for log export.
+The OTLP exporter configuration supports environment variables including
+`OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_PROTOCOL`; `http/json` is
+a valid protocol value.
+
+CTM uses this for low-latency agent status when an agent supports OTLP logs.
+
+Sources:
+
+- https://opentelemetry.io/docs/specs/otlp/
+- https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/
+
+## Current CTM Implementation
+
+### UI
+
+The AI Providers page has a **Coding Agents** tab. It checks:
+
+- CLI availability through `/api/models/available-agents`.
+- Hook install status through `/api/otel/status`.
+
+The card state is derived in `public/index.html`:
+
+- `Ready`: CLI detected and CTM hooks installed.
+- `Enable live status`: CLI detected but CTM has not found the integration for
+  the current CTM port.
+- `Not found`: CLI is not on PATH.
+- `Path changed` or `Config needs attention`: cached path or config inspection
+  failed.
+
+When coding agents are detected but hooks are missing, CTM shows one
+**Enable live status** prompt for every detected runtime that needs the current
+CTM port. The modal shows each target config path and a sanitized change
+summary from `/api/otel/plan-install`, then applies the idempotent installer
+only after the user approves. When hooks are already present, the card offers
+**Refresh live status** for the same idempotent repair path.
+
+The proactive prompt is allowed when the user opens the Coding Agents tab or
+when a fresh coding-agent session emits `session.needsSetup`. Passive page load
+still must not write config or install hooks.
+
+Relevant code:
+
+- `claude-task-manager/public/index.html`
+  - `_modelsCodingAgentStatusFor`
+  - `_ensureModelsAgentStatus`
+  - `installCodingAgentHooks`
+  - `renderModelsCodingAgentRoutes`
+
+### Installer
+
+`claude-task-manager/lib/agent-hooks-installer.js` is the local authority for
+config writes. It has a plan/apply split:
+
+- `planInstall(agent, port)` reads the user's config and builds the proposed
+  next text.
+- `install(agent, port)` applies the plan.
+- `planUninstall(agent, port)` removes CTM-owned entries.
+- `isInstalled(agent, port)` checks whether the current CTM integration marker
+  is present.
+
+The installer is deliberately idempotent. Re-running install should avoid
+duplicates, and uninstall should remove only CTM-owned entries while preserving
+user-owned config.
+
+Current target files:
+
+- Claude Code: `~/.claude/settings.json`
+- Codex: `~/.codex/config.toml`
+- Gemini CLI: `~/.gemini/settings.json`
+
+Current hook commands point at CTM scripts under `claude-task-manager/bin`:
+
+- `claude-hook.js`
+- `codex-notify.js`
+- `gemini-hook.js`
+
+### Agent Presets
+
+`claude-task-manager/lib/agent-presets.js` is the source of truth for each
+agent's lifecycle events:
+
+Claude Code:
+
+- `SessionStart` -> `claude-hook start`
+- `UserPromptSubmit` -> `claude-hook start`
+- `Stop` -> `claude-hook stop`
+- `Notification` -> `claude-hook idle`
+- `PreToolUse` -> `claude-hook menu`
+
+Codex:
+
+- `notify` -> `codex-notify stop`
+- OTLP env vars point logs at the CTM port.
+
+Gemini CLI:
+
+- `BeforeAgent` -> `gemini-hook start`
+- `AfterAgent` -> `gemini-hook stop`
+- `SessionEnd` -> `gemini-hook stop`
+- `BeforeTool` -> `gemini-hook menu`
+
+The same file also builds per-session environment variables, including
+`CTM_SESSION_ID`, `CTM_PORT`, and, where supported, OTLP endpoint settings.
+
+### Server Ingress
+
+CTM only accepts hook/OTLP ingress from loopback. The local server handles:
+
+- `/v1/logs` and `/api/otlp/v1/logs` -> `telemetryReceiver.handleLogs`
+- `/hook/claude/{start|stop|idle|menu}` -> `telemetryReceiver.hookClaude`
+- `/hook/codex/stop` -> `telemetryReceiver.hookCodexStop`
+- `/hook/gemini/{start|stop|menu}` -> `telemetryReceiver.hookGemini`
+
+The same receiver then broadcasts `session.status` over CTM's existing websocket
+fan-out. This is important: hooks enter through a small local ingress, but they
+reuse the normal session status contract instead of creating a parallel UI
+state model.
+
+Relevant code:
+
+- `claude-task-manager/server.js`
+  - hook/OTLP ingress near the local-only hook server block
+  - `/api/otel/status`, `/api/otel/plan-install`, `/api/otel/install`,
+    `/api/otel/uninstall`
+  - session creation watchdog that prompts setup only when hooks are missing
+    and the spawn is not a resume
+
+### Tests
+
+Existing tests cover the safety properties that matter most:
+
+- `claude-task-manager/tests/agent-hooks-installer.test.js`
+  - writes plausible Claude/Gemini settings
+  - writes Codex `[otel]` plus top-level `notify = [...]`
+  - install is idempotent
+  - uninstall preserves user-owned config
+  - legacy Codex `[notify]` section is repaired to the top-level array shape
+
+- `claude-task-manager/tests/agent-presets.test.js`
+  - agent detection
+  - OTLP/env construction
+  - inherited session identity sanitation
+
+## End-to-End Flow
+
+```text
+User opens AI Providers -> Coding Agents
+  |
+  +-- UI GET /api/models/available-agents
+  |     -> CTM discovers claude/codex/gemini binaries
+  |
+  +-- UI GET /api/otel/status
+        -> CTM checks whether the relevant config contains CTM's current hook marker
+
+User clicks Enable live status in the consent modal
+  |
+  +-- UI POST /api/otel/install?agent=<id>
+        -> agent-hooks-installer reads user config
+        -> patches only CTM-owned entries
+        -> writes the agent config file
+
+User launches an agent through CTM
+  |
+  +-- server builds env with CTM_SESSION_ID and CTM_PORT
+  +-- for OTLP-capable agents, server injects OTLP endpoint env
+  +-- agent runs normally in its terminal
+
+Agent lifecycle event happens
+  |
+  +-- provider hook invokes CTM script
+  +-- script posts JSON to localhost CTM hook endpoint
+  +-- telemetry-receiver maps event to CTM session status
+  +-- websocket broadcasts session.status
+  +-- desktop/mobile UI updates lanes, badges, and attention state
+```
+
+## Architectural Benefits
+
+### 1. Reliable Status Without Scraping Terminal Text
+
+Terminal text is a weak status source. It changes with provider UI versions,
+color themes, redraw timing, and terminal width. Hooks give CTM structured
+signals at the lifecycle boundary: start, stop, idle, tool/menu, and agent
+turn-complete.
+
+CTM should still keep PTY and transcript fallbacks, but hooks reduce the amount
+of brittle regex parsing needed for high-level state.
+
+### 2. Provider-Neutral Session State
+
+Claude, Codex, and Gemini expose different mechanics. CTM normalizes them into
+one internal contract: `session.status`. This lets the web UI, mobile UI,
+queue, notifications, and future Wall-E memory capture depend on one local CTM
+event stream instead of three provider-specific contracts.
+
+### 3. Low-Latency Mobile and Remote UX
+
+The phone status page and desktop session list need to know when an agent is
+actually running, waiting, or done. Hooks provide low-latency transitions that
+do not require polling large transcripts or waiting for terminal text to settle.
+
+This matters especially on mobile, where noisy lane movement and stale
+`Running` badges are high-friction.
+
+### 4. Correct Ownership Boundary
+
+The provider still owns execution, tool calls, permissions, and terminal UI.
+CTM only receives lifecycle facts and local telemetry. That keeps CTM from
+pretending it is the agent runtime, while still giving CTM enough signals to be
+a good control plane.
+
+### 5. Future Memory Capture Boundary
+
+Hooks are the natural point to trigger durable capture:
+
+- `SessionStart`: link provider session ID to CTM session ID.
+- `UserPromptSubmit` / `BeforeAgent`: mark a new work unit.
+- `Stop` / `AfterAgent`: flush final transcript tail and summarize.
+- `PreToolUse` / `BeforeTool`: detect approval/tool attention.
+- Future compaction hooks: preserve memory before context disappears.
+
+The existing `session-capture-foundation-design.md` already says hooks are
+strong status signals but should not be the only source of truth. The better
+architecture is "hooks as timing/evidence, transcripts as content, PTY as
+fallback."
+
+## Hooks-Optional Runtime Contract
+
+Coding-agent hooks are not required for a CTM session to work. They improve the
+status signal, but the baseline runtime path is still the PTY/session stream:
+
+- CTM creates the PTY and renders terminal output regardless of hook status.
+- `statusHooks` tracks meaningful PTY activity through the internal
+  `SessionStateBus`, even when no project or global `.ctm-hooks.json` command is
+  configured.
+- `waiting-for-input` and `session-resumed` websocket messages continue to
+  project running/waiting state through `SessionCapture` without a prior
+  `session.status` hook frame.
+- The missing-hook watchdog only emits `session.needsSetup` onboarding. It does
+  not fabricate runtime status and does not block the session.
+
+The intended degradation is therefore:
+
+```text
+With hooks:    provider hook/OTLP -> authoritative session.status -> UI
+Without hooks: PTY/session stream -> state bus + terminal fallback -> UI
+```
+
+If either path disappears, that is a regression. Keep regression coverage for
+both so hook improvements never turn into a hard runtime dependency.
+
+## Consent and Safety Model
+
+Installing hooks mutates persistent user-level files under the user's home
+directory. That means the integration can affect future CLI sessions outside
+the current CTM tab. It is useful, but it is also a trust boundary.
+
+Therefore CTM should keep hook install user-approved. CTM can proactively
+detect a missing integration and open the setup modal, but the persistent
+config write still needs an explicit user action.
+
+Required safety properties:
+
+1. Preview before write for advanced users.
+2. Idempotent install; no duplicate entries.
+3. CTM-owned marker for uninstall/repair.
+4. Preserve user-owned config and hooks.
+5. Localhost-only ingress.
+6. Clear "installed for this CTM port" semantics.
+7. Visible uninstall/disable path.
+8. No hook install during passive page load.
+9. Do not expose raw config contents through preview APIs.
+
+## Why CTM Should Not Auto-Install Hooks
+
+There are three separate reasons.
+
+First, it is a side effect outside the app workspace. The files are user-level
+agent configs, not CTM-owned project files. Silent edits would violate the same
+trust model that Claude/Codex/Gemini use for project trust and hook execution.
+
+Second, hooks are executable persistence. A hook entry runs a command in future
+agent sessions. CTM's entries are benign and local, but the class of action is
+still security-sensitive. The UI should make the write explicit.
+
+Third, the correct hook endpoint includes the CTM port. If a user runs multiple
+CTM instances, auto-install on page load could race ports and rewrite a working
+config for the wrong instance. User-initiated install gives the user control
+over which CTM instance owns the integration.
+
+## UX Recommendations
+
+1. Use **Enable live status** for missing integrations and
+   **Refresh live status** for installed integrations.
+   - "Repair" implies breakage.
+   - Both actions use an idempotent reinstall for the current CTM port.
+
+2. Keep the setup preview in a consent modal.
+   - Use existing `/api/otel/plan-install`.
+   - Show target file path and a sanitized CTM-owned change summary.
+   - Do not send or render raw current/next config text in the browser.
+
+3. Add **Remove integration** when hooks are installed.
+   - Use existing `/api/otel/uninstall`.
+   - This makes the trust boundary reversible.
+
+4. Explain the status in product terms:
+   - CLI: "Can CTM launch this runtime?"
+   - Hooks: "Can this runtime report live state back to CTM?"
+   - Provider link: "Which model provider powers this runtime?"
+
+5. Keep provider config separate.
+   - Hooks do not configure API keys or default models.
+   - Provider cards configure model access.
+   - Coding Agent cards configure session runtime observability.
+
+6. Prefer user-level config by default, but expose the target.
+   - The current code writes user-level config.
+   - If project-scoped hooks are added later, the UI must make scope explicit.
+
+## Open Questions
+
+1. Should CTM support project-scoped hook installs for teams that do not want
+   user-level global hooks?
+2. Should "Ready" require both hooks and a successful live test event, or is
+   config presence enough?
+3. Should Codex move from `notify`-only completion hooks to newer managed
+   lifecycle hook config if/when the CLI exposes a stable user-level contract?
+4. Should Wall-E memory capture become a first-class hook subscriber, or should
+   it continue consuming normalized CTM session events?
+
+## Proposed North Star
+
+Hooks should be treated as a local, consented observability layer for coding
+agents. The architecture should stay provider-neutral:
+
+```text
+Provider-specific hook/telemetry inputs
+  -> CTM local ingress
+  -> telemetry-receiver normalization
+  -> session.status + capture events
+  -> desktop/mobile UI, notifications, Wall-E memory, queues
+```
+
+This keeps the model clean:
+
+- Coding agents own execution.
+- AI Providers own model access.
+- CTM owns orchestration, status, mobile/desktop control surfaces, and durable
+  session evidence.

package/template/claude-task-manager/docs/conversation-import-freshness.md

@@ -52,6 +52,26 @@ This filter belongs at the parser and `/api/session/messages` boundaries. UI
 surfaces can keep a defensive check for already-cached old rows, but desktop and
 phone should both converge on the normalized API result.
 
+## Codex User Echo Dedupe
+
+Codex can record the same human prompt twice for one turn: once as a
+`response_item` user message and again as an `event_msg.user_message`. CTM must
+collapse that provider echo so Conversation, Review, search, and phone timelines
+do not show duplicate user turns.
+
+The dedupe key is **not** globally unique text. Long-lived Codex sessions often
+repeat the same prompt days later, for example rerunning the same research skill
+after follow-up design work. Those later prompts are distinct human turns and
+must remain visible. The importer therefore dedupes only same-text user events
+inside a short timestamp window. If the timestamp is missing, CTM falls back to
+conservative same-text dedupe because it cannot prove the events are separate.
+
+The Codex conversation importer records a parser version on
+`session_conversations`. When this semantic contract changes, same-size Codex
+caches with an older parser version must be eligible for full re-import; file
+size alone is not enough to prove a cache is fresh. This avoids one-off DB edits
+for historical sessions whose raw rollout still contains the correct prompt.
+
 ## Non-Starving Scheduling
 
 Background DB work can defer briefly while the user is actively interacting

package/template/claude-task-manager/docs/google-workspace-auth-health.md

@@ -0,0 +1,77 @@
+# Google Workspace Auth Health
+
+## Problem
+
+Google sign-in happens outside the CTM browser tab. After OAuth completes, the
+setup page can still show an old "Google account needs reconnection" banner if
+the page does not refresh its Wall-E credential state. The browser's Google
+login state is not a valid source of truth for CTM; Wall-E must verify the
+stored `gws` credentials and then update both setup UI and service alerts from
+that verified state.
+
+## Source Of Truth
+
+`/api/wall-e/gws/accounts` is the authoritative health endpoint for connected
+Google accounts. It derives each account state by asking the bundled
+`gws-workspace` setup module for usable credentials:
+
+- `tokenValid: true` means Wall-E has a usable access token for that account.
+- `reauthRequired: true` means the saved refresh credential is missing, expired,
+  or revoked.
+- `authIssue` is a user-facing explanation of the credential problem.
+
+The setup page must render the reconnection banner only from this endpoint. It
+must not infer success from a browser Google cookie or from returning to the CTM
+tab after OAuth.
+
+## Alert Reconciliation
+
+Service alerts are persisted in Wall-E's `service_alerts` KV entry and surfaced
+on the Wall-E panel and session pages. Google Workspace account alerts use this
+stable service key:
+
+```text
+google_workspace:<profile-id-or-default>:<lowercase-email>
+```
+
+Whenever Wall-E proves an account is usable, it should clear only resolved
+Google Workspace auth alerts for that same account. This mirrors the existing
+Slack health model while keeping unrelated alerts, disabled-skill alerts, and
+other providers intact.
+
+Reconciliation happens at two boundaries:
+
+1. OAuth completion: `completeGoogleAuthFlow()` only completes after
+   `gwsSetup.getCredentials()` returns a usable access token, then clears the
+   account's stale `gws_reauth` alert.
+2. Health reads: `/api/wall-e/gws/accounts` opportunistically clears stale
+   auth alerts for every account it reports as usable, so any setup page refresh
+   self-heals old alert state.
+
+## Browser Refresh Contract
+
+Setup should refresh connected services when the user returns from an external
+OAuth window:
+
+- `pageshow`
+- `focus`
+- visible `visibilitychange`
+- `online`
+
+These events only trigger a small debounced `/api/wall-e/gws/accounts` refresh.
+The page still uses explicit OAuth flow polling while CTM owns the flow, but it
+does not rely on blind background polling to repair stale UI.
+
+The endpoint and browser fetch should use no-store/no-cache semantics because
+credential health is live operational state, not a static catalog.
+
+## Tests
+
+Coverage should prove:
+
+- Google auth completion clears stale account-specific `gws_reauth` alerts only
+  after credentials are usable.
+- Google alert clearing does not remove unrelated Google, Slack, or disabled
+  skill alerts.
+- The setup page removes the reconnection banner when a foreground lifecycle
+  refresh sees the account become healthy.

package/template/claude-task-manager/docs/image-paste-ux.md

@@ -12,6 +12,7 @@ CTM treats pasted screenshots as first-class attachments and shows compact promp
 
 - Terminal sessions: paste events and the macOS `Ctrl+V` compatibility path upload images and insert the compact token, for example `[Image #1]`. The token is what the user sees and edits in both Claude and Codex sessions. `Cmd+Shift+V` on macOS and `Ctrl+Shift+V` elsewhere intentionally paste the raw local path reference. The terminal context menu can copy all pasted image paths or URLs for the active session.
 - Terminal sessions backed by Claude Code or Codex use provider-native image handoff. CTM uploads and normalizes the browser clipboard image, then sends the normalized local image path as a bracketed paste to the PTY. The provider creates the real image attachment and renders its own compact `[Image #n]` chip, so the model receives image context while the terminal does not show raw paths.
+- Terminal sessions backed by Claude Code or Codex also append durable image metadata when the prompt is submitted. CTM does not change the paste behavior: paste still inserts the compact token and keeps provider-native path handoff intact. At Enter/submit time, any unsent image attachments from the active input are appended once as `[Attached image: "..."]` or `[Attached images: "...", "..."]` before the newline reaches the PTY. This makes future Conversation/Review import able to resolve the image path even if the provider transcript only preserves terminal text.
 - Terminal text paste also normalizes CTM image references. If the clipboard contains `[Image #1: "/path/to/file.png"]`, a raw local image path, or an `/api/images/file/...` URL, default paste deduplicates repeated references and hands each local image path to provider-native attachment paste when possible.
 - Terminal image paste accepts browser clipboard files by `image/*` MIME type or by common image filename extension when the OS leaves the MIME type empty.
 - Wall-E sessions: pasted images become structured message attachments. The composer inserts `[Image #n]`; sending preserves the compact token in the message text and sends image data separately.
@@ -20,3 +21,15 @@ CTM treats pasted screenshots as first-class attachments and shows compact promp
 ## Provider Contract
 
 Compact tokens are UI references, not raw file paths. CTM keeps attachment metadata, normalized uploads, and copyable path/URL references beside the visible token. Provider adapters must not send only `[Image #n]` to a raw PTY. They should either send structured attachments, or, for Claude Code and Codex terminal sessions, trigger native image attachment by bracket-pasting the normalized local image path. Explicit path paste remains available for CLIs that require a visible local filesystem reference in the prompt text.
+
+Submit-time metadata is a transcript durability layer, not a replacement for native provider image attachment. It must not run during paste, path-copy, or path-paste handling, and it must mark attachments as submitted or discarded so later prompts do not inherit stale image references.
+
+## Performance Contract
+
+Image storage must not do large synchronous work on CTM's primary Node.js event loop.
+
+- Browser uploads may arrive as buffers, but hashing must process large buffers in bounded chunks and yield between chunks.
+- Screenshot capture must store the captured file through a streaming file path, then rename or copy it into the content-addressed image store. Do not synchronously read the screenshot back into a full buffer after `screencapture` exits.
+- The shared image-store helpers are the boundary for this behavior: `saveImage()` handles in-memory uploads, while `saveImageFromFile()` handles captured or already-on-disk images.
+
+This keeps terminal typing, WebSocket output flushes, and screenshot preview rendering responsive while large Retina screenshots are being stored.

package/template/claude-task-manager/docs/ipad-web-preview.md

@@ -0,0 +1,88 @@
+# CTM iPad Web Preview
+
+Status: implemented for local and staging checks
+Date: 2026-05-19
+
+## Goal
+
+Use `/ipad.html` to run the CTM mobile app inside an iPad-sized frame from any CTM server. This is a fast desktop-browser check for the iPad layout before testing on a physical iPad.
+
+The preview is intentionally same-origin by default:
+
+```text
+http://localhost:3456/ipad.html
+  frames
+http://localhost:3456/m/
+```
+
+When testing a staging/tunnel server, open that server's own preview page:
+
+```text
+https://<staging-host>/ipad.html
+```
+
+That keeps CTM cookies, device tokens, service worker scope, and API calls on the same origin as the mobile app.
+
+## Run A Safe Local Staging Instance
+
+Use `bin/dev.sh --refresh` with a separate port and data directory so iPad testing has copied CTM/Wall-E data without mutating the primary CTM state:
+
+```bash
+WALLE_DEV_DIR=/tmp/walle-dev-4456 \
+DEV_CTM_PORT=4456 \
+DEV_WALLE_PORT=4457 \
+bash bin/dev.sh --refresh
+```
+
+Open:
+
+```text
+http://localhost:4456/ipad.html
+```
+
+The source field defaults to `/m/`. Keep it there for normal testing. If the preview loads but has no sessions, restart with `--refresh`; that copies the current CTM and Wall-E databases into the staging data directory.
+
+## Preview Modes
+
+`/ipad.html` includes four device presets:
+
+- `Test Portrait`: `768 x 1024`, matching the automated tablet regression test.
+- `Test Landscape`: `1024 x 768`, matching the automated split-workspace regression test.
+- `11 Portrait`: `834 x 1194`, close to an 11-inch iPad CSS viewport.
+- `11 Landscape`: `1194 x 834`, close to an 11-inch iPad landscape viewport.
+
+Use `Reload` to reload only the framed mobile app. Use `Open` to launch the framed URL directly.
+
+## What This Catches
+
+- Tablet breakpoint regressions.
+- Horizontal overflow.
+- Portrait single-column sizing.
+- Landscape list/detail split layout.
+- Detail pane modal-vs-region behavior.
+- Composer and bottom navigation placement.
+- Search and session-card density at iPad widths.
+
+## What Still Requires A Real iPad
+
+The preview does not replace Safari-on-iPad validation. Always do one physical-device pass before shipping high-risk mobile changes because desktop browser framing does not fully emulate:
+
+- iPad Safari viewport height changes when the software keyboard opens.
+- PWA standalone mode.
+- touch momentum scrolling and rubber-band edges.
+- safe-area inset differences.
+- iOS third-party cookie and passkey behavior.
+- real camera/file-picker attachment flows.
+
+## Automated Companion Test
+
+The existing mobile render suite covers the same core tablet breakpoints:
+
+```bash
+npm --prefix claude-task-manager exec playwright test -- \
+  --config tests/rendering/playwright.config.js \
+  scenarios/mobile-pwa.spec.js \
+  -g "iPad|tablet|iPad preview"
+```
+
+Use the automated test for regression gates and `/ipad.html` for quick visual inspection.