## v0.11.0

v0.11.0 is a user-facing release focused on first-run setup, desktop behavior,
Codex reliability, and release hardening. It adds the first-run onboarding
wizard, free-roam idle movement, the dizzy spin reaction, Windows fullscreen
overlay handling, Codex official-hook health surfacing, Remote SSH
connect-on-launch, safer hook settings backups, and a broad set of fixes around
completion celebrations, low-power wake recovery, Reasonix, Telegram approvals,
and Ghostty focus.

This release also welcomes **seven first-time contributors**.

### New Features

- **First-run onboarding tutorial** (#524) - New users, and existing users who have never seen the tutorial, get a one-time setup wizard covering language, agent install/cleanup, shortcuts, and key features. Any dismissal marks it seen so it does not reopen on later launches.
- **Free roam mode** (#467, #570) - When enabled, the pet can wander around the desk while idle, with cancellation on state changes, mini-mode guards, hit-window/HUD/bubble sync during movement, and target-selection hardening. Thanks to first-time contributor @zhaoxv210, with a follow-up flake fix from first-time contributor @Git-creat7.
- **Dizzy spin reaction** (#507) - Rapidly circling the cursor around Clawd can trigger the existing dizzy animation on themes that support it, with cooldowns and theme-capability gating so unsupported themes keep normal idle behavior. Thanks to first-time contributor @IatomicreactorI.
- **Windows fullscreen overlay mode** (#538, #562) - Clawd can float over foreground fullscreen apps while keeping the hit window non-activating, so borderless-fullscreen games are not kicked out by clicks or drags. The old settings toggle was removed because it could not reliably force the pet behind borderless games; the hidden pref remains as an escape hatch.
- **Codex official hook health** (#571) - Since Codex approval awareness now depends on official `PermissionRequest` hooks, the Agents tab and startup nudge now surface disabled, unreviewed, missing, or broken Codex hook states using the same detector as Doctor.
- **Remote SSH connect-on-launch** (#561) - Remote SSH profiles can now connect silently at startup after the local hook server is actually listening, so reverse tunnels target the real bound port even if Clawd had to drift away from 23333. Thanks to first-time contributor @undownding.
- **Settings UI cleanup** (#521, #539, #541) - Settings uses consistent inline SVG sidebar icons, reorganizes General by usage frequency, moves Claude hook management into Agents, spells out Chinese language labels, and folds Animation Map into Animation & Sound.
- **Context and tray menu cleanup** (#523) - The pet right-click and tray menus are grouped into clearer state/work/display/app sections, the dangerous auto-approval entry is renamed to Auto-approve all requests, and New Session is clarified as New Claude Session across supported languages.

### Bug Fixes And Hardening

- **Hook settings backups before injection** (#531) - Clawd now backs up `settings.json` before injecting hooks and keeps the backup set bounded by a rolling window. Thanks to first-time contributor @chrono-meta.
- **Codex JSONL approval heuristic removed** (#571) - JSONL fallback no longer guesses approval prompts from shell calls. It remains for state and metadata fallback events such as web search, compaction, aborted turns, and stuck local-turn rescue. Official `PermissionRequest` is the only approval path.
- **Codex Desktop approval inference fixed** (#543) - Codex Desktop sessions no longer synthesize passive approval notifications from JSONL activity. Thanks to first-time contributor @quantai1314.
- **CJK Stop payload byte-fit** (#567) - Long Chinese/Japanese/Korean completion text no longer overflows `/state` byte limits and drops the happy completion animation; hook payloads byte-fit `assistant_last_output` while preserving structural completion fields.
- **Completion happy fixes** (#548, #555, #567) - Short completions, background-only Claude stops, and busy Stop deliveries now reliably trigger the completion celebration instead of being swallowed by debounce, 413, or timeout edges.
- **Windows crash/startup recovery and keep-size DPI freeze** (#554, #560, #408) - Startup recovery, renderer crash recovery, display metrics debounce, and keep-size frozen work-area handling were hardened for Windows sleep/wake and DPI changes.
- **Low-power eye tracking after resume** (#557) - Low-power eye tracking rebuilds and reattaches after Windows resume/unlock, waits for renderer receipt, and accepts one late success after timeout. Thanks to @YOIMIYA66.
- **Cloudling and low-power sleep polish** (#526, #527) - Low-power idle mode reclaims hidden HUD resources, fixes a wake-poll start-timer leak, reduces sleep power, renames the scripted badge to fine motion, and adds Cloudling static sleep fallback assets.
- **Reasonix Windows compatibility** (#503) - Reasonix hook install now resolves the current config home and uses PowerShell `-EncodedCommand` when Windows paths need it, avoiding `cmd /c` quoting failures in the Go CLI. Encoded Clawd hook entries are also recognized during reinstall so repeated startup syncs update/dedupe stale hooks instead of appending duplicates. Thanks to @sLingli.
- **Telegram approval outcome status** (#466) - Telegram approval cards now show the final outcome for decisions made on Telegram or resolved elsewhere, with atomic claim handling to avoid racey rewrites. Thanks to @zxypro1 (Zone Tome).
- **Ghostty cross-Space focus** (#461) - macOS Ghostty focus now switches Spaces through a verified stepping-stone terminal instead of yanking windows to the current desktop, with follow-up latency reductions. Thanks to first-time contributor @serenNan.
- **Renderer SVG cache-busting** (#522) - Object-channel SVG loads now get the same cache-bust behavior as image-channel SVGs, so one-shot animations replay instead of sticking on their last frame.

### Upgrade Notes

- Release metadata is bumped to `0.11.0` in both `package.json` and `package-lock.json`.
- `prefs` migrates v11 -> v12 on first launch. The migration only backfills `showDock=true` for pre-v12 files missing the key, preserving existing macOS users' Dock behavior while fresh installs default to a pet/menu-bar accessory with no Dock tile.
- `tutorialSeen` is intentionally **not** migration-backfilled. Existing users who have never seen the onboarding tutorial will see it once after upgrading; Finish, Skip, or closing the window marks it seen permanently.
- Codex approval notifications now require official `PermissionRequest` hooks. If the Codex hook is disabled, not reviewed, missing, or broken, use **Settings -> Agents** or Doctor to repair/review it.
- The Windows fullscreen overlay pref defaults on and no longer has a Settings row. If a fullscreen app should hide the pet, use Hide Pet; DND remains the way to silence permission bubbles.
- Hook installers may create bounded backup copies of settings files before injecting Clawd-managed entries.

### Contributors

Huge thanks to everyone who shipped code, tests, docs, QA, or release polish for v0.11.0 - and welcome to this release's **seven first-time contributors**:

- **@rullerzhou-afk** (鹿鹿 · creator) - Onboarding, Settings cleanup, Codex hook health and JSONL approval-path cleanup, Windows fullscreen/startup/recovery hardening, CJK byte-fit, completion-happy fixes, Cloudling/low-power polish, release work, and follow-up reviews.
- **@zhaoxv210** - Free roam mode and review follow-ups (#467). *First-time contributor.*
- **@serenNan** - Ghostty cross-Space focus and latency improvements (#461). *First-time contributor.*
- **@IatomicreactorI** - Dizzy spin reaction and theme support gating (#507). *First-time contributor.*
- **@quantai1314** - Codex Desktop approval inference fix (#543). *First-time contributor.*
- **@Git-creat7** - Free-roam target-selection flake fix (#570). *First-time contributor.*
- **@undownding** - Remote SSH connect-on-launch (#561). *First-time contributor.*
- **@chrono-meta** - Bounded settings backup before hook injection (#531). *First-time contributor.*
- **@sLingli** - Reasonix Windows `cmd /c` / `EncodedCommand` compatibility and current config-home fix (#503).
- **@zxypro1** (Zone Tome) - Telegram approval outcome status and race hardening (#466).
- **@YOIMIYA66** - Windows resume / low-power eye-tracking recovery (#557).
- **@Bynlk** - Continued core ownership of the Mobile / PWA companion line.

### Known Limitations

- Codex terminal focus is still unavailable because official hooks and JSONL fallback do not carry a usable terminal PID.
- Codex JSONL fallback still has polling latency for hook-uncovered events such as web search, compaction, and aborted turns; approval prompts are not inferred from JSONL.
- Windows fullscreen overlay is best for borderless fullscreen. Exclusive fullscreen behavior is still platform/game dependent and must be smoke-tested on real hardware.
- macOS Ghostty cross-Space focus has unit coverage and contributor validation, but macOS real-machine release smoke should still verify the packaged artifact.
- macOS and Linux packaged auto-update remain manual-download only; git checkout users can still update through the git-mode updater.