docs: rewrite the site for first-time installers; recolor to the brand mark

The docs had no beginner entry point. "Get Started" pointed at the wiring
guide, which opens with a lethal-voltage warning and an ASCII terminal-block
diagram, and the actual quick start lived in the README — off-site. Every
guide was written for someone who already knew what a CCA, an MPPT, or PSRAM
was.

- New "Start Here" guide: what it does in plain terms, a glossary of the
  jargon the other pages assume, a shopping list, five numbered steps, and
  how to tell it's working. The hero now points here.
- Sidebar regrouped by when you need something (Setting it up / Once it's
  running / Reference) instead of alphabetically, so nobody lands in the API
  tables mid-install.
- Config Builder fields gained plain-language hints. It was 15 bare labels —
  "API encryption key" with no hint of what to do about it. The hints go
  INSIDE the JS-toggled wrappers (cca-ip-row, cca-mac-row, display-row) so
  they hide with their fields; wizard.js binds by ID only, contract intact.
- Troubleshooting opens with the four problems people actually hit, in prose,
  ahead of the symptom tables.
- Configuration / Web Server / TSDB now state up front whether you need to
  read them. TSDB retitled "Saving History to Flash".
- Wiring answers the unspoken question — can this break my solar system? —
  before the DE/RE electrical detail.

The TSDB cadence rationale (flash writes cutting I-cache on both cores, the
~40x MTTF change from coarsening to 30 min) moved into the reference section
rather than being dropped with the rest of the simplification.

Colors: the accent ramp was green and unrelated to anything. Now taken from
the "Emitting" mark — accent-low is the optimizer body's silicon indigo
verbatim, accent-high its busbar silver. Amber keeps its one meaning. Link
text measures 11.4:1 dark / 8.5:1 light, both past WCAG AA.

Site builds clean; starlightLinksValidator passes (the read-only wiring
anchor was renamed, all three references updated).

Claude-Session: https://claude.ai/code/session_01RgSnMCa3JQigphGnPbazdw

Author: RAR

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- **Docs rewritten for first-time installers.** A new **Start Here** guide covers what to buy, what the jargon means, and the five steps from parts on the desk to a live dashboard — the "Get Started" button used to drop you into a high-voltage warning and a terminal-block diagram. The sidebar is now ordered by when you need something rather than alphabetically, the Config Builder explains what each field is for, and the reference-heavy pages say up front whether you need to read them. No behaviour changed.
+- **Docs site recoloured to the brand mark.** Link and accent colours moved from green to the mark's silicon indigo and busbar silver; amber keeps its one meaning — this part is live.
 - **New brand mark.** The green-to-blue tile is replaced by an optimizer emitting a telemetry frame, in silicon indigo and amber. It's drawn at three sizes rather than scaled — the device favicon, the device UI sidebar, and the docs — so it stays legible in a browser tab. The docs site had no logo or favicon configured before and now carries the same mark the device serves.
 
 ### Fixed

site/astro.config.mjs

@@ -34,20 +34,34 @@ export default defineConfig({
       social: [
         { icon: 'github', label: 'GitHub', href: 'https://github.com/RAR/esphome-tigomonitor' },
       ],
+      // Ordered by when a first-time installer needs it, not alphabetically:
+      // setup you can't skip, then the things you reach for once it's running,
+      // then reference nobody needs to read to get working.
       sidebar: [
         {
-          label: 'Guides',
+          label: 'Setting it up',
           items: [
-            { label: 'Configuration', link: '/guides/configuration/' },
+            { label: 'Start Here', link: '/guides/getting-started/' },
             { label: 'Wiring', link: '/guides/wiring/' },
-            { label: 'Reducing Frame Loss', link: '/guides/uart-optimization/' },
-            { label: 'Web Server & API', link: '/guides/web-server/' },
-            { label: 'TSDB Integration', link: '/guides/tsdb-integration/' },
+            { label: 'Config Builder', link: '/config-builder/' },
+          ],
+        },
+        {
+          label: 'Once it’s running',
+          items: [
             { label: 'Home Assistant', link: '/guides/home-assistant/' },
             { label: 'Troubleshooting', link: '/guides/troubleshooting/' },
+            { label: 'Reducing Frame Loss', link: '/guides/uart-optimization/' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { label: 'Configuration Options', link: '/guides/configuration/' },
+            { label: 'Web Server & API', link: '/guides/web-server/' },
+            { label: 'Saving History to Flash', link: '/guides/tsdb-integration/' },
           ],
         },
-        { label: 'Config Builder', link: '/config-builder/' },
       ],
     }),
   ],

