kmcom-nuxt-layers 2.7.5 → 3.0.0

package/docs/superpowers/specs/2026-08-30-layer-taxonomy-tier-2-design.md

@@ -0,0 +1,154 @@
+# Layer Taxonomy Redesign — Part 2: Tier 2 (Structure)
+
+## Scope
+
+Forensic audit of `layout`, `navigation`, `routing` — every real file read, every component/
+composable/util traced to actual consumers via grep, decisions recorded below. Continues the
+process established in `2026-08-30-layer-taxonomy-tier-0-1-design.md` (Tier 0/1). No
+implementation yet — design-doc recording only, per the brainstorming skill's hard gate.
+
+## Tier 0 loose end — resolved
+
+`core/app/assets/css/base.css` and `layout.css` (misleadingly named — lives in `core`, not
+`layout`) were never actually read during the Tier 0 pass despite the doc claiming Tier 0 fully
+closed. Read now: both are plain, correct CSS resets (`base.css` = typography/element defaults
+under `@layer base`; `layout.css` = table/hr/media defaults under `@layer components`). Nothing
+layout-specific, nothing that belongs in the `layout` tier. Correctly homed in `core`. No action.
+Tier 0 is now genuinely fully closed.
+
+## Decisions
+
+### `layout`: delete `GridPlacement.ts` (dead code)
+
+`app/composables/GridPlacement.ts` (`useGridPlacement`) — its own docstring admits it: "Currently
+not used - BaseGridItem inlines this logic for better reactivity. Kept for reference or future
+use." Confirmed via grep: zero consumers anywhere in the repo. `Grid/Item.vue` has its own
+equivalent, more complete implementation in `utils/gridPlacementStyle.ts` (which **is** the real,
+consumed implementation). Delete `GridPlacement.ts`.
+
+### `layout`: delete `Section/Title.vue` (`LayoutSectionTitle`) — exact duplicate of `LayoutPageHeader`
+
+`Layout/Section/Title.vue`'s JSDoc header literally still reads "PageHeader - Standard page header
+component... Used by PageContainer for visible page headers" — a copy-paste leftover from
+`Layout/Page/Header.vue`. Confirmed via grep: `LayoutSectionTitle` has **zero** real consumers
+anywhere in the repo; `LayoutPageHeader` is the real, consumed one (used by `LayoutPage`, two
+playground pages, `StarterDesignSystem.vue`). Title.vue is also a strictly weaker variant — no
+`back`-button variant, no `text-highlighted`/`text-muted` semantic color classes, wraps in
+`LayoutGridItem` instead of being a plain block. Delete `Section/Title.vue`.
+
+### `layout`: `app.config.ts` — same defect pattern as `theme`/`routing`, fix identically
+
+`layout/app/app.config.ts` uses a bare `export default {...}` (no `defineAppConfig()` wrapper),
+and its `declare module '@nuxt/schema'` augmentation lives in a separate file
+(`app/types/app-config.d.ts`) instead of the same file — both violate
+`.claude/rules/nuxt-layers.md`'s documented rule (file must live in `app/`, use
+`defineAppConfig()`, one `declare module` block, same file). This is the **same defect** already
+found and fixed for `theme` in Tier 1, and independently found in `routing` here (see below).
+Fix all three consistently: wrap in `defineAppConfig()`, merge the `declare module` block into
+`app.config.ts` itself, delete the now-redundant `types/app-config.d.ts` files.
+
+### `routing`: `app.config.ts` — third instance of the same defect
+
+`routing/app/app.config.ts` — bare `export default {...}` (no `defineAppConfig()`), augmentation
+split into `app/types/app-config.d.ts`. Functionally fine defaults (`preset: 'simple'`, everything
+off by default — sane), but same structural violation as `layout`/`theme`. Fold into the
+consolidated fix above.
+
+### New finding while fixing the above: `core`'s own `app.config.ts` had the same defect
+
+Not previously flagged — `core/app/app.config.ts` was also a bare `export default {...}` with its
+`declare module` augmentation split into `core/app/types/app-config.d.ts`. Fixed identically
+(`defineAppConfig()`, merged augmentation, deleted the `.d.ts`) while doing this batch. Also
+dropped the `scrollGuard` config block and its type, now dead after `useScrollGuard`'s deletion.
+
+### `navigation`: `app.config.ts` — correct, no action
+
+Uses `defineAppConfig()` + same-file `declare module` block correctly. This is the pattern the
+other three layers should match. No changes needed.
+
+### `navigation`: `useMastNav` didn't use the `createModal` factory it sits next to — fixed
+
+`app/utils/createModal.ts` is a well-designed generic factory (`createModal(Component)` →
+`{ open, close, patch }`, wraps `createSharedComposable` + `useOverlay`) — real and consumed by
+the playground's demo modals (`useConfirmModal`, `useInfoModal`, `useFormModal`) and documented in
+`visual/Base/Modal.vue`'s own JSDoc as _the_ pattern to use. `useMastNav` (`mastNav.ts`) hand-rolled
+the identical `overlay.create()` pattern manually instead of calling `createModal()`, plus wrapped
+`open`/`close` with `useSmoothScroll().lockScrolling()`/`unlockScrolling()`.
+
+**Resolved**: extended `createModal(component, options)` with optional `onOpen`/`onClose` hooks
+(run before open / after close), and refactored `useMastNav` to `createModal(MastNavModal, {
+onOpen, onClose })` — same 4 lines of scroll-lock logic, zero duplicated overlay wiring. Already
+implemented in this pass (`createModal.ts`, `mastNav.ts`).
+
+### `navigation`/`routing`: `ResponsiveValue<T>` triplication — already-deliberate, no new action
+
+Confirmed three separate `ResponsiveValue<T>` shapes exist: `core`'s canonical 5-key
+(`default/sm/md/lg/xl`, documented as canonical for `core`+`ui`), `layout/types/layouts.ts`'s own
+5-key copy (explicitly documented in `core`'s own type file as intentionally _not_ migrated —
+"stays as-is, used by GridConfig/GridPresetsItem"), and `gridPlacementStyle.ts`'s private
+3-key (`default/md/lg`, module-local, unexported, matches the Swiss Grid's own 3-tier column
+system). All three are already-considered, deliberate divergences from prior sessions, not new
+findings. No action — confirms Tier 0's summary was correct on this point.
+
+### `starter` layer — not in `.claude/rules/nuxt-layers.md`'s layer table, extends the dissolved `ui`
+
+Found while grepping component usage: `layers/starter` (`extends: ['../core', '../ui', '../layout',
+'../motion']`) exists on disk but is undocumented in the layer table, and depends on `ui`, which
+Tier 1 decided to dissolve entirely. Out of scope for this Tier 2 pass (not `layout`/`navigation`/
+`routing`), but flagging now since the `ui` dissolution will break its `extends` — needs its own
+audit pass (either fold into a later tier or handle alongside the `ui` dissolution work item).
+
+## Confirmed correct, no action
+
+- `layout`'s `Section/*` components (`Gallery`, `Grid`, `Hero`, `Sidebar`, `Split`, `Stack`) — all
+  real, distinct, pre-configured grid patterns with no overlap. `layout/CLAUDE.md`'s component
+  table is stale (missing `Grid.vue`, `Sidebar.vue`, `Stack.vue`, `Title.vue` from its listing) —
+  minor doc-drift, worth a pass when this tier's action items are implemented, not blocking.
+- `Grid/Item.vue` (`LayoutGridItem`) — real, well-built, single canonical grid-placement
+  implementation (via `gridPlacementStyle.ts`), presets resolve correctly against
+  `app.config.ts`'s `layoutLayer.ui.grid.presets`.
+- `Grid/Debug.vue` — real, Cmd/Ctrl+G toggle, correctly reads `core`'s `BREAKPOINT_PX` tokens.
+- `Page/Header.vue`, `Page/index.vue` (`LayoutPage`) — real, canonical, correctly documented
+  (`LayoutPage` is a fragment, doesn't double up the grid root).
+- `useGridConfig.ts` — real, clean, backwards-compat `enabled`→`mode` shim is intentional and
+  documented.
+- `navigation`'s `Mast/Header.vue`, `Footer.vue`, `Nav.vue`, `NavModal.vue` — all real, all
+  consumed (verified via grep across playground + `starter`). `Header.vue` has a dead commented-out
+  `<template #toggle><MastNav /></template>` block — harmless doc cruft, can be deleted opportunistically.
+- `Links/Group.vue`, `Links/Named.vue` — real, consumed.
+- `Site/Title.vue`, `Site/Subtitle.vue`, `useSite.ts`, `utils/site.ts`, `utils/regex.ts`
+  (`splitSpaces`) — real, consumed chain (`useSite` → `resolveSiteConfig` → `splitSpaces`). Note:
+  `navigation` has its own `regex.ts` distinct from `core`'s now-deleted one — this one has a real
+  consumer, correctly kept.
+- `useAppToast` (`toast.ts`) — real, thin wrapper over `useToast()`.
+- `routing`'s entire composable/middleware/plugin/server chain (`useRoutingConfig`,
+  `useFeatureFlags`, `useMaintenance`, `resolveRoute`, both global middleware, both plugins, the
+  `feature-flags` API route) — genuinely well-built, self-consistent governance system. Presets
+  (`simple`/`marketing`/`product`/`enterprise`) are real and sane. No dead code found.
+- `routing/app/middleware/02.governance.global.ts`'s `console.log` debug lines are gated behind
+  `config.debug` (default `false`) — not a leftover, intentional.
+- `scroll-routing.client.ts`'s `fallow-ignore-next-line code-duplication` suppression — flags a
+  real near-duplicate of an `IntersectionObserver` pattern elsewhere (likely `scroll`/`motion`
+  tier). Out of scope for Tier 2; carry forward to the Tier 5 (Motion) pass.
+
+## Consolidated action list (Tier 2)
+
+- [x] Delete `layout/app/composables/GridPlacement.ts` (dead, self-admitted unused)
+- [x] Delete `layout/app/components/Layout/Section/Title.vue` (`LayoutSectionTitle`) — zero
+      consumers, exact-duplicate copy-paste of `LayoutPageHeader`
+- [x] Fix `app.config.ts` structural defect in `layout` and `routing` (join `theme`/`core` from
+      Tier 0/1 — same 4th and 5th instance): wrapped in `defineAppConfig()`, merged
+      `declare module '@nuxt/schema'` into the same file, deleted the redundant
+      `app/types/app-config.d.ts` in each. `theme`'s own fix is still pending (Tier 1 item).
+- [x] `useMastNav` refactored onto `createModal` with new `onOpen`/`onClose` hooks (implemented)
+- [x] Delete dead commented-out `<template #toggle><MastNav /></template>` block in
+      `navigation/Mast/Header.vue`
+- [x] Update `layout/CLAUDE.md`'s component table to list `Grid.vue`, `Sidebar.vue`, `Stack.vue`
+      (post `Title.vue` deletion, dropped from the listing)
+- [ ] Separately audit `layers/starter` — extends the dissolved `ui` layer, needs its own decision
+      once `ui`'s dissolution is implemented
+
+## Not yet covered
+
+Tiers 3 (Content), 4 (Data), 5 (Motion), 6 (Render), 7 (Delivery), and the Tier sub-layer/toggle
+mechanism design are separate passes.

