docs: judge-ready documentation, plus three bugs it turned up

AGENTS.md

@@ -69,7 +69,7 @@ for the full product spec and `docs/build-plan.md` for the delivery order.
   repo. It emits an ordinary UDF around `AI_COMPLETE` anyway, so we write that ourselves.
 
 - **Backend**: Cloud Run — `/api/generate`, plus serving `/{owner}/{repo}` and
-  `/{owner}/{repo}/card.svg`. It renders the SVG from Snowflake's card payload and
+  `/{owner}/{repo}/card.png`. It renders the SVG from Snowflake's card payload and
   writes it to the bucket. It computes no analysis of its own.
 - **Cache of record**: a public GCS bucket. The card's existence in the bucket _is_
   the ready state.
@@ -105,8 +105,9 @@ rescaffold; if you find a reference to either, it is stale — fix it.
 - A repo with no real story says so. Sparse histories get an honest template card, not
   manufactured drama.
 - Cost guards are mandatory: cap commits per repo, cap daily live generations, cache
-  failed states, reject private/missing/oversized repos, and keep gallery cards
-  pre-generated.
+  failed states, reject private/missing repos, and keep the landing-page example cards
+  pre-generated. An oversized history is windowed to its newest slice, not rejected —
+  and the card says so rather than passing a slice off as the whole life.
 
 ## Documentation
 

Dockerfile

@@ -23,6 +23,9 @@ ENV NODE_ENV=production
 COPY --from=deps  /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 COPY package.json ./
+# The image ships no fonts, and the card names its families by hand. Without these the PNG
+# rasterizes with the type missing — and the type is the card.
+COPY assets ./assets
 
 USER node
 EXPOSE 8080

LICENSE

@@ -4,6 +4,12 @@
 
 Copyright (c) 2026 Ashley Childress
 
+Required Notice: Copyright Ashley Childress (https://anchildress1.dev)
+
+Licensor: Ashley Childress <https://github.com/anchildress1>
+
+Software: Commit Chronicles
+
 ## Acceptance
 
 In order to get any license under these terms, you must agree

Makefile

@@ -65,7 +65,7 @@ gcp-bootstrap: ## Create the GCP resources deploy.sh expects (idempotent, one-of
 	./scripts/gcp-bootstrap.sh
 
 deploy: ## Build the image and deploy to Cloud Run
-	set -a; [ -f .env ] && . ./.env; set +a; ./deploy.sh
+	./deploy.sh
 
 clean: ## Remove build output
 	rm -rf dist coverage playwright-report test-results .vite

deploy.sh

@@ -5,11 +5,29 @@
 # The project resources this expects (bucket, Artifact Registry repo, service accounts,
 # Secret Manager entry, Cloud Tasks queue) are created once by `make gcp-bootstrap`.
 #
-# Secrets never appear here. SNOWFLAKE_PAT is mounted from Secret Manager at run time;
-# .env is for local development only and is not read by this script.
+# Config comes from .env; SNOWFLAKE_PAT comes from Secret Manager and is mounted at run
+# time. No secret value is ever passed on a gcloud command line, where it would land in
+# shell history and the audit log.
 
 set -euo pipefail
 
+# Read here rather than in the caller, so the script behaves the same run bare or run by
+# make. Named keys only — sourcing .env would pull SNOWFLAKE_PAT and GITHUB_TOKEN into the
+# environment of a process that shells out to gcloud, which is exactly what Secret Manager
+# exists to prevent. An already-exported value wins, so CI can override with no file present.
+#
+# Every key here is optional at *this* layer: a missing one falls through to the defaults
+# below, or to the ${VAR:?} guards that make the genuinely-required ones fatal. Hence the
+# `|| true` — under `set -e`, a grep that matches nothing would otherwise kill the deploy.
+CONFIG_KEYS=(SNOWFLAKE_ACCOUNT SNOWFLAKE_USER CARD_BUCKET PUBLIC_ORIGIN DAILY_GENERATION_CAP)
+if [[ -f .env ]]; then
+  for key in "${CONFIG_KEYS[@]}"; do
+    [[ -n ${!key:-} ]] && continue
+    value="$(grep -E "^${key}=" .env | tail -1 | cut -d= -f2- || true)"
+    [[ -n ${value} ]] && export "${key}=${value}"
+  done
+fi
+
 PROJECT="${PROJECT:-anchildress1}"
 REGION="${REGION:-us-east1}"
 SERVICE="${SERVICE:-commit-chronicles}"

docs/build-plan.md

@@ -1,136 +1,49 @@
 # Commit Chronicles — Build Plan
 
-## TL;DR
+Delivery order and what became of it. The product contract — architecture, the card, the detector, the Cortex call, the renderer/Cortex ownership split — lives in [`initial-design-spec.md`](initial-design-spec.md) and is not repeated here.
 
-- **What:** a shareable OG card that tells the one real story hiding in a developer's commit history. Drops into a README, embeds in a post.
-- **Stack:** Snowflake does the work. A public **GCS bucket** holds the card. **Cloud Run** is a thin display shell — it serves the embeddable page and pushes the button.
-- **Built with:** `snow` CLI (SQL objects scripted in-repo) + Snowflake MCP (so Claude writes and runs the DDL).
 - **Prize:** Best Use of Snowflake — the app _is_ Snowflake.
 - **Due:** Mon Jul 13, 06:59 UTC.
-
-## Architecture
-
-```
-Cloud Run (static SPA + API, no analysis)
-   │  POST /api/generate → guard, claim, enqueue
-   ▼
-Cloud Tasks
-   │  OIDC POST /internal/generate
-   ▼
-Cloud Run worker ────────────────────────────────────────┐
-                                                         ▼
-                                                    Snowflake
-   │                                                  ├─ ingest proc   external access → api.github.com → COMMITS
-   │                                                  ├─ detector      plain SQL: gaps, streaks, hours → pick ONE thread
-   │                                                  └─ cortex        narrates it + picks the palette (hex + mood)
-   │                                                     │
-   │  ◄── card payload (JSON) ────────────────────────────┘
-   ▼
-Cloud Run renders the SVG → writes it to the bucket
-   ▼
-public GCS bucket ──► README <img> · dev.to embed
-```
-
-Snowflake gets its own data, finds the story, and reads it. Cloud Run serves the page and
-API, queues durable work, calls one proc in the worker request, and turns the payload into
-an SVG. **The card in the bucket is the state** — if the file exists, it is ready. The
-browser polls `/api/state/{owner}/{repo}`; it never calls the bucket for state.
-
-**Rendering is Cloud Run's job, not Snowflake's.** Templating an SVG proves nothing about a warehouse, and doing it in-warehouse would put a `STORAGE INTEGRATION`, an external stage, and a service-account IAM grant on the critical path for zero narrative gain. Cloud Run has to exist anyway; it writes to GCS with ordinary credentials.
-
-## Tooling
-
-- **Snowflake MCP (self-hosted, `Snowflake-Labs/mcp`)** — Cortex plus object management and SQL orchestration. This is what lets Claude create the network rule, secret, integration, and procedures.
-- **Snowflake connector (directory)** — Cortex Agents / Cortex Search. Retrieval only; good for querying, not for DDL.
-- **`snow` CLI** — every object lives as SQL in the repo and deploys with one command. Reproducible, reviewable, and it's what the writeup screenshots.
-
-## Snowflake objects (the whole app)
-
-| object                                              | job                                                        | status      |
-| --------------------------------------------------- | ---------------------------------------------------------- | ----------- |
-| `GITHUB_API_RULE` (EGRESS, `api.github.com`)        | let the warehouse out                                      | ✅ deployed |
-| `GITHUB_TOKEN` (`SECRET`)                           | GitHub token                                               | ✅ deployed |
-| `GITHUB_API_ACCESS` (`EXTERNAL ACCESS INTEGRATION`) | binds rule + secret                                        | ✅ deployed |
-| `COMMITS`                                           | owner, repo, sha, subject, body, authored_at, bot/AI flags | ✅ deployed |
-| `PROC INGEST_REPO_COMMITS(owner, repo)`             | Python + external access → REST Commits API → `COMMITS`    | ✅ deployed |
-| `COMMITS_CLEAN` (view)                              | drops merges + bots, derives date/hour parts               | ✅ deployed |
-| detector views                                      | gaps, streaks, night share, drama scores → one winner      | ✅ scripted |
-| `CARD_EVIDENCE` (view)                              | the winning thread's ~20 commits — all Cortex ever sees    | ✅ scripted |
-| `PROC READ_REPO(owner, repo)`                       | ingest if cold → detector → Cortex → card payload JSON     | ✅ deployed |
+- **Deploy:** `make snowflake-deploy` — every object is SQL in the repo. An object created by clicking in a UI does not exist.
+
+## Snowflake objects
+
+| object                                              | status     |
+| --------------------------------------------------- | ---------- |
+| `GITHUB_API_RULE` (EGRESS, `api.github.com`)        | ✅ shipped |
+| `GITHUB_TOKEN` (`SECRET`) — created out-of-band     | ✅ shipped |
+| `GITHUB_API_ACCESS` (`EXTERNAL ACCESS INTEGRATION`) | ✅ shipped |
+| `COMMITS` · `REPO_INGEST` · `INGEST_STAGE`          | ✅ shipped |
+| `PROC INGEST_REPO_COMMITS(owner, repo)`             | ✅ shipped |
+| `COMMITS_CLEAN` · `DETECTOR_CONFIG` (views)         | ✅ shipped |
+| detector views (15) → `REPO_STORYLINE`              | ✅ shipped |
+| `COMMIT_LINES` · `CARD_EVIDENCE` (views)            | ✅ shipped |
+| `CHRONICLE_CARD` (UDF)                              | ✅ shipped |
+| `CARD_PLOT` (view) · `CARDS`                        | ✅ shipped |
+| `PIPELINE_VERSION` · `STALE_CARDS` (views)          | ✅ shipped |
+| `CARD_PAYLOAD` (view) · `REFRESH_CARD_DATA()`       | ✅ shipped |
+| `PROC READ_REPO(owner, repo)`                       | ✅ shipped |
 
 No `STORAGE INTEGRATION` and no external stage — Cloud Run owns the bucket.
 
-## Stage 1 — the detector (plain SQL, no LLM, free)
-
-Score candidate threads, pick the single most dramatic **true** one:
-
-- **relapse** — `LAG` over commit dates: silent ≥N days, then resumed. _(rai-lint: 107 days dark, back at 3:32am)_
-- **nocturne** — share of commits after 22:00. _(my-hermantic-agent: 85%)_
-- **binge** — longest consecutive-day streak, or the heaviest single night.
-- **collapse** — a spike, then permanent silence. _(the 3:53am ending)_
-- **fight** — a revert/hotfix cluster (regex; no AI needed).
-- **resurrection** — dead, returned, **and shipped a release**.
-
-Floors (minimum real commits) keep bots and noise from winning. Deterministic — same handle, same story.
-
-## Stage 2 — Cortex (one small call)
-
-Feed **only the winning thread's evidence** — ~10–20 real commit messages plus the computed facts. It returns:
-
-```json
-{
-  "kicker": "the death of a side project",
-  "headline_upright": "Born in daylight. Last touched at",
-  "headline_accent": "3:53 in the morning",
-  "headline_trail": ".",
-  "label_first": "it begins",
-  "label_pivot": "",
-  "label_last": "",
-  "accent": "#e8a04a",
-  "accent_reason": "amber, for a thing that burned out"
-}
-```
-
-Nine keys, all the writing on the card. The italic run sits inside sentence 2 — `headline_upright` is upright, `headline_accent` is italic and in the accent colour, `headline_trail` is upright again. Empty labels for the anchors this storyline doesn't use (a collapse has no separate pivot; a non-active repo doesn't get a poetic label on the last commit).
-
-**Cortex picks the palette.** One `accent` hex paints every accent-coloured element on the card — kicker slug, italic headline fragment, last-commit dot, arrow, void-panel rule, attribution bullet. A project that died and one that shipped must not wear the same colour.
-
-**Renderer owns the facts.** Kicker slug prefix, header meta (`59 COMMITS · QUIET SINCE FEB 25`), first/last-commit anchor prefixes, void-panel text, caption, author handle — all composed from `FACTS`, `STATUS`, `PIVOT_AT`, and the `PLOT` array. See the Ownership section in `docs/initial-design-spec.md` for the full split.
-
-## Stage 3 — the card
-
-Cloud Run templates an SVG (1200×630) from the Cortex JSON plus the plotted commits, and writes it to the public GCS bucket.
-
-**Design:**
-
-- Didone headline in three slots — upright, italic accent fragment, upright · mono kicker naming the genre · status label (`abandoned` / `shipped 1.0.1`).
-- **The arc is the card:** beeswarm scatter, date across and hour down, night at the bottom. Daylight commits hollow, night commits solid. The dead stretch is a **void panel** you look through. The final commit is one accent dot.
-- Poetic tails pin to the anchors the storyline uses. The headline **interprets** — that's the point.
-
-## Cost
-
-Detection is free SQL. Cortex sees ~20 commits, not thousands. Cloud Run scales to zero. Storage is a bucket. Ballpark: **lunch money, once.**
-
-## Timeline
+## Timeline (as delivered)
 