site/src/components/ConfigWizard.astro

@@ -7,8 +7,10 @@
 ---
 <div class="tigo-wizard not-content">
   <p class="tw-intro">
-    Fill in your board and network details, then copy or download a ready-to-flash
-    ESPHome YAML. Everything runs in your browser — nothing is uploaded.
+    Answer the questions below and this writes your setup file for you — no YAML to
+    learn. Save the result next to your ESPHome install and flash it. Everything runs
+    in your browser; nothing is uploaded anywhere. Not sure what any of this is?
+    Read <a href="/esphome-tigomonitor/guides/getting-started/">Start Here</a> first.
   </p>
 
   <form id="wizard" class="tw-form">
@@ -23,46 +25,52 @@
 
     <fieldset class="tw-card">
       <legend>Device &amp; UART</legend>
-      <label class="field"><span>Device name</span><input id="name" value="tigo-server" /></label>
+      <label class="field"><span>Device name</span><input id="name" value="tigo-server" /><small class="hint">What it'll be called on your network. Lowercase letters and dashes only.</small></label>
       <div class="grid2">
-        <label class="field"><span>Number of devices</span><input id="num-devices" type="number" min="1" /></label>
-        <label class="field"><span>Update interval</span><input id="update-interval" value="30s" /></label>
-        <label class="field"><span>UART TX pin</span><input id="uart-tx" /></label>
-        <label class="field"><span>UART RX pin</span><input id="uart-rx" /></label>
+        <label class="field"><span>Number of devices</span><input id="num-devices" type="number" min="1" /><small class="hint">How many panels you have. Round up a little.</small></label>
+        <label class="field"><span>Update interval</span><input id="update-interval" value="30s" /><small class="hint">How often readings go to Home Assistant.</small></label>
+        <label class="field"><span>UART TX pin</span><input id="uart-tx" /><small class="hint">Already correct for your board.</small></label>
+        <label class="field"><span>UART RX pin</span><input id="uart-rx" /><small class="hint">Leave these alone unless you wired it yourself.</small></label>
       </div>
     </fieldset>
 
     <fieldset class="tw-card">
       <legend>Networking</legend>
-      <label class="field"><span>Wi-Fi SSID</span><input id="wifi-ssid" placeholder="YOUR_WIFI_SSID" /></label>
+      <label class="field"><span>Wi-Fi SSID</span><input id="wifi-ssid" placeholder="YOUR_WIFI_SSID" /><small class="hint">Your home Wi-Fi network name, exactly as it appears.</small></label>
       <label class="field"><span>Wi-Fi password</span><input id="wifi-pass" placeholder="YOUR_WIFI_PASSWORD" /></label>
-      <label class="field"><span>Static IP <em>(optional)</em></span><input id="static-ip" /></label>
+      <label class="field"><span>Static IP <em>(optional)</em></span><input id="static-ip" /><small class="hint">Leave blank and your router picks one. Fill it in if you want the dashboard always at the same address.</small></label>
     </fieldset>
 
     <fieldset class="tw-card">
       <legend>CCA &amp; extras</legend>
+      <p class="notes">
+        Optional. These let the device learn your panels' real names instead of
+        showing codes like "Module 4F2A". You can also type names in by hand later.
+      </p>
       <label class="field">
         <span>CCA source</span>
         <select id="cca">
           <option value="none">None</option>
           <option value="http">HTTP (older firmware)</option>
           <option value="ble">Bluetooth (4.0.4+)</option>
         </select>
+        <small class="hint">How to reach your Tigo box. Pick Bluetooth if its firmware is 4.0.4 or newer — those refuse network requests.</small>
       </label>
-      <label class="field" id="cca-ip-row"><span>CCA IP</span><input id="cca-ip" /></label>
-      <label class="field" id="cca-mac-row"><span>CCA Bluetooth MAC</span><input id="cca-mac" placeholder="04:C0:5B:XX:XX:XX" /></label>
-      <label class="check"><input type="checkbox" id="cloud" /> <span>Enable Tigo cloud import</span></label>
-      <label class="check" id="display-row"><input type="checkbox" id="display" /> <span>Include display (AtomS3R-Display)</span></label>
+      <label class="field" id="cca-ip-row"><span>CCA IP</span><input id="cca-ip" /><small class="hint">Your Tigo box's address on your network — check your router's device list.</small></label>
+      <label class="field" id="cca-mac-row"><span>CCA Bluetooth MAC</span><input id="cca-mac" placeholder="04:C0:5B:XX:XX:XX" /><small class="hint">A starting guess is fine — the device can search for your CCA and let you pick it.</small></label>
+      <label class="check"><input type="checkbox" id="cloud" /> <span>Enable Tigo cloud import<small class="hint">Pulls the panel layout your installer set up, using your Tigo account.</small></span></label>
+      <label class="check" id="display-row"><input type="checkbox" id="display" /> <span>Include display (AtomS3R-Display)<small class="hint">Only if your board has a screen on it.</small></span></label>
     </fieldset>
 
     <fieldset class="tw-card">
       <legend>Security</legend>
