refactor: tidy examples/ + document use-case extraction heuristic

- Reorganize examples/ for clarity:
  - examples/raw/papers/ -> examples/data/papers/
  - examples/demo_wiki/ -> examples/data/wiki/
  - All e2e scripts moved under examples/e2e/
  - Remove examples/__init__.py (no longer an importable package)
  - examples/wiki_schema.md -> docs/wiki_schema.md
- Decouple integration test from examples/ packaging:
  tests/integration/test_e2e_scenario.py loads run_scenario via
  importlib by file path.
- Drop dead sys.path injections in moved scripts (engine is installed
  via the uv workspace).
- Sweep cross-references: README, examples/README, docs/USAGE,
  docs/wiki_schema, scripts/run_gemini_comparison, root pyproject
  ruff per-file-ignores, .gitignore.
- SPEC \u00a79.1: add use-case extraction heuristic (when a feature
  warrants its own projects/<name>/ vs. examples/, scripts/, utils,
  or the engine CLI).

All baselines preserved:
- engine: 464 passed, 12 skipped
- utils: 2 passed
- wiki-agent: 46 passed
- check_layering: OK

Author: seismael

.gitignore

@@ -79,6 +79,9 @@ checkpoints/
 # ─────────────────────────────────────────────────────────────
 examples/adapters/
 examples/wiki/
+examples/e2e/adapters/
+examples/e2e/wiki/
+examples/e2e/demo_wiki/
 
 # ─────────────────────────────────────────────────────────────
 #  Script output artifacts

CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Tidied `examples/` directory** for a clearer separation between
+  runnable demos and sample data:
+  - `examples/raw/papers/` → `examples/data/papers/` (sample paper corpus).
+  - `examples/demo_wiki/` → `examples/data/wiki/` (pre-built wiki snapshot).
+  - All e2e demo scripts (`run_e2e.py`, `run_wiki_e2e.py`,
+    `demo_e2e_scenario.py`, `research_pipeline.py`, `validate_adapter.py`)
+    moved under `examples/e2e/`.
+  - Removed `examples/__init__.py` so `examples/` is no longer treated
+    as an importable Python package; the integration test
+    `tests/integration/test_e2e_scenario.py` now loads
+    `demo_e2e_scenario` by file path via `importlib`.
+  - `examples/wiki_schema.md` moved to `docs/wiki_schema.md`.
+  - All cross-references (root `README.md`, `examples/README.md`,
+    `docs/USAGE.md`, `docs/wiki_schema.md`,
+    `scripts/run_gemini_comparison.py`, root `pyproject.toml` ruff
+    `per-file-ignores`, and `.gitignore`) updated accordingly.
+
+### Added
+
+- **SPEC §9.1 — Use-case extraction heuristic.** Documents when a
+  feature warrants its own `projects/<name>/` (≥ 2 of: external runtime
+  dependencies, domain-specific schema, long-running surface,
+  standalone publishability) vs. living in `examples/`, `scripts/`,
+  `projects/utils/`, or the engine's own CLI.
+
 ## [1.0.0rc1] — 2026-04-26
 
 First production-readiness release candidate. Public API surface and

README.md

