@mr.dj2u/knowledge 0.1.6 → 0.1.8

package/dist/content/checklists/push-merge-loop.md

@@ -1,17 +1,17 @@
-# Push-Merge Loop Checklist
-
-Use this checklist when running the PR loop into `test`.
-
-1. Doctor CI pass: `mds doctor --ci`.
-2. Stage intentional files only.
-3. Create meaningful commit message.
-4. Push branch.
-5. Open/update PR to `test`.
-6. Wait ~2 minutes before polling checks/comments.
-7. Collect failed checks + review comments.
-8. Fix issues locally.
-9. Rerun Doctor CI.
-10. Push and poll again.
-11. Repeat up to 5 cycles.
-12. Merge only when checks are green and blockers are cleared.
-
+# Push-Merge Loop Checklist
+
+Use this checklist when running the PR loop into `test`.
+
+1. Doctor CI pass: `mds doctor --ci`.
+2. Stage intentional files only.
+3. Create meaningful commit message.
+4. Push branch.
+5. Open/update PR to `test`.
+6. Wait ~2 minutes before polling checks/comments.
+7. Collect failed checks + review comments.
+8. Fix issues locally.
+9. Rerun Doctor CI.
+10. Push and poll again.
+11. Repeat up to 5 cycles.
+12. Merge only when checks are green and blockers are cleared.
+

package/dist/content/checklists/unified-agent-bundle-validation.md

@@ -1,9 +1,9 @@
-# Unified Agent Bundle Validation Checklist
-
-Phase 9 validation artifact intent:
-
-1. Run Doctor (`--ci`) through the agent.
-2. Fetch one guide via MCP resource (`animation-performance`).
-3. Execute one CLI workflow (`mds continue` or `/push-merge-loop`).
-4. Confirm tools/resources are visible in the target client.
-
+# Unified Agent Bundle Validation Checklist
+
+Phase 9 validation artifact intent:
+
+1. Run Doctor (`--ci`) through the agent.
+2. Fetch one guide via MCP resource (`animation-performance`).
+3. Execute one CLI workflow (`mds continue` or `/push-merge-loop`).
+4. Confirm tools/resources are visible in the target client.
+

package/dist/content/examples/push-merge-loop.md

@@ -1,14 +1,14 @@
-# Push-Merge Loop Example
-
-Example iteration log for `/push-merge-loop`:
-
-- Iteration 1:
-  - Failed: `lint` and one requested review change.
-  - Fixes: remove dead import, update API guard clause.
-  - Result: `lint` green, one test still failing.
-- Iteration 2:
-  - Failed: `test` in `packages/cli`.
-  - Fixes: update stale skill ID expectation.
-  - Result: all checks green.
-- Merge: PR merged into `test`.
-
+# Push-Merge Loop Example
+
+Example iteration log for `/push-merge-loop`:
+
+- Iteration 1:
+  - Failed: `lint` and one requested review change.
+  - Fixes: remove dead import, update API guard clause.
+  - Result: `lint` green, one test still failing.
+- Iteration 2:
+  - Failed: `test` in `packages/cli`.
+  - Fixes: update stale skill ID expectation.
+  - Result: all checks green.
+- Merge: PR merged into `test`.
+

package/dist/content/examples/unified-agent-bundle-bootstrap.md

@@ -1,8 +1,8 @@
-# Unified Agent Bundle Bootstrap Example
-
-Phase 9 bootstrap artifact intent:
-
-1. Install MCP server config.
-2. Install generated skills/prompts package.
-3. Verify the agent can call Doctor + knowledge tools.
-4. Verify the agent can run one CLI workflow.
+# Unified Agent Bundle Bootstrap Example
+
+Phase 9 bootstrap artifact intent:
+
+1. Install MCP server config.
+2. Install generated skills/prompts package.
+3. Verify the agent can call Doctor + knowledge tools.
+4. Verify the agent can run one CLI workflow.

package/dist/content/guides/animation-performance.md

@@ -19,12 +19,42 @@ https://expo.dev/blog/the-real-cost-of-react-native-animations-benchmarking-ever
   complex UI-thread coordination.
 - Animated view count is a budget. A single animated card is different from 100
   animated rows.
