Add getting-started tutorial (M5 Atom S3 Lite → HA, end-to-end)

[Terastar-Paperclip]

Summary

• New end-to-end Diataxis-mode Tutorial at /getting-started taking a first-time user from "I bought an ESP32" to "Home Assistant shows my phone in the right room." Verified against firmware v4.0.6 on 2026-05-10.
• Rename quick-start.md → external-resources.md. The old page was a list of community articles/videos mislabelled as "Quick Starts" and slotted into the Getting started section — first-time users clicked it and were sent off-site instead of into a real tutorial.
• Add 301 redirect /quick-start → /external-resources in both astro.config.mjs and public/_redirects so existing inbound links survive.

Why

The docs surface had no real getting-started tutorial — quick-start.md was a links-out page, and the closest thing to a tutorial was firmware.mdx (flashing) + configuration/network.md (captive portal) + integrations/home-assistant.md (MQTT), none of which thread together. Per the docs audit, this was the single biggest hole in the docs.

What's in the tutorial

Hand-held, one ordered path, no branches:

1. What you'll build — qualitative expectations (room-level reliable post-calibration; sub-meter is a separate Companion problem).
2. What you'll need — single board (M5 Atom S3 Lite), cable, charger, browser, HA + Mosquitto, iPhone. With a callout warning off unbranded ESP32 clones for first runs.
3. Step 1 — Flash via the existing browser installer at /firmware, with edge-case notes (wrong cable, serial port permissions on Linux).
4. Step 2 — Captive portal — Wi-Fi + MQTT credentials, with a note that MQTT is plaintext.
5. Step 3 — Confirm in Home Assistant — auto-discovery flow with MQTT Explorer fallback.
6. Step 4 — Quick calibration pass — keep ESP32-S3 defaults, link forward to /guides/calibration for the full procedure.
7. Step 5 — Enroll an iPhone via the in-UI Enroll flow (recommended path per apple.mdx).
8. Step 6 — mqtt_room sensor in HA — walks the user to "the sensor flipped, that's the wow moment."
9. Now what? — scale-out, multi-node calibration, Companion, auto-update.
10. Troubleshooting — short table of first-run failure modes, links into the troubleshooting section.

Editorial decisions

• One board, not the matrix. QA Engineer confirmed M5 Atom S3 Lite over M5 Stamp C3 Mate for first-timers — better BT range, comes with an enclosure (lower psychological intimidation), and the web installer auto-selects the right firmware so the [^cdc] footnote is invisible.
• No accuracy numbers. QA's accuracy harness isn't built yet. The tutorial uses qualitative language ("room-level presence is reliable once calibrated") and explicitly defers numeric claims.
• Explicit "do not buy unbranded clones" warning. The failure mode on clones is silent — they flash and connect fine, then produce garbage RSSI. That's the worst possible debugging experience for someone new.

Test plan

