@clipboard-health/ai-rules 2.24.4 → 2.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.24.4",
+  "version": "2.25.1",
   "description": "Pre-built AI agent rules for consistent coding standards.",
   "keywords": [
     "ai",

package/skills/babysit-pr/SKILL.md

@@ -27,9 +27,9 @@ This skill always runs exactly one pass. It never waits or repeats internally. F
 
 The skill uses two sentinels. Each is a visible footer line wrapped in `<sub>` (a 🤖 mark plus the token in `<code>`).
 
-**Addressed sentinel**: `<sub>🤖 <code>babysit-pr:addressed v1 core@3.7.1</code></sub>`. Appended on its own line at the end of every reply the skill posts (both thread replies and the review-body summary); this is how re-runs know which threads and review-body comments are already handled. Dedupe matches the version-agnostic substring `babysit-pr:addressed v1` followed by a space (also matches legacy `<!-- babysit-pr:addressed v1 ... -->` sentinels). Grep `babysit-pr:addressed v1` for any version; add `core@3.7.1` for a specific one.
+**Addressed sentinel**: `<sub>🤖 <code>babysit-pr:addressed v1 core@3.8.0</code></sub>`. Appended on its own line at the end of every reply the skill posts (both thread replies and the review-body summary); this is how re-runs know which threads and review-body comments are already handled. Dedupe matches the version-agnostic substring `babysit-pr:addressed v1` followed by a space (also matches legacy `<!-- babysit-pr:addressed v1 ... -->` sentinels). Grep `babysit-pr:addressed v1` for any version; add `core@3.8.0` for a specific one.
 
-**Follow-up sentinel**: `<sub>🤖 <code>babysit-pr:followup v1 core@3.7.1</code></sub>`. Attached to replies that defer an out-of-scope comment as a tracked follow-up (see the Scope subsection and the Defer verdict in step 6). Grep `babysit-pr:followup` across PR conversation JSON to enumerate deferred items. This sentinel is additive — the post-reply scripts still append the `addressed` sentinel at the end, so a deferred thread is correctly machine-classified as addressed (the skill _has_ handled it — by deferring). Human reviewers and future sweeps distinguish deferred from resolved by looking for the follow-up sentinel.
+**Follow-up sentinel**: `<sub>🤖 <code>babysit-pr:followup v1 core@3.8.0</code></sub>`. Attached to replies that defer an out-of-scope comment as a tracked follow-up (see the Scope subsection and the Defer verdict in step 6). Grep `babysit-pr:followup` across PR conversation JSON to enumerate deferred items. This sentinel is additive — the post-reply scripts still append the `addressed` sentinel at the end, so a deferred thread is correctly machine-classified as addressed (the skill _has_ handled it — by deferring). Human reviewers and future sweeps distinguish deferred from resolved by looking for the follow-up sentinel.
 
 **Sentinel recency rules.** The script emits a per-thread `activityState` with three values:
 
@@ -280,7 +280,7 @@ Body templates (the script appends the `addressed` sentinel if missing):
 - **Agree**: `Addressed in <commit-url>. <one-line what-changed>.`
 - **Disagree**: `Leaving current behavior. <reasoning>.`
 - **Already fixed**: `Already handled by <commit-url-or-file:line>. <brief pointer>.`
-- **Defer**: `Out of scope for this PR; this looks like follow-up work rather than something introduced or required by this change. <one-line rationale or pointer if useful>.\n\n<sub>🤖 <code>babysit-pr:followup v1 core@3.7.1</code></sub>`
+- **Defer**: `Out of scope for this PR; this looks like follow-up work rather than something introduced or required by this change. <one-line rationale or pointer if useful>.\n\n<sub>🤖 <code>babysit-pr:followup v1 core@3.8.0</code></sub>`
 
 For Defer replies, include the follow-up sentinel on its own line as shown. The script will append the `addressed` sentinel after it on its own line, so the final body ends with the follow-up sentinel followed by a blank line followed by the `addressed` sentinel — `grep babysit-pr:followup` finds the deferral and `grep babysit-pr:addressed` still marks the thread handled for dedupe.
 
@@ -296,7 +296,7 @@ The PR-level summary should:
 
 - Group by source. Use `## Review-body findings` for step-7 work and `## Conversation-tab comments` for step-6b work. Omit a section if its list is empty.
 - Inside each section, group verdicts under **Agree / Disagree / Already fixed / Deferred (out of scope)** subheadings. Omit a subheading if its list is empty.
-- Under **Deferred (out of scope)**, list each deferred item as a bullet, followed on its own line by `<sub>🤖 <code>babysit-pr:followup v1 core@3.7.1</code></sub>` so grep catches them individually.
+- Under **Deferred (out of scope)**, list each deferred item as a bullet, followed on its own line by `<sub>🤖 <code>babysit-pr:followup v1 core@3.8.0</code></sub>` so grep catches them individually.
 - Include the commit URL for fixes.
 - End with a fenced fingerprint block listing every current fingerprint — addressed and deferred — one per line. Include both `reviewBodyComments[].fingerprint` (whole-body, one per automated review) and `activeIssueComments[].fingerprint` (per Conversation-tab comment). Future runs dedupe by matching these against `priorBabysitSentinels`.
 

package/skills/babysit-pr/scripts/_sentinel.sh

@@ -9,7 +9,7 @@
 # substituted at build time by embedPluginVersion.mts.
 
 SENTINEL_PREFIX='babysit-pr:addressed v1 '
-SENTINEL='<sub>🤖 <code>babysit-pr:addressed v1 core@3.7.1</code></sub>'
+SENTINEL='<sub>🤖 <code>babysit-pr:addressed v1 core@3.8.0</code></sub>'
 
 # Bot author allowlist (JSON array literal). Used by unresolvedPrComments.sh
 # as a fallback when GraphQL's `author.__typename == "Bot"` misses a GitHub

package/skills/clipboard-design-engineering/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: clipboard-design-engineering
+description: Use when a Clipboard frontend task involves UI polish, motion or animation decisions, interaction feel, small interaction details, visual hierarchy, component craft, or reviewing whether admin/mobile UI feels consistent with Clipboard's product and design-system standards.
+---
+
+# Clipboard Design Engineering
+
+Use this skill when the UI already works functionally but still needs taste: spacing that holds up under dense data, motion that feels intentional, interaction states that respond immediately, and components that belong inside Clipboard's admin and mobile products.
+
+Clipboard UI is operational software. People use it to scan, compare, decide, and repeat. The best visual work here is quiet. It makes state obvious, removes doubt, and keeps the user moving. Decoration that does not improve comprehension is noise.
+
+## Core Philosophy
+
+- **System first**: existing Clipboard components, stories, and theme tokens are the starting point. New visual patterns need a reason.
+- **Evidence over vibes**: Figma and screenshots define intent. Storybook screenshots prove the implementation.
+- **Density is a design constraint**: admin tables, cards, drawers, shift details, and mobile sheets must survive long names, translated copy, dense rows, empty states, and loading states.
+- **Motion must earn its cost**: motion should explain state, preserve spatial continuity, show progress, or confirm input.
+- **Frequent actions should feel instant**: if the user hits it all day, keep it crisp and almost invisible.
+- **Rare moments can carry more feeling**: completion, education, and onboarding can be warmer, but never sloppy.
+
+## Before Changing UI
+
+1. Search existing components, stories, and theme tokens before creating a new visual pattern.
+2. Prefer repo-owned design-system components over bespoke markup.
+3. In admin redesign work, use Berlin/MUI `sx` with theme tokens.
+4. In mobile redesign work, use the existing app V2 redesign components, Storybook decorators, and mobile viewport presets.
+5. Add or update a Storybook story for any non-trivial visual, interaction, or animation change.
+
+## Motion Decision Framework
+
+Before adding animation, answer these in order:
+
+1. **How often will this run?**
+   - Keyboard-heavy or repeated actions: no motion, or near-instant feedback only.
+   - Occasional actions such as drawers, dialogs, filters, and toasts: restrained motion.
+   - Rare education or completion moments: more expressive motion is allowed.
+2. **What does it explain?**
+   - Good reasons: state change, spatial relationship, input feedback, progress, continuity.
+   - Bad reason: it makes the mock feel more alive.
+3. **What should the user feel?**
+   - Admin surfaces should feel fast, stable, and trustworthy.
+   - Mobile surfaces should feel responsive, thumb-friendly, and native enough.
+   - Anything that delays decision-making is a regression.
+
+## Motion Rules That Matter
+
+- Do not animate keyboard-heavy or very frequent actions unless the motion is nearly instant and clearly improves feedback.
+- Prefer no animation over slow animation.
+- Keep most UI motion under 300ms. Longer motion needs a reason such as education, progress, or a rare completion moment.
+- Use explicit transition properties. Do not use `transition: all`.
+- Prefer `transform` and `opacity` for movement. Avoid animating layout properties such as width, height, top, and left unless the component has a measured reason.
+- Entering UI should respond immediately. Slow starts make the product feel delayed.
+- Moving UI should handle rapid user input. Prefer CSS transitions for state changes that can be redirected and reserve keyframes for predetermined loops or decorative sequences.
+- Respect `prefers-reduced-motion`. Reduced motion can keep opacity/color transitions, but should remove or reduce position and transform movement.
+- Gate hover-only motion behind real hover capability on touch-sensitive UI.
+- Loading skeletons should match the final content shape and not resize the layout.
+- Pressed states should acknowledge input immediately with a subtle visual response when the component style supports it.
+- Popovers, menus, and anchored overlays should visually originate from the trigger. Dialogs and centered modals should stay centered.
+- For stacked overlays such as drawers, side panels, dialogs, or bottom sheets over an existing surface, preserve spatial continuity: the parent layer should remain stable, the child layer should have a clear origin, and backdrop, focus, dismiss, and rapid re-open behavior should be inspectable.
+- Loops and pulses need a stop condition or a strong reason. Persistent pulsing is usually visual debt.
+
+## Component Feel Checklist
+
+Check these before calling a UI polished:
+
+- Text hierarchy scans correctly in the target viewport.
+- Spacing uses theme tokens and matches nearby local patterns.
+- Interactive elements have hover, active/pressed, focus-visible, disabled, and loading states where applicable.
+- Touch targets are at least 44px on mobile.
+- Long names, translated copy, dense data, and empty/error states do not break layout.
+- Iconography, radius, borders, shadows, and colors match the local design-system usage.
+- Loading, success, and error states are specific enough that the user knows what happened and what to do next.
+- Motion communicates a state change, not just style.
+
+## Anti-Slop Checks
+
+Reject these patterns unless there is a very specific local reason:
+
+- A new wrapper `Box` layer that only exists to make spacing guesses easier.
+- A color copied from Figma instead of mapped to a theme token or named as a design-system gap.
+- A story that only renders the happy path.
+- A loading state whose skeleton does not match the final content footprint.
+- A mobile sheet that looks fine at `390x844` but clips at `375x667`.
+- A hover effect that fires on touch devices.
+- An animation that cannot be replayed or inspected in Storybook.
+- A "polished" component with no focus-visible state.
+- Text that only works for the sample name or English copy.
+
+## Storybook Evidence
+
+For visual or motion claims, the Storybook story should make the claim inspectable:
+
+- Include default, loading, empty, error, disabled, long-text, and dense-data states when relevant.
+- Include mobile and desktop stories when the layout differs.
+- For animation, include a replay control, deterministic key, or explicit in-flight state.
+- For stacked overlay motion, include opened, child-opened, dismissed, and rapid re-open states so layering and focus handoff are visible before product integration.
+- For Figma work, attach the Figma URL with `parameters.design` when the repo supports `@storybook/addon-designs`.
+- Verify the story in a browser-controlled surface and report the story URL, viewport, state, and any console errors.
+
+## Review Output
+
+When reviewing UI polish, use this table format. Keep the rows concrete enough that another agent can patch the code without guessing.
+
+| Before                                           | After                                                                            | Why                                                             |
+| ------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `transition: all 300ms`                          | `transition: transform 180ms ease-out, opacity 180ms ease-out`                   | The moving properties are explicit and easier to verify.        |
+| A bottom sheet that only exists in the app route | A Storybook story with default, loading, long-copy, and repeatable motion states | Visual feedback stays cheap before integration work.            |
+| A custom color copied from Figma                 | The closest repo theme token or a named design-system gap                        | Clipboard UI should stay tied to the shared system.             |
+| One beautiful happy-path card                    | Stories for default, dense data, long text, empty, error, and loading            | Product UI breaks first at the edges.                           |
+| Hover-only affordance on mobile                  | Press/focus/tap states that work without hover                                   | Most mobile users never get a real hover state.                 |
+| Animation judged from code                       | Storybook replay plus screenshot or short video evidence                         | Motion quality is a rendered behavior, not a code-style belief. |
+
+If the right answer depends on taste or a missing design-system token, stop and ask for human confirmation with the Storybook URL and the exact ambiguity.

package/skills/commit-push-pr/SKILL.md

@@ -47,7 +47,7 @@ Script paths in this procedure are written as `scripts/...`, relative to this SK
 6. Check for an existing PR with `gh pr view`.
 
    PR title format: conventional-commit type + description, with no scope, plus the Linear ticket in parentheses at the end when one applies (e.g., `feat: add resume command (STAFF-123)`). This differs from the commit subject, which keeps its scope. Derive the ticket from the branch name, commit body, or session context; omit the parenthetical when no ticket applies.
-   - No PR: create with `gh pr create` using the PR title format above. Description = the PR body shape above, followed by the session footer line if known and the agent footer `<sub>🤖 <code>commit-push-pr:created v1 core@3.7.1</code></sub>` on its own line.
-   - PR exists: if the title doesn't match the format above, correct it with `gh pr edit --title`. Refresh the body via `gh pr edit --body` so (a) the new commit's changes are reflected in the prose while existing `## Summary`, `## Validation`, and `## Notes` sections are preserved unless clearly stale, (b) any known session footer line is appended if missing, never removing or rewriting existing `Agent session: ...` or `Agent session ID: ...` lines, and (c) any existing footer carrying the substring `commit-push-pr:created v1` is preserved verbatim, appending `<sub>🤖 <code>commit-push-pr:created v1 core@3.7.1</code></sub>` only if absent. Then report the URL.
+   - No PR: create with `gh pr create` using the PR title format above. Description = the PR body shape above, followed by the session footer line if known and the agent footer `<sub>🤖 <code>commit-push-pr:created v1 core@3.8.0</code></sub>` on its own line.
+   - PR exists: if the title doesn't match the format above, correct it with `gh pr edit --title`. Refresh the body via `gh pr edit --body` so (a) the new commit's changes are reflected in the prose while existing `## Summary`, `## Validation`, and `## Notes` sections are preserved unless clearly stale, (b) any known session footer line is appended if missing, never removing or rewriting existing `Agent session: ...` or `Agent session ID: ...` lines, and (c) any existing footer carrying the substring `commit-push-pr:created v1` is preserved verbatim, appending `<sub>🤖 <code>commit-push-pr:created v1 core@3.8.0</code></sub>` only if absent. Then report the URL.
 
 7. End with one short text response: branch name and the full PR URL (e.g., `https://github.com/clipboardhealth/core-utils/pull/123`). Never use shorthand like `repo#123` — always output the complete URL.

package/skills/frontend-ui-verification/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: frontend-ui-verification
+description: Use when a Clipboard frontend task involves a new UI idea, Figma/design URL, screenshot, redesign UI, design-to-code implementation, Storybook visual validation, Playwright/browser screenshot, animation/motion visual proof, or preventing design-system and visual-fidelity drift in admin or mobile UI work.
+---
+
+# Frontend UI Verification
+
+Use this skill for UI work where visual fidelity, design-system reuse, responsive behavior, or human review matters. The goal is to make frontend visual changes cheap to inspect before real integration makes feedback slow and expensive.
+
+## Core Rule
+
+Code is the source of truth for available components, story patterns, and design-system usage. Design references are the source of truth for intended appearance and behavior. Do not invent components, wrappers, or design tokens until you have searched the repo and checked the relevant design/reference source.
+
+Keep this as a cheap visual layer. Use repo rules and agent judgment for routine React implementation details. Be prescriptive only where agents commonly drift: choosing the reference source, finding existing components, creating an isolated Storybook surface, managing the Storybook server lifecycle, opening the exact canvas URL, capturing browser evidence, classifying console findings, and deleting temporary checkpoint stories.
+
+## Required Workflow
+
+1. **Identify the surface**
+   - Determine repo and surface: admin web, mobile web/app, shared package, or another frontend.
+   - Identify the strongest available reference source:
+     - Figma/design URL: fetch screenshot, design context, variables/tokens, metadata, and design-system/Code Connect mappings when available. If the URL is inaccessible, falls behind login, or returns an error, ask for an export/screenshot or treat the work as screenshot/written-idea based; do not claim exact Figma fidelity without design evidence.
+     - Screenshot/image: use it as the visual reference, and call out missing states, viewport, or interaction details.
+     - Written idea only: do not block. Search existing components and stories, choose the closest Clipboard pattern, build a Storybook checkpoint, and ask for confirmation before deeper integration if the visual interpretation is subjective.
+     - No visual reference: derive from nearby product patterns and design-system components, then verify the proposed interpretation in Storybook before product integration.
+   - Classify visible UI work as design-first: implement the smallest inspectable surface, verify it visually, then move to product integration.
+
+2. **Find the existing pattern first**
+   - Search for existing components, stories, hooks, fixtures, and nearby feature folders before creating anything.
+   - In `cbh-admin-frontend`, prefer `src/appV2/redesign/**` and Berlin components from `src/appV2/redesign/components/**`.
+   - Reuse existing Clipboard components, tokens, layouts, decorators, and story patterns whenever they satisfy the job.
+   - Add a new component only when existing components cannot express the needed UI without awkward composition.
+   - Create a generic shared component only when it is reusable across multiple surfaces and matches the established component API style. Otherwise keep it feature-local.
+   - Keep reusable components loosely coupled: pass primitive/domain props, not raw API response objects.
+
+3. **Build an isolated verification surface**
+   - For meaningful visual work, build or update the visual slice in Storybook before product integration.
+   - Use a temporary story when the goal is to validate a design slice before wiring backend/auth/routing. It is acceptable for this story to contain the full proposed UI composition with fixtures while the real product code is still being shaped.
+   - Iterate inside Storybook: apply visual feedback, retake screenshots, and keep refining until the Storybook surface matches the reference or the human confirms the interpretation.
+   - After the UI is integrated, delete temporary checkpoint stories. Keep only stories that are useful permanent documentation: generic components, reusable compositions, or important product states.
+   - Cover the states the user would naturally inspect: default, loading, empty, error, disabled, long text, dense data, permission/flag variants, and desktop/mobile variants when the design differs.
+   - For drawers, menus, popovers, steppers, tabs, forms, and animated UI, make the story render deterministic pre-action states such as closed, opened, selected, invalid, in-flight, and settled.
+   - Mock data at the story boundary. Do not force live API, auth, or route setup just to inspect visual composition.
+
+4. **Verify with browser evidence**
+   - Run the repo Storybook server as the primary visual verification surface.
+   - Start long-running Storybook servers in a process you can stop. In CLI or prompt-command validation, redirect logs to `/tmp`, record the server PID, and stop it before the final report. Do not leave a foreground dev server blocking screenshot capture, cleanup, or the final response.
+   - Open the exact story in a browser-controlled surface. Prefer the active Browser/Chrome tool when available; otherwise use Playwright against the Storybook URL.
+   - If the Storybook UI shell is noisy, open the canvas URL directly with `iframe.html?viewMode=story&id=<story-id>`.
+   - Use native Storybook test/a11y or component-level Playwright scripts only when the repo already exposes them. Do not invent a new harness for this layer.
+   - Check console errors, layout overflow, text clipping, loading/empty states, keyboard/interaction cues, and desktop/mobile viewport sizes.
+   - Classify console findings as story-introduced, provider/decorator gaps, or pre-existing/global Storybook warnings. Fix story-introduced errors before proceeding; report global warnings separately instead of hiding them.
+   - If motion or animation is part of the change, verify the motion in Storybook with a repeatable or controllable story, then capture evidence after the animation starts and after it settles.
+   - Capture screenshots when visual fidelity is part of the claim. For Figma work, compare the Storybook screenshot against the Figma screenshot element by element.
+   - If the design is non-trivial or the user needs sign-off, share the Storybook URL and screenshot summary, then wait for confirmation before deeper integration.
+
+5. **Do not give up on visual access early**
+   - Run the helper's `inspect` command first when the repo command, build command, or story URL shape is unclear.
+   - If the Storybook dev server fails, try the repo's Storybook build command and inspect the built Storybook when practical.
+   - If port `6006` is busy, use the alternate port Storybook prints and report that exact URL.
+   - If the story fails because of providers, routing, API data, or feature context, fix the story with decorators or fixture props instead of switching to product integration.
+   - If one browser tool fails, try another available browser path: Browser plugin, Chrome, Playwright CLI/script, or the agent's equivalent.
+   - Stop only after at least two reasonable Storybook access paths fail, and report the exact command, URL, error, and what evidence is missing.
+
+6. **Ask for human confirmation at the right time**
+   - Ask before choosing between multiple plausible visual interpretations.
+   - Ask after a temporary Storybook checkpoint when the user requested exact visual match, when the reference is subjective, or when the design changes layout density/hierarchy.
+   - Ask before adding a new generic component unless there are at least two concrete reuse sites or an existing design-system gap.
+   - Do not ask for routine wiring details once the Storybook surface clearly matches existing patterns.
+
+7. **Hand off after the visual surface is sound**
+   - If the UI is simple and maps directly to existing components, proceed to integration after visual inspection.
+   - Treat full product workflow checks as a separate post-verification layer.
+   - Do not expand this skill into full-flow Playwright or product-environment work.
+
+8. **Final verification report**
+   - List the reference source used: Figma/Notion/screenshot/written idea/story/code path.
+   - List the Storybook URL checked.
+   - List viewport sizes and states verified.
+   - State any unresolved visual ambiguity, missing source reference, or verification gap.
+
+## When to Stop and Ask
+
+Stop before continuing if:
+
+- Figma/design docs conflict with current code patterns.
+- A new generic component seems necessary but reuse is not proven.
+- The visual match depends on a subjective choice the reference does not answer.
+- A Figma URL is provided but no Figma screenshot, metadata, or design context can be fetched.
+- You cannot render the Storybook story or capture useful evidence.
+- User approval is needed after a temporary Storybook checkpoint.
+
+## Reference Files
+
+- Admin app details: read [`references/admin-app.md`](./references/admin-app.md) when working in `cbh-admin-frontend`.
+- Mobile app details: read [`references/mobile-app.md`](./references/mobile-app.md) when working in `cbh-mobile-app`.
+- Tooling details: read [`references/tooling.md`](./references/tooling.md) when using Figma, Notion, Linear, Storybook, browser screenshots, or another agent environment.
+- For motion-heavy UI, also apply the `clipboard-design-engineering` skill if it is available.
+
+## Helper Script
+
+Script paths below are written as `scripts/...`, relative to this `SKILL.md`, matching the other core skills such as `babysit-pr`.
+
+Use the helper before visual work to make the verification surface deterministic:
+
+```bash
+bash scripts/inspect-ui-verification-surface.sh inspect
+```
+
+Use these subcommands when an agent needs exact values instead of prose:
+
+```bash
+bash scripts/inspect-ui-verification-surface.sh storybook-command
+bash scripts/inspect-ui-verification-surface.sh storybook-build-command
+bash scripts/inspect-ui-verification-surface.sh storybook-test-command
+bash scripts/inspect-ui-verification-surface.sh component-test-command
+bash scripts/inspect-ui-verification-surface.sh storybook-url <story-id>
+bash scripts/inspect-ui-verification-surface.sh storybook-iframe-url <story-id>
+bash scripts/inspect-ui-verification-surface.sh figma-story-files
+```
+
+When running manually from a frontend repo instead of through host skill resolution, use the installed skill path, for example `.agents/skills/frontend-ui-verification/scripts/inspect-ui-verification-surface.sh`.

package/skills/frontend-ui-verification/references/admin-app.md

@@ -0,0 +1,119 @@
+# Admin App Verification Notes
+
+Use this reference for `cbh-admin-frontend`.
+
+## Source Locations
+
+- Redesign features live under `src/appV2/redesign/**`.
+- Shared Berlin components live under `src/appV2/redesign/components/**`.
+- Storybook config lives in `.storybook/`.
+- Stories are discovered from `src/**/*.stories.@(js|jsx|ts|tsx)` and `src/**/*.stories.mdx`.
+- Existing app rules require user-facing copy in redesign code to use `useTu(namespace).tu(...)`.
+- PHI shown in UI must be masked with `data-dd-privacy="mask"`.
+- Feature folders usually follow `api/`, `components/`, `hooks/`, `utils/`, plus container/view files, `types.ts`, `constants.ts`, and `paths.ts`.
+
+## Existing Storybook Setup
+
+The admin Storybook is React Vite based. `.storybook/main.ts` discovers all `src/**/*.stories.*`, serves `public`, uses `@storybook/addon-essentials`, `@storybook/addon-a11y`, and `@storybook/addon-links`, supports SVG imports, and mocks `@src/mobile/utils/openUrl` with `.storybook/mocks/openUrl.ts`.
+
+The global preview already wraps stories with:
+
+- `MemoryRouter`
+- `QueryClientProvider`
+- `BerlinThemeProvider`
+
+That means most visual stories should use the existing Storybook instead of a custom preview app. Add local decorators only for extra providers such as MUI date pickers, feature-specific contexts, or fixed-width containers.
+
+Common commands:
+
+```bash
+npm run storybook
+npm run build-storybook
+```
+
+As of the repo audit, these are the only native visual-layer scripts detected for admin. Use the app server only after the Storybook surface is visually sound and the work moves into product integration.
+
+Use this as the primary visual verification server:
+
+```text
+http://localhost:6006/
+```
+
+Story URLs usually follow this shape:
+
+```text
+http://localhost:6006/?path=/story/<story-id>
+```
+
+Direct canvas URLs are useful for screenshots:
+
+```text
+http://localhost:6006/iframe.html?viewMode=story&id=<story-id>
+```
+
+If port `6006` is busy, use the alternate port Storybook prints and report that exact URL in the handoff.
+
+## Story Requirements
+
+For visual feature work, prefer one of these story shapes:
+
+- Component primitive story: all variants, sizes, disabled/loading/error states.
+- Feature composition story: realistic fixture data showing the component in its card, drawer, modal, page section, or mobile shell.
+- Temporary design checkpoint story: a focused story that renders the full proposed UI before app wiring. Use it to iterate, capture screenshots, and get user sign-off. After integration, delete it unless it has become a useful permanent generic/component/state story.
+
+Stories should avoid live network/auth dependencies. If the real component requires API context, compose lower-level presentational pieces with realistic fixture data, as existing `DailyView`, `Calendar`, `Chat`, and `WorkerDocuments` stories do.
+
+Good local patterns:
+
+- `src/appV2/redesign/Calendar/Daily/Mobile/Layout.stories.tsx`: fullscreen mobile layout, fixed story date, realistic panes, local full-height decorator.
+- `src/appV2/redesign/DailyView/components/ShiftPostingForm/ShiftPostingForm.stories.tsx`: visual composition story for an API-bound form, using lower-level pieces and a Figma reference comment.
+- `src/appV2/redesign/DailyView/components/ValidationModals/RushFeeDialog.stories.tsx`: modal state coverage with mobile viewport parameters.
+
+## Design-System Checks
+
+Before creating new UI, search for:
+
+```bash
+rg "export function .*" src/appV2/redesign/components
+find src/appV2/redesign -name '*.stories.tsx'
+rg "title: .*<feature-or-component>" src/appV2/redesign -g '*.stories.tsx'
+```
+
+Check whether existing components already cover the need:
+
+- `Button`, `IconButton`, `Text`, `TextInput`, `SearchInput`
+- `Chip`, `Tag`, `Badge`, `Pill`, `StatusDot`
+- `Dialog`, `ResponsiveDialog`, `Drawer`, `SidePanel`, `BottomSheet`
+- `Tabs`, `SegmentedControl`, `DataGrid`, `PageLayout`
+- `InfoBanner`, `AcknowledgementBanner`, `NotificationCard`
+
+Use MUI `sx` with theme tokens. Avoid ad hoc CSS files, hardcoded colors, raw pixel spacing when a theme token exists, and wrapper `Box` layers that do not add layout value.
+
+Admin styling and component rules to preserve:
+
+- Use `BerlinThemeProvider`, not legacy theme providers, for new redesign surfaces.
+- Use `sx` with theme tokens and full property names such as `padding`, `paddingX`, `marginY`.
+- Keep presentational components API-light: pass primitives or domain props, not raw API response objects.
+- Register every new or updated shared UI component in Storybook with a `Default` story first and useful controls.
+
+## Storybook Browser Verification
+
+For non-trivial visual changes, inspect at least:
+
+- Mobile: `375x812`
+- Tablet or narrow desktop when relevant: `768x1024`
+- Desktop: `1440x900`
+
+Check:
+
+- No clipped text or horizontal overflow.
+- Loading, empty, disabled, error, and dense-data states.
+- Long names, long labels, and translated-copy expansion.
+- Keyboard and pointer cues for interactive elements.
+- Console errors and missing assets.
+- Motion and animation states when present: initial, active/in-flight, settled, and reduced-motion behavior when practical.
+- Feature flag and route behavior only after Storybook looks correct.
+
+## Out of Scope
+
+Do not use this skill to solve full workflow E2E coverage or product-environment setup. Those belong to the later post-verification layer after the Storybook visual surface has been reviewed.

package/skills/frontend-ui-verification/references/mobile-app.md

@@ -0,0 +1,129 @@
+# Mobile App Verification Notes
+
+Use this reference for `cbh-mobile-app`.
+
+## Source Locations
+
+- App V2 code lives under `src/appV2/**`.
+- Redesign mobile surfaces live under `src/appV2/redesign/**`.
+- Shared redesign components live under `src/appV2/redesign/components/**`.
+- Storybook config lives in `.storybook/`, with extra decorators under `src/appV2/.storybook/decorators/**`.
+- Stories are discovered from `src/**/*.stories.@(js|jsx|ts|tsx)` and `src/**/*.mdx`.
+- Many redesign stories live under `src/appV2/redesign/stories/**`; component-specific stories may also be colocated near the component.
+
+## Existing Storybook Setup
+
+The mobile Storybook is React Vite based and includes:
+
+- `@storybook/addon-designs` for attaching Figma/design references.
+- `@storybook/addon-interactions` for interaction stories.
+- A `design-system` Storybook ref named `CBH Core Design System` at `https://cbh-core.cbh.rocks/`.
+- Static assets from `public` and `src/assets`.
+- Vite TypeScript path support, SVG support, and node polyfills.
+
+Common commands:
+
+```bash
+npm run storybook
+npm run storybook:build
+```
+
+As of the repo audit, these are the native visual-layer scripts detected for mobile. Use the app server or device runtime only after the Storybook surface is visually sound and the work moves into product integration.
+
+Use this as the primary visual verification server:
+
+```text
+http://localhost:6006/
+```
+
+Story URLs usually follow this shape:
+
+```text
+http://localhost:6006/?path=/story/<story-id>
+```
+
+Direct canvas URLs are useful for screenshots:
+
+```text
+http://localhost:6006/iframe.html?viewMode=story&id=<story-id>
+```
+
+If port `6006` is busy, use the alternate port Storybook prints and report that exact URL in the handoff.
+
+The global preview wraps stories with:
+
+- `SnackbarProviderDecorator`
+- `ReactQueryDecorator`
+- `MuiThemeDecorator`
+- `RouterDecorator`
+- `SegmentPluginDecorator`
+
+Use local story decorators when a redesign surface needs a different provider. Existing examples use:
+
+- `RedesignMuiThemeDecorator` from `src/appV2/.storybook/decorators/ShiftDiscoveryMuiTheme` for redesign UI.
+- `MockWorkerDecorator` for stories that need worker query data.
+- `CustomRouteDecorator` for route-dependent components.
+- `GoogleMapsDecorator` for Google Places autocomplete behavior.
+- `KnockGuideProviderDecorator` for Knock guides.
+
+## Mobile Screen Sizes
+
+The Storybook preview already defines these useful screen sizes:
+
+- `iPhoneSE`: `375x667`
+- `iPhone12`: `390x844`
+- `pixel6`: `412x915`
+- `iPadMini`: `768x1024`
+- `smallScreen`: `420x300`
+
+Default visual inspection should include the default `iPhone12`, the smallest relevant phone viewport, and `iPadMini` when layout may stretch.
+
+## Story Requirements
+
+Prefer stories that render the real mobile shell or bottom-sheet/card/list composition with realistic fixture data. Good local patterns include:
+
+- `src/appV2/Connectivity/OfflineIndicator.stories.tsx`
+- `src/appV2/PostShiftReview/PostShiftReviewFlowContent.stories.tsx`
+- `src/appV2/redesign/stories/**`
+- `src/appV2/redesign/Placements/components/PlacementCard/PlacementCardV2.stories.tsx`
+- `src/appV2/redesign/EmergencyCredits/components/CreditProgressBar.stories.tsx`
+
+Temporary design checkpoint stories may render the full proposed UI before app wiring. Use them to iterate, capture screenshots, and get user sign-off. After integration, delete them unless they have become useful permanent generic/component/state stories.
+
+When a story maps to a Figma node, attach the design reference in Storybook:
+
+```typescript
+parameters: {
+  design: {
+    type: "figma",
+    url: "https://www.figma.com/design/...",
+  },
+}
+```
+
+For mobile redesign work, verify:
+
+- Bottom sheets, dialogs, sticky footers, safe-area spacing, and keyboard overlap.
+- Long workplace names, worker names, addresses, rates, dates, and translated-copy expansion.
+- Loading, empty, offline, retry, permission-denied, disabled, and submitted states.
+- Tap target size, focus order, scroll boundaries, and hidden overflow.
+- Whether a component should be mobile-specific or shared content inside a mobile shell.
+- If animation is part of the UI, provide a story control to replay it or render the in-flight state. `CreditProgressBar.stories.tsx` is a good local pattern.
+
+Avoid live network/auth dependencies in stories. Mock query data or pass fixture props at the story boundary.
+
+Mobile redesign lint/style constraints to preserve:
+
+- Use design-system or MUI components instead of raw `div` and `span` in redesign code.
+- Avoid raw hex colors; use theme variables.
+- Use `getStoryBackgrounds()` when a story needs the standard light/dark background set.
+- Keep mobile app verification in Storybook for visual work. Capacitor-only behavior, native permissions, push, deep links, and true device APIs are post-verification concerns.
+
+## Out of Scope
+
+Do not use this skill to solve full workflow E2E coverage, product-environment setup, or Capacitor device behavior. Those belong to the later post-verification layer after the Storybook visual surface has been reviewed.
+
+Report separately:
+
+- Storybook visual evidence.
+- Any device capability gap, such as camera, location access, push, deep links, or Capacitor-only behavior.

package/skills/frontend-ui-verification/references/tooling.md

@@ -0,0 +1,128 @@
+# Verification Tooling Notes
+
+Use this reference when the task depends on external design/project sources or shared agent workflows.
+
+## Source References
+
+- **Figma**: Use the Figma MCP/plugin when available. For Figma URLs, explicitly fetch screenshot plus structured design context before implementation. Prefer `get_design_context`, `get_screenshot`, `get_metadata`, `get_variable_defs`, `search_design_system`, and Code Connect results over visual guessing. If the MCP is unavailable or the link is blocked by login/permissions, ask for a Figma screenshot/export or link-specific notes before claiming exact fidelity.
+- **Notion**: Use Notion MCP for project docs, design process notes, and rollout context. Summarize only the UI requirements that affect the implementation or verification plan.
+- **Linear**: Use Linear MCP for project and ticket traceability. Keep tracking minimal: one project and only the few tickets needed to map back to source work.
+- **Screenshots**: Treat screenshots as design evidence, but call out missing dimensions, states, or interaction details when they are not visible.
+- **Written ideas**: Treat the user's text as product intent, not a complete visual spec. Search existing Clipboard components and stories first, compose the closest pattern, and create a Storybook checkpoint for human confirmation when the idea leaves room for visual interpretation.
+- **No reference**: Do not invent a new visual language. Derive from nearby feature patterns, shared design-system components, and existing Storybook stories, then verify the proposed UI in Storybook before product integration.
+
+## Figma Workflow
+
+When a Figma URL is present:
+
+1. Use the installed Figma skill/plugin or MCP first. If the environment exposes a named Figma or design tool, use that before coding from memory.
+2. Parse the URL before calling tools:
+   - For `figma.com/design/:fileKey/...?...node-id=1-2`, use the `/design/` segment as `fileKey` and convert `node-id` hyphens to colons, such as `1-2` to `1:2`, when the tool schema expects a node ID.
+   - For branch links, use the branch file key when the Figma server requires it.
+   - For desktop selection-based flows, follow the local Figma server's parameter requirements; the file key may be implicit.
+3. If the agent does not automatically choose the right Figma tool, request it by name:
+   - `get_design_context` for structured design context.
+   - `get_screenshot` for visual fidelity.
+   - `get_variable_defs` for variables, styles, colors, spacing, and typography.
+   - `get_metadata` to map pages/layers or recover from large-context designs.
+   - `search_design_system` when looking for reusable components, variables, or styles.
+   - `get_code_connect_map` or Code Connect mappings when the design system has mappings to repo components.
+   - `get_libraries` when the remote Figma MCP exposes library metadata and the task needs design-system source discovery.
+4. Treat Figma MCP output as design context, not production-ready code. Translate it into the repo's components, theme tokens, Storybook patterns, and TypeScript rules.
+5. Fetch screenshot, metadata, design context, variables/tokens, and design-system matches for the target node. If `get_design_context` is too large or truncated, call `get_metadata`, select smaller child nodes, and re-run `get_design_context` on the relevant subtree.
+6. Map Figma components to repo components before coding. If Code Connect mappings exist, use them; otherwise search the repo and Storybook for closest components.
+7. Implement the smallest isolated Storybook surface that can be compared to the Figma screenshot.
+8. If the repo supports `@storybook/addon-designs`, attach the Figma URL with `parameters.design` in the story when the story is expected to remain useful.
+9. Capture a Storybook screenshot at the matching viewport and compare layout, spacing, typography, color, border radius, iconography, density, and state text.
+10. If the Figma URL returns a login screen, permission error, network error, or non-design page, fall back to a provided screenshot/export. If no visual export is available, proceed as a written idea/no-reference task and label exact Figma fidelity as unverified.
+11. Ask the human to confirm when the match depends on taste, when a design token is missing, or when the Figma node appears stale compared with current code.
+
+## Browser Verification
+
+Use the repo's native Storybook server first. Then use whichever browser-controlled surface is available in the current agent: Browser plugin, Chrome, Playwright CLI/script, Playwright MCP, or the agent's built-in browser automation.
+
+For CLI agents, manage Storybook as a background process with explicit cleanup. A foreground dev server can block the agent before it captures screenshots, deletes temporary stories, or reports results.
+
+```bash
+storybook_command="$(bash scripts/inspect-ui-verification-surface.sh storybook-command)"
+storybook_log="${TMPDIR:-/tmp}/frontend-ui-verification-storybook.log"
+
+bash -lc "$storybook_command" >"$storybook_log" 2>&1 &
+storybook_pid="$!"
+
+# Run browser verification here, then always stop the server.
+kill "$storybook_pid" 2>/dev/null || true
+wait "$storybook_pid" 2>/dev/null || true
+```
+
+Prefer the helper for deterministic commands and URLs:
+
+```bash
+bash scripts/inspect-ui-verification-surface.sh storybook-command
+bash scripts/inspect-ui-verification-surface.sh storybook-build-command
+bash scripts/inspect-ui-verification-surface.sh storybook-test-command
+bash scripts/inspect-ui-verification-surface.sh component-test-command
+bash scripts/inspect-ui-verification-surface.sh storybook-url <story-id>
+bash scripts/inspect-ui-verification-surface.sh storybook-iframe-url <story-id>
+```
+
+Access ladder:
+
+1. Start Storybook with the exact command returned by `storybook-command`, then open the story URL returned by `storybook-url <story-id>`.
+2. If the Storybook shell interferes with inspection, open the canvas URL returned by `storybook-iframe-url <story-id>`.
+3. If no browser plugin is available, use Playwright to navigate to the Storybook URL, set the viewport, wait for the story root, collect console errors, and capture a screenshot.
+4. Classify console output as story-introduced, provider/decorator gaps, or pre-existing/global Storybook warnings. Fix story-introduced rendering errors before claiming the story is verified.
+5. If the helper returns a native Storybook test/a11y command, use it for isolated accessibility or interaction checks after the story renders.
+6. If the helper returns a native component browser-test command, use it only for focused component-level checks that can mount with stable providers and mocks.
+7. If the dev server fails, run the exact command returned by `storybook-build-command` and inspect the built Storybook when practical.
+8. If provider/context errors block rendering, add story decorators, fixture props, or local mocks. Do not switch to full product integration just to see the UI.
+9. Stop only with a concrete blocker: command run, URL attempted, error observed, and why no screenshot could be captured.
+
+## Component-Level Browser Checks
+
+Only use component-level Playwright or Storybook test-runner checks when the repo already exposes a script. Keep the test surface isolated and product-agnostic:
+
+- Mount the smallest parent that owns the visual state instead of a deeply prop-driven child.
+- Wrap only the providers the component actually reads: router, query client, theme, feature flags, or local context.
+- Mock API data at the test/story boundary. Derive response shape from fixture/HAR/type usage; do not guess unknown response fields.
+- For interactive components, encode pre-actions: click the drawer/menu trigger, select a tab, type into the invalid field, or advance the animation before capturing.
+- Test desktop and mobile sizes when the component has responsive behavior.
+- Assert at least one visible value or accessible control before taking a screenshot, so an empty render cannot pass as a visual baseline.
+- Use short timeouts on the first iteration to expose missing providers or mocks quickly; remove the override once the surface is stable.
+
+For visual claims, capture or report:
+
+- Storybook URL or story ID.
+- Viewport size.
+- State being inspected.
+- Console errors or missing assets.
+- Screenshot path or a short screenshot summary.
+
+For motion claims, also capture or report:
+
+- The trigger used to start the motion.
+- Whether the story can replay the motion deterministically.
+- In-flight and settled visual states.
+- Any reduced-motion behavior or gap.
+
+## Agent Handoff Contract
+
+When one agent prepares work for another, include:
+
+- Repo, branch, and changed files.
+- Source references used: Figma, Notion, Linear, screenshot, or code path.
+- Exact Storybook story to open.
+- Commands already run and their outcome.
+- Remaining subjective design choices that need human confirmation.
+
+Do not rely on agent-specific memory. Put durable instructions in the repo-owned skill, story, test, or ticket.
+
+## Temporary Storybook Checkpoints
+
+Temporary stories are acceptable for design confirmation when:
+
+- The UI needs human visual approval before backend/auth/routing work.
+- The real route is blocked by credentials, flags, data, or environment setup.
+- Multiple agents need a stable isolated surface to inspect.
+
+Before merge, remove the temporary story or convert it into a permanent story with realistic fixtures and useful states.

package/skills/frontend-ui-verification/scripts/inspect-ui-verification-surface.sh

@@ -0,0 +1,274 @@
+#!/usr/bin/env bash
+# cspell:ignore dockerless
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  inspect-ui-verification-surface.sh inspect
+  inspect-ui-verification-surface.sh storybook-command
+  inspect-ui-verification-surface.sh storybook-build-command
+  inspect-ui-verification-surface.sh storybook-test-command
+  inspect-ui-verification-surface.sh component-test-command
+  inspect-ui-verification-surface.sh storybook-url <story-id>
+  inspect-ui-verification-surface.sh storybook-iframe-url <story-id>
+  inspect-ui-verification-surface.sh figma-story-files
+
+Environment:
+  STORYBOOK_PORT  Storybook port to use for URL commands. Defaults to 6006.
+EOF
+}
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+  repo_root="$(git rev-parse --show-toplevel)"
+else
+  repo_root="$PWD"
+fi
+
+cd "$repo_root"
+
+command="${1:-inspect}"
+storybook_port="${STORYBOOK_PORT:-6006}"
+
+script_from_package_json() {
+  node -e '
+const fs = require("fs");
+const names = process.argv.slice(1);
+if (!fs.existsSync("package.json")) process.exit(1);
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+const scripts = pkg.scripts || {};
+for (const name of names) {
+  if (scripts[name]) {
+    console.log(`npm run ${name}`);
+    process.exit(0);
+  }
+}
+process.exit(1);
+' "$@"
+}
+
+storybook_script() {
+  node -e '
+const fs = require("fs");
+if (!fs.existsSync("package.json")) process.exit(1);
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+const scripts = pkg.scripts || {};
+if (!scripts.storybook) process.exit(1);
+console.log("npm run storybook");
+'
+}
+
+storybook_build_script() {
+  script_from_package_json "build-storybook" "storybook:build"
+}
+
+storybook_test_script() {
+  script_from_package_json "test-storybook" "storybook:test" "test:storybook" "test:a11y" "a11y"
+}
+
+component_test_script() {
+  script_from_package_json \
+    "test:playwright:ct-dockerless" \
+    "test:playwright:ct" \
+    "test:playwright:ct-update-screenshots" \
+    "test:ct" \
+    "test:ct:local" \
+    "ct:local"
+}
+
+figma_story_files() {
+  files="$(
+    for root in src/appV2/redesign src/appV2 src components app; do
+      if [ -d "$root" ]; then
+        find "$root" -name "*.stories.tsx" -o -name "*.stories.ts" -o -name "*.stories.mdx"
+      fi
+    done | sort -u
+  )"
+
+  if [ -z "$files" ]; then
+    return 0
+  fi
+
+  printf "%s\n" "$files" | while IFS= read -r file; do
+    if grep -Eq 'figma\.com|design:[[:space:]]*\{' "$file"; then
+      printf "%s\n" "$file"
+    fi
+  done | head -n 80
+}
+
+case "$command" in
+  inspect)
+    ;;
+  storybook-command)
+    storybook_script
+    exit 0
+    ;;
+  storybook-build-command)
+    storybook_build_script
+    exit 0
+    ;;
+  storybook-test-command)
+    storybook_test_script
+    exit 0
+    ;;
+  component-test-command)
+    component_test_script
+    exit 0
+    ;;
+  storybook-url)
+    if [ "${2:-}" = "" ]; then
+      echo "Missing story id." >&2
+      usage >&2
+      exit 2
+    fi
+    printf "http://localhost:%s/?path=/story/%s\n" "$storybook_port" "$2"
+    exit 0
+    ;;
+  storybook-iframe-url)
+    if [ "${2:-}" = "" ]; then
+      echo "Missing story id." >&2
+      usage >&2
+      exit 2
+    fi
+    printf "http://localhost:%s/iframe.html?viewMode=story&id=%s\n" "$storybook_port" "$2"
+    exit 0
+    ;;
+  figma-story-files)
+    figma_story_files
+    exit 0
+    ;;
+  --help|-h|help)
+    usage
+    exit 0
+    ;;
+  *)
+    echo "Unknown command: $command" >&2
+    usage >&2
+    exit 2
+    ;;
+esac
+
+echo "Repository: $repo_root"
+
+if [ -f package.json ]; then
+  echo
+  echo "Relevant package scripts:"
+  node -e '
+const fs = require("fs");
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+const scripts = pkg.scripts || {};
+for (const name of [
+  "storybook",
+  "build-storybook",
+  "storybook:build",
+  "test-storybook",
+  "storybook:test",
+  "test:storybook",
+  "test:a11y",
+  "a11y",
+  "test:playwright:ct-dockerless",
+  "test:playwright:ct",
+  "test:playwright:ct-update-screenshots",
+  "test:ct",
+  "test:ct:local",
+  "ct:local",
+  "test:v2",
+  "lint",
+  "lint:v2",
+  "typecheck",
+  "typecheck:v2",
+]) {
+  if (scripts[name]) console.log(`- ${name}: ${scripts[name]}`);
+}
+'
+fi
+
+echo
+echo "Deterministic Storybook commands:"
+if storybook_command="$(storybook_script 2>/dev/null)"; then
+  echo "- Start: $storybook_command"
+  echo "- Default URL: http://localhost:${storybook_port}/"
+else
+  echo "- Start: no storybook script detected"
+fi
+if storybook_build_command="$(storybook_build_script 2>/dev/null)"; then
+  echo "- Build: $storybook_build_command"
+else
+  echo "- Build: no Storybook build script detected"
+fi
+if storybook_test_command="$(storybook_test_script 2>/dev/null)"; then
+  echo "- Storybook test/a11y: $storybook_test_command"
+else
+  echo "- Storybook test/a11y: no native script detected"
+fi
+if component_test_command="$(component_test_script 2>/dev/null)"; then
+  echo "- Component browser test: $component_test_command"
+else
+  echo "- Component browser test: no native script detected"
+fi
+echo "- Story URL: $0 storybook-url <story-id>"
+echo "- Canvas URL: $0 storybook-iframe-url <story-id>"
+
+echo
+echo "Changed UI-related files:"
+changed_files="$(
+  {
+    git diff --name-only HEAD -- 2>/dev/null || true
+    git ls-files --others --exclude-standard 2>/dev/null || true
+  } | sort -u
+)"
+if [ -n "$changed_files" ]; then
+  ui_files="$(printf "%s\n" "$changed_files" | grep -E '(\.tsx?$|\.stories\.(tsx?|jsx?)$|\.mdx$|\.css$|\.scss$)' || true)"
+  if [ -n "$ui_files" ]; then
+    printf "%s\n" "$ui_files" | sed "s#^#- #"
+  else
+    echo "- No changed UI files detected."
+  fi
+else
+  echo "- No tracked changes relative to HEAD."
+fi
+
+echo
+echo "Storybook files near common Clipboard frontend roots:"
+story_files="$(
+  for root in src/appV2/redesign src components app; do
+    if [ -d "$root" ]; then
+      find "$root" -name "*.stories.tsx" -o -name "*.stories.ts" -o -name "*.stories.mdx"
+    fi
+  done | sort -u | head -n 80
+)"
+if [ -n "$story_files" ]; then
+  printf "%s\n" "$story_files" | sed "s#^#- #"
+else
+  echo "- No Storybook files found in common roots."
+fi
+
+echo
+echo "Figma tooling hints:"
+if [ -f ".storybook/main.ts" ] && grep -q "@storybook/addon-designs" ".storybook/main.ts"; then
+  echo "- Storybook addon-designs detected in .storybook/main.ts"
+fi
+echo "- When a Figma URL exists, fetch screenshot and design context before coding."
+echo "- Figma story files: $0 figma-story-files"
+
+figma_files="$(figma_story_files)"
+if [ -n "$figma_files" ]; then
+  echo
+  echo "Story files with Figma/design references:"
+  printf "%s\n" "$figma_files" | sed "s#^#- #"
+fi
+
+echo
+echo "Suggested verification ladder:"
+if storybook_command="$(storybook_script 2>/dev/null)"; then
+  echo "1. Run: $storybook_command"
+  echo "2. Open the changed story at http://localhost:${storybook_port}/"
+  echo "3. If the Storybook shell is noisy, open the iframe canvas URL."
+  echo "4. Use Browser, Chrome, or Playwright to capture mobile and desktop screenshots."
+  echo "5. If native storybook/component test commands are detected, use them for isolated interaction or a11y checks."
+  echo "6. If rendering fails, fix story decorators/fixtures before product integration."
+else
+  echo "1. No storybook script detected. Use the repo's documented visual preview surface."
+  echo "2. Use Browser, Chrome, or Playwright to capture screenshots from that surface."
+  echo "3. If rendering fails, fix isolated fixtures/providers before product integration."
+fi