squirrelscan · nc9 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/cli/audit.mdx b/cli/audit.mdx
@@ -31,8 +31,10 @@ squirrel audit <url> [options]
 | `--debug` | | Enable debug logging | `false` |
 | `--trace` | | Enable performance tracing | `false` |
 | `--project-name` | `-n` | Project name (overrides config and prompts) | auto |
-| `--publish` | `-p` | Publish report to reports.squirrelscan.com | `false` |
+| `--publish` | `-p` | Publish report to reports.squirrelscan.com (costs 2 credits) | `false` |
 | `--visibility` | | Visibility: `public`, `unlisted`, `private` | `public` |
+| `--yes` | `-y` | Skip confirmation prompts (e.g. cloud credit spend) | `false` |
+| `--render` | | Render pages with a cloud browser for this run ([uses credits](/guides/browser-rendering); requires login) | `false` |
 
 ### Coverage Modes
 

diff --git a/cli/auth.mdx b/cli/auth.mdx
@@ -1,9 +1,9 @@
 ---
 title: "auth"
-description: "Authenticate with squirrelscan for publishing reports"
+description: "Authenticate with squirrelscan for cloud features and publishing"
 ---
 
-The `auth` command manages authentication for publishing reports to [reports.squirrelscan.com](https://reports.squirrelscan.com).
+The `auth` command manages authentication for [cloud features](/cloud) - cloud rules, browser rendering, and publishing reports. Logging in grants 1,000 free credits on new accounts.
 
 ## Subcommands
 

diff --git a/cli/credits.mdx b/cli/credits.mdx
@@ -0,0 +1,63 @@
+---
+title: "credits"
+description: "Show cloud credit balance and feature pricing"
+---
+
+The `credits` command shows your [cloud credit](/cloud/credits) balance, plan, and current feature pricing.
+
+## Usage
+
+```bash
+squirrel credits [options]
+```
+
+Requires login - run [`squirrel auth login`](/cli/auth) first.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+
+## Example
+
+```bash
+squirrel credits
+```
+
+```
+Plan:    starter
+Balance: 2340 credits (2000 monthly + 340 purchased)
+         monthly credits reset 2026-07-08
+
+Pricing:
+  adblock_detect         5 per run
+  ai_parse               1 per page
+  authority_signals      1 per page
+  dead_links             1 per 100 urls
+  render                 2 per page
+  report_publish         2 per report
+  site_type              5 per run
+  ...
+
+Top up: https://squirrelscan.com/account/credits
+```
+
+JSON output:
+
+```bash
+squirrel credits --json
+```
+
+```json
+{
+  "balance": { "total": 2340, "monthly": 2000, "pack": 340, "periodEnd": "2026-07-08T00:00:00Z" },
+  "plan": { "id": "starter", "name": "starter" },
+  "pricing": { "ai_parse": { "cost": 1, "per": 1, "unit": "page" } }
+}
+```
+
+## Related
+
+- [Credits & Pricing](/cloud/credits) - how credits work and what features cost
+- [auth](/cli/auth) - log in to enable cloud features
diff --git a/cli/index.mdx b/cli/index.mdx
@@ -20,7 +20,8 @@ Commands that operate on websites and projects:
 | [`init`](/cli/init) | Create squirrel.toml config file |
 | [`config`](/cli/config) | View and modify configuration |
 | [`feedback`](/cli/feedback) | Send feedback to squirrelscan team |
-| [`auth`](/cli/auth) | Authentication for publishing |
+| [`auth`](/cli/auth) | Authentication for cloud features and publishing |
+| [`credits`](/cli/credits) | Show cloud credit balance and pricing |
 
 ### Self-Management Commands
 

diff --git a/cloud/credits.mdx b/cloud/credits.mdx
@@ -0,0 +1,76 @@
+---
+title: "Credits & Pricing"
+description: "How cloud credits work, what each feature costs, and how to control spend"
+icon: "coins"
+---
+
+Cloud features are priced in **credits** - small integers, not dollars. Local audits never cost credits.
+
+## Getting credits
+
+| Source | Credits | Notes |
+|--------|---------|-------|
+| Free plan | 500/month | Every account, no card required; resets each calendar month |
+| Starter plan ($19/mo) | 5,000/month | Resets each billing period; unused monthly credits expire |
+| Credit top-up (min $10) | 100 per $1 | Paid plan only; pick any amount; never expire |
+
+Monthly credits are spent before purchased top-up credits. Subscribe and top up from the **Billing & Credits** page in the [dashboard](/dashboard).
+
+## Checking your balance
+
+```bash
+squirrel credits
+```
+
+```
+Plan:    starter
+Balance: 2340 credits (2000 monthly + 340 purchased)
+         monthly credits reset 2026-07-08
+
+Pricing:
+  ai_parse               1 per page
+  site_type              5 per run
+  ...
+
+Top up: https://squirrelscan.com/account/credits
+```
+
+`squirrel auth status` also shows your balance, and the start banner of every audit shows the estimated spend against it.
+
+## Pricing
+
+| Feature | Cost | Used by |
+|---------|------|---------|
+| Report publishing | 2 per report | `squirrel audit --publish` |
+| AI page analysis | 1 per page | [`ai/llm-parsability`](/rules/ai/llm-parsability), [`ai/page-type-match`](/rules/ai/page-type-match) |
+| Site type detection | 5 per audit | [`ai/site-type`](/rules/ai/site-type) |
+| Authority signals | 1 per page | [`eeat/authority-signals`](/rules/eeat/authority-signals) |
+| Adblock/privacy check | 5 per audit | All three [adblock rules](/rules/adblock) share one check |
+| Dead link checking | 1 per 100 URLs | [`links/dead-links`](/rules/links/dead-links) |
+| Browser rendering | 2 per page | [Cloud rendering](/cloud/rendering) |
+| Keyword gaps | 25 per audit | [`gaps/keywords`](/rules/gaps/keywords) (opt-in) |
+| Content gaps | 25 per audit | [`gaps/content`](/rules/gaps/content) (opt-in) |
+| Issue enrichment | 1 per issue | AI recommendations in the dashboard |
+
+A typical 50-page audit with the default cloud rules costs around **60-110 credits** depending on how many pages the per-page rules analyze.
+
+## Spend controls
+
+Three guardrails keep an audit from spending more than you expect:
+
+```toml squirrel.toml
+[cloud]
+max_credits_per_audit = 200   # hard cap per audit; 0 = unlimited
+confirm_threshold = 50        # estimates above this prompt before spending
+enabled = true                # master switch for all cloud features
+```
+
+- **Per-audit cap** - if the estimate exceeds `max_credits_per_audit`, work is truncated deterministically at the cap and remaining rules report `skipped` with reason `credit-cap-reached`.
+- **Confirmation prompt** - in a terminal, an estimate above `confirm_threshold` asks before proceeding. Use `--yes` to skip prompts (e.g. in CI or agent workflows). Non-interactive runs proceed without prompting, bounded by the cap.
+- **Master switch** - `enabled = false` turns off all cloud calls for the project.
+
+See the [cloud configuration reference](/configuration/cloud) for all options.
+
+## When credits run out
+
+Nothing breaks. Cloud rules report `skipped` with reason `insufficient-credits`, the audit completes with all local rules, and you see a single warning with a top-up link. If a cloud service fails entirely after you were charged, the charge is automatically refunded.
diff --git a/cloud/index.mdx b/cloud/index.mdx
@@ -0,0 +1,65 @@
+---
+title: "Cloud Overview"
+description: "What squirrelscan cloud adds on top of free local audits"
+icon: "cloud"
+---
+
+Local audits are **free and unlimited, forever**. The cloud exists to do only what your machine can't:
+
+- **AI analysis** - page classification, site-type detection, parsability scoring, authority assessment
+- **Browser rendering** - audit JavaScript-heavy sites with a real headless browser
+- **Shared data** - full adblock/privacy filter lists, a global dead-link cache, search demand data
+- **Publishing & teams** - publish reports, track issues over time, share with your team in the [dashboard](/dashboard)
+
+Cloud features are priced in [credits](/cloud/credits). Every new account gets **1,000 free credits** - no card required.
+
+## Getting started
+
+```bash
+squirrel auth login
+```
+
+That's it. Your next `squirrel audit` automatically includes the [cloud rules](/cloud/rules) - results merge into the same report alongside the local rules.
+
+```bash
+squirrel credits   # check your balance and pricing
+```
+
+## How cloud rules behave
+
+- **Logged in** - cloud rules run as part of the audit. Calls are batched during a dedicated cloud phase, and spend is shown in the audit summary.
+- **Logged out** - cloud rules report `skipped` with a hint to log in. Your audit still completes; nothing fails.
+- **Out of credits or service down** - same thing: rules skip, the audit completes, you see a one-line warning.
+
+You stay in control of spend with a per-audit credit cap and a confirmation prompt for larger runs. See [Credits & Pricing](/cloud/credits#spend-controls).
+
+## What's in the cloud
+
+<CardGroup cols={2}>
+  <Card title="Cloud Rules" icon="list-checks" href="/cloud/rules">
+    The audit rules powered by cloud services, and what each costs
+  </Card>
+  <Card title="Credits & Pricing" icon="coins" href="/cloud/credits">
+    How credits work, full pricing, and spend controls
+  </Card>
+  <Card title="Browser Rendering" icon="globe" href="/cloud/rendering">
+    Render JavaScript-heavy sites with a cloud headless browser
+  </Card>
+  <Card title="Dashboard" icon="layout-dashboard" href="/dashboard">
+    Published reports, issue tracking, and billing at app.squirrelscan.com
+  </Card>
+</CardGroup>
+
+## Publishing reports
+
+Publishing a report to the dashboard costs **2 credits** and gives you a shareable URL plus issue history for the site:
+
+```bash
+squirrel audit https://example.com --publish
+```
+
+See [Reports](/reports) for publishing details.
+
+## Privacy
+
+Cloud analysis works on slim page summaries - URL, title, and a short text excerpt - never your full raw HTML. Third-party data providers are proxied through our API; your pages are never sent to them directly.
diff --git a/cloud/rendering.mdx b/cloud/rendering.mdx
@@ -0,0 +1,38 @@
+---
+title: "Browser Rendering"
+description: "How cloud browser rendering works under the hood"
+icon: "globe"
+---
+
+By default the crawler fetches pages with plain HTTP - fast, free, and accurate for server-rendered sites. Sites that build their content with JavaScript (SPAs, client-side frameworks) can look nearly empty to a plain fetch, which skews every content rule.
+
+Cloud browser rendering fixes that: each page is loaded in a **real headless browser** in the cloud, and the fully rendered DOM is returned to your local crawler. Everything downstream - parsing, rules, reports - works exactly as it does with plain HTTP, just on the post-JavaScript HTML.
+
+<Note>Looking for setup instructions? See the [browser rendering guide](/guides/browser-rendering). This page explains how the service behaves.</Note>
+
+## Cost
+
+**2 credits per page rendered.** A 100-page crawl with rendering costs 200 credits, so mind your [per-audit cap](/cloud/credits#spend-controls) - the default cap of 200 covers rendering for about 100 pages and nothing else. The crawl progress line shows the running spend:
+
+```
+Crawling (cloud-rendered) 34/100 · ~68 credits
+```
+
+## Fallback behavior
+
+Rendering is best-effort and degrades gracefully:
+
+- **Single page fails or times out** - that page falls back to plain HTTP; the crawl continues rendering the rest.
+- **Out of credits, auth error, or service outage** - the crawler switches permanently to plain HTTP for the remainder of the crawl, prints a one-line warning, and notes the fallback in the report metadata.
+
+A render failure never fails the audit.
+
+## When to use it
+
+| Site | Recommendation |
+|------|----------------|
+| Server-rendered (most CMS, SSR frameworks, static sites) | Plain HTTP (default) - rendering adds cost, not accuracy |
+| Client-side SPA (React/Vue/Angular without SSR) | Browser rendering |
+| Mixed - mostly SSR with a few JS-dependent pages | Try plain HTTP first; if content rules report thin/missing content on pages you know have content, switch |
+
+A quick tell: run `squirrel audit` normally, and if word counts or headings look implausibly low on pages that render fine in your browser, the site needs rendering.
diff --git a/cloud/rules.mdx b/cloud/rules.mdx
@@ -0,0 +1,68 @@
+---
+title: "Cloud Rules"
+description: "Audit rules powered by cloud services - what they check and what they cost"
+icon: "list-checks"
+---
+
+Cloud rules are regular audit rules that need data your machine doesn't have - AI models, full filter lists, search demand data, or a shared link cache. They run automatically when you're [logged in](/cloud) and report `skipped` when you're not.
+
+## The rules
+
+| Rule | What it checks | Cost |
+|------|----------------|------|
+| [`ai/llm-parsability`](/rules/ai/llm-parsability) | How well LLMs can parse and understand each page | 1 credit per page |
+| [`ai/page-type-match`](/rules/ai/page-type-match) | AI-classified page type agrees with declared structured data | 1 credit per page (shared with parsability) |
+| [`ai/site-type`](/rules/ai/site-type) | Classifies the overall site type (blog, ecommerce, saas, docs, ...) | 5 credits per audit |
+| [`eeat/authority-signals`](/rules/eeat/authority-signals) | Per-page authorship, citations, and outbound references | 1 credit per page |
+| [`adblock/element-hiding`](/rules/adblock/element-hiding) | Elements hidden by EasyList cosmetic rules | 5 credits per audit, shared |
+| [`adblock/blocked-links`](/rules/adblock/blocked-links) | Links and resources ad blockers would block | shared with above |
+| [`adblock/privacy-blocked`](/rules/adblock/privacy-blocked) | Trackers that EasyPrivacy filter lists would block | shared with above |
+| [`links/dead-links`](/rules/links/dead-links) | External links verified through a shared global cache | 1 credit per 100 URLs |
+| [`gaps/keywords`](/rules/gaps/keywords) | Keywords competitors rank for that you don't | 25 credits per audit, **opt-in** |
+| [`gaps/content`](/rules/gaps/content) | Topic clusters with search demand you don't cover | 25 credits per audit, **opt-in** |
+
+The three adblock rules share a single 5-credit blocklist check per audit - enabling all three costs the same as enabling one.
+
+The two gap-analysis rules are **disabled by default** because of their cost. Enable them explicitly:
+
+```toml squirrel.toml
+[rules]
+enable = ["gaps/keywords", "gaps/content"]
+```
+
+## How they run
+
+Cloud rules match rule filters like any other rule - `enable = ["*"]` (the default) includes them. During an audit, a dedicated cloud phase batches all the required service calls, then rules read the results. You'll see the estimate in the start banner and the actual spend per service in the audit summary:
+
+```
+☁ Cloud: 67 credits spent (ai_parse 22, authority_signals 22, site_type 5, ...)
+```
+
+## Skip behavior
+
+A cloud rule never fails your audit. When it can't run, it reports `skipped` with a reason:
+
+| Skip reason | Meaning |
+|-------------|---------|
+| `not-authenticated` | Not logged in - run `squirrel auth login` |
+| `insufficient-credits` | Balance too low - top up or lower the page count |
+| `credit-cap-reached` | The audit hit `max_credits_per_audit`; work was truncated at the cap |
+| `service-unavailable` | The cloud service errored; charges for failed calls are refunded |
+
+## Controlling spend
+
+The per-audit cap, confirmation threshold, and `--yes` flag are covered in [Credits & Pricing](/cloud/credits#spend-controls).
+
+To opt out of specific cloud rules while keeping the rest:
+
+```toml squirrel.toml
+[rules]
+disable = ["adblock/*", "links/dead-links"]
+```
+
+Or disable all cloud calls for a project:
+
+```toml squirrel.toml
+[cloud]
+enabled = false
+```