Reference index: the amal66 fork, decomposed into 25 reviewable PRs

Chapter: 01 - Repository shape.

Plain-English map:
Move the project from flat `backend/` and `frontend/` folders into a
workspace layout: `apps/api`, `apps/web`, and shared `packages/*`.
This makes the codebase easier to walk because each folder has a clear job.

Why it matters:
A contributor should not need private context to know where the API, web app,
shared types, client package, or SDK live. The repo structure should teach the
project before anyone opens a README.

Principle:
Make the project legible before making it bigger. Monorepos work best when
each workspace owns one understandable responsibility.

Precedent borrowed:
The fork report showed active forks splitting concerns, adding SDK surfaces,
and creating deployment-specific structure. This commit turns that pressure
into a stable workspace map.

Upstream base: willchen96/mike@d39f580.
Original local commit: b587d63.

Chapter: 02 - Open-source collaboration.

Plain-English map:
Add a code of conduct, security policy, issue templates, and a pull request
template. These files tell people how to report bugs, propose changes, and
disclose vulnerabilities without guessing.

Why it matters:
Open-source projects are not only code. They need a shared operating manual
so first-time contributors know the rules of the room and maintainers get the
information they need.

Principle:
Healthy collaboration is documented. A project should make the safe path the
obvious path, especially for security reports.

Precedent borrowed:
GitHub community-health conventions and the security-reporting guidance
requested in upstream PR #147.

Upstream base: willchen96/mike@d39f580.
Original local commit: 045bdb7.

Chapter: 03 - Database evolution.

Plain-English map:
Introduce Supabase CLI configuration and timestamped migrations so database
changes can be reviewed, applied, and repeated over time.

Why it matters:
A single schema file shows what the database looks like today, but not how it
got there. Migrations tell future maintainers when and why the shape changed.

Principle:
Schema changes should be versioned like application code. Existing deployments
need an incremental path instead of a one-shot reset.

Precedent borrowed:
The fork report's Docker/local-development cluster, Supabase practice, and
upstream PR #113's database-integrity work.

Upstream base: willchen96/mike@d39f580.
Original local commit: bc72e34.

Chapter: 04 - Runtime safety basics.

Plain-English map:
Validate required environment variables at startup, reuse Supabase and storage
clients instead of recreating them per request, and remove a timing leak from
download-token comparison.

Why it matters:
Bad configuration should be caught before users hit the app. Shared clients
avoid needless connection churn. Secret checks should not reveal clues through
response timing.

Principle:
Fail fast, reuse expensive resources, and compare secrets in constant time.

Precedent borrowed:
Upstream PRs #81, #106, and #109, which independently targeted timing-safe
comparison, env validation, and singleton client reuse.

Upstream base: willchen96/mike@d39f580.
Original local commit: c2d2a9a.

Chapter: 05 - Observability.

Plain-English map:
Add Pino JSON logging and attach a request ID to each request so related log
lines can be traced together in production.

Why it matters:
Plain text logs are hard to search once many users are active. Structured logs
let operators answer practical questions like "what happened during this one
failed upload?"

Principle:
Production logs should be queryable, consistent, and tied to request context.

Precedent borrowed:
Upstream PR #156 and common production logging practice in hosted services.

Upstream base: willchen96/mike@d39f580.
Original local commit: 6f59af5.

Chapter: 06 - Privacy-aware logging.

Plain-English map:
Replace ad hoc console logging with structured logger calls and remove log
lines that exposed user/document activity identifiers.

Why it matters:
Legal-document activity is sensitive. Logs often flow to third-party systems,
so they should contain only what is useful for debugging and operations.

Principle:
Minimize sensitive data. Treat logs as production data, not scratch paper.

Precedent borrowed:
Upstream PR #80 and GDPR-style data-minimization practice.

Upstream base: willchen96/mike@d39f580.
Original local commit: 9398be6.

Chapter: 07 - Deployable hardening.

Plain-English map:
Add API and frontend security headers, wire the structured request logger into
the Express app, and add a readiness endpoint that checks whether dependencies
are available.