+- Treat parallax as its own motion class, not just "fancier Reanimated". Use it
+  when scroll depth supports a story: hero scenes, layered landing sections,
+  pinned product reveals, or depth cues that help orientation.
+- Keep parallax light when possible. A few clearly separated layers usually read
+  better than many tiny offsets that all compete for attention.
+- Scroll-linked scenes should simplify as they get denser:
+  - Native mobile hero/marketing sections can afford a handful of animated
+    layers when the screen is focused on that scene.
+  - Dense content screens and long lists should prefer simpler fades,
+    translations, or sticky section behavior over many interpolated layers.
+  - Web should degrade earlier than native when the effect depends on frequent
+    scroll interpolation across large sections.
+- Large layered motion should have explicit budget notes nearby when it is
+  intentional: what is animating, why parallax is worth it, and how it should
+  simplify if performance drops.
+
+## Parallax Budget Rules
+
+- Prefer roughly 3-5 meaningful animated depth layers per scene before adding
+  more complexity.
+- Be cautious once a single file stacks many `interpolate()` calls, multiple
+  `useAnimatedStyle()` blocks, or repeated scroll-linked rows.
+- Do not combine heavy parallax, repeated list item motion, and broad layout
+  transitions in the same screen unless you have measured the release build and
+  confirmed it holds up.
+- If web shares the same component tree, provide a simpler fallback when the
+  full depth effect is not essential to comprehension.
 
 ## Doctor And Onboarding Rules
 
 - Warn when route or list files animate many repeated items without an explicit
   performance note.
+- Warn when parallax or scroll-linked scenes pile on many interpolation layers
+  without a nearby motion/performance note.
 - Warn when benchmark claims are based only on debug builds.
 - Ask during onboarding whether the app has long-running, list-heavy, or
   gesture-heavy animation requirements.
-
+- Ask whether hero sections or landing pages need parallax, pinned scenes, or
+  layered depth effects so the implementation path is chosen intentionally.

package/dist/content/guides/post-create-onboarding.md

@@ -1,49 +1,49 @@
-# Post-Create Expo Onboarding
-
-MDS onboarding runs after `rn-new`, `create-expo-app`, `create-expo-stack`, or
-another generator has created an Expo project. `create-expo-super-stack` wraps
-that same idea by running `create-expo-stack` first and then applying the MDS
-onboarding pass.
-
-## Flow
-
-1. Detect package manager, Expo SDK, Expo Router, app directory, aliases, and
-   styling stack.
-2. Explain project memory first, then ask what the app is for, who it serves,
-   primary flows, data needs, and release/deployment intent.
-3. Use friendly Clack prompts with visible defaults, helpful explanations, and
-   no blank required answers.
-4. Derive defaults from selected answers instead of asking for comma-separated
-   internal keywords.
-5. Offer rich boilerplate by default: project memory docs, exposition pages,
-   Uniwind repair for existing apps, Software Mansion core examples, Supabase or
-   local data guidance, MCP/Codex/Claude instructions, and CI/release safeguards.
-6. Scaffold only selected pieces.
-7. Add generated cleanup scripts such as `clear-expo-start` and `free-port`.
-8. Install added dependencies, run `expo install --fix`, install known missing
-   Expo peers such as `expo-font` for `@expo/vector-icons`, then run Doctor.
-
-## Agentic Onboarding (MCP)
-
-The terminal `mds onboard` command writes the project memory files. The
-agentic version is a conversation with Copilot, Claude Code, Codex, or Cursor that
-fills those files in collaboratively.
-
-Install **once, globally** (user scope, default) so every workspace gets
-the prompts:
-
-```bash
-mds mcp install --client claude   # merges into ~/.claude.json
-mds mcp install --client codex    # merges into ~/.codex/config.toml
-mds mcp install --client cursor   # merges into ~/.cursor/mcp.json
-mds mcp install --dry-run         # preview merge before writing
-```
-
-Restart the host (or run `claude mcp reload`) and the MDS prompts are
-available from any workspace.
-
-Two prompts and several callable MDS MCP tools ship with the server:
-
+# Post-Create Expo Onboarding
+
+MDS onboarding runs after `rn-new`, `create-expo-app`, `create-expo-stack`, or
+another generator has created an Expo project. `create-expo-super-stack` wraps
+that same idea by running `create-expo-stack` first and then applying the MDS
+onboarding pass.
+
+## Flow
+
+1. Detect package manager, Expo SDK, Expo Router, app directory, aliases, and
+   styling stack.
+2. Explain project memory first, then ask what the app is for, who it serves,
+   primary flows, data needs, and release/deployment intent.
+3. Use friendly Clack prompts with visible defaults, helpful explanations, and
+   no blank required answers.
+4. Derive defaults from selected answers instead of asking for comma-separated
+   internal keywords.
+5. Offer rich boilerplate by default: project memory docs, exposition pages,
+   Uniwind repair for existing apps, Software Mansion core examples, Supabase or
+   local data guidance, MCP/Codex/Claude instructions, and CI/release safeguards.
+6. Scaffold only selected pieces.
+7. Add generated cleanup scripts such as `clear-expo-start` and `free-port`.
+8. Install added dependencies, run `expo install --fix`, install known missing
+   Expo peers such as `expo-font` for `@expo/vector-icons`, then run Doctor.
+
+## Agentic Onboarding (MCP)
+
+The terminal `mds onboard` command writes the project memory files. The
+agentic version is a conversation with Copilot, Claude Code, Codex, or Cursor that
+fills those files in collaboratively.
+
+Install **once, globally** (user scope, default) so every workspace gets
+the prompts:
+
+```bash
+mds mcp install --client claude   # merges into ~/.claude.json
+mds mcp install --client codex    # merges into ~/.codex/config.toml
+mds mcp install --client cursor   # merges into ~/.cursor/mcp.json
+mds mcp install --dry-run         # preview merge before writing
+```
+
+Restart the host (or run `claude mcp reload`) and the MDS prompts are
+available from any workspace.
+
+Two prompts and several callable MDS MCP tools ship with the server:
+
 - `create_expo_super_stack` — invoke from a **parent folder** (e.g.
   `F:\ReactNativeApps`) when the app folder does not exist yet. This is
   now a thin orchestration prompt: `mds_runtime_versions` checks for
