bw-copilot-resources/docs/troubleshooting.md

Troubleshooting

Resource Does Not Appear

• Run the verify script.
• Confirm the resource exists in the repository.
• Confirm the default discovery link exists.
• Use VS Code Chat Diagnostics to confirm the resource is being loaded.

Changed Resource Does Not Reload

Treat hot reload as likely but not guaranteed. If needed:

• start a new chat session
• restart the Copilot CLI session
• reopen VS Code

Session Start Hook Permission Denied

If you see /bin/sh: .../report-hook-event.sh: Permission denied when a Copilot session starts:

• Pull the latest repo changes and rerun install/update.sh.
• If you need to refresh links and generated config without pulling, rerun install/bootstrap.sh.
• Run install/verify.sh --quick and resolve any missing managed files it reports.
• Start a new Copilot session and confirm ~/.copilot-resources-state/hook-events.log receives a new JSON line.

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 --force only after confirming the replacement is intentional.