-      <label class="check"><input type="checkbox" id="use-secrets" checked /> <span>Generate a <code>secrets.yaml</code></span></label>
+      <label class="check"><input type="checkbox" id="use-secrets" checked /> <span>Generate a <code>secrets.yaml</code><small class="hint">Keeps your passwords in a separate file. Recommended.</small></span></label>
       <label class="field">
         <span>API encryption key</span>
         <span class="with-btn"><input id="api-key" /><button type="button" id="gen-key" class="btn-secondary">Generate</button></span>
+        <small class="hint">Lets Home Assistant talk to the device securely. Click Generate — you don't need to understand it, just don't lose it.</small>
       </label>
-      <label class="field"><span>OTA password</span><input id="ota-pass" value="changeme" /></label>
+      <label class="field"><span>OTA password</span><input id="ota-pass" value="changeme" /><small class="hint">Needed to update the firmware over Wi-Fi later. Change it from the default.</small></label>
     </fieldset>
   </form>
 
@@ -178,12 +186,24 @@
   }
   .tigo-wizard input::placeholder { color: var(--sl-color-gray-4); }
 
+  /* Plain-language help under a field. Deliberately quiet — it should read as
+     an aside to someone who needs it and be skippable by someone who doesn't. */
+  .hint {
+    font-size: var(--sl-text-xs);
+    line-height: 1.45;
+    color: var(--sl-color-gray-3);
+  }
+  /* Checkbox hints sit inside the label's <span>, so they need to break the line. */
+  .check .hint { display: block; margin-top: 0.15rem; }
+
   .check {
-    display: flex; align-items: center; gap: 0.55rem;
+    /* flex-start, not center: every checkbox here carries a two-line hint, so
+       the box must align to the first line rather than the block's midpoint. */
+    display: flex; align-items: flex-start; gap: 0.55rem;
     margin: 0.85rem 0 0; cursor: pointer;
     font-size: var(--sl-text-sm); color: var(--sl-color-white);
   }
-  .check input[type=checkbox] { width: 1.05rem; height: 1.05rem; flex: none; accent-color: var(--sl-color-accent); }
+  .check input[type=checkbox] { width: 1.05rem; height: 1.05rem; flex: none; margin-top: 0.15rem; accent-color: var(--sl-color-accent); }
   .check code { font-size: 0.9em; }
 
   .with-btn { display: flex; gap: 0.5rem; }

site/src/content/docs/guides/configuration.md

@@ -2,7 +2,34 @@
 title: Configuration Guide
 ---
 