@@ -52,27 +52,27 @@ Two prompts and several callable MDS MCP tools ship with the server:
   `create_expo_super_stack_intake_step` is only the manual fallback for
   missing or ambiguous answers, and generation happens through
   `create_expo_super_stack_generate`.
-- `onboard_new_expo_app` — invoke from **inside an existing Expo app
-  folder** (a freshly generated one or a year-old project). Runs the
-  intake → normalize → plan → scaffold flow.
-
-After generation, the user-dev should open the generated app folder
-directly in a new agent session and run `mds continue`. That fresh
-app-root session reduces token usage and saves money because future
-searches, reads, and plans are scoped to the app instead of the parent
-folder and old generator conversation.
-
-Both prompts enforce or surface a **TodoForContext blocker** before
-implementation work: they scan every `project/` file for the literal
-marker `# TodoForContext(optional):` and ask the user to fill it in or
-delete the marker line.
-
-`mds doctor` mirrors this rule with a `todo-for-context markers`
-error so the same blocker stops CI and editor surfaces until the user
-fills the section or deletes the marker line.
-
-### What's new in the agentic prompts and tools
-
+- `onboard_new_expo_app` — invoke from **inside an existing Expo app
+  folder** (a freshly generated one or a year-old project). Runs the
+  intake → normalize → plan → scaffold flow.
+
+After generation, the user-dev should open the generated app folder
+directly in a new agent session and run `mds continue`. That fresh
+app-root session reduces token usage and saves money because future
+searches, reads, and plans are scoped to the app instead of the parent
+folder and old generator conversation.
+
+Both prompts enforce or surface a **TodoForContext blocker** before
+implementation work: they scan every `project/` file for the literal
+marker `# TodoForContext(optional):` and ask the user to fill it in or
+delete the marker line.
+
+`mds doctor` mirrors this rule with a `todo-for-context markers`
+error so the same blocker stops CI and editor surfaces until the user
+fills the section or deletes the marker line.
+
+### What's new in the agentic prompts and tools
+
 - **PHASE 0 file intake.** The agent offers to digest an existing
   `project/info.md` and `project/style.md` if the user has them already.
   Questions whose answers are unambiguous in the file are skipped; the
@@ -84,80 +84,80 @@ fills the section or deletes the marker line.
   merges explicit overrides, returns missing or ambiguous fields, and
   produces a ready-to-pass generate payload so the user is not forced
   through redundant question-by-question discovery.
