From 9ade602219ee9626a863e214230e1a0cbc34f13e Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Sun, 26 Jul 2026 17:38:51 -0400
Subject: [PATCH] docs(#2585): single lockfile-driven bootstrap path in
 CONTRIBUTING.md (#2675)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Getting Started opened with `npm install`, contradicting both the `npm ci` quick
start fifteen lines below it in the same file and docs/contributing/bootstrap.md,
which states `npm ci` is required so installs are reproducible, lockfile-driven,
and fail fast when package-lock.json is out of sync. A contributor taking the
shortest path — the first copyable block — got the wrong bootstrap contract.

Rather than correct `npm install` in place and leave two near-identical blocks,
the duplicate "Bootstrap your environment" quick start is folded into Getting
Started so CONTRIBUTING.md carries exactly ONE fresh-checkout path, in the
canonical order from bootstrap.md (nvm use -> npm run check:env -> npm ci), and
names bootstrap.md as the source of truth for everything else (fnm/asdf/mise, the
environment validator, daily commands, troubleshooting). That satisfies the
issue's "keep bootstrap.md as the source of truth rather than introducing another
variant" — three competing variants become one pointer plus one sequence.

No regression test: the change is prose in a contributor guide, not a runtime
contract, so a readFileSync+includes assertion would be exactly the source-grep
test scripts/lint-no-source-grep.cjs rejects.


Claude-Session: https://claude.ai/code/session_015TCwhbMuY37DzRMCfzTABJ

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CONTRIBUTING.md | 30 +++++++++++++-----------------
 1 file changed, 13 insertions(+), 17 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 60e171b42..6b3bc4446 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,29 +7,25 @@
 git clone https://github.com/open-gsd/gsd-core.git
 cd gsd-core
 
-# Install dependencies
-npm install
+# Activate the pinned Node version from .nvmrc
+nvm use
+
+# Validate your environment
+npm run check:env
+
+# Install dependencies (reproducible, lockfile-driven)
+npm ci
 
 # Run tests
 npm test
 ```
 
----
+`npm ci` is required over `npm install`. It installs exactly what `package-lock.json`
+specifies and fails fast if the lockfile is out of sync — this is intentional.
 
-## Bootstrap your environment
-
-For a step-by-step setup guide covering Node version managers, `npm ci`, the environment
-validator, daily commands, and troubleshooting, see:
-
-**[docs/contributing/bootstrap.md](docs/contributing/bootstrap.md)**
-
-Quick start:
-
-```bash
-nvm use           # activate the pinned Node version from .nvmrc
-npm run check:env # validate your environment
-npm ci            # install from lockfile
-```
+**[docs/contributing/bootstrap.md](docs/contributing/bootstrap.md)** is the source of truth
+for setup. See it for Node version managers other than nvm (fnm, asdf, mise), the
+environment validator, daily commands, and troubleshooting.
 
 ---