docs: local star-history chart, README refresh, and doc-consistency fixes

[andre-salvati]

What?

Three related things, all in the docs/repo-hygiene layer — no runtime behavior changes.

1. Star-history chart is generated locally now. New scripts/star_history.py + make star-history render committed light/dark SVGs into assets/; the README's <picture> points at them.
2. README refresh + a setup-breaking fix. Resolved the two #TODOs (keyword-first H1; badges stay at top) and corrected the CI secret names in step 8.
3. Docs reconciled with the code, plus scripts/ added to the ruff lint gate.
4. Changelog conventions tightened: entries are now written at merge time and capped at ~5 rendered lines; #42/#43 headers standardized onto the PR-URL format.

Why?

The chart stopped rendering because api.star-history.com returns 503 All GitHub API tokens are rate-limited — for every repo, reproduced against facebook/react. Nothing was wrong with our markup; the free tier had exhausted its GitHub token pool. Caching their SVG would have kept the dependency, so the chart is now built from the GitHub API directly.

The most important fix is the smallest diff: README step 8 told people to configure DATABRICKS_PRINCIPAL_ID / DATABRICKS_SECRET, but onpush.yml reads DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET / TEMPLATE_ALERT_EMAILS. Anyone following the setup guide configured CI auth that silently failed. For a template whose pitch is "fork this and go," that's the worst place to be wrong. specs/architecture.md already had the correct names, so the docs also contradicted each other.

The rest came out of a documentation audit: the specs claimed a bundle validate CI step that doesn't exist, an --env local value the parser rejects, omitted --load-test and job1_sdp/ entirely, and over-generalized the retry rule. CLAUDE.md is loaded every session, and the resources/jobs.yml rule was stated in it four separate times.

How?

• No new dependencies. The SVG is hand-rolled; stargazer timestamps come from gh api (Accept: application/vnd.github.star+json).
• Two committed SVGs, not one, to keep the existing <picture> light/dark switch.
• Chart form: single-series line, so no legend (the title carries identity) and exactly one direct label (the current total) — a static README image has no hover layer to carry values.
• known-first-party = ["_sdk_sql"] was needed once scripts/ was linted: isort otherwise files that local sibling under the third-party databricks imports.
• Changelog rule (CLAUDE.md): an entry is written immediately before merge rather than during development (scope grows; an early entry just gets rewritten), and is capped at ~5 rendered lines (~475 chars) on top of the 3-sentence rule — "3 sentences" alone had drifted into 17-line run-ons. Applies to new entries only; the changelog stays append-only, so the other 47 entries are untouched.
• Constraints and Keep It Simple in CLAUDE.md were left verbatim — they're the rules most often broken. Only genuine duplication was cut (~90 → 88 lines).

Validation?

• make unit-test — 16 passed.
• pre-commit run --all-files — both hooks pass; ruff check src/ scripts/ clean; 23 files formatted.
• Lint gate proven, not assumed: a deliberately-broken probe in scripts/ initially reported "Passed" — pre-commit skips untracked files. Once git-added, the hook caught it and failed. The gate genuinely covers scripts/.
• Both SVGs rendered in a real browser and inspected (no label collisions, clean ticks, correct in both themes); the committed files are byte-identical to what was reviewed.
• Downsampling (MAX_POINTS) and nice_ticks edge cases exercised with 1,000 synthetic stars.
• Merged origin/main (which brought in feat: weekly USD cost pivots + generated markdown cost report #47, merged mid-branch); the only conflict was both branches adding a changelog entry at the top — resolved keeping feat: weekly USD cost pivots + generated markdown cost report #47.
• Every corrected doc claim re-checked against source — README secret names now diff-match onpush.yml exactly.

Verified on the pushed branch: GitHub does rewrite relative paths inside <source srcset> — both sources resolve to /andre-salvati/databricks-template/raw/<branch>/assets/… and serve 200 image/svg+xml. This had been an open risk (<picture> has no fallback if a matched source fails, so a bad path would break dark mode outright); it is now confirmed working in both themes, and no absolute-URL workaround is needed.

Impact in prod

• No table schema/data change — no production impact.

No table, schema, cluster key, or task logic touched. The only src/ change is a corrected comment in job1_sdp/pipeline.py (it said the streaming silver freezes price; it freezes product_name since #43). Docs-only pushes are skipped by paths-ignore, but this PR also touches scripts/, pyproject.toml, and src/, so CI will run.

Chosen strategy: leave as-is (no schema change).

🤖 Generated with Claude Code