docs: rewrite documentation site

.claude/rules/doc-rules.md

@@ -29,7 +29,7 @@ Hassette docs should feel like a patient friend who's already built the thing yo
 ### Voice rules
 
 1. **Use "you" and "your" in getting-started and recipe procedure sections.** In concept and API reference pages, make the system the subject instead — see voice-guide.md rule #10.
-2. **Lead with what it does, not what it is.** "The scheduler lets you run functions at specific times" not "The scheduler is a service that manages timed execution of callable objects."
+2. **Lead with what it does, not what it is.** Every first mention of a Hassette term (`App`, `Bus`, `Scheduler`, `Api`, `StateManager`, `AppConfig`) must define it by function, not by category. "The scheduler runs functions at specific times" not "The scheduler is a service that manages timed execution." "`AppConfig` loads and validates settings from `hassette.toml`" not "`AppConfig` is a Pydantic settings model." The category is invisible to the reader; the function is what they need.
 3. **Use concrete examples in prose, not just code blocks.** "like temperature sensors that report every 2 seconds" not "such as high-frequency update sources."
 4. **Short sentences for concepts, longer ones for flow.** Introduce an idea in one punchy line. Then explain how it works in a sentence or two that builds on the first.
 5. **Active voice.** "Hassette connects to Home Assistant" not "a connection is established." Passive voice makes prose feel distant and academic.
@@ -73,8 +73,9 @@ The voice and approachability rules above are hard requirements. The structures
 1. **Problem statement** — one paragraph describing the real-world situation. Use a concrete example ("Your motion sensor fires every time a cat walks by").
 2. **The Code** — a full, runnable app with config. This is the main attraction.
 3. **How it works** — walk through the code, explaining each decision. Call out the Hassette features being used and link to their concept pages.
-4. **Variations** — alternative approaches or tweaks for different scenarios.
-5. **See also** — links to concept pages for the features used, and related recipes.
+4. **Verify it's working** — a concrete verification step: a CLI command (`hassette log --app <key>`) or web UI action (Handlers tab) the reader runs to confirm the automation fires. Show expected output.
+5. **Variations** — alternative approaches or tweaks for different scenarios.
+6. **See also** — links to concept pages for the features used, and related recipes.
 
 ### Getting-started pages
 
@@ -87,7 +88,7 @@ The voice and approachability rules above are hard requirements. The structures
 
 API reference is auto-generated by mkdocstrings from docstrings. When adding a new public module or class:
 
-- Add it to the `PUBLIC_MODULES` allowlist in `tools/gen_ref_pages.py`
+- Add it to the `PUBLIC_MODULES` allowlist in `tools/docs/gen_ref_pages.py`
 - Write clear docstrings on the class and its public methods (one-liner summary, parameter descriptions via type hints, usage example if the method is non-obvious)
 - Don't duplicate reference content in concept pages — link to it instead
 
@@ -143,6 +144,7 @@ This way minimal fragments are slices of tested files, not standalone untested c
 - **Show the outcome.** After a code block, briefly say what happens when it runs. "When the sensor crosses 75°F, the handler fires and turns on the fan." The reader should be able to predict behavior before running it.
 - **One concept per example.** An example that demonstrates debouncing should not also introduce conditions, predicates, and dependency injection. Layer concepts across examples, not within them.
 - **Real entity names.** Use `light.kitchen`, `sensor.outdoor_temperature`, `binary_sensor.front_door` — not `entity.my_entity` or `sensor.test_sensor`. Real names help readers map to their own setup.
+- **Keep lines under 80 characters.** The docs content area is narrow — long lines force horizontal scrolling, which makes code hard to read. Break function signatures across multiple lines, use short variable names, and extract intermediate values. If a line is too long for the rendered page, it's too long for the snippet.
 
 ## Layering for Skill Levels
 

.claude/skills/doc-accuracy-review/SKILL.md

