Merge branch 'personal-recommender'

Personal recommender feature: interests + recommendations persistence,
recipe cook-timeline, Checkly monitoring plan, operations docs, and
embedded Postgres test-startup fix.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

# Conflicts:
#	docs/operations.md
#	plans/2026-07-14-checkly-playwright-suite/DESIGN.md
#	plans/2026-07-14-checkly-playwright-suite/PLAN.md
#	test/kaleidoscope/persistence/interests_test.clj

Author: ALai57

.gitignore

@@ -51,4 +51,7 @@ kaleidoscope.iml
 # Generated per-environment Fly configs (scripts/ephemeral/deploy-app)
 fly.kal-eph-*.toml
 
-.neon
+.neon
+
+# Playwright MCP browser-debug artifacts (console logs, page snapshots)
+.playwright-mcp/

CLAUDE.md

@@ -173,6 +173,7 @@ When debugging test failures, never pipe full test output directly into the conv
 3. **Don't refactor legacy CMS code** (articles, albums, portfolio) unless it's explicitly the task.
 4. **Every feature needs automated tests.** Unit or end-to-end — discuss the right layer, but "no tests" is not acceptable.
 5. **Keep `Taskfile.yml` in sync with `bin/`.** If a bin script is added, renamed, or changes its interface, update the Taskfile.
+6. **Keep `docs/operations.md` current.** Any change to deployment (`fly.toml`, `bin/` deploy scripts, Docker/build, secrets/env) or to the Taskfile/`bin/` interface must be reflected in `docs/operations.md` in the same change.
 
 ---
 

README.md

@@ -158,6 +158,9 @@ For local development, see [local-development.md](./docs/local-development.md)
 ## Deployment
 To deploy, follow instructions in [deployment.md](./docs/deployment.md)
 
+## Operations
+For operational concerns of running the app, see [operations.md](./docs/operations.md)
+
 
 # TODO:
 3) Update to stop using hash-routing

docs/operations.md

@@ -1,5 +1,13 @@
 # Operations
 
+Operational concerns for running Kaleidoscope in production. This document
+covers how the app is set up to operate, the guardrails around that setup, and
+the decisions behind them.
+
+> **Maintenance:** Keep this document current. Any change to deployment
+> (`fly.toml`, `bin/` deploy scripts, Docker/build, secrets/env) or to the
+> Taskfile / `bin/` interface must be reflected here in the same change.
+
 ## Synthetic monitoring (Checkly)
 
 Synthetic checks live in `checkly/` as a standard Playwright project
@@ -32,3 +40,36 @@ is include-only.
 **Deployed monitors need these Checkly environment variables** (set once in the
 Checkly account, not committed): `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`.
 `ENVIRONMENT_URL` is omitted in production so checks default to the live site.
+
+## Claude Code workspaces
+
+Kaleidoscope's AI features (the workflow engine and project scorer) call the
+Anthropic API. Rather than running Claude Code against the same Anthropic
+account and API key used for production traffic, we provision a **separate,
+dedicated Claude Code workspace** with its own key.
+
+That workspace is capped at a **hard spend limit of $10 per month**.
+
+**Why a separate workspace with a hard cap:**
+
+- **Blast radius.** A Claude Code API key can end up in more places than a
+  production key — shell history, local config, CI logs, a subagent's
+  environment. Isolating it in its own workspace means a leaked or misused key
+  can never draw down the production Anthropic budget or touch production usage.
+- **The cap bounds the damage.** $10/month is the ceiling on what a leaked key
+  can cost before it's cut off. It's high enough for normal development use and
+  low enough that a compromised key is an annoyance, not an incident.
+- **Clean attribution.** Keeping the workspaces separate makes Claude Code
+  spend legible on its own, distinct from the app's production API usage.
+
+**Operational notes:**
+
+- The workspace key is only for development tooling (Claude Code). It is **not**
+  the key the deployed app uses for its own Anthropic calls — that key lives in
+  Fly.io secrets (`ANTHROPIC_API_KEY`) and is scoped to the production
+  workspace/budget.
+- If the $10 cap is hit mid-month, Claude Code requests will start failing.
+  That's the intended signal — investigate the spend before raising the limit,
+  don't reflexively bump it.
+- If the workspace key is ever suspected leaked, rotate it in that workspace;
+  no production credential or budget is affected.

fly.toml

@@ -4,6 +4,15 @@ primary_region = "iad"
 [build]
   dockerfile = "Dockerfile"
 
+# Non-secret config only. Secrets are supplied via `fly secrets set` and are
+# NOT declared here (fly.toml can't hold their values). Required secrets:
+#   ANTHROPIC_API_KEY     — llm scorer, llm workflow executor, claude-vision transcriber
+#   FIRECRAWL_API_KEY     — firecrawl recipe fetcher
+#   GOOGLE_VISION_API_KEY — only if IMAGE_TRANSCRIBER_TYPE=google-vision
+#   KALEIDOSCOPE_DB_PASSWORD — Neon Postgres password
+#   KALEIDOSCOPE_BUGSNAG_KEY — Bugsnag exception reporting
+#   KALEIDOSCOPE_STRIPE_API_KEY — Stripe client
+#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY — S3 static content + storage
 [env]
   KALEIDOSCOPE_DB_TYPE                    = "postgres"
   KALEIDOSCOPE_DB_HOST                    = "ep-polished-frost-an34qo7y.c-6.us-east-1.aws.neon.tech"
@@ -31,6 +40,14 @@ primary_region = "iad"
   # Set to "none" until SNS/image-resizer is migrated off AWS
   KALEIDOSCOPE_IMAGE_NOTIFIER_TYPE        = "none"
 
+  # AI / pluggable components. Real backends below require ANTHROPIC_API_KEY
+  # (scorer, workflow executor, claude-vision transcriber) and FIRECRAWL_API_KEY
+  # (recipe fetcher), supplied via `fly secrets`.
+  KALEIDOSCOPE_SCORER_TYPE                = "llm"
+  KALEIDOSCOPE_WORKFLOW_EXECUTOR_TYPE     = "llm"
+  KALEIDOSCOPE_RECIPE_FETCHER_TYPE        = "firecrawl"
+  KALEIDOSCOPE_IMAGE_TRANSCRIBER_TYPE     = "claude-vision"
+
   AWS_REGION                              = "us-east-1"
 
   OTEL_SERVICE_NAME                       = "kaleidoscope-publishing"

plans/2026-07-14-recipe-cook-timeline/DESIGN.md

@@ -67,6 +67,23 @@ level. This matches the approved prototype exactly.
 Only the **authored overrides** must never be silently dropped. Everything else
 is persisted purely as an optimization.
 
+### Load-bearing invariant: overrides annotate phases
+
+An override is **not** a fact about content — it's an *annotation on a derived
+phase*. Its key (`"{component}/{label}"`) names a phase the segmenter invented;
+it can't even be expressed without the timeline to point at. Override and phase
+therefore share one identity and one lifecycle, which is why they live together
+in the blob rather than being split into an "authored" store — they are not
+independent things.
+
+What keeps an annotation valid across regenerations is **phase-identity
+stability**, and that is exactly what the trust boundary (below) guarantees: for
+an unchanged component the cached phases are kept verbatim (the LLM's
+re-segmentation is discarded), so the phase key an override points at does not
+move. When a component's steps *do* change, its phases are legitimately new and
+its overrides are legitimately dropped — the annotation's target is gone. This
+coupling is cohesion, not complecting; the trust boundary is what makes it safe.
+
 ---
 
 ## Data model