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.
diff --git a/src/index.ts b/src/index.ts
index fcd6602..6977bf0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -26,9 +26,7 @@ import { homedir } from "node:os";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
-	ExtensionContext,
 	MessageRenderer,
-	SessionStartEvent,
 } from "@oh-my-pi/pi-coding-agent";
 import { Box, Text } from "@oh-my-pi/pi-tui";
 import "./checks/all.js";
@@ -40,10 +38,6 @@ import {
 } from "./phases.js";
 import type { AgentSessionEvent } from "@oh-my-pi/pi-coding-agent";
 
-/** Startup hint mirrored after piolium's convention. */
-export const PYGIENIUM_STARTUP_HINT =
-	"Pygienium loaded. Run /pygienium-help for available checks and flags.";
-
 /** Custom message type for the live tool-event stream (mirrors piolium-stream). */
 export const PYGIENIUM_STREAM = "pygienium-stream";
 
@@ -418,12 +412,4 @@ export default async function pygieniumExtension(
 			},
 		});
 	});
-
-	pi.on(
-		"session_start",
-		async (_event: SessionStartEvent, ctx: ExtensionContext) => {
-			if (!ctx.hasUI) return;
-			ctx.ui.notify(PYGIENIUM_STARTUP_HINT, "info");
-		},
-	);
 }