[WIP] update docs to reflect checks

.claude/skills/docs-style/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: docs-style
+description: Style guidelines for writing and updating documentation. Use when writing new docs, updating existing docs, or reviewing docs for quality.
+---
+
+# Docs Style Guide
+
+## Principles
+
+- **Be concise** — no filler. Make it easy to find what you're looking for
+- **Task-oriented** — frame around what the user is trying to do, not what the product can do
+- **Progressive disclosure** — guide from introduction to advanced use-cases. Don't throw users into the deep end
+- **Real examples over abstract explanations** — show, don't describe
+- **Code snippets must be copy-pasteable** — no placeholder values that silently break, no missing imports
+- **Prerequisites up front** — don't surprise the user halfway through
+- **One topic per page** — if you're covering two things, split it
+- **Link, don't repeat** — reference other docs instead of duplicating content
+- **Scannable headings** — skimming the TOC should reveal the page structure
+- **Show expected output** — after a step, tell the user what they should see
+- **Consistent terminology** — pick one term for a concept, use it everywhere
+- **Screenshots/GIFs for key product features** — use visuals when they teach faster than text
+- **Know which type of doc you're writing** — a tutorial (learning), a how-to (completing a task), a reference (looking something up), or an explanation (understanding why). Don't mix them in one page
+- **Tutorials should be completable** — a user following every step should end up with a working result, every time
+- **Reference docs should be exhaustive and consistent** — cover everything, use the same structure for every entry
+
+## Tone
+
+- **Don't be patronizing** — the reader is a developer. Don't tell them when to use something in a "when to use X vs Y" comparison table. If the distinction matters, state it plainly at the top of the relevant section in a sentence, then move on.
+- **Respect the reader's time** — open with the command or code, not a paragraph explaining what they're about to see. Lead with the thing, then explain.
+- **No personality** — the docs aren't a character. Don't try to be warm, clever, or endearing. No "Let's dive in!", no "The Magic of...", no "Pro Tip:", no emoji in headings. Developers see through it instantly and it reads like marketing copy wearing a docs costume. Just be direct and clinical. The docs serve information, they don't have a relationship with the reader.
+- **Inline guidance over callout boxes** — prefer weaving tips into the prose rather than using `<Tip>`, `<Info>`, `<Warning>`, etc. These components break reading flow and look heavy when overused. Reserve them for truly critical warnings (e.g. data loss, security). One per page is a good ceiling; zero is often fine.
+- **Examples should feel real** — use realistic file paths, realistic prompts, realistic tasks. Not `> Tell me about the CLI` but `> @tests/auth.test.ts This test started failing after the last migration`.
+- **Examples earn their place** — don't add "Example: Doing X" sections that are just English prompts in a code block. Examples are valuable when they demonstrate non-obvious syntax, flags, piping, or configuration. If the reader could figure it out from the rest of the page, skip the example.
+- **No "Next Steps" sections** — don't end pages with a "Next Steps" or "What's Next?" section with CardGroups linking to other pages. The sidebar navigation already does this. If a link to another page is relevant, put it inline where the context is, not in a generic footer.
+- **Page title = sidebar title** — the `title` in frontmatter should match the sidebar label. Drop `sidebarTitle` unless there's a genuine reason for them to differ. Don't stuff extra context into the page title (e.g., "Continue CLI (cn) Overview" → "Overview").
+- **No subtitle/description in frontmatter** — don't use the `description` field. The opening paragraph of the page should provide whatever context is needed. Metadata subtitles add clutter and duplicate what the prose already says.
+
+## Headings
+
+- **Direct and plain, not clever or engaging** — headings should just say what the section is about. Verbs are fine when they're direct ("Resume previous sessions"). Gerund phrases that sound like tutorial chapter titles are not ("Giving Context with @" → "`@` Context"). The test isn't grammatical — it's tonal. If it sounds like a friendly narrator is walking you through something, rewrite it. If it just plainly states what the section covers, it's good.
+- **Scannable over descriptive** — skimming the TOC should reveal the page structure at a glance. Keep headings short and plain.

docs/agents/overview.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Cloud Agents & Continuous AI"
 description: "Standardized Cloud Agent workflows that combine prompts, rules, and tools to complete specific, repeatable tasks"
-sidebarTitle: "Overview"
+sidebarTitle: "Agents"
 ---
 
 ## What are Cloud Agents?

docs/cli/configuration.mdx

