diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f0f2174
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,22 @@
+# AGENTS.md
+
+Review the `README.md` and `CONTRIBUTING.md` for all relevant repository information.
+
+## Development Tips
+- Use `npm install` to install dependencies
+- Use `npm run build` to build the project files
+- Do not edit files in `dist/`; it is compiled output and gitignored.
+- Do not run `npm version` or `npm publish`; these commands are for humans only.
+- The `.cts` extension is intentional and load-order-sensitive. Do not change file extensions in `src/`.
+
+## Code Style
+- Use Prettier for formatting: `npm run format:fix`
+- `src/plugin.ts` is ESM. `src/withHarper.cts` and `src/CacheHandler.cts` are CommonJS (required by Next.js config resolution). Keep them that way.
+
+## Testing Tips
+- Use `npm link` in this directory and `npm link @harperfast/nextjs` in other project directories to test out changes locally
+- Run `npm run install:fixtures` before running tests for the first time, and again after changing any fixture's `package.json`.
+- Run `npm run test:integration` to run all tests, or `npm run test:integration -- integrationTests/next-15.pw.ts` for a single file.
+- Test startup is slow by design — each test file starts a real Harper instance and waits for Next.js to build (up to 2 minutes). A slow start is not a failure.
+- The ISR cache tests in `integrationTests/next-16.pw.ts` are intentionally skipped; `CacheHandler.cts` is a work in progress.
+- CI is currently disabled (`if: false` in `.github/workflows/integration-tests.yml`). Run tests locally.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 68d3158..330af79 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,9 +10,7 @@ The key source files are:
 - `schema.graphql` — the plugin table schemas
 - `config.yaml` — Harper configuration for the plugin
 
-The `.cts` extension marks files as CommonJS, which is required because Next.js config files (`next.config.js`, `next.config.mjs`, `next.config.ts`) all use CommonJS module resolution. `plugin.ts` stays as ESM since it is only loaded by Harper's own runtime.
-
-Run `npm run build` to compile `src/withHarper.cts` and `src/CacheHandler.cts` to `dist/cjs/`. The `src/plugin.ts` file is not compiled — Harper loads it directly using Node's type-stripping support.
+Run `npm run build` to compile the `src/` directory. The `.cts` extension marks files as CommonJS, which is required because Next.js config files (`next.config.js`, `next.config.mjs`, `next.config.ts`) all use CommonJS module resolution. `plugin.ts` stays as ESM since it is only loaded by Harper's own runtime.
 
 The published module includes `dist/`, `config.yaml`, and `schema.graphql`.