[Docs] Common errors and solutions guide

[mikejmorgan-ai]

Problem

Users hit errors and don't know what they mean or how to fix them.

Solution

Create docs/TROUBLESHOOTING.md with common errors:

Content Needed

API Errors

Error	Cause	Fix
ANTHROPIC_API_KEY not set	No API key configured	Run export ANTHROPIC_API_KEY=sk-... or cortex wizard
Rate limit exceeded	Too many requests	Wait 60 seconds or use --offline
Invalid API key	Key expired or wrong	Get new key from console.anthropic.com

System Errors

Error	Cause	Fix
apt lock held	Another process using apt	sudo killall apt apt-get or wait
Permission denied	Need sudo	Run with sudo cortex install X
Package not found	Typo or not in repos	Check spelling, try cortex search X

Network Errors

Error	Cause	Fix
Connection timeout	Network issue	Check internet, try --offline
SSL certificate error	Corporate proxy	Set HTTP_PROXY env var

Acceptance Criteria

• Create docs/TROUBLESHOOTING.md
• Cover top 15 error scenarios
• Plain English explanations
• Copy-paste fix commands
• Link from main README

## Bounty: $15 now (+$15 match after funding)

Total: $30 when we close our funding round.

[MChandrahas]

Hi, I would like to work on this issue. Please assign it to me.

[mikejmorgan-ai]

Hi, I would like to work on this issue. Please assign it to me.

Assigned

[MChandrahas]

I noticed PR #280 is linked to this issue, but it currently has failing CI/CD checks and several critical issues flagged by the code review bot (unsafe commands, incorrect environment variables, etc.).

Would you like me to take over this task and submit a corrected version that addresses these feedback points?

[mikejmorgan-ai]

I noticed PR #280 is linked to this issue, but it currently has failing CI/CD checks and several critical issues flagged by the code review bot (unsafe commands, incorrect environment variables, etc.).

Would you like me to take over this task and submit a corrected version that addresses these feedback points?

yes