-- **Fri night — THE GATE.** MCP + `snow` CLI connected. Prove two things: external access can reach `api.github.com` from inside a proc, and Cortex AISQL runs in your region. Nothing else matters until both are green.
-- **Sat AM** — `ingest_commits` → `COMMITS_RAW` for one handle.
-- **Sat PM** — detector SQL. Confirm it picks `my-hermantic-agent` (nocturne/collapse) and `rai-lint` (resurrection) unaided.
-- **Sun AM** — Cortex call (kicker, headline, anchor labels, accent) via `READ_REPO`; Cloud Run renders the SVG → GCS.
-- **Sun PM** — Cloud Run shell + `/api/generate`; confirm the card renders in a real README and the page embeds in a dev.to draft.
-- **Sun night** — writeup: the detector SQL, the Cortex call, the `snow` deploy. Cards are the demo.
+- **Fri night — THE GATE.** Two things proven before anything else was allowed to matter: external access can reach `api.github.com` from inside a proc, and Cortex AISQL runs in the region.
+- **Sat AM** — ingest → `COMMITS`.
+- **Sat PM** — detector SQL. It picked the intended storylines unaided.
+- **Sun AM** — Cortex call via `READ_REPO`; Cloud Run renders the SVG → GCS.
+- **Sun PM** — Cloud Run shell + `/api/generate`; card confirmed rendering in a real README.
+- **Sun night** — writeup.
 - **Mon early** — submit with buffer.
 
 ## Open items
 
