Onboarding: the one document a second developer reads on day one

[Apolloccrypt]

docs/ONBOARDING.md. Written by running it: a fresh clone of origin/main in a temporary directory, npm ci, every suite, the deploy dry run. Nothing in the document is a number I did not see printed. Re-measured on faf599e after #359 landed; the branch carries docs only.

What is in it

• What Paramant is in five sentences, quoted out of docs/brand/messaging.md.
• The repo map: relay, admin, frontend, bron-seo, scripts/directie, scripts/heartbeat, deploy, tests, with what is in each directory and the test or workflow that guards it. Including the honest list of what is guarded by nothing (bron-seo/*.py, signalen.py, build.sh, relay/test/koop-pad-intentie.test.mjs, which no CI glob matches).
• Local setup with the exact commands CI runs and the counts they print on faf599e: relay unit 175/175, admin 40/40, root integration 152 with 150 passing and 2 skipped, crypto 144/144, ParaSign engine 4/4, boot integration 11/11, route suites 70/70, sign-full 33/33, browser suites 12/12, static-sanity 10 checks in about 1.4 seconds, deploy/deploy-3.1.sh --dry-run --preflight-only exit 0 with 0 warnings.
• The rules of the house, each with its gate: no AI attribution (scripts/check-commit-style.sh via static-sanity check 10 and the pre-push hook), every site claim tied to a test, pins hanging off tiers.js and the code rather than off another page, Community as the name of the free plan.
• Release and deploy by reference to docs/RELEASE.md and deploy/DEPLOY-3.1.md, not a second copy of them.
• The two heartbeats and how they differ, HEARTBEAT_ENABLED as a repository variable, and scripts/directie/signalen.py.
• Where production runs and who holds the key, paths only, no values.
• Ten traps of the first week: the missing @paramant/core sibling, two green PRs that merge into a red main, tap versus spec, compose without env_file, the pinned gitleaks version, a PR whose checks did not run, the suites that fail locally on purpose, a 200 healthcheck over a broken container, and the one rule eslint actually has here.

What the clean run found

The tests workflow was red on main when this started: relay/test/pricing-page.test.js had const tiers twice and tests/ui-truthfulness.test.mjs had const pricingVisible twice, both from parallel PRs appending a top-level const to the end of the same long file. A hard SyntaxError fails to load the file rather than failing a check, and the no-undef-only eslint config does not catch a redeclaration. #359 fixed both and moved its new blocks into function scope. This branch no longer carries that fix; it carries the trap as the second entry in the first-week list, with what to do about it.

One honest note that is in the document rather than hidden here: inbound-hash-verify, deep-health-gate and billing-stance-boot boot a real relay.js and wait for it to become healthy, and one run in ten failed on a loaded machine while the other nine were clean. Every other suite was deterministic across repeated runs.

Verification

Full clean-environment run on faf599e: the counts above, plus eslint clean, cache-bust 340 links, CSP inline clean, bash -n clean, and the route suites against redis:7.4.8-alpine.

Nothing on production.