diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..59c4dd4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,35 @@
+# AGENTS.md
+
+Pygienium is a `pi` extension: code-hygiene checks that scan a target with isolated sub-agent sessions (analysis), optionally apply fixes, then verify artifacts. Sub-agents are defined as markdown in `agents/*.md` (YAML frontmatter: `name`, `allowedTools`; body = system prompt).
+
+## Commands
+
+- `bun run typecheck` — `tsc --noEmit` on `src/`
+- `bun test` — full suite (bun test)
+
+## Layout
+
+- `src/checks/` — check definitions; self-register on import (`registerCheck`)
+- `src/agent-runner.ts` — spawns sub-agent sessions; runner injectable (`setAgentRunner`), tests use `fakeAgentRunner` (no real model calls)
+- `src/commands.ts` — slash-command handlers, exported for direct test invocation with a stub `PygieniumCtx`
+- `tests/` — bun tests; stub ctx with `{ cwd, mode: "print", hasUI: false, ui: undefined } as PygieniumCtx`
+- `port-to-omp.mjs` — regenerates the self-contained omp port (see commit process)
+
+## Conventions
+
+- Checks: `gate` (skip reason), `buildScanTask`, optional `buildFixTask`, optional `verify`. Scan tasks embed `!write`/`!echo` lines as deterministic fallback for the fake runner.
+- Sub-agent sessions must be pinned to the invoking session's model: thread `ctx.model` through `PygieniumCtx` → run options → `AgentTaskOptions.model` → `createAgentSession({ model })`.
+- Keep files modular; no compatibility shims.
+
+## Commit process (IMPORTANT)
+
+Commits are gated by the pre-commit hook (enable: `git config core.hooksPath .githooks`). It regenerates the omp port into a temp dir and typechecks it — exactly what CI runs. A failing hook blocks the commit; never bypass with `--no-verify`.
+
+`port-to-omp.mjs` rewrites source via exact-string matchers (`FILE_RULES`). Editing these files **requires** keeping the matching ops in sync or the port regeneration throws and the commit is blocked:
+
+- `src/index.ts` — removes `mode: ctx.mode` from the `pygieniumCtx` literal
+- `src/commands.ts` — removes `mode` from the `PygieniumCtx` Pick; swaps `ctx.mode` for `ctx.hasUI` in `print`
+- `src/agent-runner.ts` — swaps the SDK import + loader for the omp SDK's `createAgentSession` options (`toolNames`, `systemPrompt`, `agentRegistry`, …)
+- `src/agents.ts` — `find` → `glob`
+
+After touching any of those, run `bun port-to-omp.mjs --out <tmp>` and `(cd <tmp> && bun run typecheck)` before committing; the hook does the same.