v1 docs: install guide + README drive the whole loop from forgecell ui (Set up your Lab, Issues, Molecule view, Formula, Insights) #278

v1 install guide and README: drive the whole loop from forgecell ui (2026-10-27)

docs/install.md and README.md still describe the pre-v1 flow: first run via CLI forgecell init plus init --approve PROPOSAL_ID, and forgecell ui as "a read-only view of a Lab". As of today's merges, v1 is: install Forgecell, run forgecell ui inside your repository, and drive everything from the browser.

Rewrite (docs only, no code):

• docs/install.md → "First run":

  1. Install (keep the existing verified bootstrap section unchanged).
  2. cd into your repository and run forgecell ui.
  3. In the browser, Set up your Lab:
     • the repository and gh sign-in status;
     • pick a coding agent (claude-code, codex, cursor; each signs in with its own CLI);
     • create the Lab;
     • review and approve the first Formula (review Atom on or off).
  4. Issues: open Issues with their state. Start intake on one, or start the loop on a milestone (milestone:<name>).
  5. Molecule view: approve the plan; watch coding and checks; at the review gate preview and publish the draft PR. Merging stays on GitHub.
  6. Unblock actions, Formula view (rebind after an upgrade, refresh the baseline, review Atom, model pin) and Insights (cost, tokens and time per model).

  Keep the CLI equivalents in one short "Prefer the terminal?" subsection: init, run, loop, amend, deliver, doctor.

• docs/install.md → "Local UI": replace "read-only view" with what it actually does and doesn't do.

  • Every write goes through the engine and is bound to the digest you saw.
  • It never merges or deploys.
  • It uses a one-time link and an HttpOnly cookie, and binds to 127.0.0.1 only.
  • The UI refuses the other API routes until setup is done.

• docs/install.md → "Resources": add verificationSlots in <lab>/resources.json: default 1 when unset; new Labs get 2; a resource guard. Add the stall watchdog and fail-fast checks, in one paragraph.

• docs/install.md → "Versions, upgrade and rollback": after upgrading, rebind the Lab from the Formula view (or init --rebind). Dev builds order by recorded commit time.

• README.md: the quick start becomes the three-line UI flow, and the feature list matches the shipped views. No screenshots required.

Rules:

• Only describe shipped behaviour. Every claim must match the code at the base commit. Anything not built says so. GitLab and Jira are post-v1 (Post-v1 #1: GitLab (draft MRs, GitLab CI baseline, pipeline evidence) and Jira intake behind Forge/IssueSource interfaces #259); outside reviewers are post-v1 (Post-v1: outside code-review agents (Baz, GitLab Duo, BugBot, Anthropic/OpenAI/Qodo…) feed findings back into the loop; auto-fix high severity #260).
• Plain language, second person. Keep the primitives (Lab, Molecule, Atom, Formula) with their meanings.
• No absolute local paths, no tokens, and no personal names beyond the repository owner already shown.

Done when

• The repo hygiene scripts pass.
• A link check passes over the docs: relative links resolve inside the repo.
• Every UI step named in the guide exists in lab/internal/ui/web/index.html or its modules. Verify by grep, and list the evidence in the outcome.
• The operator reads the guide.

Plan checks for this slice

• The operator's read-through is a manual step after delivery, not a plan check. Every plan check leaves reviewedAcceptance and independentProvenance empty.
• Docs only. Use the repo hygiene check plus a targeted docs check. No Go tests are needed beyond the Formula baseline.