docs: fix src-layout path refs and repoint public docs off gitignored CLAUDE.md

The repo moved to src-layout and trimmed README into a 238-line front door
with the feature reference under docs/, but several committed files still
referenced bare soup_cli/ paths or linked the gitignored .claude/CLAUDE.md
(which 404s for anyone cloning the public repo).

- docs/: `soup_cli/{plugins,templates,ui/plugins}/...` path refs -> `src/soup_cli/...`
  (import statements `from soup_cli...` left unchanged — package name is still soup_cli)
- AGENTS.md: point external agents at public docs/, CONTRIBUTING.md, and the
  config schema; note CLAUDE.md is a maintainer-local (gitignored) file
- CONTRIBUTING.md + .github/pull_request_template.md: PR checklist now says
  "README.md and the matching page under docs/" (kept in sync); Questions
  section links docs/ instead of the gitignored CLAUDE.md
- examples/README.md: fix two broken ../CLAUDE.md links -> config schema source
  + docs/ feature reference
- .gitignore: add root-anchored /_*.py temp-script guard + trailing newline

.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

.gitignore

@@ -57,4 +57,7 @@ report.xml
 .claude/rules/
 .claude/skills/
 .claude/settings.json
-.coverage
+.coverage
+
+# Local scratch / temp scripts at repo root (e.g. _smoke.py, _scratch.py) — never committed
+/_*.py

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.)

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!

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:

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.
 

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:

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?