# Interaction redesign (Likwidmack, September 2026)

A focused pass on how visitors and the site owner **use** the portfolio: readable contrast in both themes, no lost work, navigation that is always visible, no dead ends, simpler browsing and a safer Style Studio. The visual identity (warm near-black grounds, deep red, ember, clay, condensed display type) is unchanged.

- Design spec: [superpowers/specs/2026-09-23-likwidmack-redesign-design.md](../../superpowers/specs/2026-09-23-likwidmack-redesign-design.md)
- Implementation plan: [superpowers/plans/2026-09-23-likwidmack-redesign.md](../../superpowers/plans/2026-09-23-likwidmack-redesign.md)

## Why

| Problem (before)                                                                                               | Who it hurt                                         | Fix                                                                                   |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Focus outline was the brand red (2.7:1 on the dark page) and personalization re-applied it at runtime          | Keyboard users                                      | AA focus colour from the theme; personalization no longer overrides it                |
| Form borders were an 8 % hairline                                                                              | Everyone filling a field (especially in light mode) | `--theme-border-strong-color` (≥3:1)                                                  |
| Every destination was hidden behind **Menu** at all widths                                                     | First-time visitors, recruiters                     | Inline primary nav from 768 px with the current page marked; visible **Get in touch** |
| Work cards had three links to the same story                                                                   | Keyboard and screen-reader users                    | One link per card                                                                     |
| Case studies ended without a next step                                                                         | Visitors walking the work                           | Previous / next story + **Get in touch** at the end                                   |
| Splash hid “Continue from…” under numbered doors                                                               | Returning visitors                                  | **Resume** first; doors unnumbered with a scope line                                  |
| Browse filters had two controls per facet and no result count                                                  | Gallery and Docs visitors                           | One control per facet, counts, “Showing N of M”, Clear filters, filters in the URL    |
| Style Studio discarded unapplied edits on leave, deleted setups with one click, and allowed unreadable colours | Anyone personalizing the site                       | Draft kept until Apply/Discard, Undo for deletes, live contrast checks                |
| Camera background asked for the webcam without explanation                                                     | Privacy-conscious visitors                          | Explains first; switches only after “Turn on camera”                                  |
| Admin media page was an id table with raw JSON recipes                                                         | Site owner                                          | Drop zone, thumbnail grid, detail drawer, named variant presets                       |

## What changed, by page