-- **Android TV alongside Apple TV.** The platform multi-select now
-  includes Android TV. Android TV builds from the same Android target
-  with leanback config in `app.json`; Apple TV is a separate tvOS build
-  target via `react-native-tvos`. Selecting either records the intent
-  in project memory.
-- **Shared CLI-backed intake contract.** The agentic CESS flow now uses
-  callable MCP tools backed by the shared `@mr.dj2u/cli` intake
-  contract. That keeps the questionnaire, defaults, dependency rules,
-  and flag mapping aligned with the published CLI behavior.
-- **No silent defaults.** Guided intake must explicitly collect answers
-  or explicitly present visible defaults. If the CESS intake tools are
-  unavailable, the agent should stop and tell the user to refresh the
-  plugin or MCP install instead of inventing `--mds-yes` defaults.
+- **Android TV alongside Apple TV.** The platform multi-select now
+  includes Android TV. Android TV builds from the same Android target
+  with leanback config in `app.json`; Apple TV is a separate tvOS build
+  target via `react-native-tvos`. Selecting either records the intent
+  in project memory.
+- **Shared CLI-backed intake contract.** The agentic CESS flow now uses
+  callable MCP tools backed by the shared `@mr.dj2u/cli` intake
+  contract. That keeps the questionnaire, defaults, dependency rules,
+  and flag mapping aligned with the published CLI behavior.
+- **No silent defaults.** Guided intake must explicitly collect answers
+  or explicitly present visible defaults. If the CESS intake tools are
+  unavailable, the agent should stop and tell the user to refresh the
+  plugin or MCP install instead of inventing `--mds-yes` defaults.
 - **Runtime version diagnostics.** `mds_runtime_versions` reports the
   active MCP server version, CLI version, concrete installed
   `create-expo-super-stack` version, and the published generation path
   in use.