Why it matters:
Browsers and platforms need clear signals. Security headers reduce browser-side
risk, while readiness checks tell deploy platforms when the app can actually
serve traffic.

Principle:
Defense in depth plus honest health checks.

Precedent borrowed:
Upstream PR #78 and standard container/load-balancer practice that separates
liveness from readiness.

Upstream base: willchen96/mike@d39f580.
Original local commit: 73ff97a.

Chapter: 08 - Workspace independence.

Plain-English map:
Add the API package metadata, TypeScript config, and Vitest config needed for
`apps/api` to build, run, and test as a clear workspace.

Why it matters:
After the monorepo move, each workspace needs its own local controls. A new
contributor should be able to enter `apps/api` and understand its commands.

Principle:
Every package should be independently understandable even inside a monorepo.

Precedent borrowed:
Monorepo conventions used by larger TypeScript open-source projects and by
forks that split Mike into clearer package boundaries.

Upstream base: willchen96/mike@d39f580.
Original local commit: 377d685.

Chapter: 09 - Physical source move.

Plain-English map:
Move the API implementation files from the old backend location into
`apps/api` so the directory structure and package boundaries match.

Why it matters:
The repo should not say one thing in package metadata and another thing in its
file layout. Matching structure reduces mental bookkeeping for readers.

Principle:
Make ownership visible in the filesystem.

Precedent borrowed:
The same workspace and modularization pattern introduced in Chapter 01.

Upstream base: willchen96/mike@d39f580.
Original local commit: d1ec379.

Chapter: 10 - API boundaries.

Plain-English map:
Introduce a module layer for API routes, validate incoming request shapes with
Zod, and add authorization checks around tabular document access.

Why it matters:
Large route files make it hard to see where trust boundaries are. Validation
and access checks need to sit at the boundary before data reaches deeper code.

Principle:
Validate inputs and authorize data access close to the edge of the system.

Precedent borrowed:
Upstream PR #155 and the fork report's strongest security signal: multiple
forks independently patched CWE-639 style tabular-document access bugs.

Upstream base: willchen96/mike@d39f580.
Original local commit: f913869.

Chapter: 11 - First regression tests.

Plain-English map:
Add Vitest tests for download tokens, storage-path helpers, and user API-key
encryption behavior.

Why it matters:
These helpers sit near sensitive boundaries. If they regress, users can lose
access, leak secrets, or store files in the wrong place.

Principle:
Test the sharp edges first.

Precedent borrowed:
The fork report highlighted several forks with meaningful test suites. This
starts that same protection around core helper behavior.

Upstream base: willchen96/mike@d39f580.
Original local commit: 4fdc779.

Chapter: 12 - Continuous integration.

Plain-English map:
Add a GitHub Actions pipeline for tests, builds, migration checks, and deploy
gating.

Why it matters:
Reviewers should not have to run every check by hand. CI gives maintainers and
contributors a shared, repeatable answer about whether a change is ready.

Principle:
Make correctness checks part of the merge path.

Precedent borrowed:
Downstream AGPL disclosures and testing-focused forks that added CI around
backend and document-processing behavior.

Upstream base: willchen96/mike@d39f580.
Original local commit: e3d2728.

Chapter: 13 - Bounded external calls.

Plain-English map:
Add a three-minute timeout around LLM server-sent-event streams so a stalled
provider call cannot hold a connection open forever.

Why it matters:
External services can hang. Without a timeout, one stuck call can consume
server resources until something outside the app kills it.

Principle:
Every external dependency call should have a clear time boundary.

Precedent borrowed:
Upstream PR #112.

Upstream base: willchen96/mike@d39f580.
Original local commit: 8992d98.

Chapter: 14 - Secret lifetime.

Plain-English map:
Add a 30-day expiration to signed download tokens while keeping old tokens
backward compatible.

Why it matters:
A signed link should not be useful forever. Shorter lifetimes reduce the
damage if a link is copied, leaked, or found later.

Principle:
Secrets and bearer tokens should expire.

Precedent borrowed:
Upstream PR #77.

Upstream base: willchen96/mike@d39f580.
Original local commit: e6bfeb1.

Chapter: 15 - Database defense in depth.