package/docs/superpowers/specs/2026-08-30-layer-taxonomy-tier-3-design.md

@@ -0,0 +1,109 @@
+# Layer Taxonomy Redesign — Part 3: Tier 3 (Content)
+
+## Scope
+
+Forensic audit of `content` (only member of Tier 3) — every real file read, every component/
+composable traced to actual consumers via grep. Continues the process established in the Tier 0/1
+and Tier 2 docs. Findings below were investigated, decided, and implemented in the same pass (user
+explicitly asked to close the gaps rather than just record them).
+
+## Findings and resolution
+
+### Dead code — deleted
+
+- `_jiti_test.ts` (layer root) — scratch diagnostic testing zod's `.def`/`._def` shape, leftover
+  from investigating the documented jiti/`moduleCache:false` bug. Zero consumers.
+- `useBlogPost.ts`, `useGalleryItem.ts`, `usePortfolioItem.ts` (all singular) — zero consumers;
+  `NuxtContent/Detail.vue` calls the generic `useCollectionItem(collection, slug)` directly.
+- `usePortfolioItems.ts` (plural) — zero consumers; superseded by the generic path below.
+- `createPortfolioComposables.ts` — absorbed into the new generic composable (see below).
+- `Gallery/Card.vue`, `Blog/Card.vue`, `Portfolio/Card.vue`, `Gallery/AmbientImage.vue` — all zero
+  consumers. Each was a complete, working component that got bypassed by an inline reimplementation
+  of the same markup in its real consumer (`Gallery/Grid.vue`, `Blog/List.vue` via `<UBlogPost>`,
+  `Portfolio/List.vue` via `<UPageCard>`, `Gallery/ImageDetail.vue`).
+- `NuxtContent/Renderer.vue` — zero consumers; `NuxtContent/Detail.vue` uses `@nuxt/content`'s raw
+  `<ContentRenderer>` directly instead.
+
+### List-composable duplication — resolved with one generic composable
+
+`docs/fallow-refactor/layers-content.md` (pre-existing repo doc) had already flagged
+`useGalleryItems`/`usePortfolioItems` as near-duplicates. Confirmed broader than that doc knew:
+`useBlogPosts`, `useGalleryItems`, and `createPortfolioComposables`'s `useItems` all reimplemented
+the same sort → filter-by-tags → filter-by-boolean-field → limit pipeline, differing only in the
+sort key (`date` vs `year`) and the boolean field (`draft` vs `featured`).
+
+**Implemented**: one generic `useCollectionItems(collectionName, { tags, limit, sortKey,
+sortDirection, filter })` (`composables/useCollectionItems.ts`) — `sortKey` and the boolean
+`filter` predicate are duck-typed, so the same function serves both compile-time-known collections
+and `Portfolio/List.vue`'s runtime `collection` prop. `useBlogPosts.ts`/`useGalleryItems.ts` are
+now thin wrappers over it (per fallow's own recommendation); `Portfolio/List.vue` calls it directly
+since it has no fixed domain to wrap. `createPortfolioComposables.ts` deleted, fully absorbed.
+
+### Missing `/blog` and `/portfolio` routes — resolved (design was misread, corrected by user)
+
+Initial read: `content.vue`'s own demo page claimed _"the content layer provides default pages at
+`/blog`, `/portfolio`, and `/gallery`... out of the box"_, but `layers/content` has no `app/pages/`
+directory and the playground had no `/blog` or `/portfolio` routes — only `/gallery`.
+
+**User correction**: the layer has never auto-registered routes — that was tried once and produced
+stray unused pages, so it was deliberately rebuilt as components-only. "Out of the box with very
+little coding" means each domain ships a `Page.vue` + `ItemPage.vue`/`SlugPage.vue` pair that the
+consuming app copies into `app/pages/` as a 1–3 line wrapper — exactly what `gallery/index.vue` →
+`<GalleryPage />` already does. The actual gap: `Portfolio` already had this `Page.vue`/
+`ItemPage.vue` pair but the playground never copied the wrapper pages in; `Blog` didn't have the
+pair built at all.
+
+**Implemented**:
+
+- Added `Blog/Page.vue` and `Blog/ItemPage.vue`, mirroring `Portfolio/Page.vue`/`ItemPage.vue`
+  exactly (`contentLayer.sections.blog` guard, `LayoutSection`/`LayoutGridItem` wrapper).
+- Added the four thin playground route wrappers: `apps/playground/app/pages/blog/index.vue`,
+  `blog/[slug].vue`, `portfolio/index.vue`, `portfolio/[slug].vue` — same 1–3 line shape as the
+  existing `gallery/*` routes.
+- Rewrote `content.vue`'s Architecture Note to describe the real, components-only/copy-in pattern
+  instead of the false "layer provides pages" claim.
+
+### `content`: `app.config.ts` structural defect — fixed (6th instance of the repo-wide pattern)
+
+Same defect as `core`/`layout`/`routing` (Tiers 0-2): bare `export default {...}`, augmentation
+split into a separate `app/types/app-config.d.ts`. Fixed identically: `defineAppConfig()`, merged
+`declare module` into the same file, deleted the `.d.ts`. `theme`'s own instance of this (Tier 1)
+is still pending — not touched here.
+
+## Confirmed correct, no action
+
+- `content.config.ts` — all four collection schemas correctly mirrored into
+  `types/collections.d.ts`'s frontmatter augmentation, per the documented jiti constraint.
+- `useContentData`, `useContentPage`, `useCollectionItem`, `useCollectionSurround` — real,
+  consumed, correctly layered.
+- `NuxtContent/Detail.vue`, `NuxtContent/List.vue`, `NuxtContent/Surround.vue`, `NuxtContent/Toc.vue`
+  — real, well-built generic wrappers, correctly consumed by all three domains.
+- `Gallery/Grid.vue`, `Gallery/Detail.vue`, `Gallery/ImageDetail.vue`, `Gallery/Lightbox.vue`,
+  `Gallery/Page.vue`, `Gallery/SlugPage.vue`, `Gallery/ImagePage.vue` — real, fully wired.
+- `Portfolio/Detail.vue`, `Portfolio/ColorPalette.vue`, `Portfolio/Typography.vue`, `Blog/Article.vue`
+  — real, complete; now reachable via the routes added above.
+- `content/Figure.vue` — MDC component invoked from markdown (`::figure`), not from Vue templates;
+  zero grep hits is expected and correct for this component category.
+- `types/content.ts`, `types/collections.d.ts` — clean, kept in sync with `content.config.ts`.
+- `nuxt-studio` conditional dev-only module load — real, deliberate optional peer dependency
+  pattern, correctly guarded.
+
+## Consolidated action list (Tier 3)
+
+- [x] Delete `layers/content/_jiti_test.ts`
+- [x] Fix `content/app/app.config.ts` structural defect
+- [x] Delete `useBlogPost.ts`, `useGalleryItem.ts`, `usePortfolioItem.ts`, `usePortfolioItems.ts`,
+      `createPortfolioComposables.ts`
+- [x] Delete `Gallery/Card.vue`, `Gallery/AmbientImage.vue`, `Blog/Card.vue`, `Portfolio/Card.vue`,
+      `NuxtContent/Renderer.vue`
+- [x] Build generic `useCollectionItems`; migrate `useBlogPosts`/`useGalleryItems`/
+      `Portfolio/List.vue` onto it
+- [x] Add `Blog/Page.vue` + `Blog/ItemPage.vue`; wire `/blog` + `/portfolio` playground routes
+- [x] Fix `content.vue`'s stale "provides default pages... out of the box" claim
+
+Tier 3 is fully closed — nothing left open.
+
+## Not yet covered
+
+Tiers 4 (Data), 5 (Motion), 6 (Render), 7 (Delivery), and the Tier sub-layer/toggle mechanism
+design are separate passes.

package/docs/superpowers/specs/2026-08-30-layer-taxonomy-tier-4-design.md

@@ -0,0 +1,124 @@
+# Layer Taxonomy Redesign — Part 4: Tier 4 (Data)
+
+## Scope
+
+Forensic audit of `database`, `auth`, `metadata` (+ 4 providers: `comicvine`, `openlibrary`,
+`google-books`, `themoviedb`), `forms`, `mailer`. Every real file read, every composable/route
+traced to actual consumers via grep.
+
+## Findings and resolution
+
+### `mailer`: runtime-config augmentation split + wrong module — fixed
+
+`mailer/nuxt.config.ts` declared `runtimeConfig.mailerLayer` but had no `declare module
+'@nuxt/schema'` block at all. Instead `server/types.d.ts` augmented `declare module 'nitropack' {
+interface NitroRuntimeConfig }` — a different ambient module than every other layer uses, and
+still split into a separate file. `database` (same tier) shows the correct pattern: augmentation
+inline in `nuxt.config.ts` targeting `@nuxt/schema`.
+
+**Fixed**: moved the augmentation into `mailer/nuxt.config.ts` as `declare module '@nuxt/schema' {
+interface RuntimeConfig }`, deleted `server/types.d.ts`.
+
+### `forms`: app.config.ts structural defect — fixed (8th instance)
+
+Same repeat defect as `core`/`layout`/`routing`/`content` (Tiers 0-3): bare `export default
+{...}`, augmentation split into `app/types/app-config.d.ts`. Fixed identically:
+`defineAppConfig()`, merged `declare module` into the same file, deleted the `.d.ts`.
+`theme` and `shader`'s own instances of this are still pending — not this tier's layers.
+
+### `metadata` providers: `type RuntimeConfig` instead of `interface RuntimeConfig` — fixed (real bug)
+
+`comicvine`, `google-books`, `themoviedb`'s `nuxt.config.ts` each declared:
+
+```ts
+declare module '@nuxt/schema' {
+  type RuntimeConfig = { ... }
+}
+```
+
+A `type` alias inside a `declare module` block does not merge with the ambient `RuntimeConfig`
+interface the way `interface RuntimeConfig { ... }` does — every other augmented `RuntimeConfig` in
+the repo (`database`, `mailer`) uses `interface`. With `typeCheck: false` this was silently
+masked, but it's wrong and would break under a real typecheck (duplicate/non-merging declaration
+of the same global name three times). `openlibrary` has no runtime config (public API, no key) so
+it was unaffected.
+
+**Fixed**: `type RuntimeConfig` → `interface RuntimeConfig` in all three.
+
+## Confirmed correct, no action
+
+- `database`: `useSql()`/`useDrizzle()` — minimal, correct, real. `nuxt.config.ts` augmentation
+  pattern is the reference example other layers should match.
+- `auth`: `nuxt-auth-utils` + GitHub OAuth handler + opt-in `auth` middleware — real, correct,
+  appropriately thin (session/oauth runtimeConfig keys belong to the module, not custom, so no
+  augmentation needed).
+- `metadata` core: `provider-registry.ts`, `cache.ts` (memory-storage `useStorage('metadata')`,
+  documented as non-persistent across restarts — acceptable for a demo/dev cache), `search.ts`
+  (parallel provider fan-out via `Promise.all` + per-provider try/catch + dedup + cache), all four
+  `server/api/metadata/*.get.ts`/`sync.post.ts` routes — real, correct, well-built.
+- All four providers' `provider.ts`/`normalise.ts`/`types.ts` — real, correctly registered via
+  `server/plugins/*-register.ts`, correctly composed in the playground's `metadata.vue` (search,
+  provider registry list, live status check).
+- `forms`: `useFormSchema`, `fieldConfigs` registry (`FieldType` derived from `keyof typeof`),
+  `Form/Contact.vue` + `Form/Field.vue`, `contact.post.ts` (rate-limited, hook-driven), all real
+  and correctly wired end to end (verified via the playground `/forms` and `/mailer` pages).
+- `mailer`: `sendContactEmail`, `mailerLayerHooks` (hookable-based `contact:submitted/sent/failed`
+  hooks, consumed by `forms/server/api/contact.post.ts`) — real, correctly layered.
+
+## Resolved this pass (user decision)
+
+### `useMetadataSearch` — wired up, duplicate logic in the page deleted
+
+User chose: wire the composable up rather than delete it. `useMetadataSearch` now takes
+`mediaType`/`providers`/`limit` as `MaybeRef` and an optional `debounceMs` (default 300, via
+`refDebounced` internally — closes the previously-flagged missing-debounce gap instead of leaving
+it patched only at the call site). `metadata.vue` was migrated onto it: the manual
+`refDebounced`/`$fetch`/loading/error state block is gone, replaced by
+`useMetadataSearch(rawQuery, { mediaType, limit: 20 })` and `status`-derived `isLoading`/
+`hasSearched`. Verified template usages (`results?.length`, `error.message`, `v-for="item in
+results"`) still resolve correctly against the new `data`/`status`/`error` shape.
+
+`useMetadataItem` remains unwired (no lookup/detail page exists) — user explicitly deferred that
+decision (build a detail page vs. delete) rather than resolving it now. Still open.
+
+## Open — needs a decision, not implemented this pass
+
+### `useMetadataItem` — still no consumer
+
+Deferred per above. Left in place, not deleted, pending a decision on whether a lookup/detail page
+gets built for it.
+
+### Provider error-handling divergence (confirmed, pre-existing finding; deferred, low severity)
+
+`comicvine` (`status_code !== 1` check) and `tmdb` (try/catch wrapper) throw `MetadataProviderError`
+from their client layer. `openlibrary` and `google-books` let raw `$fetch` errors propagate
+unwrapped (except `openlibrary`'s `lookupByIsbn`, which swallows to `null`). Harmless on the
+`/search` path — `searchMetadata()` already catches per-provider and degrades gracefully — but
+`/lookup` and `/sync` have no top-level try/catch, so an openlibrary/google-books failure surfaces
+as an opaque Nitro fetch error instead of a clean `MetadataProviderError`-shaped one. Low severity,
+cosmetic-on-error-message only. Left open — fixing means adding the same try/catch wrapper to two
+more clients, a bounded fix but not done here pending direction on the composable question above
+(same investigation pass, similar size).
+
+## Consolidated action list (Tier 4)
+
+- [x] Fix `mailer/nuxt.config.ts` runtime-config augmentation (wrong module + split file)
+- [x] Fix `forms/app/app.config.ts` structural defect (8th instance of the repeat pattern)
+- [x] Fix `type RuntimeConfig` → `interface RuntimeConfig` in comicvine/google-books/tmdb
+- [x] Wire `useMetadataSearch` into `metadata.vue` (with debounce fixed), delete duplicate logic
+- [x] `useMetadataItem` — user decision: keep as-is, unwired. Intended as a standalone composable
+      for future projects to consume directly, not necessarily via a playground page. Not dead
+      code, not building a page for it.
+- [x] Normalised openlibrary/google-books client error handling — wrapped `searchOpenLibrary`,
+      `lookupOpenLibraryWork`, `lookupOpenLibraryEdition`, `searchGoogleBooks`,
+      `fetchGoogleBooksVolume` in try/catch throwing `MetadataProviderError`, matching
+      comicvine/tmdb. Left `lookupByIsbn`'s swallow-to-null alone (deliberate not-found handling,
+      zero real callers either way).
+
+## Not yet covered
+
+Tiers 5 (Motion), 6 (Render), 7 (Delivery). Also still pending from earlier tiers: `theme`'s and
+`shader`'s app.config.ts structural defects, and the larger deferred Tier 0-2 structural items
+(ui-layer dissolution, `.mastmain` rename, `theme`→`theming` rename, typography font-prop system,
+breakpoint token consolidation, `AppContainer` clamp() conversion, `compatibilityVersion: 5` flip,
+`error.vue` real implementation, `starter` layer audit).