-- **Credits while waiting.** When generation kicks off, the agent
-  prints a recognition note for the upstream teams and individuals
-  whose work fills the MDS knowledge base.
-- **Success message surfaced.** After a successful run, the agent
-  quotes the generator's `MDS onboarding complete` tail block back
-  verbatim so the Mr. DJ personal thank-you text appears in chat the same way
-  it does in a terminal CLI run.
-- **MDS Continue handoff.** The agent runs `mds continue` from the
-  generated app folder, then tells the user-dev to open that app folder
-  in a fresh agent session to lower token usage and cost.
-
-## Defaults
-
-- Prefer Uniwind and Tailwind v4 for new projects.
-- Keep route files thin and move business logic into features, services, hooks,
-  and utilities.
-- Always add `project/info.md`, `project/todo.md`, `project/style.md`, and
-  `project/guidelines.md` when project memory is selected.
-- Normalize existing `project/info.md` and `project/style.md` into canonical
-  sections while preserving unknown content under Imported Notes.
-- Add `project/intake-agent.md` when context is thin or imported notes need a
-  follow-up agent conversation.
-- Keep `project/style.md` visual-only; put technical and agent rules in
-  `project/guidelines.md`.
-- Treat monorepo-aware scaffolding as a future step after the single-app MVP is
-  stable.
-
-## VS Code & GitHub Copilot Integration
-
-This guide is authored as canonical knowledge consumed by agent bundles; it is not the agent itself. To enable the generated Copilot/VS Code surface and the custom MDS agent in a workspace, regenerate the VS Code bundle and install the generated prompts/settings into the target repository or your user profile.
-
-- Regenerate VS Code assets (from repository root):
-
-```powershell
-pnpm --filter @mr.dj2u/knowledge build:vscode
-```
-
-- Copy the generated workspace assets into your project (PowerShell):
-
-```powershell
-Copy-Item -Path .\plugins\vscode-copilot\.github\* -Destination . -Recurse -Force
-Copy-Item -Path .\plugins\vscode-copilot\.vscode\* -Destination .\.vscode -Recurse -Force
-```
-
-- Then restart VS Code. Ensure the `GitHub Copilot Chat` extension is installed and enabled. The generated `.vscode/settings.json` enables agent skill locations and prompt file lookup under `.github/prompts`.
-
-- If you prefer user-scope installs, copy the `user/.copilot` content into your user profile per the extension docs, or run `mds agent install --client codex --scope user` (if available) to automate the merge.
-
-## Install Path & What This MD Is For
-
-- This markdown is a human- and agent-facing guide. It documents the onboarding flow and explains what the agent prompts do. It is used as input to the `packages/knowledge` build which generates plugin/agent bundles for Codex, Claude Code, and VS Code Copilot.
-- The agent itself is not this file — it is a runtime that loads generated prompts/skills from the plugin bundles or the MCP server. To activate the agent surfaces you must either:
-  - Install the MCP prompts via `mds mcp install --client <client>` (user or project scope), or
-  - Copy the generated plugin files from `plugins/vscode-copilot` / `plugins/codex` / `plugins/claude-code` into the target workspace or user profile and restart the corresponding client.
-- If a host keeps using stale prompt or plugin behavior after republish,
-  refresh the local plugin cache, reinstall the MDS MCP server, and run
-  `mds_runtime_versions` from the host surface to confirm which version
-  is actually active.
-
-If you want, I can: regenerate the VS Code bundle now, copy the assets into the current workspace, and verify Copilot sees the prompts. Say "Do it" and I'll run the build and copy steps for you.
+- **Credits while waiting.** When generation kicks off, the agent
+  prints a recognition note for the upstream teams and individuals
+  whose work fills the MDS knowledge base.
+- **Success message surfaced.** After a successful run, the agent
+  quotes the generator's `MDS onboarding complete` tail block back
+  verbatim so the Mr. DJ personal thank-you text appears in chat the same way
+  it does in a terminal CLI run.
+- **MDS Continue handoff.** The agent runs `mds continue` from the
+  generated app folder, then tells the user-dev to open that app folder
+  in a fresh agent session to lower token usage and cost.
+
+## Defaults
+
+- Prefer Uniwind and Tailwind v4 for new projects.
+- Keep route files thin and move business logic into features, services, hooks,
+  and utilities.
+- Always add `project/info.md`, `project/todo.md`, `project/style.md`, and
+  `project/guidelines.md` when project memory is selected.
+- Normalize existing `project/info.md` and `project/style.md` into canonical
+  sections while preserving unknown content under Imported Notes.
+- Add `project/intake-agent.md` when context is thin or imported notes need a
+  follow-up agent conversation.
+- Keep `project/style.md` visual-only; put technical and agent rules in
+  `project/guidelines.md`.
+- Treat monorepo-aware scaffolding as a future step after the single-app MVP is
+  stable.
+
+## VS Code & GitHub Copilot Integration
+
+This guide is authored as canonical knowledge consumed by agent bundles; it is not the agent itself. To enable the generated Copilot/VS Code surface and the custom MDS agent in a workspace, regenerate the VS Code bundle and install the generated prompts/settings into the target repository or your user profile.
+
+- Regenerate VS Code assets (from repository root):
+
+```powershell
+pnpm --filter @mr.dj2u/knowledge build:vscode
+```
+
+- Copy the generated workspace assets into your project (PowerShell):
+
+```powershell
+Copy-Item -Path .\plugins\vscode-copilot\.github\* -Destination . -Recurse -Force
+Copy-Item -Path .\plugins\vscode-copilot\.vscode\* -Destination .\.vscode -Recurse -Force
+```
+
+- Then restart VS Code. Ensure the `GitHub Copilot Chat` extension is installed and enabled. The generated `.vscode/settings.json` enables agent skill locations and prompt file lookup under `.github/prompts`.
+
+- If you prefer user-scope installs, copy the `user/.copilot` content into your user profile per the extension docs, or run `mds agent install --client codex --scope user` (if available) to automate the merge.
+
+## Install Path & What This MD Is For
+
+- This markdown is a human- and agent-facing guide. It documents the onboarding flow and explains what the agent prompts do. It is used as input to the `packages/knowledge` build which generates plugin/agent bundles for Codex, Claude Code, and VS Code Copilot.
+- The agent itself is not this file — it is a runtime that loads generated prompts/skills from the plugin bundles or the MCP server. To activate the agent surfaces you must either:
+  - Install the MCP prompts via `mds mcp install --client <client>` (user or project scope), or
+  - Copy the generated plugin files from `plugins/vscode-copilot` / `plugins/codex` / `plugins/claude-code` into the target workspace or user profile and restart the corresponding client.
+- If a host keeps using stale prompt or plugin behavior after republish,
+  refresh the local plugin cache, reinstall the MDS MCP server, and run
+  `mds_runtime_versions` from the host surface to confirm which version
+  is actually active.
+
+If you want, I can: regenerate the VS Code bundle now, copy the assets into the current workspace, and verify Copilot sees the prompts. Say "Do it" and I'll run the build and copy steps for you.

package/dist/content/patterns/animation/animation-motion-selection.md

