A site that improves itself needs a platform that can write.

One question picked the platform. Can the API write?

Every analytics tool with a heatmap can tell you what happened. That is not the job. The job is a loop: read the data, form a hypothesis, ship a variant, measure it, keep the winner. An agent can only close that loop if the platform lets it create things, not just read them. So the entire evaluation collapsed into one test: does the API have a working create endpoint for experiments.

Clarity is still worth running beside PostHog on any site where you want an unlimited free recording archive for a human to scrub through. It just never gets a vote in the loop.

Four values, and only one of them is a secret.

Create one PostHog project per client site. Pick the region at creation and never guess it later: US and EU are separate hosts and a key from one returns nothing on the other. Then collect four values.

Serve PostHog from the client's own domain. It is free, and it is not optional.

Ad blockers and browser privacy modes block us.i.posthog.com by name. Most people assume the cost of that is some missing events. The real cost is much worse: the analytics bundle itself is loaded from that same host, so a blocked request does not lose some events, it loses the entire visitor. No pageview, no heatmap, no recording, nothing. Those visitors are invisible and you never see a gap where they should be.

A reverse proxy fixes this by serving everything from a subdomain of the client's own site. PostHog hosts and manages it at no cost. Blockers do not block the client's own domain.

Use PostHog's generated snippet. Then add the two flags it leaves out.

Do not hand roll a loader. PostHog's generated snippet installs a stub that queues any event fired before the bundle finishes loading, so early events survive. A hand rolled loader with a readiness flag silently drops them, and the events fired earliest are usually the ones at the top of the funnel where the traffic is.

Copy the snippet from the PostHog UI, then add the config below. Two of these options are not in the generated snippet and must be added manually every single time.

The person profiles trade, made on purpose

With identified_only, anonymous visitors never get a person profile. The consequence is real and you should know it before someone reports it as a bug: person based cohorts will calculate cleanly and return zero. That is correct behavior, not a broken config. Funnels, trends, heatmaps, replays, and every breakdown work perfectly on anonymous events, and that is effectively all of the CRO value. Setting it to always bills person processing on every anonymous ad click for a feature we do not use. Keep identified_only unless a client genuinely needs person level analysis.

The client flag is only half the switch. Read this section twice.

Setting capture_heatmaps: true in your code is not enough to collect heatmaps. There is a second, separate toggle at the project level in the PostHog UI, and it is off by default. When the code flag is on and the project toggle is off, the browser looks completely correct: the bundle loads, the config reads true, no console errors, events flow normally. Every heatmap query returns zero datapoints and no error message.

This burned a full day on the reference build. The code flag was live and verified in browser for hours while the project was quietly discarding every heatmap payload.

Reading scroll depth once it flows

The heatmap API is REST only. There is no MCP tool for it, so this is the one part of the loop that needs a direct call with the personal key.

Read cumulative_count, not bucket_count. The cumulative number is the one that answers the owner's actual question: how many people ever saw the offer. Plot it against the page height and the cliff is obvious.

Three patterns cover almost every site we will ever build.

Autocapture handles clicks for free. These three patterns cover everything autocapture cannot see, and together they took the reference site from raw pageviews to a full purchase funnel in a very small diff.

Pattern 1 · Fan out from the existing event helper

Most of our sites already push funnel events to a dataLayer through a single helper. Add PostHog inside that helper rather than at each call site. On the reference build this covered nine funnel events with one edit, and every future event added to the helper is instrumented automatically.

Pattern 2 · Virtual pageviews for in page steps

This one is mandatory, not optional. Any flow that runs on a single URL, which describes every modern scan tool, quiz, wizard, or checkout drawer we build, looks to PostHog like one pageview and nothing else. Without virtual pageviews no funnel can be built at all. Map each step to a fake path and emit it.

Pattern 3 · Super properties for anything you will segment by

Register a value once and PostHog attaches it to every subsequent event from that visitor. This is how you answer questions that span the whole session, like whether a low scoring lead buys more often than a high scoring one. Register the variant, the score, the band, anything you will later want as a breakdown.

Wire the MCP, and know the trap before it costs you an hour.

PostHog ships an official MCP with roughly 80 tools. This is what gives an agent hands: it can query insights, read funnels, create dashboards, and most importantly create feature flags and experiments. Add it as an http server with the secret referenced by variable so nothing is ever committed.

Writing the key to .env is necessary but never sufficient. Set the User scoped environment variable in the same step, then restart, because the environment is read once at launch.

Note that this is a per machine setup step. A teammate who pulls the repo gets the .mcp.json and the gitignored .env is absent, so their MCP will 401 until they run the same command. Put it in the client handoff notes.

Build the dashboard with the API. Never by hand.

The reason PostHog won is that it can be built by code, so build it by code. A hand clicked dashboard cannot be replicated to the next client, cannot be version controlled, and cannot be repaired by an agent. A script can stamp the same command center onto every client site in seconds.

