draft-troubleshooting

# Draft troubleshooting page Draft a troubleshooting page that helps users diagnose and fix common issues. ## Workflow Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **troubleshooting template** at `.agents/templates/troubleshooting.md`. ## Frontmatter description One to two sentences, 50-160 characters, naming the symptoms covered rather than the act of troubleshooting. - ✅ `Fix sign-in failures, failed conversation resumes, and update problems in the Warp Agent CLI.` - ❌ `Troubleshooting information for common problems.` See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. ## Content type rules These rules are specific to troubleshooting pages (from the "Drafting by content type" section of `AGENTS.md`): - Use the problem or error message as the header — this helps with search. - Group related issues under broader category headers (e.g., "SSH", "Shells"). - Lead with the symptom — the reader arrived because something broke. Don't make them read context before getting to the fix. - Provide workarounds when a fix isn't available. - Link to related troubleshooting pages and support channels. - Include workarounds even when no fix exists — documenting a known issue without a workaround still saves the user time searching. - Title convention: "Troubleshooting [feature]" or "Error: [error name]" - Apply the tone rules in AGENTS.md → Voice & tone: lead with the fix, not framing; no marketing buzzwords or meta-openers. Delete any category or symptom section you don't have real content for — a short page is a finished page. ## Heading case All headings (H1–H4) must use **sentence case**: capitalize only the first word and proper feature names. - ✅ `# Troubleshooting environments` - ✅ `## Agent fails to start` - ❌ `# Troubleshooting Environments` - ❌ `## Agent Fails To Start` ## Existing examples Read 2-3 of these strong examples to match the existing pattern: - `src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx` - `src/content/docs/agents/cli/oz-cli/troubleshooting.mdx`