@@ -0,0 +1,77 @@
+---
+title: "Configuration"
+---
+
+`cn` resolves its configuration (models, MCP servers, rules, etc.) from several sources, in this order:
+
+1. **`--config` flag** — a file path or hub assistant slug passed at launch
+2. **Saved config** — the last-used configuration, persisted across sessions
+3. **Default** — your first assistant from [Continue](https://continue.dev), or `~/.continue/config.yaml` if you're not logged in
+
+## `--config` flag
+
+Point `cn` at a local YAML file or a hub assistant:
+
+```bash
+# Local file
+cn --config ./my-config.yaml
+
+# Hub assistant
+cn --config my-org/my-assistant
+```
+
+This overrides any saved preference for the current session.
+
+## Switching at runtime
+
+Use `/config` inside a TUI session to switch between available configurations:
+
+```
+> /config
+```
+
+This shows your available assistants and local configs. The selection is saved for next time.
+
+## `config.yaml`
+
+If you're not logged in to Continue, `cn` looks for `~/.continue/config.yaml`. This file uses the same format as the IDE extensions — see [config.yaml reference](/customize/deep-dives/configuration) for the full schema.
+
+## CLI-specific flags
+
+Several flags inject configuration at launch without editing a file:
+
+```bash
+# Add models from the hub
+cn --model my-org/claude-sonnet
+
+# Add MCP servers from the hub
+cn --mcp my-org/github-mcp
+
+# Add rules (file path, hub slug, or inline string)
+cn --rule ./rules/style.md
+cn --rule my-org/code-review-rules
+cn --rule "Always use TypeScript strict mode"
+
+# Load an agent file from the hub
+cn --agent my-org/pr-reviewer
+```
+
+All of these are repeatable — pass them multiple times to add multiple items.
+
+## Organization
+
+If you belong to multiple organizations on Continue, use `--org` to specify which one:
+
+```bash
+cn --org my-team -p "Review this PR"
+```
+
+In TUI mode, `/config` lets you switch organizations interactively.
+
+## Secrets
+
+Store sensitive values (API keys, tokens) in [Continue → Settings → Secrets](https://continue.dev/settings/secrets). Reference them in config with:
+
+```yaml
+${{ secrets.MY_API_KEY }}
+```

docs/cli/headless-mode.mdx

@@ -0,0 +1,86 @@
+---
+title: "Headless Mode"
+---
+
+Run `cn -p "your prompt"` to execute a single task without an interactive session. The agent runs to completion and prints its response to stdout.
+
+```bash
+cn -p "Generate a conventional commit message for the staged changes"
+```
+
+## Piping
+
+Pipe data into `cn` to include it as context:
+
+```bash
+git diff --staged | cn -p "Write a commit message for this diff"
+cat error.log | cn -p "Explain what went wrong"
+curl -s https://api.example.com/health | cn -p "Is this healthy?"
+```
+
+Pipe the output into other tools:
+
+```bash
+cn -p "Generate a commit message" | git commit -F -
+cn -p "List all TODO comments in src/" --silent > todos.txt
+```
+
+## Output options
+
+| Flag | Effect |
+|------|--------|
+| `--silent` | Strip `<think>` tags and excess whitespace from output |
+| `--format json` | Output structured JSON |
+
+`--silent` is useful when piping output into another program. `--format json` is useful for parsing results programmatically.
+
+## Tool permissions
+
+In headless mode, tools that would normally prompt for approval (`ask` permission) are automatically excluded — there's no one to approve them. To enable write operations, explicitly allow them:
+
+```bash
+# Allow the agent to write files
+cn -p "Fix the type errors in src/" --allow Write --allow Edit
+
+# Allow everything
+cn -p "Set up the project" --allow "*"
+```
+
+See [tool permissions](/cli/tool-permissions) for the full policy system.
+
+## Authentication in CI
+
+Set `CONTINUE_API_KEY` instead of running `cn login`:
+
+```bash
+export CONTINUE_API_KEY=your-key-here
+cn -p "Review the PR for security issues"
+```
+
+Get an API key from [Continue → Settings → API Keys](https://continue.dev/settings/api-keys). Store it as a secret in your CI provider.
+
+## Resume in headless mode
+
+Resume a previous session without interactive input:
+
+```bash
+cn -p --resume
+```
+
+This replays the previous session's history, which can be useful for inspecting past results in automation.
+
+## Examples
+
+```bash
+# Git hooks
+cn -p "Review staged changes for obvious bugs" --silent
+
+# CI pipeline — allow file writes for auto-fix
+cn -p "Fix all ESLint errors in src/" --allow Write --allow Edit --allow Bash
+
+# Generate docs from code
+cn -p "@src/api/ Generate OpenAPI documentation for these endpoints" --silent > api-docs.yaml
+
+# Use a specific assistant
+cn -p "Triage this error log" --config my-org/error-triage-assistant
+```

docs/cli/install.mdx

@@ -1,140 +1,46 @@
 ---
-title: "Install Continue CLI"
-description: "Get Continue CLI installed and configured for command-line AI coding assistance and automation"
-sidebarTitle: "Install"
+title: "Install"
 ---
 
 import { OSAutoDetect } from '/snippets/OSAutoDetect.jsx'
 import CLIInstall from '/snippets/cli-install.mdx'
 
 <OSAutoDetect />
 
-<iframe
-  width="100%"
-  height="400"
-  src="https://www.youtube.com/embed/vm9RcP9xM4o"
-  title="Install Continue CLI"
-  frameborder="0"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowfullscreen
-></iframe>
-
-## Installation
-
 <CLIInstall />
 
-## Two Ways to Use Continue CLI
-
-<Info>
-  **Quick Overview**: Continue CLI works in two modes - TUI for interactive
-  conversations or headless for automated commands.
-</Info>
-
-<Tabs>
-<Tab title="TUI Mode">
-**Interactive development sessions**
-
-Start a conversation with AI in your terminal:
-
-```bash
-cn
-> @src/app.js Generate unit tests for this component
-```
-
-Perfect for exploration, debugging, and iterative development.
-
-</Tab>
-
-<Tab title="Headless Mode">
-**Automation and scripting**
-
-Single commands that return results:
+Verify the installation:
 
 ```bash
-cn -p "Generate a commit message for current changes"
-cn -p "Review the last 5 commits for issues"
+cn --version
 ```
 
-Perfect for CI/CD, git hooks, and automated workflows.
-
-</Tab>
-</Tabs>
-
-## Setup
-
-<Tabs>
-<Tab title="cn TUI Mode">
+## Authentication
 
-For interactive development and exploration:
+### Log in with Continue
 
-<Steps>
-<Step title="Login to Continue CLI">
 ```bash
 cn login
 ```
-This will open your browser to authenticate with Continue Mission Control.
-</Step>
 
-<Step title="Test TUI Mode">
-Start an interactive session:
-```bash
-cn
-```
+This opens your browser to authenticate with [Continue](https://continue.dev). Once authenticated, `cn` can use your configured assistants, models, and MCP servers from the platform.
 
-Try asking a question:
+### API key (headless / CI)
 
-```
-> Tell me about the CLI
-```
+For automation environments where there's no browser, set the `CONTINUE_API_KEY` environment variable:
 
-</Step>
-</Steps>
-</Tab>
-<Tab title="cn Headless Mode">
-
-For automation workflows and scripting:
-
-<Steps>
-<Step title="Get API Key for Automation">
-For automation workflows, get an API key:
-1. Visit [Continue Mission Control API Keys](https://continue.dev/settings/api-keys)
-2. Click **"+ New API Key"**
-3. Copy the API key immediately (you won't see it again!)
-4. Login using your Continue account
-</Step>
-
-<Step title="Add Secrets for Workflows">
-Store secure credentials for CLI workflows:
-1. Visit [Continue Mission Control Secrets](https://continue.dev/settings/secrets)
-2. Add your API keys and sensitive data
-3. Reference in configurations with `${{ secrets.SECRET_NAME }}`
-</Step>
-
-<Step title="Test Headless Mode">
-Try headless mode for automation:
 ```bash
-cn -p "Generate a conventional commit message for the current git changes"
+export CONTINUE_API_KEY=your-key-here
+cn -p "your prompt"
 ```
-</Step>
-</Steps>
-</Tab>
-</Tabs>
-
-## What's Next?
 
-<CardGroup cols={2}>
-<Card title="Quick Start Guide" icon="rocket" href="/cli/quick-start">
-  Learn basic usage with practical examples
-</Card>
+Get an API key from [Continue → Settings → API Keys](https://continue.dev/settings/api-keys).
 
-<Card title="Create your first workflow" icon="gear" href="/guides/posthog-github-continuous-ai">
-  Build automated workflows with Continue CLI
-</Card>
-</CardGroup>
+### Local API key
 
-## Getting Help
+If you don't want to use Continue, you can use an Anthropic API key directly. On first launch, `cn` will prompt you to choose between logging in with Continue or entering an Anthropic API key.
 
-If you encounter issues:
+## Requirements
 
-- Ask for help in [our discussions](https://github.com/continuedev/continue/discussions)
-- Report bugs on [GitHub](https://github.com/continuedev/continue)
+- **Node.js 20+** — needed for the npm install path. The shell installer bundles its own runtime.
+- A [Continue](https://continue.dev) account, or an Anthropic API key.