@@ -592,7 +592,7 @@ from llm_patch.core.interfaces import (
 The `examples/` directory contains a complete tutorial that chains an [LLM Wiki Agent](https://github.com/SamurAIGPT/llm-wiki-agent) with llm-patch to build domain-specialized LoRA adapters from ML research papers:
 
 ```
-raw/papers/*.md ──► LLM Wiki Agent ──► wiki/ ──► WikiKnowledgeSource ──► adapters/
+examples/data/papers/*.md ──► LLM Wiki Agent ──► wiki/ ──► WikiKnowledgeSource ──► adapters/
 ```
 
 ### Quick Demo (No GPU Required)

SPEC.md

@@ -198,6 +198,36 @@ the same exemption.
 
 ## 9. Adding a New Use-Case Project
 
+### 9.1 Extraction Heuristic — when does something deserve its own project?
+
+Not every demo, script, or feature warrants a `projects/<name>/`
+directory. Promote a piece of work into its own use-case project when
+**at least two** of the following are true:
+
+1. **External runtime dependencies.** It pulls in third-party packages
+   (e.g. `anthropic`, `obsidian-tools`, a vector DB client) that the
+   engine itself must not depend on.
+2. **Domain-specific schema or vocabulary.** It defines its own
+   data model, frontmatter contract, prompt templates, or wire format
+   that is meaningless to the engine and to other use-cases.
+3. **Long-running surface or service.** It exposes a CLI, daemon,
+   server, or scheduled job intended to be operated as a deployable
+   unit, with its own lifecycle, configuration, and logging concerns.
+4. **Standalone publishability.** It is something an end user would
+   reasonably `pip install <name>` on its own, with its own README,
+   versioning, and changelog.
+
+If only **one** criterion applies, prefer one of these lighter homes:
+
+- **One-off scripts** that exercise the engine end-to-end belong in
+  `examples/` (tutorial demos) or `scripts/` (operator/automation
+  one-shots).
+- **Reusable stdlib-only helpers** belong in `projects/utils/`.
+- **Engine-facing CLI commands** belong in the engine itself
+  (`llm_patch.cli`), not in a separate project.
+
+### 9.2 Procedure
+
 1. Run `python tools/scaffold_project.py <name>` to materialize the
    standardized skeleton (`src/llm_patch_<name>/`, `tests/`,
    `pyproject.toml`, `README.md`, `CHANGELOG.md`). The scaffold

docs/USAGE.md

@@ -119,7 +119,7 @@ python run_e2e.py --clean --aggregate
 
 This will:
 
-1. Copy sample ML papers from `raw/papers/` into a simulated `wiki/` directory
+1. Copy sample ML papers from `examples/data/papers/` into a simulated `wiki/` directory
 2. Add wiki-style frontmatter and create entity stub pages
 3. Run the full pipeline with mock generator and repository
 4. Report all generated adapter manifests
@@ -379,7 +379,7 @@ wiki = WikiPipeline(agent, config)
 wiki.init()
 
 # Ingest a raw source
-result = wiki.ingest(Path("./raw/papers/attention-paper.md"))
+result = wiki.ingest(Path("./examples/data/papers/attention-paper.md"))
 
 # Query the wiki
 answer = wiki.query("How does self-attention work?")

examples/wiki_schema.md docs/wiki_schema.mdexamples/wiki_schema.md renamed to docs/wiki_schema.md

@@ -1,7 +1,7 @@
 # Wiki Schema (CLAUDE.md-style)
 
 This file defines the structure, conventions, and rules for the LLM Wiki.
-Load it with `WikiSchema.from_file("wiki_schema.md")`.
+Load it with `WikiSchema.from_file("docs/wiki_schema.md")`.
 
 ## Directory Layout
 
@@ -26,7 +26,7 @@ type: concept|entity|summary|synthesis|journal
 tags: [tag1, tag2]
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
-sources: [raw/papers/example.md]
+sources: [examples/data/papers/example.md]
 confidence: high|medium|low|uncertain
 ---
 ```

examples/README.md

@@ -7,63 +7,71 @@ adapter weights that can be applied to a base language model.
 ## Architecture
 
 ```
-raw/papers/*.md ──► LLM Wiki Agent ──► wiki/ (structured markdown)
-                      (ingest)          │
-                                        ▼
-                                  llm-patch library
-                                  ┌──────────────┐
-                                  │ WikiSource   │ (IKnowledgeSource)
-                                  │  watches     │
-                                  │  wiki/       │
-                                  └──────┬───────┘
-                                         ▼
-                                  ┌──────────────┐
-                                  │ Weight       │ (IWeightGenerator)
-                                  │ Generator    │
-                                  └──────┬───────┘
-                                         ▼
-                                  ┌──────────────┐
-                                  │ Adapter      │ (IAdapterRepository)
-                                  │ Repository   │
-                                  └──────┬───────┘
-                                         ▼
-                                  adapters/{id}/
+data/papers/*.md ──► LLM Wiki Agent ──► wiki/ (structured markdown)
+                       (ingest)          │
+                                          ▼
+                                    llm-patch library
+                                    ┌──────────────┐
+                                    │ WikiSource   │ (IKnowledgeSource)
+                                    │  watches     │
+                                    │  wiki/       │
+                                    └──────┬───────┘
+                                           ▼
+                                    ┌──────────────┐
+                                    │ Weight       │ (IWeightGenerator)
+                                    │ Generator    │
+                                    └──────┬───────┘
+                                           ▼
+                                    ┌──────────────┐
+                                    │ Adapter      │ (IAdapterRepository)
+                                    │ Repository   │
+                                    └──────┬───────┘
+                                           ▼
+                                    adapters/{id}/
 ```
 
-## Files
+## Layout
 
-| File | Purpose |
-|------|---------|
-| `research_pipeline.py` | Core demo — batch or watch mode pipeline |
-| `run_e2e.py` | Full end-to-end: simulate wiki → generate → validate |
-| `validate_adapter.py` | Load adapter + base model, compare inference |
-| `raw/papers/*.md` | 3 sample ML paper summaries |
+```
+examples/
+├── data/                 # Read-only sample corpora used by the demos
+│   ├── papers/           # 3 sample ML paper summaries (raw input)
+│   └── wiki/             # Pre-built wiki snapshot (sources/ + entities/)
+├── e2e/                  # End-to-end demo scripts
+│   ├── run_e2e.py            # Full pipeline: simulate wiki → generate → validate
+│   ├── run_wiki_e2e.py       # Wiki-agent variant (mock or Anthropic)
+│   ├── demo_e2e_scenario.py  # Scripted 5-step scenario for documentation/tests
+│   ├── research_pipeline.py  # Core batch/watch pipeline implementation
+│   └── validate_adapter.py   # GPU-only adapter validation script
+└── quickstart/           # Smallest possible getting-started example
+```
 
 ## Quick Start
 
 ### 1. Run the end-to-end demo (no GPU needed)
 
 ```bash
-cd examples
-python run_e2e.py --clean
+python examples/e2e/run_e2e.py --clean
 ```
 
 This will:
-1. Copy raw papers from `raw/papers/` into a simulated `wiki/` directory
+1. Copy raw papers from `examples/data/papers/` into a simulated `wiki/` directory
 2. Add wiki-style frontmatter and create entity stub pages
 3. Run the WikiKnowledgeSource → MockWeightGenerator → MockAdapterRepository pipeline
 4. Report all generated adapter manifests
 
 ### 2. Batch mode — process an existing wiki
 
 ```bash
-python research_pipeline.py batch --wiki-dir wiki/ --output-dir adapters/
+python examples/e2e/research_pipeline.py batch \
+    --wiki-dir examples/data/wiki/ --output-dir adapters/
 ```
 
 ### 3. Batch mode with wikilink aggregation
 
 ```bash
-python research_pipeline.py batch --wiki-dir wiki/ --aggregate
+python examples/e2e/research_pipeline.py batch \
+    --wiki-dir examples/data/wiki/ --aggregate
 ```
 
 When `--aggregate` is enabled, each source page follows its `[[wikilinks]]`
@@ -73,7 +81,7 @@ enriched document before weight generation.
 ### 4. Watch mode — live monitoring
 
 ```bash
-python research_pipeline.py watch --wiki-dir wiki/
+python examples/e2e/research_pipeline.py watch --wiki-dir wiki/
 ```
 
 Add or modify wiki pages while the watcher is running. Each change triggers
@@ -82,8 +90,9 @@ automatic adapter generation. Press Ctrl-C to stop.
 ### 5. Validate adapters (GPU required)
 
 ```bash
-python validate_adapter.py --adapter-dir adapters/sources/attention-paper \
-                           --base-model google/gemma-2-2b-it
+python examples/e2e/validate_adapter.py \
+    --adapter-dir adapters/sources/attention-paper \
+    --base-model google/gemma-2-2b-it
 ```
 
 This loads the base model, applies the LoRA adapter, and runs a side-by-side