diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b2a2dab
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,16 @@
+# Working agreement — solid-layouts
+
+The operating contract for **any** coding agent working in this repository. Codex, Cursor
+and Gemini CLI read `AGENTS.md` natively; Claude Code loads it through the `@AGENTS.md`
+import in [`CLAUDE.md`](CLAUDE.md). Never fork these rules into a per-vendor file.
+
+**JavaScript/TypeScript** monorepo (`packages/`, `Test-UI/`).
+
+## Invariants (do not break these)
+
+- **No Python.** Not a script, not `python3 -c`, not a heredoc. Reaching for it is the
+  tell that a step is being solved by parsing when the tool that owns the answer could
+  just be asked. Do not swap it for another parser either, and do not assume `jq` is
+  present: it does not ship with macOS. A fixed-shape field is one `sed -nE` line;
+  anything needing real parsing belongs in TypeScript, where it can be tested. If a task seems
+  to need Python, the approach is wrong.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6190b41
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,7 @@
+@AGENTS.md
+
+# Claude Code notes — solid-layouts
+
+The import above is binding: [`AGENTS.md`](AGENTS.md) is the working agreement for this
+repository, and every Claude Code session loads it automatically. Do not copy rules here,
+one source of truth, no drift. Only genuinely Claude-specific wiring belongs below.