Monster12138 · Oct 13, 2026 · Sep 18, 2026 · Sep 20, 2026 · Sep 29, 2026 · Oct 12, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -130,6 +130,36 @@ cover the change and report the unrelated failure clearly.
 - Prefer focused comments that explain platform constraints or non-obvious
   behavior; do not narrate straightforward code.
 
+## Desktop UI and Sprite Pack Workshop
+
+- Keep secondary windows visually consistent with the settings panel. Reuse its
+  neutral dark backgrounds, text, borders, blue action accent, control shapes,
+  and spacing; reserve a checkerboard for transparent image previews. When a
+  style token changes, update related windows together or share the token.
+- Put major features in the settings sidebar as clear, labeled entries. Small
+  actions inside a section may use simple icons with accessible names. Avoid
+  redundant instructional labels when the action is clear from context.
+- Keep user-facing forms focused on concepts users choose. Generate technical
+  identifiers internally, and do not require or display them unless users need
+  them to complete a task. Mark optional fields explicitly; validate only
+  fields and assets that the format actually requires.
+- In image editors, make selection and preview direct: selecting a state shows
+  that state's image, switching packs selects the first available image, and
+  previews preserve the source aspect ratio. Support both file picking and
+  dropping onto a specific state; highlight the drop target and report invalid
+  files at that state. For native Tauri drops, use the webview event and verify
+  platform coordinate units before mapping the drop point to a DOM element.
+- Keep editable user packs distinct from built-in packs. Copy built-in packs
+  before editing; allow deletion only for user packs. Save through the backend
+  with validation and recovery of the previous version, then refresh the pack
+  list and active pet through the existing update event. Export the saved
+  version, saving pending edits first.
+- Protect unsaved work on navigation and the system close button with an
+  in-window confirmation that does not block other app windows. Do not add a
+  second close control when the native window control already serves that
+  purpose. Use transient feedback for successes and errors, and provide both
+  Chinese and English text for every visible label and message.
+
 ## Agent Hooks Integration
 
 Rules for adding or updating hook integration for a coding agent (Claude Code,

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -9,7 +9,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "2.4.0"
+version = "3.0.1"
 edition = "2021"
 rust-version = "1.88"
 license = "MIT OR Apache-2.0"

diff --git a/README.md b/README.md
@@ -1,32 +1,49 @@
-# Familiar
+<p align="center">
+  <img src="app/src-tauri/icons/128x128.png" alt="Familiar" width="96" height="96">
+</p>
 
-> *A desktop pet that reacts to your world.*
+<h1 align="center">Familiar</h1>
 
-[简体中文](README_zh.md)
+<p align="center">A desktop pet that reacts to your world.</p>
+
+<p align="center">
+  <a href="https://github.com/Monster12138/familiar/releases"><img src="https://img.shields.io/github/v/release/Monster12138/familiar?style=flat&color=blue" alt="Latest release"></a>
+  <a href="https://github.com/Monster12138/familiar/actions/workflows/rust.yml"><img src="https://github.com/Monster12138/familiar/actions/workflows/rust.yml/badge.svg" alt="Rust CI"></a>
+  <a href="#license"><img src="https://img.shields.io/badge/license-MIT%20%2F%20Apache--2.0-blue" alt="License: MIT or Apache-2.0"></a>
+  <img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Windows%20%7C%20Linux-555" alt="Platforms: macOS, Windows, Linux">
+</p>
+
+<p align="center">
+  <a href="README_zh.md">简体中文</a> · <a href="README.md">English</a> · <a href="https://github.com/Monster12138/familiar/releases">Download</a> · <a href="#documentation">Documentation</a> · <a href="https://github.com/Monster12138/familiar/issues">Issues</a>
+</p>
 
 Familiar is a local-first desktop companion for coding agents. It turns Hook events into the actions, task bubbles, and status changes of a pixel-art desktop pet—without adding another dashboard to watch.
 
-## Features
+<details>
+<summary><strong>Contents</strong></summary>
 
-- **Reactive desktop pet** — Pixel-art actions follow agent activity without interrupting your flow.
-- **Agent integrations** — Connect Claude Code, Codex CLI, DeepSeek Harness, Qoder, and Google Antigravity through their Hook APIs.
-- **Remote connections** — Run the Agent and Familiar server remotely while the local desktop client subscribes to pet state.
-- **System dashboard** — Show CPU, memory, and disk usage beside the pet.
-- **Sprite packs** — Import more companions with the `.fpack` format.
-- **Lightweight** — Pause unnecessary polling while UI surfaces are hidden.
-- **Privacy-first** — Process events locally by default, with no telemetry and minimal operational logs.
+- [Why Familiar?](#why-familiar)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Features](#features)
+- [Supported integrations](#supported-integrations)
+- [Remote mode](#remote-mode)
+- [Privacy](#privacy)
+- [Build from source](#build-from-source)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
 
-## Supported integrations
+</details>
 
-| Integration | Transport | Status |
-| --- | --- | --- |
-| Claude Code | Hooks | Available |
-| Codex CLI | Hooks | Available |
-| DeepSeek Harness | Hooks | Available |
-| Qoder | Hooks | Available |
-| Google Antigravity | Hooks | Available |
+---
 
-Familiar only manages its own Hook entries. Installation creates a backup and preserves existing agent configuration.
+## Why Familiar?
+
+- **Multi-agent support**: Claude-code, ChatGpt, DeepSeek Harness... one desktop pet handles them all.
+- **One less window to watch**: Follow agent activity through pet actions and task bubbles.
+- **Fits your workflow**: Connect through agent Hook APIs while preserving existing configuration.
+- **Your data, your choice**: Run locally by default; configure remote connections when needed.
 
 ## Install
 
@@ -48,51 +65,74 @@ brew install Monster12138/familiar/familiar-cli
 
 Download the latest release from [GitHub Releases](https://github.com/Monster12138/familiar/releases).
 
-Current release targets:
-
-- macOS arm64 and x86_64
-- Windows x86_64
-- Linux x86_64 (`.deb` and AppImage)
+| Platform | Architecture | Installation |
+| --- | --- | --- |
+| macOS | arm64 / x86_64 | Homebrew Cask or release download |
+| Windows | x86_64 | Release download |
+| Linux | x86_64 | `.deb` / AppImage |
 
-macOS packages are not notarized with an Apple Developer ID, and Windows packages are not code-signed. Gatekeeper or SmartScreen may require manual approval on first launch.
+> [!NOTE]
+> macOS packages are not notarized with an Apple Developer ID, and Windows packages are not code-signed. Gatekeeper or SmartScreen may require manual approval on first launch.
 
-### First launch on macOS
+<details>
+<summary><strong>First launch on macOS: allow an unnotarized app</strong></summary>
 
 Because Familiar is not yet notarized, macOS blocks it the first time you open
 it. If you installed Familiar from this repository's Homebrew tap or GitHub
 Releases, allow it manually:
 
 1. Open Familiar. When macOS says it cannot verify the app, click **Done**.
 
-   <img src="docs/images/macos-gatekeeper/01-unverified-app.jpg" alt="macOS cannot verify Familiar" width="420">
+   <img src="docs/images/macos-gatekeeper/01-unverified-app.jpg" alt="macOS cannot verify Familiar" width="300">
 
 2. Open **System Settings → Privacy & Security**, scroll to **Security**, find
    the message that Familiar was blocked, and click **Open Anyway**.
 
-   <img src="docs/images/macos-gatekeeper/02-open-anyway-setting.jpg" alt="Open Anyway in macOS Privacy and Security settings" width="680">
+   <img src="docs/images/macos-gatekeeper/02-open-anyway-setting.jpg" alt="Open Anyway in macOS Privacy and Security settings" width="480">
 
 3. In the confirmation dialog, click **Open Anyway** again. Authenticate with
    your password or Touch ID if macOS asks. Familiar will open normally from
    then on.
 
-   <img src="docs/images/macos-gatekeeper/03-confirm-open.jpg" alt="Confirm opening Familiar on macOS" width="420">
+   <img src="docs/images/macos-gatekeeper/03-confirm-open.jpg" alt="Confirm opening Familiar on macOS" width="300">
 
 Only bypass this warning when you obtained Familiar from the official sources
 linked above.
 
-## Build from source
+</details>
 
-Requirements: Rust 1.88+, Node.js 18+, npm, and the desktop prerequisites for your platform.
+## Quick start
 
-```bash
-cargo test --workspace
-cargo clippy --workspace --all-targets -- -D warnings
+1. **Launch Familiar** and choose local mode in onboarding.
+2. **Connect an agent**: Preview and confirm Hook injection in onboarding or **Settings → Hooks**.
+3. **Start an agent task** and watch the pet actions and task bubbles respond to its activity.
+4. **Make it yours**: Choose visible content, click-through, or fullscreen auto-hide in **Settings → Display Configuration**, and switch companions in **Pet Materials**.
 
-cd app
-npm ci
-npm run build
-npm run tauri dev
-```
+> [!TIP]
+> For agents running on another machine, use [remote mode](#remote-mode) and manage Hooks on the server.
+
+## Features
+
+- **Reactive desktop pet** — Pixel-art actions follow agent activity without interrupting your flow.
+- **Agent integrations** — Connect Claude Code, Codex CLI, DeepSeek Harness, Qoder, and Google Antigravity through their Hook APIs.
+- **Remote connections** — Run the Agent and Familiar server remotely while the local desktop client subscribes to pet state.
+- **System dashboard** — Show CPU, memory, and disk usage beside the pet.
+- **Sprite packs** — Import more companions with the `.fpack` format.
+- **Lightweight** — Pause unnecessary polling while UI surfaces are hidden.
+- **Privacy-first** — Process events locally by default, with no telemetry and minimal operational logs.
+- **Fullscreen auto-hide** — Optionally hide the pet when the foreground app fills its screen on macOS / Windows, then restore it on exit. Off by default; unavailable on Linux.
+
+## Supported integrations
+
+| Integration | Transport | Status |
+| --- | --- | --- |
+| Claude Code | Hooks | Available |
+| Codex CLI | Hooks | Available |
+| DeepSeek Harness | Hooks | Available |
+| Qoder | Hooks | Available |
+| Google Antigravity | Hooks | Available |
+
+Familiar only manages its own Hook entries. Installation creates a backup and preserves existing agent configuration.
 
 ## Remote mode
 
@@ -108,6 +148,22 @@ Remote mode sends bounded render-state summaries to the configured Familiar serv
 
 See [Privacy & Data Handling](docs/PRIVACY.md) for details.
 
+## Build from source
+
+Requirements: Rust 1.88+, Node.js 18+, npm, and the desktop prerequisites for your platform.
+
+```bash
+# Build the CLI resource required by the desktop app
+cargo build --release -p familiar-cli
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+
+cd app
+npm ci
+npm run build
+npm run tauri dev
+```
+
 ## Documentation
 
 - [Privacy & Data Handling](docs/PRIVACY.md)