BloxClips documentation

For current development, start with onboarding (leases, bases, first PR), the architecture overview for repo ownership, and the QA runbook for iteration checks vs. completion gates. Backend and frontend integrate on dev; metric-scraper integrates on main. (In the outer workspace checkout, these correspond to AGENTS.md and the orchestrator/test-router skills.)

Current entrypoint — start here for QA and onboarding

This is the only current startup/QA runbook in docs/. Everything else in this folder is either a scoped plan with its own status notice or a retired compatibility pointer to the archive. Do not use archived setup, provider, or test instructions as runbooks.

Three repositories, three processes, three authoritative candidates:

Process	Repository	Integrates on	Current code entrypoint
API / funding / payouts / scheduling	Bloxclips-backend/	origin/dev	src/api/index.ts, src/index.ts
Next.js UI and Whop embed	BloxClips-frontend/	origin/dev	app/, tests/
Crawlee queue consumer and platform extraction	metric-scraper/	origin/main	src/worker/worker.ts

Safe local checks (no providers, no production data):

• ./scripts/bloxclips-doctor and ./scripts/bloxclips-status --compact from the workspace root.
• Test-router-selected iteration checks, then the repository completion gate (scripts/bloxclips-gate <leased-worktree-path>). Typical gates are backend npm run test:tracking-contract / package tests, frontend lint / test / build, scraper pnpm test / pnpm typecheck / pnpm build — always run them inside a Treehouse lease, never in a primary checkout.

Provider-capable startup is a separate, explicitly authorized step. dev, start, worker, seed/fresh-database, and migrate/deploy commands can reach real databases and providers. Do not run them for routine QA, do not reset or touch a production or shared database, and do not reuse inherited live financial credentials. Controlled mocks or Whop sandbox only when specifically authorized, with disposable identities and authorized provider scope.

Financial safety (Whop-only): CampaignInvoice -> CampaignFundingReceipt -> CampaignFundingAllocation -> exactly-once bridge -> CampaignFinanceAccount/payout journal. ABSORB means charge_buyer_fee: false; CHARGE_BUYER means true. CPM depletes client budget; RPM pays creators; rates are versioned and pinned to earning periods. Pending submissions at budget exhaustion are not paid; paused views are not paid; top-up and resume establish new earning boundaries. No live financial action during tests.

Authoritative current runbooks: root AGENTS.md, project map, GitHub conventions, the owning repository's skill/source/tests in a Treehouse lease, and current GitHub issues/PRs. Retired architecture, payment-rail, SQLite, PV-tracker, and ticket-status claims live only in the archive and must not drive implementation.

New here? Read the guides first

• Onboarding: your first day — orientation, tooling, first PR.
• QA runbook — how verification works here.
• Architecture overview — the system in one page.
• How these docs work — guides vs. reference, freshness rules.

Everything below this section is reference material: complete and searchable, but not a reading list. Each page carries its own status note.

Current operational references

• Project map, GitHub conventions, and task packet template support the existing control plane.
• Data-fetching and cache policy records reviewed privacy and freshness rules; recheck source paths when applying it.
• Payout research and open provider gates, main-to-dev redesign specification, MVP stabilization handoff, analytics workstream, and support-chat operations remain accessible but contain dated status claims. Read each status notice and verify current evidence.

Historical evidence

The archive contains retired system guides and superseded project snapshots. Original paths remain short compatibility pointers. Older architecture, payment-rail, SQLite, PV-tracker, and ticket-status claims there must not drive implementation. Archive placement does not revoke an approved product decision; establish its current authority from the owning repository, tests and issue before use.