diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index 3923e85..0000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- Root scripts: smart_cors_middleware.py (Flask CORS add-on), export_risk_json.py (PostgreSQL export).
-- Data/outputs: risk_tables_export.json (generated by export script).
-- Docs: PRD.md.
-- Python 3.10+ is required (uses PEP 604 unions like str | None).
-
-## Build, Test, and Development Commands
-- Create venv (Windows):
-  ~~~powershell
-  python -m venv .venv; .venv\Scripts\activate; pip install Flask pg8000 black ruff pytest
-  ~~~
-- Run DB export (writes risk_tables_export.json):
-  ~~~bash
-  python export_risk_json.py
-  ~~~
-- Verify CORS middleware in your Flask app (diagnosis endpoint):
-  ~~~bash
-  curl -i http://localhost:5000/api/cors-diagnosis
-  ~~~
-- Lint/format (optional tools): ruff .  and  black .
-- Tests (when added): pytest -q
-
-## Coding Style & Naming Conventions
-- Python: 4-space indents, UTF-8 files, snake_case for functions/vars, SCREAMING_SNAKE_CASE for constants.
-- Prefer type hints; keep functions small and side-effect free.
-- Formatting: black (line length 100). Linting: ruff (default rules).
-- Filenames: modules like smart_cors_middleware.py; tests as test_*.py under tests/.
-
-## Testing Guidelines
-- Framework: pytest with Flask test client for middleware behavior.
-- Target cases: origin matching (wildcard, exact, subdomains), preflight handling, X-CORS-Decision header, NGINX_CORS_MODE behavior.
-- Coverage: prioritize core branches in _origin_matches, preflight (OPTIONS), and after_request logic.
-
-## Commit & Pull Request Guidelines
-- No Git history found here; use Conventional Commits (e.g., feat: add CORS diagnosis endpoint).
-- PRs should include: purpose, concise summary, screenshots or curl examples for HTTP changes, and any config/env notes.
-- Link related issues; keep PRs focused and under ~300 changed lines when possible.
-
-## Security & Configuration Tips
-- Do NOT hardcode secrets. Move DB credentials in export_risk_json.py to env vars and load via os.getenv() or a .env file.
-- CORS env vars supported by middleware: ALLOWED_ORIGINS, CORS_STRICT, CORS_DEBUG, NGINX_CORS_MODE, CORS_MAX_AGE, CORS_EXPOSE_HEADERS.
-- Validate inputs from the DB export; avoid writing outside the repo.
diff --git a/CLAUDE.md b/docs/CLAUDE.md
similarity index 100%
rename from CLAUDE.md
rename to docs/CLAUDE.md