docs: prune CLAUDE.md to navigation pointers

[iabaako]

Pull Request Summary 🚀

What does this PR do? 📝

Prunes CLAUDE.md from 273 lines to 51 — a table of navigation pointers plus a short set of rules for agents — and moves the content it uniquely held into the documents that own those topics.

  CLAUDE.md                         (273 -> 51 lines)
- ├── Development commands           => Justfile / just --list
- ├── Mandatory pre-commit workflow  => CONTRIBUTING.md
- ├── Cache and data locations       => README.md
- ├── Testing config + fixtures      => pyproject.toml / CONTRIBUTING.md
- ├── src/ tree, data flow, state    => docs/ARCHITECTURE.md (new)
- ├── Adding a check / connector     => CONTRIBUTING.md
- └── Build, CI, and Release         => CONTRIBUTING.md
+ ├── Where things are documented    (pointer table)
+ └── Rules for agents               (just recipes, PR template,
                                      generated files, credentials)

Two rules were added for agents by request: always use the documented just recipes for linting and testing rather than ad-hoc ruff/pytest invocations, and always open pull requests using .github/pull_request_template.md.

Why is this change needed? 🤔

CLAUDE.md had become a second copy of documentation owned elsewhere, and the copies had already drifted:

• It documented connectors/script.py as "an empty placeholder slated for removal (issue 194)" — the file no longer exists.
• Its utils/ inventory omitted project_config.py and reapply_utils.py.
• Its command list was a subset of the Justfile, missing fmt-py, fmt-md, fmt-all, pre-commit-run, test-cov-html, and package-workflow.
• "Adding a data quality check" existed in two divergent versions, here and in CONTRIBUTING.md.

Duplicated facts go stale silently, and an agent reading the stale copy acts on it. Single-sourcing each topic removes that failure mode.

CLAUDE.md is also read by agents rather than people, so human-oriented material (project overview prose, installation context, architecture narrative) belongs in README.md and the docs/ guides instead.

How was this implemented? 🛠️

Each claim in CLAUDE.md was checked against the filesystem to find its real owner, then routed:

docs/ARCHITECTURE.md   NEW - package layout, data flow, cache/storage
                       locations, session state, generated output views,
                       credentials, DataFrame and SQL conventions
CONTRIBUTING.md        + View UI Consistency (ui_utils rules)
                       + Shared Fixtures, Testing Views, Windows
                         INTERNALERROR note, coverage threshold
                       + PR template requirement
                       ~ duplicated src/ tree -> link to ARCHITECTURE.md
README.md              + Documentation Map table
CLAUDE.md              ~ rewritten as pointers + agent rules

One further change was needed to make this durable: .claude/commands/update_claude.md previously instructed an agent to regenerate CLAUDE.md with "Architecture", "Setup & Installation", "API Documentation", "File Structure", and a "Recent Updates" section — running /update_claude once would have reverted this PR. It is rewritten as a router that sends changes to the owning document, treats an unchanged CLAUDE.md as the expected outcome, and enumerates what must not be added back.

No Python source was touched.

How to test or reproduce ? 🧪

# Markdown lint (the only automated gate these files hit)
uv tool run pre-commit run markdownlint-fix --files \
  CLAUDE.md README.md CONTRIBUTING.md docs/ARCHITECTURE.md \
  .claude/commands/update_claude.md

# Confirm content was moved rather than dropped
git diff origin/main...HEAD -- CLAUDE.md
git show HEAD -- docs/ARCHITECTURE.md

Review suggestion: read CLAUDE.md first and confirm every pointer resolves to a file that genuinely covers that topic.

Screenshots (if applicable) 📷

N/A — documentation only, no UI change.

Checklist ✅

• I have run and tested my changes locally — pre-commit passes on all five files; no Python changed, so the pytest suite is unaffected and was not run
• I have limit this PR to less than 1000 lines of code change (if not, explain why) — 310 insertions, 438 deletions
• I have updated/added tests to cover my changes (if applicable) — N/A, documentation only
• I have updated/added requirements to cover my changes (if applicable) — N/A, no dependency change
• I have run linting and formatting on any code changes (if applicable) — markdownlint-fix passes
• I have updated the documentation (README, etc.) accordingly — this PR is the documentation change
• I have reviewed and resolved any merge conflict — branched after Release v1.1.0 #291 merged; the diff against origin/main is these five files only

Reviewer Emoji Legend

	:code:	Meaning
😃👍💯	:smiley: :+1: :100:	I like this... ...and I want the author to know it! This is a way to highlight positive parts of a code review.
⭐⭐⭐	:star: :star: :star:	Important to fix before PR can be approved... And I am providing reasons why it needs to be addressed as well as suggested improvements.
⭐⭐	:star: :star:	Important to fix but non-blocking for PR approval... And I am providing suggestions where it could be improved either in this PR or later.
⭐	:star:	Give this some thought but non-blocking for PR approval... ...and consider this a suggestion, not a requirement.
❓	:question:	I have a question. This should be a fully formed question with sufficient information and context that requires a response.
📝	:memo:	This is an explanatory note, fun fact, or relevant commentary that does not require any action.
⛏	:pick:	This is a nitpick. This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter
♻️	:recycle:	Suggestion for refactoring. Should include enough context to be actionable and not be considered a nitpick.

---

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[NKeleher]

Good idea to update and clean up the documentation.