chore(dx): add local dev doctor and setup commands

.github/pull_request_template.md

@@ -8,11 +8,15 @@
 
 ## Validation
 
+- [ ] `npm run verify`
+- [ ] `npm run verify:ci`
+- [ ] `npm test -- test/documentation.test.ts`
 - [ ] `npm run lint`
 - [ ] `npm run typecheck`
 - [ ] `npm test`
-- [ ] `npm test -- test/documentation.test.ts`
 - [ ] `npm run build`
+- [ ] `npm run doctor:dev` (when troubleshooting setup/environment issues)
+- [ ] `npm run setup:dev` (for first-clone reproducibility checks)
 
 ## Docs and Governance Checklist
 

.github/workflows/ci.yml

@@ -6,10 +6,15 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     name: Test on Node.js ${{ matrix.node-version }}
     runs-on: ubuntu-latest
+    timeout-minutes: 30
 
     strategy:
       matrix:
@@ -28,32 +33,18 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Repository hygiene check
-        run: npm run clean:repo:check
-
-      - name: Security audit (CI policy)
-        run: npm run audit:ci
-
-      - name: Lockfile floor guard
-        run: npm run test -- test/lockfile-version-floor.test.ts
+      - name: Run CI verify pipeline
+        run: npm run verify:ci
 
       - name: Security audit (full dependency tree, non-blocking)
         continue-on-error: true
         run: npm run audit:all
 
-      - name: Run type check
-        run: npm run typecheck
-
-      - name: Run tests with coverage
-        run: npm run coverage
-
-      - name: Build
-        run: npm run build
-
   lint:
     name: Lint
 
     runs-on: ubuntu-latest
+    timeout-minutes: 20
 
     steps:
       - name: Checkout code
@@ -68,12 +59,16 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Run ESLint
+      - name: Dev doctor sanity check
+        run: npm run doctor:dev
+
+      - name: Run lint and format checks
         run: npm run lint
 
   codex-compat:
     name: Codex Compatibility Smoke
     runs-on: ubuntu-latest
+    timeout-minutes: 20
 
     steps:
       - name: Checkout code

CONTRIBUTING.md

@@ -22,15 +22,17 @@ If a proposal conflicts with OpenAI policy boundaries, it will be declined.
 ## Local Setup
 
 ```bash
-npm ci
-npm run typecheck
-npm run lint
-npm test
-npm run build
+npm run setup:dev
+npm run verify
 ```
 
 Node requirement: `>=18`.
 
+Supporting commands:
+
+- `npm run doctor:dev` for prerequisite and repo-shape checks
+- `npm run format` to apply Biome formatting for repo config files
+
 ---
 
 ## Development Standards
@@ -56,13 +58,17 @@ Documentation requirements for behavior changes:
 1. Create a focused branch from `main`.
 2. Keep commits atomic and reviewable.
 3. Run full local gate:
+   - `npm run verify`
+   - `npm run test -- test/documentation.test.ts`
+4. If triaging failures, run component gates directly:
+   - `npm run doctor:dev`
    - `npm run typecheck`
    - `npm run lint`
    - `npm test`
    - `npm run build`
-4. Include command output evidence in the PR description.
-5. Document behavior changes and migration notes when needed.
-6. Ensure no secrets or local runtime data are committed.
+5. Include command output evidence in the PR description.
+6. Document behavior changes and migration notes when needed.
+7. Ensure no secrets or local runtime data are committed.
 
 Use `.github/pull_request_template.md` when opening the PR.
 
@@ -116,4 +122,4 @@ Unacceptable behavior:
 
 ## License
 
-By contributing, you agree contributions are licensed under the project license in [LICENSE](LICENSE).
+By contributing, you agree contributions are licensed under the project license in [LICENSE](LICENSE).

README.md

@@ -93,6 +93,28 @@ codex auth check
 
 ---
 
