Unify project docs with CLAUDE.md as single source of truth

[dougborg]

Summary

Project documentation was scattered across multiple files with stale and conflicting information. This PR consolidates everything into a single authoritative source (CLAUDE.md) and brings the remaining docs up to date.

What changed

• Add CLAUDE.md — comprehensive project reference covering quick start, build commands, repo layout, conventions, architecture, data flow, deployment, and environment variables. Acts as the single source of truth for both human contributors and AI coding assistants.
• Slim down .github/copilot-instructions.md — now a lightweight entry point that inlines key conventions and defers to CLAUDE.md for depth, eliminating duplication.
• Fix README.md — replace stale Scala/shotgun tech stack references with the current Fastify + Bun API; fix broken serverless/alpr_clusters link.
• Fix serverless docs — rename "ALPR Clusters" → "ALPR Cache" in serverless/README.md and serverless/alpr_cache/README.md to match the current tile-based caching approach.
• Fix .gitignore — replace stale alpr_clusters.py exception with alpr_counts.py; add .claude/ directory.

Why this matters

• Reduces onboarding friction — new contributors get accurate, consolidated docs instead of piecing together outdated fragments.
• Improves AI-assisted development — CLAUDE.md is the standard entrypoint for Claude Code, GitHub Copilot, and similar tools, giving them correct context about the project's architecture and conventions.
• Eliminates stale references — the Scala backend (shotgun/) has been gone for a while but was still referenced in README.md and elsewhere.

Test plan

• Verified all documented commands, paths, and conventions against the current codebase
• Confirmed no stale references to alpr_clusters, shotgun, or Scala remain
• Fixed inaccurate "US + worldwide" claim in alpr_counts description (currently US-only)
• Review rendered markdown in each changed file for formatting/readability

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR consolidates project documentation by introducing CLAUDE.md as the canonical source of truth, streamlining copilot-instructions.md to reference it, and fixing outdated technical references throughout the documentation. The changes eliminate stale references to the deprecated Scala/shotgun backend and correct serverless function naming from "clusters" to "cache."

Changes:

• Added comprehensive CLAUDE.md covering quick start, architecture, data flow, conventions, and deployment
• Rewrote copilot-instructions.md as a concise entry point that inlines critical coding conventions and references CLAUDE.md
• Updated README.md tech stack from deprecated Scala/PekkoHTTP to current Fastify+Bun API, fixed broken serverless links
• Corrected serverless README terminology from "ALPR Clusters" to "ALPR Cache" and "map clusters" to "map tile caches"
• Updated .gitignore to replace stale alpr_clusters.py with alpr_counts.py and added .claude/ directory

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
CLAUDE.md	New comprehensive documentation file covering project structure, commands, architecture, and conventions
.github/copilot-instructions.md	Streamlined to inline coding conventions and reference CLAUDE.md for detailed documentation
README.md	Updated tech stack from Scala/shotgun to Fastify/Bun, fixed serverless links, corrected API running instructions
serverless/README.md	Updated terminology from "map clusters" to "map tile caches"
serverless/alpr_cache/README.md	Updated title and description from "ALPR Clusters" to "ALPR Cache" with accurate tile-based description
.gitignore	Corrected serverless file exceptions from alpr_clusters.py to alpr_counts.py, added .claude/ directory

[frillweeman]

Thanks for this! I'll accept this soon and probably make a bunch of modifications, including trashing the copilot-instructions since copilot also reads CLAUDE.md.