Onboarding-readiness audit (2026-08-08)

Why: the operator onboards a slightly-technical, AI-assisted colleague tomorrow. Walked the real first-run path a newcomer hits and produced a day-one runbook + this gaps list.

Verdict

The onboarding tooling and docs are strong; the one real gap was discoverability at the entry point, plus two minor doc drifts. Fixed the discoverability gap in the moment.

What I actually walked (verified)

• npm run lantern (landing): clean command list + a "start with lantern doctor" pointer. Good.
• npx lantern doctor: real run, reports node / deps / gcloud / ADC / .env.local / firebase-tools / git hooks with a green summary and the exact next command on any miss. Excellent, this is the best onboarding touchpoint we have.
• ONBOARDING.md: comprehensive and accurate (updated 2026-06-15), prereqs, clone+install, lantern doctor, the committed-dev-config explanation, env:bootstrap, directory map, first-PR flow.
• .env.development: committed (11 public VITE_* vars), so npm run dev boots against dev with no secrets/auth, the smooth day-one path. Confirmed via the file + doctor + the doc's claim.
• /context-onboard skill: clear; sets up the per-user AI context (voice/people/projects), never committed.

Gaps

1. [FIXED] The README (the entry point) linked none of the above. A newcomer landing on README.md got the product pitch + a bare npm install / npm run dev, and would never discover lantern doctor, ONBOARDING.md, or /context-onboard. Fix: added an onboarding callout to the README Quick Start and created a one-page DAY_ONE.md the colleague can literally follow.
2. [minor, noted] ONBOARDING.md prereqs say "ask a team member for .env.local values" while §3 correctly shows npm run env:bootstrap pulls them from Secret Manager. Mildly redundant; env:bootstrap is the real path and the "ask a team member" line is a stale fallback. Low priority; leave for a docs pass.
3. [minor, noted] DIRECTORY_DEFINITIONS.md says "Last Updated: 2026-04-24" (~3.5 months stale). Not deep-audited here; a docs-tree reconciliation is its own small task, worth a refresh before it drifts further.

Not verified live

• npm run dev cold-start was not run as a live server in this session: the VM has several sessions active and starting Vite would contend for port 5173 (see the check-ports rule). Confirmed indirectly via the committed .env.development, a green doctor, and the doc's explicit "works immediately after npm install" claim. Worth a literal cold-start on a clean machine as the final check.

Bigger / for the day plan

• Codespace one-click env (#801) is the genuinely frictionless path (zero local setup). Deliberately out of tonight's scope; it's tomorrow's day-plan candidate with the colleague as the first real user.

Deliverables (on PR #816)

• README onboarding callout (points to lantern, DAY_ONE.md, ONBOARDING.md, /context-onboard).
• New docs/engineering/guides/DAY_ONE.md, one page, literal steps to a running app in ~10 minutes.