diff --git a/AGENTS.md b/AGENTS.md
index 07e225c..2fe9bfc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,7 +11,7 @@ Operating manual for coding agents working in this repository. Read this fully b
 Two products in one monorepo:
 
 - **`flutterwindcss`** — Tailwind CSS's *design system and styling vocabulary* for Flutter. A real pub dependency. It provides design tokens (spacing, radius, semantic colors) and a utility authoring API over Flutter's **primitive** widgets. This is the "Tailwind" layer.
-- **`flutterbits`** — shadcn/ui for Flutter. **Copy-paste** components (the developer owns the source, fetched via a CLI from a registry), styled entirely through `flutterwindcss` and semantic tokens. This is the "shadcn/ui" layer.
+- **`flutterbits`** — shadcn/ui for Flutter, **plus an opinionated app-structure layer**. **Copy-paste** components (the developer owns the source, fetched via a CLI from a registry), styled entirely through `flutterwindcss` and semantic tokens. Two things in one: (1) shadcn's familiar primitives (parity), and (2) an **intention-revealing "structure" layer** — `Layout`, `Screen`, and typed routing that model how a Next.js/Expo dev thinks, replacing `MaterialApp`/`Scaffold`/`Navigator` ceremony while staying Material-free. This second part is the differentiator. **flutterbits is mobile-first** (portable to web/desktop, matured by demand). Full design: `docs/superpowers/specs/2026-06-10-flutterbits-charter.md` and its two companions (structure+routing, registry+CLI).
 
 The headline feature is **theme portability**: a developer pastes any [tweakcn](https://tweakcn.com)/shadcn theme into a web generator and gets a working Flutter `theme.dart`. No other Flutter UI library does this — protect it.
 
@@ -32,11 +32,12 @@ packages/
 registry/                # SOURCE OF TRUTH for components: .dart files + JSON manifests
 apps/
   docs/                  # Fumadocs (Next.js) site: docs + the tweakcn -> theme.dart generator + registry endpoint
-  example/               # Flutter showcase app; ALSO the golden-test + compile target for the registry
+  example/               # flutterwindcss ENGINE showcase (pure-path WidgetsApp + FwAnimatedTheme) + engine golden/smoke target
+  gallery/               # flutterbits COMPONENT showcase; the golden-test + compile target for the registry (planned)
 tooling/                 # registry builder, melos config, CI scripts
 ```
 
-> **This is the *target* layout.** Today `packages/flutterwindcss/`, `tooling/bake_palette.dart`, `apps/example/`, and `apps/docs/` exist — `apps/example` is a runnable, pure-path **engine** showcase (`WidgetsApp` + `FwAnimatedTheme`), not yet the **component** golden target (no `flutterbits` components yet); `apps/docs` is a **Fumadocs (Next.js/TS)** site whose tweakcn→`theme.dart` generator is **complete (G0–G5 all shipped)** — the color core (`src/lib/generator/color/`, G1), the CSS parser (`src/lib/generator/parse/`, G2 — `:root`/`.dark` → `RawTheme`), the emitter (`src/lib/generator/emit/`, G3 — `RawTheme` → `ResolvedTheme` → `theme.json` → `theme.dart`, end-to-end golden vs `themes.dart`), the web UI (`src/app/(home)/theme-generator/`, G4 — paste → preview → copy, logic in the tested `src/lib/generator/preview.ts`), and the docs page (`content/docs/theme-generator.mdx`, G5). `flutterbits_cli/`, `registry/`, and the melos config are still planned. CI covers `packages/flutterwindcss` (analyze + format + tests + floor-compat + arch-guard), `apps/example` (analyze + format + widget smoke tests), **and** `apps/docs` (the `docs-generator` job: eslint + scoped `tsc` on `src/lib/generator` *and* the `theme-generator` route + Vitest). Don't go looking for dirs that aren't there yet.
+> **This is the *target* layout.** Today `packages/flutterwindcss/`, `tooling/bake_palette.dart`, `apps/example/`, and `apps/docs/` exist — `apps/example` is a runnable, pure-path **engine** showcase (`WidgetsApp` + `FwAnimatedTheme`) and stays **engine-only**; the **component** golden + compile target is a **separate `apps/gallery`** app (planned — does not exist yet, created with the first component slice), NOT `apps/example` (decision 2026-06-10: the engine showcase and the component showcase are distinct apps); `apps/docs` is a **Fumadocs (Next.js/TS)** site whose tweakcn→`theme.dart` generator is **complete (G0–G5 all shipped)** — the color core (`src/lib/generator/color/`, G1), the CSS parser (`src/lib/generator/parse/`, G2 — `:root`/`.dark` → `RawTheme`), the emitter (`src/lib/generator/emit/`, G3 — `RawTheme` → `ResolvedTheme` → `theme.json` → `theme.dart`, end-to-end golden vs `themes.dart`), the web UI (`src/app/(home)/theme-generator/`, G4 — paste → preview → copy, logic in the tested `src/lib/generator/preview.ts`), and the docs page (`content/docs/theme-generator.mdx`, G5). `flutterbits_cli/`, `registry/`, and the melos config are still planned. CI covers `packages/flutterwindcss` (analyze + format + tests + floor-compat + arch-guard), `apps/example` (analyze + format + widget smoke tests), **and** `apps/docs` (the `docs-generator` job: eslint + scoped `tsc` on `src/lib/generator` *and* the `theme-generator` route + Vitest). Don't go looking for dirs that aren't there yet.
 
 - **Toolchain floor (hard): Flutter ≥ 3.29 / Dart ≥ 3.7.** The wide-gamut `Color` API (`Color.withValues` per §3.8, and the `Color.a/.r/.g/.b` accessors), the `Row`/`Column`/`Flex` `spacing` parameter, and pub workspaces require 3.27/3.6 — below that, the code will not compile. We floor one minor higher at **Dart 3.7** so `dart format` uses the modern "tall" style (Dart 3.7+) rather than the legacy short style; mixing the two fails the format check. This floor is set in every `pubspec.yaml` `environment:` and **verified by a CI job pinned to it** (separate from the golden job, which pins a newer version for determinism). Keep the floor identical in the pubspecs and the README.
 - Dependency resolution: **pub workspaces** (`resolution: workspace` in each `pubspec.yaml`). Task running / versioning / publishing: **Melos** — the intended cross-package runner, adopted once the workspace holds multiple packages. While `flutterwindcss` is the only package, use plain `flutter`/`dart` per-package (see §10).
@@ -70,7 +71,7 @@ These encode hard-won decisions. Violating any of them is a review failure.
 
 ## 4. Coding conventions (Dart)
 
-- Public types are prefixed `Fw` (`FwStyle`, `FwButton`, `FwColors`, `FwButtonVariant`).
+- **`flutterwindcss` (engine) public types are prefixed `Fw`** (`FwStyle`, `FwColors`, `FwTokens`, `FwBreakpoint`), and so are the routing/structure **library** base types that ship as engine-style code (`FwRoute`, `FwRoutePattern`, `FwPresentation`, `FwStatusBar`). **flutterbits *components* are UNprefixed** — `Button`, `Card`, `Screen`, `Layout` — because they are copy-paste source the developer owns (shadcn-style) and need no namespace. (Material name clashes, only possible in the rare Material-interop case, are resolved by namespacing the barrel `import '.../ui/ui.dart' as ui;`, not by prefixing — see the charter §5.) When you see `Fw` inside a component, that is the engine showing through.
 - Prefer `const` constructors wherever the analyzer allows; leaf widgets that never change should be `const`.
 - Variants are **typed enums + exhaustive `switch`** (the cva equivalent). No stringly-typed variant maps. The `switch` must be exhaustive so the compiler catches a missing case — do not add a `default:` that papers over new enum values.
 - Every file passes `dart format` (100-col) and `flutter analyze` with **zero** warnings before you call a task done.
@@ -109,7 +110,7 @@ Until the first component lands, follow the component checklist below and the en
 - [ ] Directional layout throughout (§3.3).
 - [ ] A registry manifest entry (§8) listing pub deps and `registryDeps`.
 - [ ] Golden tests for **every variant × size × brightness** (§9).
-- [ ] Imported and rendered in `apps/example` so CI compiles it.
+- [ ] Imported and rendered in `apps/gallery` (the flutterbits component target — **not** `apps/example`, which is the engine showcase) so CI compiles it.
 
 If a desired behavior genuinely cannot be done in Flutter, do not fake it — add it to the **Won't-do list** (§11) and note it in the component's docs.
 
@@ -137,10 +138,12 @@ If a desired behavior genuinely cannot be done in Flutter, do not fake it — ad
 
 ## 8. Registry & CLI
 
-- Registry manifest per component (JSON): `{ name, description, pubDeps: [...], registryDeps: [...], files: [{ path, content }] }`. `registryDeps` resolves inter-component needs (e.g. `dialog` pulls in `button`).
-- `flutterbits add <name>` writes files into the host project (default `lib/components/ui/`), installs `pubDeps`, recursively adds `registryDeps`, then runs `dart format`.
-- `flutterbits diff <name>` shows upstream changes vs the developer's copy (the copy-paste survival mechanism — analogous to shadcn's diff).
-- The registry build step (`tooling/`) generates manifests FROM the `registry/*.dart` source. Never hand-edit a manifest's `content`.
+- Registry manifest per item (JSON): `{ name, type, description, exported, pubDeps: [...], registryDeps: [...], files: [{ path, type, target, content }] }`. **Install-types** (shadcn's `registry:ui`/`lib`/`hook` analog): `component` → `lib/components/ui/<name>.dart`; `util` → `lib/components/ui/_utils/<name>.dart` (shared lib utilities — the `anchor`/overlay substrate, `showConfirm`/`showSheet`/`showToast`; Flutter has no native "hooks", so these are plain utilities). `registryDeps` resolves inter-item needs recursively (e.g. `dialog` pulls in `button`; `popover` pulls in `anchor`).
+- `flutterbits init` scaffolds a project: adds `flutterwindcss`, creates `lib/components/ui/` + `_utils/`, writes a starter `theme.dart`, an initial barrel, an optional starter `Layout`, and `flutterbits.json` (the config — `components.json` analog: registry URL + target paths + theme path).
+- `flutterbits add <name>` writes files into the host project (default `lib/components/ui/`), installs `pubDeps`, recursively adds `registryDeps`, **regenerates the barrel**, then runs `dart format`.
+- **The barrel `lib/components/ui/ui.dart`** is CLI-**generated, never hand-edited** — it re-exports every `exported` item so devs import the whole set from one place (and `import … as ui;` namespaces it for the rare Material-interop clash). Internal utils (e.g. `anchor`) are imported directly and stay out of the barrel.
+- `flutterbits diff <name>` shows upstream changes vs the developer's copy (the copy-paste survival mechanism — analogous to shadcn's diff); it **shows, never auto-merges** (the dev owns their edits).
+- The registry build step (`tooling/build_registry.dart`) generates manifests FROM the `registry/*.dart` source. Never hand-edit a manifest's `content`. Full design: `docs/superpowers/specs/2026-06-10-flutterbits-registry-cli-design.md`.
 
 ---
 
@@ -148,11 +151,11 @@ If a desired behavior genuinely cannot be done in Flutter, do not fake it — ad
 
 This is the safety net that makes a solo, wave-by-wave rollout survivable.
 
-- **Golden tests** use `matchesGoldenFile`. **`flutterwindcss` engine goldens live in-package** (`packages/flutterwindcss/test/golden/`) — a library tests its own widgets. **Component goldens** (every variant × size × brightness) live in `apps/example`, which is also the registry compile target.
+- **Golden tests** use `matchesGoldenFile`. **`flutterwindcss` engine goldens live in-package** (`packages/flutterwindcss/test/golden/`) — a library tests its own widgets. **Component goldens** (every variant × size × brightness) live in **`apps/gallery`**, which is also the registry compile target. (`apps/example` is the *engine* showcase and hosts only engine smoke tests — the two apps are deliberately separate, decision 2026-06-10.)
 - CI pins a **fixed font** and platform so goldens are deterministic across machines, and **CI (Linux) is the authoritative golden platform** — goldens are generated/verified there, and a local `--update-goldens` on a dev box is *not* authoritative. A golden diff on CI is a failing build, not a nuisance.
 - Update goldens only intentionally: `flutter test --update-goldens`, and review the image diff before committing.
 - `flutterwindcss` gets unit tests for `FwStyle` resolution — especially **last-wins conflict behavior** and that chaining produces a single resolved widget.
-- Before marking any task done: `flutter analyze` (zero warnings) AND `flutter test` (green) AND the registry compiles in `apps/example`.
+- Before marking any task done: `flutter analyze` (zero warnings) AND `flutter test` (green) AND the registry compiles in `apps/gallery`.
 
 ---
 
@@ -178,6 +181,8 @@ Adjust paths if the layout drifts; keep this section current.
 | Task | Command |
 |---|---|
 | Build registry manifests | `dart run tooling/build_registry.dart` |
+| Run the flutterbits component gallery | `cd apps/gallery && flutter run` (any device; e.g. `-d chrome`) |
+| Test/golden the gallery | `cd apps/gallery && flutter test` (`--update-goldens` locally is non-authoritative; CI Linux is the source of truth) |
 | Run docs site / generator | `cd apps/docs && pnpm dev` |
 
 Once the workspace holds multiple packages, **Melos** wraps the per-package commands (`melos bootstrap`, `melos run analyze`, `melos run test`); adopt it then, not before.
@@ -217,7 +222,7 @@ Everything **not** in 11a or 11b is fair game and must not be refused on cost gr
 - **Verdict before "won't" (MUST).** Before declaring anything a Non-Goal or limitation, write a one-paragraph feasibility verdict: the mechanism that *would* implement it, its rough cost, and the honest call. Attach it to the spec. Default to building; only the §11 bar excuses not building.
 - **Read before you edit.** Open the canonical sources (`lib/src/style/`, `lib/src/theme/`, `lib/src/tokens/`, and once it exists `registry/button.dart`) and match their patterns before writing new code.
 - **Small, focused changes.** One component or one utility group per change. Don't refactor unrelated code in passing.
-- **No new dependencies without justification.** Prefer the framework's widgets layer. Known sanctioned deps: `lucide_icons_flutter` (icons), `flutter_animate` (animation). Anything else needs a reason in the PR description.
+- **No new dependencies without justification.** Prefer the framework's widgets layer. Known sanctioned deps: `lucide_icons_flutter` (icons), `flutter_animate` (animation), and **`go_router`** (the routing engine the flutterbits structure layer *wraps* — not forks — declared as a `pubDep` of the structure components only; never a `flutterwindcss` dep). `flutter_svg` is sanctioned **by-demand** for blocks that render real SVG illustrations. Anything else needs a reason in the PR description. Deps are declared **per-component in the manifest `pubDeps`**, never globally: a copied `Button` drags in nothing; `add toast` pulls `flutter_animate`; `add layout` pulls `go_router`.
 - **Don't invent APIs.** If unsure whether a Flutter symbol exists in the widgets layer, verify before using it. Do not assume Material symbols are available.
 - **Surface assumptions.** If a task is ambiguous (which variant set? which platforms?), state the assumption you made inline rather than guessing silently.
 - **Never weaken the rules in §3 to make a task pass.** If a rule blocks you, stop and flag it — don't import Material, don't hardcode a color, don't nest wrappers to ship faster.
diff --git a/README.md b/README.md
index c42ab98..741be12 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@
 Two products in one monorepo, built so that **any [tweakcn](https://tweakcn.com)/shadcn theme you paste into a web generator becomes a working Flutter `theme.dart`** — theme portability no other Flutter UI library offers.
 
 - **`flutterwindcss`** — Tailwind CSS v4's *design system and styling vocabulary* for Flutter. Design tokens (spacing, radius, semantic colors, typography, shadows) and a typed, compile‑time utility API (`.tw`) over Flutter's primitive widgets. This is the **Tailwind** layer.
-- **`flutterbits`** — shadcn/ui for Flutter. **Copy‑paste** components you own, fetched via a CLI from a registry, styled entirely through `flutterwindcss` and semantic tokens. This is the **shadcn/ui** layer.
+- **`flutterbits`** — shadcn/ui for Flutter. **Copy‑paste** components you own, fetched via a CLI from a registry, styled entirely through `flutterwindcss` and semantic tokens — **plus** an opinionated, intention‑revealing **structure layer** (`Layout`, `Screen`, typed routing) that models app‑building the Next.js/Expo way. Mobile‑first, portable. This is the **shadcn/ui** layer (and a bit more).
 
 ## Install & docs
 
@@ -88,7 +88,7 @@ Flutter has no structure/style split and no CSS cascade — the widget tree *is*
 
 **🚧 Next on the roadmap:**
 
-1. **`flutterbits` components** and the **registry + CLI** (`flutterbits add` / `diff`). *(The engine is ready — ~96% of daily-driver Tailwind is covered and a full-catalog audit found no engine blocker.)*
+1. **`flutterbits` components** and the **registry + CLI** (`flutterbits init` / `add` / `diff`) — primitives (shadcn parity), the **structure layer** (`Layout`/`Screen`/routing over `go_router`), blocks, and templates. Design specs: [`flutterbits-charter`](docs/superpowers/specs/2026-06-10-flutterbits-charter.md), [structure + routing](docs/superpowers/specs/2026-06-10-flutterbits-structure-and-routing-design.md), [registry + CLI](docs/superpowers/specs/2026-06-10-flutterbits-registry-cli-design.md). *(The engine is ready — ~96% of daily-driver Tailwind is covered and a full-catalog audit found no engine blocker.)*
 2. **Remaining engine long-tail (by demand only)** — niche/feasible items (`inset-shadow`, `mask-*`, backdrop color filters, `columns`, negative margins, `scroll-margin/padding`, decoration styling) built when a real component needs one; the rest is the [coverage & roadmap](docs/superpowers/specs/2026-06-07-flutterwindcss-coverage-and-roadmap.md)'s delegated (animation → [`flutter_animate`](https://pub.dev/packages/flutter_animate); forms/prose/tables/SVG → flutterbits) / impossible sets.
 
 See [`docs/superpowers/specs`](docs/superpowers/specs) for the full engine design and [`docs/superpowers/plans`](docs/superpowers/plans) for the implementation plans.
@@ -99,7 +99,8 @@ See [`docs/superpowers/specs`](docs/superpowers/specs) for the full engine desig
 packages/
   flutterwindcss/        # pub package: tokens, FwTheme, FwStyle accumulator, .tw utilities
 apps/
-  example/               # flutterwindcss engine showcase (pure path, runnable); component golden target (planned)
+  example/               # flutterwindcss ENGINE showcase (pure path, runnable) + engine golden/smoke target
+  gallery/               # flutterbits COMPONENT showcase + golden/compile target (planned)
   docs/                  # Fumadocs site + the tweakcn→theme.dart generator (shipped: parse→color→emit pipeline, web UI at /theme-generator, docs)
 registry/                # (planned) source-of-truth copy-paste components
 tooling/                 # registry builder + the Tailwind palette baker
diff --git a/apps/docs/content/docs/flutterbits/index.mdx b/apps/docs/content/docs/flutterbits/index.mdx
index 8984489..d72b477 100644
--- a/apps/docs/content/docs/flutterbits/index.mdx
+++ b/apps/docs/content/docs/flutterbits/index.mdx
@@ -3,12 +3,18 @@ title: Overview
 description: flutterbits is shadcn/ui for Flutter — copy-paste components you own, styled entirely through flutterwindcss semantic tokens.
 ---
 
-**flutterbits** is *[shadcn/ui](https://ui.shadcn.com) for Flutter*: a registry of **copy-paste
-components** you own. You don't
+**flutterbits** is *[shadcn/ui](https://ui.shadcn.com) for Flutter* — a registry of **copy-paste
+components** you own — **plus an opinionated, intention-revealing app-structure layer**. You don't
 add a versioned widget library — you pull a component's source into your project and it's yours to
 read and edit. Every component is styled entirely through [flutterwindcss](/docs/flutterwindcss)
 semantic tokens, so a theme reskins them all.
 
+Beyond shadcn's primitives, flutterbits ships a **structure layer** — `Layout`, `Screen`, and typed
+routing that model how a Next.js/Expo developer thinks (layouts wrap screens, screens compose blocks,
+blocks compose primitives), so the code reads top-down as the rendered artifact instead of as
+`MaterialApp`/`Scaffold`/`Navigator` plumbing. flutterbits is **mobile-first** (portable to web and
+desktop, maturing there by demand).
+
 <Callout title="Components — coming soon">
   The styling engine ([flutterwindcss](/docs/flutterwindcss)) and the
   [Theme generator](/theme-generator) are shipped and stable. The component registry and CLI
@@ -21,10 +27,12 @@ semantic tokens, so a theme reskins them all.
 - **Copy-paste, not a dependency.** Components are source you own — fetched from a registry, written
   into your project (default `lib/components/ui/`). You can change anything; nothing is locked behind
   a package version. This is the model shadcn/ui pioneered.
-- **A CLI to fetch and update.** `flutterbits add <name>` writes a component's files into your app,
-  installs its package dependencies, and pulls in any other components it needs. `flutterbits diff
-  <name>` shows what changed upstream versus your copy — the survival mechanism for code you've since
-  edited.
+- **A CLI to scaffold, fetch, and update.** `flutterbits init` sets up your project (the styling
+  engine, a `theme.dart`, the components folder, and a generated barrel). `flutterbits add <name>`
+  writes a component's files into your app, installs its package dependencies, pulls in any other
+  components it needs, and regenerates the barrel so you import the whole set from one place
+  (`components/ui/ui.dart`). `flutterbits diff <name>` shows what changed upstream versus your copy —
+  the survival mechanism for code you've since edited (it shows, it never overwrites your edits).
 - **Styled through tokens.** Components reference only semantic roles (`primary`, `muted`, `border`)
   via `context.fw` — never raw colors. So a `theme.dart` generated from any tweakcn/shadcn theme
   reskins every component at once.
diff --git a/docs/superpowers/plans/2026-06-10-flutterbits-button-and-gallery.md b/docs/superpowers/plans/2026-06-10-flutterbits-button-and-gallery.md
new file mode 100644
index 0000000..ef5a355
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-10-flutterbits-button-and-gallery.md
@@ -0,0 +1,833 @@
+# flutterbits `Button` + `apps/gallery` — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stand up the flutterbits component app (`apps/gallery`) and author the canonical `Button` component — the template every later component imitates — with full behavioral tests and golden coverage.
+
+**Architecture:** `Button` is a Material-free `StatefulWidget` that sources its own interaction states (hover/focus/pressed/disabled) via `FocusableActionDetector` + a tap detector (AGENTS.md §6 — action-bearing components own their states), resolves a `(variant, size, states)` → visual treatment with exhaustive `switch`es in plain Dart, and renders a single styled box through the `flutterwindcss` `.tw` chain using only semantic tokens (`context.fw.colors.*`). `apps/gallery` is a new pub-workspace member (mirroring `apps/example`) that hosts the component, its widget smoke test, and its goldens.
+
+**Tech Stack:** Dart/Flutter (≥3.29/3.7), `flutterwindcss` (path dep), `package:flutter/widgets.dart` + `package:flutter/services.dart` (keyboard), `flutter_test` goldens. No Material, no other deps.
+
+**Scope note (no silent reduction):** This plan delivers `Button` + `apps/gallery` end-to-end. The **registry source-of-truth file (`registry/button.dart`), the manifest JSON, and `tooling/build_registry.dart` are deliberately moved to the next plan** (the registry + CLI slice), because the manifest's metadata-source (where `description`/`pubDeps`/`registryDeps` come from when "generated from the .dart") is a registry-spec decision best made alongside the CLI — not invented here. For this plan, `Button` is authored at its consumer-shaped home `apps/gallery/lib/components/ui/button.dart`; the registry/CLI plan promotes it to `registry/` and adds the install path. This is an explicit, recorded adjustment to the original "manifest in plan 1" scope.
+
+**Gallery root is TEMPORARY (becomes `Layout`):** the gallery's job is to showcase flutterbits, and `Layout` (the structure layer) is the flagship — so the gallery's real root **will be `Layout`**. `Layout` is the (larger) structure+routing plan, and Button is built first to de-risk the component pattern and give `Layout` something real to host. Therefore the `WidgetsApp` host in Tasks 0/6 is an **explicitly-temporary bootstrap** (commented as such), and the structure plan **replaces it with `Layout` and makes the gallery the `Layout` demo**. The `WidgetsApp` here is throwaway dev scaffolding for an internal app, not shipped product code — it must be clearly labeled so it is never mistaken for the intended root.
+
+**Reconciliation this plan performs (no-drift):** `default` is a Dart reserved word and cannot be an enum constant, so the shadcn `default` variant/size map to `primary` (variant) and `md` (size). Task 7 updates the charter §3.2 + AGENTS.md §where-named to record this. Every other shadcn variant/size name is used verbatim.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `apps/gallery/pubspec.yaml` | New workspace member `flutterbits_gallery`; deps `flutter` + `flutterwindcss` (path); `uses-material-design: false`. |
+| `pubspec.yaml` (root) | Add `apps/gallery` to the `workspace:` list. |
+| `apps/gallery/analysis_options.yaml` | Lints (mirror `apps/example`). |
+| `apps/gallery/lib/components/ui/button.dart` | The `Button` component + `ButtonVariant`/`ButtonSize` enums. The canonical template. |
+| `apps/gallery/lib/main.dart` | Material-free `WidgetsApp` host rendering a Button gallery (so CI compiles the component). |
+| `apps/gallery/test/button_behavior_test.dart` | Widget tests: renders label, tap fires, disabled blocks, keyboard activates, Semantics flags. |
+| `apps/gallery/test/button_golden_test.dart` | Goldens: every variant × size × brightness grid, plus focused-ring and RTL. |
+| `apps/gallery/test/gallery_smoke_test.dart` | The app builds + renders without exceptions (light/dark/LTR/RTL). |
+
+---
+
+## Task 0: Scaffold `apps/gallery` and register it in the workspace
+
+**Files:**
+- Create: `apps/gallery/pubspec.yaml`
+- Modify: `pubspec.yaml` (root, `workspace:` list)
+- Create: `apps/gallery/analysis_options.yaml`
+- Create: `apps/gallery/lib/main.dart` (placeholder for now)
+
+- [ ] **Step 1: Create `apps/gallery/pubspec.yaml`**
+
+```yaml
+name: flutterbits_gallery
+description: >-
+  flutterbits COMPONENT gallery — a Material-free Flutter app showcasing the
+  copy-paste components, and the golden-test + compile target for the registry.
+publish_to: none
+version: 1.0.0+1
+
+# Joins the repo's pub workspace (root pubspec.yaml `workspace:`).
+resolution: workspace
+
+environment:
+  # Match the toolchain floor (AGENTS.md §2): Flutter 3.29 / Dart 3.7.
+  sdk: '>=3.7.0 <4.0.0'
+  flutter: '>=3.29.0'
+
+dependencies:
+  flutter:
+    sdk: flutter
+  # The styling engine every component styles through.
+  flutterwindcss:
+    path: ../../packages/flutterwindcss
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  flutter_lints: ^5.0.0
+
+flutter:
+  # Material-free: components run on the pure path (WidgetsApp + FwTheme).
+  uses-material-design: false
+```
+
+- [ ] **Step 2: Add `apps/gallery` to the root workspace list**
+
+In `pubspec.yaml` (root), under `workspace:`, add the line so it reads:
+
+```yaml
+workspace:
+  - packages/flutterwindcss
+  - packages/flutterwindcss/example
+  - apps/example
+  - apps/gallery
+```
+
+- [ ] **Step 3: Create `apps/gallery/analysis_options.yaml`**
+
+```yaml
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-raw-types: true
+```
+
+- [ ] **Step 4: Create a placeholder `apps/gallery/lib/main.dart`** (replaced in Task 6)
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutterwindcss/flutterwindcss.dart';
+
+void main() => runApp(const GalleryApp());
+
+/// TEMPORARY bootstrap root for the gallery. The structure plan REPLACES this
+/// raw `WidgetsApp` with the flutterbits `Layout` (the gallery's intended root,
+/// which it then demos). Do not entrench this — it is throwaway dev scaffolding.
+class GalleryApp extends StatelessWidget {
+  const GalleryApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return FwTheme(
+      tokens: FwTokens.light,
+      child: WidgetsApp(
+        title: 'flutterbits gallery',
+        color: const Color(0xFF2563EB),
+        debugShowCheckedModeBanner: false,
+        pageRouteBuilder: <T extends Object?>(RouteSettings settings, WidgetBuilder builder) {
+          return PageRouteBuilder<T>(
+            settings: settings,
+            pageBuilder: (context, _, _) => builder(context),
+          );
+        },
+        home: Builder(
+          builder: (context) => ColoredBox(
+            color: context.fw.colors.background,
+            child: const Center(child: Text('flutterbits gallery')),
+          ),
+        ),
+      ),
+    );
+  }
+}
+```
+
+- [ ] **Step 5: Resolve and analyze**
+
+Run: `flutter pub get` (from repo root) then `cd apps/gallery && flutter analyze --fatal-infos --fatal-warnings`
+Expected: deps resolve; analyze reports **No issues found**.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/gallery pubspec.yaml
+git commit -m "feat(gallery): scaffold apps/gallery (flutterbits component target)"
+```
+
+---
+
+## Task 1: `Button` enums + skeleton + first behavior test
+
+**Files:**
+- Create: `apps/gallery/lib/components/ui/button.dart`
+- Create: `apps/gallery/test/button_behavior_test.dart`
+
+- [ ] **Step 1: Write the failing test** (`button_behavior_test.dart`)
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutterwindcss/flutterwindcss.dart';
+import 'package:flutterbits_gallery/components/ui/button.dart';
+
+Widget _host(Widget child) => FwTheme(
+  tokens: FwTokens.light,
+  child: Directionality(
+    textDirection: TextDirection.ltr,
+    child: MediaQuery(
+      data: const MediaQueryData(),
+      child: Center(child: child),
+    ),
+  ),
+);
+
+void main() {
+  testWidgets('renders its label and reports button semantics', (t) async {
+    await t.pumpWidget(_host(Button(onPressed: () {}, child: const Text('Save'))));
+    expect(find.text('Save'), findsOneWidget);
+
+    final semantics = t.getSemantics(find.text('Save'));
+    expect(semantics.hasFlag(SemanticsFlag.isButton), isTrue);
+    expect(semantics.hasFlag(SemanticsFlag.isEnabled), isTrue);
+  });
+}
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: FAIL — `button.dart` / `Button` does not exist (compile error).
+
+- [ ] **Step 3: Write the minimal skeleton** (`button.dart`)
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutterwindcss/flutterwindcss.dart';
+
+/// shadcn's button variants. `primary` is shadcn's `default` (`default` is a
+/// Dart reserved word, so it cannot be an enum constant).
+enum ButtonVariant { primary, secondary, destructive, outline, ghost, link }
+
+/// shadcn's button sizes. `md` is shadcn's `default` size (same reserved-word
+/// reason as above).
+enum ButtonSize { sm, md, lg, icon }
+
+/// A Material-free, themeable button — shadcn parity. Copy-paste source you own.
+///
+/// Sources its own interaction states (hover/focus/pressed/disabled) and styles a
+/// single box through `.tw` using semantic tokens only (AGENTS.md §3.1/§6).
+class Button extends StatefulWidget {
+  const Button({
+    super.key,
+    required this.child,
+    this.onPressed,
+    this.variant = ButtonVariant.primary,
+    this.size = ButtonSize.md,
+    this.semanticLabel,
+  });
+
+  /// The button's content (a `Text`, an icon widget, or a row of both).
+  final Widget child;
+
+  /// Tapped/activated callback. `null` disables the button.
+  final VoidCallback? onPressed;
+
+  final ButtonVariant variant;
+  final ButtonSize size;
+
+  /// Optional accessibility label (defaults to the child's own semantics).
+  final String? semanticLabel;
+
+  /// Whether the button is interactive.
+  bool get enabled => onPressed != null;
+
+  @override
+  State<Button> createState() => _ButtonState();
+}
+
+class _ButtonState extends State<Button> {
+  @override
+  Widget build(BuildContext context) {
+    return Semantics(
+      button: true,
+      enabled: widget.enabled,
+      label: widget.semanticLabel,
+      child: widget.child,
+    );
+  }
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/button.dart apps/gallery/test/button_behavior_test.dart
+git commit -m "feat(button): skeleton + variant/size enums + semantics"
+```
+
+---
+
+## Task 2: Tap and disabled behavior
+
+**Files:**
+- Modify: `apps/gallery/lib/components/ui/button.dart`
+- Modify: `apps/gallery/test/button_behavior_test.dart`
+
+- [ ] **Step 1: Add failing tests**
+
+Append to `button_behavior_test.dart`'s `main()`:
+
+```dart
+  testWidgets('fires onPressed when tapped', (t) async {
+    var taps = 0;
+    await t.pumpWidget(_host(Button(onPressed: () => taps++, child: const Text('Go'))));
+    await t.tap(find.text('Go'));
+    expect(taps, 1);
+  });
+
+  testWidgets('disabled (onPressed null) does not fire and reports disabled', (t) async {
+    await t.pumpWidget(_host(const Button(onPressed: null, child: Text('Nope'))));
+    await t.tap(find.text('Nope'));
+    // No callback to fire; assert it is reported disabled to a11y.
+    final semantics = t.getSemantics(find.text('Nope'));
+    expect(semantics.hasFlag(SemanticsFlag.isEnabled), isFalse);
+  });
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: FAIL — `fires onPressed` fails (no tap wiring yet).
+
+- [ ] **Step 3: Wire the tap detector in `button.dart`**
+
+Replace `_ButtonState.build` with:
+
+```dart
+  @override
+  Widget build(BuildContext context) {
+    final enabled = widget.enabled;
+    return Semantics(
+      button: true,
+      enabled: enabled,
+      label: widget.semanticLabel,
+      child: GestureDetector(
+        behavior: HitTestBehavior.opaque,
+        onTap: widget.onPressed, // null when disabled → inert
+        child: widget.child,
+      ),
+    );
+  }
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: PASS (all four tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/button.dart apps/gallery/test/button_behavior_test.dart
+git commit -m "feat(button): tap + disabled behavior"
+```
+
+---
+
+## Task 3: Keyboard activation (Enter / Space) + focus/hover/press sourcing
+
+**Files:**
+- Modify: `apps/gallery/lib/components/ui/button.dart`
+- Modify: `apps/gallery/test/button_behavior_test.dart`
+
+- [ ] **Step 1: Add a failing keyboard test**
+
+Append to `main()`:
+
+```dart
+  testWidgets('activates via keyboard (Enter) when focused', (t) async {
+    var taps = 0;
+    final focus = FocusNode();
+    addTearDown(focus.dispose);
+    await t.pumpWidget(_host(
+      Focus(focusNode: focus, child: Button(onPressed: () => taps++, child: const Text('K'))),
+    ));
+    focus.requestFocus();
+    await t.pump();
+    // The button's own FocusableActionDetector takes focus on traversal; send Enter.
+    await t.sendKeyEvent(LogicalKeyboardKey.tab);
+    await t.pump();
+    await t.sendKeyEvent(LogicalKeyboardKey.enter);
+    await t.pump();
+    expect(taps, 1);
+  });
+```
+
+Add the import at the top of the test file:
+
+```dart
+import 'package:flutter/services.dart';
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: FAIL — Enter does nothing (no `FocusableActionDetector`/actions yet).
+
+- [ ] **Step 3: Add `FocusableActionDetector` + state sourcing in `button.dart`**
+
+Add `import 'package:flutter/services.dart';` at the top. Replace `_ButtonState` with:
+
+```dart
+class _ButtonState extends State<Button> {
+  bool _hovered = false;
+  bool _focused = false;
+  bool _pressed = false;
+
+  void _set(VoidCallback f) {
+    if (mounted) setState(f);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final enabled = widget.enabled;
+    return Semantics(
+      button: true,
+      enabled: enabled,
+      label: widget.semanticLabel,
+      child: FocusableActionDetector(
+        enabled: enabled,
+        mouseCursor: enabled ? SystemMouseCursors.click : SystemMouseCursors.basic,
+        onShowHoverHighlight: (h) => _set(() => _hovered = h),
+        onShowFocusHighlight: (f) => _set(() => _focused = f),
+        shortcuts: const <ShortcutActivator, Intent>{
+          SingleActivator(LogicalKeyboardKey.enter): ActivateIntent(),
+          SingleActivator(LogicalKeyboardKey.space): ActivateIntent(),
+        },
+        actions: <Type, Action<Intent>>{
+          ActivateIntent: CallbackAction<ActivateIntent>(
+            onInvoke: (_) {
+              widget.onPressed?.call();
+              return null;
+            },
+          ),
+        },
+        child: GestureDetector(
+          behavior: HitTestBehavior.opaque,
+          onTap: widget.onPressed,
+          onTapDown: enabled ? (_) => _set(() => _pressed = true) : null,
+          onTapUp: enabled ? (_) => _set(() => _pressed = false) : null,
+          onTapCancel: enabled ? () => _set(() => _pressed = false) : null,
+          child: widget.child,
+        ),
+      ),
+    );
+  }
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: PASS (all five tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/button.dart apps/gallery/test/button_behavior_test.dart
+git commit -m "feat(button): keyboard activation + hover/focus/press sourcing"
+```
+
+---
+
+## Task 4: Variant + size styling through `.tw` (the visual core)
+
+**Files:**
+- Modify: `apps/gallery/lib/components/ui/button.dart`
+- Modify: `apps/gallery/test/button_behavior_test.dart`
+
+This task adds the styled box. There is no color-assert in widget tests (that is the goldens' job, Task 5); the behavioral test here asserts the styled box is present and the existing behavior still holds.
+
+- [ ] **Step 1: Add a structural test**
+
+Append to `main()`:
+
+```dart
+  testWidgets('renders a single styled box (FwStyled) per variant', (t) async {
+    for (final v in ButtonVariant.values) {
+      await t.pumpWidget(_host(Button(variant: v, onPressed: () {}, child: const Text('x'))));
+      expect(find.byType(FwStyled), findsOneWidget, reason: 'variant $v');
+    }
+  });
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: FAIL — no `FwStyled` in the tree (child is rendered raw).
+
+- [ ] **Step 3: Implement the styling build**
+
+In `button.dart`, replace the `GestureDetector(... child: widget.child)` so its `child:` is the styled box, by inserting a `_styled(context)` helper and using it. Add this method to `_ButtonState` and call it:
+
+```dart
+  /// The single styled box: resolves (variant, size, states) → one `.tw` chain.
+  Widget _styled(BuildContext context) {
+    final c = context.fw.colors;
+    final enabled = widget.enabled;
+
+    // Base treatment per variant (transparent fill uses the one allowed literal,
+    // Color(0x00000000), per AGENTS.md §3.1).
+    const transparent = Color(0x00000000);
+    late Color baseBg;
+    late Color baseFg;
+    Color? borderColor;
+    var isLink = false;
+    switch (widget.variant) {
+      case ButtonVariant.primary:
+        baseBg = c.primary;
+        baseFg = c.primaryForeground;
+      case ButtonVariant.secondary:
+        baseBg = c.secondary;
+        baseFg = c.secondaryForeground;
+      case ButtonVariant.destructive:
+        baseBg = c.destructive;
+        baseFg = c.destructiveForeground;
+      case ButtonVariant.outline:
+        baseBg = transparent;
+        baseFg = c.foreground;
+        borderColor = c.border;
+      case ButtonVariant.ghost:
+        baseBg = transparent;
+        baseFg = c.foreground;
+      case ButtonVariant.link:
+        baseBg = transparent;
+        baseFg = c.primary;
+        isLink = true;
+    }
+
+    // Hover/press treatment (shadcn: filled → /90 (secondary /80); outline/ghost
+    // → accent; link → underline).
+    var bg = baseBg;
+    var fg = baseFg;
+    final interacting = enabled && (_hovered || _pressed);
+    if (interacting) {
+      switch (widget.variant) {
+        case ButtonVariant.primary:
+        case ButtonVariant.destructive:
+          bg = baseBg.withValues(alpha: 0.9);
+        case ButtonVariant.secondary:
+          bg = baseBg.withValues(alpha: 0.8);
+        case ButtonVariant.outline:
+        case ButtonVariant.ghost:
+          bg = c.accent;
+          fg = c.accentForeground;
+        case ButtonVariant.link:
+          break; // underline handled below
+      }
+    }
+    final underlineNow = isLink && enabled && (_hovered || _focused);
+
+    // Content: shrink-wrap width, center vertically within the fixed height.
+    final inner = widget.size == ButtonSize.icon
+        ? Center(child: widget.child)
+        : Center(widthFactor: 1.0, child: widget.child);
+
+    var box = inner.tw
+        .bg(bg)
+        .text(fg)
+        .textSize(FwFontSize.sm.px)
+        .weight(FwFontWeight.medium)
+        .roundedMd;
+
+    box = switch (widget.size) {
+      ButtonSize.sm => box.h(9).px(3),
+      ButtonSize.md => box.h(10).px(4),
+      ButtonSize.lg => box.h(11).px(8),
+      ButtonSize.icon => box.size(10),
+    };
+
+    if (borderColor != null) box = box.border(1, color: borderColor);
+    if (underlineNow) box = box.underline;
+    if (_focused && enabled) {
+      box = box.ring(2, color: c.ring, offset: 2, offsetColor: c.background);
+    }
+    if (!enabled) box = box.opacity(0.5);
+
+    return box;
+  }
+```
+
+Then change the `GestureDetector`'s child from `widget.child` to `_styled(context)`:
+
+```dart
+        child: GestureDetector(
+          behavior: HitTestBehavior.opaque,
+          onTap: widget.onPressed,
+          onTapDown: enabled ? (_) => _set(() => _pressed = true) : null,
+          onTapUp: enabled ? (_) => _set(() => _pressed = false) : null,
+          onTapCancel: enabled ? () => _set(() => _pressed = false) : null,
+          child: _styled(context),
+        ),
+```
+
+- [ ] **Step 4: Run the full behavior suite to verify pass**
+
+Run: `cd apps/gallery && flutter test test/button_behavior_test.dart`
+Expected: PASS (all six tests — label/semantics, tap, disabled, keyboard, styled-box).
+
+- [ ] **Step 5: Analyze (zero-warning bar) + format**
+
+Run: `cd apps/gallery && flutter analyze --fatal-infos --fatal-warnings` then `dart format --line-length 100 lib test`
+Expected: No issues found; formatter makes no further changes after re-run.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/button.dart apps/gallery/test/button_behavior_test.dart
+git commit -m "feat(button): variant/size/state styling via .tw + semantic tokens"
+```
+
+---
+
+## Task 5: Golden coverage (every variant × size × brightness, + focus ring + RTL)
+
+**Files:**
+- Create: `apps/gallery/test/button_golden_test.dart`
+
+> **Golden authority:** goldens are generated/verified on **CI Linux** (AGENTS.md §9). A local `--update-goldens` is **non-authoritative** — generate the baseline locally to author the test, but the committed baseline must come from CI (or be regenerated there). Note this in the PR.
+
+- [ ] **Step 1: Write the golden test**
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutterwindcss/flutterwindcss.dart';
+import 'package:flutterbits_gallery/components/ui/button.dart';
+
+Widget _frame(FwTokens tokens, TextDirection dir, Widget child) => FwTheme(
+  tokens: tokens,
+  child: Directionality(
+    textDirection: dir,
+    child: MediaQuery(
+      data: const MediaQueryData(),
+      child: ColoredBox(
+        color: tokens.colors.background,
+        child: Center(child: Padding(padding: const EdgeInsets.all(16), child: child)),
+      ),
+    ),
+  ),
+);
+
+/// One row per variant; one column per size. Disabled appears in its own row.
+Widget _grid() {
+  Widget cell(ButtonVariant v, ButtonSize s) => Button(
+    variant: v,
+    size: s,
+    onPressed: () {},
+    child: s == ButtonSize.icon ? const Text('+') : Text(v.name),
+  );
+  return Column(
+    mainAxisSize: MainAxisSize.min,
+    children: [
+      for (final v in ButtonVariant.values)
+        Padding(
+          padding: const EdgeInsets.symmetric(vertical: 4),
+          child: Row(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              for (final s in ButtonSize.values)
+                Padding(padding: const EdgeInsets.symmetric(horizontal: 4), child: cell(v, s)),
+            ],
+          ),
+        ),
+      // A disabled row (primary across sizes).
+      Padding(
+        padding: const EdgeInsets.symmetric(vertical: 4),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            for (final s in ButtonSize.values)
+              Padding(
+                padding: const EdgeInsets.symmetric(horizontal: 4),
+                child: Button(size: s, onPressed: null, child: s == ButtonSize.icon ? const Text('+') : const Text('off')),
+              ),
+          ],
+        ),
+      ),
+    ],
+  );
+}
+
+void main() {
+  testWidgets('button grid — light LTR', (t) async {
+    await t.binding.setSurfaceSize(const Size(520, 420));
+    addTearDown(() => t.binding.setSurfaceSize(null));
+    await t.pumpWidget(_frame(FwTokens.light, TextDirection.ltr, _grid()));
+    await expectLater(find.byType(Column).first, matchesGoldenFile('goldens/button_grid_light.png'));
+  });
+
+  testWidgets('button grid — dark LTR', (t) async {
+    await t.binding.setSurfaceSize(const Size(520, 420));
+    addTearDown(() => t.binding.setSurfaceSize(null));
+    await t.pumpWidget(_frame(FwTokens.dark, TextDirection.ltr, _grid()));
+    await expectLater(find.byType(Column).first, matchesGoldenFile('goldens/button_grid_dark.png'));
+  });
+
+  testWidgets('button grid — light RTL (padding/border mirror)', (t) async {
+    await t.binding.setSurfaceSize(const Size(520, 420));
+    addTearDown(() => t.binding.setSurfaceSize(null));
+    await t.pumpWidget(_frame(FwTokens.light, TextDirection.rtl, _grid()));
+    await expectLater(find.byType(Column).first, matchesGoldenFile('goldens/button_grid_rtl.png'));
+  });
+}
+```
+
+- [ ] **Step 2: Generate the baseline locally (to author), then run to verify**
+
+Run: `cd apps/gallery && flutter test --update-goldens test/button_golden_test.dart`
+Then inspect the three PNGs under `apps/gallery/test/goldens/` (open them) and confirm: filled variants show token colors, outline shows a border, link is underlined-on-default? (no — link underlines only on hover/focus, so the static golden shows it plain), disabled row is dimmed, RTL mirrors padding/border.
+Then: `flutter test test/button_golden_test.dart` → Expected: PASS against the just-written baseline.
+
+- [ ] **Step 3: Commit (baseline regenerated on CI)**
+
+```bash
+git add apps/gallery/test/button_golden_test.dart apps/gallery/test/goldens/
+git commit -m "test(button): golden grid (variant x size x brightness + RTL)"
+```
+
+---
+
+## Task 6: Render `Button` in the gallery app + smoke test
+
+**Files:**
+- Modify: `apps/gallery/lib/main.dart`
+- Create: `apps/gallery/test/gallery_smoke_test.dart`
+
+- [ ] **Step 1: Write the failing smoke test**
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutterbits_gallery/main.dart';
+
+void main() {
+  testWidgets('gallery builds and renders without exceptions', (t) async {
+    await t.binding.setSurfaceSize(const Size(800, 1200));
+    addTearDown(() => t.binding.setSurfaceSize(null));
+    await t.pumpWidget(const GalleryApp());
+    await t.pumpAndSettle();
+    expect(t.takeException(), isNull);
+    // Every variant label is on screen.
+    expect(find.text('primary'), findsWidgets);
+  });
+}
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `cd apps/gallery && flutter test test/gallery_smoke_test.dart`
+Expected: FAIL — the placeholder home shows no buttons (`find.text('primary')` finds nothing).
+
+> **Note:** this keeps the **temporary** `WidgetsApp` bootstrap (Task 0) — the structure plan swaps the whole root to `Layout` and turns this into the `Layout` demo. Here we only fill its `home` with the Button gallery.
+
+- [ ] **Step 3: Replace `main.dart`'s `home` with a real Button gallery**
+
+Replace the `home:` `Builder` in `main.dart` with a scrolling gallery:
+
+```dart
+        home: Builder(
+          builder: (context) => ColoredBox(
+            color: context.fw.colors.background,
+            child: SafeArea(
+              child: SingleChildScrollView(
+                padding: const EdgeInsets.all(24),
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    for (final v in ButtonVariant.values)
+                      Padding(
+                        padding: const EdgeInsets.symmetric(vertical: 6),
+                        child: Wrap(
+                          spacing: 12,
+                          runSpacing: 12,
+                          crossAxisAlignment: WrapCrossAlignment.center,
+                          children: [
+                            for (final s in ButtonSize.values)
+                              Button(
+                                variant: v,
+                                size: s,
+                                onPressed: () {},
+                                child: s == ButtonSize.icon ? const Text('+') : Text(v.name),
+                              ),
+                          ],
+                        ),
+                      ),
+                  ],
+                ),
+              ),
+            ),
+          ),
+        ),
+```
+
+Add the import at the top of `main.dart`:
+
+```dart
+import 'components/ui/button.dart';
+```
+
+- [ ] **Step 4: Run to verify pass + analyze + format**
+
+Run: `cd apps/gallery && flutter test test/gallery_smoke_test.dart`
+Expected: PASS.
+Run: `cd apps/gallery && flutter analyze --fatal-infos --fatal-warnings` then `dart format --line-length 100 lib test`
+Expected: No issues; no formatting changes on re-run.
+
+- [ ] **Step 5: Run the full gallery suite**
+
+Run: `cd apps/gallery && flutter test`
+Expected: all tests PASS (behavior + golden + smoke).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/gallery/lib/main.dart apps/gallery/test/gallery_smoke_test.dart
+git commit -m "feat(gallery): render the Button gallery + smoke test"
+```
+
+---
+
+## Task 7: Reconcile docs (charter + AGENTS) for the `default`→`primary`/`md` naming
+
+**Files:**
+- Modify: `docs/superpowers/specs/2026-06-10-flutterbits-charter.md` (§3.2)
+- Modify: `AGENTS.md` (§4 naming, where the variant/size naming is stated)
+
+- [ ] **Step 1: Update charter §3.2** — change the variant/size naming line to record the reserved-word deviation. Replace the bullet that reads "variants `default / secondary / destructive / outline / ghost / link`; sizes `sm / default / lg / icon`" with:
+
+```markdown
+- **Variant/size naming mirrors shadcn**, with one forced deviation: `default` is a **Dart reserved word**, so the shadcn `default` variant is `primary` and the `default` size is `md`. Full set — variants `primary / secondary / destructive / outline / ghost / link`; sizes `sm / md / lg / icon`. Implemented as **typed enums + exhaustive `switch`** (the cva equivalent; AGENTS.md §4).
+```
+
+- [ ] **Step 2: Add a one-line note in AGENTS.md §4** after the variants rule (the line about "Variants are typed enums + exhaustive switch"):
+
+```markdown
+  - Where a shadcn name is a Dart reserved word, deviate minimally and document it: the `default` button variant → `primary`, the `default` size → `md` (`default` cannot be an enum constant). Mirror every other shadcn name verbatim.
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/superpowers/specs/2026-06-10-flutterbits-charter.md AGENTS.md
+git commit -m "docs: record default->primary/md (Dart reserved word) for button"
+```
+
+---
+
+## Self-Review (completed at authoring)
+
+- **Spec coverage:** AGENTS.md §6 component checklist — styled via `.tw` + semantic tokens (Task 4 ✓), typed enums + exhaustive `switch` (Tasks 1/4 ✓), Material-free interaction states via `FocusableActionDetector` (Task 3 ✓), keyboard activation via `ActivateIntent`→`CallbackAction` (Task 3 ✓), visible focus ring using `context.fw.colors.ring` (Task 4 ✓), `Semantics(button:, enabled:, label:)` (Task 1 ✓), directional layout — `.px`/`.roundedMd`/`.border` are directional and covered by the RTL golden (Task 5 ✓), goldens for variant×size×brightness (Task 5 ✓), rendered in `apps/gallery` so CI compiles it (Task 6 ✓). Manifest entry is explicitly deferred to the registry/CLI plan (scope note).
+- **Placeholder scan:** none — every code/test/command step is concrete.
+- **Type consistency:** `ButtonVariant{primary,secondary,destructive,outline,ghost,link}` and `ButtonSize{sm,md,lg,icon}` are used identically in Tasks 1/4/5/6; `_styled`/`_set`/`_hovered`/`_focused`/`_pressed` names are consistent across tasks; `FwFontSize.sm.px`, `FwFontWeight.medium`, and the `.tw` setters (`.h/.px/.bg/.text/.textSize/.weight/.roundedMd/.border/.ring/.opacity/.underline/.size`) match the engine API in `fw_style_ops.dart`.
+- **Reserved-word check:** `primary`/`md` used everywhere (never `default` as an identifier).
diff --git a/docs/superpowers/specs/2026-06-05-flutterwindcss-core-engine-design.md b/docs/superpowers/specs/2026-06-05-flutterwindcss-core-engine-design.md
index 1988ba3..a1f9353 100644
--- a/docs/superpowers/specs/2026-06-05-flutterwindcss-core-engine-design.md
+++ b/docs/superpowers/specs/2026-06-05-flutterwindcss-core-engine-design.md
@@ -28,7 +28,7 @@ Flutter has no structure/style split and no CSS cascade — the widget tree *is*
 
 These are **separate products** in the monorepo, each with its own spec → plan → build cycle. They are not part of the styling engine and their absence here is a scope boundary, not a stub:
 
-- **flutterbits components** (`registry/`) — `FwButton` et al. The engine is their dependency; they are authored against it later.
+- **flutterbits components** (`registry/`) — `Button` et al. (flutterbits components are **unprefixed** — copy-paste source the dev owns; the `Fw` prefix is for engine types only, see AGENTS.md §4 and the flutterbits charter §5.) The engine is their dependency; they are authored against it later.
 - **The theme generator** (`apps/docs`, TypeScript) — the tweakcn→`theme.dart` OKLCH pipeline. Per AGENTS.md §7, color math lives **only** there. This engine consumes `FwTokens`; it never parses or converts CSS color strings.
 - **The registry builder + CLI** (`flutterbits_cli`, `tooling/`).
 - **The docs site + example showcase app** beyond the minimal golden-test harness this engine needs.
diff --git a/docs/superpowers/specs/2026-06-10-flutterbits-charter.md b/docs/superpowers/specs/2026-06-10-flutterbits-charter.md
new file mode 100644
index 0000000..f4f7d29
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-10-flutterbits-charter.md
@@ -0,0 +1,176 @@
+# flutterbits — product charter (identity, taxonomy, platform, catalog)
+
+**Status:** design · **Date:** 2026-06-10 · **Audience:** anyone building the flutterbits component layer.
+**Supersedes/extends:** the "flutterbits" framing in `AGENTS.md` §1, the roadmap note in the coverage doc, and `apps/docs/content/docs/flutterbits/index.mdx`. Companion specs: `2026-06-10-flutterbits-structure-and-routing-design.md` (the structure layer) and `2026-06-10-flutterbits-registry-cli-design.md` (the registry + CLI).
+
+---
+
+## 1. What flutterbits is (the identity, sharpened)
+
+flutterbits is **two things in one library**, and the second one is the differentiator:
+
+1. **shadcn/ui for Flutter** — a registry of **copy-paste components you own** (Button, Card, Input, Dialog…), styled entirely through `flutterwindcss` semantic tokens, fetched via a CLI. This is the trust layer: a dev who knows shadcn finds the familiar set and it just works.
+
+2. **An opinionated "structure" layer that models how app developers think** — `Layout`, `Screen`, navigation, and routing that read like a Next.js / Expo app rather than Flutter's `MaterialApp`/`Scaffold`/`Navigator` ceremony. **No other Flutter UI library ships this.** It is the reason flutterbits is more than "shadcn ported."
+
+> **AGENTS.md §1 reconciliation.** The manual currently calls flutterbits "shadcn/ui for Flutter — copy-paste components." That is necessary but no longer sufficient: flutterbits *also* ships the opinionated structure/app-framework layer above. The identity is **"shadcn's copy-paste components *plus* an opinionated, intention-revealing app skeleton."**
+
+### 1.1 The governing design principle — intention-revealing structure
+
+> The widget tree should read like a **description of the app**, not its plumbing. `Screen`, `Layout`, `header`/`body`/`footer` say *what the thing is*; `MaterialApp`/`Scaffold` say *what framework you imported*. flutterbits models the mental model of a Next.js/Expo developer — **layouts wrap screens, screens compose blocks, blocks compose primitives** — so the code reads top-down as the rendered artifact.
+
+This is consistent with — not a violation of — the engine's Material-free stance: a `Screen` is built from `package:flutter/widgets.dart` primitives + `context.fw`, never a wrapper around `Scaffold`.
+
+### 1.2 The "Material-like" framing
+
+flutterbits' structure layer plays the **role** Material plays — the batteries-included app skeleton you reach for first — **without** Material's visuals or ceremony, and as **copy-paste source you own** (so you can rip it open). It is "the opinionated default way to build a flutterbits app."
+
+### 1.3 The three rules (design north star)
+
+Every flutterbits artifact is held to the author's three rules, in order of weight:
+
+1. **Works good** — complete, correct, accessible, tested (goldens + the `apps/gallery` compile target — the flutterbits component app, separate from the engine's `apps/example`). No demoware.
+2. **Looks good** — semantic-token styled so it reskins with any pasted theme; polished defaults.
+3. **Feels good (most important)** — the API is a joy to write. Minimal concepts, call sites that read like sentences, one idea expressed one way.
+
+These are not decoration; "feels good" is an explicit acceptance criterion. Where two designs are equally correct, the more pleasant-to-write one wins.
+
+---
+
+## 2. Taxonomy — the tiers
+
+Four tiers (the originally-considered "tools" tier is **dropped** — what would have lived there is either a registry *install-type* (`util`), see the registry spec, or belongs in `flutterwindcss`).
+
+| Tier | What it is | shadcn analog | The "feel" |
+|---|---|---|---|
+| **primitives** | Button, Badge, Input, Card, Switch, Dialog… | shadcn components (parity) | trust / familiarity |
+| **structure** | `Layout`, `Screen`, nav, app-shell, routing | *(none — the differentiator)* | "reads like Next.js/Expo" |
+| **blocks** | music-player card, stat grid, charts, auth form, splash | shadcn blocks | "feels like a real app" |
+| **templates** | full app scaffolds wiring all three | *(none)* | "clone-and-go" |
+
+**Altitude rule:** `structure` is a *different altitude* from the engine's layout primitives. `FwRow`/`FwColumn`/`FwGrid` (flutterwindcss) are flex/grid **layout primitives**; `Layout`/`Screen` (flutterbits) are **app-shell semantics** — safe areas, status-bar styling, nav regions, scroll ownership, routing. No overlap.
+
+### 2.1 Components that *re-home* into the structure layer
+
+A naïve clone of shadcn's flat list is wrong for Flutter. Several shadcn "components" are, in flutterbits, expressions of the structure layer rather than standalone primitives:
+
+- **Sheet / Drawer / Dialog** → presentation modes of a `Screen` (`FwPresentation.sheet/dialog/fullScreen`), not separate component APIs. What remains is content + chrome (`SheetHandle`). (See structure/routing spec.)
+- **Sidebar** → `SidebarLayout`, a `Layout` shell (sibling to `TabsLayout`). Structure, not a primitive. (Desktop/web → by-demand, §4.)
+- **Tabs** → splits in two: *navigation* tabs = `TabsLayout` (structure); *in-page* content tabs = a `Tabs` primitive.
+
+---
+
+## 3. The catalog
+
+Organised by tier and by "maps cleanly / re-homes / adapt-by-demand." **None of the by-demand items is impossible** — each has a Flutter idiom and ships when a real need appears (AGENTS.md §11b discipline).
+
+### 3.1 Structure (flutterbits-native — the differentiator)
+
+`Layout`, `Screen`, `TabsLayout`, `SidebarLayout` (by-demand, desktop/web), `TopBar`, `BottomNav` + `NavDestination`, `BackButton`, `SheetHandle`. Routing types (`FwRoute`, `FwRoutePattern`, `FwPresentation`, `FwTransition`). Full design in the structure/routing spec.
+
+### 3.2 Primitives — shadcn parity that maps cleanly to Flutter
+
+Button, Badge, Card, Input, Textarea, Label, Checkbox, RadioGroup, Switch, Slider, Select, Accordion, Alert, Avatar, Progress, Separator, Skeleton, Toggle, ToggleGroup, Tooltip, Popover, DropdownMenu, Tabs (in-page), Collapsible, AspectRatio, Spinner, Pagination, Carousel, Calendar, DatePicker, InputOTP.
+
+- **Variant/size naming mirrors shadcn** for familiarity: variants `default / secondary / destructive / outline / ghost / link`; sizes `sm / default / lg / icon`. Implemented as **typed enums + exhaustive `switch`** (the cva equivalent; AGENTS.md §4).
+- All require `flutterwindcss` (semantic tokens) — that is the whole styling model.
+
+### 3.3 App-feel components shadcn lacks (because shadcn is web-only)
+
+`ThemeToggle`, `Splash`, `PullToRefresh`, `SegmentedControl`, `SearchBar`, `EmptyState`, `ListItem`. Plus the imperative feedback helpers `showConfirm` / `showSheet` / `Toaster` + `showToast`.
+
+### 3.4 Blocks (tier 2 — "feels like an app")
+
+music-player card, stat/metric grid, Chart(s), auth form, profile header, settings list, onboarding carousel. Blocks compose structure + primitives.
+
+### 3.5 shadcn web-centric — adapt or defer (by-demand, none impossible)
+
+Command (⌘K palette), Combobox, DataTable (Flutter wants a different idiom than a web grid), Resizable, Menubar, NavigationMenu, HoverCard (no hover on touch), Breadcrumb, ContextMenu (→ long-press on mobile). Each needs an honest Flutter rethink; scheduled, not refused.
+
+### 3.6 The overlay substrate (cross-cutting dependency)
+
+Popover, DropdownMenu, Tooltip, Select, Combobox, and ContextMenu all sit on the **same** behavioral plumbing — an **anchored overlay** (`OverlayPortal` + `CompositedTransformFollower` + edge-flip positioning, floating above the screen, dismiss-on-outside-tap). This is flutterbits' equivalent of shadcn's Radix dependency.
+
+It is built **once** as a shared **lib util** (`anchor`) — the flutterbits analog of shadcn's `cn.ts`: a predictable, pasted-once file every overlay component imports. It must be built **before** the components that depend on it. (Install mechanics in the registry/CLI spec.) The anchored positioning itself — measuring available space and flipping/shifting placement at viewport edges — is **real work the eventual `anchor` spec owns** (feasible, not free; §12). `OverlayPortal`/`CompositedTransformFollower` are in `widgets.dart`, so the substrate is buildable Material-free.
+
+---
+
+## 4. Platform — mobile-first, portable, matures by demand
+
+**Decision: mobile-first as the design *center*; portable but not desktop-tuned.**
+
+- **Design center = phones.** Touch targets ≥ ~44px, safe-area aware, `TabsLayout`/`BottomNav` + sheets are the default navigation idioms, status-bar styling is first-class.
+- **Portable, not exclusive.** Every component still *runs* on web/desktop (they are plain widgets) and keeps full **keyboard + focus-ring + `Semantics` accessibility** (AGENTS.md §6 requires this regardless of platform). They are simply not *optimized* for desktop density/hover.
+- **Hover is enhancement-only** — never required to operate anything, so touch loses nothing.
+- **Catalog impact.** `TabsLayout`/`BottomNav` are v1 core; `SidebarLayout` and the desktop-centric shadcn set (§3.5) are **by-demand**, not v1.
+- **Tablets / large phones** — *styling* reuses the engine's existing responsive + container-query variants (no new work there). Adaptive *navigation* (rail/sidebar, multi-pane, master-detail) is **structure-layer work, by-demand** — `.tw` breakpoint variants restyle a box, they do not restructure the shell — see `SidebarLayout`. (Corrected 2026-06-10: an earlier "no new work" blanket was a silent scope reduction — §12.)
+- **Maturation.** Desktop/web become first-class "with need" — the §11b "feasible, scheduled" framing, not a "can't."
+
+**Boundary (no drift):** this is a **flutterbits** stance only. **`flutterwindcss` stays fully platform-agnostic** (the universal styling engine), and the **web theme generator is unaffected** (a build-time web tool). Mobile-first describes how the *components* are designed, not the engine.
+
+---
+
+## 5. Naming — unprefixed components, `Fw` engine
+
+- **flutterbits components are unprefixed**: `Button`, `Card`, `Badge`, `Screen`, `Layout`. This is the shadcn DX, and these are **source you own** (copied into your project), so they need no namespace.
+- **`flutterwindcss` engine types stay `Fw`-prefixed**: `FwColumn`, `FwTokens`, `FwBreakpoint`. The **flutterbits structure *value types*** that ship as library code also carry `Fw` (they are not components a dev composes): `FwRoute`, `FwRoutePattern`, `FwPresentation`, `FwTransition`, `FwStatusBar`. `FwStatusBar` is a **flutterbits** type — it wraps `package:flutter/services.dart`'s system-UI overlay style; it is **not** an engine type (the engine never touches `services.dart`). When you see `Fw` in a flutterbits component, that is the engine *or* a structure value type showing through — never a component.
+
+> **AGENTS.md §4 reconciliation.** "Public types are prefixed `Fw`" is an **engine** rule (`flutterwindcss`). It does **not** apply to flutterbits *components*, which are deliberately unprefixed (copy-paste, shadcn-style). The routing/structure *base types* that ship as library code (e.g. `FwRoute`, `FwPresentation`) keep `Fw`; the *components* a dev composes (`Screen`, `Layout`, `Button`) do not.
+
+### 5.1 The name-clash, handled honestly
+
+There are **two** clash surfaces — and an earlier draft of this section wrongly claimed only one existed. Corrected 2026-06-10 (verified against the Flutter SDK):
+
+1. **`package:flutter/widgets.dart` itself** — which *every* flutterbits app imports — exports some common nouns: `Form`/`FormField`, `Icon`, `Image`, `Table`, `Title`, `Navigator`, `Page`, `Visibility`, `Spacer`, `Semantics`, `Builder`, `Actions`, `Overlay`, `OverlayPortal`, `Banner`. A component named `Form`/`Icon`/`Image`/`Table` **would collide even in a Material-free app**. (The prior "zero clashes in the intended world" claim was false.)
+2. **`package:flutter/material.dart`** additionally defines `Card`, `Badge`, `Switch`, `Slider`, `Checkbox`, `Drawer`, `Tooltip`, `BackButton`. These clash **only** in the rare Material-interop case (possible because flutterwindcss can theme Material via the `FwThemeExtension` bridge). Verified **absent** from `widgets.dart` (so clash-free in a pure app): `Button`, `Card`, `Badge`, `Input`, `Dialog`, `Sheet`, `Switch`, `Slider`, `Checkbox`, `Tooltip`, `Tabs`, `Layout`, `Screen`.
+
+**Hard authoring rule (MUST):** every component name is checked against `package:flutter/widgets.dart` **before it ships**. A name that collides there is **renamed** — the dev cannot avoid importing `widgets.dart`, so `widgets.dart` wins (e.g. an icon wrapper is `Lucide`/`Img`, not `Icon`/`Image`; a data grid is `DataTable`, not `Table`; there is no `Form` component — auth screens compose `Input`s directly). The shadcn set is overwhelmingly clash-free; the handful that aren't get a distinct name. (This is why the catalog §3.2/§3.5 names `DataTable`, never `Table`, and lists no `Form`/`Icon`/`Image` component.)
+
+**Material interop** is then handled by the **barrel** (`ui.dart`) as an escape hatch: `import 'components/ui/ui.dart' as ui;` → `ui.Card`, `ui.Button` — explicit namespacing on demand, with no `Fw` noise forced on the common case.
+
+This is still better than prefixing every component `Fw` (which would make the engine and components look identical and kill the shadcn feel); the cost is a naming-discipline rule, not a global prefix.
+
+---
+
+## 6. Dependency policy
+
+- **Core stays dependency-free.** Primitives (Button, Card, Input…) need only `widgets.dart` + `flutterwindcss`. A copied `Button` drags in nothing.
+- **Sanctioned deps are declared per-component in the manifest `pubDeps`**, never globally — exactly as shadcn lists a component's npm deps:
+  - **`lucide_icons_flutter`** (sanctioned) — icons.
+  - **`flutter_animate`** (sanctioned, AGENTS.md §11b) — the motion layer. Toast slide-in, Skeleton shimmer, Accordion/Collapsible expand, Splash, the `ThemeToggle` icon crossfade compose it. The engine deliberately ships no element-animation subsystem; components own their state machines and animate with `flutter_animate`.
+  - **`go_router`** (newly sanctioned — see §6.1) — the routing engine the structure layer wraps.
+  - **`flutter_svg`** — **by-demand**, only on blocks that render real SVG illustrations (illustrated `EmptyState`, onboarding art). Not core; most things use lucide or simple shapes.
+- **The payoff:** `add button` installs zero deps; `add toast` installs `flutter_animate`; `add layout` installs `go_router` (+ `lucide_icons_flutter` and `flutter_animate` — the structure layer's full `pubDeps` set; see structure spec §7). Every component is honest about exactly what it costs.
+
+### 6.1 `go_router` — newly sanctioned dependency (justification)
+
+> **AGENTS.md §12 reconciliation.** §12 lists `lucide_icons_flutter` and `flutter_animate` as sanctioned; **`go_router` is added** as a sanctioned dep for the structure layer. Justification: building a router de-novo over Navigator 2.0 is a tar pit and violates "don't rebuild what works"; `go_router` is the Flutter-team-endorsed router and provides deep links, web URLs, and `ShellRoute` (persistent shells) for free. flutterbits **wraps** it in a thin, typed, intention-revealing face — it does not fork it. The router engine is a trusted dependency; only the ergonomic wrapper is owned. `go_router` is a `pubDep` of the structure components **only** — it never touches `flutterwindcss`.
+
+---
+
+## 7. Where everything lives (package vs registry)
+
+- **`flutterwindcss` stays styling-only** (tokens + utilities + `FwRow`/`FwColumn`/`FwGrid`). It never learns routing, components, or app-shell concepts exist. Folding any of that in would blur "the Tailwind layer" and force unrelated deps (e.g. `go_router`) onto token-only users.
+- **`flutterbits` is copy-paste source** (the registry): primitives, structure (`Layout`/`Screen`/routing), blocks, templates, and `util`s (`anchor`, overlay helpers). Components **import** `flutterwindcss` (which is why flutterbits cannot work without it) and declare `pubDeps` for anything else.
+- **No new runtime package is introduced for v1.** Routing is copy-paste source + a `go_router` `pubDep`, not a new published package. If a genuinely shared runtime emerges later, it is promoted to a package then — not pre-emptively.
+
+---
+
+## 8. Decomposition & sequencing
+
+This charter is the umbrella. Implementation is decomposed into specs, each its own spec → plan → build cycle:
+
+1. **This charter** — identity, taxonomy, platform, catalog, naming, deps. *(done)*
+2. **`2026-06-10-flutterbits-structure-and-routing-design.md`** — `Layout`, `Screen`, routing, presentations, navigation DX.
+3. **`2026-06-10-flutterbits-registry-cli-design.md`** — manifest schema, install-types, `init`/`add`/`diff`, barrel regen, `flutterbits.json`, hosting.
+4. **Per-component specs** — small, one component (or tight group) each, with `button` as the canonical template.
+
+**First vertical slice (proves the whole stack end-to-end):** `Layout` + `Screen` + routing + `Button` + `ThemeToggle`, rendered in **`apps/gallery`** — a **new** flutterbits component showcase + golden/compile target, created with this slice and kept separate from the engine's `apps/example` (decision 2026-06-10). `ThemeToggle` is the chosen first concrete component — tiny, pure "feel good," and it forces every layer to play together (`Layout` owning theme → the `Switch` primitive → semantic-token reskin → the engine's `FwAnimatedTheme` transition).
+
+---
+
+## 9. Open questions (deferred, by explicit decision)
+
+- **State management / data conventions** — deferred. flutterbits blesses **no** controller/view-model/folder-structure pattern in v1; Screens stay pure UI. Conventions are introduced later "when we have earned the right to impose them" (recorded decision, 2026-06-10). This is a deliberate de-scope, not an omission.
+- **`SidebarLayout` and the desktop-centric set** — by-demand (§4).
+- **Codegen routing** — explicitly rejected for v1 (forces `build_runner` on every consumer; awkward in a copy-paste model). The typed hand-written route is the chosen DX. May be offered as an *optional* layer later — capability-raising, not locked out.
diff --git a/docs/superpowers/specs/2026-06-10-flutterbits-registry-cli-design.md b/docs/superpowers/specs/2026-06-10-flutterbits-registry-cli-design.md
new file mode 100644
index 0000000..e892961
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-10-flutterbits-registry-cli-design.md
@@ -0,0 +1,158 @@
+# flutterbits — registry & CLI (design)
+
+**Status:** design · **Date:** 2026-06-10 · **Audience:** implementers of the `flutterbits` CLI and registry tooling.
+**Parent:** `2026-06-10-flutterbits-charter.md`. **Sibling:** `2026-06-10-flutterbits-structure-and-routing-design.md`.
+**Extends:** `AGENTS.md` §8 (registry & CLI) — adds `init`, the barrel, install-types, and `flutterbits.json` that §8 did not yet specify.
+
+---
+
+## 1. Model recap (the copy-paste contract)
+
+Components are **source the developer owns**, not a versioned dependency. The CLI fetches a component's files from a **registry** into the host project; the dev reads and edits freely. `registry/*.dart` is the **single source of truth**; JSON manifests are **generated** from it, never hand-edited (AGENTS.md §8).
+
+---
+
+## 2. Install-types (the shadcn `registry:ui`/`lib`/`hook` analog)
+
+The registry needs to know *what kind* of thing each item is so the CLI places it in the right predictable path. Three types:
+
+| `type` | Default target | Purpose | In barrel? |
+|---|---|---|---|
+| `component` | `lib/components/ui/<name>.dart` | a primitive / structure / block / template | yes |
+| `util` | `lib/components/ui/_utils/<name>.dart` | shared lib utility (the `anchor`/overlay substrate, formatters, the `cn`-equivalents, `showConfirm`/`showSheet`/`showToast`) | only if `exported: true` |
+| `barrel` | `lib/components/ui/ui.dart` | the regenerated re-export file (managed by the CLI; never authored) | n/a |
+
+**On "hooks":** Flutter has no native hook concept (`flutter_hooks` is a separate dep we are **not** taking — charter §6). What shadcn calls `registry:hook` is, here, a plain Dart `util` — a utility / widget / extension. Same *role*, different mechanism.
+
+### 2.1 The `anchor` util = flutterbits' `cn.ts`
+
+In shadcn, `cn()` lives in a predictable `lib/utils.ts` every project has, and components import it. The flutterbits analog is the **overlay substrate** (`anchor`): the anchored-overlay behavior (`OverlayPortal` + `CompositedTransformFollower` + edge-flip positioning) that Popover, DropdownMenu, Tooltip, Select, Combobox, and ContextMenu all share (charter §3.6). It is a `util`, pasted once into `_utils/anchor.dart`, pulled in as a `registryDep` by every overlay component, and **built before** them.
+
+`anchor` is **internal** (`exported: false`): components import it by relative path; it does not appear in the barrel. Dev-facing helpers like `showConfirm`/`showToast` are `util`s with `exported: true`.
+
+---
+
+## 3. Manifest schema (extends AGENTS.md §8)
+
+```jsonc
+{
+  "name": "popover",
+  "type": "component",            // component | util  (barrel is CLI-managed, not authored)
+  "description": "An anchored floating panel.",
+  "exported": true,               // does the barrel re-export it? (components: true; internal utils: false)
+  "pubDeps": ["flutter_animate"], // pub packages to `flutter pub add`
+  "registryDeps": ["anchor"],     // other registry items to install first (recursive)
+  "files": [
+    { "path": "popover.dart", "type": "component", "target": null, "content": "<dart source>" }
+  ]
+}
+```
+
+- `type`/`target` per **file** lets one item ship files to different predictable locations; `target: null` uses the type default (§2). A `target` override allows custom paths for advanced cases.
+- `registryDeps` resolves inter-item needs recursively (e.g. `dialog` → `button`; `popover` → `anchor`). `pubDeps` are real pub packages.
+- Manifests are produced by `tooling/build_registry.dart` **from** `registry/*.dart` — `content` is never hand-edited (AGENTS.md §8).
+- **Versioning (recorded decision, 2026-06-10).** v1 manifests carry **no** revision/version field, and `diff` (§5.3) compares the dev's copy against the **current** registry source — the same model, and the same limitation, as shadcn. There is no recorded baseline of "which upstream revision I copied from," so `diff` cannot perfectly separate *upstream changes since I copied* from *my own edits*; it shows the full delta and the dev judges. Accepted for v1; a per-file `revision` hash may be added later (capability-raising, not required now). This is a deliberate scope bound, not an oversight.
+
+---
+
+## 4. `flutterbits.json` (the project config — shadcn `components.json` analog)
+
+`init` writes this to the project root; every other command reads it. It records where things go so the CLI never guesses:
+
+```jsonc
+{
+  "registry": "https://flutterbits.vercel.app/r",  // registry endpoint (served by apps/docs)
+  "componentsDir": "lib/components/ui",
+  "utilsDir": "lib/components/ui/_utils",
+  "barrel": "lib/components/ui/ui.dart",
+  "theme": "lib/theme.dart",                        // where the generated theme.dart lives
+  "interop": false                                   // true if the app also uses Material (affects nothing yet; reserved)
+}
+```
+
+---
+
+## 5. Commands
+
+### 5.1 `flutterbits init`
+
+Scaffolds a flutterbits-ready project:
+
+1. Ensures `flutterwindcss` is a dependency (`flutter pub add flutterwindcss`).
+2. Creates `lib/components/ui/` and `lib/components/ui/_utils/`.
+3. Writes a starter `theme.dart` at the configured `theme` path — a default `FwTokens` light/dark in **exactly the shape the `apps/docs` generator emits** (AGENTS.md §7), so that regenerating from a pasted tweakcn theme is a **drop-in file replacement** at `flutterbits.json.theme`, requiring no component edits (AGENTS.md §7's "drop-in" guarantee). The CLI never does color math (that lives only in `apps/docs`); it just writes the default file.
+4. Writes an initial barrel `ui.dart` (empty export list, with the generated-file header).
+5. Optionally scaffolds a starter `Layout` (root wiring) so `runApp` is intention-revealing from line one.
+6. Writes `flutterbits.json`.
+
+### 5.2 `flutterbits add <name> [<name>…]`
+
+1. Fetch the manifest(s) from `registry`.
+2. Resolve `registryDeps` **recursively** (so `add popover` also installs `anchor`; `add dialog` also installs `button`); de-duplicate.
+3. Write each file to its `type`/`target`-determined path (§2). Refuse to clobber a modified file without `--overwrite` (the dev owns it).
+4. `flutter pub add` every collected `pubDep`.
+5. **Regenerate the barrel** (§6).
+6. `dart format --line-length 100` the written files.
+
+### 5.3 `flutterbits diff <name>`
+
+The copy-paste **survival mechanism**: shows what changed in the upstream registry version **vs the dev's local copy**, so they can merge upstream improvements (bug fixes, new variants, a11y fixes, Flutter-API-driven changes) **on their own terms**. It **does not auto-merge** — the dev may have customized their copy; merging is their call (like reviewing a PR against a fork). This is why a single canonical `registry/*.dart` source matters: `diff` always has one version to compare against.
+
+### 5.4 `flutterbits remove <name>` (by-demand)
+
+Removes a component's files and **regenerates the barrel**. Leaves `pubDeps` in place by default (other components may share them); `--prune-deps` to attempt removal of now-unused deps. Scheduled by-demand, not v1-blocking.
+
+---
+
+## 6. The barrel (`ui.dart`) — regeneration rules
+
+The barrel is the convenience the dev wanted: import the whole component set from one place instead of file-by-file.
+
+- **Fully regenerated** by the CLI on every `add`/`remove` — **never hand-edited**. It carries a header making that explicit:
+  ```dart
+  // GENERATED BY flutterbits — do not edit. Run `flutterbits add/remove` to update.
+  export 'button.dart';
+  export 'card.dart';
+  export 'theme_toggle.dart';
+  export 'screen.dart';
+  export 'layout.dart';
+  export '_utils/overlays.dart';   // exported helper util (showConfirm/showSheet/showToast)
+  ```
+- **Exports `exported: true` items only** — every `component`, plus dev-facing `util`s. **Internal utils** (`anchor`) are imported directly by the components that need them and are **not** in the barrel (keeps plumbing out of the public surface, so no `show`-clause gymnastics are needed).
+- **Usage:** `import 'package:my_app/components/ui/ui.dart';` — one import for all installed components.
+- **No barrel name collisions.** The hard authoring rule (charter §5.1) guarantees **no exported component name collides with `package:flutter/widgets.dart`** (the rule that bans a `Form`/`Icon`/`Image`/`Table` component), so a wildcard `export` is always safe to import alongside `widgets.dart`. Registry item names are unique, so two components never export the same top-level symbol either. (If a future exception ever forced it, the barrel would emit `export 'x.dart' hide <sym>;` — but the standing rule is to **rename at authoring time**, not paper over with `hide`.)
+- **Interop escape hatch (charter §5.1):** a dev mixing Material in can namespace the whole set — `import '.../ui/ui.dart' as ui;` → `ui.Card`, `ui.Button` — resolving any *Material* name clash explicitly, with no `Fw` prefix forced on the common case. The barrel thus doubles as the Material-clash resolver.
+
+---
+
+## 7. Hosting & tooling
+
+- **Registry source of truth:** `registry/*.dart` (one component per file; no barrel that re-exports registry components — they are copied individually, AGENTS.md §4/§8).
+- **Manifest build:** `dart run tooling/build_registry.dart` generates the JSON manifests from the Dart source (AGENTS.md §10 "planned commands").
+- **Registry endpoint:** served by `apps/docs` (the Next.js site already plans a registry endpoint, AGENTS.md §2). The CLI's `registry` URL points at it. Each component also gets a docs page with source + a Copy button (shadcn-style).
+- **CLI package:** `packages/flutterbits_cli` (Dart), exposing the `flutterbits` command (AGENTS.md §2). The CLI **fetches components only** — it does **no** color math or theme generation (that lives solely in `apps/docs`; AGENTS.md §7).
+
+### 7.1 Component previews (how a dev sees it before copying) — decided 2026-06-10
+
+shadcn shows *live* previews because its components **are** the web; flutterbits components are Flutter, so a React reimplementation would show a **different artifact than the one copied** — **rejected** (it would be a fake). Both supported previews render the **real** component:
+
+- **(A) Golden images — the always-on default.** Every component already ships `variant × size × brightness` goldens (AGENTS.md §9). The docs surface those PNGs directly: **100% faithful** (the image *is* the CI-tested render), instant, SEO-friendly, zero runtime cost. This is the primary preview on every component page.
+- **(C) DartPad embeds — live + editable, where deps allow.** An official Flutter live-editor iframe runs the **real** Dart: `flutterwindcss` (pub-published) as a dependency + the component source inlined + a tiny demo `main`. Because the component is copy-paste source, the embed *is* the code you copy — preview and source are the same artifact. **Verify per component:** DartPad's pub support must cover that component's `pubDeps` (`flutterwindcss` is fine; confirm `go_router`/`flutter_animate`/`lucide_icons_flutter` before relying on a live embed — otherwise fall back to the golden image).
+
+**Deferred (not rejected):** (B) a single Flutter-Web gallery (one CanvasKit build, lazy iframe) for richer interaction — added by-demand if A+C prove insufficient.
+
+---
+
+## 8. Build/verify discipline (inherited)
+
+- A component is "done" per AGENTS.md §6: styled through `.tw` with semantic tokens, typed-enum variants with exhaustive `switch`, Material-free interaction states, keyboard + focus ring, `Semantics`, directional layout, a manifest entry (§3), goldens for every variant × size × brightness in `apps/gallery` (the flutterbits component target — not the engine's `apps/example`), and rendered there so CI compiles it.
+- `diff` correctness depends on the canonical `registry/*.dart` source staying authoritative; the manifest's `content` is always regenerated, never edited (§3).
+
+---
+
+## 9. Sequencing
+
+1. **Registry plumbing first** — `tooling/build_registry.dart`, the manifest schema (§3), `flutterbits.json` (§4), and the `apps/docs` registry endpoint.
+2. **CLI** — `init`, `add` (with recursive `registryDeps` + barrel regen), `diff`. `remove` by-demand.
+3. **First vertical slice** (charter §8) — `Layout` + `Screen` + routing + `Button` + `ThemeToggle`, installed via the real CLI into **`apps/gallery`**, proving manifest → fetch → place → barrel → compile → golden end-to-end. (`apps/gallery` is a **new** flutterbits component app — created with this work, carrying its own `flutterbits.json` — kept separate from the engine's `apps/example`, decision 2026-06-10. The very first component, however, may be authored + golden-tested in `apps/gallery` directly before the CLI exists; the CLI then proves the install path.)
+4. **The overlay `anchor` util** before any overlay component (Popover/Dropdown/Tooltip/Select/Combobox/ContextMenu).
diff --git a/docs/superpowers/specs/2026-06-10-flutterbits-structure-and-routing-design.md b/docs/superpowers/specs/2026-06-10-flutterbits-structure-and-routing-design.md
new file mode 100644
index 0000000..98f0a81
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-10-flutterbits-structure-and-routing-design.md
@@ -0,0 +1,329 @@
+# flutterbits — structure layer & routing (design)
+
+**Status:** design · **Date:** 2026-06-10 · **Audience:** implementers of the flutterbits structure layer.
+**Parent:** `2026-06-10-flutterbits-charter.md`. **Sibling:** `2026-06-10-flutterbits-registry-cli-design.md`.
+
+This spec designs the **differentiator**: the opinionated, intention-revealing app skeleton (`Layout`, `Screen`) and the routing that wraps `go_router`. All names are unprefixed *components* the dev composes; `Fw`-prefixed types are routing/engine **library** types (charter §5).
+
+---
+
+## 1. Philosophy recap (the bar this design must clear)
+
+- **Intention-revealing** — `Layout`, `Screen`, `header`/`body`/`footer` read like the rendered artifact (charter §1.1).
+- **Composition, not inheritance** — components are **widgets you return**, never base classes you extend. This is the single most important API decision in this spec (§2.1).
+- **Feels good** — one concept expressed one way; a sheet is "a `Screen` mounted differently," not a separate API (§4).
+- **Material-free** — built on `package:flutter/widgets.dart` + `context.fw`; never `Scaffold`/`MaterialApp`/`Navigator` directly in component code (the router wrapping is the one place `go_router` — itself Material-free-capable — is touched).
+
+---
+
+## 2. The vocabulary
+
+```
+Layout      ← app root. Holds config: theme, router, global providers.
+            ← "the better MaterialApp." Also nestable (a section Layout =
+            ← persistent chrome: bottom nav / sidebar).
+  └─ Screen ← a routable destination. Owns screen-level concerns: safe area,
+            ← status-bar style, header/footer regions, scroll ownership,
+            ← background. "the better Scaffold." This is what the router targets.
+       └─ blocks → primitives
+```
+
+`Page` was considered and **dropped**: a universal `Screen` covers mobile/desktop/web ("everyone knows what a screen is"), and a sub-`Screen` concept was unnecessary surface.
+
+### 2.1 Composition, not inheritance — the decision that dissolves `ScreenSpec`
+
+An earlier sketch had `Screen` as a **base class** whose `build` returned a *description* object (`ScreenSpec`). That forces a non-widget return type — the smell that made the name feel wrong. **Rejected.**
+
+`Screen` and `Layout` are **composed widgets you return**:
+
+- `Screen` is "the better `Scaffold`" — screen-level concerns are **intention-revealing named slots** (`header`/`body`/`footer`) plus props (`statusBar`, `background`).
+- `Layout` is "the better `MaterialApp`" — you return `Layout(theme:, routes:, shell:)`; there is no `LayoutConfig` return object.
+- A screen's **identity** comes from its file + its route, **not** a base class. So there is no `ScreenSpec`, no `extends Screen`, nothing un-Flutter.
+
+**Why this is the strongest design:** zero new return-type concepts; plays with `const`; the slots read like semantic HTML; defaults are semantic-token-aware; `Screen`s stay plain widgets droppable anywhere (the root `Layout` is the one exception — it hosts the app + router, see §3.1). The "framework feel" comes from the *vocabulary*, not from inheritance.
+
+No base class is introduced in v1 (no lifecycle hooks, no view-model binding — that is the deferred state-management decision, charter §9). A screen is an ordinary `StatelessWidget`/`StatefulWidget` that returns a `Screen`.
+
+---
+
+## 3. `Layout` and `Screen` — the API
+
+### 3.1 `Layout` (root)
+
+```dart
+/// The app root. Config lives here; everything renders inside it.
+class AppLayout extends StatelessWidget {
+  const AppLayout({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Layout(
+      theme: appTheme,                 // generated FwTokens (light/dark) — see charter
+      title: 'Tunes',
+      // A nested layout: a persistent shell across the screens inside it.
+      shell: TabsLayout(
+        destinations: const [
+          NavDestination(icon: LucideIcons.house, label: 'Home',    route: HomeRoute.pattern),
+          NavDestination(icon: LucideIcons.user,  label: 'Profile', route: ProfileRoute.pattern),
+        ],
+      ),
+      routes: const [HomeRoute.pattern, ProfileRoute.pattern],  // the table, in plain sight
+      redirect: _authRedirect,         // optional global guard (§5.2)
+    );
+  }
+}
+```
+
+- `theme` — the `FwTokens` light/dark bundle; `Layout` owns the light↔dark swap and drives the engine's `FwAnimatedTheme` so a toggle crossfades every `context.fw`-styled descendant.
+- `shell` — an optional nested `Layout` (`TabsLayout`/`SidebarLayout`) providing persistent chrome. Maps to `go_router`'s `ShellRoute`.
+- `routes` — the explicit route table (a plain `const` list of `FwRoutePattern`s; no codegen).
+- **Root `Layout`** constructs the `go_router` configuration **and** the root `WidgetsApp.router`-family widget (Material-free). `runApp(const AppLayout())` works directly — the root `Layout` *is* the app.
+- **Nested `Layout`** (one passed as `shell:`) is a **different role**: it compiles to a `go_router` `ShellRoute`/`StatefulShellRoute` **builder** that wraps the routed child with persistent chrome. It **must not** re-host a router or app widget. (The `shell:` value is a `Layout`-typed *description* the root translates into a `ShellRoute` builder; it is not itself a second app.)
+- **Invariant (MUST):** exactly **one** root `Layout` hosts the app + router; every other `Layout` is a shell builder. The shared `Layout` name is deliberate vocabulary, but the two roles are distinct and the implementation keeps them separate. A `Layout` is therefore *not* "droppable anywhere" — it is either the root or a shell; only `Screen`s and below are freely composable. (Resolves the earlier ambiguity flagged in review — a returned widget that *is* the root router cannot also be an arbitrary child.)
+
+### 3.2 `Screen` (destination) — slots
+
+```dart
+class HomeScreen extends StatelessWidget {
+  const HomeScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Screen(
+      statusBar: FwStatusBar.lightIcons,
+      background: context.fw.colors.background,
+      header: TopBar(title: const Text('Home')),     // <header>
+      body:   FwColumn(gap: 4, children: [...]),       // <main>
+      footer: null,                                    // <footer> (e.g. a CTA bar)
+    );
+  }
+}
+```
+
+| Slot/prop | Role | Maps to |
+|---|---|---|
+| `header` | top region (title, actions, back) | `<header>` — a `TopBar`, or any widget |
+| `body` | the screen's main content | `<main>` |
+| `footer` | bottom region (CTA bar, nav) | `<footer>` |
+| `statusBar` | `FwStatusBar` style enum | system-UI overlay style via `services.dart` (a flutterbits concern, Material-free) |
+| `background` | screen fill (semantic token) | the page background |
+
+`Screen` owns **safe-area insets**, scroll ownership conventions, and status-bar styling so the dev declares intent, not plumbing.
+
+### 3.3 Naming pass (the types a dev sees most)
+
+| Concept | Name | Why not the obvious |
+|---|---|---|
+| App root / nestable shell | `Layout` | — |
+| Routable destination | `Screen` | — |
+| Top bar widget | `TopBar` | not `AppBar` (Material-loaded) |
+| Persistent bottom-nav shell | `TabsLayout` (a `Layout`) | nested layout = persistent chrome |
+| Sidebar shell (by-demand) | `SidebarLayout` (a `Layout`) | desktop/web; charter §4 |
+| Slots | `header` / `body` / `footer` | web-native; reads as the artifact |
+| Status-bar style | `FwStatusBar` | flutterbits structure value type (`Fw`, like `FwPresentation`); wraps `services.dart` `SystemUiOverlayStyle` — flutterbits's, **not** the engine's |
+| Back affordance | `BackButton` | unprefixed; typed `pop`. *Clashes with Material's `BackButton` under interop → resolve via the barrel namespace (charter §5.1).* |
+| Sheet grabber | `SheetHandle` | used by sheet-presented screens |
+
+---
+
+## 4. Routing
+
+**Decision: wrap `go_router` (do not build a router).** **Decision: typed route objects, hand-written, NO codegen** (the rejected codegen alternative is recorded in charter §9). The router engine is a trusted `pubDep`; flutterbits owns only the thin typed face.
+
+### 4.1 The two route types
+
+The route concept is split for ergonomics — the **navigation token** stays dead-simple; the **definition** holds every route fact in one obvious place.
+
+```dart
+// Navigation token: just typed args + where it lives.
+class ProfileRoute extends FwRoute {
+  const ProfileRoute({required this.userId});
+  final int userId;
+
+  @override
+  String get location => '/profile/$userId';     // concrete path (navigation side)
+
+  // The definition: path pattern + builder + presentation/transition/guard.
+  static final pattern = FwRoutePattern(
+    '/profile/:userId',
+    builder: (s) => ProfileScreen(userId: int.parse(s.params['userId']!)),
+  );
+}
+```
+
+- `FwRoute` (instance) = the typed navigation token. Carries args, exposes `location`, and the navigation verbs (§4.2).
+- `FwRoutePattern` (static `pattern`) = the registration-time definition: `path`, `builder` (parses `FwRouteState` → `Screen` widget), the optional `present` / `transition` / `guard` (§4.3–§4.5), and `children:` for **nested** routes (§4.3.1 — required for sheets that layer over a parent). One home for route facts; no redundancy between instance and definition.
+- The hand-written cost is honest: ~3 lines per screen (`location` + `pattern` + the param-parse). In exchange: **zero build step**, a **self-contained copy-paste unit** (the `Screen` and its route in one file), a **readable route table**, and a **visible param-parse** you can customize. (The trade vs codegen is recorded in the charter; this is the chosen side.)
+
+### 4.2 Navigation verbs
+
+```dart
+ProfileRoute(userId: 42).go(context);       // replace location (go_router `go`)
+ProfileRoute(userId: 42).push(context);     // push on the stack
+final picked = await ContactPickerRoute().push<Contact>(context);  // typed result back
+context.pop();                              // BackButton calls this; auto-hidden if can't pop
+```
+
+`push<T>` returns a typed `Future<T?>`; a presented screen returns a value with `context.pop(result)`.
+
+**Wiring:** the verbs are thin typed wrappers over `go_router` — `route.go(context)` ≡ `context.go(route.location)`, `route.push<T>(context)` ≡ `context.push<T>(route.location)`. The instance only needs its `location`; the matching `FwRoutePattern` (and its `present`/`transition`) is resolved by **path-match in the router**, not by the instance. **Web caveat (a genuine limitation, not effort):** a typed `push<T>` result requires a live in-app push that the user returns *from*. A cold deep-link, a browser refresh, or browser-back to a route has no pusher, so `await …push<T>()` may complete `null` on web — design result-bearing flows to also work without a result.
+
+### 4.3 Presentations — "a sheet is a `Screen` mounted differently" (the feel-good core)
+
+A single `present` knob on the definition decides how the screen is mounted. **One `Screen` concept** serves pages, sheets, dialogs, and full-screen covers — the dev never learns a separate "sheet API."
+
+```dart
+class EditProfileRoute extends FwRoute {
+  const EditProfileRoute({required this.userId});
+  final int userId;
+
+  @override
+  String get location => '/profile/$userId/edit';
+
+  static final pattern = FwRoutePattern(
+    '/profile/:userId/edit',
+    present: FwPresentation.sheet,        // page | sheet | dialog | fullScreen
+    transition: FwTransition.slideUp,     // optional; a sensible default per presentation
+    builder: (s) => EditProfileScreen(userId: int.parse(s.params['userId']!)),
+  );
+}
+```
+
+```dart
+class EditProfileScreen extends StatelessWidget {
+  const EditProfileScreen({super.key, required this.userId});
+  final int userId;
+
+  @override
+  Widget build(BuildContext context) {
+    // Identical Screen API. Because the route mounts it as a sheet, the sheet
+    // PRESENTATION (a custom Material-free PopupRoute — see below) supplies the
+    // grabber, scrim, safe-area insets, rounded top & drag-to-dismiss.
+    return Screen(
+      header: const SheetHandle(),
+      body: EditProfileForm(userId: userId),
+      footer: FwRow(gap: 3, children: [
+        Button.ghost(onPressed: () => context.pop(false), child: const Text('Cancel')),
+        Button(
+          onPressed: () async {
+            await profiles.save(userId);
+            if (context.mounted) context.pop(true);   // typed result back
+          },
+          child: const Text('Save'),
+        ),
+      ]),
+    );
+  }
+}
+```
+
+Call site reads like a sentence:
+
+```dart
+final saved = await EditProfileRoute(userId: 7).push<bool>(context);
+if (saved ?? false) showToast(context, 'Profile updated');
+```
+
+> Navigating to `/profile/7/edit` — from a link, the browser bar, or a push notification — opens the profile screen with the edit sheet **over** it, and system/browser **back closes the sheet** (the route pops). For the parent to render *underneath* on a cold deep-link, the sheet route MUST be a **child** of the parent route (§4.3.1), not a sibling.
+
+**`FwPresentation`** values: `page` (default, full destination), `sheet` (bottom sheet), `dialog` (centered modal), `fullScreen` (full-screen cover, e.g. iOS modal).
+
+**Honest scope (not "free"):** `go_router` ships only `MaterialPage`/`CupertinoPage`/`NoTransitionPage`. flutterbits is Material-free, so it **authors custom Material-free `Page`s** — `FwSheetPage` / `FwDialogPage` / `FwFullScreenPage`, each returning a custom `PopupRoute` returned from `go_router`'s `pageBuilder`. Those custom routes **own the scrim, safe-area insets, rounded top, the `SheetHandle` grabber, and drag-to-dismiss** — real, scheduled work (feasible — §11b "feasible, scoped" — **not** free). What *is* free from `go_router`: the route **pop** on back and the URL addressability. The gesture/scrim/chrome is flutterbits's to build.
+
+#### 4.3.1 Deep-linkable sheets require nested routes
+
+For `/profile/7/edit` to open the sheet *over* the profile screen on a **cold** deep-link, `EditProfileRoute` must be registered as a **child** of `ProfileRoute`, so the router builds the parent beneath the sheet page:
+
+```dart
+FwRoutePattern(
+  '/profile/:userId',
+  builder: (s) => ProfileScreen(userId: int.parse(s.params['userId']!)),
+  children: [
+    FwRoutePattern('edit',                       // → '/profile/:userId/edit'
+      present: FwPresentation.sheet,
+      builder: (s) => EditProfileScreen(userId: int.parse(s.params['userId']!))),
+  ],
+);
+```
+
+A flat *sibling* registration would **replace** the profile screen instead of layering the sheet over it. `FwRoutePattern.children` maps to `go_router`'s nested `routes:`. (The `EditProfileRoute` navigation token in §4.3 is unchanged; only the registration nests.)
+
+### 4.4 Imperative overlays — for ephemera not worth a URL
+
+Routable presentation (§4.3) is for screens that deserve a URL/deep link. For throwaway popups, **imperative helpers** (lib utils — see registry spec) avoid route ceremony:
+
+```dart
+final ok = await showConfirm(context,
+  title: 'Delete track?', message: 'This can’t be undone.',
+  confirm: 'Delete', tone: Tone.destructive);   // Tone = the shared normal/destructive intent enum
+
+final picked = await showSheet<Color>(context, (_) => const ColorPickerSheet());
+showToast(context, 'Saved');   // via the Toaster overlay host
+```
+
+Both worlds coexist by design: **routable** when it deserves a URL, **imperative** when it doesn't.
+
+### 4.5 Guards / auth
+
+Two ergonomic levels, both intention-revealing. A guard is `FutureOr<String?> Function(BuildContext, FwRouteState)` — it returns a redirect target, or `null` to allow. It is **async-capable** (so token checks / silent refreshes work), mapping directly onto `go_router`'s async `redirect`:
+
+```dart
+// Per-route (async-capable):
+static final pattern = FwRoutePattern(
+  '/dashboard',
+  guard: (c, s) async => (await auth.isLoggedIn) ? null : LoginRoute(next: s.location).location,
+  builder: (_) => const DashboardScreen(),
+);
+
+// Or global, on Layout (cross-cutting):
+FutureOr<String?> _authRedirect(BuildContext c, FwRouteState s) =>
+    (!auth.isLoggedIn && s.location.startsWith('/app')) ? LoginRoute().location : null;
+```
+
+Both map to `go_router`'s route-level and top-level `redirect` (both `FutureOr<String?>`).
+
+### 4.6 Transitions
+
+`FwTransition` — sensible Material-free defaults, overridable per route:
+`slide` · `fade` · `scale` · `slideUp` · `none` · `custom`. Each presentation has a sensible default (e.g. `sheet` → `slideUp`). Bespoke motion composes `flutter_animate` inside the screen's body — the engine ships no element-animation subsystem (AGENTS.md §11b).
+
+### 4.7 Deep links / web URLs — free
+
+Because each route's `location` getter **is** a real path and its `pattern` parses it back, web URLs (correct address bar, refreshable) and mobile deep links work with no extra effort — typed navigation *and* shareable URLs from one declaration. This is a genuine selling point and falls out of `go_router`.
+
+---
+
+## 5. Nested shells (persistent chrome)
+
+`TabsLayout` (and the by-demand `SidebarLayout`) are `Layout`s used as a `shell:` — they persist across the `Screen`s routed inside them, mapping to `go_router`'s `ShellRoute`. A tabbed home is one `TabsLayout` shell whose tabs route to sibling `Screen`s; switching tabs swaps the routed screen while the shell (and its state) persists.
+
+```dart
+TabsLayout(
+  destinations: const [
+    NavDestination(icon: LucideIcons.house, label: 'Home',    route: HomeRoute.pattern),
+    NavDestination(icon: LucideIcons.disc,  label: 'Library', route: LibraryRoute.pattern),
+    NavDestination(icon: LucideIcons.user,  label: 'Profile', route: ProfileRoute.pattern),
+  ],
+)
+```
+
+---
+
+## 6. Accessibility & platform (inherited rules)
+
+- Every interactive structure component meets AGENTS.md §6: `Semantics` roles/labels, keyboard activation (`ActivateIntent` → `CallbackAction`), a visible focus ring using `context.fw.colors.ring`, directional layout. This holds on mobile **and** web/desktop (charter §4).
+- Mobile-first defaults: ≥44px touch targets, safe areas honored by `Screen`, `TabsLayout`/`BottomNav` + sheets as the primary idioms. Hover is enhancement-only.
+
+---
+
+## 7. Where it lives & deps
+
+- All of the above are **flutterbits copy-paste source** (registry tier `structure`), importing `flutterwindcss` for styling.
+- `pubDeps`: `go_router` (routing), `lucide_icons_flutter` (nav icons), `flutter_animate` (transitions/micro-motion). Declared on the structure components' manifests (charter §6).
+- `flutterwindcss` is **untouched** — it never learns routing exists (charter §7).
+
+---
+
+## 8. Done criteria (this layer)
+
+A structure component is done only when: composed (not inherited); slots/props are intention-revealing; routing is typed with a readable table; presentations work including deep-link + back-to-dismiss; accessible per §6; goldens cover the relevant states/brightness; and it is rendered in `apps/gallery` (the flutterbits component target — separate from the engine's `apps/example`) so CI compiles it. First slice: `Layout` + `Screen` + routing + `Button` + `ThemeToggle` (charter §8).