docs: add CLAUDE.md for development guidance and architecture overview

- Introduced a comprehensive guide for developers working with the Claude Code repository.
- Included sections on development commands for both frontend and backend, big-picture architecture, window and state models, and persistence details.
- Provided project-specific guidance on UI patterns, testing, and documentation structure.

CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development commands
+
+### Root app
+- `pnpm install` — install JS dependencies
+- `pnpm dev` — run the Vite frontend only
+- `pnpm tauri dev` — run the full desktop app in Tauri dev mode
+- `pnpm build` — run `tsc` and build the frontend with Vite
+- `pnpm tauri build` — build the production desktop bundle
+- `pnpm lint` — run Biome checks for `src/**/*.ts` and `src/**/*.tsx`
+- `pnpm format` — apply Biome formatting to `src/**/*.ts` and `src/**/*.tsx`
+- `pnpm format:check` — check Biome formatting without writing changes
+- `pnpm i18n:check` — check locale JSON formatting
+- `pnpm i18n:fix` — rewrite locale JSON formatting
+- `pnpm version-sync` — sync version numbers across app files
+- `pnpm release` — version sync + frontend build + Tauri build
+
+### Rust / Tauri backend
+- `cargo fmt --manifest-path src-tauri/Cargo.toml` — format Rust code
+- `cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets` — lint Rust code
+- `cargo test --manifest-path src-tauri/Cargo.toml` — run backend Rust tests
+- `cargo test --manifest-path src-tauri/Cargo.toml <test_name>` — run a single backend Rust test
+- `cargo test --manifest-path src-tauri/crates/otp/Cargo.toml` — run OTP crate tests
+- `cargo test --manifest-path src-tauri/crates/otp/Cargo.toml <test_name>` — run a single OTP crate test
+
+Example single-test command:
+- `cargo test --manifest-path src-tauri/Cargo.toml normalizes_trailing_slashes_without_breaking_roots`
+
+### Docs site
+- `pnpm --dir docs-site start` — run the Docusaurus docs site locally
+- `pnpm --dir docs-site build` — build the docs site
+
+## Big-picture architecture
+
+- This is a Tauri 2 desktop app: React/TypeScript frontend in `src/`, Rust backend in `src-tauri/src/`, and IPC between them via Tauri commands/events.
+- The frontend should call Rust through the typed wrapper in `src/lib/invoke.ts`, not raw scattered `invoke()` calls where a shared wrapper already exists.
+- Tauri commands are registered centrally in `src-tauri/src/lib.rs` and grouped by concern under `src-tauri/src/cmd/` (`session`, `sftp`, `connection`, `settings`, `watcher`, `translate`, `stats`, `tunnel`, `proxy`, `otp`, `importer`).
+
+### Window model
+- `src/main.tsx` decides between two boot paths:
+  - main window: `AppProvider` + `App.tsx`
+  - child windows: `ChildAppProvider` + `ChildWindowRouter`
+- Child windows are opened from `src/lib/windowManager.ts` using `?window=` query params. Current child-window flows include settings, new-session, quick-command, and per-file auto-upload dialogs.
+- Modal child-window focus/enable state is managed in `windowManager.ts` plus `src/ChildWindowRouter.tsx`; changes here affect cross-window UX.
+
+### Frontend state model
+- `src/context/AppContext.tsx` is the main state container. It owns:
+  - tab/session workspace state
+  - persisted UI/app settings
+  - saved connections/groups loading and refresh
+  - startup session restoration from persisted `ui.open_tabs`
+- `src/context/ChildAppProvider.tsx` is a lightweight provider for child windows. It only loads/saves settings and emits cross-window events; it does not manage the full tab/session workspace.
+- `src/context/TransferContext.tsx` separately tracks file transfer progress from backend `transfer-event` notifications.
+
+### Workspace / terminal model
+- The terminal workspace has two distinct layers that are easy to confuse:
+  - `src/lib/workspaceTabs.ts` manages the persistent logical tab model. Each tab owns a recursive pane tree (`leaf` session panes and `split` panes). This is what gets serialized into `ui.open_tabs` for startup restore.
+  - `src/lib/tabWindows.ts` manages the runtime terminal window layout: which tabs live in each split window leaf, active tab per leaf, and window split ratios for the multi-tab/multi-split UI.
+- `src/App.tsx` is the shell that composes activity bars, left/right panels, the terminal workspace, quick command / serial send bottom panels, OTP dialogs, transfer UI, recording, and lock screen.
+- `src/components/terminal/XTerminal.tsx` is the xterm.js integration point. It wires Fit/Search/WebLinks addons, shell integration, command suggestions, reconnect hooks, and listens to per-session backend events.
+
+### Backend runtime model
+- `src-tauri/src/lib.rs` constructs and stores the shared backend managers in Tauri state:
+  - `SessionManager`
+  - `TunnelManager`
+  - `RecordingManager`
+  - `PendingAuthManager`
+- `src-tauri/src/core/session.rs` contains `SessionManager`, which is the central registry for active sessions, command routing, command history, fuzzy history search, and session lifecycle events.
+- Session implementations live under `src-tauri/src/core/`:
+  - `ssh/` for SSH transport, auth, OSC/CWD tracking, tunnels, and SFTP
+  - `pty.rs` for local terminal sessions
+  - `telnet.rs` for Telnet sessions
+  - `serial.rs` for serial sessions
+  - `recording.rs` for terminal recording
+  - `watcher.rs` for file-watch driven flows
+- Backend session I/O is event-driven. The Rust side emits session-specific and app-wide events such as `terminal-output-{id}`, `cwd-changed-{id}`, `session-closed-{id}`, `sessions-changed`, `connections-changed`, `command-history-changed`, `transfer-event`, and `otp-request`.
+
+### SSH / auth / transfer details
+- SSH logic is split across `src-tauri/src/core/ssh/`:
+  - `client.rs` handles russh client setup, keepalive config, proxy-aware connection setup, and TOFU-style `known_hosts` verification stored under `~/.dragonfly/known_hosts`
+  - `auth.rs` handles saved auth loading plus keyboard-interactive / OTP flows through `PendingAuthManager` and the `otp-request` event
+  - `io.rs` streams terminal output and emits CWD updates
+  - `sftp.rs` implements remote file operations and emits transfer progress events consumed by `TransferContext`
+- SFTP commands exposed to the frontend are in `src-tauri/src/cmd/sftp.rs`; the file explorer and transfer UI sit on top of these commands and events.
+
+### Persistence model
+- App data is stored under `~/.dragonfly/` through `src-tauri/src/config/`.
+- Important persisted files include:
+  - `settings.json`
+  - `sessions.json`
+  - `keys.json`
+  - `passwords.json`
+  - `otp.json`
+  - `quick-command.json`
+  - `tunnels.json`
+  - `proxies.json`
+  - `history.json`
+  - `known_hosts`
+- Sensitive values in keys/passwords/OTP storage are encrypted before being written.
+- When changing settings or workspace persistence, update both the frontend defaults (`AppContext` / `ChildAppProvider`) and the Rust persistence/migration code (`src-tauri/src/config/settings/mod.rs` and `src-tauri/src/config/ui.rs`).
+
+## Project-specific guidance
+
+- If a task touches UI, prefer shadcn/ui patterns and components. The repo has an explicit Cursor rule for this in `.cursor/rules/ui.mdc`.
+- shadcn is configured in `components.json`, and shared UI components live in `src/components/ui/`.
+- When changing user-facing UI text, update both locale files:
+  - `src/i18n/locales/en.json`
+  - `src/i18n/locales/zh-CN.json`
+- The root app currently has no dedicated frontend unit test runner configured in `package.json`; the automated tests in this repo are Rust tests under `src-tauri/` and `src-tauri/crates/otp/`.
+- Vite uses the `@` alias for `src/`.
+- Tauri dev/build behavior is configured in `src-tauri/tauri.conf.json`; the dev server runs on port `1420` with HMR on `1421`.
+- There is a separate Docusaurus docs app in `docs-site/`. The most useful repo docs for implementation context are in `docs-site/docs/development/` (`architecture.md`, `frontend.md`, `backend.md`, `setup.md`, `contributing.md`).
+- Repo docs and recent history use Conventional Commits (`feat:`, `fix:`, `perf:`, `chore:`).