# 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.