docs: add a troubleshooting guide for MCP server startup failures (closes #258)

[dchaudhari7177]

Closes #258.

Adds docs/troubleshooting.md covering the four failure modes from the issue — server fails to start, scan times out, tool listing returns empty, rate limiting — plus what to include when reporting. Linked from the README docs list.

⚠️ Two corrections to the suggested content

The issue's outline named flags that do not exist, so I documented what actually works instead. Both were checked against src/ rather than assumed:

1. There is no --timeout flag on scan/score/test. --timeout <ms> is registered only on demo (src/commands/demo.ts:80). The scan timeout is the per-target timeoutMs field in a target config file passed via --target, defaulting to 10 s in runner.ts:119. The guide shows a worked config for both local-process and http adapters.

2. There is no --verbose flag anywhere in the CLI. I enumerated every registered .option( across src/commands/ to confirm. The guide points at --format json instead, which carries the per-check evidence and any captured fatalError.

Documenting either flag as suggested would have sent users to a command that errors out.

Other content notes

• The 10 s default is worth stating plainly: an npx cold start alone can exceed it, so the guide suggests warming the package cache before blaming the server.
• The empty-tool-listing section shows env with ${VAR} expansion in the target config, so required API keys are reproducible without writing secrets into the file.
• Rate limiting is framed as usually the upstream API a server wraps, with skipInvoke: true as the way to check capability listings without spending quota.
• The "don't run as root" advice is framed as a security point rather than generic caution — running an untrusted MCP server as root hands it root, which is precisely the risk this tool measures.

Every flag and config field referenced (--target, --format, --invoke-tools, --interval, timeoutMs, env, skipInvoke) was verified present in src/ before being written down.

Docs-only change.

🤖 Generated with Claude Code

[KryptosAI]

Merged after a README rebase onto current main (conflict with the shorter docs list). Thank you — docs/troubleshooting.md is on main.