diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e33a6c8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,28 @@
+# capsite working rules
+
+Applies to AI agents working in `capsite/` (goal tree + how-to-run:
+[capsite-checklist.md](capsite-checklist.md); background:
+[the capsite notes](capsite-notes.md); workspace-wide policy:
+[AGENTS.md](../AGENTS.md) — commit trailers live there).
+
+## Dev servers are the user's job
+
+The assistant never starts, stops, or restarts long-running dev servers
+(`wrangler dev`, `pnpm dev`/`astro dev`). The user runs them and owns the
+terminals; the assistant observes via `.tmp/capsite.script` (the `script`
+capture; use `watchme`). One-shot codegen (`wrangler types`), linters,
+typechecks, and tests are fine.
+
+## Secrets discipline
+
+Worker secrets never in source or wrangler config. `.dev.vars` (gitignored)
+locally; `wrangler secret put` deployed. As of the DO split, the cookie
+lives only in the webapp DO's storage; `DIIGO_WEB_ID` is the one
+diigo-dump secret. Error messages must not contain header or param values
+(they cross RPC as exceptions and land in logs); URLs appear query-stripped.
+
+## Keep config types generated
+
+Run `wrangler types` after any wrangler.jsonc change
+(`worker-configuration.d.ts` is generated, gitignored; hand-rolled
+`cloudflare:workers` shims drift and gave red squiggles).
\ No newline at end of file
diff --git a/capsite-checklist.md b/capsite-checklist.md
index 498e056..7ba9138 100644
--- a/capsite-checklist.md
+++ b/capsite-checklist.md
@@ -99,18 +99,11 @@ madmode (EmDash site; separate worker, separate concerns):
     # admin at /_emdash/admin; dev-bypass auth helper:
     # /_emdash/api/setup/dev-bypass?redirect=/_emdash/admin
 
-## Hard rules (learned 2026-10-06/07; keep them)
+## Working rules
 
-- The ASSISTANT never runs wrangler/astro dev servers; the user does
-  (assistant watches work happen via .tmp/capsite.script; one-shot
-  codegen like `wrangler types` is fine).
-- Worker secrets never in source/config; `.dev.vars` (gitignored) locally,
-  `wrangler secret put` deployed. Since the DO split, only DIIGO_WEB_ID
-  is a diigo-dump secret at all.
-- Error messages must not contain header or param values (they cross RPC
-  as exceptions and land in logs); URLs appear query-stripped.
-- `wrangler types` after any wrangler.jsonc change (generated
-  worker-configuration.d.ts is gitignored).
+Agent working rules are in [AGENTS.md](AGENTS.md) — dev servers are the
+user's job; secrets discipline; keep config types generated. They apply
+to every goal in this tree.
 
 ## Pointers