Plain-English map:
Enable Row Level Security fallback policies that deny browser/client roles by
default on public tables.

Why it matters:
The backend uses a service role, but mistakes happen. If a future grant or
client path exposes a table, the database should still default to no access.

Principle:
Least privilege by default, with explicit access instead of accidental access.

Precedent borrowed:
Upstream PR #145.

Upstream base: willchen96/mike@d39f580.
Original local commit: faa098c.

Chapter: 16 - Consistent identity matching.

Plain-English map:
Lowercase emails before checking whether a user has shared access to a
project.

Why it matters:
People do not think of email case as meaningful. Access checks that disagree
with that expectation create confusing denials and uneven security behavior.

Principle:
Normalize identity fields before comparing them.

Precedent borrowed:
Upstream PR #79.

Upstream base: willchen96/mike@d39f580.
Original local commit: e740508.

Chapter: 17 - Resource limits.

Plain-English map:
Add `limit` and `before` cursor support to chat history loading so the API
does not return an unbounded number of chats in one request.

Why it matters:
Unbounded endpoints are easy to misuse accidentally and easy to stress on
purpose. Pagination keeps response sizes predictable.

Principle:
Public API reads should be bounded and page through large data sets.

Precedent borrowed:
Upstream PR #110.

Upstream base: willchen96/mike@d39f580.
Original local commit: b52b04f.

Chapter: 18 - Operational guardrails.

Plain-English map:
Reduce the accepted JSON body size and add handlers that log unhandled
promise rejections and uncaught exceptions.

Why it matters:
Large request bodies can create memory pressure. Unexpected crashes should
leave useful logs so operators can understand what happened.

Principle:
Bound inputs and surface failures clearly.

Precedent borrowed:
The fork report's security-hardening cluster, where many forks added basic
abuse and reliability guardrails.

Upstream base: willchen96/mike@d39f580.
Original local commit: d70fde7.

Chapter: 19 - Automated review.

Plain-English map:
Add ESLint for the API workspace, including TypeScript and security-oriented
rules.

Why it matters:
Linters catch repetitive mistakes before a human reviewer spends attention on
them. That frees review time for product and architecture questions.

Principle:
Automate the boring parts of code review.

Precedent borrowed:
Open-source CI hygiene and the fork report's broad hardening pattern.

Upstream base: willchen96/mike@d39f580.
Original local commit: 276d1fa.

Chapter: 20 - Maintenance flow.

Plain-English map:
Add Dependabot configuration and CODEOWNERS so dependency updates arrive
regularly and sensitive paths route to designated reviewers.

Why it matters:
Open-source maintenance gets easier when updates are routine and review
responsibility is explicit.

Principle:
Make maintenance systematic instead of heroic.

Precedent borrowed:
GitHub dependency-management and ownership conventions used across mature
open-source projects.

Upstream base: willchen96/mike@d39f580.
Original local commit: 5723a73.

Chapter: 21 - Security checks in the merge path.

Plain-English map:
Add npm audit and ESLint security scanning to the CI pipeline.

Why it matters:
Dependency risk and unsafe patterns should show up during pull request review,
not after deployment.

Principle:
Security automation belongs where code is merged.

Precedent borrowed:
The fork report's dominant security PR cluster and common CI hardening
practice.

Upstream base: willchen96/mike@d39f580.
Original local commit: 8cda4ca.

Chapter: 22 - User API key protection.

Plain-English map:
Replace static SHA-256 key derivation with HKDF and a unique salt per stored
user API key row.

Why it matters:
Users may store real provider keys in Mike. Those keys deserve standard,
reviewable cryptography instead of one shared derived key for every row.

Principle:
Use established key-derivation functions and per-record salts for encrypted
secrets.

Precedent borrowed:
Upstream PR #76.

Upstream base: willchen96/mike@d39f580.
Original local commit: e0a64bd.

Chapter: 23 - Server-side quota enforcement.

Plain-English map:
Check a user's monthly message credits before making chat LLM calls.

Why it matters:
A UI counter alone does not enforce anything. The backend must stop expensive
provider calls when a user has reached the configured limit.

Principle:
Billing and quota rules must be enforced server-side.