-- **Font rendering in the SVG** — GitHub proxies README images through camo, so webfonts won't load. Fix is a base64-embedded subset. Deferred by decision.
-- **Anonymous serving** — Snowflake will not answer an anonymous HTTP request (SPCS "public" endpoints are RBAC-gated; a browser gets a login page). The public GCS bucket is the answer.
-- **Async generation** — Cloud Tasks owns the durable worker request. The page polls
-  `/api/state`, so closing the tab does not affect the job.
+- ~~**Font rendering**~~ **Closed.** The card is rasterized to PNG with the fonts vendored, so nothing depends on a proxy fetching a webfont. dev.to forced this — its image proxy will not serve an SVG.
+- **Stale cards** — `STALE_CARDS` reports which cards a dead pipeline version wrote; it does not act, because acting costs a Cortex call each. `make cards-rerender` redraws stored cards for free — only a prompt change needs real spend.
 
-## Cut first if behind
+## Cut
 
-1. Extra story types (ship `relapse` + `nocturne` only).
-2. The gallery page.
+1. **The gallery page.** Three example chips on the landing page cover the same need.
+2. Story types beyond the six — none were needed.
 
-**Never cut:** external-access ingest · the detector SQL · the Cortex call including the palette pick · the SVG card · the writeup showing the SQL.
+**Never cut, and wasn't:** external-access ingest · the detector SQL · the Cortex call including the palette pick · the SVG card.