@@ -0,0 +1,155 @@
+# Motion Implementation Selection
+
+## Description
+
+Animation work should start with intent, not library preference. This pattern
+helps choose between simple platform transitions, Reanimated, Lottie, and
+parallax or scroll-linked motion based on what the interface is trying to
+communicate and how much performance budget the screen can afford.
+
+It is seeded from layered landing-page motion in `time2pay` plus the
+multi-layer scroll examples from the Quantum Jam project, where depth is used
+intentionally instead of sprinkling animation across unrelated UI.
+
+## When to Use
+
+**Use this pattern** when:
+
+- The user says an animation feels janky or unsatisfying.
+- A screen mixes several animation styles and needs a cleaner implementation
+  choice.
+- You are deciding whether something should be a fade, a layout transition, a
+  Reanimated interaction, a Lottie asset, or a parallax scene.
+- A landing page or hero section wants layered depth, pinned scenes, or
+  scroll-linked reveals.
+
+## Motion Selection Matrix
+
+### One-shot transition
+
+Use for:
+- Small enter/exit fades
+- Simple banners, cards, and modals
+- Brief route-adjacent transitions with low component count
+
+Prefer:
+- Platform or native transitions
+- Lightweight Reanimated enter/exit helpers only when already in use nearby
+
+Avoid:
+- Rebuilding the whole screen around shared values just to fade a few elements
+
+### Layout transition
+
+Use for:
+- Expanding sections
+- Reordering compact content
+- Small layout shifts that should feel connected
+
+Prefer:
+- Reanimated layout transitions when layout coupling is the main problem
+
+Avoid:
+- Running the same heavy layout animation on long repeated lists
+
+### Gesture-driven motion
+
+Use for:
+- Drag, swipe, sheet, or scroll-coupled controls
+- Motion that depends on continuous user input
+
+Prefer:
+- Reanimated on the UI thread
+
+Avoid:
+- JS-thread animation paths for tight gesture loops
+
+### List-heavy motion
+
+Use for:
+- Large repeated rows
+- Feed item enter/exit motion
+- Repeated cards inside FlatList, FlashList, or mapped collections
+
+Prefer:
+- Simple, consistent motion with a clear budget
+- Native or lightweight paths when the same animation repeats many times
+
+Avoid:
+- Many simultaneous animated rows with custom interpolation logic unless
+  measured and justified
+
+### Loading animation
+
+Use for:
+- Branded loops
+- Focused status moments
+- Empty/loading scenes that benefit from illustration
+
+Prefer:
+- Lottie for self-contained loops
+- Small skeleton or opacity transitions for utilitarian loading states
+
+Avoid:
+- Large always-running animations across dense work screens
+
+### Parallax or scroll-linked motion
+
+Use for:
+- Hero motion on landing pages
+- Layered background depth
+- Pinned scenes and product storytelling
+- Scroll-linked reveals where depth helps orientation or emphasis
+
+Prefer:
+- Reanimated with a small number of meaningful layers
+- Scene-level helpers that isolate interpolation logic
+- Simpler web fallbacks when the full effect is not essential
+
+Avoid:
+- Turning every section into its own parallax rig
+- Dense route files packed with many interpolations and animated rows
+
+## Parallax Section
+
+### Layered background motion
+
+- Use a few strong layers with different depth speeds.
+- Make sure each layer has a visual reason to exist.
+- Keep decorative motion behind core content rather than fighting it.
+
+### Pinned scenes
+
+- Use when a section needs a short storytelling beat during scroll.
+- Keep the pinned duration purposeful; long pinned scenes become work for the
+  user if the content payoff is weak.
+
+### Staggered depth
+
+- Let foreground, midground, and background move at clearly different rates.
+- Favor readable separation over tiny offsets across many elements.
+
+### Budget rules
+
+- Prefer roughly 3-5 layers in a scene before adding more.
+- Be cautious when a single file accumulates many `interpolate()` calls or
+  several `useAnimatedStyle()` blocks.
+- Simplify sooner on web and on dense native screens than on a dedicated mobile
+  hero section.
+- Add a nearby motion/performance note when a heavy scene is intentional.
+
+## Verification Checklist
+
+- Classify each animation before changing its implementation.
+- Verify the release build, not just debug mode.
+- Check web fallback behavior if the scene is shared cross-platform.
+- Confirm repeated rows are not doing the same expensive motion hundreds of
+  times.
+- Confirm parallax scenes still feel readable when motion is reduced or
+  simplified.
+
+## Related Guidance
+
+- `mds://guides/animation-performance`
+- `mds://skills/animation-motion`
+- `mds://skills/debugging`