Precedent borrowed:
Upstream PR #157.

Upstream base: willchen96/mike@d39f580.
Original local commit: fa433e1.

Chapter: 24 - LLM threat modeling.

Plain-English map:
Fence document text, filenames, and other untrusted content with nonce-marked
spotlighting so the model can better separate data from instructions.

Why it matters:
Legal documents can contain malicious or simply confusing text. The model
should be told which text came from the user, which came from a document, and
which instructions are trusted.

Principle:
An LLM is not a security boundary. Prompts should preserve provenance and make
untrusted content explicit.

Precedent borrowed:
Upstream PR #158 and the threat model documented in `docs/SECURITY-MODEL.md`.

Upstream base: willchen96/mike@d39f580.
Original local commit: bededdd.

Chapter: 25 - Upload trust boundary.

Plain-English map:
Check uploaded files by their magic bytes, not only by their filename or
extension.

Why it matters:
A file can be renamed to look harmless. The backend should inspect the actual
file signature before accepting it as a supported document type.

Principle:
Trust content, not labels.

Precedent borrowed:
Upstream PR #78 and standard upload-validation practice.

Upstream base: willchen96/mike@d39f580.
Original local commit: c6dd2ec.

Chapter: 26 - Sensitive-path observability.

Plain-English map:
Replace remaining console logging in `chatTools.ts` with the same structured
Pino logger used elsewhere.

Why it matters:
`chatTools.ts` assembles prompts and handles model tool calls. It should have
the same traceability and privacy discipline as the rest of the API.

Principle:
Observability conventions should be consistent, especially in sensitive code.

Precedent borrowed:
Upstream PR #156 and the structured logging baseline from Chapter 05.

Upstream base: willchen96/mike@d39f580.
Original local commit: 921ef5b.

Chapter: 27 - Self-hosting path.

Plain-English map:
Add Dockerfiles and Docker Compose configuration so contributors can run a
local web/API setup with less manual environment work.

Why it matters:
If local setup is fragile, forks drift because everyone solves deployment
differently. A supported path keeps more work shareable upstream.

Principle:
Self-hosting should be boring and documented.

Precedent borrowed:
Upstream PRs #44, #63, and #149 plus the fork report's large local/self-hosted
stack cluster.

Upstream base: willchen96/mike@d39f580.
Original local commit: b2ae01c.

Chapter: 28 - Request-level testing.

Plain-English map:
Extract an app factory from process startup and add Supertest integration
tests that exercise the API through HTTP-style requests.

Why it matters:
Unit tests protect small functions. Integration tests catch mistakes in route
wiring, middleware order, and app startup assumptions.

Principle:
Test important boundaries at the level where users and clients hit them.

Precedent borrowed:
The fork report's testing leaders and downstream backend test coverage.

Upstream base: willchen96/mike@d39f580.
Original local commit: 9549258.

Chapter: 29 - Provider resilience.

Plain-English map:
Wrap LLM provider calls with exponential-backoff retries for temporary errors
like rate limits, timeouts, and provider outages.

Why it matters:
LLM providers occasionally fail for reasons the user cannot fix. A short,
careful retry can turn a temporary outage into a normal response.

Principle:
Classify external failures before retrying. Retry transient problems, not bad
requests or authentication errors.

Precedent borrowed:
The fork report's alternative-provider cluster and provider-abstraction work
across active forks.

Upstream base: willchen96/mike@d39f580.
Original local commit: 1417930.

Chapter: 30 - Database identity integrity.

Plain-English map:
Convert nine `user_id` columns from text to UUID and attach them to Supabase
Auth users with foreign keys.

Why it matters:
Supabase user IDs are UUIDs. Storing them as plain text allows invalid values
and orphaned rows that the database cannot protect against.

Principle:
Let the database enforce identity shape and relationships.

Precedent borrowed:
Upstream PR #113.

Upstream base: willchen96/mike@d39f580.
Original local commit: 5c28df3.

Chapter: 31 - Workflow portability.

Plain-English map:
Add endpoints for exporting and importing workflows as `.mikeworkflow.json`
files.

