Onboarding docs: one page, four parts

Status: EXECUTED 2026-08-10, after operator review. Kept as the record of why the page is shaped this way. Her answers are folded in below (marked ANSWERED); the one open thread is the freshness automation in the last section. Issues: #840 (guides consolidation, operator-narrowed to onboarding), #825 (colleague onboarding umbrella). Related: #833 (broken-link burn-down), #829 (closed, delivered the current state). Branch: docs/onboarding-fixes.

Why

Today there are two onboarding docs and the split does not survive a plain reading of their names: ONBOARDING.md (540 lines, merged this morning from four files) and DEVELOPER_ONBOARDING.md (510 lines). "Onboarding" and "developer onboarding" describe the same audience doing the same thing, so a newcomer has no way to know which one they are supposed to be in, and we keep paying to cross-link them.

The operator also likes DEVELOPER_ONBOARDING.md's entrance (What Is Lantern: the product framing before the mechanics) better than ONBOARDING.md's, which opens on logistics. The merge should keep that opening.

Target layout (operator's, 2026-08-10)

One page, docs/engineering/guides/onboarding/ONBOARDING.md:

Part	Contents	Fed by
1. What is Lantern	The product in a few paragraphs: anonymous, venue-anchored, presence not profiles; pilot phase and invite-gated signup	DEVELOPER_ONBOARDING section 1 (kept nearly verbatim, it is the elegant entrance)
2. Prereqs	ANSWERED, narrowed: only what a human must do by hand, which is accounts/logins and VS Code (plus WSL on Windows), and the POC block. The toolchain (gh, Node, gcloud) MOVED into Part 3.B, since either the AI installs it or the by-hand path walks it.	Current Parts 1 + 2, reframed from "maintainer" to "your POC"
3.A Quick setup	The paste-ready AI prompt	Current Part 3, unchanged
3.B Full setup	Clone, install, link, editor, doctor, run the app, the Lantern Control sidebar, then credentials when they are needed	Current Parts 4 + 6, plus DEVELOPER_ONBOARDING section 3 where it adds detail
4. Additional dev instructions	What now, first PR, architecture, git flow, security checklist, testing, docs practices, environments	Current Parts 5 + 7, plus DEVELOPER_ONBOARDING sections 4 to 12

DEVELOPER_ONBOARDING.md is deleted; its inbound links repoint to the merged page.

Decision 1: what to do with content that duplicates AGENTS.md

Recommendation: cut to a pointer, do not copy. Roughly 150 lines of DEVELOPER_ONBOARDING restate AGENTS.md (key commands, deployment rules, testing config, PR label mapping). AGENTS.md is canonical by our own rule, every agent loads it, and duplication is the exact failure this whole PR has been unwinding (a stale chats collection, a changelog:consolidate script documented in eleven places and existing in none).

Option	What it does	Risks
Pointer (recommended)	Part 4 names the topic in a sentence and links AGENTS.md	A newcomer clicks once more for the full command list
Copy it in	Everything readable in one place	Two copies drift; we have already been burned twice this week
Copy the "first week" subset	Duplicate only the ten commands a newcomer actually needs	Still two copies, and the subset needs its own judgment call every time AGENTS.md changes

Decision 2: should the POC grants become a real script?

Recommendation: yes, but not in this merge. The operator asked for "simple scripts for the POC". Today those are two copy-paste commands (gh api ... collaborators, gcloud projects add-iam-policy-binding) plus four dashboard steps. A single npm run onboard:grant -- --github USERNAME --email EMAIL would make the phrase literal, print what it did, and refuse the dashboard-only steps with a checklist.

That is a tooling change with its own wiring obligations (script-wiring skill, help entry, scripts-info), and it mutates access, so it wants its own review. This merge ships the commands as a clean copy-paste block; the script follows as a small separate change if she wants it.

What gets deduplicated

Duplicate	Resolution
Prerequisites (both docs)	One list, in Part 2, keeping the OS labels
Clone and install (both docs)	One sequence, in Part 3.B, keeping the guarded clone block
Environment file / secrets (both docs)	Short version in 3.B, deep version stays in ENVIRONMENT_SETUP.md
First PR / git flow (both docs)	One section in Part 4; the rules stay canonical in AGENTS.md
Key commands, deployment rules, testing config	Pointer to AGENTS.md per decision 1
Documentation map (both docs)	One short "where to go next" at the end

Estimated result: about 700 lines, down from 1050 across two files. Long, but it is a page you read once and then stop needing, and one long page beats two overlapping ones.

Phases

1. Assemble the merged page programmatically from the two sources (same method as this morning's merge, so today's hard-won prompt text survives verbatim), in the four-part order.
2. Dedupe and rewrite the seams by hand: the joins are where errors hide.
3. Reframe maintainer to POC throughout, and add the "ask your POC" line to Part 2.
4. Delete DEVELOPER_ONBOARDING.md; rewire inbound links (README, AGENTS via .agents/rules/project/onboarding-routing.md, ENVIRONMENT_SETUP, DIRECTORY_DEFINITIONS, PR_WORKFLOW, worklog, both test-run docs) and link-check.
5. Gates: em dash, md tables, link resolver, npm run validate --scope lint,format.
6. Log it in the test plan's feedback log and re-point run-2's setup instructions at the merged page.

Risks

• A 700-line page is a scroll. Mitigation: the four parts are top-level headings with a short "what you need" map at the top, and Part 4 is explicitly the come-back-later half.
• Losing something in the merge. Mitigation: assemble programmatically, and diff the section inventory before and after rather than eyeballing.
• Run 2 is mid-flight. The operator is testing against the current text; this merge should land after that run finishes, or she should re-copy the prompt block afterward.

Open questions

1. Confirm "POC" is the term you want in the doc (versus "maintainer" or a named person).
2. Should Part 4 keep the security checklist inline (it is short and genuinely onboarding-shaped) or point at docs/security/?
3. Anything in DEVELOPER_ONBOARDING you want cut entirely rather than carried over?

Answers from the operator (2026-08-10)

• Decision 1, pointer: accepted. Plainer statement of the reason, for the record: two copies of a command list means the next person updates one of them, and the other quietly starts lying. We have already been bitten twice this week (a collection name that no longer exists, a script documented in eleven places and existing in none). So Part 4 names the topic and links AGENTS.md, which is the copy every agent already loads.
• Decision 2, the POC script: she did not follow what it was; restated as "one command that does the two runnable grants and prints a checklist for the click-only ones", and it stays deferred to its own change. She also wants better nomenclature than "maintainer".
• OQ1, naming: "POC" adopted for now, open to brainstorming. The doc uses "your POC (your point of contact on the team, the person who invited you)" on first use, so the term is self-defining and a later rename is one find-and-replace.
• OQ2, security checklist: keep inline. Done, in Part 4.
• OQ3: file is named ONBOARDING.md (done); everything re-verified during the merge, including the Lantern Control extension coverage (Quickstart versus npm run dev, the reload-and-confirm step); freshness automation is the open thread below.

Open thread: keeping docs true automatically

Her question was whether references and commands can auto-update so the docs cannot rot. Fully generating prose is not realistic, but the two rot modes we actually hit this week are both mechanically catchable, and both are lint.* scripts of the kind the repo already runs in validate:

1. Command check: every npm run X mentioned in docs/** must exist in a package.json. This is exactly the changelog:consolidate failure (documented in eleven places, existed in none) and would have caught it the day it was written.
2. Link check: every relative markdown link must resolve. This is the folder-move breakage from earlier today, caught by hand with a throwaway script; as a gate it would fail the PR that breaks it. It also gives #833 a floor: fix the backlog once, then it cannot grow.

Both are small, both fit tooling/scripts/lint.*.js with a ratchet baseline like the em-dash and story-coverage checks, so the existing backlog is grandfathered and only NEW rot fails. Recommended as a follow-up change, not folded into this merge.