First run from the UI: Set up your Lab (repo, coding agent, create Lab, approve first Formula) when no Lab exists #263

First run from the UI: onboarding with no Lab (2026-10-27)

v1 means: install Forgecell, point it at a repository, and run the whole loop from forgecell ui. Today forgecell ui with no Lab fails with "no Lab selected; use --lab DIR", so a new user has to learn forgecell init, doctor and Formula approval on the CLI first. That breaks the v1 promise.

Behaviour:

• forgecell ui run inside a git checkout with no Lab for that repository opens a Set up your Lab view instead of failing. The existing one-time link and cookie auth are unchanged.
• Steps, each one a real engine call. The UI never writes Lab files itself.
  1. Repository: the detected OWNER/REPO and default branch, read-only, and the gh auth status in plain words (signed in as …, or "Run gh auth login, then Check again").
  2. Coding agent: the harnesses doctor finds (claude-code, codex, cursor), each with version, sign-in state and model. Pick one; unavailable ones are explained, not hidden.
  3. Create the Lab: calls the same engine path as forgecell init --harness ID, which writes lab.json and proposes the initial Formula.
  4. Review and approve the first Formula: shows the proposed Formula in plain words: Atoms in order, baseline checks derived from CI, the gate policy. It also offers the review Atom on or off. One primary button, Approve Formula, bound to the shown digest, through the same decision path as init --approve.
  5. Done: go to Issues, with a hint to pick a first small Issue.
• Resumable: reload at any step resumes from the Lab's actual state. Every step is idempotent, and a half-made Lab is detected and continued, never duplicated.
• Existing Labs: forgecell ui with several Labs for the repo lets you choose; with one, it opens it (today's --lab still works).
• Never in onboarding: credentials (gh and harness sign-in stay in their own CLIs), network calls beyond gh's own repo read, and approving anything without an explicit click.

Done when

• Tests (deterministic, fake engine seams and a fixture checkout):
  • every step's happy and failure path;
  • resume after reload at each step;
  • double submit;
  • approval binds the shown digest;
  • no Lab files written outside engine calls;
  • no local absolute paths in responses.
• Visual check: the operator does a first run on a scratch repo.
• Targeted checks: go test ./internal/ui/... ./internal/cli/....

UX rules for every redesign slice (from the 2026-10-26 UI review)

• Follow the approved mockup in docs/design/ui/redesign-2026-10-26/ (its README lists the tokens and rules), with the assets in lab/internal/ui/web/assets/. Reuse the .btn primary, secondary and danger system and the glass panel from UI polish: composed Start Work controls, segmented lane bar, sharper glass (visual only) #241.
• One primary action per card or row. Destructive actions (Retire, Stop Molecule, Stop loop) sit behind a disclosure and a confirmation that names the Molecule or loop. Never place them next to a primary action.
• State in the URL: view, selected Molecule, filter and search (for example ?view=inbox, ?m=<id>, ?filter=…&q=…) via history.pushState, so Back, reload and copied links work. Navigation uses real <a href>.
• Forms: real <form>s, so Enter submits. Inputs carry name, autocomplete="off" and an example placeholder ending in "…". A submit button stays enabled until the request starts, then shows progress. Errors appear inline, linked with aria-describedby, and focus moves to them.
• No rebuild under the user: polling patches the DOM in place, keyed by id. Never rebuild a block that has focus or an input being typed in. Keep one persistent aria-live region and update its text only when it changes.
• Readable values:
  • dates via Intl.DateTimeFormat plus relative time;
  • money via Intl.NumberFormat (one precision rule; small amounts never round to $0);
  • counts via Intl.PluralRules;
  • tabular-nums for numbers;
  • never raw phase codes, assay-… or mol-… ids, full digests or ISO timestamps in the main UI (short forms only, behind "details" with a copy button).
• Plain language, second person, Title Case buttons: "Plan ready for your approval", "Coding · 18 min", "Ready to publish". Keep the primitives true: Lab, Molecule, Atom and Formula keep their names and meanings.
• Accessibility and touch:
  • a skip link;
  • one <main>;
  • ordered headings;
  • visible :focus-visible everywhere;
  • targets at least 44 px on coarse pointers;
  • touch-action: manipulation;
  • reduced motion and forced colors honoured;
  • no horizontal page scroll at 400 px.

Review checklist (read before coding)

The adversarial review checks these every time. Recent slices failed review on all of them, so build them in from the start:

• Bounds: sizes, counts, time and total work are bounded, and hitting a bound fails safe (incomplete or truncated, never silently accepted).
• Filesystem safety: paths cannot traverse. Use Lstat and O_NOFOLLOW, and check symlinks and ownership. Watch for TOCTOU races on shared dirs (/tmp). Only ever delete Forgecell-owned, marked paths.
• Untrusted input: issue text, repository files, model and tool output, and ledgers can be malformed, huge or hostile. Validate them, never interpolate them into HTML or a shell, and never let them trigger retries or approvals.
• No local leaks: no absolute local paths, environment variables or credentials in output, logs, the UI or ledgers.
• Contract changes: a changed adapter invocation bumps the protocol, and approved digests still bind exactly what was shown.
• Tests: deterministic. Use no wall-clock budgets (use readiness markers or seams), write nothing into the user's real temp or home, and cover the failure path as well as the happy path.

Plan checks (for intake)

Check category must be one of regression, candidate or setup. Use targeted package tests only as plain go test commands (for example go test ./internal/<pkg>/...); the protected view adds -json itself when protected deltas are declared. The Formula baseline already runs the full suite once, so don't add another full go test ./... check, and don't repeat its go vet or gofmt checks. A plan may hold at most 16 checks in total, counting the 5 Formula baseline checks, so prefer one combined targeted command over one check per package.

• Keep base tests compiling (added 2026-10-27): the protected view runs the base _test.go files against your code. Never change the signature of an existing Go function, method or type that a base test file calls. Add a new one instead. A protected build failure cannot be declared as an expected delta.
• After UI foundation: split app.js/style.css into per-view modules (no behaviour change) so v1 UI slices run in parallel #262: this slice owns its own web/js/<view>.js module(s) and web/css/<view>.css. Don't edit other views' modules; shared helpers go in core*.js.

Plan checks for this slice (2026-10-27)

• The operator's visual or browser check is a manual step after delivery, not a plan check. Don't add a check for it.
• Every plan check: category: regression or candidate, with reviewedAcceptance and independentProvenance left empty. The analysis must never assert independent acceptance.
• Use one combined targeted go test check for the packages this slice changes.