Add shared port registry workflow and improve scaffold tooling

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