docs: plan for a self-serve ad network

[obro79]

Adds docs/self-serve-ad-network.md — a component-by-component plan for owning the demand side of our own ad slots, so an advertiser can sign up, write a text ad, target it, pay, and have it serve without a salesperson or a third-party network in the path.

Docs only. No code changes.

Scope

• First-party inventory only, with the ad-request API shaped as if it were external so a later multi-publisher expansion is configuration rather than a rewrite.
• Gravity / Carbon / ZeroClick stay as backfill below our own demand, so fill rate and user credit payouts never depend on direct demand ramping fast enough.

What the plan is built on

Two systems already exist that this connects:

1. Publisher side. cli/src/hooks/use-gravity-ad.ts requests from three providers that the server already normalizes onto one AdResponse shape. That boundary means a first-party network is one more AdProvider value behind the same contract — no client changes needed to introduce it.
2. Advertiser side. common/src/constants/freebuff-ads.ts is a complete self-serve marketplace (advertiser accounts, approval gates, campaign lifecycle, $5-ladder daily budgets, Stripe, admin queue) pointed at social-post boosting. It's roughly 60% of the advertiser-facing work here, and the plan extends that schema rather than standing up a parallel one.

What's actually missing: an ad server, a creative/targeting model for text ads, mediation with a floor price, measurement an advertiser will pay for, and invalid-traffic defense on inventory with no browser and no viewport.

Contents

• Current state and what's reusable as-is
• 11 components: placement registry, advertiser console, creative policy, ad server pipeline, pricing and allocation, targeting and data, mediation and backfill, the user credit loop, measurement, invalid traffic, admin and client changes
• Data model sketch
• 11 open decisions with a recommendation on each
• Six phases, Phase 0 through general availability
• Open questions

Three things worth arguing about before this merges

• The floor price is the whole project. Ad revenue pays users as credits (GrantType = 'ad'). If first-party demand doesn't clear what the backfill networks net us per placement, launching this quietly cuts user payouts and shortens free sessions. That's why Phase 0 is pure measurement with no product work.
• Flat pricing externally, eCPM internally. The plan keeps the existing stance against auctions (and the reasoning already written down in freebuff-ads.ts) for what the advertiser sees, but adds an internal eCPM ledger — mediation has to compare our demand against networks that quote in CPM, and without that number the floor price is guesswork.
• ANSI escape stripping in creative text is a security control, not a lint rule. An unescaped \x1b[ in adText can rewrite the user's terminal. Enforced server-side on ingest and on serve, with client-side stripping as defence in depth.

Unresolved

Prepaid balance vs. the daily-subscription billing the boost marketplace uses. The plan recommends prepaid, but it diverges from existing billing and needs a deliberate call.

---

Generated by Claude Code

[victorxheng]

Apologies — this PR was auto-closed by GitHub when we force-pushed a history rewrite of this repository (repository maintenance; every commit SHA changed). That was not a judgment on this PR, and GitHub does not allow us to reopen it because the commits it was based on no longer exist in the new history.

If you'd like to continue with this change: rebase your branch onto the new main (or recreate it from a fresh clone) and open a new PR — feel free to link back to this one for context, and we'll pick up the review there.

Sorry for the churn, and thanks for contributing.