| Surface                           | Change                                                                                                                                                                                                         | Code                                                                                                                                          |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| All pages                         | Contrast roles `--theme-focus-ring-color`, `--theme-link-color`, `--theme-border-strong-color`, `--theme-primary-fill-color`/`--theme-on-primary-color`, `--theme-success-ink-color`/`--theme-error-ink-color` | `theme/core` — [packages/theme.md](../../packages/theme.md#contrast-roles)                                                                    |
| Header                            | Inline rail About · Work · Gallery · Code · Writing (≥768 px), `aria-current`, **Get in touch**, Personalize icon button                                                                                       | `AppPrimaryNav`, `shared/primary-nav.ts`                                                                                                      |
| Splash `/`, `/splash`             | Resume bar first; unnumbered doors with scope; “Go straight to where I left off next time”                                                                                                                     | `AppSplash`, `content/home.json`                                                                                                              |
| Work `/work`                      | Whole card is one link; “Read the story →”                                                                                                                                                                     | `AppWorkCard`                                                                                                                                 |
| Case study `/work/:slug`          | Previous / next story + Get in touch                                                                                                                                                                           | `AppStoryPager`, `adjacentStudies()`                                                                                                          |
| Code `/code`                      | Fluid reader: package filter (shared toolbar), accessible snippet tabs (arrows, Home/End), one panel with code + facts, Copy, View source ↗; package cards; `?group=…&item=…` deep links                       | `pages/code/index.vue`, `shared/code-types.ts`, `shared/public-repo.ts`                                                                       |
| Docs, Code                        | Browse toolbar with counts, live status, Clear filters, URL state                                                                                                                                              | `AppBrowseToolbar`, `useBrowseQuery`, `shared/browse-query.ts` — [gallery-and-docs.md](./gallery-and-docs.md#browse-toolbar-appbrowsetoolbar) |
| Gallery `/gallery`                | Full-bleed justified grid; floating menu (Group / Filter / Sort with counts, Play feed, site links); full view = the feed (`?item=`)                                                                           | `GalleryMenu`, `GalleryGrid`, `GalleryViewer`, `useBrowseQuery` — [gallery-and-docs.md](./gallery-and-docs.md#gallery)                        |
| Style Studio `/styles`            | Role-first editing, contrast guard, sticky draft bar, setup Undo, pack tiles                                                                                                                                   | `AppStyleStudio`, `shared/contrast-guard.ts` — [personalization.md](./personalization.md)                                                     |
| Component parity `/styles/parity` | Kitchen sink moved off Style Studio (`/styles/kitchen-sink` redirects)                                                                                                                                         | `pages/styles/parity.vue`, `AppStylesParity`                                                                                                  |
| Personalize dialog, Studio        | Shared background picker with camera consent                                                                                                                                                                   | `AppBackgroundPicker`                                                                                                                         |
| Admin `/admin/media`              | Drop zone, Kind counts, grid, drawer, presets, confirm + Undo                                                                                                                                                  | `core/admin`, `app/utils/media-presets.ts` — [admin.md](./admin.md#local-media-library-dam)                                                   |

## Rules that keep it this way

1. Text and controls use the contrast roles (brand-coloured text: `--theme-primary-ink-color` / `--theme-secondary-ink-color`); brand colours are for fills. Tests fail if a role drops below its minimum (`theme/core/tests/contrast-roles.spec.ts`).
2. One primary action per view; one link or button per object (card, door, asset).
3. Every story or result list offers a next step (pager, Clear filters, Retry).
4. Changes that can be lost are kept until the person applies or discards them; destructive actions confirm in place and offer Undo.
5. Status is always a word (and often a glyph), never colour alone.

## Responsive regression (e2e)

Three Cypress specs guard the responsive · accessible · touch rule (`docs/agents/README.md`):

| Spec                                               | Scope                                                                                                   | Checks                                                                                                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core/web-e2e/src/e2e/responsive.cy.ts`            | `RESPONSIVE_ROUTES` at the seven fluid widths                                                           | Page-level horizontal overflow only.                                                                                                                           |
| `core/web-e2e/src/e2e/ui-audit.cy.ts`              | `PUBLIC_ROUTES` at the seven fluid widths (320 doubles as reflow), phone Menu, page-nav disclosure      | Overflow, 44px targets, 12px type floor, accessible names.                                                                                                     |
| `core/web-e2e/src/e2e/responsive-components.cy.ts` | Every public route at the seven fluid widths, and the components at phone / tablet portrait / landscape | Overflow, clipped or spilling text, overlapping text, controls off-screen, media wider than its box, plus the ui-audit floors; components opened and measured. |
| `core/web-e2e/src/e2e/layout-audit.cy.ts`          | Self-tests of `layoutAudit` on fixtures, at the seven fluid widths                                      | Cropped text, the containing-block chain, scroll containers and ellipsis, sticky roots.                                                                        |

**Viewports are listed once.** `core/web-e2e/src/support/viewports.ts` exports `FLUID_VIEWPORTS` — pages run at 320, 480, 768, 1024, 1280, 1440 and 1920 (owner decision 2026-10-14: every page is mostly consistent across the fluid range) — and `PHONE` (375×812), `TABLET_PORTRAIT` (768×1024) and `TABLET_LANDSCAPE` (1024×768) for the components. The 320×640 width doubles as the ≈ 400% zoom reflow check (WCAG 1.4.10) on every page. Pages size their layout from the shared primitives (`auto-grid`, `--prose-max`, `--container-wide`, `--section-space`), not per-page values — guarded by `core/web/tests/pages-scss.spec.ts`.

**Routes come from the source.** `core/web-e2e/src/support/routes.ts` globs `core/web/app/pages/**/*.vue` (static routes) and `core/web/content/case-studies/*.json` (`/work/<slug>`) with Vite's `import.meta.glob`, so a new page joins the matrix on its own. One doc page and one blog post are resolved at run time from `/docs` and `/api/posts`. An empty `/docs` index fails (docs ship with the repo), and so does a non-200 `/api/posts` (the store is missing: run `npm run db:migrate:local`). `npm run e2e:regression` seeds one published fixture post (`scripts/e2e-seed-posts.js`, test data only), so on CI (`Cypress.env('CI')`, set from `CI` in `cypress.config.ts`) an empty blog store fails too. Locally the blog test logs the reason and is marked pending with `this.skip()`; run `node scripts/e2e-seed-posts.js` after `db:migrate:local` to audit it.

**Components** (phone, tablet portrait, tablet landscape): the primary Menu dropdown disclosure (Tab order, `Esc` closes and returns focus; inline nav from 48em), Personalize, Style Studio (scroll, controls, Apply / Discard bar), page-nav disclosure, the gallery menu panel, the code browse toolbar (pickers ≤ 768px, segments above), the work jump bar, the code snippet picker and `‹ ›` steps, media player controls, the story pager, footer social links and the evidence examples dialog. Each one is opened and checked: inside the viewport, scrolls inside when taller, 44px targets, named controls, no sideways scroll, and no control hidden at rest that only a `:hover` rule reveals.

**Shared audit.** `core/web-e2e/src/support/layout-audit.ts` holds `floorAudit` (the ui-audit floors), `layoutAudit`, `surfaceAudit` and the hydration-aware `visitHydrated`. `SCROLL_ALLOWLIST` there lists the intentional scroll containers (code frames, table wrappers, carousels) and the decorative layers.

**Known issues.** Real layout bugs found by the suite go in `KNOWN_ISSUES` at the top of the spec. Each entry names its issue and matches only its findings, so the suite stays green while the fix lands; remove the entry with the fix and the check guards the regression. The list is empty today: KI-1 and KI-3…KI-9 were fixed in one pass (see the TODO entry below).

**Cropped text and visible ink.** Clipping follows the _containing-block chain_. A box's `overflow` clip applies to a run only when the box sits on that chain. An `absolute` child escapes a non-positioned `overflow: hidden` wrapper; a `fixed` one escapes everything up to a transform, filter or contain ancestor.

- **Crop check.** A run whose visible ink is under 90% of its line boxes is reported under `clipped` as _crops text_, vertically as well as horizontally (a caption pushed out of a fixed-height frame). Scroll containers, `SCROLL_ALLOWLIST` (code frames, carousels) and ellipsis or line-clamp truncation are intended crops and are not reported.
- **Overlap check.** It compares the visible ink only. Hidden ink is either reported by the crop check or sits in one of those intended crops.
- **Sticky boxes.** Each run records its nearest `position: sticky` root. A pair is skipped only when the two runs have different roots and one root is _stuck_ at that moment, meaning it is offset from its static position. Pairs inside one sticky box (for example `header.site-chrome`) are always checked, and so is a sticky box sitting in flow.
- **Self-tests.** `core/web-e2e/src/e2e/layout-audit.cy.ts` covers both rules. One case rebuilds the pre-fix KI-8 gallery caption and checks that the audit catches it.

**Settle before measuring motion.** Media queries are re-evaluated in the browser's rendering step, not on a forced layout. Headless, after `cy.viewport` a page can keep the previous viewport's `(orientation)` state until something produces a frame — on /work that flips every card's `--media-ratio` (16:9 → 9:16) right after a jump. `settleLayout()` nudges scroll by 1px, dispatches `resize`, then waits two animation frames and three consecutive steady document-height samples before the jump-bar click. The jump itself is instant because `visitHydrated` seeds `motion: 'reduced'`, which the handler reads (setting `data-motion` on `<html>` alone does not change it). Settling still missed once on 768×1024 (story left at top ~4200), so if the story is off screen and the document height changed after the click, the test jumps once more; a jump link that never scrolls still fails, and the record notes `rejumped`.

**Output.** Raw measurements are written to `core/web-e2e/test-output/responsive/<viewport>/{pages,components}/*.json`. Screenshots go to `core/web-e2e/test-output/cypress/screenshots/responsive-components.cy.ts/<viewport>/{pages,components}/` (full page per route at w320, w768 and w1440, plus each open component at phone and tablet portrait). Both folders are gitignored.

```bash
# Build and serve the app (any free port), then:
NX_NO_CLOUD=true NX_DAEMON=false npm run build
PORT=4310 HOST=127.0.0.1 node .output/local/server/index.mjs &
cd core/web-e2e
E2E_BASE_URL=http://127.0.0.1:4310 npx cypress run --spec src/e2e/responsive-components.cy.ts
E2E_BASE_URL=http://127.0.0.1:4310 npx cypress run --spec "src/e2e/ui-audit.cy.ts,src/e2e/responsive.cy.ts"
```

## TODO

### Cognitive accessibility (follow-ups from the 2026-10-22 audit)

Audit: [web/reference/cognitive-a11y-audit.md](../reference/cognitive-a11y-audit.md). Done in the same branch: header _Pause animation_, the depth field holding still under reduced motion, the gallery full view's _Pause_, Motion in Personalize, one touch preview at a time, the _Undo_ duration hint, the full-view focus trap and upright blockquotes and `cite`.

- [ ] **Reading options in Personalize** (audit fix 5): a _Reading_ group with text size (100 / 115 / 130 %), comfortable spacing (the WCAG 1.4.12 values: 0.12em letter, 0.16em word, 2em paragraph spacing, 1.5 line height) and an optional _Focus mode_ that hides the depth field and side chrome on case studies and blog posts. Off by default, remembered in `tgmc-preferences` and painted before first paint by the FOUC script like motion. Cover responsive (no sideways scroll at 130 % on 320px), accessible (radio groups with visible labels, "Applied: …" status) and touch (44px rows).

### Documentation review follow-ups

- [ ] Media SourceBufferQueue: failed entries remain queued and drain immediately re-enters; a missing buffer can recurse if onError does not clear/destroy the queue. Review retry scheduling and in-flight teardown separately from this documentation pass.
- [ ] AI continuation replay tracking: the bounded spent cookie can be cleared, rolled back or raced. If durable one-time execution is required, use server-side atomic consumption rather than claiming cookie-based enforcement.

### Nuxt layers (follow-ups from PR 2 Task 4)

- [ ] Dependency versions: every workspace package should match the root's ranges and be on the latest release. `packages/web-layer-admin` drifts from the root today (`h3 ^1.15.11` vs `^1.8.2`, `ufo` not declared at the root, `nuxt ^4.3.1` vs `^4.5.2`); align it. Raise the root ranges to the latest releases (2026-10-15: `nuxt` 4.6.1, `sass-embedded` 1.105.1, `@iconify-json/lucide` 1.2.144). `core/web/tests/layer-dependency-ranges.spec.ts` covers only the Nuxt layers (owner's choice). Nuxt 4.6.2 and PrimeVue 5.0.2 are out; the bump (PrimeVue is a major) is open. `@nuxt/kit` aligned to `^4.5.2` (5b).
- [ ] Review the `@nuxt/a11y` dev highlights seen on `core/web` during Task 6 (`nuxt dev` on `localhost`): a heading level that skips (`heading-order`), a second `main` landmark (`landmark-no-duplicate-main`), and landmarks without a unique name (`landmark-unique`). Find the pages and components behind each one and fix them.
- [ ] Web skip link (`core/web/app/layouts/site.vue`, `a[data-skip-link]` to `#site_main`): measured 2026-10-15, Enter changes the URL to `/about#site_main` with no remount, but `document.activeElement` stays `BODY` (the next Tab does land inside `main`). The owner kept the current link (2026-10-15), so fix it in place: give `main` `tabindex="-1"` and focus it on activation.
- [ ] `@nuxt/a11y` 1.0.0-alpha.1 throws `crypto.randomUUID is not a function` in `nuxt dev` when the app is opened on a non-secure origin such as `http://tgmc-portfolio.local:3000`; `http://localhost:3000` works. This was there before PR 2. Use `localhost` or HTTPS dev, or upgrade the module when a fix ships.
- [ ] `packages/nuxt-layer-base/src/config/scss.ts` finds its importer root with `new URL('../..', import.meta.url)`, which jsdom-environment Vitest rewrites into an http URL, so specs that import it need `// @vitest-environment node`. Consider `import.meta.dirname` before the UI layer (roadmap Task 5) imports it.
- [ ] The merged Sass `silenceDeprecations` list holds duplicate entries now that web, admin and the layer each contribute. They are harmless; dedupe when convenient.
- [ ] `npx nx run @tgmc/nuxt-layer-base:typecheck` passes only with `--skip-sync --excludeTaskDependencies`: the Nx TypeScript project references are out of sync, and the `@tgmc/theme` specs it pulls in have type errors. CI doesn't run `typecheck`. Run `npx nx sync`, fix the theme spec types, then drop the flags from `docs/packages/nuxt-layer-base.md`.
- [ ] `/about` at desktop width (1280px): the Digital CV contact card breaks `likwidmack@gmail.com` in the middle of a word across three lines (`LIKWIDMAC`, `likwidmack@gmail.com`, `M`). This was there before PR 2 (the CSS is unchanged). Break at `@` and `.` instead, for example with `<wbr>` or `overflow-wrap: anywhere` on a wider column.

### Nuxt UI layer (follow-ups from PR 2 Task 5)

- [ ] Tabs: the selected tab is weight 700 and the others 500 (theme `globals/_primevue-union.scss`, 2026-10-19), so a tab's width shifts when it becomes selected and the labels next to it move. Reserve the bold width, e.g. a hidden bold copy of the label (`::after { content: attr(data-label); font-weight: 700; visibility: hidden; height: 0; }` on a `data-label` the tab renders) so the box is always as wide as the bold label.
- [ ] Tabs: PrimeVue's scroll buttons (`.p-tablist-prev-button` / `.p-tablist-next-button`, rendered when `Tabs` is `scrollable`) are plain `<button>`s without `.p-button`, so the theme's native button base still paints them with the primary gradient. No call site uses `scrollable` yet; exclude them from `button:not(.p-button, .p-tab)` (or style them with the tab rules) before one does.
- [ ] `ToastService` installs twice: `@primevue/nuxt-module` registers it (`Toast` is in the component list) and `packages/nuxt-layer-ui/app/feature-plugins/toast-primevue.client.ts` (added by the ui module when PrimeVue is on) calls `vueApp.use(ToastService)` again. That causes the dev warning "Plugin has already been applied", now in admin too, and the same `[Vue warn]: Plugin has already been applied to target app.` noise in the `nuxt-layer-ui:nuxt` mounted specs (for example `use-paged-list.spec.ts`). Drop the second install and read the service from the module's install, then check the mounted specs print no Vue warning.
- [ ] `UiColorPicker` renders `PrimeColorPicker`, which is missing from the theme's `DEFAULT_COMPONENTS` include list (`theme/core/src/primevue.ts`). It works on `/styles` only because `autoImport: true` resolves `Prime*` tags on demand. `packages/nuxt-layer-ui/tests/primevue.spec.ts` lists it as `autoImportOnly`. Add `ColorPicker` to the list so the list is complete, then re-run the CSS gate.
- [x] `UiButton.vue` reads the web global `--portfolio-rose-color`. Replace it with a theme role (roadmap Task 6), then give the ui layer a theme-only colour guard like the base layer's `tests/colors-scss.spec.ts`. **Done:** it reads `--theme-link-color`, and `packages/nuxt-layer-ui/tests/colors-scss.spec.ts` is the ui layer's colour guard.
- [x] The `nuxt-app` generator still emits `extends: ['@tgmc/nuxt-layer-base']`. Switch it to the ui layer (roadmap Task 5b). **Done:** it extends `@tgmc/nuxt-layer-ui` (`--no-ui` for the base layer), writes a `tgmc:` block and lists only the chosen features' packages ([nuxt-app-generator.md](../../packages/nuxt-app-generator.md)).
- [ ] `UiCodeBlock` stays in `core/web/app/components/ui` because it imports the syntax engine (`core/web/shared/syntax`, specs in `core/web/tests/shared/syntax` and `syntax-entities.spec.ts`). Move `UiCodeBlock` and the engine into the ui layer together.
- [ ] Mounted-test matrix (roadmap Task 6): done for `UiButton` and the six form controls (`tests/nuxt/ui-<component>.spec.ts`), in PR 3 for the four form parts (`ui-form.spec.ts`) and `UiConfirmDialog` (`ui-confirm-dialog.spec.ts`), and in PR 4 for `UiConfirmInline` (`ui-confirm-inline.spec.ts`) and `UiUndoNotice` (mounted by `use-confirm-undo.spec.ts`; features-off specs for both). Mounted since the media-fallback work: `UiImage` (`ui-image.spec.ts`) and `UiSvgImg` (`ui-svg-img.spec.ts`), both stacks, failure fallback included. Still open for the other 22 components, each to get a spec when it is next touched: `UiAccordion`, `UiAvatar`, `UiBadge`, `UiCard`, `UiChip`, `UiColorPicker`, `UiDatePicker`, `UiDialog` (partial: `ui-dialog.spec.ts` covers role, open state and the native backdrop only; see [§ PR 3 Task 7](#forms-template-follow-ups-from-pr-3-task-7)), `UiDivider`, `UiFloatLabel`, `UiIcon`, `UiInputNumber`, `UiMessage`, `UiPanel`, `UiProgressBar`, `UiProgressSpinner`, `UiRadio`, `UiSkeleton`, `UiTabs`, `UiTag`, `UiTimeline`, `UiToastHost`. Features-off specs exist for `UiIcon` and the native `UiChip` (`ui-icon-off.spec.ts`) and for `UiToastHost`'s native list (`ui-toast-host.spec.ts`); they don't replace the full matrix.
- [ ] The `nuxt-layer-ui:nuxt` Vitest project works around a Vite mismatch in `packages/nuxt-layer-ui/vitest.config.ts` (Nuxt's builder runs on Vite 8, Vitest on the root's Vite 7: it drops the rolldown-only `nuxt:replace` plugin and applies the `import.meta.*` defines itself). Remove the workaround once the root Vite and Nuxt's builder agree.
- [ ] `UiUndoNotice` `holdSpace` holds the space of every line that leaves, so after an Undo in the media phone sheet a blank band also stays under the heading until the sheet closes. Holding only committed lines needs the controller to say why a line left (a commit vs an Undo signal on `useConfirmUndo`); add it and release the space on Undo.
- [ ] Admin media drawer sheet: with the default keep list, anything inside `#teleports` or a live region stays reachable while the sheet is open. Check that no teleported overlay with controls (PrimeVue popup, confirm dialog) opens from the sheet without its own focus handling.
- [x] 2026-10-19, superseded by the gallery redesign: the feed dialog ("Back to grid", one scroll-snap list) is gone; the full view (`GalleryViewer`) replaced it. What still applies to the full view:
  - [x] **Accepted limit (owner decision 2026-10-19), not a TODO:** Escape does not close the full view while focus is inside Chrome's built-in video controls. Measured 2026-10-19 (on the old feed, same native `<video controls>`): on the `<video>` itself Escape reaches the page's `keydown` listener and closes; inside the built-in controls Chrome sends no `keydown` / `keyup` / `keypress` to the page at all, not even to a `window` capture listener, so no page code can catch it. The full view keeps native controls (custom controls were the alternative). From the first built-in control, Shift+Tab once returns to the video, where Escape works. Documented in [gallery-and-docs.md](./gallery-and-docs.md#gallery).
  - [x] `GalleryViewer` focus trap: done (cognitive a11y fixes, 2026-10-22). Tab and Shift+Tab wrap inside the dialog through `useFocusTrap` (`core/web/tests/gallery-viewer.spec.ts`).
- [ ] Admin database selector: a new browser session always starts on SQLite because `defaultAdminSession()` (`packages/web-layer-admin/app/utils/admin-session.ts`) hard-codes `'sqlite'`. The Docker admin stack's `DEFAULT_ADMIN_DATABASE=dynamodb` (`public.defaultAdminDatabase`) is used only when SQLite is not allowed. Seed the session from `public.defaultAdminDatabase`.
- [x] `UiButton` with `href` renders `<a type="button" disabled="false">`, attributes that are invalid on a link. Fix with the `as` prop (roadmap Task 6). **Done:** `to` renders a `NuxtLink` and `href` an `<a>`, neither with `type` / `disabled`; the call sites use them and `core/web/tests/ui-button-call-sites.spec.ts` keeps undeclared props out.
- [ ] `UiSelect` in the PrimeVue stack can't be named by `<label for>`: its combobox is a `<span role="combobox">`, which isn't labelable. Audit the callers that rely on a label, starting with `AppStylesParity/index.vue:251` (`input-id="styles-ui-role"`), and consider deriving `aria-labelledby` from the matching label. **Partly done (PR 3):** a control inside a `UiFormField` is named by `aria-labelledby` pointing at the field's label, so `UiSelect` in a form field has a name (the admin blog editor's Status). Still open for callers outside a form field, such as `AppStylesParity`.
- [ ] The blueprint's `UiVisuallyHidden` (tier 0) doesn't exist; `UiButton`'s new-tab note uses the theme's `.sr-only` class. Add the component, or drop it from the blueprint.
- [ ] Dev server: Vite's dependency scan fails with `Missing "#components" specifier in "@nuxtjs/i18n" package`, so dev pre-bundling is skipped (the server still runs). Seen during PR 2 Task 5 verification. It was not compared against an earlier run, so it is not known whether PR 2 introduced it.

### Optional layer features (follow-ups from PR 2 Task 5b)

- [ ] `installModule` is deprecated in `@nuxt/kit` 4.6; the layer modules (`tgmc-features.ts`, `tgmc-ui.ts`) keep it because `moduleDependencies` installs after app modules and changes CSS order. Revisit when Nuxt offers ordered dependencies.
- [ ] Owner decision (optional): expose `bp-up` / `bp-down` / `touch-target` / `font-size-floor` to layer SFCs? They are not in `nuxt-auto` today; forwarding `globals/_mixins` from it breaks `core/web` (duplicate global module). If they are added, the theme-off fallback (`packages/nuxt-layer-base/scss/_fallback.scss`) mirrors them.
- [ ] Media components (roadmap Tasks 12b / 12c) go in `packages/nuxt-layer-ui/app/components/media/` (empty today, registered only with `tgmc.media`); the build-matrix probe's `media` marker then starts reporting them.
- [ ] Feature-flag gating still owed by later tasks: the Tiptap `mediaEmbed` extension and "Insert media" button appear only with `useTgmcFeatures().media` (roadmap Tasks 11, 12b / 12c); `UiDataTable`, `UiChart` and `UiRichTextEditor` fall back to native markup with `.primevue` off (roadmap Tasks 9, 11).
- [ ] Native toast list (`UiToastHost` with PrimeVue off): the `Dismiss` button sits inside the live region, so some screen readers read "Dismiss" after each message. Consider moving the dismiss controls outside the regions.

### Forms template (follow-ups from PR 3 Task 7)

- [x] Forms template (roadmap Task 7): `UiForm`, `UiFormField`, `UiFormErrorSummary`, `UiFormActions` and `useForm()` on Standard Schema, server errors on their fields (422, and 409 on the slug), the in-page "Leave without saving?" dialog (`useUnsavedChangesGuard` with `UiConfirmDialog`), and the admin blog editor as the reference page on one shared zod schema ([ui-components.md § Forms](./ui-components.md#forms), [admin.md § Blog editor](./admin.md#blog-editor)).
- [x] Admin blog delete: Undo. **Done (PR 4, owner Q1 A):** the editor confirms with `UiConfirmInline` and hands the post to the list, which runs the Undo window and the delete through `useCrudResource`; the list's status filter is in the URL ([admin.md § Blog list](./admin.md#blog-list)).
- [ ] Admin blog editor: switching the database in the header drops unsaved edits without the leave prompt. `watch(adminDatabase)` reloads the post and runs `form.reset(post)`; the leave guard covers navigation only. Ask first (the same `UiConfirmDialog`), or keep the edits.
- [ ] Admin blog editor: after a create, "Post created." is announced but not shown. The page remounts on `/admin/blog/<id>` (the page key is the path), and the new instance's status starts idle. Carry the status over (for example in `useState` or a query flag) or show it on the new page.
- [x] ESLint: the base `no-unused-vars` rule flagged parameter names in TypeScript type signatures. It is now off for TS and Vue files in every project (root `.eslintrc.json` TS override, the Nuxt flat configs, and the `image` / `media` / `media-player` configs); `@typescript-eslint/no-unused-vars` covers them. The TS override also keeps the root's `no-explicit-any: off` (the `@nx/typescript` preset had turned it back on), and test code (`core/web-e2e`, `packages/utilities/tests`) allows non-null assertions. `npx nx run-many -t lint` reports 0 problems.
- [ ] `core/web/content.config.ts` imports `z` from `zod/v3`, because `@nuxt/content` 3 converts zod 3 schemas (owner Q4 A). Move it to the zod 4 API, and check that the generated content output is unchanged, when convenient.
- [ ] `UiDialog` tests: `tests/nuxt/ui-dialog.spec.ts` covers only `role`, the open state and the native backdrop. Untested: `header` and `ariaLabel` naming in the native stack, `closable`, `modal` / `aria-modal`, the `footer` slot, native Escape (`cancel` / `close`), PrimeVue's Escape and focus return, and `v-model:visible` in the PrimeVue stack. Give it the full matrix when it is next touched.
- [ ] Native-stack `UiDialog` now closes on a backdrop click (`dismissableMask`, on by default), as the PrimeVue stack already did. Check each `core/web` caller (`AppPersonalize`, `AppEvidenceExamplesDialog`, `AppStylesParity`) in the native stack; a caller that must not close that way passes `:dismissable-mask="false"`.
- [ ] `invalid` prop on `UiCheckbox`, `UiPassword`, `UiToggleSwitch`, `UiRadio`, `UiDatePicker`, `UiInputNumber` and `UiColorPicker` (PrimeVue supports it on each), so they can take `UiFormField`'s `invalid`. Add `invalid: true` to each control's matrix spec with it.
- [ ] Other admin forms (messages, CDN, media) can move to `useForm()` / `UiForm`.
- [ ] Leave guard: after Leave, every navigation passes until the page unmounts, so if that navigation is aborted without a redirect (route middleware returns `false`), the page stays and later navigations no longer ask. In apps with pages, checking `to.redirectedFrom` would avoid that; Nuxt's minimal router (pageless apps and the ui layer's test app) never sets it, which is why the flag is used.
- [ ] zod is bundled into the public `core/web` server: the public `GET /api/posts` routes import `server/api/posts/service.ts`, which imports `parse-body.ts` and the shared schema, although only admin writes parse bodies. Split the write parsing out of the read service if the Lambda's size matters.
- [ ] `cd core/admin && npx nuxi typecheck` exits with 35 errors that predate PR 3, all TS6310 ("referenced project may not disable emit") and TS6305 ("output file has not been built") for `core/admin/app/**`. The layer's blog page isn't in that program either, so admin pages have no type check. Fix the project references, and include the admin layer's pages.
- [ ] Dialog surface: the theme gives `.p-dialog` a glass panel (16% surface, `theme/core/scss/globals/_primevue-union.scss`), and over the opaque mask its text drops below 4.5:1. Each app overrides it: `core/web/assets/css/_globals.scss`, and since PR 3 verification `core/admin/assets/css/admin.scss`. Decide whether the theme or `@tgmc/nuxt-layer-ui` should give dialogs a solid surface for every app.

### Lists and deletes (follow-ups from PR 4 Task 8)

- [ ] Blueprint § 4 ([nuxt-layers.md](../../packages/nuxt-layers.md#4-data-and-crud)) still shows the planned signatures; update it from [ui-components.md § Differences from the blueprint](./ui-components.md#differences-from-the-blueprint) (owner).
- [ ] A reload or tab close drops pending deletes (owner Q2 A); revisit with `fetch(…, { keepalive: true })` on `pagehide` if it bites (admin/media review 2026-10-21, M11).
- [ ] CDN (M3) and messages lists move to `useCrudResource` with `UiCrudView` (roadmap Tasks 9–10).
- [ ] Admin media: uploading a file name whose delete is still pending returns 409 `name_conflict` for the rest of the 8 s Undo window (the object is only removed when the delete commits). Either commit the pending delete of that name before the upload, or say in the conflict message that the delete is still pending.
- [ ] Media drawer: `useUnsavedDetails` still asks with `window.confirm` (`core/admin/app/composables/useUnsavedDetails.ts`); move it to `UiConfirmDialog`.

### Admin media library: all media types

The DAM is meant to hold **audio, video, images, SVG (vector), 3D / XR objects and text documents**. `MediaKind` is `image | svg | audio | video | model | document` (`packages/media/src/kinds.ts`, `@tgmc/media-client`). Editorial facets use **`meta.tags`** (and optional facet keys like `animated` / `panorama`) — not extra kinds or multicategory.

- [x] Add `model` (3D / XR: `.glb`, `.gltf`, `.usdz`), `document` (`.md`, `.txt`, `.pdf`), and `svg` (parallel to raster image) kinds to `@tgmc/media` types, recipe parsing (`parseRecipe`), stub transformers, and `@tgmc/media-client`.
- [x] Admin page: widen the drop-zone `accept`, `guessKind()` (by MIME and extension — `.glb` often has no MIME), the **Kind** filter options and `countByKind()`.
- [x] Tags / meta: `meta.tags` helpers, list `?tag=`, PATCH meta, admin drawer add/remove + tag filter (no subcategory / multicategory kinds).
- [x] Kind-appropriate tiles and drawer previews: plan PR 4 — `previewUrl` tiles (image `t` thumbnail, SVG original) with a Lucide kind icon otherwise, drawer `<img>` / `<audio>` / `<video preload="metadata">` and a facts panel for 3D and documents ([admin.md § Local media library](./admin.md#local-media-library-dam)).
- [ ] Richer kind previews: 3D `<model-viewer>`-style poster, document first page / text excerpt, audio waveform, video poster frame (today: icon or facts panel, and the player's first frame).
- [ ] Kind-appropriate variant presets (e.g. 3D poster render / LOD, document thumbnail / text extract, SVG optimize/rasterize, audio preview clip, video poster) — `MEDIA_RECIPE_PRESETS` is image-only.
- [x] A read-only blob or thumbnail endpoint for admin so tiles show real previews for previously uploaded assets: plan PR 4 — list / detail / upload responses carry `publicUrl` / `previewUrl`, the local admin DAM serves `/m/**`, and every uploaded image gets its `t` thumbnail.
- [x] Pagination / "Load more" past the 100-asset API page: plan PR 4 (appends the next page and announces the count; after the last page, focus moves to the first new tile).

### Site media in the library (owner request 2026-10-21)

Today the site's own media (`core/web/content/media.json`: portrait, case-study heroes and artifacts, work cards, gallery, PDFs, MP4s) stays as static build files under `/i`, `/v`, `/d` and is not in the catalog ([site media](./site-media.md), owner decision 2026-10-17). Goal: manage it in the admin media library instead. Moving it replaces that decision, so update `site-media.md`, `cicd.md` and `image.md` when it lands.

- [ ] In-use safeguards first (owner decisions 2026-10-21; design [`2026-10-21-media-usage-safeguards-design.md`](../../superpowers/specs/2026-10-21-media-usage-safeguards-design.md)): pages reference library media by asset id; deleting an asset a **published** page uses is **refused** and lists those pages, with an audited force for the admin only, after which the pages show a placeholder automatically; renaming warns and lists the pages; media slots become admin-editable; every media kind has a fallback when its file is missing.
  - [x] Fallbacks per kind (plan 1, [`2026-10-22-media-usage-safeguards.md`](../../superpowers/plans/2026-10-22-media-usage-safeguards.md)): media slots (`AppMediaFile`) and case-study media show a labelled stand-in for a failed image, svg or video; other direct `UiImage` / `UiSvgImg` callers get an empty frame named by `alt`, never a broken icon ([site media § Fallbacks](./site-media.md#fallbacks-when-media-is-missing)); real-browser check `core/web-e2e/src/e2e/media-fallback.cy.ts`.
  - [ ] Gallery video: `GalleryExhibit` renders a raw `<video>` with no fallback; give it the video fallback (poster or placeholder, no empty player).
  - [ ] Pass a `#fallback` (`AppPlaceholderMedia` / `AppMediaFallback`) from the other `UiImage` / `UiSvgImg` callers: `AppWorkCard`, `AppOrbitStage`, `GalleryExhibit` images, the About portrait (today an empty, named frame).
  - [ ] Documents and models: detect a 404 file (today only an unresolved reference falls back, plan 3's path; a document link is never probed).
  - [ ] `validateMediaSlots` rejects a blank `alt` (a slot fallback would otherwise be unnamed).
  - [ ] A server-rendered hero-video e2e once content has a case study with a video hero (today `media-fallback.cy.ts` builds one by client navigation).
  - [ ] One SSR error-marker helper exported by the ui layer (`onerror` → `data-error`): three copies today (`UiImage`, `UiSvgImg`, `useMediaFailure`'s `imgSsrErrorAttrs`).
  - [ ] `data-media-kind` means a `SiteMediaKind` on `AppMediaFile` but `diagram` on case-study media: rename one when plan 3 spreads `AppMediaFile`.
  - [ ] The poster `img` that `AppMediaFallback` renders has no SSR error marker, so a poster that fails before hydration stays broken until a client render (plan 3).
  - [x] Plan 2 — usage list and delete / rename safeguards ([`2026-10-22-media-usage-safeguards-plan-2.md`](../../superpowers/plans/2026-10-22-media-usage-safeguards-plan-2.md)): per-asset usage rows on all three backends, delete refused (409 `in_use`, listing the pages) inside the cascade's atomic step, admin-only audited force, rename `usedBy`; `@tgmc/media-client` and the admin server pass them through, and the admin media page explains a refusal in its message line.
  - [x] The admin UI for refusals (plan 4): the media drawer's **Used by** list, Delete… checking first and refusing an asset in use, **Delete anyway** confirmed in place with the 8 s Undo, the rename warning, and **Rebuild usage list** ([admin § Used by, refusal and Delete anyway](./admin.md#used-by-refusal-and-delete-anyway)).
  - [ ] After `transferMedia` between backends, run the usage rebuild on the target: usage rows are not transferred.
  - [x] The CD post-deploy usage rebuild (plan 4): `scripts/media-usage-rebuild.js`, gated by `MEDIA_USAGE_REBUILD_ENABLED=1` ([cicd.md](../../cicd.md)).
  - [ ] Plan 2 follow-ups (deferred review minors):
    - [ ] `npx nx run @tgmc/media:typecheck` checks nothing (`tsc --build` with no references); fix the target (meanwhile `tsc -p packages/media/tsconfig.lib.json --noEmit`).
    - [ ] `normalizeUsageTime` accepts any `Date.parse` string (`"1"`, `"Oct 1 2026"`): tighten it to strict ISO.
    - [ ] Postgres single-statement autocommit writes (`removeAssetUsage`, child updates, job claims) inherit `default_transaction_isolation`: pin READ COMMITTED per connection or document that the server default must be it.
    - [ ] Load `core/web`'s own Postgres messages / posts stores lazily (they import `pg` statically, so it still loads at Lambda boot).
    - [ ] DynamoDB usage: an in-memory test of two writers alternating chunks on a page with more than 20 assets, and a live `TransactionConflict` case on DynamoDB Local.
    - [ ] Route tests: a tenant `?force=1` on an unknown or other-tenant id is a 403 (not 404); a cross-tenant 404 body equals the missing-id one.
    - [ ] A forced delete whose cascade fails with a non-in-use error leaves `asset.delete_started{force}` open with no `asset.delete_failed`; `resumeDelete` casts `pages` without a shape check.
    - [ ] SQLite and Postgres store-level `deleteAsset` have no usage check (DynamoDB's refuses); only ingest rollbacks of just-created assets call it today.
    - [ ] Gated live Postgres lock tests detect waiting with a 300 ms settle: poll `pg_stat_activity` for a lock wait instead.
    - [ ] DynamoDB usage: a plain delete of the last row leaves an n=0 counter item (index-2); make that a conditional Delete.
    - [ ] Postgres `rebuildUsage` takes every page advisory lock in one transaction: batch per page, or note the limit in `docs/packages/media-postgres.md`.
    - [ ] `media delete` CLI has no `--force`, so it fails on an in-use asset.
    - [x] A forced delete of an unused asset audits `force_deleted` with `pages: []` and returns `forced: true`: plan 4 offers Delete anyway only from a refusal, so the admin's forced deletes always have pages ([media § Usage list and delete safeguards](../../packages/media.md#usage-list-and-delete-safeguards)).
    - [ ] Media on Postgres: a missing `DATABASE_URL` fails on the first media request, not at boot; the lazy pool caches a failed `import('pg')`.
  - [x] Plan 3 — slots and post references with the resolver ([`2026-10-22-media-usage-safeguards-plan-3.md`](../../superpowers/plans/2026-10-22-media-usage-safeguards-plan-3.md)): slot store, `coverAssetId` and `asset:` body references, `resolveMediaRefs` with its cache cleared on delete, usage writes on publish, slot views and blog covers / embeds on public pages ([site media § Library media on public pages](./site-media.md#library-media-on-public-pages)).
  - [ ] Plan 3 follow-ups (deferred review minors):
    - [ ] `splitBodyMedia` CommonMark edge cases: the fence pattern is not end-anchored and accepts a backtick info string; a reference line indented 4+ spaces (code) or inside a list / blockquote counts as a block; fences in list items with 4+ indentation; a block line with text right above or below cuts the paragraph, and link reference definitions don't carry across segments. Add tests for CRLF, indented, list / blockquote and unterminated fences.
    - [ ] Resolver tests for a `getAsset` failure that is not not-found, and for a poster lookup that fails.
    - [ ] DynamoDB / slot store: an unknown tenant's key falls back and can collide, and `get` does not check `item.tenant` (tenancy work).
    - [ ] Slot store tests: concurrent seeding, and a multi-page DynamoDB slot list (matters as the Posts table grows).
    - [ ] A service test: a slug-conflict create clears the pending pages of its pre-generated id.
    - [x] Bound a pending usage write that never settles. **Done:** the live write waits at most `PENDING_SETTLE_MS` (10 s) for it, and on Lambda (no platform `waitUntil`) the response awaits the write's `waitUntil` work for at most 5 s (`core/web/server/plugins/media-usage-wait.ts`, logged `media.usage_wait_timeout` when cut); rows a cut leaves `pending` are settled by the post-deploy rebuild (`MEDIA_USAGE_REBUILD_ENABLED=1`) or **Rebuild usage list** ([site media § Usage list writes](./site-media.md#usage-list-writes)).
    - [ ] The compatibility `html` in `GET /api/posts/:slug` renders block references as unavailable text (only the github.io export and older clients read it).
    - [ ] A decorative body embed without a written alt gets the asset's alt; align it with the cover rule.
    - [ ] Pre-existing stderr noise in `posts-write-conflict.spec.ts` and `nitro-externals.spec.ts` (the specs pass): silence or assert it.
  - [ ] Plan 4 — admin write endpoints and admin UI: posts / slots CRUD through the web, the media-slot picker, **Used by**, the refusal and **Delete anyway** with Undo, the usage rebuild.
    - [x] Web write endpoints for posts (`/api/blog/posts…`, [admin](./admin.md#web-write-endpoints)).
    - [x] Web write endpoints for slots (`/api/media-slots/records`, `PUT /api/media-slots/:id`, `POST /api/media-slots/:id/reset`; [site media](./site-media.md#media-slots-and-placeholders)).
    - [x] Admin forward mode (`MEDIA_API_URL`): posts, slots and the rebuild forward to the web's endpoints, which record the usage ([admin § Forward mode](./admin.md#forward-mode)).
    - [x] Slot writes record usage with `slotUsagePage` and call `clearMediaSlotCache()`.
    - [x] One usage sync per write (the sync keeps per-write state), documented in [site media](./site-media.md#usage-list-writes); the live write waits at most `PENDING_SETTLE_MS` (10 s) for a stuck pending write.
    - [x] Reset a slot to its seed in the admin UI (**Done:** **Reset to seed…** on [Admin → Slots](./admin.md#slots)), or pick up `media-slots.json` changes for slots never edited in the store (today a seeded slot ignores later JSON edits on the live site; [site media](./site-media.md#media-slots-and-placeholders)).
    - [ ] Captions for library video and audio (asset meta or a captions asset): body embeds have no `track` or transcript today. Video / audio without captions are warned, not blocked (owner 2026-10-23; **Insert media** shows "No captions yet"); captions support still open.
    - [x] The cover form trims `coverAlt` (a blank alt is already ignored when rendering). **Done:** the shared schema trims it and saves a blank alt as `null`.
    - [x] The slot picker ([Admin → Slots](./admin.md#slots)).
    - [x] The cover picker, and **Insert media** for the post body ([admin § Blog editor](./admin.md#blog-editor)).
    - [x] A "needs media" filter for slots (on a placeholder or unavailable; [Admin → Slots](./admin.md#slots), `?filter=needs-media`).
    - [x] A "needs media" filter for posts (covers or embeds that do not resolve; [admin § Blog list](./admin.md#blog-list), `?media=needs`).
  - [ ] Plan 4 follow-ups (deferred review minors, final review triage):
    - [ ] `needsMedia` can make two resolve calls (the posts', then the slot views' own, cached): resolve once.
    - [ ] `core/web/server/utils/blog-post-writes.ts` also holds the slot route helpers: rename it (for example `admin-write-routes.ts`).
    - [ ] A test that a throwing `requireMediaAdmin` stops `readBody` and the service on the admin slot and post routes.
    - [ ] `cicd-workflow-policy.test.mjs` does not assert the rebuild step's `--stack-name "${STACK_NAME}"`.
    - [ ] `scripts/media-usage-rebuild.js`: a 200 with missing or non-numeric counts prints `undefined`, and a non-JSON body throws a bare `SyntaxError`.
    - [ ] Media picker: "No images match your filter." while more pages exist (offer Load more in that message).
    - [ ] Media picker: a test for the filter announcement after unmount or close (the debounce must not fire).
    - [ ] Slots page asset names: refetched after a failure, not tied to `listRequest`, not cleared on a database switch; let the list route return the names.
    - [ ] `slots.vue` is about 700 lines: extract `AdminSlotEditor`.
    - [ ] Blog cover **Clear** finds **Choose cover** with a global `querySelector`: use a template ref.
    - [ ] The blog list filter test greps the source: mount the list with `?media=needs` instead.
    - [ ] **Insert media** mid-line splits the paragraph, and inside a code fence the reference renders as code but still counts as usage (documented in [site media](./site-media.md#blog-covers-and-embeds)): insert at the line's end, or warn inside a fence.
    - [ ] A usage read that keeps failing blocks Delete… (fail-closed); a "Delete without checking…" fallback is safe because the server refuses atomically.
    - [ ] A shown refusal is not re-checked after **Rebuild usage list** (`onUsageRebuilt` could reset the step).
    - [ ] The docker guard for `media-site-origin` checks the plugin's source text only.
    - [ ] `httpOriginOf` (`core/admin/server/utils/media-site-origin.ts`) is a global server auto-import: rename it if a name collides.
    - [ ] `server/plugins/media-site-origin.ts` clones the runtime config on every request: scope it to page renders if it shows in profiles.
    - [ ] A guard test that core/admin's `AdminBlogMediaFields` overrides the layer's (Task 7 ruling; proven today by a `nuxi prepare` check and the browser, not a committed test).
- [ ] Catalog variant ladder that matches the build-time `_ipx` one: the 7 widths in `IPX_VARIANT_WIDTHS` plus WebP, so the `/about` and case-study `sizes` work keeps its candidates (today the catalog makes `t`, 640, 1280, 1920).
- [ ] How pages get versioned URLs (`?v=<sha8>`): a catalog read at render time, or a committed export (`media:site-manifest --from`); keep the github.io static copy and offline builds working.
- [ ] A stable, absolute, unversioned URL for the default social image (`og:image`).
- [ ] Redirects (301) from the old `/i`, `/v`, `/d` paths, including the résumé and deck PDFs that external links use.
- [ ] Clear the `reviewNotes` on the 13 manifest entries that still have them, then run `media:site-import` per environment (test, production, Docker, local).
- [ ] E2E and local fixtures: real site images instead of the one stubbed `/m/` WebP; video and PDF stubs.

### Public repo links (likwidmack/portfolio)

All code / doc links now point to `likwidmack/portfolio` on `main` (repo rule — see `docs/agents/README.md`). The public repo does not yet contain every linked path, so these 404 until the mirror syncs them:

- [ ] `docker/`, `infra/sam/`, `scripts/`, `archive/v3/`, `AGENTS.md`, `.env*.example`, `docs/superpowers/`
- [ ] `packages/image`, `packages/media`, `packages/media-aws`, `packages/media-client`, `packages/media-nuxt` (package `homepage` fields)

### Site navigation

A link audit (crawl of every page, October 2026) found no broken links outside `/docs`, but several sections are hard to reach. Each change must cover responsiveness (no page-level horizontal overflow, phone to desktop), accessibility (keyboard, focus ring, screen-reader names, `aria-current`) and touch (≥ 44px targets, no hover-only affordances).

- [ ] Docs, AI Lab and Process are reachable only from the **Related** panel on case-study pages (`AppWorkSubNav` in `app/pages/work/[slug].vue`) and the Writing cards. Add entry points: the `/work` overview, the footer, and/or the phone Menu dropdown (`shared/primary-nav.ts`, `shared/work-sub-nav.ts`).
- [x] Decide whether the primary rail stays Work / About / Gallery / Writing / Code or gains a Docs (or "More") entry; update `shared/primary-nav.ts` and its tests together. — decided 2026-10-14: About, Work, Gallery, Code, Writing; no Docs entry ([site-header.md](./site-header.md)).
- [x] Header home link: in-app navigation to `/` shows the splash; "Skip the splash" resumes the last view on the first HTML response only (`app/middleware/home-landing.ts`, pinned in `core/web/tests/home-landing.spec.ts`; see [portfolio-august-launch.md](../../portfolio-august-launch.md)).
- [ ] Header home link: add an e2e case — with skip on, open a case study, activate the brand link, expect the splash; reload `/`, expect the case study.
- [x] In-app `/docs` links: the 64 GitHub-relative links that 404'd (`../docker/`, `./web/README.md`, `../superpowers/…`) now map to lowercase doc routes or the public repo (`app/components/ProseA.global.vue`, `shared/docs-links.ts`, `core/web/tests/docs-links.spec.ts`; [gallery-and-docs.md § Technical documentation](./gallery-and-docs.md#technical-documentation)). A full crawl finds 0 internal 404s.
- [ ] Add a link-crawl check (CI or e2e) so new pages and docs can't reintroduce internal 404s.
- [ ] External links: `https://web.dev/cdn/` (cdn-guide) is dead; the `tamaramack/portfolio` PR links (#214, #235, #239) 404 for signed-out visitors; the public-repo gaps are listed above.
- [ ] Breadcrumbs and back links: check every page has one consistent way up (`AppBreadcrumbs`, `.back-link`) — case studies say "← All work", docs "← All documentation", other pages vary.

### Gallery (follow-ups from the 2026-10-19 redesign)

The redesign ([gallery-and-docs.md § Gallery](./gallery-and-docs.md#gallery); spec `docs/superpowers/specs/2026-10-19-gallery-redesign-design.md`) left these out on purpose. Each change must cover responsiveness, accessibility and touch like the rest of the gallery.

- [ ] **Likes:** no likes, comments or engagement backend yet (`gallery.json` still carries `views` / `likes`, which nothing shows since the feed cards went). Design a like action for the full view (44px button, `aria-pressed`, a polite count) and where the counts live.
- [ ] **Item page for link previews:** a shared `?item=<id>` link previews as the gallery page (one title, description and image for every piece). Build an item page (or server-rendered per-item meta) with the piece's own title, description and image, and make Share point at it.
- [ ] **Case studies:** every post has a placeholder `caseStudy` (`/work`) unless it already linked one (`/work/spatial-experiences`). Build up the case studies and replace the `/work` placeholders in `core/web/content/gallery.json`.
- [ ] **Grid virtualization / pagination:** the grid renders every post (lazy media, previews only in view, the viewer mounts ±1; see [Performance](./gallery-and-docs.md#performance-100-posts)). Revisit virtualization or pagination once the gallery passes ~300 posts.
- [ ] **Tile markup:** each grid tile is a `<button>` that wraps block content (the exhibit, label and tags). Refactor to a stretched button sibling over the tile (Ruling 20), so the tile's content is not inside an interactive element.
- [ ] **Tile titles on touch:** a tile shows its title only on hover / focus, so touch readers see tags but no title. Decide on an always-visible (or first-row) title treatment for touch.
- [ ] **Text-only zoom:** the grid measures the root font size on resize only, so a text-only zoom does not relayout the rows (or re-size the photo requests) until the next resize. Watch the root font size (e.g. a `ResizeObserver` on an `em`-sized probe).
- [ ] **Programmatic focus starts a preview:** hover and focus share one preview state, so focusing a tile from script (the `?specimen=` link, focus return from the full view) starts its silent preview. Split keyboard focus from programmatic focus (`:focus-visible`) or skip previews on programmatic focus.
- [ ] **Share fallback on Safari:** after a failed share sheet, Safari may have dropped the user activation before the clipboard fallback runs, so the copy fails and the link field shows. Check on Safari / iOS; copy first or keep the field path if it does.
- [ ] **Dates:** the content schema's date regex accepts impossible dates (`2026-02-31`), and the newest / oldest sort compares dates with `localeCompare`. Validate real calendar dates and compare parsed dates.
- [ ] Theme filled-secondary button pair fails contrast in light mode (1.29:1 measured on the gallery menu, 2026-10-19); no consumer today — fix the pair before using it. (`UiButton` with `severity="secondary"` and no `variant`; the gallery menu's Play feed now uses `variant="outlined"`.)
- [ ] Theme outlined secondary buttons (`UiButton severity="secondary" variant="outlined"`, `_primevue-union.scss` `.p-button-outlined.p-button-secondary`) draw their border in the 8% `--theme-border-color` hairline: about 1.2:1 on the page and on glass, under WCAG 1.4.11's 3:1 where the border is the only boundary. The gallery menu overrides it with `--theme-text-secondary-color` (2026-10-19, [gallery-and-docs.md § Contrast on glass](./gallery-and-docs.md#gallery)); decide the site-wide border (the strong border role passes on plain grounds, not on glass) and check every consumer. Also: `--theme-border-strong-color` (inputs, `UiSelectButton`) is 2.4:1 dark / 2.9:1 light on an 88% glass panel; it is only guaranteed on the plain surface.

### Admin + media hardening (review 2026-10-21)

Done on `cl/admin-media-hardening`: I1 delete keeps the name held until the objects are gone (resumable); I2 a failed CDN purge after a delete is audited, not a 500 (retried by deleting again); I3 versioned media URLs (`?v=<sha8>`, CloudFront `m/*` cache key); I4 private `pending/` prefix + lifecycle (also closes M7: the local `/m/**` never serves pending uploads); I5 DynamoDB post / message lists read every page (+ cross-backend store contract); I6 forward-mode upstream 401/403 → 502; I7 admin upload caps; I8 weak admin tokens refused + admin Host allowlist; M1 atomic DynamoDB slugs; M2/M3 admin blog resolved after auth, body after auth; M4 shared AWS clients + timeouts; M5 admin token runtime-only; M6 partial create-only copy removed.

- [x] M7: local `/m/**` served pending objects. Closed by I4 (pending uploads live under `pending/`, which `/m/**` never maps to).
- [ ] M10: a retried `complete` re-encodes an already re-encoded raster (lossy each time, e.g. JPEG). Skip the re-encode when the stored object is already clean (`stillClean`, or record the sanitized SHA-256 in the pending object's metadata and compare).
- [ ] M12: `/api/image/ingest` and `/api/image/transform` are unauthenticated (gated to local / development only), and the transform disk cache is unbounded. Require the admin token (or remove them outside dev) and cap / evict the cache.
- [ ] I7 follow-up: admin local mode still uploads base64 JSON (capped now). Move it to the presign → PUT → complete flow the web uses (the `_local-s3` shim and `pending/` prefix exist), so no file is base64-encoded or buffered whole.
- [ ] I1 / I2 follow-up: a failed blob delete (`asset.delete_failed`) or CDN purge (`asset.invalidation_failed`, `hook: 'afterDelete'`) is retried only when someone deletes the gone id again. Add a sweeper (scheduled, or on admin load) that finds open ones and resumes them, and show them in the admin.
- [ ] M1 follow-up: DynamoDB posts written before the `SLUG#` claims have none until their next update; backfill claims for existing posts (one-off script) so the GSI pre-check is no longer needed for them.
- [ ] I4 follow-up: local and Docker `pending/` objects never expire. The S3 lifecycle rule only exists on AWS; the filesystem backends (`FsBlobStore` under `MEDIA_LOCAL_ROOT/blobs/pending/`) and MinIO keep abandoned presigned uploads forever. Add a sweep (on startup or on presign) that deletes `pending/` objects older than a day, or a MinIO ILM rule in `docker/minio-init.sh`.
- [ ] I8 follow-up: the web app's own `/api/media/*` on `localhost` (`npm run dev`, `docker:local` / `docker:dev`) has no Host allowlist (only the admin does); weak tokens are refused there, but consider the same Host check for localhost-bound web stacks.

### Responsive images (follow-ups from the /about portrait, 2026-10-21)

Context: [site media § Responsive sizes and format](./site-media.md#responsive-sizes-and-format).

- [x] 2026-10-21: `AppCaseStudyMedia` takes a native `sizes`; the `/work/[slug]` hero and the Artifacts rasters in `content/media.json` get a WebP `w` ladder up to the source width (`shared/case-study-media.ts`), loading unchanged (hero eager). A 375 px DPR 3 phone now downloads a 127 KB WebP instead of the 3.4 MB PNG. Rasters outside the manifest keep the density srcset. ([site media](./site-media.md#responsive-sizes-and-format)). The Walkthrough slot is `AppMediaSlot` (placeholders today), not this component.
- [ ] `GalleryExhibit`'s `image` branch (`width="720" height="900"`, no `sizes`) has the same density-only srcset; its `media` branch already passes `sizes`.
- [ ] `AppOrbitStage` renders `UiImage` with no width or `sizes` (the full source); no page uses the component today.
- [ ] WebP for the other rasters: `AppWorkCard`, `AppMediaSlot` and `GalleryExhibit` pass `sizes` but not `format`. `format="webp"` now works on every build for the PNG / JPEG / WebP rasters (the CDN has a WebP variant of each); not for the GIF below.
- [ ] The animated GIF (`/i/tesseract/blue-8-cell-simple.png`, `ext: gif` in `content/media.json`) gets no `_ipx` variants: `IPX_RASTER_EXTENSIONS` in `shared/ipx-variants.ts` leaves GIF out, so on CDN builds a `UiImage` of it would link a missing variant (403). Decide: serve it as a plain file (no resizing), or add animated WebP variants (`sharp(input, { animated: true })`).
- [ ] AVIF (about 44% smaller than WebP for the portrait) needs a `<picture>` fallback. `NuxtPicture` puts the class on `<picture>`, out of reach of `UiImage`'s scoped styles and fade; `UiImage`'s `widths` mode (a plain `<img>`) could take AVIF and WebP `<source>`s instead. The CDN build step would also have to write AVIF variants (the S3 sync already types `.avif`).

### Other follow-ups

- [ ] Admin sign-in page (`packages/web-layer-admin/app/pages/admin/index.vue`): `@nuxt/a11y` (axe) logs `aria-allowed-attr` ("Elements must only use supported ARIA attributes") on the admin token password input in `nuxt dev`. Find the unsupported attribute (likely passed through the PrimeVue `Password` / input wrapper) and drop it or move it to a role that allows it.
- [ ] Admin dev server (`core/admin`, `nuxt dev`): one unattributed `503 (Service Unavailable)` shows in the browser console during startup / first page loads (seen 2026-10-19 while checking the blog list; the blog API calls all returned 200 and the dev log has no matching line). Find the request and decide whether it is expected (a backend probe for a database that isn't running) or a defect.
- [ ] Replace the media-slot placeholders (`core/web/content/media-slots.json`) with real images / video.
- [ ] Server cold start (media-nuxt page-load check, 2026-10-20): the web Nitro bundle (`inlineDynamicImports`) loads every static import at boot, and `@tgmc/media-aws` statically imports the S3, SQS and CloudFront SDK modules and the S3 presigner (~50 ms of a ~577 ms local boot, on every Lambda cold start too) although only the `/api/media/*` routes use them. svgo already loads on first use. The client objects are now created on first use and shared (`sharedS3Client`, `sharedCloudFrontClient`, review M4, 2026-10-21); what remains is loading the SDK modules through a cached dynamic `import()` in `@tgmc/media-aws` (`clients.ts`, `presign.ts`, `sqs.ts`, `invalidate.ts`), with a test like `packages/image/tests/sanitize-svg-lazy.spec.ts` and a boot measurement. Numbers: [media-nuxt.md](../../packages/media-nuxt.md#page-load-cost).
- [x] 2026-10-15: Likwidmack alignment full verification (Task 18): unit suites, script tests, units report, colour-name guard, builds and the whole Cypress suite (16 specs, 480 tests) pass against the local build. Fixed on the way: text `UiButton`s (header Personalize) had no focus ring (`.p-button-text { box-shadow: none }` beat the focus glow; pinned in `core/web/tests/focus-rings.spec.ts`); a complete `#rrggbbaa` in Style Studio's paper / ink fields shows the opacity alert again.
- [x] 2026-10-19: `npx nx run @tgmc/web-e2e:lint` reports 0 errors (warnings only); the `gallery-feed-dialog.cy.ts` chains and fixed wait went with that spec (replaced by `gallery-viewer.cy.ts`). Was: `@tgmc/web-e2e` lint had 7 errors (`cypress/unsafe-to-chain-command` in `app.cy.ts`, `gallery-feed-dialog.cy.ts`, `responsive-components.cy.ts`; `cypress/no-unnecessary-waiting` in `gallery-feed-dialog.cy.ts`), so `npm run lint` failed.
- [ ] Header **Get in touch** (`AppPrimaryNav.scss` `&__contact`, also `AppStoryPager`) is a solid primary fill, not the gradient CTA treatment; in light mode the theme draws no gradient on any solid button (`--button-solid-bg: none`). Decide whether Get in touch should become a gradient `UiButton` (dark mode) or stay solid, and update the Button README to match.
- [ ] Keyboard e2e: `cy.press(Tab)` does not move focus in headless Electron here, so tab order and focus rings are checked by hand (Task 18) or by DOM order. Add a real-keyboard check (CDP `Input.dispatchKeyEvent` or `cypress-real-events`) for header → Resume → doors.
- [x] 2026-10-14: PageNav current item = ink + link rule + selected fill; label not faded; reading-progress bar (`progressFor`) saved in `tgmc-journey-progress` for Resume (Task 10). Resume shows the last percentage written for that path, not the furthest: a write happens only when the reader moves 5+ points from the saved value (or reaches 100), so returning to the page without scrolling keeps the previous value, and scrolling back up past it lowers it. Nothing is written when cookies are blocked or on pages Resume cannot return to; `AppPageNav` without `progressFor` neither probes cookies nor listens to scroll. In forced-colors mode the current item gets a `Highlight` border in place of the dropped fill and rule.
- [x] 2026-10-14: WayIn splash (Task 11) — Resume bar first (title, “% read”, the page's only primary button `UiButton` Resume), unnumbered one-link door cards in an auto-fit row (`--grid-min: 16rem`, one column on phones, no sideways overflow at 320px with long labels), display uppercase labels, link-coloured counted scope, 2px lift + link border on hover and focus; skip label “Go straight to where I left off next time” kept. Pinned in `core/web/tests/home-page.spec.ts` and `core/web-e2e/src/e2e/splash.cy.ts`.
- [ ] Owner decision — PageNav `progressFor` is unused: no page passes it yet, so Resume never shows a percentage in practice. Candidates: product pages and blog posts (`AppPageNav` with `progressFor` set to the page's path).
- [ ] Owner decision — Resume lands at the top: the splash shows “% read” but Resume opens the page at the top. It could restore the reader's scroll position (from the saved percentage or a saved offset) instead.
- [ ] Owner decision — two sticky-offset tokens: unify `--main-top-padding` and `--header-height` for sticky offsets (both come from `useMeasuredChrome`), and wire `--gutter` into pages. Controller ruling 2026-10-14: deferred, to avoid regressing the sticky behaviour.
- [ ] Fonts: pin the Fontsource version (today `@latest`) or self-host the woff2 files under `core/web/public/fonts/` so a font update can't change metrics unannounced.
- [ ] Deployed test images: on `https://api.example.com` (the 2026-10-01 `main` build), every `/_ipx/*` request redirects (302) to the shared test CDN `https://cdn.example.com/_ipx/…`, which returns 403. `NuxtImg` images don't load there; for example both tesseract images on `/work/spatial-experiences` (plain `/i/*` files on the CDN load). Observed 2026-10-14; still 403 on 2026-10-19. **Fixed on `fix/content-api-cache` (verified on `docker:test`, not yet on AWS):** every `content/media.json` raster is written at build time to `public/_ipx/w_<width>/…` and `NuxtImg` links those files on the CDN through the `cdnIpx` provider; SVGs, videos and posters use `usePublicAssetUrl` ([site-media.md § Resized images on the CDN](./site-media.md#resized-images-on-the-cdn)). Re-check on the next test deploy. Follow-ups: rasters outside the manifest get no variants; variants keep the source format (the PNG sources make 28 MB of variants). Since 2026-10-21 every non-WebP PNG / JPEG raster also gets WebP variants (`.webp` keys, so the S3 sync types them), used where `UiImage` asks for `format="webp"` ([site-media.md § Responsive sizes and format](./site-media.md#responsive-sizes-and-format)).

- [x] Theme + Preferences deepen (two modules, one seam) — plan [`docs/superpowers/plans/2026-09-24-theme-preferences-deepen.md`](../../superpowers/plans/2026-09-24-theme-preferences-deepen.md); spec [`docs/superpowers/specs/2026-09-24-theme-preferences-deepen-design.md`](../../superpowers/specs/2026-09-24-theme-preferences-deepen-design.md). All 10 tasks merged in [#214](https://github.com/likwidmack/portfolio/pull/214).
- [x] Preferences storage owner: landed in [#235](https://github.com/likwidmack/portfolio/pull/235) — one versioned `tgmc-preferences` key, commits written 250 ms later (flushed on page hide), setups as full documents (max 24). Spec [`docs/superpowers/specs/2026-09-30-preferences-storage-admin-session-design.md`](../../superpowers/specs/2026-09-30-preferences-storage-admin-session-design.md); plan Part A [`docs/superpowers/plans/2026-09-30-preferences-storage-admin-session.md`](../../superpowers/plans/2026-09-30-preferences-storage-admin-session.md). See [personalization.md § Storage](./personalization.md#storage).
- [x] Admin session: landed in [#239](https://github.com/likwidmack/portfolio/pull/239) — one `tgmc-admin-session` key in `sessionStorage` owned by `useAdminSession`, `useAdminFetch()` adds the token and database headers (a `401` signs out to `/admin?expired=1`), token-gated pages use the `admin-auth` middleware, and `/admin/**` renders client-only. Plan Part B [`docs/superpowers/plans/2026-09-30-preferences-storage-admin-session.md`](../../superpowers/plans/2026-09-30-preferences-storage-admin-session.md). See [admin.md § Session](./admin.md#session).
- [ ] Admin session: the media page's other calls (`selectAsset`, delete, upload) have no `401` handling. Plan: the session plugin provides its deduplicated `onUnauthorized`, and the media client gets a `fetch` wrapper (through `MediaApiClientOptions.fetch`) with the same stale-token check.
- [x] Admin sign-in, wrong token: Continue now checks the token with `GET /api/admin/session` before saving it and shows "That token is not valid for this environment." instead of signing in and then "Session expired" ([PR #279](https://github.com/likwidmack/portfolio/pull/279); [admin.md § Session](./admin.md#session)).
- [ ] Admin session: "Session expired" can still be misleading after a `401` for a request sent without a token while no session exists.
- [x] Admin blog editor: Delete uses `window.confirm('Delete this post permanently?')` — move it to confirm in place with Undo like the media page (rule 8). **Done in part (PR 3, owner Q2 A):** `window.confirm` is gone; "Delete…" asks in place with Confirm / Cancel and focus handed over and back ([admin.md § Blog editor](./admin.md#blog-editor)). Undo landed in PR 4 ([admin.md § Blog list](./admin.md#blog-list)).
- [ ] Admin config: `admin-database.ts` reads `adminDynamoTable`, but the runtime config key is `dynamoTable` (latent; the DynamoDB messages table falls back to its default name).
- [ ] Public blog post (`core/web/app/pages/blog/[slug].vue`): `.page-with-nav` holds only the body, so on tablet and up the post sits in the narrow nav column. The admin fixed the same pattern in `core/admin/assets/css/admin.scss` (body `:only-child` spans the row); decide whether the theme should do this for every page.
- [ ] Admin session tests: the plugin `401` tests don't use a real ofetch context, so the parallel stale-`401` path is untested end to end; there is also no table test over the header forms (`Headers`, array, object).
- [ ] Admin session: the "Session expired" message is inserted on mount (focus then moves to the token field) — check whether screen readers announce the message as well as the field.
- [x] Admin media: `/admin/media` returned a `500` in `nuxt dev` (and the admin build bundled Node `fs` / `path` / `crypto` into the client) because the page imported the `@tgmc/media` root for `guessMediaKind`. It now imports the browser-safe subpath `@tgmc/media/kinds` ([media.md § Boundaries](../../packages/media.md#boundaries)).
- [ ] CI watch: `@tgmc/web:build` failed once with a rolldown `onLog` stack trace during admin session work, then passed on rerun.
- [x] CI flake: `@tgmc/web:build` ENOENT on `theme/core/dist/index.js` during parallel Affected — web is excluded from the parallel graph and runs alone after a theme rebuild ([nx-local-cache-utilities-dist-enoent.md](../../solutions/build-errors/nx-local-cache-utilities-dist-enoent.md); hit again on PR #290 run 38925552828).
- [x] Preferences draft clone: `cloneDocument` deep-copies plain data (`clonePlain`, unwraps Vue Proxies) instead of `structuredClone`, which threw `DataCloneError` in Style Studio / Personalize previews (adapters also pass `toPlain` at the call site; regression in `core/web/tests/preferences.spec.ts`).
- [x] Personalize on iPhone Safari: after **Done**, the dialog mask stayed dark and blocked the page for seconds. The mask now goes transparent and stops catching taps as soon as the close starts, and `.p-dialog` has no `backdrop-filter` ([dialog-mask-lingers-ios-safari.md](../../solutions/ui-bugs/dialog-mask-lingers-ios-safari.md); guard `core/web/tests/dialog-mask.spec.ts`).
- [x] Personalize on iPhone Safari: re-checked on a real iPhone on AWS Test (release 2026-10-18). The dialog closes and the backdrop no longer blocks the page.
- [ ] Personalize on iPhone Safari: closing still lags. After **Done** there is a visible delay before the panel and backdrop are gone. Profile the close on a real iPhone (Safari Web Inspector timeline): PrimeVue's `p-dialog` leave transition, the depth-field canvas repaint under the mask, and `closeDialog()`'s `setTimeout(0)` in `AppPersonalize`. Then shorten or skip the leave animation on touch devices. Re-check X, tap-outside and the Work evidence-examples dialog too ([dialog-mask-lingers-ios-safari.md](../../solutions/ui-bugs/dialog-mask-lingers-ios-safari.md#remaining-close-lag)).
- [ ] Admin session storage (`tgmc-admin-session` in `sessionStorage`) — Part B of the same plan.
- [ ] Preferences: the catch-alls in `flush` (`shared/preferences/draft.ts`) and in the legacy conversions (`shared/preferences/legacy.ts`) swallow every error, so a programming error (e.g. a `TypeError` in token building) looks like a full store and the conversion silently retries on every load. Rethrow anything that isn't a storage error — needs a server-safe shared quota / storage-error helper in `shared/preferences` (today `isStorageQuotaError` lives in `app/utils/storage-quota.ts`).
- [ ] Preferences: `setups.list` returns the cache's own setup objects (a copy of the array only), and `useState` wraps them in reactive proxies — a future in-place edit would change the cache. Clone on `list` or freeze the cached items.
- [ ] Preferences: when `Preferences.setups.save` succeeds but the following `setActiveId` write fails (inside `commitLive`), Style Studio reports "storage is full" although the setup was saved, and the draft stays dirty.
- [ ] Preferences: a `tgmc-style-setup-active` change from another tab moves the active marker but does not repaint, so a setup can show as active while another look is painted. Reload the document on `tgmc-preferences` events too, or ignore cross-tab active-id changes.
- [ ] `scripts/measure-app-scss.mjs`: the JS-constant branch of the colour-source scan matches nothing (it doesn't resolve identifiers) — fix the regex to resolve them, or drop the branch.
- [ ] Preferences: type-only exports of `#shared/preferences` (`PreferenceDocument`, `StyleSetup`, `PreferenceStorage` …) are not pinned by `core/web/tests/preferences-interface.spec.ts` (runtime keys only) — add an `expectTypeOf` check or a `.d.ts` snapshot.
- [ ] Preferences: legacy setups without a `mode` take the mode stored on disk during conversion (`shared/preferences/lifecycle.ts`); prefer `getCommitted().mode` and fall back to disk, so a failed earlier write can't hand them a stale mode.
- [ ] Preferences: the theme plugin (`app/plugins/theme-tokens.client.ts`) keeps its own `try/catch` around `Preferences.load(localStorage)`; use the shared `app/utils/preference-storage.ts` helper instead.
- [ ] Preferences: `STYLE_SETUPS_KEY` / `STYLE_SETUP_ACTIVE_KEY` are exported only for the cross-tab `storage` filter in `usePersonalization` — replace with an `isSetupsStorageKey(key)` helper and drop them from `#shared/preferences`.
- [ ] Preferences (optional): when a tab still on the old release rewrites `tgmc-style-setups` as an array, conversion keeps only that tab's setups; merge with the in-memory list by id to recover setups saved since.
- [ ] Tests: the Node 25 `localStorage` stub is duplicated across the theme and web jsdom specs (`theme/core/tests/color-mode-storage.spec.ts`, `core/web/tests/preferences-fouc.spec.ts`) — move it into one shared setup file.
- [ ] Prettier import-order drift on `development` (about 51 `core/web` files) makes the pre-commit hook fail for commits that touch theme files — run `npm run format` once on `development` in its own PR.
- [ ] Next release: remove the legacy preference keys — `core/web/shared/preferences/legacy.ts`, the FOUC legacy fallback (the `leg` branch in `shared/preferences/fouc.ts`), `LEGACY_KEYS` in `shared/preferences/document.ts` and `PREFERENCE_KEYS.legacy` in `shared/preferences/storage.ts`. Keep one best-effort line in `load` that removes the old key names, so keys left by a late old-bundle tab don't stay forever.
- [ ] Next release: remove the legacy admin session keys — the `portfolio.adminToken` / `portfolio.adminDatabase` conversion in `packages/web-layer-admin/app/utils/admin-session.ts` (`LEGACY_TOKEN_KEY`, `LEGACY_DATABASE_KEY` and the conversion branch in `loadAdminSession`) and its tests in `core/web/tests/web-layer-admin/admin-session.spec.ts`. Keep one best-effort line in `loadAdminSession` that removes the old key names, so keys left by a late old-bundle tab don't stay forever.
- [ ] Next release: remove the deprecated `core/web/shared/personalization.ts` re-export (`#shared/personalization`); import from `#shared/preferences`.
- [ ] Behavioural tests: Cypress smoke for Docs search typing (focus kept), Gallery tile → full view of that piece, entry via the Exhibition door; component tests for the Style Studio save / replace / undo flow and the admin upload error path.
  - Mounted tests for the admin media page and the admin blog list: today their delete specs (`core/admin/tests/media-delete-ui.spec.ts`, `media-page-ui.spec.ts`, `blog-list-ui.spec.ts`) read the source. Cover the `focusAfter` targets (Cancel → Delete…, Undo → the restored tile / link or the drawer heading, commit → the next tile or the page heading) and the phone sheet's `hold-space` wiring.
- [x] `useBrowseQuery` follows external `route.query` changes (back / forward, a link to `/gallery?group=x`): it is now a thin `useRouteQueryState(browseCodec, …)` from `@tgmc/nuxt-layer-ui` (PR 4, owner Q8 A).
- [ ] `useBrowseQuery` / `browseCodec`: ignore unknown `group` / `kind` values (an allowed-values list) and debounce `q` writes (owner Q8 option C, not yet chosen).
- [ ] Style Studio: case-insensitive name matching; re-read the page background on OS scheme changes; group swatches (Brand / Families) as the spec describes. (Done in PR 4, owner Q3 A: a second setup delete within 8 s no longer replaces the first Undo; each keeps its own line.)
- [ ] Admin media drawer: queue drops made during an upload instead of discarding them; tiles open the drawer but say `aria-pressed` — use `aria-expanded` (with `aria-controls`) or `aria-current` instead. (Focus management, scoped `Esc`, the `selectAsset` race guard, the viewport-capped panel and the modal sheet landed in plan PR 4. **Done:** Undo shows even when an error message is visible — `UiUndoNotice` renders beside the message line, one line per delete, through `useCrudResource`.)
- [ ] Admin media drawer, desktop: page messages (error, delete Undo, success) render inside the drawer only while it is a phone / tablet sheet; on desktop they stay above the grid, out of view while the drawer has focus. Show them in the drawer at all widths (or announce them from the drawer).
- [ ] Admin media drawer, phone sheet: `inertOutside` walks the sheet's siblings once when it opens, so an overlay teleported to `<body>` afterwards (a future PrimeVue popup, toast or confirm dialog) is neither inert nor reachable as part of the sheet. Re-run the walk on teleport, or teleport such overlays into the drawer.
- [x] Admin media, local upload thumbnails: the admin no longer calls `ensureDefaultThumbnail` (removed); its local library runs the on-ingest recipes in-process through the `onIngested` hook, so it never waits on a queue (plan PR 5c, [admin.md § Local media library](./admin.md#local-media-library-dam)).
- [x] Media on-ingest recipes (plan PR 5c): meta + `t` / `640` / `1280` / `1920` for every new image, run by the S3 `ObjectCreated` trigger and the worker on SAM, in-process everywhere else, with a Processing section and **Re-run processing** in the admin drawer ([media § On-ingest recipes](../../packages/media.md#on-ingest-recipes), [media-aws § Upload triggers](../../packages/media-aws.md#upload-triggers)).
- [x] Media on-ingest: no per-variant uniqueness, so an S3 event and a Re-run click at the same moment (or a duplicated S3 event) could each create a child for the same catalog variant. Fixed in PR 5c: deterministic catalog child ids + create-only child inserts ([media § On-ingest recipes](../../packages/media.md#on-ingest-recipes)).
- [ ] Media on-ingest: bundle `pdf-lib` into the media worker (or the web Lambda) so `pageCount` is recorded on AWS; today it is skipped where the package is absent.
- [ ] Media on-ingest: backfill existing production assets (a CLI or admin bulk action that runs `runOnIngestRecipes` / queues `on-ingest` for every asset without its variants); today only the per-asset Re-run exists.
- [ ] Media on-ingest: generate a video poster frame (today only an editor-linked `meta.posterId`) and a raster preview for SVG if the grid ever needs one.
- [ ] Admin media, forward mode (`MEDIA_API_URL`): proxy the admin's `/m/**` to `MEDIA_API_URL`, so previews load when that host is an internal Compose name (today: set `MEDIA_PUBLIC_BASE_URL` on the web app).
- [ ] Media: presigned browser uploads sign only `Content-Type` and `If-None-Match`, so those objects keep S3's default headers. Sign `Cache-Control` and `Content-Disposition` too (add them to `PRESIGN_REQUIRED_HEADERS` and the bucket CORS `AllowedHeaders`; the CORS test follows the constant) or copy-in-place on complete.
- [x] Media: on `DATA_BACKEND=sqlite|postgres` the web `/api/media` had no upload route (presign / complete returned 503). PR 2c of [the prod-readiness plan](../../superpowers/plans/2026-10-01-prod-readiness-docker-media.md) added the S3-mimicking `FsBlobStore`, local presign mode with the signed `PUT /api/media/_local-s3/<key>` route, and the `/m/**` CDN stand-in ([media-nuxt.md § Upload modes](../../packages/media-nuxt.md#upload-modes)).
- [x] Media (plan PR 4): `MINIO_BUCKET_POLICY=media` (`docker/minio-init.sh`: anonymous reads under `m/` only) in `docker/emulators/local.env`, `dev.env` and `test.env`, so the MinIO media base answers instead of 403 ([docker.md](../../docker.md#shared-emulators-and-data_backend)).
- [ ] Media, MinIO `media` policy: `mc anonymous set download` on `m/` also allows anonymous listing of `m/`. Switch to a GetObject-only policy (`mc anonymous set-json` with `s3:GetObject` on `arn:aws:s3:::<bucket>/m/*`) and extend `scripts/docker-compose.test.mjs`.
- [x] Media (plan PR 4): `MEDIA_PUBLIC_BASE_URL`, checked first by `mediaPublicBaseUrl()`, set in `infra/sam/template.yaml` to the stack's own distribution on `test` and `production` (replaces the planned `NUXT_PUBLIC_MEDIA_BASE_URL` on deployed stacks; that name now only feeds `core/web/shared/media-public.ts` for builds without a media server, such as the tamaramack.github.io copy); pinned by `scripts/sam-template.test.js` ([media-nuxt § Public URLs](../../packages/media-nuxt.md#public-urls)).
- [x] Media (plan PR 4): `core/web/server/middleware/cdn.ts` leaves `/m/` to the stand-in when local media is on and otherwise sends it to `mediaPublicBaseUrl()` (every `/m/` object, whatever its extension; audio, 3D / XR and AVIF joined the static extensions).
- [ ] Media CDN follow-ups: an optional loop guard in `core/web/server/middleware/cdn.ts` when the media base origin equals the request host (a misconfigured `MEDIA_PUBLIC_BASE_URL` would 302 to itself); a custom domain on the assets CloudFront distribution needs both `NUXT_APP_CDN_URL` (prod) and `MEDIA_PUBLIC_BASE_URL` (template, today `AssetsDistribution.DomainName`) updated together.
- [x] Media `/m/**` stand-in (plan PR 4): single `Range` requests (206 / 416, `If-Range`) and weak / list `If-None-Match` matching ([media-nuxt § CDN stand-in](../../packages/media-nuxt.md#cdn-stand-in-m)).
- [ ] Media local uploads: reject chunked `_local-s3` PUTs without `Content-Length` with 411 (today an over-cap chunked body ends with the connection closed, not a 413); write the derived sidecar back for legacy blobs so they are not re-hashed on every read; Windows `EPERM` when a variant is re-materialized (rename over the file) while `/m/**` streams it; document that local presign derives the upload origin from `X-Forwarded-Host` / `X-Forwarded-Proto` (acceptable because presign is admin-only).
- [ ] Media materialize: an `ImageInputError` (oversize / unreadable source) maps to 413 / 422 and is now a terminal failure (job + child `failed`, error rethrown, SQS worker acks; fixed). Still open: `core/web` `image-service` maps these errors to 400 by message; switch it to `instanceof ImageInputError`. Decode-time sharp errors inside `transformImage` (after preflight passes) are still plain errors (500).
- [ ] Media materialize: a `queued` job that no worker owns (for example one left by a failure before input rejections became terminal, with a `lastError`) blocks every re-materialize of that variant with 409 forever. Needs an expiry for stale queued jobs or an admin "retry / clear" action. (The local DynamoDB test asset `about-375.png`, 360×12309, was cleared by delete + re-upload; its variants now fail with 422 as they should.)
- [x] Admin media: a failed upload or variant shows the server's reason for a 4xx (`mediaFailureMessage`, `MediaApiError.serverMessage`) instead of the generic "Materialize failed." / "Upload failed: …". Create variant failures render inline under the picker (`role="alert"`, `aria-describedby`), since the page's message line is out of view while the drawer is scrolled.
- [ ] Media, site `i/`, `v/`, `d/` objects (permanent typed sync since the 2026-10-17 owner decision; plan PR 5a's untracking is cancelled): the metadata repair never rewrites these objects, so if the extension → `Content-Type` map changes, re-upload the affected tracked files or check their `Content-Type` by hand. A file removed from git keeps its bucket object until it is deleted deliberately ([cicd.md § No media work in GitHub Actions](../../cicd.md#no-media-work-in-github-actions)).
- [ ] E2E (plan PR 5): make the shared `/m/**` Cypress stub in `core/web-e2e/src/support/media.ts` extension-aware (video / PDF placeholders) once pages render catalog video or PDF; today every `/m/` GET gets the WebP.
- [ ] E2E: `npx nx run @tgmc/web-e2e:typecheck` fails on `development` (Nx TS project references out of sync, no DOM lib, `nodenext` resolution in `core/web-e2e/tsconfig*.json`). Run `nx sync` and give the Cypress tsconfig the DOM lib and bundler resolution so the target passes.
- [ ] Media (right after the first production deploy, [runbook step 6](../../cicd.md#6-verify-production)): set `PRODUCTION_MEDIA_BASE_URL` in `core/web/shared/media-public.ts` to the prod CloudFront origin (stack output `AssetsCdnUrl`) so the tamaramack.github.io copy loads media from the prod CDN ([cicd.md § Site media in the GitHub.io copy](../../cicd.md#site-media-in-the-githubio-copy)).
- [x] Production first-deploy runbook ([cicd.md § Production first-deploy runbook](../../cicd.md#production-first-deploy-runbook)): ordered owner steps from preconditions through `release:pr`, test-stack verification, preflight, Release, prod verification and rollback (CloudFormation, previous release, PITR, object versions), plus the read-only `npm run prod:preflight` (`scripts/prod-preflight.js`: stack outputs or first-deploy leftovers, bucket notification, sync dry-run deletes under `m/` `media/` `i/` `v/` `d/`, PITR, queue SSE, `SITE_URL`, `production` reviewers, secret and variable names).
- [ ] Owner, first production deploy: run the [runbook](../../cicd.md#production-first-deploy-runbook) steps 0–6. Decide the `production` reviewers (with `prevent_self_review` a sole reviewer cannot approve a Release they published), set `CORS_ALLOW_ORIGIN` to the exact `SITE_URL` origin, enable `MEDIA_SMOKE_ENABLED=1` on `test` before `production`, and without a custom domain do the `SITE_URL` second pass (point it and CORS at `HttpApiUrl`, redeploy the tag).
- [ ] Split `scripts/prod-preflight.js` (960 lines) and `scripts/prod-preflight.test.js` (~970) before they cross the 1k-line rule: move the read-only guards (`assertReadOnlyAws`, `isDryRunSync`, `assertReadOnlyGh`) and the `shell: false` `capture` into `scripts/prod-preflight-guards.js` with their own test file, and add the new path to the `ci.yml` `node --test` list.
- [ ] Windows spawning in `scripts/lib/spawn.js` (re-exported by `scripts/sam-aws-helpers.mjs`; also used by `sam-build`, `sam-dry-run` and `prepare-nitro-output`): its `runCapture` / `run` helpers use `spawn(…, { shell: true })` on Windows, and `quoteWinCmdArg` quotes only whitespace, `"`, `*` and `?`, so `& | ^ % < >` in an argument reach cmd.exe. Only Windows-workstation runs of `sam:deploy` / `sam:sync:*` are affected (CI and CD run on Linux with `shell: false`), and their inputs come from the owner's own env and config. `prod:preflight` no longer uses these helpers (its own `shell: false` spawn). Fix: spawn `aws.exe` directly with `shell: false` and keep the shell only for `.cmd` shims (`sam.cmd`, `npm.cmd`), quoting cmd metacharacters there (`%` cannot be neutralised inside quotes, so validate those values instead).
- [ ] Test stack: once `/aws/lambda/portfolio-test-nitro-logs` and `…-media-worker-logs` receive events, delete the old default `/aws/lambda/<function>` log groups by hand ([runbook step 3](../../cicd.md#3-verify-the-test-stack)). Production never had them.
- [ ] Media docs (plan PR 6): the `portfolio-aws-cicd` skill references (`references/cdn-sync.md` in `.agents`, `.github`, `.opencode`) say prod sync "may use `--delete`" without the media excludes; add the media excludes (`m/`, `media/` on every pass; also `i/`, `v/`, `d/` on the `--delete` pass and the repair) and "no media in Actions".
- [ ] Media (PR 5): presign MIME / kind strictness (reject a Content-Type that does not match the kind and extension).
- [x] Media (PR 5 part 1): policy `normalizeMediaFilename` (generator / camera prefixes, UUIDs, long ids, middle initials dropped; mechanical `slugMediaFilename` kept for the migration), `validateMediaMeta` behind `enforceMetaPolicy`, `@tgmc/image/sanitize`, the reviewed `core/web/content/media.json` and `media:site-manifest` / `media:site-import` ([site-media.md](./site-media.md)).
- [x] Site media (PR 5 part 2a, metadata only after the 2026-10-17 owner decision): site media stays in `core/web/public` at its `/i`, `/v`, `/d` paths (no `/m/` URLs, no 301s, no site import before a deploy); `useSiteMedia` reads title, alt and dimensions from a generated client map (`core/web/shared/site-media-map.json`, `npm run media:site-map`); the content guard (`core/web/tests/site-media-guard.spec.ts`) requires every `/i|v|d/` path to be a manifest entry (tesseract paths and the HTML labs allowlisted for good); the default social image is the public `manhattan-2150-keyframe` file, absolute with its dimensions, and also replaces SVG / video page images (case-study diagrams); `/i/profile_pic_2.jpg` is back in the manifest ([site-media.md](./site-media.md#rendering-metadata-only-part-2a)).
- [ ] Site media (owner review): the alt text and title of `/i/profile_pic_2.jpg` in `core/web/content/media.json` were drafted by an agent from the image (`reviewNotes`); `/i/profile_pic_1.jpg` is unused on the site since #278 (keep or drop it).
- [x] Media (PR 5 part 2b): `enforceMetaPolicy` on by default (CLI and `transferMedia` opt out) with validated meta edits (400 `invalid_meta` + field issues); the admin upload form asks for title and alt (or decorative) per file; drawer **Details** (title, alt, description, credit) and **Rename…** (`POST …/assets/:id/rename`: `NAME#` hold, create-only copies, `CatalogStore.renameAsset`, old-key cleanup, CDN purge; 409 `name_conflict` with a free name; old `/m/` URLs stop working, no redirects); uploads sanitized at ingest (admin: full sanitizer with ffmpeg; web: rasters and SVG) and presigned uploads in place in `complete` (`ifMatch`), SVG / PDF / MP4 refused on the web API unless the admin pre-sanitized them (415 `sanitize_required`). Site media is unaffected: it is not in the catalog ([media § Rename](../../packages/media.md#rename), [media § Upload sanitizing](../../packages/media.md#upload-sanitizing), [admin.md § Local media library](./admin.md#local-media-library-dam)).
- [ ] Admin media (after part 2b): a 401 on detail, tags, variants, Re-run processing and delete shows an error instead of signing out like list, upload, save and rename do.
- [x] Media rename (part 2b fix round): copies are server-side through the optional `BlobStore.copy` (S3 `CopyObject`, exclusive `copyFile` on `FsBlobStore`), and adopted copies compare a streamed SHA-256 ([media § Rename](../../packages/media.md#rename)).
- [x] Media uploads (part 2b fix round): SVG never goes through a presigned upload (presign refuses it); the admin sends the sanitized SVG to `POST /api/media/ingest/svg`, where the web server runs svgo on it again (`@tgmc/image/sanitize-web`) and scans the result before storing only the sanitized bytes (second fix round; the scan also refuses non-UTF-8 markup, and PDF sanitizing resolves indirect action references). Uploads outside the kinds allowlist are 415 `unsupported_type`, and markup posing as another type is refused ([media § Upload sanitizing](../../packages/media.md#upload-sanitizing)).
- [ ] Media uploads (after part 2b): MP4 and PDF uploads straight to the web API (`/api/media`) are refused with 415 because the web server has no ffmpeg / pdf-lib sanitizer; they go through the admin, which sanitizes and forwards with `preSanitized: true`. The web API trusts that flag from any admin-authorized caller. Follow-up: a dedicated admin → web secret (not the shared admin token) and an HMAC over the sanitized object's SHA-256 + path that `complete` checks; optionally sign `x-amz-checksum-sha256` into the presign.
- [x] Media uploads (after part 2b), closed 2026-10-21 by the private pending prefix (review I4, owner decision): presigned uploads land under `pending/<assetId>/`, which CloudFront cannot read and a lifecycle rule expires; `complete` publishes the checked object ([media § Name reservation](../../packages/media.md#name-reservation)). Original note: between the presigned PUT and `complete`, an unsanitized raster, PDF or MP4 is already readable at its public `/m/` key; a `complete` that never arrives leaves it there (the reservation lapses after 30 minutes, and nothing deletes the object until that name is presigned again). Smallest fix: sign `x-amz-tagging: upload=pending` into the presign, deny CloudFront `s3:GetObject` while `s3:ExistingObjectTag/upload` is `pending`, clear the tag in `complete`, and expire pending objects with a lifecycle rule. Deferred because the tag gate needs real S3 + CloudFront to verify (MinIO and `FsBlobStore` cannot exercise the bucket policy).
- [ ] Media materialize (after part 2b): the variant put is not create-only, so a zombie job past its lease (still running after the lease expired and the asset was renamed) can overwrite another asset's object at the old key once that name was released and taken. The finalize refuses the moved job's catalog write (`asset-moved`), but the bytes are already written. Fix: write variants create-only (with a conditional replace for a deliberate re-materialize), or re-check the name hold on the old key right before the put and skip it when another asset holds the name.
- [ ] Media uploads (after part 2b): PDF sanitizing runs pdf-lib on the admin server's event loop. The 10 MiB cap (`MAX_PDF_SANITIZE_BYTES`) bounds it to ~10 s with blocks of at most ~0.5 s ([image § sanitizers](../../packages/image.md)). Move `sanitizePdf` into a worker thread with a timeout (terminate the worker and answer 415 `invalid_upload` when it runs over), then raise the cap.
- [ ] Media on DynamoDB, tests: the rename and meta-edit races are covered by the shared catalog contract on SQLite and Postgres, but DynamoDB has its own in-memory fake plus one DynamoDB Local test with no concurrent case. Run the shared catalog contract against DynamoDB Local (`DYNAMODB_TEST_ENDPOINT`) with the concurrent rename / child-write / meta-edit cases. Tried 2026-10-28 (tech-debt Phase 1): on DynamoDB Local 5 contract cases fail, so the suite is not wired in yet: asset listing ties are not ordered by id descending; `deleteAsset` leaves the asset's own name reservations; a queued or fresh-lease running job does not block `renameAsset`; `deleteAssetCascade` leaves the asset's jobs; `listJobs` refuses a status-only filter. Decide per case whether DynamoDB or the contract is right, then add `describeCatalogContract` to `packages/media-aws/tests` (the in-memory client also lacks `gsi1` queries). The negative-limit case now passes: `listPage()` in `@tgmc/media` normalises paging for Postgres and DynamoDB.
- [ ] Tech-debt audit leftovers (2026-10-28; Phases 1–3 done on `fix/tech-debt-phase-1`): job state transitions are still copy-pasted in the SQLite and DynamoDB job stores (Postgres has one `transition()`); `registerRemoteAsset` and `enqueue` in `media-library.ts` are each over 100 lines; DynamoDB `deleteChildrenForAsset` / `deleteJobsForAsset` delete one item at a time; the deprecated `DynamoCatalogStoreWithLookup` is still exported (two specs use it); server logging has two styles (Consola `Logging`, which logs on every construction, and hand-rolled JSON); `sam-build` `main()` is 117 lines; argv parsing is hand-rolled in 7+ scripts (`util.parseArgs`); `resolveRepo` is written twice; clipboard / timed status messages, focus moves (`document.querySelector`) and browser storage each have several hand-written variants; `AppStyleStudio` has 8 watchers; `media/index.vue` (about 810 lines) and `slots.vue` could still lose the tag and materialize flows to composables.
- [ ] Media rename (after part 2b): no redirects from the old `/m/` key; add CloudFront redirects or a tombstone lookup if external links to renamed media matter.
- [x] 2026-10-19 (merge of `development` into the likwidmack alignment branch): the default social image stays the `manhattan-2150-keyframe` site-media file with its real 1672×941 size (upstream #327; controller ruling — this supersedes the branch's 2026-10-14 owner decision to default to `/i/brand/og-card.png`). `/i/brand/og-card.png` and its generator (`npm run brand:assets`, `scripts/build-brand-assets.js`) stay as an available placeholder asset ([brand-marks.md](./brand-marks.md#where-they-are-wired)).
- [ ] Site media follow-ups: video entries have no LQIP / poster link (`posterId`); the x264 encoder string in the H.264 bitstream survives the MP4 remux; the manifest sha256 is tied to the sharp / svgo / pdf-lib / ffmpeg versions (rerun `--draft` after upgrades; the import skips entries already imported before comparing bytes).
- [ ] Site media: strip raster metadata at the container level, losslessly, instead of re-encoding with sharp — PNG ancillary chunks except `iCCP`, WebP EXIF / XMP chunks, JPEG APPn segments except ICC, GIF comment extensions — and re-encode only when EXIF orientation is not 1. Removes the coupling of the manifest sha256 to the sharp version and the ~17% WebP growth.
- [ ] Media CDN (admin/media review 2026-10-21, M8): a CloudFront response-headers policy with `Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox` for `/m/*`, as defence in depth behind the upload sanitizers (the local `/m/**` stand-in already sends it). Needs a custom policy that keeps the managed CORS-with-preflight + security headers, and a separate behaviour or an exception for PDFs: Chrome's viewer will not render a PDF under `sandbox`. Deferred from part 2b because it can only be verified on a deployed distribution. (SVG `<style>` / `style` CSS with `url()` / `@import` is now sanitized and scanned.)
- [ ] Site media: read the MP4 track rotation matrix so `width` / `height` of rotated (portrait phone) videos are the displayed dimensions.
- [x] Media: concurrent first materialize of the same (asset, variant, format) could create two children before either is `ready`. Fixed in PR 5c: the catalog child id is a UUIDv5 of that triple and child inserts are create-only (SQLite primary key, DynamoDB `attribute_not_exists`, Postgres id check + `23505` → `MediaConflictError`), covered by the shared catalog contract.
- [ ] Media asset URLs: list responses call `listChildren` once per image / SVG row to find the `t` thumbnail (N+1, up to 100 reads a page). Store the thumbnail path on the asset when `t` is ready, or batch the children read.
- [ ] Media on-ingest without a queue (host dev, Docker, `docker:test`, admin local): the recipes (meta + up to four variants) run inside `complete` / the admin upload, so a large image delays the response. Run them after the response (fire-and-forget, e.g. `event.waitUntil`); `runOnIngestRecipes` is already idempotent and the drawer already polls.
- [ ] Media: on DynamoDB the `-2`, `-3` suggestion search does up to 1000 consistent reads of `NAME#` items in the worst case; replace with a prefix query or a counter if names pile up.
- [ ] Media: legacy SQLite children migrate as `custom` (not mapped to the catalog `t`/`640`/… codes), so re-materializing a catalog variant creates a new child instead of replacing the legacy one.
- [x] Media: `transferMedia` and `npm run media:transfer` copy a catalog between SQLite + FS and DynamoDB + S3 (seed production, backup pull) — PR 3 of [the prod-readiness plan](../../superpowers/plans/2026-10-01-prod-readiness-docker-media.md); runbook [cicd.md § Promote media to production](../../cicd.md#promote-media-to-production).
- [x] Media transfer: `postgres:<url>` endpoint with `--blobs fs:<dir>|s3:<bucket>` (plan PR 3b) on the new `@tgmc/media-postgres` stores; one catalog contract suite runs against SQLite always and Postgres when `MEDIA_PG_TEST_URL` is set ([media-postgres.md](../../packages/media-postgres.md)).
- [ ] Media on Postgres (plan PR 3c): wire `@tgmc/media-postgres` into the admin / `@tgmc/media-nuxt` media library for `DATA_BACKEND=postgres` (today that backend still uses SQLite/FS media under `MEDIA_LOCAL_ROOT`), plus the optional admin transfer panel. Run the schema as a separate migration and open the stores with `ensureSchema: false` (least-privilege role, no bootstrap per Lambda cold start; [media-postgres § Schema](../../packages/media-postgres.md#schema)), and pass `onError` to log dropped idle connections.
- [ ] Media on Postgres, CI: add a `services: postgres` sidecar to the local-parity job and set `MEDIA_PG_TEST_URL`, so the Postgres contract (including its concurrent name-hold and job-claim tests over several connections) runs on every PR; today it runs only when a developer sets the variable.
- [ ] Media transfer: each object is read whole into memory before it is written; stream S3 ↔ FS copies before transferring large video. On DynamoDB `listAssets` pages by offset (each page re-queries from the start), so very large catalogs page in O(n²) reads; add a cursor-based listing (`ExclusiveStartKey`) to `CatalogStore` if that matters (admin/media review 2026-10-21, M9). Offset paging on a DynamoDB source is also not stable for assets with an equal `createdAt` (no id tie-break like SQLite's `created_at DESC, id DESC`), so a page boundary can repeat or skip one; a cursor fixes both.
- [ ] Media transfer follow-ups: an identical object already on the target is adopted with the headers it was written with (old `Cache-Control` / `Content-Disposition` are not refreshed; a `CopyObject` with `MetadataDirective: REPLACE` would fix it). The CLI never closes its AWS clients (`destroy()` on the DynamoDB/S3 clients; harmless for a one-shot process). One set of AWS flags (`--region`, `--dynamodb-endpoint`, `--s3-endpoint`, `--path-style`) applies to both sides, so `aws:` → `aws:` across different endpoints or regions is not possible; add per-side flags if needed. Children are outside the name hold: a target worker re-materializing the same variant between the transfer's create-only put and a failed child insert can lose its object to the cleanup ([media.md § Transfer](../../packages/media.md#transfer-between-backends)).
- [ ] Media transfer hardening: add resume tests (a child object present on the target with its row missing; an AWS rerun while the previous run's name hold is still live). In the next `docker:test` rehearsal, verify the pinned MinIO honours `If-None-Match: *` on put (expect 412 for an existing key). Optionally re-hold the name just before `insertAsset` so a slow copy cannot outlive `TRANSFER_NAME_HOLD_MS`.
- [ ] Media transfer verification and audit: skipped assets and children are only checked for existence on the target, never re-hashed (a re-hash downloads every object on every rerun); add an opt-in `--verify` that hashes both sides for skipped items. An `audit: …` failure is not retried by a rerun (the data is skipped, so no event is appended); make the event retryable, for example by checking `listByEntity` for an `asset.transferred` event when an asset is skipped.
- [ ] `@tgmc/utilities`: `new Logging()` logs "Consola logger initialized" to stdout when the package is imported, which pollutes CLI output (`media:transfer` routes stray stdout to stderr via `scripts/media-transfer-stdout.js`). Log at debug level, or not at all, on construction.
- [x] Splash Discovery scope counts the case-study collection (`{caseStudies}` in `home.json` → `resolveDoorScope`, `shared/splash-scope.ts`).
- [ ] Owner info: fill the `null` entries you want public in `core/web/content/profile.json` (`contact.phone` / `website` / `location` / `booking`, and `href` for LinkedIn, X, Bluesky, …). Empty entries stay hidden from UI and SEO.
- [x] Automate the responsive · a11y · touch audit — `core/web-e2e/src/e2e/ui-audit.cy.ts` at the seven fluid widths, 320 → 1920 (320 doubles as the reflow check).
- [x] Phone + tablet responsive regression for every page and the interactive components — `core/web-e2e/src/e2e/responsive-components.cy.ts` ([§ Responsive regression](#responsive-regression-e2e)).
- [x] Fix the layout bugs it found (`KNOWN_ISSUES` is now empty): KI-1 page-nav toggle label wraps: the toggle overrides the global button base's existing `white-space: nowrap`, which is left unchanged; KI-3 browse-toolbar segments wrap inside their box (every toolbar); KI-4 the Menu dropdown returns focus to its trigger on `Esc` (`app/utils/disclosure-focus.ts`); KI-5 PrimeVue dialog / drawer close is 44×44 (theme `touch-target` mixin); KI-6 evidence card links use the touch floor; KI-7 Style Studio uses `overflow: clip` so its Apply / Discard bar sticks; KI-8 gallery chips and the exhibit caption sit in the tile meta. The media box reserves the aspect ratio: strict for photos and video, and a floor that grows for text exhibits (viz series and diagrams, the fallback title), so no row is cut off. Code stays a cropped preview window; KI-9 was a headless media-query timing artefact (test settles first). On the way: reduced-motion readers got smooth scrolling (`behavior: 'auto'` deferred to the global `scroll-behavior: smooth`) — the theme now scrolls smoothly only under `prefers-reduced-motion: no-preference` without `html[data-motion='reduced']`, or with `html[data-motion='playful']`. Replaced styles are archived in `theme/core/scss/_archive/2026-10-06-responsive-layout-fixes/` and /work and /gallery jump `'instant'`. (KI-2, gallery captions clipped, was fixed by #236.)
- [x] /work cards at tablet portrait (768×1024) use the root portrait `--media-ratio` 9:16, so each card's image is ~630×1120px; consider 16:9 (or 4:5) for the row card's stacked media. — done 2026-10-14 (16:9 everywhere, images centred).
- [ ] Theme `section, article, aside, .panel { overflow: hidden }` makes every section a scroll container, which breaks `position: sticky` inside any of them; consider `overflow: clip` globally (Safari 16+) after a visual check.
- [x] **Review batch 1 (a11y, stacked on #264):**
  - Saved colour map: `refreshStaleColorTokens` compares values, not just names (a builder change rewrites the map once; an identical map is never rewritten), and paper / ink parse to lower-case `#rrggbb` so a `#fff` / `rgb()` pair reaches the FOUC map ([personalization.md](./personalization.md#colour-variations-and-the-fouc-map)).
  - Menu dropdown: the `mailto:` "Get in touch" and the current page's link close as `stay` and return focus to Menu (`app/utils/disclosure-focus.ts`, `linkStaysOnPage`).
  - Gallery grid: the code preview is not a tab stop (`UiCodeBlock` `focusable: false`; the tile button is the control), so no clipped ring; the e2e ring check measures against every clipping ancestor (`hidden` / `clip` / mixed axes).
  - Focus rings: one recipe (`focus-ring` / `focus-ring-shadow`, [theme.md § Focus rings](../../packages/theme.md#focus-rings)) — visible in forced-colors mode, text fields keep their rest border, the nav "On view" and About focus use the focus role.
  - Gallery feed: a modal dialog (`role="dialog"`, `aria-modal`, inert background via `app/utils/inert-outside.ts`, `Esc`, focus in and back to the opener, 44px close). (2026-10-19: the feed was replaced by the full view, `GalleryViewer`, which keeps the same dialog contract.)
  - Admin: the phone media sheet paints the page paper (was transparent); the layer's blog status text uses the contrast roles, and the admin colour guard scans `packages/web-layer-admin/app`.
- [x] **#267 review follow-ups:** paper / ink save only what reads back (`withPaperInk` refuses translucent values; Style Studio shows an inline alert); `button-theme` no longer transitions `outline-color` (no text-coloured flash); `UiButton` uses `focus-ring-shadow` (one ring); the theme guard catches every outline-removal spelling and pins the ring per field selector; focus-mixin px are capped at 4px; `inertOutside` keeps live regions and teleport hosts live; the feed's `Esc` respects a handled event / IME, and its position is announced once on open; a leftover colour map is removed for the defaults.
- [ ] Theme background hooks: `--theme-background{,-secondary,-accent}-color` read the external hooks `--background-color*`, which nothing sets, so any use is transparent (`theme/core/scss/globals/_root.scss`). core/web's background options (`--portfolio-background-*-color`) and `AppDepthField` fall back to them, so giving them a fallback (e.g. the page paper) would change those surfaces — owner decision: give them a fallback, or document them as hooks only and guard against painting them directly.
- [x] Two copies of `inertOutside`: done (PR 2 Task 5). One copy in `@tgmc/nuxt-layer-base` (`packages/nuxt-layer-base/app/utils/inert-outside.ts`, with `useInertOutside` / `useFocusTrap` on top), used by the web gallery feed dialog (since 2026-10-19 the gallery full view, `GalleryViewer`) and the admin media drawer. Admin uses the default `INERT_OUTSIDE_KEEP` list (owner default, 2026-10-16): live regions, the `UiAnnouncer`, toasts and teleport hosts stay live behind the sheet. The consolidated helper skips `<noscript>` siblings (web's old behaviour; admin's copy did not).
- [x] 2026-10-19, superseded by the gallery redesign (the feed is now `GalleryViewer`, one piece at a time, focus on the dialog and back to the tile of the piece last shown). Was: Gallery feed dialog: focus moves to "Back to grid" on open; when opened from a tile, the next Tab starts at the first card, not the opened post. Consider focusing the opened post's card (`tabindex="-1"`) instead.
- [x] 2026-10-19, superseded: `GalleryFeedCard` is gone (styles archived in `theme/core/scss/_archive/2026-10-19-gallery-redesign/`); the full view shows no caption over the piece, the details sit in `GalleryInfoPanel`. Was: Gallery feed (`GalleryFeedCard.vue`): the exhibit caption still uses `caption-placement="inside"`, a frosted chip over the media or shell. Move it under the frame like the grid tile's meta row, and check WebXR at phone width.
- [x] 2026-10-19, superseded: the grid is justified rows, each tile at the piece's own ratio, nothing cropped. Was: Gallery wide photo / video tiles keep a strict aspect ratio with a 16rem minimum height, so very wide images are cropped at the sides. Consider `object-fit: contain` on a paper fill, or let wide tiles span two columns.
- [ ] Archive: `theme/core/scss/_archive/2026-10-06-responsive-layout-fixes/` holds the pre-#256 originals only; #256's own intermediate gallery rules (ratio on the tile, chips) were replaced in #264 without a snapshot. Add them if the history matters.
- [x] Style Studio fixes (2026-10-12): hex fields commit only a full `#rrggbb`; a custom background fill replaces the pack image (the pack image returns on the next pack), follows the active mode's paper until a colour is picked (`backgroundCustomFor`) and is painted so the mode's ink reads on it (`paintedBackgroundCustom`); Background → Custom shows the painted pack values, and a pack's background Primary / Secondary / Accent are its painted brand colours (the same ones the pack tile shows; three distinct colours per pack) instead of the palette extras; pack image stops stand out from the paper (≥ 3:1) while the ink still reads on them; pack labels pick ink / paper with a halo; select / autocomplete / multiselect overlays are opaque `--theme-surface-color`; colour variations stay in the lightness band 15–90 where contrast allows ([theme.md § Solid colours](../../packages/theme.md#solid-colours-and-variations)); the nav env chip shows on every `SYS_ENV` except production.
- [ ] Style Studio on phones: the sticky Apply / Discard draft bar is ~270px tall at 375px wide and covers a third of the viewport. Collapse it to one row (status + two buttons) below 30em.
- [ ] Theme: `paper-ink` and `color-variations` import each other (cycle). The real cycle has three modules — `color-variations → color → paper-ink → color-variations` (`theme/core/src/color.ts:30` imports `DEFAULT_PAPER_INK`) — so a third helpers module alone won't break it while `color.ts` imports `paper-ink`. Layer strictly (colour maths ← neutral steps / `DEFAULT_PAPER_INK` ← `color-variations` ← `checkPaperInk` ← the `Color` facade) and add `import/no-cycle` on `theme/core/src` (architecture review T8).
- [ ] Theme API packs pin mode colours (code review M-4): the palette packs (`paletteToTokens`) and `Theme.create` / `Theme.apply({ colors })` (`definitionToTokens`, `theme/core/src/theme.ts`) write `--theme-primary-color`, `--theme-paper-color` / `--theme-ink-color`, `--primary-default` and a dark-mode `--theme-button-fg-color` inline — names `DERIVED_ROLE_TOKENS` / `MODE_COLOR_TOKENS` (`tokens.ts`) say must never be pinned. In light mode a pack gets the dark button text, and the next mode switch (`setTokens`) drops the keys, so the pack silently disappears. No app caller today. Make packs write the per-mode variation names (as `buildBrandTokens` in `core/web/shared/preferences/paint.ts` does), or document the pinning.
- [ ] Architecture review 2026-10-06 (each item one PR; needs the owner's OK first):
  - [ ] **One contrast formula (T4).** `color-mix.ts` `luminance` / `contrast` (threshold 0.04045) and `contrast.ts` `relativeLuminance` / `contrastRatio` (0.03928, reached through an HSL round-trip in `Color.contrastRatio`) both decide "passes" inside `color-variations.ts`, so a value can read 4.5 in one and 4.49 in the other. Also three `hexToRgb`, two `rgbToHex`, two `rgbToHsl`. One `color-math.ts`; the rest delegate.
  - [ ] **One `buildThemeColorTokens` and one colour-token catalogue `colorTokenKind` (T1 + T2).** The nine `build*Tokens` are composed by hand in `core/web/shared/preferences/paint.ts:185-234` and `theme/core/bin/build-color-variations.mjs:46-63`; whether a name may be pinned inline lives in four lists (`DERIVED_ROLE_TOKENS`, `MODE_COLOR_TOKENS` — read from the codemod's rename map —, `MODE_VARIATION_NAME` in `tokens.ts`, `RUNTIME_COLOR_TOKEN_NAMES` in `paint.ts:237-263`).
  - [ ] **Split the theme root entry (T3)** into `@tgmc/theme/color` (pure, isomorphic), `/tokens` and `/primevue`, with `"sideEffects"`. The root re-exports the PrimeVue preset (`index.ts:200-207`; `primevue.ts:248, 373` run at import), so `packages/image` (Nitro / Lambda via `core/web/server/utils/image-service.ts`) evaluates it. Add a Node import guard.
  - [ ] **Preferences paints the whole document through a `PaintTarget` (P1 + P5).** `usePersonalization.ts` repeats "preview, then `setThemeMode`, `applyChrome`, `syncFromDoc`" at six call sites (the ordering comment appears three times) and mirrors the document as eight `useState`s with hand-written SSR branches (`:63-85`, `:153-163`, `:460-478`). Inject `{ setMode, setChrome }` into Preferences; one `useState<PreferenceDocument>` plus a pure `mergePatch`.
  - [ ] **The head-script sanitizers drift from the runtime (P4).** `shared/preferences/fouc.ts:28` re-implements mode, colour-map and background sanitizing as string-built JS; it accepts any ≤ 600-character string for every background option, where `document.ts:206-221` / `paint.ts:287-296` accept only hex / list / image values. Write `headPaint` as a real, tested function and serialize it (after the legacy-key removal).
  - [ ] **Five copies of the lightness search (T5)** in `color-variations.ts` (`adjustLightnessFor`, `backgroundFor`, `washFor`, `linkInkFor`, `gradientStopFor`) with different clamps and step limits; the file header says there is one. One internal `searchLightness`, behind a characterization test over the 21 presets.
  - [ ] **Unused root exports and duplicate alpha steps (T6).** About 70 of ~140 `theme/core/src/index.ts` value exports have no consumer outside the theme; `COLOR_ALPHA_STEPS` (`color-rename.ts:35`) duplicates `PAPER_INK_ALPHA_STEPS` (`paper-ink.ts:45`); `core/web/shared/utils/set-css-variable.ts` uses the raw `setThemeVariable` and bypasses the registry. Shrink the surface and pin it like `tokens-public-exports.spec.ts`.
  - [ ] **Default bridges defined twice (P3).** `DEFAULT_APPLY_BRIDGES` (`theme.ts:99`) and `bindThemeBridges` (`core/web/app/plugins/theme-tokens.client.ts:36-60`, which wraps 13 `Theme` methods, so a new writer is silently unbridged). Preferences (`paint.ts`, `draft.ts`) imports the unbound `Theme`, so `runtimeConfig.public.theme.bridges` never reaches Personalize / Style Studio painting. One `Theme.configure({ bridges })`.
  - [ ] **Rename normalization at three layers (T7):** `normalizeColorName(s)` runs in `theme.ts:136, 185`, `token-registry.ts:56, 61` and `set-theme-variable.ts:9, 96, 313`. Normalize once at the `Theme` / registry input.
  - [ ] **Sass colour forwards (T9).** `theme/core/scss/_nuxt-auto.scss:12-15` forwards `tokens/colors` and `tokens/color-fns` into every SFC, though only `AppStylesParity` uses them. Forward only non-colour tokens and mixins; the parity page `@use`s the colours itself.
  - [ ] **Style Studio rebuilds the neutral grounds (P6):** `AppStyleStudio/index.vue:274, 495-511` and `shared/portfolio-chrome.ts:152-171` re-list `NEUTRAL_ROLE_STEPS`. Add `paperInkPreview(pair, mode)` beside `checkPaperInk`.
  - [ ] **Utilities entries leak (U1).** `core/web/shared/utils/{debounce,throttle}.ts` import `@tgmc/utilities/browser` and `to-snake-case.ts` the Node root; `shared/` is auto-imported into Nitro (`.nuxt/types/nitro-imports.d.ts`) and the client. Move `debounce` / `throttle` to `/universal` (or delete the three unused wrappers) and add `no-restricted-imports` under `core/web/shared/**`.
  - [ ] **`EventHandler` name clash (U2):** `EventHandler` / `EventsHandler` are Node `EventEmitter` on the root (`packages/utilities/src/index.ts:20`) and DOM `CustomEvent` on `/browser` (`browser.ts:30`). Keep only `NodeEventsHandler` / `DomEventsHandler`; make the root a superset of `/universal`.
  - [ ] **`/browser` installs a global storage listener on import (U3):** `web-storage-service.ts:226` creates `storage` at module load and its constructor (`:49-57`) logs every cross-tab `storage` event. Create it lazily, drop the debug listener, declare `"sideEffects": false`.
  - [ ] **E2E audit policy and duplicate measurements (E1 / E2).** Thresholds, `KNOWN_ISSUES` and recording live in `responsive-components.cy.ts:71-260`, and `ui-audit.cy.ts:30-130` restates the floors without known-issue filtering — move them behind one `expectLayoutClean(scope)` in `support/layout-audit.ts`. Page overflow is measured four ways (`layout-audit.ts:180, 489`, `responsive.cy.ts:11-15`, `ui-audit.cy.ts:113`), visibility three ways (`floorAudit`'s ignores `inert`), viewports are listed four times (done: listed once in `support/viewports.ts`, 2026-10-14) and the floors are magic numbers (43.5, 24, 11.95): one `support/viewports.ts`, one `visible` / `pageOverflow`, one `FLOORS`; fold `responsive.cy.ts` into the page pass.
- [ ] Guard coverage for admin (design-system audit M1): the units report (`scripts/scss-units-report.mjs:23-29`), the type-floor scan (`core/web/tests/ui-floors.spec.ts`), the admin colours guard (`core/admin/tests/colors-scss.spec.ts:84-95`) and the e2e responsive suites (`PUBLIC_ROUTES` only) skip `core/admin/{app,assets/css}` and `packages/web-layer-admin/app`. Add them (admin routes with a stub session in `ui-audit.cy.ts`), then fix what they find, including:
  - [ ] Admin colours guard gaps (`core/admin/tests/colors-scss.spec.ts`): it still accepts (a) a brand fill used as text, `color: var(--theme-primary-color)` (3:1 — text uses an `-ink` role), and (b) paints from the unset `--theme-background-color` hook (and `--theme-background-{secondary,accent}-color`), which resolve to nothing and leave the surface transparent — the #267 admin sheet bug. Reject both, then fix what they find.
  - [ ] M2: `core/admin/app/components/AdminDatabaseSelector.vue:67-72` — the `select` border is the 8 % hairline `--theme-border-color` (use `--theme-border-strong-color`) with `0.25rem` padding; `AdminNav.vue` — done (touch targets in #279; current section underlined with `aria-current` on nested routes in PR 0); `layouts/default.vue:10` — `min-height: 100vh` (use `100dvh`).
  - [ ] M3: `core/admin/app/pages/admin/cdn/index.vue` — fixed in [PR #279](https://github.com/likwidmack/portfolio/pull/279): the table scrolls in its own labelled, keyboard-focusable box (no page overflow at 375px), Delete leads each row and is named after its object, the empty header reads "Actions", and the Object key label reaches its input. PR 0 added row headers, column classes, chunked uploads and focus after delete (next Delete, else the status line). Still open: Delete removes the object at once with no confirm-in-place / Undo.
- [ ] Token clean-up (design-system audit 2026-10-06; each needs a design decision):
  - [ ] **Scales (M5):** spacing (~470 rem literals in `gap` / `padding` / `margin` against 16 `var(--space-*)`, ~130 off the 4px scale), type (~130 `font-size`, 27 on `--font-size-*`), radius (literals and mismatched `var(--border-radius-sm, …)` fallbacks), blur (`blur(14–20px)` literals instead of `--blur-*`), motion (`--transition-*` used twice; `150–550ms` literals) and no z-index scale (1 … 1100; the gallery feed's 500 sat over the header's 99 — since 2026-10-19 the full view `GalleryViewer` uses 500 and the gallery layout has no header). Add the missing steps plus `--z-*` and `--duration-*` / `--ease-*`, then a guard for off-scale literals.
  - [ ] **Duplicated patterns (M6):** the focus-ring recipe is hand-written 33 times (no `focus-ring` mixin); pill / tag variants in `work/case-study.scss:174-179`, `AppWorkCard.scss:138-147`, `code/index.scss:37-48`, `gallery/index.scss:196-206` and the global `.tag` (`_globals.scss:102-107`) instead of `UiTag` / `UiChip` (2026-10-14: the `/work/[slug]` technology list and the gallery grid's kind / platform chips now render `UiTag` — Task 15; `AppWorkCard`, `GalleryFeedCard` (removed 2026-10-19) and the evidence dialog too, and the global `.tag-list li` chip is gone — Task 16; `code/index.scss` `__lang` and the global `.tag` remain); two segmented controls (done for web: `UiSelectButton`, Task 16; admin `.media-kinds` remains, follow-up); a local `.sr-only`, `.button-row` five times and an admin `.panel` restyle.
  - [ ] **Three button systems (M7):** theme `.btn` (`globals/_button.scss`, used only by `/styles/parity` and the Studio preview), PrimeVue via `UiButton`, Foundation `.button`; plus hand-rolled buttons that reset the global `button:not(.p-button)` gradient ("Back to grid" — gone with the feed on 2026-10-19 — the Menu trigger, `/about`, admin media). Make `UiButton` the one button, archive unused `.btn` variants, narrow the global base to a reset. The first part is done: `UiButton` has `variant="ghost"`, `size` and `to` / `href`, and its call sites pass only declared props; the three button systems remain.
    - [x] 2026-10-14: `UiButton` gains `flat`; flat recipe in the theme (Task 6). Its `to` / `href` links are now upstream's implementation (2026-10-19 merge), with `flat` and the status fills ported into `packages/nuxt-layer-ui`. Remaining: archive unused `.btn` variants, narrow the global base.
    - [x] 2026-10-14: the pages use `UiButton` / `UiTag` / `UiTextarea` / `UiImage` / `UiCard` in place of hand-rolled controls (Task 15; table and the kept-on-purpose list in [App SCSS § Components](./app-scss.md#components)).
    - [x] 2026-10-14 (Task 16): fixed in `UiButton` (theme status hue fill, paper label, underline on hover; every branch); the `/about` rule is removed. Was: filled status `UiButton` links (`:href` / `to` + `severity="success"` …) paint no fill when no PrimeVue `Button` is mounted: PrimeVue's unlayered `.p-button-success { background: var(--p-button-success-background) }` wins over the theme's layered `pv-solid-tone`, and the variable is undefined; UiButton's unlayered `.p-button[href]` text colour also beats the status paper text. `/about` works round it in `about.scss` (`&__resume.p-button[href]`). Fix in `UiButton` / `_primevue-union.scss`, then drop that page rule.
    - [x] 2026-10-14 (Task 16): `UiCard` maps its default slot into PrimeVue Card's `#content` (mount test `ui-card.spec.ts`); `/process` uses the default slot. Was: `UiCard`'s default slot renders nothing under PrimeVue: the bare `slot` becomes PrimeVue Card's default slot, which Card does not render (only the native fallback puts it in `.p-card-content`). Callers use `#content` (`/process`, `error.vue`); fix `UiCard` to feed the default slot into `#content`.
    - [x] 2026-10-14: the shared components use `UiSelectButton` / `UiButton` / `UiInputText` / `UiRadio` / `UiTag` / `UiImage` (Task 16; table in [App SCSS § Shared components](./app-scss.md#shared-components-task-16)).
    - [ ] Filled `secondary` / `help` / `contrast` `UiButton` links: PrimeVue's unlayered `.p-button-secondary` (and the others) also read `--p-button-*` tokens that are undefined on a links-only page. No such link exists today; give them a fill in `UiButton` when one is added (the flat `secondary` recipe must keep winning in flat contexts).
    - [ ] Still hand-rolled: admin `/admin/media` buttons (upload trigger, tag filters with `aria-pressed`, `core/admin/app/pages/admin/media/index.vue:38-51`) — move to `UiButton` (outside the Task 15 page list).
    - [x] `/about`: `.about-cv__contact` named both the sidebar `dl` and the old contact link, so the link's button recipe (inline-flex, border, uppercase) painted the `dl`. Fixed in Task 15 fix round 1: the `dl` is `.about-cv__contact-list`, a plain definition list, and the dead block is gone (archived).
  - [x] **OS reduced motion collapses transitions too (M8):** the `prefers-reduced-motion` branch in `core/web/assets/css/_globals.scss` now matches `data-motion='reduced'` (`transition-duration: 0.01ms`); guarded by `core/web/tests/reduced-motion.spec.ts`.
  - [x] **`2.75rem` instead of `var(--touch-target)` (M9):** fixed in Personalize, the home page, `.btn-group--lg`, `AppPrimaryNav.scss` and `about.scss`, and guarded in `core/web/tests/ui-floors.spec.ts`. Both files use `var(--touch-target)`; the allowlist is now empty and `ui-floors.spec.ts` fails on stale entries. Not part of this item and unchanged: `globals/_objects.scss:120` (`audio { min-height: 2.5rem }`, not a bare `2.75rem`).
  - [x] **`vw`-only fluid type (M10)** — done 2026-10-14 (Task 3): `clamp(a, Nvw, b)` in `core/web/assets/css/_globals.scss:40, 85, 92, 149, 153`, `AppWorkCard.scss:20, 169, 206`, `GalleryFeedCard.vue:163` (removed 2026-10-19), `about.scss:90, 184`, `blog/index.scss:70`, `index.scss:27, 37, 88` — the heading doesn't grow with the reader's text size (WCAG 1.4.4). Use `clamp(a, b rem + c vw, d)` or `--font-size-*`, and reject `vw`-only clamps in `ui-floors.spec.ts`.
  - [x] 2026-10-14: camera blocked / Personalize Applied are announced (C5, C6) — polite `role="status"` regions ([personalization.md](./personalization.md#status-announcements)).
  - [x] **Mixed px / em breakpoints (M12):** the browse toolbar and Style Studio device-class pairs use `#{bp(tablet)}` (48em) instead of `$breakpoint-tablet` (768px).
  - [ ] **Sass colour values in the theme globals (M4):** `globals/_container.scss` (section insets, table header / stripe tints), `_objects.scss` (media borders; every `svg` / `canvas` gets `rgba($color-gray-lt, .04)`), `_class-selectors.scss:69, 99-115`, `_animate.scss:349-352`, `_mixins.scss:184-199`. They ignore mode and paper / ink (`rgba(black, .1)` stripes vanish on the dark page). Map them to alphas / `--theme-shadow-color` mixes and extend the rule-3 guard to property values.
  - [ ] **Grey families (L1):** `--theme-gray-{100…500}-color` and `--theme-gray-{1…5}-color` hold the same steps (plus `--theme-gray-med-color`), numbered against the neutral scale; the page ground has four names (`--theme-main-background-color`, `--theme-paper-color`, the unset hook `--theme-background-color`, `--theme-surface-color`). Deprecate one family; document which ground name is for what.
  - [ ] **Unused atmosphere colours (L2):** `core/web/assets/css/_variables.scss:48-90` (`haze-1…4`, `particle-*`, `grid-glow`, `grid-line`, `coral`, `ivory`) have no readers but are mirrored in `shared/portfolio-chrome.ts` and pinned by tests. Archive them, or wire them into `AppDepthField`.
  - [x] **`UiTag` icon-font class (L3):** `packages/nuxt-layer-ui/app/components/ui/UiTag.vue:5` renders `i.p-tag-icon(:class="icon")`; render `UiIcon` like `UiChip`.
  - [ ] **Style Studio swatches (L4):** `AppStyleStudio.scss:185-191` makes them 1.75rem (28px) wide; `index.vue:116-126` has `role="list"` children that are buttons with no `listitem`. The swatches no longer pass the undeclared `text` / `rounded` props to `UiButton`; their size is unchanged.
  - [ ] **Primary text-shadow under body text (L6):** `--text-shadow-root` on `body` mixes the primary (`globals/_root.scss`), and `label` / `legend` add `--text-shadow-sm|md` (`_form.scss:23, 31`). Owner decision: keep it for display type only?
- [x] Phone `.page-nav` (`AppPageNav` / `AppWorkSubNav`): below 48em a labelled disclosure ("On this page · <current>", 44px, `aria-expanded`) opens a vertical 44px list; `Esc` / a link tap closes it (`usePageNavDisclosure`). Was a swipe-only row.
- [x] Five-input colour model (primary, secondary, accent, paper, ink → derived grayscale + status tones): plan Task 2b.
- [x] Style Studio: **paper** (background) and **ink** (text) per mode, "other mode uses the inverse" link, live contrast readout, swap / reset, persisted (`tgmc-paper-ink`, FOUC) and in setups. See [personalization.md](./personalization.md#pen--paper).
- [ ] `AnalogClock.vue` is unreferenced (dead since the Sept-4 restyle); archive + remove it like `NxWelcome`.
- [ ] Personalize (quick panel): optional paper / ink presets (e.g. warm, cool, high contrast) reusing `withPaperInk`.
- [x] Colour system, stages 1–8: solid colours + variations, runtime on the per-mode variations, `--portfolio-*-color` / `--web-*-color` globals, no literals in pages / components, bridges, and (Task 8) the old names removed with strict guards and the JS API on the new names. See [packages/theme.md § Colour system](../../packages/theme.md#colour-system) and agent rule 17.
- [ ] Colour system follow-ups: `.p-dialog-mask` in `_globals.scss` still mixes with a literal `black` (allowlisted in `tests/colors-scss.spec.ts`); style setups do not record the pack id, so a setup loaded from a pack uses its mode's hexes as a custom pick for both modes; ~~the `colors.json` / `darkCssVariables` mirrors keep the Sass source hexes for brand, status, focus and button text~~ fixed 2026-10-14: the mirrors and the theme.md table are generated from the compiled `_root.scss`; the colour-mode writer still pins the palette name `--primary-default` inline per mode (declare its light value in `theme-light-vars` to drop the pin).
- [x] **Vendored themes unlinked (2026-10-14):** Foundation comes from npm `foundation-sites` 6.9.0 through Sass `pkg:` imports, with the compiled CSS pinned by `theme/core/tests/foundation-css-equivalence.spec.ts`; the PrimeVue v3 Sass theme (`mytheme` + `theme-base`) and the classic Sass / PassThrough path are archived in `theme/core/scss/_archive/2026-10-14-primevue-v3/`, and the third-party v3 themes are removed ([theme.md](../../packages/theme.md#third-party-layers)).
- [x] **AA:** brand colour used as 0.75rem text below 4.5:1 (light 3.75:1, dark 3.18:1) — fixed with the derived text role `--theme-primary-ink-color` (light `#a33e16`, dark `#e65059`; ≥ 4.5:1 on page, surface and variant; recomputed on Style Studio picks and paper / ink). Every `color:` / `-webkit-text-fill-color:` in `core/web` and `core/admin` that read `--theme-primary-color` (eyebrow mixin, `dt` labels, hovers, current states, link fallbacks) and the theme's PrimeVue / `.btn` outline and text-button text now read it; a guard refuses a main variation as text ([theme.md](../../packages/theme.md#contrast-roles)).
- [x] **AA:** secondary as text below 4.5:1 (dark `#8a6a56`: 4.02:1 on paper, 3.77:1 on surface) — fixed with `--theme-secondary-ink-color` (built like primary-ink: light `#6e1622`, dark `#a17e68`; ≥ 4.5:1 on page, surface and variant for the defaults and all 21 presets; recomputed on Style Studio picks and paper / ink). Prose `li::marker` and `dl dt` read it; on tints it mixes toward the text colour — table `th` and the `/styles` column labels at 60 % ink, the architecture diagram's group labels at 75 % (preset-tested on their real tints); `cite`, code text and inline code mix from it; the code-block language pill paints `--theme-ink-color` on `--theme-secondary-background-color`. UiCodeBlock frames lost their resting `opacity: 0.65` (owner decision; code text 3.53 → 8.84:1 light at rest) and their line numbers now read `--theme-gray-200-color` instead of being repainted by the prose `ol li` text colour (light 1.01 → 13.09:1). **`time`** now uses `--theme-text-secondary-color` (was light 2.08:1, dark 1.48:1; now 8.76 / 8.13). The main-variation-as-text allowlists hold only the diagram's edge strokes ([theme.md](../../packages/theme.md#contrast-roles)). Accent paints no text. PrimeVue `mytheme` (archived 2026-10-14 in `theme/core/scss/_archive/2026-10-14-primevue-v3/`) set text via Sass variables from `$primaryColor` (`$tabviewHeaderTextActiveColor`, `$calendarMonthYearHeaderHoverTextColor`, `$tableHeaderCellHighlightText*Color`) — switch them to the ink role if it is ever restored.
- [x] **AA:** code frames scroll but had only the browser default focus cue once the resting fade went: each `UiCodeBlock` frame is now a named focusable region (`role="region"`, `tabindex="0"`, "Code: <language>") with the 2px `--theme-focus-ring-color` ring ([theme.md](../../packages/theme.md#style-layers-and-units)).
- [x] Status / focus follow a custom paper / ink: the runtime map rebuilds all eight solid colours and the status inks (`--theme-<status>-ink-{light,dark}-color`, builder-computed: ≥ 4.5:1 on page, surfaces and variant for any pair whose text rows pass); `checkPaperInk` shows Success / Warning / Error / Info text rows in Style Studio ([personalization.md](./personalization.md#colour-variations-and-the-fouc-map)).
- [x] Hover / active tints under primary-ink text: `.btn` outline / ghost (`globals/_button.scss`) and `.p-button` / `.p-button-outlined` / `.p-button-text` (`globals/_primevue-union.scss`) keep their 12–18 % primary hover washes (plus the inset primary shadow) and 16–20 % secondary `:active` washes. With the ink text they are far better than before but not all ≥ 4.5:1 — outline hover light 4.37 on paper / 3.92 on surface, dark 4.50 / 4.21; ghost / `.p-button` hover light 4.29 / 3.84; `:active` secondary light 3.10. **Done:** computed washes `--theme-{primary,secondary}-wash-color` (`buildWashTokens`, painted at 24 %) keep primary-ink ≥ 4.5:1 over page, surfaces and variant for the defaults and all 21 presets; the covering inset shadow became a 1px inset ring, ghost / text buttons underline on hover ([theme.md](../../packages/theme.md#runtime-model)).
- [x] **AA:** `--portfolio-rose-color` (the primary mixed 70 % / 56 % toward the ink) painted every inline text link without a contrast check (default dark 4.58:1, midnightMagic dark 4.20:1, random picks down to 3.75:1, 3.08:1 on the nav wash). **Done:** it is `--theme-link-color`, the builder-computed link ink (`buildLinkTokens`: ≥ 4.5:1 on page, surfaces, variant and its own 12 % / 16 % washes), and `--portfolio-rose-strong-color` an OKLab mix of it toward the text colour (85 % light / 50 % dark) — defaults, all 21 presets and 300 random paper / ink pairs ([theme.md](../../packages/theme.md#derived-families)).
- [x] Colour system rule 3 gap: the last Sass-valued roles (`--theme-link-color`, `--theme-on-primary-color`, `--theme-primary-{hover,inverted}-color`, `--theme-secondary-inverted-color`, `--theme-main-color`, the form roles, `--theme-button-secondary-fg-color`, the `--button-*-bg` gradients, every shadow, `accent-color`) are `var()` / `color-mix()`s of variations; the unused ones (`--theme-primary-action-color`, `--theme-main-{secondary,background-accent}-color`, `--theme-teal-signal-color`, `--theme-default-*-color` + `--foundation-{white,black}`, `--theme-button-border-color`, `--rgb-{white,neon,shadow,shadow-alt}`) are retired and archived. Guard: `theme/core/tests/rule3-guard.spec.ts`; contrast: `theme/core/tests/derived-roles-contrast.spec.ts` ([theme.md](../../packages/theme.md#derived-families)).
- [x] Dark `--theme-button-hover-fill-color` is undeclared (light-only), so dark hover paints transparent (`theme/core/scss/globals/_button.scss:62,70`, `_primevue-union.scss:301`); declare it or add a fallback. **Done:** dark = `var(--theme-button-fill-color)` (button text ≥ 4.5:1 on it by construction).
- [x] Dark `--theme-button-secondary-fg-color` is a static Sass value and ignores Style Studio picks. **Done:** it is `var(--theme-button-fg-color)`; the sheen stops are built for it (`buildButtonStopTokens`), so it reads ≥ 4.5:1 on every gradient point for any pick or paper / ink.
- [ ] Rule 3 follow-ups (exceptions kept on purpose): the syntax palette (`globals/_syntax.scss` `--syntax-*` hexes, `--rgb-accent-soft`, the language badge's `rgba($default-white, .5)` border) is data on an always-dark code pane, not derived; the Sass `$css-form-*`, `$text-shadow-*`, `$main-*` and `$teal-signal-*` values only feed `colors.json` now (prune them with the Sass inventory); `--primary-default` no longer feeds `--text-shadow-root`, so its per-mode inline pin only serves the Theme API — drop the pin with the follow-up above.
- [x] Test every Studio preset against its contrast targets (only `colorRed` is tested today) — `core/web/tests/studio-preset-contrast.spec.ts`.
- [x] Assert `RUNTIME_COLOR_TOKEN_NAMES` ⊆ the names the theme declares (compiled `_root.scss`) — `core/web/tests/runtime-color-tokens.spec.ts`.
- [x] (low) Replace the `core/web/tests/styles-studio.spec.ts` source-string test with a behaviour test — the readout lives in `shared/studio-readout.ts` and is driven with a painting resolver.
- [x] (low) Dev-only warning when a retired colour key (`retired` in `color-rename-map.json`) is passed to the theme API — today it is dropped silently. **Done:** one `console.warn` per name outside production.
- [x] SCSS hierarchy + units: Tasks 1–7 done (strict units check, page / component contract tests) — [docs/superpowers/plans/2026-09-24-scss-hierarchy-and-units.md](../../superpowers/plans/2026-09-24-scss-hierarchy-and-units.md).
- [ ] Docker: the compose project and container names are fixed (`tgmc-*`), so an `up` from a git worktree recreates the primary checkout's containers (seen Oct 1). Consider a per-checkout `COMPOSE_PROJECT_NAME` and dropping `container_name`; names left unchanged for now.
- [ ] Generator templates (`packages/likwidlibs/src/generators/nuxt-app/files/app/{app.vue,pages/index.vue}__tmpl__`): colour-literal fallbacks (`var(--theme-…, #hex)`), the 8 % hairline `--theme-border-color` for borders, and `--theme-primary-color` as a fill under text (use `--theme-primary-fill-color` / `--theme-on-primary-color`).
- [ ] Generator `docker-node` target: the workflow builds `core/<name>/Dockerfile`, which the generator does not create.
- [ ] Admin blog pages (`packages/web-layer-admin/app/pages/admin/blog/{index,[id]}.vue`) still render a `!writesEnabled` banner that `core/admin` can never show (`adminWritesEnabled: true` constant).
- [ ] Root `npm run dev` (`nx nuxt dev`) fails with "Cannot find project 'dev'" — Nx reads `nuxt` as the target and `dev` as the project. `npm start` (`nx dev @tgmc/web`) works. Fix the script and the `AGENTS.md` / `scripts/update-agents.mjs` lines that quote it.
- [ ] `UiCodeBlock`: the inner `code.syntax-code` is the element that scrolls sideways, not the focusable `.syntax-frame` region, so axe reports "Scrollable region must have keyboard access" (seen on `/styles/parity`, Oct 14). Make the frame the only scroll container.
- [ ] Pre-commit hook: any change under `theme/` or the root makes `@tgmc/web` and `@tgmc/web-e2e` affected, and their full `eslint .` fails on pre-existing errors in untouched files (`core/web-e2e` Cypress `unsafe-to-chain-command` / `no-unnecessary-waiting`; the `UiRadio.vue` `prettier/prettier` error is fixed, PR 2 Task 5), so `scripts/lint-staged-nx.mjs` blocks those commits. The vendored-themes unlink (2026-10-14) committed with `HUSKY=0` after running Prettier and ESLint on the staged files by hand; fix the errors or scope the staged lint to the staged files.
- [ ] `theme/core/scss/globals/_root.scss`: three `color-mix()` values are not Prettier-formatted, and Prettier's reflow changes the compiled CSS (Sass keeps line breaks inside custom-property values: 47,084 → 48,044 bytes), so the next commit of that file through the hook reformats it. Add `// prettier-ignore` to those declarations or accept the whitespace change deliberately.
- [ ] Style Studio (`/styles`): the rail titles (Setups, Packs, Colors) are `h3` straight under the page `h1`, so axe warns "Heading levels should only increase by one". Decide the outline (rail titles as `h2`, or an `h2` for the rail) and keep the visual size via the class.
- [ ] Touch targets under 44px (measured 2026-10-15; not caused by the vendored-themes unlink): `/work` card title links are 34px tall at 375px wide, `/blog` list title links are 22px tall, and the admin media drawer's icon-only "Close details" button (`AdminMediaDrawer.vue`) is 36px wide. Give them the `touch-target` mixin (`$square: true` for the icon button).
