docs: add bonus chapter — Style with wheels-basecoat

[bpamiri]

Summary

Adds tutorial/08-bonus-basecoat.mdx, a 30-minute optional follow-up to Part 7 that walks through installing the wheels-basecoat package and rewriting the post show view using uiCard, uiField, and uiButton helpers. Lands the Wheels package system as a teachable end-to-end flow rather than a chapter-3 conceptual aside.

This is the chapter that originally motivated the four-PR fix chain (#2368, #2373, #2374, plus the two package-side PRs). With those fixes merged or in flight, the install path is now functional end-to-end and the chapter can be authored against verified-working instructions instead of aspirational ones.

Chapter shape

Follows the existing tutorial conventions:

• "Where we left off" — clean Part-7 recap so readers can resume.
• "Why basecoat over simple.css" — tradeoff framing, not a recommendation. Tutorial readers stay on simple.css; the chapter is for after-the-tutorial work.
• Steps for install, CSS asset serving, layout wiring, and view rewrite.
• Checkpoint with three curl | grep verifications a reader can run themselves.
• Troubleshooting with four real failure modes I hit during end-to-end verification on a fresh VM.

What it teaches

Beyond the visible "now your views are prettier" outcome, the chapter teaches the package model:

1. wheels packages add <name> — registry lookup, sha256 verification, extraction
2. Auto-discovery on app boot via PackageLoader (no registration step, no config edit)
3. package.json's provides.mixins as the source of truth for helper injection
4. The <name>End() helper convention for block components (uiCard / uiCardEnd)
5. Update / remove / list as the symmetric lifecycle operations

These show up in the chapter narrative, not as bullet-point exposition — readers walk through them.

Verb naming caution

The chapter uses wheels packages add (per #2374), not install. The Aside warning explicitly calls out the LuCLI interception so a reader who reaches for the historic verb gets immediate context, not a confusing [INFO] No git or extension dependencies to install red herring.

Files

• NEW tutorial/08-bonus-basecoat.mdx (~330 lines)
• tutorial/index.mdx — adds the bonus chapter as a row in the parts table and as a card in the "Ready to start" CardGrid
• tutorial/01-hello-wheels.mdx — the existing "On styling" Aside now links to the bonus chapter (was a bare GitHub repo link)
• tutorial/07-testing-deploying.mdx — adds the bonus chapter as the first card in "What to read next"

Prerequisites for the chapter to work end-to-end

	Status
#2368 — BuildInfo isDev() fix	✅ merged
#2373 — $detectRuntime fix	✅ merged
#2374 — install → add rename	✅ merged
wheels-dev/wheels-basecoat#2 — drop view mixin target	🟡 open (link)
wheels-dev/wheels-hotwire#2 — same fix on the hotwire side	🟡 open (link)

The chapter will work the moment wheels-basecoat 1.0.2 (or whatever version ships the package fix) is current in the registry. Until then, readers running the tutorial will hit the helper-activation issue documented in the troubleshooting section.

Verified end-to-end

Fresh VM running wheels 4.0.0-SNAPSHOT+1644 with all five fixes patched in:

$ wheels packages add wheels-basecoat
Installed wheels-basecoat@1.0.1 → /Users/peter/ws/blog/vendor/wheels-basecoat
Run `wheels reload` to activate it.

$ wheels stop && wheels start
$ curl localhost:8080/main/index   # view calling #uiButton(text="Save", variant="primary")#
<button type="button" class="btn">Save</button>

The rendered HTML is shadcn/ui-quality output. The chapter's checkpoint curl | grep commands all pass.

Test plan

• CI green (verify-docs harness should compile the snippets)
• After all five prerequisite PRs merge + a brew snapshot picks them up + wheels-basecoat 1.0.2 is in the registry, a fresh-VM reader can complete the chapter end-to-end without troubleshooting.
• Visual inspection of the rendered chapter in the docs site — links, code blocks, Asides, troubleshooting block all render as intended.

Related

Closes the loop on the work started by the fresh-VM tutorial run earlier this session. Five PRs that together make the package system actually usable, plus this chapter that teaches it.