diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5be4657
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,75 @@
+# gigit
+
+A desktop git GUI client. Tauri 2 + Solid, with a colourful commit graph whose layout is
+computed in Rust and streamed to the frontend.
+
+## Stack
+
+| Layer | Choice |
+|---|---|
+| Shell | Tauri 2 |
+| Frontend | Solid 2 (beta), TypeScript 7, Vite |
+| Styling | Tailwind CSS v4 (CSS-first config) + `@claas.dev/material-tailwind` |
+| Lint / format | Oxc — `oxlint` and `oxfmt`. **Not** ESLint or Prettier. |
+| Git access | `gix` (gitoxide), reads only for now |
+| Async | tokio |
+
+`crates/gigit-git` holds git access and the graph layout engine and knows nothing about
+Tauri, so it can be tested and benchmarked with plain `cargo test`. `src-tauri` holds the
+actors, commands and channels.
+
+## Architecture rules
+
+- **Logic goes in Rust.** The frontend renders and handles input; it does not compute.
+- **Actors, not mutexes.** Shared state gets an owning actor (handle + `tokio::sync::mpsc`
+  + `oneshot`, per <https://ryhl.io/blog/actors-with-tokio/>). No `Mutex`/`RwLock` without a
+  stated reason the actor pattern doesn't fit. A `gix::Repository` is blocking and
+  thread-affine, so its actor runs on a dedicated `std::thread` draining its receiver with
+  `blocking_recv()`.
+- **Stream anything large.** List-shaped data crosses IPC as pull-based chunks over
+  `tauri::ipc::Channel`, driven by the frontend asking for more — never one big response.
+- **Rule of least power** (<https://www.w3.org/2001/tag/doc/leastPower.html>): semantic HTML
+  first, then CSS, then JavaScript. A CSS solution beats a JS one.
+- **Accessibility is a requirement.** Keyboard operability and correct AT semantics are part
+  of the work, not a follow-up. Decorative graphics are `aria-hidden` over content that
+  already reads correctly without them.
+
+## Browser support policy
+
+The only targets are Tauri's webviews: WKWebView (Safari) on macOS, WebView2 (Chromium) on
+Windows, WebKitGTK on Linux. Baseline Newly available features are fine where they degrade
+gracefully. No polyfills. Hand-written fallbacks only when under ~20 lines and dependency-free.
+
+Use the `modern-web-guidance` skill before starting frontend work.
+
+## Dependencies
+
+**Ask before adding any npm or cargo dependency**, and list notable transitive ones. Prefer a
+platform feature over a library.
+
+## Licence and attribution
+
+gigit is MIT. Adapted or copied code must carry attribution including its licence, in
+`NOTICE.md`.
+
+Specifically: the commit graph is implemented from the algorithm *described* in
+<https://pvigier.github.io/2019/05/06/commit-graph-drawing-algorithms.html>. Its reference
+implementation, [gitamine](https://github.com/pvigier/gitamine), is **GPL-3.0** — do not read
+or port its source.
+
+## Commands
+
+```
+pnpm tauri dev        # run the app
+pnpm typecheck        # tsc --noEmit
+pnpm lint             # oxlint
+pnpm format           # oxfmt .
+pnpm format:check     # oxfmt --check .
+cargo test --workspace
+cargo clippy --workspace
+```
+
+## Workflow
+
+Work ships as stacked PRs using the `gh-stack` skill — small, reviewable layers where
+foundational changes sit below dependent ones.