Why it matters:
Workflows capture reusable legal know-how. Users should be able to move them
between Mike instances, teams, and environments without database access.

Principle:
Useful knowledge should be portable.

Precedent borrowed:
Upstream PR #59.

Upstream base: willchen96/mike@d39f580.
Original local commit: 212fbbe.

Chapter: 32 - Shared workflow contract.

Plain-English map:
Add a JSON Schema and human documentation for workflow packs, including
examples and field explanations.

Why it matters:
Portable files need a shared contract. A schema lets editors, importers, and
forks validate workflow packs in the same way.

Principle:
Schema-first formats reduce fragmentation.

Precedent borrowed:
Upstream PR #34 and workflow-heavy jurisdiction and practice-area forks from
the fork report.

Upstream base: willchen96/mike@d39f580.
Original local commit: 557e647.

Chapter: 33 - Safe local development.

Plain-English map:
Document how to avoid using production databases, production buckets, real
client documents, or browser-exposed service-role keys during local testing.

Why it matters:
New contributors can accidentally leak sensitive data or admin credentials
while only trying to run the app. The docs should prevent that mistake early.

Principle:
Good setup docs are a security control.

Precedent borrowed:
Upstream PR #133.

Upstream base: willchen96/mike@d39f580.
Original local commit: 5e3608b.

Chapter: 34 - Quota regression tests.

Plain-English map:
Add unit tests for the monthly message-credit gate, including reset dates,
limit boundaries, null counters, and database-error behavior.

Why it matters:
A quota bug can either block legitimate users or make the limit meaningless.
The important edge cases need to be pinned down.

Principle:
Server-side gates need boundary tests.

Precedent borrowed:
Chapter 23 and the fork report's testing-focused active forks.

Upstream base: willchen96/mike@d39f580.
Original local commit: 919665e.

Chapter: 35 - Prompt assembly tests.

Plain-English map:
Add tests for spotlight nonce generation and document label resolution in the
prompt/tool pipeline.

Why it matters:
Prompt fencing depends on unpredictable nonces, and tool calls depend on the
model resolving document labels correctly. Both failures are subtle.

Principle:
Security-sensitive prompt helpers deserve direct regression tests.

Precedent borrowed:
Chapter 24's prompt-injection defense work.

Upstream base: willchen96/mike@d39f580.
Original local commit: d198da9.

Chapter: 36 - Provider contract tests.

Plain-English map:
Add tests that verify known model IDs route to the right provider and unknown
model preferences fall back safely.

Why it matters:
Provider routing mistakes are hard for users to diagnose. They show up only
when a chat request hits the wrong external API or an unknown model string.

Principle:
Provider abstraction needs tests that define its contract.

Precedent borrowed:
The fork report's alternative-provider cluster.

Upstream base: willchen96/mike@d39f580.
Original local commit: a706a79.

Chapter: 37 - Reader scaffolding.

Plain-English map:
Rewrite the README so it explains the fork's thesis, the open-source bets, the full change index, and the way to read this branch's commits as chapters.

Why it matters:
The branch changes a lot: repo shape, security, CI, Docker, workflows, tests, and docs. A less technical reader needs a map before they walk the history.

Principle:
Documentation should explain why the work exists, not only how to run it.

Precedent borrowed:
The fork report itself: repeated community patterns around security, self-hosting, provider choice, workflow portability, database integrity, and testing.

Upstream base: willchen96/mike@d39f580.
Original local commit: d598c70.

Chapter: 38 - Action-plan gap closure.

Plain-English map:
Add the missing foundation pieces that can be safely implemented now: a standard error helper with legacy detail compatibility, API-client parsing for the new error envelope, validated env usage for rate limits/CORS/storage, real storage readiness checks, MinIO-backed local object storage in Docker Compose, LLM circuit breaking, backend abort wiring for timed-out provider streams, access-helper tests, HTTP helper tests, and a manual follow-up register.

Why it matters:
The previous chapters handled the main security and infrastructure pulls, but the action plan still had loose ends. This commit tightens the operational boundary without pretending that larger product work like MCP connectors, a durable queue, or seeded browser E2E can be completed safely as drive-by changes.

