diff --git a/flash/cli/init.mdx b/flash/cli/init.mdx
index f5085402b..fee00858f 100644
--- a/flash/cli/init.mdx
+++ b/flash/cli/init.mdx
@@ -52,6 +52,8 @@ The command creates the following project structure:
     <Tree.File name="pyproject.toml" />
     <Tree.File name="requirements.txt" />
     <Tree.File name="README.md" />
+    <Tree.File name="AGENTS.md" />
+    <Tree.File name="CLAUDE.md" />
   </Tree.Folder>
 </Tree>
 
@@ -62,6 +64,40 @@ The command creates the following project structure:
 - **cpu_worker.py**: CPU queue-based endpoint. Contains an `@Endpoint` function that runs on CPU-only instances. Provides `/run` or `/runsync` routes for job submission. Creates one Serverless endpoint when deployed.
 - **.env**: Template for environment variables including `RUNPOD_API_KEY`.
 
+### AI coding agent files
+
+Flash generates context files that help AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, Aider, and others) use Flash correctly. These files tell agents to use Flash CLI commands instead of raw Runpod API calls.
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | CLI-first rules for AI coding tools (Cursor, Codex, Aider, Amp, Jules, and others) |
+| `CLAUDE.md` | Symlink to `AGENTS.md` so Claude Code picks up the same rules |
+
+Flash writes these files only when they don't already exist. If you have your own `AGENTS.md` or `CLAUDE.md`, Flash leaves them alone.
+
+<Tip>
+
+**Tools using other conventions:** GitHub Copilot reads `.github/copilot-instructions.md` and Cursor (legacy) reads `.cursorrules`. If you use those, symlink or copy `AGENTS.md`:
+
+```bash
+ln -s ../AGENTS.md .github/copilot-instructions.md
+ln -s AGENTS.md .cursorrules
+```
+
+</Tip>
+
+### Add agent files to existing projects
+
+If you've already run `flash init`, add the agent files with:
+
+```bash
+python -c "from runpod_flash.rules import install_agent_files; from pathlib import Path; install_agent_files(Path.cwd())"
+```
+
+### Opt out
+
+Delete `AGENTS.md`. Flash won't re-create it.
+
 ## Next steps
 
 After initialization:
diff --git a/flash/quickstart.mdx b/flash/quickstart.mdx
index 104266214..12a193395 100644
--- a/flash/quickstart.mdx
+++ b/flash/quickstart.mdx
@@ -27,6 +27,12 @@ source .venv/bin/activate
 uv pip install runpod-flash
 ```
 
+<Tip>
+
+When you create a project with `flash init`, Flash generates `AGENTS.md` (and `CLAUDE.md` as a symlink) with CLI-first rules for AI coding assistants. These files tell AI tools like Claude Code, Cursor, and Codex to use Flash commands instead of raw Runpod API calls. See [`flash init`](/flash/cli/init) for details.
+
+</Tip>
+
 ### Optional: Install coding agent integration
 
 If you're using an AI coding agent like Claude Code, Cline, or Cursor, you can install the Flash skill package to give your agent detailed context about the Flash SDK: