Worker brief: Link In Bio Phase 4, Analytics + commission funnel¶
main. NEVER deploy to prod. NEVER run migrations against the prod DB (lifeos). NEVER commit secrets (they live in ~/.forge-secrets/*.env).
- Doctrine (FORGE-DOCTRINE): robust over quick (root-cause, no band-aids, no --no-verify), fail loud (no catch-and-ignore), idempotent by default, test the path before claiming done. No em dashes anywhere. snake_case [source]_[entity]_[state] vars. Flat verbose filenames for new code.
- Commit OFTEN. The CreatorTrack dev-slot reaper deletes idle (45m) or over-cap worktrees and will eat uncommitted work.
cd /home/justinwieb/creatortrack
2. Bootstrap your isolated slot: scripts/forge_creatortrack_agent_bootstrap.sh links-analytics 3061
(creates a git worktree on branch links-analytics + its own dev DB clone). If you do not need the dev server yet, add --no-server and start it only when verifying.
3. Worktree dev-server gotcha: turbopack symlink bug means you must run next dev --webpack in a worktree (see forge/memory/general/reference_creatortrack_worktree_dev_turbopack_symlink.md). Also watch for stale .next-dev types.
4. Dev auth for testing: WORKSPACE_DEV_AUTH=1; NEVER fresh-login over http (forge/memory/general/reference_creatortrack_dev_testing.md).
Read before planning:
- /home/justinwieb/creatortrack/AGENTS.md (search BEGIN:link-in-bio-module, ~lines 116-140)
- forge/memory/general/reference_links_module.md (canonical architecture)
- forge/memory/plans/affiliate-click-foundation-2026-07-08.md (roadmap; your work = Phase 4)
- CT app code: app/(suite)/link-in-bio/{page,[pageId]/page,stats/page}.tsx, components/apps/link-in-bio/*, lib/links-store.ts (esp. getLinkStats, ~lines 342-401), lib/links/{render,cf,brands,bio-css}.ts, app/api/links/{route,publish/route}.ts
- Schema: db/schema.ts (links pgSchema, ~lines 825-873)
- Edge worker (analytics source of truth): forge/infra/links-edge/src/{redirect,capture}.ts, schema.sql
- Sync: forge/scripts/forge_links_sync.py (D1 -> Postgres mirror, every 10 min)
Current state: clicks + captures are logged at the Cloudflare edge to D1, mirrored into Postgres links.clicks/links.captures by the sync cron. The stats page reads only mirrored Postgres rows. Attribution today is click-count by linkId/brand only. There is NO commission-dollar tracking and NO PostHog instrumentation yet. That gap is your job.
links.commissions Postgres table: workspace-scoped + RLS (match the existing links.* scoping pattern and the finance module's per-workspace GUC approach). Columns at least: id (ULID pk), workspace_id, brand, network (amazon|cj|shopmy|impact|manual), order_id/external_id, link_id (nullable FK to a click), product, amount_cents, currency, status (pending|confirmed|reversed), occurred_at, imported_at, source_batch. Idempotent upsert key on (network, external_id).
2. Commission ingestion: a manual CSV import path NOW (Amazon Associates earnings report export + a generic CSV mapper), plus a stubbed API-pull scaffold for Amazon PA-API / CJ that reads keys from ~/.forge-secrets/ when Justin provides them. Fail loud on malformed rows; idempotent on external_id.
3. Stats funnel: extend the /link-in-bio/stats page + getLinkStats into a click -> capture -> commission funnel per link/brand (the thing Beacons cannot do). Read-only "Gus stats" view; the 5 numbers that matter surfaced clearly.
4. PostHog cloud instrumentation on the PUBLISHED bio pages: land -> capture -> click-out events. Add the snippet in the edge page render (lib/links/render.ts / worker src/page.ts), keyed off a project key env var; guard so a missing key is a no-op, not a crash. Do NOT hardcode a key.
Process:
1. Read all references above.
2. Run /feature-plan for this scope. Write the spec + numbered task list to forge/memory/plans/links-analytics-commissions-2026-07-11.md. Justin authorized the buildout, so after the plan is written proceed to implement; keep the plan as the contract.
3. Implement task by task, committing at each boundary (feat(links): ...). Apply migrations ONLY to your dev clone.
4. Verify end-to-end before claiming done: seed a test commission CSV, confirm it lands in links.commissions and the funnel renders. Do not hand-drive; script the check.
5. When done or blocked, write forge/memory/handoffs/links-analytics-status-2026-07-11.md: what is built, what is tested, the EXACT Justin-only action that unblocks the rest (Amazon Associates report access + PostHog project key), and your branch name. Leave everything committed on branch links-analytics. Do NOT merge, deploy, or touch prod.
6. /notify low "links-analytics worker" "Phase 4 analytics build done, see handoff" when finished.
Execute now.