Principle:
Automate what can be proven, document what needs manual credentials or product direction, and keep compatibility while improving contracts.

Precedent borrowed:
ACTION_PLAN.md, the fork report's testing/self-hosting/security clusters, and independent agent review of the remaining gaps.

Verification:
- npm test --workspace apps/api
- npm run build --workspace apps/api
- tsc -p packages/api-client/tsconfig.json --noEmit
- git diff --check

Upstream base: willchen96/mike@d39f580.

Chapter: 39 - Manual follow-up reduction.

Plain-English map:
Move safe pieces out of MANUAL_FOLLOW_UP.md and into the repo: add Redis to Docker Compose as the queue dependency, add OpenAI-compatible base URL support with production HTTPS guardrails, and add a skipped-by-default live Supabase access harness for proving document ID filtering against a real local Supabase database.

Why it matters:
Some follow-up items genuinely need credentials or product decisions, but the repo can still provide the rails: local dependencies, documented commands, and tests that activate when the right environment is available.

Principle:
Turn manual work into repeatable hooks wherever possible; leave only the irreducibly manual or product-shaped decisions in the follow-up document.

Precedent borrowed:
ACTION_PLAN.md, the fork report's local/self-hosting and alternative-provider clusters, and Supabase's local migration/testing workflow.

Verification:
- npm test --workspace apps/api (118 passed, 1 skipped live Supabase harness)
- npm run build --workspace apps/api
- tsc -p packages/api-client/tsconfig.json --noEmit
- git diff --check

Upstream base: willchen96/mike@d39f580.

Implements three open-source extensibility primitives so adding a new LLM
provider, storage backend, or law-library integration is a single-file
operation with no edits to core dispatch logic.

**LLM provider registry** (lib/llm/registry.ts)
- LLMProviderAdapter interface: id, matchesModel, stream, complete, models
- registerProvider() / findProviderForModel() / allRegisteredModels()
- Built-in providers (Claude, Gemini, OpenAI) self-register in index.ts on
  load; Vitest mock hoisting still captures them so retryCircuit tests pass
- providerForModel() checks registry first, then falls back to prefix
  heuristics - external providers override routing with zero core edits
- resolveModel() checks live registry union then static ALL_MODELS fallback
  (derived from *_MODELS spreads, not hand-maintained)
- Dispatch in streamChatWithTools / completeText: registry lookup + explicit
  throw on missing adapter - no silent fallthrough
- registerProvider() re-exported from lib/llm for consumer convenience
- Example: lib/llm/providers/ollama.ts shows full third-party integration

**Storage adapter pattern** (lib/storage/adapter.ts + r2.ts)
- StorageAdapter interface: upload, download, delete, getSignedUrl, checkReady
- R2StorageAdapter implements the interface with singleton S3Client
- lib/storage.ts gains setStorageAdapter() - swap to Supabase Storage, local
  filesystem, AWS S3, or MinIO with zero changes to any route or middleware
- All original function exports preserved with identical signatures

**Table-driven API-key lookup** (core/apiKeyProviders.ts)
- Provider env-var names live in a Map, not in a switch statement
- registerApiKeyProvider() lets new providers declare their env vars once
- getUserApiKeyStatus() and getUserApiKeys() iterate getRegisteredProviders()
  so a fourth provider appears in both automatically - no literal-object edits
- UserApiKeys index signature extended so third-party keys flow through
  without type changes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds a self-contained plugin system so teams can wire in Danish law,
EU law, Australian law - or any jurisdiction - without touching chatTools.ts
or any route file. One file + one registerLawLibrary() call activates the
plugin; its system prompt fragment and tools are picked up automatically.

- lib/lawLibraries/registry.ts: LawLibraryPlugin interface, registerLawLibrary(),
  buildLawLibrarySystemPrompt(), getAllLawLibraryTools()
- lib/lawLibraries/index.ts: clean public re-export surface
- lib/lawLibraries/examples/danishLaw.ts: full working example (Retsinformation.dk
  citation conventions, danish_law_search tool schema)
- chatTools.ts: two-line integration - system prompt and tool list now include
  all registered law library plugins automatically

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds sdks/python/ - a fully typed Python SDK covering every key API
surface so community forks can build integrations without writing HTTP
boilerplate from scratch.

