diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..393053a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,40 @@
+# Working agreements for miniSCP
+
+## Orientation
+
+`docs/` is the source of truth — read the relevant file before touching adjacent code:
+[architecture.md](docs/architecture.md) (process/window model, bun modules, UI services, theming),
+[gotchas.md](docs/gotchas.md) (landmines already hit — read before changing nearby code),
+[build-and-release.md](docs/build-and-release.md), [platform-notes.md](docs/platform-notes.md).
+
+## Planning
+
+In plan mode, use `AskUserQuestion` to resolve **every** ambiguity before finalizing a
+plan. Never guess at intent or silently pick behavior the user didn't specify — keep asking
+until the approach is unambiguous, then exit planning.
+
+## After an approved plan is executed
+
+1. **Verify first** — backend: `bun run ./node_modules/typescript/bin/tsc --noEmit -p tsconfig.json`;
+   UI: `bun run build:ui`; plus any smoke test that fits the change. (`bun run build:ui` is the
+   full AOT type-check for Angular — trust it over IDE squiggles.)
+2. **Then commit + push automatically, no need to ask** — a descriptive message ending with:
+
+   ```
+   Co-Authored-By: Claude <noreply@anthropic.com>
+   ```
+
+   Push to the current branch (this repo works directly on `main`).
+3. If verification fails, fix it or report back — do **not** commit broken work.
+
+## Keep the live documentation current
+
+`docs/` is living, not a one-time write. When a change alters the architecture/process model,
+a module's or service's responsibility, the RPC surface, theming, or introduces a new landmine,
+update the matching doc **in the same change, before the auto-commit**:
+
+- `docs/architecture.md` — structure, bun modules, UI services, theming.
+- `docs/gotchas.md` — anything that caused a real bug or debugging spiral.
+- `docs/build-and-release.md` / `docs/platform-notes.md` — when build or platform behavior changes.
+
+Match the existing dense, bulleted house style.