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

.continue/checks/stale-comments.md

@@ -0,0 +1,92 @@
+---
+name: Stale & Misleading Comments
+description: Flag comments that no longer match the code they describe.
+---
+
+# Stale & Misleading Comments
+
+## Context
+
+In a fast-moving TypeScript monorepo with many contributors, comments frequently fall out of sync with the code they describe. A misleading comment is worse than no comment — it actively misdirects developers and causes bugs. This check catches comments that contradict, no longer match, or misrepresent adjacent code.
+
+## What to Check
+
+### 1. Comments That Contradict the Code
+
+Look for inline comments (`//`) and block comments (`/* */`) where the description no longer matches what the code actually does.
+
+**BAD — comment says "retry" but code doesn't retry:**
+
+```typescript
+// Retry the request on failure
+const result = await fetch(url);
+```
+
+**BAD — comment describes old parameter list:**
+
+```typescript
+// Takes a model name and returns the provider
+function getProvider(config: ModelConfig, context: ContextManager) {
+```
+
+**GOOD — comment matches behavior:**
+
+```typescript
+// Resolve provider from full model configuration and context
+function getProvider(config: ModelConfig, context: ContextManager) {
+```
+
+### 2. TODO/FIXME/HACK Comments for Completed Work
+
+Flag TODO, FIXME, and HACK comments where the described work appears to already be done in the surrounding code.
+
+**BAD — TODO says to add validation, but validation exists below:**
+
+```typescript
+// TODO: add input validation
+if (!input || typeof input !== "string") {
+  throw new Error("Invalid input");
+}
+```
+
+### 3. Commented-Out Code With Misleading Annotations
+
+Flag blocks of commented-out code that have an annotation suggesting they're still needed, when the functionality has been replaced or removed.
+
+**BAD:**
+
+```typescript
+// Keep this for fallback support
+// const oldProvider = new LegacyProvider(config);
+// oldProvider.initialize();
+const provider = new ModernProvider(config);
+```
+
+### 4. JSDoc / Docstrings That Mismatch Signatures
+
+Check that `@param`, `@returns`, and `@throws` tags in JSDoc comments match the actual function signature — correct parameter names, types, and return type.
+
+**BAD — documents a param that doesn't exist:**
+
+```typescript
+/**
+ * @param modelName - The model to use
+ * @returns The completion text
+ */
+async function complete(config: AutocompleteConfig): Promise<Result> {
+```
+
+## Key Files to Check
+
+- `core/` — shared logic across all extensions
+- `extensions/vscode/src/` — VS Code extension source
+- `extensions/cli/src/` — CLI extension source
+- `gui/src/` — React GUI components
+- `packages/` — shared npm packages
+
+## Exclusions
+
+- License headers and copyright notices
+- Comments in generated files, vendored code, or `node_modules`
+- Comments in test files that describe expected (intentionally wrong) behavior
+- Commented-out code in test fixtures used as test data

README.md

@@ -41,12 +41,10 @@ Continue runs agents on every pull request as GitHub status checks. Each agent i
 name: Security Review
 description: Review PR for basic security vulnerabilities
 ---
-
 Review this PR and check that:
-
-- No secrets or API keys are hardcoded
-- All new API endpoints have input validation
-- Error responses use the standard error format
+  - No secrets or API keys are hardcoded
+  - All new API endpoints have input validation
+  - Error responses use the standard error format
 ```
 
 ## Install CLI