Add shared port registry workflow and improve scaffold tooling

docs/operations.md

@@ -22,6 +22,31 @@ install/verify.ps1
 
 Scheduled sync will be added on top of the same update and verify entrypoints.
 
+## Port Registry
+
+Session start hooks append events and also synchronize project-local port
+declarations into the machine-wide registry.
+
+Source-of-truth file:
+
+- `~/.copilot-resources-state/project-ports-registry.json`
+
+Project-local declaration file:
+
+- `.local/project-ports.json`
+
+Manual sync for the current workspace:
+
+```bash
+node ~/.copilot-resources/resources/scripts/update-port-registry.mjs
+```
+
+Conflict report:
+
+```bash
+node ~/.copilot-resources/resources/scripts/update-port-registry.mjs --report
+```
+
 ## Audit
 
 ```bash

docs/setup.md

@@ -20,6 +20,7 @@ install/bootstrap.ps1
 - Generates managed VS Code and Copilot CLI MCP config files from the tracked templates in `config/mcp/`
 - Writes a managed Copilot CLI environment fragment and sources it from the shell or PowerShell profile
 - Creates `.local/mcp.local.jsonc` from the tracked example if the machine-local MCP override file does not exist yet
+- Creates a project-local port declaration file at `.local/project-ports.json` on first session start if it does not exist yet
 - Writes a local install-state file outside the repository
 
 ## Optional Settings

docs/troubleshooting.md

@@ -31,6 +31,22 @@ session starts:
 The shared hook now invokes the shell script through `bash`, so the session
 start hook no longer depends on the script file itself being executable.
 
+## Port Registry Not Updating
+
+If `~/.copilot-resources-state/project-ports-registry.json` is missing or stale:
+
+- Run `install/verify.sh --quick` and confirm the hook script paths exist.
+- Run `node ~/.copilot-resources/resources/scripts/update-port-registry.mjs`.
+- Check `~/.copilot-resources-state/project-ports-errors.log` for parse or
+	write failures.
+
+If `.local/project-ports.json` contains invalid JSON, fix the JSON and re-run
+the sync command.
+
+To review collisions and recommended project changes:
+
+- Run `node ~/.copilot-resources/resources/scripts/update-port-registry.mjs --report`.
+
 ## Publish Refused To Overwrite
 
 The publish scripts stop on collisions by default. Use a new name or rerun with