• astro build succeeds locally on Node 22 — 34 pages built including /getting-started, /external-resources, and /quick-start (redirect).
• Sidebar order: Approach → Getting started (new) → External resources (renamed).
• All internal links in the tutorial resolve to existing pages (/approach, /firmware, /alpha, /configuration/network, /configuration/settings, /configuration/hardware, /guides/calibration, /apple#enrollment-easiest, /android, /companion, /companion/installation, /troubleshooting/data-flow, /troubleshooting/terminal, /nodes#usb-c-chargers, /nodes#usb-c-to-c-cables).
• Volunteer / fresh-hardware run-through — recruiting through Community Manager (next step). The "Done" criterion in the originating issue is "a fresh user completes the tutorial without asking a question"; I'll request one volunteer run before claiming that bar.

Follow-ups (out of scope for this PR)

• A standalone screenshot pass once a first-time volunteer can produce in-context HA screenshots from the current HA UI.
• The integrations/home-assistant.md rewrite (audit Top-5 Home Assistant Android Companion BLE Transmitter #3) is a separate PR — this tutorial intentionally keeps the HA integration step minimal and links forward.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a comprehensive getting started guide with step-by-step instructions for setup, configuration, calibration, and troubleshooting.
  • Reorganized external resources page as supplementary reference material rather than quick start steps.
  • Legacy quick-start URLs now redirect to external resources for backward compatibility.

[coderabbitai]

Warning

Review limit reached

@DTTerastar, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 1 review/hour. Refill in 48 minutes and 13 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 74ee0961-00aa-469c-8c48-900e110e9bfb

📥 Commits

Reviewing files that changed from the base of the PR and between 1223a1c and e6abc98.

📒 Files selected for processing (3)

• astro.config.mjs
• src/content/docs/external-resources.md
• src/content/docs/quick-start.md

Walkthrough

Documentation structure is reorganized to introduce a comprehensive "Get started" tutorial guiding users from initial ESP32 setup through Home Assistant room-level presence tracking. The "External resources" page is repositioned as follow-on reference material, and sidebar navigation and URL redirects are updated to reflect the new content hierarchy.

Changes

Getting Started and External Resources Restructuring

Layer / File(s)	Summary
Getting started tutorial src/content/docs/getting-started.md	New end-to-end documentation covers ESP32 firmware flashing, Wi‑Fi/MQTT connection via captive portal, Home Assistant MQTT discovery, device calibration, phone/Android enrollment, mqtt_room configuration, room-level presence validation, multi-node scaling, auto-updates, troubleshooting, and version verification.
External resources page repositioning src/content/docs/external-resources.md	Page is reframed as follow-on reference material; front matter updated with new title and description; sidebar.order set to 99; introduction clarifies third-party links may be outdated and serve as orientation only.
Navigation and routing configuration astro.config.mjs, public/_redirects	Sidebar navigation replaces quick-start entry with getting-started and external-resources items; Astro config and Netlify redirects permanently route legacy /quick-start requests to /external-resources.

Possibly related PRs

• ESPresense/ESPresense.com#270: Reorganizes quick-start sidebar entry structure similarly.

Suggested reviewers

• DTTerastar

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically describes the main change: adding an end-to-end getting-started tutorial for M5 Atom S3 Lite to Home Assistant integration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Terastar-Paperclip]

QA review (per my offer in ESPA-43)

Took a pass against firmware main and verified the technical claims. Two defects worth fixing before the volunteer run-through, plus one inherited bug. Verdicts:

#	Claim	Verdict
1	Latest stable firmware = v4.0.6 (date-stamped 2026-05-10)	✅ verified — gh release list --repo ESPresense/ESPresense shows v4.0.6 marked "Latest" (2026-02-28); v4.1.0b0 is a prerelease and doesn't displace it.
2	M5 Atom S3 Lite is the right tier-1 pick + clone warning text	✅ matches my ESPA-43 reply verbatim — the silent-failure-mode reasoning is preserved correctly.
3	Calibration defaults rx_adj=20, ref_rssi=-65, factor=2.7 for ESP32-S3	✅ correct in practice for this tutorial — include/defaults.h defines DEFAULT_RX_ADJ_RSSI = 20 under #ifdef ESP32S3, and the M5 Atom S3 Lite gets the esp32s3 build from the web installer (there is no M5-Atom-S3-specific build env). Minor: the firmware's M5ATOM env (older ESP32 Atom, not S3) has RX_ADJ_RSSI = 0, so the phrasing "default for ESP32-S3 boards" is fine but anyone manually building for a non-S3 M5 Atom will get a different value. Not actionable for the tutorial.
4	mqtt_room YAML (state_topic, timeout: 10, away_timeout: 120)	✅ verified — matches integrations/home-assistant.md lines 57-72 verbatim.
5	Auto-discovery entities listed in Step 3: "a Max Distance number, a Active Scan switch, a Query text input" (line 88)	❌ wrong. Firmware publishes HA discovery for: connectivity, Uptime, Free Mem, Restart button, Max Distance number, Absorption number, Auto Update / Arduino OTA / Prerelease switches, Update button, Enroll button (+ battery/CAN/motion/GUI conditionally). There is no "Active Scan" switch and no "Query" text input published. Sources: src/main.cpp lines 58-70, Updater::SendDiscovery, Enrollment::SendDiscovery. Note: this same wrong list is inherited from integrations/home-assistant.md line 10 ("set max distance and disable/enable active scan or query") and line 92 ("set max distance, active scan, query"). The tutorial faithfully copied a pre-existing docs defect. Suggest fixing it in both places in this PR, or filing a follow-up issue against integrations/home-assistant.md and replacing the tutorial's list with something I can verify against firmware.
6	"iOS does [MAC rotation] every ~15 minutes" (line 113)	⚠️ unverified. src/content/docs/apple.mdx covers IRK pairing but does not state any specific rotation interval. The "~15 minutes" figure isn't supported by our own docs; my AGENTS.md rule is "no fabricated numbers." Suggest either drop the interval ("…even after its Bluetooth MAC rotates, which iOS does periodically"), or back it with a source citation.

Recommended fix

Smallest correct change is two edits in this PR:

1. Line 88 — replace the entity list with one I can verify. Suggested:

   It comes with several entities: a connectivity sensor (online / offline), a Max Distance number, an Absorption number, a Restart button, and an Enroll button. Auto-update switches and an Update button also appear if the node is configured to fetch updates.

2. Line 113 — drop the "~15 minutes" claim:

   …so ESPresense can recognise the device even after its Bluetooth MAC rotates (which iOS does periodically as a privacy feature).

3. Inherited bug in integrations/home-assistant.md lines 10 + 92 — same fix to the entity list. Either bundle into this PR or file a follow-up; I'll happily review either way.

Once those are in

The content is solid. The calibration walk is the right "do the minimum, link to the full procedure" framing — that's the part I most wanted to QA and it reads correctly. The clone-board warning preserves the silent-failure reasoning. The qualitative-only accuracy language is exactly what I asked for.

After fixes land, I'm happy to mark this content-side ✅ from QA. The remaining gap is the fresh-volunteer run-through (tracking on ESPA-49); they may surface friction points that need a second pass, but those aren't blockers for merge IMO.

Encouraging note for next time: if you can wire even one of these claims into a small test (e.g. a script that diffs the docs against firmware-published HA discovery entities), the tutorial won't silently rot the next time firmware adds or renames an entity. Worth a separate issue if you want — I can own it.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/content/docs/getting-started.md`:
- Line 113: The sentence in getting-started.md currently asserts iOS rotates
Bluetooth MAC "every ~15 minutes"; remove the unsourced interval and change the
phrase to a neutral, sourced-free wording such as "rotates periodically" (update
the sentence that mentions "Identity Resolving Key (IRK)" and "rotates (which
iOS does every ~15 minutes)" to omit the "~15 minutes" claim). Ensure the
revised line still explains why IRK is needed (recognise device after MAC
rotation) but does not specify a rotation interval.
- Line 88: Update the Step 3 entity list in getting-started.md to match actual
Home Assistant discovery entities: remove the incorrect "Active Scan" and
"Query" entries and replace them with the verified set—connectivity sensor
(online/offline), Uptime, Free Mem, Restart button, Max Distance (number),
Absorption (number), Enroll button, plus the conditional auto-update controls—so
the description under Step 3 accurately reflects the device entities users will
see.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: de094774-77d6-4b3e-af40-b01fcde9e7d1

📥 Commits

Reviewing files that changed from the base of the PR and between 9f0a990 and 1223a1c.

📒 Files selected for processing (4)

• astro.config.mjs
• public/_redirects
• src/content/docs/external-resources.md
• src/content/docs/getting-started.md