@@ -0,0 +1,140 @@
+# Doc Accuracy Review
+
+Verify documentation pages against the actual source code. Each verification subagent reads one page, inventories its checkable claims (signatures, defaults, behaviors, exceptions, config keys, CLI flags), and confirms or refutes each one against `src/hassette/`.
+
+Sibling of `doc-persona-review`: that skill tests whether a page is *followable*; this one tests whether it is *true*. Snippets are Pyright-checked in CI, but nothing guards prose claims — they drift silently after every `src/` change.
+
+## Arguments
+
+The page or section to verify. Examples:
+- `core-concepts/bus` (verifies all pages in the section)
+- `core-concepts/scheduler/methods`
+- `cli` (verifies all CLI pages)
+
+If empty, ask what to verify.
+
+## Phase 1: Resolve Pages
+
+If the argument is a section, expand to all pages in that directory (excluding `snippets/`). If it's a single page, use that page.
+
+No persona selection — every page gets the same verification treatment.
+
+## Phase 2: Extract and Assemble
+
+Two scripts handle all file preparation. Run them, don't read their output. Do NOT read the page content or briefing files yourself — the heavy content belongs only in subagent contexts.
+
+### Step 1: Get a tmp directory
+
+```bash
+get-skill-tmpdir doc-accuracy-review
+```
+
+Use the printed path as `$TMPDIR` below.
+
+### Step 2: Build docs and extract pages
+
+```bash
+uv run mkdocs build --strict
+uv run tools/docs/extract_doc_page.py --section <section> --output-dir $TMPDIR/pages
+# or for a single page:
+uv run tools/docs/extract_doc_page.py <page> --output-dir $TMPDIR/pages
+```
+
+### Step 3: Assemble briefing files
+
+One command per page (no persona argument — the template is fixed):
+
+```bash
+uv run tools/docs/assemble_accuracy_briefing.py $TMPDIR/pages/<page-slug>.txt $TMPDIR/briefings
+```
+
+Chain with `&&` for multi-page sections. Each briefing lands at `$TMPDIR/briefings/accuracy--<page-slug>.md`.
+
+## Phase 3: Dispatch Verification Agents
+
+For each briefing file, dispatch a **Sonnet** subagent with this prompt:
+
+```
+Read the file at {briefing_path} and follow the instructions inside. You have full read access to the repository — verify claims against the source code in src/hassette/. Return the JSON result exactly as specified.
+```
+
+Unlike persona walkthroughs, these agents actively explore the repo (Read, Grep, Glob), so they run longer per page. Cap at 5 concurrent subagents.
+
+Use `schema` on the agent call to enforce the JSON structure:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "page": {"type": "string"},
+    "claims_checked": {"type": "integer"},
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "line": {"type": "integer"},
+          "claim_type": {"type": "string", "enum": ["api-signature", "default-value", "behavior", "exception", "config", "cli", "import-path", "version", "file-path"]},
+          "verdict": {"type": "string", "enum": ["WRONG", "OUTDATED_API", "UNVERIFIABLE"]},
+          "severity": {"type": "string", "enum": ["high", "low"]},
+          "doc_quote": {"type": "string"},
+          "code_evidence": {"type": "string"},
+          "explanation": {"type": "string"},
+          "suggested_fix": {"type": "string"}
+        },
+        "required": ["line", "claim_type", "verdict", "severity", "doc_quote", "code_evidence", "explanation", "suggested_fix"]
+      }
+    },
+    "summary": {"type": "string"}
+  },
+  "required": ["page", "claims_checked", "findings", "summary"]
+}
+```
+
+## Phase 4: Triage and Present
+
+### Triage before trusting
+
+Verification agents make mistakes in both directions, and for accuracy work a wrong "fix" is worse than the original error — it makes a true sentence false. Before presenting or fixing anything:
+
+1. For each `WRONG` and `OUTDATED_API` finding, open the cited `code_evidence` location and confirm the contradiction is real and that the cited code is the code path the page describes.
+2. Findings with no usable code citation are discarded.
+3. `UNVERIFIABLE` findings get a quick independent grep — agents sometimes miss a symbol that one targeted search finds. If you find it and the claim holds, drop the finding; if you find it and the claim is false, upgrade to `WRONG`.
+
+### Sanity-check coverage
+
+A page with `claims_checked: 3` that plainly contains dozens of API references got a lazy pass — re-dispatch it. Use judgment, not a fixed threshold: reference-heavy pages (methods, triggers, predicate tables) should report high counts; conceptual index pages legitimately report low ones.
+
+### Output format
+
+Group confirmed findings by page, worst first (`high` severity, then `WRONG` before `OUTDATED_API` before `UNVERIFIABLE`):
+
+```
+## page-name.md — N findings (M claims checked)
+
+- **[verdict / claim_type / severity]** L{line}: "{doc_quote}"
+  Code: {code_evidence}
+  {explanation}
+  Fix: {suggested_fix}
+```
+
+End with a summary table:
+
+| Page | Claims checked | WRONG | OUTDATED_API | UNVERIFIABLE |
+|------|----------------|-------|--------------|--------------|
+
+Pages with zero findings appear in the table only — that's the success case, not a gap.
+
+### Fixing
+
+When the user asks for fixes (or pre-authorized auto-fixing), edit the markdown source in `docs/pages/`, not the rendered output. After fixes, run `uv run mkdocs build --strict` to verify the build. If a fix changes a snippet file, re-run Pyright on snippets per the docs CI.
+
+## Design Decisions
+
+**Why a separate skill from doc-persona-review?** Opposite stances toward the repo. The persona reviewer is deliberately blind — it must not know more than the persona does. The accuracy reviewer is the opposite: it greps and reads source freely. One briefing template can't serve both without contradicting itself.
+
+**Why no second adversarial verification pass?** The evidence requirement (every finding cites `file:line`) plus main-agent triage against the cited code catches fabricated findings at a fraction of the cost of doubling the agent count. If triage starts rejecting a large share of findings, revisit this.
+
+**Why `claims_checked`?** Zero findings is the expected result for an accurate page, which makes it indistinguishable from a lazy agent that checked nothing. The count is the cheap signal that separates the two.
+
+**Why Sonnet?** Same reasoning as doc-persona-review — findings drive editing decisions directly, so they need to be trustworthy without per-finding human review. Verification additionally requires multi-step code navigation, which Haiku does less reliably.

.claude/skills/doc-accuracy-review/references/briefing-template.md

@@ -0,0 +1,115 @@
+# Documentation Accuracy Verification Briefing
+
+You are a technical fact-checker verifying one Hassette documentation page against the framework's actual source code. Hassette is an async-first Python framework for building Home Assistant automations. The repository root is your current working directory; the source lives in `src/hassette/`.
+
+The governing principle: **a page is accurate when every checkable claim is true of the code as it exists right now** — not as it was designed, not as a docstring describes it, not as another doc page restates it.
+
+Style, clarity, voice, and structure are explicitly out of scope. Other reviews cover those. If a sentence is confusing but true, it is not a finding.
+
+## What counts as a checkable claim
+
+Check every instance of these claim types. Skip everything else.
+
+| Type | Examples |
+|---|---|
+| `api-signature` | Method/function/class names, parameter names, return types mentioned in prose ("`on_state_change` returns a `Subscription`", "pass `jitter=` to any trigger") |
+| `default-value` | Any stated default: parameter defaults ("`run_daily()` defaults to midnight"), config defaults, timeouts, retention periods, ports |
+| `behavior` | Assertions about runtime behavior ("the timer resets on re-trigger", "registration is synchronous with the DB", "events during the window are discarded") |
+| `exception` | Exception class names and the conditions that raise them ("omitting `name=` raises `ListenerNameRequiredError`") |
+| `config` | Config keys, section names, file names, env prefixes |
+| `cli` | Commands, subcommands, flags, example invocations ("`hassette listener --app <key> --since 1h`") |
+| `import-path` | Module paths and aliases ("`D` is `hassette.dependencies`", "triggers live in `hassette.scheduler.triggers`") |
+| `version` | Version requirements ("Python 3.11+") |
+| `file-path` | Repo or runtime file paths referenced in prose |
+
+Code examples on the page come from snippet files that CI type-checks with Pyright — do not re-verify that they compile. DO check that prose claims *about* an example match what the example and the underlying API actually do (e.g., prose says "waits 10 seconds" but the snippet passes `debounce=5`).
+
+## How to verify
+
+1. Read the page content at the bottom of this file and inventory the checkable claims as you go. Line numbers are marked with `LINE N:` prefixes — use them in findings.
+2. For each claim, locate the relevant source and confirm or refute it. Start from the source map below; grep from there.
+3. Verify against code, not against docstrings or other doc pages. Docstrings drift exactly like docs do — a docstring is evidence only for a claim about what the docstring says. Read the actual signature, the actual default, the actual raise statement.
+4. Report only claims that FAIL verification. Confirmed claims are not findings — count them and move on. A page where everything checks out returns zero findings, and that is a successful review, not a thin one. Do not pad.
+
+The trap in this task is confirmation laziness: a claim that *sounds* like the code you just read gets waved through. Parameter names and defaults are where this bites — "defaults to 30 seconds" feels right until you read the signature and it says `60`. For every `default-value` and `api-signature` claim, put eyes on the actual line of code before counting it confirmed.
+
+The inverse trap is the plausible-but-wrong finding: flagging a claim as WRONG because you found *a* function that contradicts it, when the page was describing a different overload, wrapper, or layer. Before reporting, confirm the code you cite is the code path the page is actually describing.
+
+## Source map
+
+| Docs section | Primary source |
+|---|---|
+| `core-concepts/bus/*` | `src/hassette/bus/`, `src/hassette/event_handling/`, `src/hassette/events/` |
+| `core-concepts/scheduler/*` | `src/hassette/scheduler/` |
+| `core-concepts/api/*` | `src/hassette/api/`, `src/hassette/models/` |
+| `core-concepts/states/*` | `src/hassette/state_manager/`, `src/hassette/models/states/`, `src/hassette/conversion/` |
+| `core-concepts/apps/*` | `src/hassette/app/`, `src/hassette/task_bucket/`, `src/hassette/config/` |
+| `core-concepts/configuration/*` | `src/hassette/config/` |
+| `core-concepts/cache/*` | `src/hassette/app/` (cache property; backed by the `diskcache` library) |
+| `core-concepts/internals/*` | `src/hassette/core/`, `src/hassette/resources/` |
+| `core-concepts/database-telemetry` | `src/hassette/core/database_service.py`, `src/hassette/migrations_sql/` |
+| `cli/*` | `src/hassette/cli/` |
+| `web-ui/*` | `src/hassette/web/` |
+| `testing/*` | `src/hassette/test_utils/` |
+| `operating/*` | `src/hassette/logging_.py`, `src/hassette/core/` |
+| `getting-started/*`, `recipes/*`, `migration/*`, `troubleshooting` | Cross-cutting — grep `src/hassette/` for the symbols the page mentions |
+
+Cross-cutting locations regardless of section:
+
+- Exceptions: `src/hassette/exceptions.py`
+- Public API surface and aliases: `src/hassette/__init__.py`
+- Event payloads: `src/hassette/events/`
+- Enums and shared types: `src/hassette/types/`
+
+## Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `WRONG` | The claim contradicts the code: wrong default, wrong parameter name, wrong behavior, wrong condition |
+| `OUTDATED_API` | The claim references a symbol, flag, config key, or path that no longer exists (renamed or removed) |
+| `UNVERIFIABLE` | A specific, checkable claim whose implementation you could not locate after a genuine search |
+
+Severity: `high` if acting on the claim would break user code or send a user down a wrong path (wrong API usage, wrong exception to catch, wrong config key); `low` if the error is real but harmless (a name misspelled in prose with correct usage in the adjacent example).
+
+## Evidence rules
+
+Every finding must carry its evidence:
+
+- `doc_quote` — the exact sentence or phrase from the page making the claim
+- `code_evidence` — `file:line` plus a short quote of the contradicting code; for `UNVERIFIABLE`, list where you searched (paths and grep patterns)
+
+A finding without a code citation will be discarded during triage, so do the lookup now.
+
+## Output
+
+Return your results as a JSON object:
+
+```json
+{
+  "page": "{{PAGE_PATH}}",
+  "claims_checked": 0,
+  "findings": [
+    {
+      "line": 0,
+      "claim_type": "default-value",
+      "verdict": "WRONG",
+      "severity": "high",
+      "doc_quote": "<exact text from the page>",
+      "code_evidence": "<file:line — short code quote, or search trail for UNVERIFIABLE>",
+      "explanation": "<what the code actually does>",
+      "suggested_fix": "<corrected sentence or phrase>"
+    }
+  ],
+  "summary": "<2-3 sentences: overall accuracy of the page, where the errors cluster>"
+}
+```
+
+`claims_checked` is the total number of checkable claims you verified, including the ones that passed. It is how the reviewer distinguishes "all true" from "didn't look."
+
+## Page content
+
+Page: {{PAGE_PATH}}
+
+---
+{{PAGE_CONTENT}}
+---