# 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.