package/docs/superpowers/specs/2026-08-30-layer-taxonomy-tier-5-design.md

@@ -0,0 +1,121 @@
+# Layer Taxonomy Redesign — Part 5: Tier 5 (Motion)
+
+## Scope
+
+Forensic audit of `scroll`, `animations`, `transitions`, `page-transitions`, `motion`. Every
+real file read, every composable/component traced to actual consumers via grep.
+
+## Findings and resolution
+
+### `scroll` app.config: dead `lenis`/`gsapScrollTrigger` keys — fixed (user decision)
+
+`app/app.config.ts` declared a `lenis` options block (duration, orientation, smoothWheel, etc.)
+and a `gsapScrollTrigger` flag. `locomotive-scroll.client.ts` never read either — it hardcodes
+its own `lenisOptions` (`lerp`, `smoothWheel`, `wheelMultiplier`) directly in the
+`new LocomotiveScroll(...)` call and always calls `ScrollTrigger.update()` unconditionally.
+
+User's call: Locomotive Scroll v5 already wraps Lenis internally, so a separate top-level
+`lenis` config key is redundant. **Fixed**: stripped `lenis` and `gsapScrollTrigger` from
+`app.config.ts`, keeping only `smoothScroll` (the one key actually read, by
+`useSmoothScroll.ts` and the plugin).
+
+### `page-transitions`: reactive state never drove a real transition — fixed (user decision)
+
+`usePageTransition()` / `page-transitions.client.ts` maintained a `page-transition:current`
+`useState`, but nothing bound it to Nuxt's actual route-transition mechanism — no `:transition`
+on `NuxtPage`, no `page-enter`/`page-leave` CSS. Real navigations never visually transitioned;
+only the playground's `/page-transitions` demo page visualized the state via `MotionTransition`.
+
+**Fixed**: added `layers/page-transitions/app/assets/css/page-transitions.css` (fade/slide/default
+enter-leave classes, duration driven by a `--page-transition-duration` CSS custom property),
+registered via `css:` in `nuxt.config.ts`. `usePageTransition()` now sets that CSS var reactively
+via `watchEffect` (client-only). `apps/playground/app/app.vue` binds
+`<NuxtPage :transition="{ name: transitionName, mode: 'out-in' }" />`, sourced from
+`usePageTransition()`.
+
+### `animations` missing `transitions` layer dependency — fixed (real bug)
+
+`Motion/Staggered.vue` applies `animate-${animation}` classes that are only defined in the
+`transitions` layer's CSS (`animate-fade-in`, `animate-slide-in-up`, etc.), but
+`animations/nuxt.config.ts` only declared `extends: ['../scroll']` — not `transitions`. Relying
+on the playground's load order to happen to also load `transitions` is exactly the anti-pattern
+the repo's own `nuxt-layers.md` rule warns against. **Fixed**: `extends: ['../scroll',
+'../transitions']`.
+
+### `Motion/Staggered.vue`: `animation` prop default didn't match any real CSS class — fixed (real bug)
+
+Default `animation = 'fadeIn'` produced class `animate-fadeIn`; the actual CSS (now confirmed
+reachable per the fix above) only defines kebab-case classes (`animate-fade-in`,
+`animate-slide-in-up`, ...). The mismatch was cosmetic in practice (the component's own
+`.animated` rule unconditionally sets `opacity: 1` regardless of which named class matched), but
+the specific keyframe animation silently never played. **Fixed**: default changed to `'fade-in'`,
+prop doc comment clarifies it's a `transitions` layer `animate-*` suffix.
+
+### `Motion/Marquee.vue`: dead commented-out `<style>` block — fixed
+
+Trailing HTML comment held a fully-commented-out, stale `<style scoped>` block (superseded by
+Tailwind utility classes already on the template). **Fixed**: deleted.
+
+### `animations/app/types/` — dead duplicate type, unused alias — fixed
+
+`types/animations.ts` exported `UseCountUpOptions`, but `useCountUp.ts` declares its own local
+`UseCountUpOptions` and never imports the "shared" one — the exported type had zero consumers
+anywhere in the repo (verified via grep), and the `#layers/animations/types` alias was also
+unconsumed externally. **Fixed**: deleted `types/animations.ts` and `types/index.ts`, removed the
+now-pointless alias entry from `nuxt.config.ts`. `useCountUp.ts`'s local type is untouched — one
+producer, one consumer, no need for a shared export.
+
+### `motion` layer: fictional README + dead stub component — fixed (user decision)
+
+`motion/README.md` documented an API that has never existed in this layer: `useMotion`,
+`useTransition`, `useAnimation` composables, a `$motion` plugin, `<MotionTransition>` and
+`<MotionStaggered>` described as if built here (they're real, but live in `transitions` and
+`animations` respectively). `motion/app/components/Motion/index.vue` was a dead stub (just
+wraps `<slot />`) with zero consumers anywhere. `TASKS.MD` was an unrelated stray to-do note.
+
+**Fixed**: rewrote `README.md` to describe `motion` accurately — a pure orchestrator with no
+components/composables of its own, just an `extends` list, plus a table pointing at which real
+layer provides what. Deleted the dead stub component and `TASKS.MD`. Left
+`docs/MarqueeText.md` as-is — it's accurate, and `motion` is a reasonable place for
+orchestrator-level consumer docs even though the component itself lives in `animations`.
+
+## Confirmed correct, no action
+
+- `scroll`: `useGsap`, `useSmoothScroll`, `useSectionProgress`, `useScrollSteps`,
+  `locomotive-scroll.client.ts`, `utils/scroll.ts` — all real, correctly cleaned up (GSAP
+  tweens/ScrollTriggers killed in `onUnmounted`, confirmed against prior-session fixes for the
+  HorizontalScroll/PinnedSection cleanup and FOUC bugs). All 8 `Motion/*` scroll components
+  (`HorizontalScroll`, `Parallax`, `PinnedSection`, `ScrollLink`, `ScrollProgress`,
+  `ScrollScene`, `ScrollStats`, `ScrollStep`) traced to real consumers in the playground
+  (`/scroll`, `/scrollytelling`, `/locomotive-scroll`, `/layout-blind-reveal`,
+  `/layout-stacking`, `/motion`).
+- `animations`: `useMarqueeVelocity`, `useMarqueeCopies`, `useCountUp`, `useCursorFollower`,
+  `useMagneticElement`, `useTiltEffect`, `pointerMotion.ts` (shared spring-physics helper) — real,
+  correctly ticker-based (GSAP `gsap.ticker.add`/`remove` pairs, no leaks). All 9 `Motion/*`
+  components traced to consumers (`/animations`, `/motion`, `/motion-interactions`,
+  `/marquee-text`, `/locomotive-scroll`).
+- `transitions`: `transitions.css` (transition/animation utility classes), `Motion/Transition.vue`
+  — real, consumed by `/transitions` and `/page-transitions`.
+- `page-transitions`: `app.config.ts` structure already correct (colocated `declare module`,
+  8th-tier-audit pattern holds here without needing a fix).
+- `motion`: `nuxt.config.ts` — correct orchestrator `extends` list, no runtime code of its own
+  beyond what was fixed above.
+
+## Consolidated action list (Tier 5)
+
+- [x] Strip dead `lenis`/`gsapScrollTrigger` keys from `scroll/app/app.config.ts`
+- [x] Wire `usePageTransition` state to a real Nuxt page transition (CSS + `NuxtPage :transition`)
+- [x] Add missing `transitions` dependency to `animations/nuxt.config.ts`
+- [x] Fix `Motion/Staggered.vue`'s default `animation` prop to match real CSS class names
+- [x] Delete dead commented-out `<style>` block in `Motion/Marquee.vue`
+- [x] Delete unused `animations/app/types/` (dead duplicate type + unused alias)
+- [x] Rewrite `motion/README.md`, delete dead `Motion/index.vue` stub and stray `TASKS.MD`
+
+## Not yet covered
+
+Tiers 6 (Render: `canvas`, `shader`), 7 (Delivery). Also still pending from earlier tiers:
+`theme`'s and `shader`'s `app.config.ts` structural defects, `useMetadataItem`'s fate, the
+openlibrary/google-books provider error-handling divergence, and the larger deferred Tier 0-2
+structural items (ui-layer dissolution, `.mastmain` rename, `theme`→`theming` rename, typography
+font-prop system, breakpoint token consolidation, `AppContainer` clamp() conversion,
+`compatibilityVersion: 5` flip, `error.vue` real implementation, `starter` layer audit).