+## Local Development (Contributors)
+
+From repo root:
+
+```bash
+npm run setup:dev
+```
+
+Daily validation:
+
+```bash
+npm run doctor:dev
+npm run verify
+```
+
+- `doctor:dev` validates local prerequisites and required project files.
+- `setup:dev` runs install plus the local validation gate.
+- `verify` is the canonical local and CI gate.
+- `format` applies Biome formatting for repo config files (JSON/JSONC/YAML).
+
+---
+
 ## Quick Start
 
 ```bash

biome.jsonc

@@ -6,7 +6,16 @@
 		"useIgnoreFile": true
 	},
 	"files": {
-		"includes": ["**", "!!**/dist"]
+		"includes": [
+			"package.json",
+			"biome.jsonc",
+			".github/**/*.yml",
+			".github/**/*.yaml",
+			"!!dist/**",
+			"!!coverage/**",
+			"!!node_modules/**",
+			"!!vendor/**"
+		]
 	},
 	"formatter": {
 		"enabled": true,

docs/DOCUMENTATION.md

@@ -39,6 +39,8 @@ Canonical governance for repository documentation quality and consistency.
 | IA/findability audit (2026-03-01) | `docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md` |
 | Config fields internals | `docs/development/CONFIG_FIELDS.md` |
 | Config flow internals | `docs/development/CONFIG_FLOW.md` |
+| Local development runbook | `docs/development/LOCAL_DEV.md` |
+| Release runbook | `docs/development/RELEASE_RUNBOOK.md` |
 | Repository ownership map | `docs/development/REPOSITORY_SCOPE.md` |
 | Testing and release gates | `docs/development/TESTING.md` |
 | TUI parity checklist | `docs/development/TUI_PARITY_CHECKLIST.md` |

docs/README.md

@@ -56,6 +56,8 @@ Canonical documentation map for `codex-multi-auth`.
 | [development/IA_FINDABILITY_AUDIT_2026-03-01.md](development/IA_FINDABILITY_AUDIT_2026-03-01.md) | IA/findability baseline, mismatches, and migration plan |
 | [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md) | Complete field and env inventory |
 | [development/CONFIG_FLOW.md](development/CONFIG_FLOW.md) | Configuration resolution flow |
+| [development/LOCAL_DEV.md](development/LOCAL_DEV.md) | Local contributor setup and validation runbook |
+| [development/RELEASE_RUNBOOK.md](development/RELEASE_RUNBOOK.md) | Maintainer release gate and checklist |
 | [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map by repository path |
 | [development/TESTING.md](development/TESTING.md) | Validation gates and test matrix |
 | [development/TUI_PARITY_CHECKLIST.md](development/TUI_PARITY_CHECKLIST.md) | Dashboard UX parity checklist |

docs/development/LOCAL_DEV.md

@@ -0,0 +1,85 @@
+# Local Development Runbook
+
+Canonical contributor workflow for setting up and validating this repository.
+
+---
+
+## Prerequisites
+
+- Node.js `>=18`
+- npm available in `PATH`
+- git available in `PATH`
+
+Verify environment:
+
+```bash
+npm run doctor:dev
+```
+
+---
+
+## First Clone
+
+From repo root:
+
+```bash
+npm run setup:dev
+```
+
+`setup:dev` runs:
+
+1. environment checks (`doctor:dev`)
+2. dependency install (`npm ci`)
+3. validation gate (`npm run verify`)
+4. docs integrity smoke (`npm test -- test/documentation.test.ts`)
+
+---
+
+## Daily Development
+
+```bash
+npm run verify
+```
+
+Use component commands when debugging failures:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run build
+```
+
+Format repo config files (JSON/JSONC/YAML):
+
+```bash
+npm run format
+```
+
+---
+
+## Common Failure Modes
+
+- `doctor:dev` fails on missing npm/git:
+  - ensure shell `PATH` includes Node.js and git executables
+- `verify` fails on audit policy:
+  - run `npm run audit:ci` to inspect blocking advisory output
+- `setup:dev`/`doctor:dev` on Windows fails with transient `EBUSY`/`EPERM` lock errors:
+  - retry `npm ci` first (transient antivirus/file contention is common)
+  - if it persists, pause antivirus or exclude the repository, then re-run in an elevated PowerShell/CMD session
+  - if state looks corrupted, run `git clean -fdx` then run `npm ci` again
+  - if lock contention still stalls installs, try `npm ci --no-audit` or run setup from WSL2
+- `test/documentation.test.ts` fails with missing `dist/lib/*.js`:
+  - run `npm run build` and re-run the docs test
+
+---
+
+## CI Parity
+
+CI uses `npm run verify:ci` for the matrix test gate.
+
+Local equivalent:
+
+```bash
+npm run verify:ci
+```

docs/development/RELEASE_RUNBOOK.md

@@ -0,0 +1,57 @@
+# Release Runbook
+
+Maintainer checklist for preparing a reliable release from `main`.
+
+---
+
+## Preconditions
+
+1. Release PR merged to `main`
+2. CI checks green on latest `main`
+3. Working tree clean
+
+---
+
+## Validation Gate
+
+Run from repository root:
+
+```bash
+npm run release:check
+```
+
+This command runs:
+
+1. `npm run verify`
+2. `npm run test -- test/documentation.test.ts`
+3. `npm pack --dry-run`
+
+---
+
+## Documentation Gate
+
+Before publishing/tagging:
+
+1. update `CHANGELOG.md`
+2. add or update matching release note in `docs/releases/`
+3. verify docs links in `README.md` and `docs/README.md` point to the latest stable release note
+
+---
+
+## Publish/Tag Flow
+
+1. bump version in `package.json` and lockfile as needed
+2. commit release metadata
+3. create signed/annotated git tag
+4. push commit and tag
+5. verify package metadata and release notes in GitHub
+
+---
+
+## Rollback
+
+If release validation fails after version bump:
+
+1. revert release commit on branch
+2. re-run `npm run release:check`
+3. open a corrective PR with failure evidence

docs/development/TESTING.md

@@ -19,6 +19,15 @@ Coverage thresholds in `vitest.config.ts`: statements/branches/functions/lines >
 
 ## Core Commands
 
+```bash
+npm run setup:dev
+npm run doctor:dev
+npm run verify
+npm run verify:ci
+```
+
+Component commands:
+
 ```bash
 npm run typecheck
 npm run lint
@@ -39,11 +48,18 @@ npm run bench:edit-formats:smoke
 
 ## Recommended Local Gate Before PR
 
-1. `npm run typecheck`
-2. `npm run lint`
-3. `npm test`
-4. `npm run build`
-5. run docs command checks for newly documented command paths
+1. for first clone setup: `npm run setup:dev`
+2. `npm run verify`
+3. `npm run test -- test/documentation.test.ts`
+4. run docs command checks for newly documented command paths
+
+## Release Gate
+
+Run before version bump, tag, or publish workflow:
+
+1. `npm run release:check`
+2. verify changelog and release notes alignment
+3. confirm PR checks are green on the release branch
 
 * * *