diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e5cc0fc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,30 @@
+# petrolyst-infra: agent rules
+
+Deployment of the petrolyst server (atoma.petrolyst.com) and the Superset customization.
+Runbook: README.md. Workspace rules: `../AGENTS.md`; shared context: `../.context/` (server and
+identity facts: `deployment.md`).
+
+## Layout
+- `stacks/`, `traefik/`, `deploy/`, `host/`: how and where things run.
+- `petrolyst-insights/`: what Superset looks like and does (config, security manager, the guest
+  role, branding, patches, dashboards as code). Its README maps each file to the image.
+- `keycloak/`: the `petrolyst` client import.
+
+## Rules
+- **Deploys:** only by README "Manual deploy", only when the owner asks. There is no CI. Commit on
+  `main` first; never push or deploy unprompted.
+- **No secrets** in the repository; `deploy/deploy.sh` refuses if one appears.
+- **The Superset image's inputs** (`SUPERSET_INPUTS` in `deploy/lib.sh`) make its tag: a change
+  there rebuilds Superset on the next deploy.
+- **Dashboards are code:** change `build_bundle.py` and SPEC.md, never the UI followed by an
+  export. `import_bundle.py` never deletes; old objects go by hand (`dashboards/README.md`).
+- **Embedding** stays off in production (`superset_config.py`) until PD-12's points are decided;
+  the local stack turns it on in its own override.
+- **ATOMA's users** have no Superset role (PD-13): `atoma-reader` opens the Petrolyst app only.
+- fuel-db migrations (`stacks/fuel-monitoring/fuel-db/migrations/`) are applied by hand (P3).
+
+## Checks
+- Shell: the README's Docker shellcheck command (warnings and errors must be zero).
+- Dashboards: `build_bundle.py` checks the bundle as it builds; import locally and expect column
+  drift 0 (`../.context/local-stack.md`).
+- Superset changes: rebuild the local image and check it turns healthy before calling it done.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md