Rewrite CLAUDE.md against the real architecture; resolve the 3-way mocking-policy contradiction

Part of #108 · **Phase 5** · label: documentation

## Problem

`CLAUDE.md` is the file every AI coding session loads as ground truth, so its inaccuracies propagate into work. Verified inaccuracies:

- **"Add new cluster type to `ClusterType` enum in `config.py`"** — **no such symbol exists.** `grep -rn ClusterType clustrix/` returns nothing; `config.py:19` uses a plain `cluster_type: str`. Anyone following this instruction is looking for a thing that isn't there.
- **"ClusterExecutor (`clustrix/executor.py`): Central execution engine handling job submission, SSH connection management, file transfer, job monitoring..."** — `executor.py` is a **39-line re-export shim** (`:1-38`). The real logic lives in `executor_core.py` (466), `executor_connections.py` (389), `executor_schedulers.py` (378), `executor_scheduler_status.py` (651), `executor_kubernetes.py` (461), `executor_cloud.py` (470) — **none of which CLAUDE.md mentions.**
- **"Implement `_submit_{type}_job` method in `ClusterExecutor`"** — these are back-compat wrappers (`executor_core.py:430-448`); real work is in `SchedulerManager.submit_*_job` / `KubernetesJobManager`.
- **The architecture section omits most of the package**: the entire notebook stack (`notebook_magic_{core,config,widget,mocks,enhanced,aws,azure,gcp,ssh}.py`, `modern_notebook_widget.py` at 1,631 lines), plus `cloud_providers/`, `cost_providers/`, `pricing_clients/`, `kubernetes/`, `credential_manager.py`, `auth_manager.py`, `function_flattening.py`, `gpu_utils.py`.
- **"The project is in beta (v0.1.0)"** — `pyproject.toml` and `setup.py` say `0.1.1`.
- **Direct self-contradiction on mocking.** `CLAUDE.md` says unit tests *"Mock external dependencies"*; `.claude/CLAUDE.md` says *"Do not use mock services for anything ever"*; `README.md` claims *"Zero use of `@patch`, `Mock()`"*. Three files, three incompatible policies — which is a large part of how the suite ended up with 2,513 mock occurrences while claiming to have none.

**Verified accurate, for the record** (do not "fix" these): `scripts/check_quality.py`, `scripts/pre_push_check.py`, `scripts/run_real_world_tests.py` with its documented flags, both installed git hooks, and the entire filesystem-utilities section.

## Stale project-management state

| Path | Verdict |
|-|-|
| `notes/` | One file, `github_sub_issues_mapping_2025-09-04.md`, ~11.5 months old, covers only #101/#103 |
| `.claude/epics/remove-1password/` | Orphaned — has `97.md` + `97-analysis.md` but no `epic.md`, no status |
| `.claude/epics/test-coverage-90-percent/` | `status: backlog` for an epic with 30 unpushed commits claiming completion |
| Untracked WIP | `coverage_detailed_report.txt`, `103-*.md`, `updates/103/` |

## Acceptance criteria

- [ ] `CLAUDE.md` architecture section regenerated from the **actual** module layout
- [ ] The `ClusterType` enum instruction removed or the enum introduced
- [ ] "Adding a new cluster type" rewritten against the real extension points (`SchedulerManager`, the provider ABC from the Phase 3 issue)
- [ ] **One** mocking policy, stated once, consistent across `CLAUDE.md`, `.claude/CLAUDE.md`, and `README.md`
- [ ] Version reference removed from prose, or sourced from a single location
- [ ] `notes/` and `.claude/epics/` reconciled with reality or archived
- [ ] A CI check that fails when `CLAUDE.md` references a symbol or path that does not exist — the same drift will otherwise recur

Start by comparing CLAUDE.md, .claude/CLAUDE.md, README.md, pyproject.toml, and setup.py, then inspect the module layout and the executor files named in the issue. Trace the real extension points through executor_core.py, executor_schedulers.py, and executor_kubernetes.py before reconciling the architecture, version, mocking, and stale-state documentation. Done means the acceptance checklist is satisfied, including a CI check for nonexistent CLAUDE.md symbols or paths.

Written by the indexing model from the issue text.