diff --git a/AGENTS.md b/AGENTS.md
index 61c5f56..e851393 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,3 +24,36 @@ Before creating ANY pull request, verify:
 - ✅ NOT targeting: `rlabbe/filterpy` (FORBIDDEN)
 - ✅ Base branch is set correctly for this fork
 - ✅ You are NOT attempting to contribute upstream
+
+## 📝 Agent Documentation Guidelines
+
+### Where to Write Documentation
+
+When agents need to create documentation files (design docs, analysis reports, guides, etc.), they should **write to the `scratch_files/` directory** instead of the repository root.
+
+**Example:**
+- ❌ DON'T: Create `MY_ANALYSIS.md` in root
+- ✅ DO: Create `scratch_files/MY_ANALYSIS.md`
+
+### Why?
+
+The repository root should contain only essential documentation files:
+- `README.md` - Project overview
+- `AGENTS.md` - Agent guidelines (this file)
+- Other critical docs
+
+The `scratch_files/` directory is where agents can freely write:
+- Analysis and investigation reports
+- Design documents
+- Planning notes
+- Implementation guides
+- Troubleshooting docs
+- Architecture diagrams
+- Any other supporting documentation
+
+### File Naming
+
+Agent-generated documentation in `scratch_files/` can use any naming convention:
+- Capitalized markdown files are fine (e.g., `ANALYSIS.md`, `DESIGN.md`)
+- Descriptive names are encouraged
+- Dates/timestamps are helpful (e.g., `2025-10-25_investigation.md`)
diff --git a/scratch_files/.gitkeep b/scratch_files/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/PUBLISHING.md b/scratch_files/PUBLISHING.md
similarity index 100%
rename from PUBLISHING.md
rename to scratch_files/PUBLISHING.md
diff --git a/PYPI_SETUP.md b/scratch_files/PYPI_SETUP.md
similarity index 100%
rename from PYPI_SETUP.md
rename to scratch_files/PYPI_SETUP.md
diff --git a/TESTING.md b/scratch_files/TESTING.md
similarity index 100%
rename from TESTING.md
rename to scratch_files/TESTING.md
diff --git a/TESTING_PLAN.md b/scratch_files/TESTING_PLAN.md
similarity index 100%
rename from TESTING_PLAN.md
rename to scratch_files/TESTING_PLAN.md
diff --git a/TYPE_ANNOTATIONS.md b/scratch_files/TYPE_ANNOTATIONS.md
similarity index 100%
rename from TYPE_ANNOTATIONS.md
rename to scratch_files/TYPE_ANNOTATIONS.md