The insight creation schema is fiddly and undocumented in places. This shape works and is worth copying verbatim.

One schema gotcha to save you a search: in cohort definitions, type: 'event' is invalid. The valid tags are behavioral, cohort, person, person_metadata, AND, and OR. Read the validation error text before assuming the problem is your config, because a wrong guess here sends you debugging the wrong thing entirely.

Everything in this stack can report success while quietly doing nothing.

This section exists because three separate things in this build reported success while doing nothing. If you skip everything else in this playbook, do not skip this. Each rule below is one specific failure that actually happened.

So the final check for any client is always the same, and it is server side. Ask the API what it actually stored:

PostHog knows what happened. It does not know what is allowed.

This is the part that decides whether autonomous CRO works or quietly destroys things, and it has nothing to do with analytics. PostHog is a sensor. It reports behavior on a page with no idea what that page is for, what the client agreed to, what is deliberate, or what we already tried and buried. An agent holding only PostHog data is confident and blind at the same time, which is the worst combination we can build.

The brain is not a convenience layer that makes the agent better informed. It is the refusal layer. It is the only thing standing between a plausible optimization and a broken client site.

Direction one · the agent reads the brain before it proposes

Every agent in this workspace inherits CLAUDE.md, which means every agent already has the retrieval rule. Before touching prior decisions, client history, tool gotchas, or past lessons, it queries rather than guesses. Never grep the notes, because the corpus moves and the query does not.

This is the same mechanism the self heal loop already uses. Its propose agent receives a PRIOR LESSONS block built from the top brain matches for the issue signature, so it argues from history instead of from a blank page. A CRO propose agent gets the identical treatment, with the client slug and the page as the signature.

Direction two · the agent writes back, and the loop feeds itself

A finding that lives only in a chat window is lost. The write path is already built and already runs nightly, so a CRO loop plugs into it rather than inventing a new one.

Getting the tooling right was the easy half. Statistical power is the gate.

Once the setup above is done, an agent can technically read the funnel, create a feature flag, launch an experiment, and ship the winner with no human involved. That capability arrives on day one. It should not be used on day one. An agent with write access and forty sessions of data will confidently optimize a site into noise, and it will produce a very convincing report while doing it.

So autonomy is earned in rungs, and the gate between rung two and rung three is traffic volume, not confidence.

Do not build a new machine. We already run one.

The instinct here is to design an autonomous CRO system from scratch. Resist it. This workspace already operates a loop that diagnoses a problem, writes an exact fix, has that fix independently reviewed, gates it, applies it, commits it to production, and reverts it if it regresses. That is the Sentry self heal loop, it has been live since July, and it has shipped unattended commits. Every hard problem in autonomous CRO was already solved there, in production, under real failure.

So CRO is not a new system. It is the second franchise of an existing one, with PostHog swapped in as the sensor. The heal loop watches errors. The CRO loop watches behavior. Everything between the sensor and the commit is the same machinery, and it is machinery that has already been attacked on purpose and held.

The guardrails that transfer directly

These are not theoretical. Each one exists because something went wrong once and the fix got pinned as a permanent check.

Franchising is an admission exam, not a code port

This was the breakthrough when the heal loop was extended to a second surface, and it is the single most useful idea to carry into CRO. You do not grant a client site autonomy by pointing the code at it. The site earns autonomy by passing an exam against its own configuration, and until it passes, it runs propose only.

The exam is a red team drill: plant scenarios that should be refused and confirm the loop refuses all of them. On the heal loop this ran four scenarios and refused four, twice, and designing the drill exposed two real holes in the protections that nobody had noticed. Expect the same here. The drill is not a formality, it is how you find out what your ring actually covers.

The platform can close the loop on day one. The data cannot, and the brain decides whether it should. Ship the reading before you ship the writing.

Effectively free at client scale, with one thing to watch.

PostHog's free tier is permanent and it survives upgrading, so adding a paid feature later does not remove the free allowance. There is no platform fee, which means every client site can have its own project without a per seat cost.

One shot setup for the next client site. Run it in this order.

The order matters. Toggles before traffic, because heatmaps never backfill. Proxy before the tag, so you ship the final snippet once. Verification before the dashboard, so you are not building charts on a broken pipe.

The weekly ten minute read

Once a site is live, the recurring work is small and should stay small.

• Web vitals first. If LCP is bad on mobile, nothing about copy or layout matters until that is fixed. Check this before forming any opinion about the page.
• Scroll depth against page height. Where does cumulative_count fall off, and is the offer above or below that point.
• Dead clicks. The cheapest fixes on the site are almost always here.
• Funnel by variant and by creative. Which ad brings people who actually buy, not which brings the most clicks.
• Annotate anything that changed. Deploys, price changes, budget shifts. Future you cannot read a chart without them.