sprint: add website-observability-wire-up.md

sprints/website-observability-wire-up.md

@@ -0,0 +1,51 @@
+# Sprint: website observability wire-up
+
+## Vision issues
+- #426 — Website observability — make disinto.ai an observable addressable
+
+## What this enables
+After this sprint, the factory can read engagement data from disinto.ai. The planner
+will have daily evidence files in `evidence/engagement/` to answer: how many people
+visited, where they came from, which pages they viewed. Observables will exist.
+The prerequisites for two milestones unlock:
+- Adoption: "Landing page communicating value proposition" (evidence confirms it works)
+- Ship (Fold 2): "Engagement measurement baked into deploy pipelines" (verify-observable step becomes non-advisory)
+
+## What exists today
+
+The design and most of the code are already done:
+
+- `site/collect-engagement.sh` — Complete. Parses Caddy's JSON access log, computes unique visitors / page views / top referrers, writes dated JSON evidence to `$OPS_REPO_ROOT/evidence/engagement/YYYY-MM-DD.json`.
+- `formulas/run-publish-site.toml` verify-observable step — Complete. Checks Caddy log activity, script presence, and evidence recency on every deploy.
+- `docs/EVIDENCE-ARCHITECTURE.md` — Documents the full pipeline: Caddy logs → collect-engagement → evidence/engagement/
+- `docs/OBSERVABLE-DEPLOY.md` — Documents the observable deploy pattern.
+- `docker/edge/Dockerfile` — Caddy edge container exists for the factory.
+
+What's missing is the wiring: three pieces that connect the parts together.
+
+## Complexity
+
+Files touched: 3-4 (lib/generators.sh, lib/ops-setup.sh, disinto-factory/SKILL.md, possibly site/collect-engagement.sh)
+Subsystems: Caddy config generation, ops repo initialization, cron registration
+Sub-issues: 3
+Gluecode ratio: ~85% gluecode, ~15% greenfield
+
+This is almost entirely wiring existing infrastructure — not new capability.
+
+## Risks
+
+- Production vs. factory Caddy: The factory's generated Caddyfile is for the local dev proxy (Forgejo + Woodpecker + staging). The production disinto.ai runs on a separate host Caddy. Sub-issue 1 must address both: update the template (for new deployments) and document the manual step for the existing production host.
+- Ops repo path on production host: collect-engagement.sh writes to $OPS_REPO_ROOT/evidence/engagement/. The script must commit via Forgejo API (no SSH required) so it can run on any host with a token.
+- Log format mismatch: collect-engagement.sh assumes Caddy's structured JSON format. If the production Caddy uses default Combined Log Format, the script will produce empty reports silently. Fix: add a format-detection guard.
+
+## Cost — new infra to maintain
+
+- One cron entry on the production host (55 23 * * *)
+- Daily evidence files in ops repo (evidence/engagement/*.json) — ~1KB/file, negligible storage
+- No new services, containers, or agents
+
+## Recommendation
+
+Worth it. Three small implementation issues close a design that is already fully specified and mostly implemented. The return: a live observable, daily engagement data in the ops repo, and the planner can begin evidence-driven gap analysis on the landing page. This is the cheapest path from Fold 2 to Fold 3.
+
+Do NOT add Plausible/Umami at this stage. The Caddy-log approach is cookie-free, zero-dependency, and already coded. Richer analytics can layer on top once basic observability is confirmed working.