LaunchRepoOnce the workspace exists and the dashboard is running, the first real session is led by the agent. ONBOARDING.md tells it to speak your language, work through one phase at a time, fill files from your answers and verified sources, and never ask twice what it could read from an existing file. If a session breaks off, onboarding.json and SESSION.md let the next agent continue from the first incomplete phase. Here is what each phase does — and what the agent is told not to do.
Phases 1–2: orientation and a private home
The agent starts by explaining the plan: understand the product, connect the browser and the verification mailbox, agree how it may publish listings and website badges, and preserve the setup for future sessions. It asks for the first product’s name, URL and local code folder, and reads those before asking anything else. It also checks what it can actually do in this session — a terminal alone is not browser control, and the kit forbids claiming tools the session cannot call.
Phase 2 gives your data a private home. If the agent is still inside the purchased delivery repository, it initialises the independent workspace the three-step start creates and helps you set up your own private remote. It says plainly that stored login details, if you consent to storing them, live in that private repository — readable by anyone with access, including to its history — and never in the delivery repo. Owner, repository, visibility check and credential choice go into workspace.json; with a secret manager, only references are saved.
Phase 3: the product brief and your launch date
The agent runs scripts/new-product.py with a short lowercase slug and fills product.json — the product context file every playbook reads — from your answers: audience, problem, differentiator, real features, pricing or trial, launch stage, genuine screenshots and logo. The resulting copy is shown to you for corrections. Two rules protect you from embarrassing listings: capabilities are never derived from a competitor, and planned features are never described as available. Unknowns stay empty.
This phase also asks when the first launches should go live and whether there is a date before which nothing may post — with the plain warning that free-tier directories queue submissions for review and publication can take weeks, not days. Your answer becomes earliest_launch_date in product.json, the launch-date floor that record.py enforces later.
identity.json then captures the public name, contact email, nickname and organisation facts you authorise, keeping your private account email apart from the public contact address. Before any of it reaches a listing, the agent runs the short representation briefing.
Phase 4: Chrome and the mailbox
Following the Chrome connection guide, the agent walks you through Chrome’s remote-debugging page and any macOS permissions, then performs a visible smoke check on a public page. You sign in to your web mailbox in the connected browser yourself; the agent confirms it is the intended account without copying messages. Verification emails finish registrations and listings, so the scope of mailbox access is recorded in authorizations.json. Forwarding codes by hand is a supported fallback, recorded as a human handoff rather than automated access.
Phase 5: permissions, agreed once per product
The agent asks where the product website’s code lives, how it deploys, which branch is production and what the canonical URL is. Then the question that saves the most friction later: may it add an official directory badge to that product’s footer, commit, push and redeploy? Scope, answer, date and the permitted repository and branch go into authorizations.json. A “no” does not block directories that need no badge. The same file records whether free registrations, free final submissions and specific verification-email actions are authorised. Spending stays at zero, and a grant for one product never extends to another.
Phases 6–7: one real result, then a resumable workspace
With setup done, the agent runs doctor.py, separating missing setup from permission you deliberately declined. It picks three to five relevant playbooks, explains the fit, and starts with one accessible free route: search for an existing listing, verify the destination, prepare accurate copy, confirm nothing is charged, submit within the grant, record the real outcome. A good first result is often a submitted review rather than a live page — see the outcome recording guide.
To close, the agent updates onboarding.json only with checks it has actually observed, writes non-sensitive evidence and open steps to SESSION.md, puts follow-up dates in FOLLOW-UP.md, and summarises what is done, pending, waiting on you and next. A git privacy check runs before every push. The test of a good first session: the next agent can continue without registering anything again or asking for standing permissions twice. The how-it-works page shows where this sits in the whole flow.