diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b5978b0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,37 @@
+# AGENTS.md — NullClaw Chat UI Engineering Protocol
+
+Default working protocol for coding agents in this repository. Scope: entire repository.
+
+## 1) Project Snapshot
+
+The chat surface for NullClaw: a SvelteKit app served two ways — as a web app
+(vite dev/build) and as a dynamically-mounted UI module (`npm run build:module`
+→ `module.js`, consumed by NullHub's module loader). TypeScript + Svelte 5.
+
+Transport contract: WebSocket to the NullClaw gateway's `channels.web` endpoint
+(default `ws://127.0.0.1:32123/ws`), end-to-end encryption (X25519 + ChaCha20-Poly1305),
+PIN/token pairing. The protocol lives in `src/lib/protocol/` and the session
+controller in `src/lib/session/` — treat these as the compatibility surface.
+
+## 2) Engineering Principles
+
+- The gateway wire protocol is a compatibility contract: changes must be
+  backward-compatible or explicitly versioned, and tested against a running
+  `nullclaw gateway`.
+- No secrets in the repo. Keep tokens and keys out of logs; persisted browser
+  auth must respect its TTL and be cleared on rejection.
+- Deterministic tests: `npm test` (vitest) must pass; no network in unit tests.
+
+## 3) Validation
+
+```bash
+npm install          # node 20+, npm 10+
+npm test             # vitest — required before every commit
+npm run check        # svelte-check — required before every commit
+npm run build        # app build must succeed
+npm run build:module # module.js must build (NullHub consumption)
+```
+
+## 4) Contribution flow
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..61187bc
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,9 @@
+# Contributing to NullClaw Chat UI
+
+1. **Read [AGENTS.md](AGENTS.md)** first — the gateway wire protocol is a
+   compatibility contract and the validation gates live there.
+2. One concern per PR. No drive-by refactors.
+3. Before every commit: `npm test`, `npm run check`, `npm run build`,
+   `npm run build:module` — all must pass.
+4. Every PR runs CI. Keep it green.
+5. Bug fixes must include a regression test citing the issue number.