ToolboxAid · ToolboxAid · Jun 28, 2026 · Jun 28, 2026 · Jun 28, 2026 · Jun 28, 2026
diff --git a/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_branch-validation.md b/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_branch-validation.md
@@ -0,0 +1,10 @@
+# PR_26171_ALFA_009 Branch Validation
+
+| Check | Status | Evidence |
+| --- | --- | --- |
+| Failed dirty attempt recorded | PASS | Dirty files listed in PR report before reset. |
+| Failed dirty attempt discarded | PASS | Ran `git reset --hard` and `git clean -fd`. |
+| Clean `main` confirmed before implementation | PASS | `main...origin/main` was `0 0`; worktree was clean. |
+| Branch recreated from `main` | PASS | Current branch is `PR_26171_ALFA_009-team-aware-bootstrap` at source commit `a4e671ec8`. |
+| Scope check | PASS | Changes limited to approved bootstrap scripts, package scripts, tests, and reports. |
+| Validation | PASS | Targeted validation commands passed. |
diff --git a/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_manual-validation-notes.md b/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_manual-validation-notes.md
@@ -0,0 +1,75 @@
+# PR_26171_ALFA_009 Manual Validation Notes
+
+## Primary Alfa Owner Command
+
+```powershell
+npm run dev:bootstrap -- --team alfa
+```
+
+Expected diagnostics:
+
+- `Team: alfa`
+- `Role: owner`
+- `Web URL: http://127.0.0.1:5510`
+- `API URL: http://127.0.0.1:5511/api`
+- `Browser launch: http://127.0.0.1:5510/index.html`
+
+## Primary Alfa Codex Command
+
+```powershell
+npm run dev:bootstrap -- --team alfa --role codex
+```
+
+Expected diagnostics:
+
+- `Team: alfa`
+- `Role: codex`
+- `Web URL: http://127.0.0.1:5512`
+- `API URL: http://127.0.0.1:5513/api`
+- `Browser launch: skipped for codex role`
+
+## Legacy Command
+
+```powershell
+npm run dev:local-api
+```
+
+Expected result:
+
+- Legacy startup remains available.
+- The legacy command still runs `node --use-system-ca ./dev/scripts/start-local-api-server.mjs`.
+
+## Other Startup Commands
+
+```powershell
+npm run dev:bootstrap -- --team owner
+npm run dev:bootstrap -- --team bravo
+npm run dev:bootstrap -- --team charlie
+npm run dev:bootstrap -- charlie
+npm run dev:bootstrap -- --team delta
+npm run dev:bootstrap -- --team echo
+npm run dev:bootstrap -- --team foxtrot
+npm run dev:bootstrap -- --team golf
+npm run dev:bootstrap -- --team hotel
+```
+
+For Charlie, both forms should show:
+
+- `Team: charlie`
+- `Web URL: http://127.0.0.1:5530`
+- `API URL: http://127.0.0.1:5531/api`
+- `Browser launch: http://127.0.0.1:5530/index.html`
+
+If `.env` or the current shell already has `GAMEFOUNDRY_SITE_URL` or `GAMEFOUNDRY_API_URL`, bootstrap should still show the resolved team/role ports in diagnostics and launch the browser from the computed `GAMEFOUNDRY_SITE_URL`.
+
+## Failure Checks
+
+```powershell
+npm run dev:bootstrap -- --team omega
+npm run dev:bootstrap -- --team alfa --role reviewer
+```
+
+Expected result:
+
+- Unknown team fails with the supported team list.
+- Unknown role fails with the supported role list.
diff --git a/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_report.md b/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_report.md
@@ -0,0 +1,114 @@
+# PR_26171_ALFA_009 Team-Aware Bootstrap Report
+
+## Purpose
+
+Implement team-aware local dev bootstrap commands with role-aware port assignment while preserving the legacy local API command.
+
+## Reset Note
+
+Before rebuilding from clean `main`, the failed dirty attempt included:
+
+- `dev/reports/codex_changed_files.txt`
+- `dev/reports/codex_review.diff`
+- `dev/scripts/start-local-api-server.mjs`
+- `package.json`
+- untracked bootstrap reports
+- untracked `dev/scripts/start-dev.mjs`
+- untracked `dev/scripts/team-port-config.mjs`
+- untracked `dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs`
+
+Per OWNER instruction, those uncommitted changes were discarded with `git reset --hard` and `git clean -fd`, then this branch was recreated from clean `main`.
+
+## Implementation Summary
+
+- Added `npm run dev:bootstrap`.
+- Added `npm run dev:api`.
+- Added `npm run dev:web`.
+- Preserved `npm run dev:local-api` unchanged as the legacy alias.
+- Added `dev/scripts/team-port-config.mjs` for full team name and role-aware port resolution.
+- Added `dev/scripts/start-dev.mjs` as the bootstrap orchestrator.
+- Added focused node tests for team resolution, role offsets, invalid team/role validation, script wiring, `.env` loading behavior, and bootstrap diagnostics.
+- Added automatic browser launch for owner-role `dev:bootstrap` after the API and web servers are both ready.
+- Skipped automatic browser launch for the `codex` role.
+- Fixed npm argument forwarding/parsing so both `--team charlie` and positional `charlie` select the same team after the package script's `--mode bootstrap` argument.
+- Treats `.env` `GAMEFOUNDRY_SITE_URL` and `GAMEFOUNDRY_API_URL` as legacy/default local values for bootstrap mode, then overwrites runtime URLs from the resolved team/role ports.
+
+## Supported Teams
+
+`owner`, `alfa`, `bravo`, `charlie`, `delta`, `echo`, `foxtrot`, `golf`, `hotel`
+
+## Supported Roles
+
+`owner`, `codex`
+
+## Port Mapping
+
+`owner` role uses base ports. `codex` role uses base ports plus 2.
+
+| Team | Owner Web | Owner API | Codex Web | Codex API |
+| --- | ---: | ---: | ---: | ---: |
+| owner | 5500 | 5501 | 5502 | 5503 |
+| alfa | 5510 | 5511 | 5512 | 5513 |
+| bravo | 5520 | 5521 | 5522 | 5523 |
+| charlie | 5530 | 5531 | 5532 | 5533 |
+| delta | 5540 | 5541 | 5542 | 5543 |
+| echo | 5550 | 5551 | 5552 | 5553 |
+| foxtrot | 5560 | 5561 | 5562 | 5563 |
+| golf | 5570 | 5571 | 5572 | 5573 |
+| hotel | 5580 | 5581 | 5582 | 5583 |
+
+## Commands Added
+
+```powershell
+npm run dev:bootstrap
+npm run dev:api
+npm run dev:web
+```
+
+## Legacy Command Preserved
+
+```powershell
+npm run dev:local-api
+```
+
+## Exact Startup Commands
+
+```powershell
+npm run dev:bootstrap -- --team owner
+npm run dev:bootstrap -- --team alfa
+npm run dev:bootstrap -- --team bravo
+npm run dev:bootstrap -- --team charlie
+npm run dev:bootstrap -- --team delta
+npm run dev:bootstrap -- --team echo
+npm run dev:bootstrap -- --team foxtrot
+npm run dev:bootstrap -- --team golf
+npm run dev:bootstrap -- --team hotel
+```
+
+Codex role example:
+
+```powershell
+npm run dev:bootstrap -- --team alfa --role codex
+```
+
+## Browser Launch Behavior
+
+- `owner` role launches the browser automatically to the selected team's `index.html`.
+- `codex` role skips browser launch.
+- Browser launch happens only after both API and web servers are ready.
+- The Alfa owner launch target is `http://127.0.0.1:5510/index.html`.
+- The Alfa codex browser launch is skipped while using web `5512` and API `5513`.
+- The Charlie launch target is `http://127.0.0.1:5530/index.html` for both `npm run dev:bootstrap -- --team charlie` and `npm run dev:bootstrap -- charlie`.
+- Computed team/role ports override any `.env` or inherited process `GAMEFOUNDRY_SITE_URL` / `GAMEFOUNDRY_API_URL` values loaded before bootstrap startup.
+- Bootstrap runtime sets `GAMEFOUNDRY_SITE_URL=http://127.0.0.1:<webPort>` and `GAMEFOUNDRY_API_URL=http://127.0.0.1:<apiPort>/api` after team/role resolution.
+
+## Files Changed
+
+- `package.json` - updated
+- `dev/scripts/start-dev.mjs` - added
+- `dev/scripts/team-port-config.mjs` - added
+- `dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs` - added
+
+## Validation Summary
+
+All requested targeted validation passed.
diff --git a/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_requirement-checklist.md b/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_requirement-checklist.md
@@ -0,0 +1,32 @@
+# PR_26171_ALFA_009 Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Start from clean `main` | PASS | Reset failed attempt, switched to `main`, pulled fast-forward, confirmed `main...origin/main` was `0 0`, then recreated branch. |
+| Add `npm run dev:bootstrap` | PASS | Added to `package.json`. |
+| Keep `npm run dev:local-api` as legacy alias | PASS | Existing command remains unchanged. |
+| Add `npm run dev:api` | PASS | Added to `package.json`. |
+| Add `npm run dev:web` | PASS | Added to `package.json`. |
+| Create `dev/scripts/start-dev.mjs` | PASS | Added orchestrator. |
+| Create `dev/scripts/team-port-config.mjs` | PASS | Added team/role port resolver. |
+| Support full team names only | PASS | Supported teams are owner, alfa, bravo, charlie, delta, echo, foxtrot, golf, hotel. |
+| Support roles owner/codex | PASS | Role resolver supports owner and codex only. |
+| Codex role uses base ports plus 2 | PASS | Covered by targeted unit test. |
+| Do not use unsupported old team names | PASS | Scan returned no matches in new bootstrap files. |
+| Do not use single-letter public team commands | PASS | Scan returned no matches in new bootstrap files. |
+| Validate unknown team names | PASS | `omega` fails clearly with supported team list. |
+| Validate unknown role names | PASS | `reviewer` fails clearly with supported role list. |
+| Support `--team` argument forwarding | PASS | `npm run dev:bootstrap -- --team charlie` resolves Charlie ports. |
+| Support positional team forwarding | PASS | `npm run dev:bootstrap -- charlie` resolves Charlie ports. |
+| Support positional team/role forwarding | PASS | `npm run dev:bootstrap -- alfa codex` resolves Alfa codex ports and skips browser launch. |
+| Prevent `.env` and process URL port override | PASS | Unit and live startup tests confirm computed team/role ports overwrite loaded or inherited API/site URL port values. |
+| Load environment | PASS | Orchestrator loads `.env` values without overriding existing environment values. |
+| Resolve team ports | PASS | Unit tests cover all teams and both roles. |
+| Start Local API | PASS | `dev:bootstrap` starts the existing Local API server on resolved API port. |
+| Start web server when requested | PASS | `dev:bootstrap` starts web plus API; `dev:web` mode is wired. |
+| Print startup diagnostics | PASS | Diagnostics include mode, team, role, web URL, API URL, environment source, supported teams, and supported roles. |
+| Owner role launches browser automatically | PASS | Live startup validation opened `http://127.0.0.1:5510/index.html` after API and web were ready. |
+| Codex role skips browser launch | PASS | Live startup validation reported `Browser launch: skipped for codex role`. |
+| Wait for both servers before browser launch | PASS | Targeted unit test asserts API ready, web ready, then browser launch order. |
+| Preserve legacy behavior | PASS | `dev:local-api` command unchanged and startup validation passed. |
+| No unrelated cleanup | PASS | Scope limited to package scripts, new dev scripts, targeted tests, and reports. |
diff --git a/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_validation-report.md b/dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_validation-report.md
@@ -0,0 +1,26 @@
+# PR_26171_ALFA_009 Validation Report
+
+## Validation Results
+
+| Command | Result | Notes |
+| --- | --- | --- |
+| `node --check dev/scripts/team-port-config.mjs` | PASS | Syntax valid. |
+| `node --check dev/scripts/start-dev.mjs` | PASS | Syntax valid. |
+| `node --check dev/scripts/start-local-api-server.mjs` | PASS | Legacy startup entrypoint remains valid. |
+| `node --check dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs` | PASS | Test syntax valid. |
+| `node ./dev/scripts/run-node-test-files.mjs dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs dev/tests/dev-runtime/LocalApiStartupLogging.test.mjs` | PASS | 2 targeted files passed; 14 subtests passed. |
+| Unsupported team token scan in new bootstrap files | PASS | No unsupported old team names or single-letter public team commands found in package scripts, bootstrap scripts, or targeted bootstrap tests. |
+| `npm run validate:canonical-structure` | PASS | Canonical repository structure guardrail passed. |
+| `npm run dev:bootstrap -- --team alfa` | PASS | Started with team `alfa`, role `owner`, web `5510`, API `5511`, launched browser to `http://127.0.0.1:5510/index.html`, then process tree was stopped. |
+| `npm run dev:bootstrap -- --team alfa --role codex` | PASS | Started with team `alfa`, role `codex`, web `5512`, API `5513`, skipped browser launch, then process tree was stopped. |
+| `npm run dev:bootstrap -- alfa codex` | PASS | Positional team/role forwarding selected team `alfa`, role `codex`, web `5512`, API `5513`, and skipped browser launch. |
+| `npm run dev:bootstrap -- --team charlie` with inherited stale URL env values | PASS | Started with team `charlie`, role `owner`, web `5530`, API `5531`, launched browser to `http://127.0.0.1:5530/index.html`, and ignored inherited `GAMEFOUNDRY_SITE_URL` / `GAMEFOUNDRY_API_URL` port values before process cleanup. |
+| `npm run dev:bootstrap -- charlie` | PASS | Positional team forwarding selected team `charlie`, web `5530`, API `5531`, and browser target `http://127.0.0.1:5530/index.html`. |
+| `npm run dev:bootstrap -- --team bravo` | PASS | Started with team `bravo`, role `owner`, web `5520`, API `5521`, and browser target `http://127.0.0.1:5520/index.html`. |
+| `npm run dev:bootstrap -- --team omega` | PASS | Failed clearly with supported team list. |
+| `npm run dev:bootstrap -- --team alfa --role reviewer` | PASS | Failed clearly with supported role list. |
+| `npm run dev:local-api` | PASS | Legacy command started and printed legacy startup diagnostics, then process tree was stopped. |
+
+## Notes
+
+The startup-command validations used short-lived process launches and `taskkill /T /F` cleanup after expected diagnostics appeared, so no dev servers were left running. Owner-role validations opened the configured browser target after both server diagnostics were available. Unit coverage verifies loaded `.env` and inherited process URL values are overwritten by computed team/role ports.
diff --git a/dev/reports/codex_changed_files.txt b/dev/reports/codex_changed_files.txt
@@ -1 +1,21 @@
-dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
+# git status --short
+M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_manual-validation-notes.md
+ M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_report.md
+ M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_requirement-checklist.md
+ M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_validation-report.md
+ M dev/scripts/start-dev.mjs
+ M dev/scripts/team-port-config.mjs
+ M dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs
+
+# git ls-files --others --exclude-standard
+(no output)
+
+# git diff --stat
+...team-aware-bootstrap_manual-validation-notes.md |  2 +-
+ ...R_26171_ALFA_009-team-aware-bootstrap_report.md |  6 +-
+ ...9-team-aware-bootstrap_requirement-checklist.md |  3 +-
+ ...A_009-team-aware-bootstrap_validation-report.md |  3 +-
+ dev/scripts/start-dev.mjs                          |  2 +-
+ dev/scripts/team-port-config.mjs                   | 31 ++++++++--
+ dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs  | 71 ++++++++++++++++------
+ 7 files changed, 87 insertions(+), 31 deletions(-)