Structure mirrors the Anthropic and OpenAI Python SDK conventions:
- MikeClient / AsyncMikeClient - thin httpx wrappers; swap in a custom
  httpx client for proxy/testing, pass session_token for auth
- Resources: chat, documents, projects, tabular, workflows, user - each
  exposed as client.<resource>.<verb>()
- SyncStream / AsyncStream - iterate SSE events from chat and tabular
  generate endpoints as plain Python dicts
- Pydantic v2 models for every response type; open to model_validate from
  raw API JSON
- Exception hierarchy (MikeError → APIError → AuthenticationError,
  NotFoundError, RateLimitError, InternalServerError, StreamError)
- 15 pytest tests with respx mocking (sync + async paths, error handling)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chatTools.ts was a 3412-line file mixing static constants, types, context
builders, and tool execution. Now split into three focused files so each
concern is navigable and independently testable:

- lib/chatToolDefs.ts  - static constants + shared types (SYSTEM_PROMPT,
  TOOLS, PROJECT_EXTRA_TOOLS, TABULAR_TOOLS, WORKFLOW_TOOLS, DocStore,
  WorkflowStore, DocIndex, ToolCall, ChatMessage)
- lib/chatContext.ts   - chat context builders (buildMessages,
  enrichWithPriorEvents, buildDocContext, buildProjectDocContext,
  buildWorkflowStore, generateSpotlightNonce)
- lib/chatTools.ts     - runtime tool execution, down to 2604 lines;
  re-exports everything from both sub-modules so no callers changed

All 128 tests pass, zero type errors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(google-cloud): GCS storage adapter + Vertex AI Gemini provider

Adds two drop-in Google Cloud integrations following the existing
extension points (StorageAdapter + LLMProviderAdapter) so no core files
needed editing beyond exporting the new classes.

**GCS storage adapter** (lib/storage/gcs.ts)
- Implements the StorageAdapter interface backed by @google-cloud/storage
- Auth via Application Default Credentials - covers service account key
  files (GOOGLE_APPLICATION_CREDENTIALS), Workload Identity on GKE /
  Cloud Run, and gcloud CLI for local dev (zero secrets to manage)
- Enabled when GCS_PROJECT_ID or GOOGLE_APPLICATION_CREDENTIALS is set
- Signed URLs use V4 signing; Content-Disposition header supported
- Swap R2 for GCS with one setStorageAdapter() call at startup:
    import { setStorageAdapter } from "./lib/storage";
    import { GCSStorageAdapter } from "./lib/storage/gcs";
    setStorageAdapter(new GCSStorageAdapter());

**Vertex AI Gemini provider** (lib/llm/providers/vertexAI.ts)
- Routes all Gemini model IDs through Google Cloud Vertex AI instead of
  AI Studio - same model IDs, different billing + auth + data residency
- Uses @google/genai (already a dep) with vertexai: true mode - no new
  package required
- Auth via ADC: Workload Identity on GKE/Cloud Run, or
  GOOGLE_APPLICATION_CREDENTIALS locally
- Replaces the built-in gemini provider on re-registration (same id):
    import { setupVertexAI } from "lib/llm/providers/vertexAI";
    setupVertexAI();

**Tests**: 23 new tests (16 GCS adapter, 7 Vertex AI provider); full
suite 151 tests passing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(readme): rewrite as setup and contribution guide

The previous README was a project retrospective - design rationale,
open-source bets, a 40-row change index - with the actual setup steps
buried partway through. This rewrites it as a task-oriented doc:

- Quick Start: clone → install → env → database → run (5 steps)
- Configuration: all env vars grouped by category with descriptions
- Extending Mike: concrete code snippets for each extension point
  (custom LLM provider, Vertex AI, GCS, custom storage, law library
  plugins, Python SDK)
- Development: test/lint/build/typecheck commands in one place
- Troubleshooting: the four most common issues
- Contributing: short version inline, CONTRIBUTING.md for the rest

The commit history and design rationale move to a collapsed footnote
(<details> block) so they're available without dominating the page.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>