-Complete YAML reference for the ESPHome Tigo Monitor component — every option on the `tigo_monitor` and `tigo_server` platforms, the sensors they expose, and the ESP-IDF/PSRAM settings the firmware needs. New here? Start with the [Quick Start in the README](https://github.com/RAR/esphome-tigomonitor#quick-start), then come back for the details.
+This is the full list of every setting, for when you need to look one up.
+
+:::tip[You probably don't need to read this]
+The **[Config Builder](/esphome-tigomonitor/config-builder/)** writes a working
+setup file for you, and the settings people actually change day-to-day can be
+changed on the device itself without touching any file — see
+[the handful that matter](#the-settings-most-people-change) below.
+
+Setting up for the first time? Go to
+**[Start Here](/esphome-tigomonitor/guides/getting-started/)** instead.
+:::
+
+## The settings most people change
+
+Everything else on this page has a sensible default. These five are the ones
+worth knowing about:
+
+| Setting | What it does |
+|---------|--------------|
+| `number_of_devices` | How many panels to track. Set it to your panel count (or a bit more). |
+| `power_calibration` | Nudges all power readings up or down if they don't match your inverter. `1.05` = +5%. |
+| `reset_at_midnight` | Starts the daily energy and peak-power figures fresh each night. |
+| `inverters:` | Groups your strings under inverter names so the dashboard mirrors your real layout. |
+| `api_token` / `web_password` | Passwords for the dashboard and API. Worth setting. |
+
+The first three can be changed **live in the web dashboard** (Tools → Device
+Configuration) without rebuilding or reflashing anything — handy for tuning
+`power_calibration` against your inverter's own display.
 
 ## Contents
 
@@ -66,21 +93,30 @@ inverters:
       - "MPPT 4"
 ```
 
-MPPT labels must match CCA labels exactly. The web dashboard shows hierarchy: Inverter → MPPT → String → Panel.
+MPPT labels must match your CCA's labels exactly. The dashboard then shows your array the way it's really built: Inverter → MPPT → String → Panel.
+
+#### Renaming things without editing the file
 
-#### Renaming from the UI
+You can rename inverters and strings directly in the dashboard — click the ✎ next
+to any label on the Topology page. The new name is saved on the device (in NVS,
+its small settings memory) and survives reboots, so you can switch to friendly
+names like "South Roof" without rebuilding your config.
 
-Inverter and string display names are editable from the Topology view (✎ next to each label). Overrides are persisted to NVS, keyed by canonical YAML/CCA name. The YAML-defined `name:` is still the immutable identity used everywhere internally; the override only affects display. Empty override = falls back to canonical name. Useful when you want friendlier names ("South Roof") without redeploying YAML.
+The name in your YAML stays the real identity behind the scenes; the rename only
+changes what's displayed. Clear it to go back to the original.
 
-#### Per-string panel nameplate (rating)
+#### Telling it how big your panels are
 
-Click the rating pill in the Topology view to set the per-panel nameplate watts for a string (uint16, 0 = unset). Persisted to NVS. When set:
+Click the rating pill on the Topology page to enter your panel's rated watts —
+the number on the sticker, e.g. 400. Saved on the device. Once set:
 
-- Panel tiles show "% of rated" alongside watts.
-- Health classification uses rating-vs-power instead of median-vs-peer (with a "string sleeping" check at <5% of total nameplate so dawn doesn't paint everything red).
-- String aggregate roll-up shows output as % of total nameplate.
+- Each panel shows what percentage of its rating it's currently making.
+- Underperforming panels are judged against that rating rather than against their
+  neighbours, which is more reliable. (At dawn, when the whole string is below 5%
+  of rated, it's marked as sleeping rather than as broken.)
+- Each string shows its total output as a percentage of what it could be making.
 
-Falls back to median-based behavior when unset.
+Leave it unset and panels are compared against each other instead.
 
 ### Midnight Reset
 
@@ -145,6 +181,10 @@ tigo_server:
 
 ### CCA over Bluetooth (`cca_source: ble`)
 
+**In plain terms:** newer Tigo CCAs refuse to answer questions over your home
+network. This option asks them over Bluetooth instead, so you can still pull your
+panel names and layout across. If your CCA is on older firmware you don't need it.
+
 Tigo CCA firmware 4.0.4+ (incl. 4.0.5-ct) locks the local HTTP API, so the CCA Info page can instead source data over Bluetooth. With `cca_source: ble` and a `ble_client_id`, `tigo_server` becomes the BLE client and talks the CCA's `mobile_api` over GATT. The link is opened on demand and dropped after each read so the Tigo phone app can still connect (the CCA allows one BLE central at a time).
 
 ```yaml
@@ -182,6 +222,11 @@ The YAML value is the **default**. A stored value overrides it until you press *
 
 ### Tigo cloud import (`cloud_import: true`)
 
+**In plain terms:** your installer already typed your panel names and layout into
+Tigo's system. This pulls that work down so you don't have to retype it. You sign
+in once with your normal Tigo account; only the resulting access token is kept on
+the device, never your password.
+
 When the CCA's local HTTP is locked, the panel names + string/MPPT/inverter layout can be recovered from Tigo's cloud (the same API the mobile app uses). Enter your Tigo account in the **Configure** modal on the Tigo Cloud page — **only the resulting bearer token is persisted to NVS, never the password**. The page also shows Tigo's own per-equipment health/status/history; layout import is a button on the Topology page. HTTPS is verified against the mbedTLS certificate bundle, which `cloud_import` enables automatically.
 
 ### Authentication
@@ -461,7 +506,7 @@ Check the low-water mark at any time — `heap_min_free` in `curl http://<device
 
 ## On-Flash History (esp_tsdb)
 
-Persistent time-series history is opt-in via two extra dependencies and a custom partition table. See [TSDB Integration](/esphome-tigomonitor/guides/tsdb-integration/) for the full schema, sizing, and query reference.
+Persistent time-series history is opt-in via two extra dependencies and a custom partition table. See [Saving history to flash](/esphome-tigomonitor/guides/tsdb-integration/) for the full schema, sizing, and query reference.
 
 Quick form (8 MB AtomS3R):