Onboarding: your first day

Guide · last verified 2026-09-27. If anything here contradicts a repository's own skill, source, or tests, the repository wins — tell the team so this page gets fixed.

The 10-minute version

BloxClips is three codebases plus this docs site:

You work in	Repo	Integrates on
API, funding, payouts, scheduling	Bloxclips-backend	origin/dev
Next.js UI and Whop embed	BloxClips-frontend	origin/dev
TikTok/Instagram metrics worker	metric-scraper	origin/main

dev is staging for backend/frontend; main is production. The scraper has no staging branch and integrates on main.

Hour one: get oriented (read-only, no setup)

1. Read the docs homepage — it is the only current startup runbook.
2. Read the project map and GitHub conventions.
3. Read the architecture overview for the one-page mental model.
4. Skim the QA runbook so you know what "done" looks like here.

Do not start from archive/ — that is history, not instructions.

Hour two: tooling

You need git, gh (authenticated to the BloxClips org), node 20+, and pnpm. Then:

gh repo clone BloxClips/Bloxclips-backend
gh repo clone BloxClips/BloxClips-frontend
gh repo clone BloxClips/metric-scraper

From the workspace root that holds all three checkouts, run:

./scripts/bloxclips-doctor
./scripts/bloxclips-status --compact

Both must pass before you accept task work.

Before your first edit: Treehouse leases

Never edit a primary checkout directly. Every code task runs inside an isolated worktree:

scripts/treehouse-bloxclips acquire <backend|frontend|metric-scraper|docs> --task <ISSUE-OR-SLUG>

One task, one lease, one branch (task/<issue>-<slug>). Tests and commits happen inside the lease only. Your reviewer will check this.

Your first PR

1. Pick a Ready ticket with satisfied dependencies; claim it (assign yourself, mark Claimed, comment).
2. Work on the correct base: origin/dev for backend/frontend, origin/main for scraper and docs.
3. Run the smallest relevant tests while iterating, then the repo completion gate before handoff.
4. Open the PR against dev (backend/frontend) or main (scraper/docs) with Summary, Why, Scope, Verification, Data/Migration Impact, Risks/Rollback, and Links. One repo per PR.

Nobody merges, deploys, or moves real money without explicit human approval — including you.