diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 58e2250..fe34d0e 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -14,4 +14,4 @@
 
 - [ ] `ruff check src/soup_cli/ tests/` passes
 - [ ] `pytest tests/ -v` passes
-- [ ] Updated relevant docs (README, CLAUDE.md) if needed
+- [ ] Updated relevant docs (`README.md` and the matching page under `docs/`) if needed
diff --git a/.gitignore b/.gitignore
index 54f2a9d..66e7b9f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,4 +57,7 @@ report.xml
 .claude/rules/
 .claude/skills/
 .claude/settings.json
-.coverage
\ No newline at end of file
+.coverage
+
+# Local scratch / temp scripts at repo root (e.g. _smoke.py, _scratch.py) — never committed
+/_*.py
diff --git a/AGENTS.md b/AGENTS.md
index 6a71d61..2f23a4d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,4 +25,8 @@ ruff check src/soup_cli/ tests/  # Lint — must be clean before any commit
 
 ## Full instructions
 
-The authoritative, detailed guide lives in [`.claude/CLAUDE.md`](.claude/CLAUDE.md) — architecture map, every CLI command, the config schema, the security model, and the release checklist. Read it before making non-trivial changes.
+- **Feature reference** lives in [`docs/`](docs/README.md) — per-topic guides plus the full `soup` command list ([`docs/commands.md`](docs/commands.md)). Read the relevant page before changing a feature.
+- **Contribution workflow, project structure, and architecture notes** are in [`CONTRIBUTING.md`](CONTRIBUTING.md). Read it before making non-trivial changes.
+- The Pydantic config schema in [`src/soup_cli/config/schema.py`](src/soup_cli/config/schema.py) is the single source of truth for every config field.
+
+(Maintainers also keep a detailed local-only operating manual at `.claude/CLAUDE.md`; it is gitignored and not part of the public repo.)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 991f4a2..85417b8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -338,7 +338,7 @@ When you open a PR, the GitHub template will show this checklist:
 
 - [ ] `ruff check src/soup_cli/ tests/` passes
 - [ ] `pytest tests/ -v` passes
-- [ ] Updated relevant docs (README, CLAUDE.md) if needed
+- [ ] Updated relevant docs (`README.md` and the matching page under `docs/`) if needed
 - [ ] New tests added for new functionality
 - [ ] No breaking changes (or documented in PR description)
 
@@ -444,7 +444,7 @@ See `CLAUDE.md` for the complete release checklist.
 ## Questions?
 
 - Check the [README](README.md) for quick start and features
-- Check [CLAUDE.md](.claude/CLAUDE.md) for detailed architecture
+- Check the [docs](docs/README.md) for the full feature reference and architecture
 - Open a GitHub Discussion for questions
 
 Thank you for contributing!
diff --git a/docs/backends-and-ops.md b/docs/backends-and-ops.md
index 21f3e16..3caf16d 100644
--- a/docs/backends-and-ops.md
+++ b/docs/backends-and-ops.md
@@ -729,7 +729,7 @@ The sender uses a 1-second hard timeout, HTTPS-only with private-IP / link-local
 
 ## Plugin System
 
-Drop a Python module under `soup_cli/plugins/` (or any package importable by Soup) and register at import time:
+Drop a Python module under `src/soup_cli/plugins/` (or any package importable by Soup) and register at import time:
 
 ```python
 from soup_cli.plugins import register_plugin
@@ -789,7 +789,7 @@ Register a plugin once via the v0.45.0 registry API; v0.53.6 wires it into every
 transformer-backend trainer as a real HF `TrainerCallback`:
 
 ```python
-# soup_cli/plugins/my_plugin.py — auto-discovered at `soup` startup
+# src/soup_cli/plugins/my_plugin.py — auto-discovered at `soup` startup
 from soup_cli.plugins import register_plugin
 
 class MyPlugin:
diff --git a/docs/peft-and-efficiency.md b/docs/peft-and-efficiency.md
index 94932c4..aad0068 100644
--- a/docs/peft-and-efficiency.md
+++ b/docs/peft-and-efficiency.md
@@ -193,7 +193,7 @@ configs where expert FFNs need lower rank than attention. Caps: 256 keys × valu
 gated and silent on unrelated models.
 
 **Template registry** — the 16 built-in templates now live as
-`soup_cli/templates/*.yaml` with a `manifest.json` index. `soup init --template <name>`
+`src/soup_cli/templates/*.yaml` with a `manifest.json` index. `soup init --template <name>`
 reads the YAML; the inline copies in `schema.py` stay as a back-compat fallback,
 deprecated in favour of the YAML registry.
 
diff --git a/docs/serving-and-export.md b/docs/serving-and-export.md
index d5ec4c3..34e4efd 100644
--- a/docs/serving-and-export.md
+++ b/docs/serving-and-export.md
@@ -414,7 +414,7 @@ Pure-Python EMA + linear-interp percentiles (DoS cap: `MAX_SAMPLES=1_000_000`).
 ## Web UI Plugin Registry + Env Knobs
 
 ```python
-# soup_cli/ui/plugins/my_tab.py
+# src/soup_cli/ui/plugins/my_tab.py
 from soup_cli.ui.plugins import register_tab
 
 def render_my_tab(request) -> str:
diff --git a/examples/README.md b/examples/README.md
index 5876ac3..fc0a389 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -400,13 +400,13 @@ max_seq_length: 2048
 output_dir: ./output_advanced/
 ```
 
-See [config schema documentation](../CLAUDE.md#config-system) for all available options.
+See the [config schema](../src/soup_cli/config/schema.py) (the single source of truth) for all available options.
 
 ## Learn More
 
 - **README**: [Main documentation](../README.md)
+- **Docs**: [Full feature reference](../docs/README.md)
 - **CONTRIBUTING**: [How to contribute](../CONTRIBUTING.md)
-- **CLAUDE.md**: [Architecture and detailed docs](../CLAUDE.md)
 
 ## Questions?