package/docs/superpowers/specs/2026-08-30-layer-taxonomy-tier-6-design.md

@@ -0,0 +1,77 @@
+# Layer Taxonomy Redesign — Part 6: Tier 6 (Render)
+
+## Scope
+
+Forensic audit of `canvas`, `shader`. Cleanup-only pass (per user direction after Tier 5): fix
+dead code, structural defects, and stale docs — no new feature wiring. `shader` is large (150+
+`Pipeline/*.client.vue` effect components) — sampled several rather than reading all, since they
+follow one consistent, correct pattern (`useShaderStage`/`useShaderPipelineContext`, TSL node
+composition, reactive `watch` → `uniform.value` sync).
+
+## Findings and resolution
+
+### `shader` app.config.ts structural defect — fixed (9th instance, worst yet)
+
+`app/app.config.ts` was a bare object export (no `defineAppConfig()`), and the split
+`app/types/app-config.d.ts` augmented a phantom `shaderLayer?: { name?: string }` shape that
+doesn't even match the real config key (`shader: { preferWebGPU, maxPixelRatio, defaultQuality,
+debugPanel, toneMapping }`) — worse than prior instances of this repeat pattern, since the type
+augmentation was augmenting the wrong shape entirely. **Fixed**: `defineAppConfig()` wrapper,
+correct inline `declare module` matching the real `shader` key, deleted `app-config.d.ts`.
+
+### Two dead one-liner exports in `canvas` — deleted
+
+`getQualitySettings()` and `useGlobalShaderTime()` (a global singleton wrapper around
+`useShaderTime`) had zero consumers anywhere in the repo. **Fixed**: deleted both, removed the
+now-unused `QualitySettings` type import from `useRendererCapabilities.ts`.
+
+### `shader/AGENTS.MD` — stale, describes a structure that doesn't exist — fixed
+
+Documented a `.tsl`/GLSL file-based shader structure (`vertexPlane.tsl`, `noise3D.tsl`, etc.)
+that was never built — the real system is TSL-function-based `.ts` modules
+(`shaders/common/*.ts`, `shaders/layers/*.ts`, `three/tsl` node functions). **Fixed**: rewrote to
+a short, accurate structure map of the real `app/` tree.
+
+## Left open (user decision — not implemented this pass)
+
+### 8 shader composables with zero consumers
+
+`useShaderFloat`, `useShaderVec2`, `useCSSColourUniform`, `useCSSFloatUniform`,
+`useSunDirectionUniform`, `useShaderPerf`, `useTSLNodes`, and the whole `useUniforms.ts` file
+(`useUniforms`/`useUniform`/`useColorUniform`/`useVector2Uniform`/`useVector3Uniform`) — all
+well-built, none wired into any component. Real, actively-used equivalents exist alongside some
+of them (`useShaderColor`, `useAmbientMaterials`, `useShaderMixBlend`, `useThemeColors`), which
+suggested some of these are superseded scaffolding — but given the size of the shader library
+(150+ components still growing) this could equally be toolkit-ahead-of-use rather than dead code.
+**User's call: leave them, don't delete.** Not touched.
+
+## Confirmed correct, no action
+
+- `canvas`: `nuxt.config.ts` (Three.js WebGPU SSR stub via custom Vite plugin, TresJS module
+  config), `ShaderCanvas.vue`, `useRendererCapabilities` (renderer detection, `useAutoQuality`),
+  `useShaderTime`, `types/renderer.ts` — real, correctly consumed by `apps/playground/app/pages/canvas.vue`
+  and `shader.client.ts`.
+- `shader`: `nuxt.config.ts`, `useShader`/`useBasicShader`/`useStandardShader` (node material
+  factory, cleanup-on-unmount), `useShaderRuntime`/`useShaderRuntimeContext` (provide/inject
+  global runtime), `useShaderPipeline`/`useShaderStage`/`useShaderPipelineContext` (provide/inject
+  stage registry, versioned for recompilation), `useUniformWatchers`'s `watchUniformProp`
+  (confirmed consumed by 7 `Material/*.client.vue` components), `useAmbientMaterials`,
+  `useShaderColor`/`useShaderMixBlend`/`useThemeColors`/`useThemePreset`/`useMousePosition` (all
+  confirmed real consumers), `shader.client.ts` plugin, `shader.css`, sampled `Pipeline/*`
+  components (`LinearGradient`, `UVRotate`) — consistent, correct pattern across the sample.
+
+## Consolidated action list (Tier 6)
+
+- [x] Fix `shader/app/app.config.ts` structural defect (9th instance, was augmenting the wrong shape)
+- [x] Delete dead `getQualitySettings()`/`useGlobalShaderTime()` from `canvas`
+- [x] Rewrite stale `shader/AGENTS.MD`
+- [ ] 8 zero-consumer shader composables — left open, user chose not to delete
+
+## Not yet covered
+
+Tier 7 (Delivery). Also still pending from earlier tiers: `theme`'s `app.config.ts` structural
+defect, `useMetadataItem`'s fate, openlibrary/google-books provider error-handling divergence,
+and the larger deferred Tier 0-2 structural items (ui-layer dissolution, `.mastmain` rename,
+`theme`→`theming` rename, typography font-prop system, breakpoint token consolidation,
+`AppContainer` clamp() conversion, `compatibilityVersion: 5` flip, `error.vue` real
+implementation, `starter` layer audit).