From 7a76c37ac4d3f031a512995166c0f0f160212827 Mon Sep 17 00:00:00 2001
From: NagyVikt <nagy.viktordp@gmail.com>
Date: Tue, 30 Jun 2026 03:13:35 +0200
Subject: [PATCH] feat(vercel): vendor vercel-labs/agent-skills (9 skills) +
 mirror sync script

Vendored read-only mirror of vercel-labs/agent-skills @ f8a72b9 (MIT).
scripts/sync-vercel-skills.sh re-pulls upstream (zips stripped).
See skills/vercel/UPSTREAM.md for attribution.
---
 scripts/sync-vercel-skills.sh                 |   31 +
 skills/vercel/UPSTREAM.md                     |   12 +
 skills/vercel/composition-patterns/AGENTS.md  |  946 ++++
 skills/vercel/composition-patterns/README.md  |   60 +
 skills/vercel/composition-patterns/SKILL.md   |   89 +
 .../vercel/composition-patterns/metadata.json |   11 +
 .../composition-patterns/rules/_sections.md   |   29 +
 .../composition-patterns/rules/_template.md   |   24 +
 .../rules/architecture-avoid-boolean-props.md |  100 +
 .../rules/architecture-compound-components.md |  112 +
 .../patterns-children-over-render-props.md    |   87 +
 .../rules/patterns-explicit-variants.md       |  100 +
 .../rules/react19-no-forwardref.md            |   42 +
 .../rules/state-context-interface.md          |  191 +
 .../rules/state-decouple-implementation.md    |  113 +
 .../rules/state-lift-state.md                 |  125 +
 skills/vercel/deploy-to-vercel/SKILL.md       |  296 ++
 .../resources/deploy-codex.sh                 |  301 ++
 .../deploy-to-vercel/resources/deploy.sh      |  301 ++
 skills/vercel/react-best-practices/AGENTS.md  | 3810 +++++++++++++++++
 skills/vercel/react-best-practices/README.md  |  123 +
 skills/vercel/react-best-practices/SKILL.md   |  149 +
 .../vercel/react-best-practices/metadata.json |   15 +
 .../react-best-practices/rules/_sections.md   |   46 +
 .../react-best-practices/rules/_template.md   |   28 +
 .../rules/advanced-effect-event-deps.md       |   56 +
 .../rules/advanced-event-handler-refs.md      |   55 +
 .../rules/advanced-init-once.md               |   42 +
 .../rules/advanced-use-latest.md              |   39 +
 .../rules/async-api-routes.md                 |   38 +
 .../async-cheap-condition-before-await.md     |   37 +
 .../rules/async-defer-await.md                |   82 +
 .../rules/async-dependencies.md               |   51 +
 .../rules/async-parallel.md                   |   28 +
 .../rules/async-suspense-boundaries.md        |   99 +
 .../rules/bundle-analyzable-paths.md          |   63 +
 .../rules/bundle-barrel-imports.md            |   60 +
 .../rules/bundle-conditional.md               |   31 +
 .../rules/bundle-defer-third-party.md         |   49 +
 .../rules/bundle-dynamic-imports.md           |   35 +
 .../rules/bundle-preload.md                   |   50 +
 .../rules/client-event-listeners.md           |   74 +
 .../rules/client-localstorage-schema.md       |   71 +
 .../rules/client-passive-event-listeners.md   |   48 +
 .../rules/client-swr-dedup.md                 |   56 +
 .../rules/js-batch-dom-css.md                 |  107 +
 .../rules/js-cache-function-results.md        |   80 +
 .../rules/js-cache-property-access.md         |   28 +
 .../rules/js-cache-storage.md                 |   70 +
 .../rules/js-combine-iterations.md            |   32 +
 .../rules/js-early-exit.md                    |   50 +
 .../rules/js-flatmap-filter.md                |   60 +
 .../rules/js-hoist-regexp.md                  |   45 +
 .../rules/js-index-maps.md                    |   37 +
 .../rules/js-length-check-first.md            |   49 +
 .../rules/js-min-max-loop.md                  |   82 +
 .../rules/js-request-idle-callback.md         |  105 +
 .../rules/js-set-map-lookups.md               |   24 +
 .../rules/js-tosorted-immutable.md            |   57 +
 .../rules/rendering-activity.md               |   26 +
 .../rules/rendering-animate-svg-wrapper.md    |   47 +
 .../rules/rendering-conditional-render.md     |   40 +
 .../rules/rendering-content-visibility.md     |   38 +
 .../rules/rendering-hoist-jsx.md              |   46 +
 .../rules/rendering-hydration-no-flicker.md   |   82 +
 .../rendering-hydration-suppress-warning.md   |   30 +
 .../rules/rendering-resource-hints.md         |   85 +
 .../rules/rendering-script-defer-async.md     |   68 +
 .../rules/rendering-svg-precision.md          |   28 +
 .../rules/rendering-usetransition-loading.md  |   75 +
 .../rules/rerender-defer-reads.md             |   39 +
 .../rules/rerender-dependencies.md            |   45 +
 .../rules/rerender-derived-state-no-effect.md |   40 +
 .../rules/rerender-derived-state.md           |   29 +
 .../rules/rerender-functional-setstate.md     |   74 +
 .../rules/rerender-lazy-state-init.md         |   58 +
 .../rules/rerender-memo-with-default-value.md |   38 +
 .../rules/rerender-memo.md                    |   44 +
 .../rules/rerender-move-effect-to-event.md    |   45 +
 .../rules/rerender-no-inline-components.md    |   82 +
 .../rerender-simple-expression-in-memo.md     |   35 +
 .../rules/rerender-split-combined-hooks.md    |   64 +
 .../rules/rerender-transitions.md             |   40 +
 .../rules/rerender-use-deferred-value.md      |   59 +
 .../rerender-use-ref-transient-values.md      |   73 +
 .../rules/server-after-nonblocking.md         |   73 +
 .../rules/server-auth-actions.md              |   96 +
 .../rules/server-cache-lru.md                 |   41 +
 .../rules/server-cache-react.md               |   76 +
 .../rules/server-dedup-props.md               |   65 +
 .../rules/server-hoist-static-io.md           |  149 +
 .../rules/server-no-shared-module-state.md    |   50 +
 .../rules/server-parallel-fetching.md         |   83 +
 .../rules/server-parallel-nested-fetching.md  |   34 +
 .../rules/server-serialization.md             |   38 +
 skills/vercel/react-native-skills/AGENTS.md   | 2897 +++++++++++++
 skills/vercel/react-native-skills/README.md   |  165 +
 skills/vercel/react-native-skills/SKILL.md    |  121 +
 .../vercel/react-native-skills/metadata.json  |   16 +
 .../react-native-skills/rules/_sections.md    |   86 +
 .../react-native-skills/rules/_template.md    |   28 +
 .../rules/animation-derived-value.md          |   53 +
 .../rules/animation-gesture-detector-press.md |   95 +
 .../rules/animation-gpu-properties.md         |   65 +
 .../design-system-compound-components.md      |   66 +
 .../rules/fonts-config-plugin.md              |   71 +
 .../rules/imports-design-system-folder.md     |   68 +
 .../rules/js-hoist-intl.md                    |   61 +
 .../rules/list-performance-callbacks.md       |   44 +
 .../list-performance-function-references.md   |  132 +
 .../rules/list-performance-images.md          |   53 +
 .../rules/list-performance-inline-objects.md  |   97 +
 .../rules/list-performance-item-expensive.md  |   94 +
 .../rules/list-performance-item-memo.md       |   82 +
 .../rules/list-performance-item-types.md      |  104 +
 .../rules/list-performance-virtualize.md      |   67 +
 .../rules/monorepo-native-deps-in-app.md      |   46 +
 .../monorepo-single-dependency-versions.md    |   63 +
 .../rules/navigation-native-navigators.md     |  188 +
 .../react-compiler-destructure-functions.md   |   50 +
 ...react-compiler-reanimated-shared-values.md |   48 +
 .../rules/react-state-dispatcher.md           |   91 +
 .../rules/react-state-fallback.md             |   56 +
 .../rules/react-state-minimize.md             |   65 +
 .../rules/rendering-no-falsy-and.md           |   74 +
 .../rules/rendering-text-in-text-component.md |   36 +
 .../rules/scroll-position-no-state.md         |   82 +
 .../rules/state-ground-truth.md               |   80 +
 .../rules/ui-expo-image.md                    |   66 +
 .../rules/ui-image-gallery.md                 |  104 +
 .../rules/ui-measure-views.md                 |   78 +
 .../react-native-skills/rules/ui-menus.md     |  174 +
 .../rules/ui-native-modals.md                 |   77 +
 .../react-native-skills/rules/ui-pressable.md |   61 +
 .../rules/ui-safe-area-scroll.md              |   65 +
 .../rules/ui-scrollview-content-inset.md      |   45 +
 .../react-native-skills/rules/ui-styling.md   |   87 +
 .../vercel/react-view-transitions/AGENTS.md   |  955 +++++
 .../vercel/react-view-transitions/README.md   |   42 +
 skills/vercel/react-view-transitions/SKILL.md |  320 ++
 .../react-view-transitions/metadata.json      |   12 +
 .../references/css-recipes.md                 |  242 ++
 .../references/implementation.md              |  182 +
 .../references/nextjs.md                      |  176 +
 .../references/patterns.md                    |  262 ++
 skills/vercel/vercel-cli-with-tokens/SKILL.md |  353 ++
 skills/vercel/vercel-optimize/AGENTS.md       |   48 +
 skills/vercel/vercel-optimize/CONTRIBUTING.md |   41 +
 skills/vercel/vercel-optimize/README.md       |   91 +
 skills/vercel/vercel-optimize/SKILL.md        |  322 ++
 .../vercel/vercel-optimize/lib/auth-route.mjs |   23 +
 .../vercel-optimize/lib/budget-summary.mjs    |  182 +
 .../vercel/vercel-optimize/lib/citations.mjs  |  139 +
 .../vercel-optimize/lib/cost-coverage.mjs     |  143 +
 .../vercel/vercel-optimize/lib/dedup-recs.mjs |  325 ++
 .../vercel/vercel-optimize/lib/deep-dive.mjs  |  350 ++
 .../vercel-optimize/lib/display-labels.mjs    |  185 +
 .../vercel-optimize/lib/extract-claims.mjs    |  550 +++
 .../vercel-optimize/lib/framework-support.mjs |   67 +
 .../lib/gates/build-minutes-fanout.mjs        |   69 +
 .../vercel-optimize/lib/gates/cold-start.mjs  |   66 +
 .../vercel-optimize/lib/gates/contract.mjs    |   79 +
 .../vercel-optimize/lib/gates/cwv-poor.mjs    |   87 +
 .../lib/gates/external-api-slow.mjs           |   55 +
 .../vercel-optimize/lib/gates/hard-gates.mjs  |   73 +
 .../vercel-optimize/lib/gates/index.mjs       |   45 +
 .../lib/gates/isr-overrevalidation.mjs        |   62 +
 .../lib/gates/middleware-heavy.mjs            |   51 +
 .../observability-events-attribution.mjs      |   56 +
 .../lib/gates/platform-bot-protection.mjs     |  115 +
 .../lib/gates/platform-fluid-compute.mjs      |   83 +
 .../lib/gates/region-misconfig.mjs            |   64 +
 .../lib/gates/route-errors.mjs                |   80 +
 .../lib/gates/scanner-driven.mjs              |  122 +
 .../lib/gates/select-candidates.mjs           |  134 +
 .../vercel-optimize/lib/gates/slow-route.mjs  |   88 +
 .../vercel-optimize/lib/gates/types.d.ts      |   38 +
 .../lib/gates/uncached-route.mjs              |   93 +
 .../lib/gates/usage-spike-triage.mjs          |  121 +
 .../lib/grade-recommendation.mjs              |  155 +
 .../vercel-optimize/lib/impact-label.mjs      |  126 +
 .../vercel-optimize/lib/impact-magnitude.mjs  |   60 +
 .../lib/investigation-brief.mjs               |  610 +++
 .../lib/observation-safety.mjs                |  174 +
 .../vercel-optimize/lib/project-facts.mjs     |   99 +
 skills/vercel/vercel-optimize/lib/queries.mjs |  315 ++
 .../lib/reconcile-candidates.mjs              |  372 ++
 .../vercel-optimize/lib/render-report.mjs     |  955 +++++
 .../vercel/vercel-optimize/lib/repo-root.mjs  |   86 +
 .../vercel-optimize/lib/route-normalize.mjs   |  220 +
 .../sanitizers/bot-protection-certainty.mjs   |   38 +
 .../cache-tag-invalidation-certainty.mjs      |   30 +
 .../lib/sanitizers/count-correct.mjs          |   52 +
 .../function-duration-invocations.mjs         |   38 +
 .../vercel-optimize/lib/sanitizers/index.mjs  |   79 +
 .../lib/sanitizers/middleware-conflict.mjs    |   36 +
 .../lib/sanitizers/missing-citation.mjs       |   16 +
 .../lib/sanitizers/pre-release.mjs            |   74 +
 .../lib/sanitizers/rate-limit.mjs             |   67 +
 .../sanitizers/rendering-mode-mislabel.mjs    |   38 +
 .../lib/sanitizers/undeclared-dep.mjs         |   78 +
 .../lib/sanitizers/vercel-directive-strip.mjs |   37 +
 .../lib/sanitizers/window-units.mjs           |   32 +
 .../cache-components-suspense-dedupe.mjs      |  109 +
 .../lib/scanners/edge-heavy-import.mjs        |   94 +
 .../lib/scanners/force-dynamic.mjs            |   42 +
 .../lib/scanners/headers-in-page.mjs          |   44 +
 .../vercel-optimize/lib/scanners/index.mjs    |   35 +
 .../lib/scanners/large-static-asset.mjs       |   92 +
 .../lib/scanners/max-age-without-s-maxage.mjs |   42 +
 .../lib/scanners/middleware-broad-matcher.mjs |   55 +
 .../lib/scanners/missing-cache-headers.mjs    |   90 +
 .../lib/scanners/prisma-include-tree.mjs      |   42 +
 .../lib/scanners/region-pin-in-config.mjs     |   88 +
 .../lib/scanners/source-maps-production.mjs   |   36 +
 .../scanners/sveltekit-prerender-missing.mjs  |   43 +
 .../lib/scanners/turbo-force-bypass.mjs       |  129 +
 .../lib/scanners/unoptimized-image.mjs        |  113 +
 .../lib/scanners/use-cache-date-stamp.mjs     |  106 +
 .../vercel-optimize/lib/support-topics.mjs    |  355 ++
 .../vercel/vercel-optimize/lib/throttle.mjs   |  273 ++
 skills/vercel/vercel-optimize/lib/util.mjs    |   17 +
 skills/vercel/vercel-optimize/lib/vercel.mjs  |  864 ++++
 .../vercel-optimize/lib/verify-claim.mjs      | 1296 ++++++
 .../lib/workspace-resolver.mjs                |  521 +++
 skills/vercel/vercel-optimize/metadata.json   |   14 +
 .../vercel-optimize/references/candidates.md  |  176 +
 .../references/data-collection.md             |  218 +
 .../references/docs-library.json              |  683 +++
 .../vercel-optimize/references/doctrine.md    |  105 +
 .../references/observability-plus.md          |  108 +
 .../references/playbooks/README.md            |   53 +
 .../references/playbooks/ai-application.md    |   32 +
 .../references/playbooks/api-service.md       |   30 +
 .../references/playbooks/content-site.md      |   30 +
 .../references/playbooks/ecommerce.md         |   30 +
 .../references/playbooks/marketing.md         |   30 +
 .../references/playbooks/saas.md              |   31 +
 .../references/playbooks/sveltekit.md         |   75 +
 .../references/recommendations.md             |  203 +
 .../references/scanner-patterns.md            |  251 ++
 .../vercel-optimize/references/scoring.md     |  205 +
 .../references/support-topics/README.md       |   46 +
 .../astro-edge-middleware-scope.md            |   22 +
 .../astro-output-mode-and-isr.md              |   22 +
 .../auth-preserving-parallelization.md        |   22 +
 .../bot-protection-product-guardrails.md      |   22 +
 .../build-minutes-monorepo-fanout.md          |   23 +
 ...ache-components-static-shell-boundaries.md |   22 +
 ...ache-components-suspense-dedupe-pitfall.md |   23 +
 .../support-topics/cdn-cache-auth-safety.md   |   22 +
 .../cold-start-initialization-bundle.md       |   22 +
 .../core-web-vitals-client-bottlenecks.md     |   22 +
 .../database-egress-pooling-region.md         |   22 +
 .../support-topics/dynamic-rendering-traps.md |   22 +
 .../external-api-critical-path-platform.md    |   22 +
 .../external-api-critical-path.md             |   22 +
 .../fast-data-transfer-payloads.md            |   22 +
 .../support-topics/fluid-compute-caveats.md   |   22 +
 .../function-duration-io-and-after.md         |   22 +
 .../function-invocation-reduction.md          |   22 +
 .../function-region-misconfiguration-ttfb.md  |   23 +
 .../image-optimization-cost-control.md        |   22 +
 .../isr-revalidation-static-generation.md     |   22 +
 .../middleware-proxy-edge-cost.md             |   22 +
 .../next-fetch-revalidate-floor.md            |   22 +
 .../next-font-cls-self-hosting.md             |   23 +
 .../next-heavy-ui-lazy-load-boundaries.md     |   23 +
 .../next-image-lcp-preload-sizes.md           |   23 +
 .../next-route-handler-get-cache-defaults.md  |   22 +
 .../next-script-third-party-strategy.md       |   23 +
 .../nextjs-version-cache-semantics.md         |   22 +
 .../not-found-catchall-request-waste.md       |   23 +
 .../nuxt-route-rules-cache-isr.md             |   22 +
 .../observability-events-cost-attribution.md  |   22 +
 .../post-response-work-waituntil.md           |   22 +
 .../route-error-durable-offload.md            |   22 +
 .../route-error-runtime-limits.md             |   22 +
 .../runtime-cache-reusable-data.md            |   22 +
 .../sveltekit-isr-prerender-safety.md         |   22 +
 .../sveltekit-split-cold-start-tradeoff.md    |   22 +
 .../support-topics/usage-spike-triage.md      |   22 +
 ...se-cache-date-stamp-isr-write-amplifier.md |   23 +
 .../use-cache-remote-shared-origin-data.md    |   22 +
 .../workflow-resumable-stream-routes.md       |   23 +
 .../references/verification.md                |  102 +
 .../vercel-optimize/references/voice.md       |   76 +
 .../scripts/budget-summary.mjs                |   56 +
 .../vercel-optimize/scripts/build-docs.mjs    |   74 +
 .../scripts/check-citations.mjs               |   81 +
 .../scripts/check-docs-fresh.mjs              |   93 +
 .../scripts/collect-signals.mjs               |  576 +++
 .../scripts/collect-sub-agent-outputs.mjs     |  296 ++
 .../vercel-optimize/scripts/deep-dive.mjs     |  319 ++
 .../scripts/gate-investigations.mjs           |  166 +
 .../vercel-optimize/scripts/merge-signals.mjs |  192 +
 .../scripts/prepare-investigation-brief.mjs   |  231 +
 .../scripts/reconcile-candidates.mjs          |   62 +
 .../vercel-optimize/scripts/render-report.mjs |  437 ++
 .../vercel-optimize/scripts/scan-codebase.mjs |  313 ++
 .../scripts/verify-and-regen.mjs              |  346 ++
 .../scripts/verify-finding.mjs                |   19 +
 skills/vercel/web-design-guidelines/SKILL.md  |   39 +
 skills/vercel/writing-guidelines/SKILL.md     |   39 +
 304 files changed, 38802 insertions(+)
 create mode 100755 scripts/sync-vercel-skills.sh
 create mode 100644 skills/vercel/UPSTREAM.md
 create mode 100644 skills/vercel/composition-patterns/AGENTS.md
 create mode 100644 skills/vercel/composition-patterns/README.md
 create mode 100644 skills/vercel/composition-patterns/SKILL.md
 create mode 100644 skills/vercel/composition-patterns/metadata.json
 create mode 100644 skills/vercel/composition-patterns/rules/_sections.md
 create mode 100644 skills/vercel/composition-patterns/rules/_template.md
 create mode 100644 skills/vercel/composition-patterns/rules/architecture-avoid-boolean-props.md
 create mode 100644 skills/vercel/composition-patterns/rules/architecture-compound-components.md
 create mode 100644 skills/vercel/composition-patterns/rules/patterns-children-over-render-props.md
 create mode 100644 skills/vercel/composition-patterns/rules/patterns-explicit-variants.md
 create mode 100644 skills/vercel/composition-patterns/rules/react19-no-forwardref.md
 create mode 100644 skills/vercel/composition-patterns/rules/state-context-interface.md
 create mode 100644 skills/vercel/composition-patterns/rules/state-decouple-implementation.md
 create mode 100644 skills/vercel/composition-patterns/rules/state-lift-state.md
 create mode 100644 skills/vercel/deploy-to-vercel/SKILL.md
 create mode 100755 skills/vercel/deploy-to-vercel/resources/deploy-codex.sh
 create mode 100755 skills/vercel/deploy-to-vercel/resources/deploy.sh
 create mode 100644 skills/vercel/react-best-practices/AGENTS.md
 create mode 100644 skills/vercel/react-best-practices/README.md
 create mode 100644 skills/vercel/react-best-practices/SKILL.md
 create mode 100644 skills/vercel/react-best-practices/metadata.json
 create mode 100644 skills/vercel/react-best-practices/rules/_sections.md
 create mode 100644 skills/vercel/react-best-practices/rules/_template.md
 create mode 100644 skills/vercel/react-best-practices/rules/advanced-effect-event-deps.md
 create mode 100644 skills/vercel/react-best-practices/rules/advanced-event-handler-refs.md
 create mode 100644 skills/vercel/react-best-practices/rules/advanced-init-once.md
 create mode 100644 skills/vercel/react-best-practices/rules/advanced-use-latest.md
 create mode 100644 skills/vercel/react-best-practices/rules/async-api-routes.md
 create mode 100644 skills/vercel/react-best-practices/rules/async-cheap-condition-before-await.md
 create mode 100644 skills/vercel/react-best-practices/rules/async-defer-await.md
 create mode 100644 skills/vercel/react-best-practices/rules/async-dependencies.md
 create mode 100644 skills/vercel/react-best-practices/rules/async-parallel.md
 create mode 100644 skills/vercel/react-best-practices/rules/async-suspense-boundaries.md
 create mode 100644 skills/vercel/react-best-practices/rules/bundle-analyzable-paths.md
 create mode 100644 skills/vercel/react-best-practices/rules/bundle-barrel-imports.md
 create mode 100644 skills/vercel/react-best-practices/rules/bundle-conditional.md
 create mode 100644 skills/vercel/react-best-practices/rules/bundle-defer-third-party.md
 create mode 100644 skills/vercel/react-best-practices/rules/bundle-dynamic-imports.md
 create mode 100644 skills/vercel/react-best-practices/rules/bundle-preload.md
 create mode 100644 skills/vercel/react-best-practices/rules/client-event-listeners.md
 create mode 100644 skills/vercel/react-best-practices/rules/client-localstorage-schema.md
 create mode 100644 skills/vercel/react-best-practices/rules/client-passive-event-listeners.md
 create mode 100644 skills/vercel/react-best-practices/rules/client-swr-dedup.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-batch-dom-css.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-cache-function-results.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-cache-property-access.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-cache-storage.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-combine-iterations.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-early-exit.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-flatmap-filter.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-hoist-regexp.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-index-maps.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-length-check-first.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-min-max-loop.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-request-idle-callback.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-set-map-lookups.md
 create mode 100644 skills/vercel/react-best-practices/rules/js-tosorted-immutable.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-activity.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-animate-svg-wrapper.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-conditional-render.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-content-visibility.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-hoist-jsx.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-hydration-no-flicker.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-hydration-suppress-warning.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-resource-hints.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-script-defer-async.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-svg-precision.md
 create mode 100644 skills/vercel/react-best-practices/rules/rendering-usetransition-loading.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-defer-reads.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-dependencies.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-derived-state-no-effect.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-derived-state.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-functional-setstate.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-lazy-state-init.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-memo-with-default-value.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-memo.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-move-effect-to-event.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-no-inline-components.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-simple-expression-in-memo.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-split-combined-hooks.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-transitions.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-use-deferred-value.md
 create mode 100644 skills/vercel/react-best-practices/rules/rerender-use-ref-transient-values.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-after-nonblocking.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-auth-actions.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-cache-lru.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-cache-react.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-dedup-props.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-hoist-static-io.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-no-shared-module-state.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-parallel-fetching.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-parallel-nested-fetching.md
 create mode 100644 skills/vercel/react-best-practices/rules/server-serialization.md
 create mode 100644 skills/vercel/react-native-skills/AGENTS.md
 create mode 100644 skills/vercel/react-native-skills/README.md
 create mode 100644 skills/vercel/react-native-skills/SKILL.md
 create mode 100644 skills/vercel/react-native-skills/metadata.json
 create mode 100644 skills/vercel/react-native-skills/rules/_sections.md
 create mode 100644 skills/vercel/react-native-skills/rules/_template.md
 create mode 100644 skills/vercel/react-native-skills/rules/animation-derived-value.md
 create mode 100644 skills/vercel/react-native-skills/rules/animation-gesture-detector-press.md
 create mode 100644 skills/vercel/react-native-skills/rules/animation-gpu-properties.md
 create mode 100644 skills/vercel/react-native-skills/rules/design-system-compound-components.md
 create mode 100644 skills/vercel/react-native-skills/rules/fonts-config-plugin.md
 create mode 100644 skills/vercel/react-native-skills/rules/imports-design-system-folder.md
 create mode 100644 skills/vercel/react-native-skills/rules/js-hoist-intl.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-callbacks.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-function-references.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-images.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-inline-objects.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-item-expensive.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-item-memo.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-item-types.md
 create mode 100644 skills/vercel/react-native-skills/rules/list-performance-virtualize.md
 create mode 100644 skills/vercel/react-native-skills/rules/monorepo-native-deps-in-app.md
 create mode 100644 skills/vercel/react-native-skills/rules/monorepo-single-dependency-versions.md
 create mode 100644 skills/vercel/react-native-skills/rules/navigation-native-navigators.md
 create mode 100644 skills/vercel/react-native-skills/rules/react-compiler-destructure-functions.md
 create mode 100644 skills/vercel/react-native-skills/rules/react-compiler-reanimated-shared-values.md
 create mode 100644 skills/vercel/react-native-skills/rules/react-state-dispatcher.md
 create mode 100644 skills/vercel/react-native-skills/rules/react-state-fallback.md
 create mode 100644 skills/vercel/react-native-skills/rules/react-state-minimize.md
 create mode 100644 skills/vercel/react-native-skills/rules/rendering-no-falsy-and.md
 create mode 100644 skills/vercel/react-native-skills/rules/rendering-text-in-text-component.md
 create mode 100644 skills/vercel/react-native-skills/rules/scroll-position-no-state.md
 create mode 100644 skills/vercel/react-native-skills/rules/state-ground-truth.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-expo-image.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-image-gallery.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-measure-views.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-menus.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-native-modals.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-pressable.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-safe-area-scroll.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-scrollview-content-inset.md
 create mode 100644 skills/vercel/react-native-skills/rules/ui-styling.md
 create mode 100644 skills/vercel/react-view-transitions/AGENTS.md
 create mode 100644 skills/vercel/react-view-transitions/README.md
 create mode 100644 skills/vercel/react-view-transitions/SKILL.md
 create mode 100644 skills/vercel/react-view-transitions/metadata.json
 create mode 100644 skills/vercel/react-view-transitions/references/css-recipes.md
 create mode 100644 skills/vercel/react-view-transitions/references/implementation.md
 create mode 100644 skills/vercel/react-view-transitions/references/nextjs.md
 create mode 100644 skills/vercel/react-view-transitions/references/patterns.md
 create mode 100644 skills/vercel/vercel-cli-with-tokens/SKILL.md
 create mode 100644 skills/vercel/vercel-optimize/AGENTS.md
 create mode 100644 skills/vercel/vercel-optimize/CONTRIBUTING.md
 create mode 100644 skills/vercel/vercel-optimize/README.md
 create mode 100644 skills/vercel/vercel-optimize/SKILL.md
 create mode 100644 skills/vercel/vercel-optimize/lib/auth-route.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/budget-summary.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/citations.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/cost-coverage.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/dedup-recs.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/deep-dive.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/display-labels.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/extract-claims.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/framework-support.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/build-minutes-fanout.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/cold-start.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/contract.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/cwv-poor.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/external-api-slow.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/hard-gates.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/index.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/isr-overrevalidation.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/middleware-heavy.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/observability-events-attribution.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/platform-bot-protection.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/platform-fluid-compute.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/region-misconfig.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/route-errors.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/scanner-driven.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/select-candidates.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/slow-route.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/types.d.ts
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/uncached-route.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/gates/usage-spike-triage.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/grade-recommendation.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/impact-label.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/impact-magnitude.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/investigation-brief.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/observation-safety.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/project-facts.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/queries.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/reconcile-candidates.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/render-report.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/repo-root.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/route-normalize.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/bot-protection-certainty.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/cache-tag-invalidation-certainty.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/count-correct.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/function-duration-invocations.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/index.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/middleware-conflict.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/missing-citation.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/pre-release.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/rate-limit.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/rendering-mode-mislabel.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/undeclared-dep.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/vercel-directive-strip.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/sanitizers/window-units.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/cache-components-suspense-dedupe.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/edge-heavy-import.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/force-dynamic.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/headers-in-page.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/index.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/large-static-asset.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/max-age-without-s-maxage.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/middleware-broad-matcher.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/missing-cache-headers.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/prisma-include-tree.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/region-pin-in-config.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/source-maps-production.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/sveltekit-prerender-missing.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/turbo-force-bypass.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/unoptimized-image.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/scanners/use-cache-date-stamp.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/support-topics.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/throttle.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/util.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/vercel.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/verify-claim.mjs
 create mode 100644 skills/vercel/vercel-optimize/lib/workspace-resolver.mjs
 create mode 100644 skills/vercel/vercel-optimize/metadata.json
 create mode 100644 skills/vercel/vercel-optimize/references/candidates.md
 create mode 100644 skills/vercel/vercel-optimize/references/data-collection.md
 create mode 100644 skills/vercel/vercel-optimize/references/docs-library.json
 create mode 100644 skills/vercel/vercel-optimize/references/doctrine.md
 create mode 100644 skills/vercel/vercel-optimize/references/observability-plus.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/README.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/ai-application.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/api-service.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/content-site.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/ecommerce.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/marketing.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/saas.md
 create mode 100644 skills/vercel/vercel-optimize/references/playbooks/sveltekit.md
 create mode 100644 skills/vercel/vercel-optimize/references/recommendations.md
 create mode 100644 skills/vercel/vercel-optimize/references/scanner-patterns.md
 create mode 100644 skills/vercel/vercel-optimize/references/scoring.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/README.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/astro-edge-middleware-scope.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/astro-output-mode-and-isr.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/auth-preserving-parallelization.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/bot-protection-product-guardrails.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/build-minutes-monorepo-fanout.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/cache-components-static-shell-boundaries.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/cache-components-suspense-dedupe-pitfall.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/cdn-cache-auth-safety.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/cold-start-initialization-bundle.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/core-web-vitals-client-bottlenecks.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/database-egress-pooling-region.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/dynamic-rendering-traps.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path-platform.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/fast-data-transfer-payloads.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/fluid-compute-caveats.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/function-duration-io-and-after.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/function-invocation-reduction.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/function-region-misconfiguration-ttfb.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/image-optimization-cost-control.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/isr-revalidation-static-generation.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/middleware-proxy-edge-cost.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/next-fetch-revalidate-floor.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/next-font-cls-self-hosting.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/next-heavy-ui-lazy-load-boundaries.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/next-image-lcp-preload-sizes.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/next-route-handler-get-cache-defaults.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/next-script-third-party-strategy.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/nextjs-version-cache-semantics.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/not-found-catchall-request-waste.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/nuxt-route-rules-cache-isr.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/observability-events-cost-attribution.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/post-response-work-waituntil.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/route-error-durable-offload.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/route-error-runtime-limits.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/runtime-cache-reusable-data.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/sveltekit-isr-prerender-safety.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/sveltekit-split-cold-start-tradeoff.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/usage-spike-triage.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/use-cache-date-stamp-isr-write-amplifier.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/use-cache-remote-shared-origin-data.md
 create mode 100644 skills/vercel/vercel-optimize/references/support-topics/workflow-resumable-stream-routes.md
 create mode 100644 skills/vercel/vercel-optimize/references/verification.md
 create mode 100644 skills/vercel/vercel-optimize/references/voice.md
 create mode 100644 skills/vercel/vercel-optimize/scripts/budget-summary.mjs
 create mode 100755 skills/vercel/vercel-optimize/scripts/build-docs.mjs
 create mode 100644 skills/vercel/vercel-optimize/scripts/check-citations.mjs
 create mode 100755 skills/vercel/vercel-optimize/scripts/check-docs-fresh.mjs
 create mode 100755 skills/vercel/vercel-optimize/scripts/collect-signals.mjs
 create mode 100644 skills/vercel/vercel-optimize/scripts/collect-sub-agent-outputs.mjs
 create mode 100755 skills/vercel/vercel-optimize/scripts/deep-dive.mjs
 create mode 100755 skills/vercel/vercel-optimize/scripts/gate-investigations.mjs
 create mode 100644 skills/vercel/vercel-optimize/scripts/merge-signals.mjs
 create mode 100644 skills/vercel/vercel-optimize/scripts/prepare-investigation-brief.mjs
 create mode 100644 skills/vercel/vercel-optimize/scripts/reconcile-candidates.mjs
 create mode 100644 skills/vercel/vercel-optimize/scripts/render-report.mjs
 create mode 100755 skills/vercel/vercel-optimize/scripts/scan-codebase.mjs
 create mode 100644 skills/vercel/vercel-optimize/scripts/verify-and-regen.mjs
 create mode 100755 skills/vercel/vercel-optimize/scripts/verify-finding.mjs
 create mode 100644 skills/vercel/web-design-guidelines/SKILL.md
 create mode 100644 skills/vercel/writing-guidelines/SKILL.md

diff --git a/scripts/sync-vercel-skills.sh b/scripts/sync-vercel-skills.sh
new file mode 100755
index 0000000..611d9bd
--- /dev/null
+++ b/scripts/sync-vercel-skills.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Sync vercel-labs/agent-skills into skills/vercel/ (vendored read-only mirror).
+# Re-run anytime to pull upstream updates. Build .zip artifacts are excluded.
+#
+#   bash scripts/sync-vercel-skills.sh
+#
+set -euo pipefail
+UPSTREAM="${VERCEL_SKILLS_UPSTREAM:-https://github.com/vercel-labs/agent-skills.git}"
+PREFIX="skills/vercel"
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
+
+git clone --quiet --depth=1 "$UPSTREAM" "$WORK/up"
+SHA="$(git -C "$WORK/up" rev-parse HEAD)"
+dest="$REPO_ROOT/$PREFIX"; mkdir -p "$dest"
+
+# Replace vendored skill dirs (preserve UPSTREAM.md), excluding build artifacts
+find "$dest" -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} +
+for d in "$WORK/up/skills"/*/; do
+  rsync -a --exclude='*.zip' "$d" "$dest/$(basename "$d")/"
+done
+sed -i -E "s|^- Upstream commit:.*|- Upstream commit: $SHA|" "$dest/UPSTREAM.md" 2>/dev/null || true
+
+cd "$REPO_ROOT"
+git add "$PREFIX"
+if git diff --cached --quiet; then
+  echo "Already up to date with $SHA"
+else
+  git commit -q -m "chore(vercel): sync agent-skills to ${SHA:0:7}"
+  echo "OK: $PREFIX synced to $SHA"
+fi
diff --git a/skills/vercel/UPSTREAM.md b/skills/vercel/UPSTREAM.md
new file mode 100644
index 0000000..a10f2af
--- /dev/null
+++ b/skills/vercel/UPSTREAM.md
@@ -0,0 +1,12 @@
+# Vendored from vercel-labs/agent-skills
+
+Read-only mirror of https://github.com/vercel-labs/agent-skills
+
+- Upstream commit: f8a72b9603728bb92a217a879b7e62e43ad76c81
+- Vendored: 2026-06-30 via `git subtree` (prefix skills/vercel)
+- License: MIT (declared in upstream README; upstream ships no LICENSE file)
+- Update: run `bash scripts/sync-vercel-skills.sh` from the skills repo root.
+  It re-pulls upstream and strips build `.zip` artifacts automatically.
+
+Do not hand-edit these skills — local changes are overwritten on the next sync.
+Contribute fixes upstream at vercel-labs/agent-skills.
diff --git a/skills/vercel/composition-patterns/AGENTS.md b/skills/vercel/composition-patterns/AGENTS.md
new file mode 100644
index 0000000..558bf9a
--- /dev/null
+++ b/skills/vercel/composition-patterns/AGENTS.md
@@ -0,0 +1,946 @@
+# React Composition Patterns
+
+**Version 1.0.0**  
+Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React codebases using composition. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.
+
+---
+
+## Table of Contents
+
+1. [Component Architecture](#1-component-architecture) — **HIGH**
+   - 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)
+   - 1.2 [Use Compound Components](#12-use-compound-components)
+2. [State Management](#2-state-management) — **MEDIUM**
+   - 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)
+   - 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)
+   - 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)
+3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**
+   - 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)
+   - 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)
+4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**
+   - 4.1 [React 19 API Changes](#41-react-19-api-changes)
+
+---
+
+## 1. Component Architecture
+
+**Impact: HIGH**
+
+Fundamental patterns for structuring components to avoid prop
+proliferation and enable flexible composition.
+
+### 1.1 Avoid Boolean Prop Proliferation
+
+**Impact: CRITICAL (prevents unmaintainable component variants)**
+
+Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
+
+component behavior. Each boolean doubles possible states and creates
+
+unmaintainable conditional logic. Use composition instead.
+
+**Incorrect: boolean props create exponential complexity**
+
+```tsx
+function Composer({
+  onSubmit,
+  isThread,
+  channelId,
+  isDMThread,
+  dmId,
+  isEditing,
+  isForwarding,
+}: Props) {
+  return (
+    <form>
+      <Header />
+      <Input />
+      {isDMThread ? (
+        <AlsoSendToDMField id={dmId} />
+      ) : isThread ? (
+        <AlsoSendToChannelField id={channelId} />
+      ) : null}
+      {isEditing ? (
+        <EditActions />
+      ) : isForwarding ? (
+        <ForwardActions />
+      ) : (
+        <DefaultActions />
+      )}
+      <Footer onSubmit={onSubmit} />
+    </form>
+  )
+}
+```
+
+**Correct: composition eliminates conditionals**
+
+```tsx
+// Channel composer
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Attachments />
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Thread composer - adds "also send to channel" field
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <AlsoSendToChannelField id={channelId} />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Edit composer - different footer actions
+function EditComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.CancelEdit />
+        <Composer.SaveEdit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+```
+
+Each variant is explicit about what it renders. We can share internals without
+
+sharing a single monolithic parent.
+
+### 1.2 Use Compound Components
+
+**Impact: HIGH (enables flexible composition without prop drilling)**
+
+Structure complex components as compound components with a shared context. Each
+
+subcomponent accesses shared state via context, not props. Consumers compose the
+
+pieces they need.
+
+**Incorrect: monolithic component with render props**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+  showAttachments,
+  showFormatting,
+  showEmojis,
+}: Props) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {showAttachments && <Attachments />}
+      {renderFooter ? (
+        renderFooter()
+      ) : (
+        <Footer>
+          {showFormatting && <Formatting />}
+          {showEmojis && <Emojis />}
+          {renderActions?.()}
+        </Footer>
+      )}
+    </form>
+  )
+}
+```
+
+**Correct: compound components with shared context**
+
+```tsx
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+
+function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
+  return (
+    <ComposerContext value={{ state, actions, meta }}>
+      {children}
+    </ComposerContext>
+  )
+}
+
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta: { inputRef },
+  } = use(ComposerContext)
+  return (
+    <TextInput
+      ref={inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+
+function ComposerSubmit() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Send</Button>
+}
+
+// Export as compound component
+const Composer = {
+  Provider: ComposerProvider,
+  Frame: ComposerFrame,
+  Input: ComposerInput,
+  Submit: ComposerSubmit,
+  Header: ComposerHeader,
+  Footer: ComposerFooter,
+  Attachments: ComposerAttachments,
+  Formatting: ComposerFormatting,
+  Emojis: ComposerEmojis,
+}
+```
+
+**Usage:**
+
+```tsx
+<Composer.Provider state={state} actions={actions} meta={meta}>
+  <Composer.Frame>
+    <Composer.Header />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Submit />
+    </Composer.Footer>
+  </Composer.Frame>
+</Composer.Provider>
+```
+
+Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
+
+---
+
+## 2. State Management
+
+**Impact: MEDIUM**
+
+Patterns for lifting state and managing shared context across
+composed components.
+
+### 2.1 Decouple State Management from UI
+
+**Impact: MEDIUM (enables swapping state implementations without changing UI)**
+
+The provider component should be the only place that knows how state is managed.
+
+UI components consume the context interface—they don't know if state comes from
+
+useState, Zustand, or a server sync.
+
+**Incorrect: UI coupled to state implementation**
+
+```tsx
+function ChannelComposer({ channelId }: { channelId: string }) {
+  // UI component knows about global state implementation
+  const state = useGlobalChannelState(channelId)
+  const { submit, updateInput } = useChannelSync(channelId)
+
+  return (
+    <Composer.Frame>
+      <Composer.Input
+        value={state.input}
+        onChange={(text) => sync.updateInput(text)}
+      />
+      <Composer.Submit onPress={() => sync.submit()} />
+    </Composer.Frame>
+  )
+}
+```
+
+**Correct: state management isolated in provider**
+
+```tsx
+// Provider handles all state management details
+function ChannelProvider({
+  channelId,
+  children,
+}: {
+  channelId: string
+  children: React.ReactNode
+}) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update, submit }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// UI component only knows about the context interface
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Usage
+function Channel({ channelId }: { channelId: string }) {
+  return (
+    <ChannelProvider channelId={channelId}>
+      <ChannelComposer />
+    </ChannelProvider>
+  )
+}
+```
+
+**Different providers, same UI:**
+
+```tsx
+// Local state for ephemeral forms
+function ForwardMessageProvider({ children }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// Global synced state for channels
+function ChannelProvider({ channelId, children }) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+
+  return (
+    <Composer.Provider state={state} actions={{ update, submit }}>
+      {children}
+    </Composer.Provider>
+  )
+}
+```
+
+The same `Composer.Input` component works with both providers because it only
+
+depends on the context interface, not the implementation.
+
+### 2.2 Define Generic Context Interfaces for Dependency Injection
+
+**Impact: HIGH (enables dependency-injectable state across use-cases)**
+
+Define a **generic interface** for your component context with three parts:
+
+`state`, `actions`, and `meta`. This interface is a contract that any provider
+
+can implement—enabling the same UI components to work with completely different
+
+state implementations.
+
+**Core principle:** Lift state, compose internals, make state
+
+dependency-injectable.
+
+**Incorrect: UI coupled to specific state implementation**
+
+```tsx
+function ComposerInput() {
+  // Tightly coupled to a specific hook
+  const { input, setInput } = useChannelComposerState()
+  return <TextInput value={input} onChangeText={setInput} />
+}
+```
+
+**Correct: generic interface enables dependency injection**
+
+```tsx
+// Define a GENERIC interface that any provider can implement
+interface ComposerState {
+  input: string
+  attachments: Attachment[]
+  isSubmitting: boolean
+}
+
+interface ComposerActions {
+  update: (updater: (state: ComposerState) => ComposerState) => void
+  submit: () => void
+}
+
+interface ComposerMeta {
+  inputRef: React.RefObject<TextInput>
+}
+
+interface ComposerContextValue {
+  state: ComposerState
+  actions: ComposerActions
+  meta: ComposerMeta
+}
+
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+```
+
+**UI components consume the interface, not the implementation:**
+
+```tsx
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta,
+  } = use(ComposerContext)
+
+  // This component works with ANY provider that implements the interface
+  return (
+    <TextInput
+      ref={meta.inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+```
+
+**Different providers implement the same interface:**
+
+```tsx
+// Provider A: Local state for ephemeral forms
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const inputRef = useRef(null)
+  const submit = useForwardMessage()
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update: setState, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+
+// Provider B: Global synced state for channels
+function ChannelProvider({ channelId, children }: Props) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+```
+
+**The same composed UI works with both:**
+
+```tsx
+// Works with ForwardMessageProvider (local state)
+<ForwardMessageProvider>
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ForwardMessageProvider>
+
+// Works with ChannelProvider (global synced state)
+<ChannelProvider channelId="abc">
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ChannelProvider>
+```
+
+**Custom UI outside the component can access state and actions:**
+
+```tsx
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        {/* The composer UI */}
+        <Composer.Frame>
+          <Composer.Input placeholder="Add a message, if you'd like." />
+          <Composer.Footer>
+            <Composer.Formatting />
+            <Composer.Emojis />
+          </Composer.Footer>
+        </Composer.Frame>
+
+        {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
+        <MessagePreview />
+
+        {/* Actions at the bottom of the dialog */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton />
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
+function ForwardButton() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Forward</Button>
+}
+
+// This preview lives OUTSIDE Composer.Frame but can read composer's state!
+function MessagePreview() {
+  const { state } = use(ComposerContext)
+  return <Preview message={state.input} attachments={state.attachments} />
+}
+```
+
+The provider boundary is what matters—not the visual nesting. Components that
+
+need shared state don't have to be inside the `Composer.Frame`. They just need
+
+to be within the provider.
+
+The `ForwardButton` and `MessagePreview` are not visually inside the composer
+
+box, but they can still access its state and actions. This is the power of
+
+lifting state into providers.
+
+The UI is reusable bits you compose together. The state is dependency-injected
+
+by the provider. Swap the provider, keep the UI.
+
+### 2.3 Lift State into Provider Components
+
+**Impact: HIGH (enables state sharing outside component boundaries)**
+
+Move state management into dedicated provider components. This allows sibling
+
+components outside the main UI to access and modify state without prop drilling
+
+or awkward refs.
+
+**Incorrect: state trapped inside component**
+
+```tsx
+function ForwardMessageComposer() {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer />
+    </Composer.Frame>
+  )
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+  return (
+    <Dialog>
+      <ForwardMessageComposer />
+      <MessagePreview /> {/* Needs composer state */}
+      <DialogActions>
+        <CancelButton />
+        <ForwardButton /> {/* Needs to call submit */}
+      </DialogActions>
+    </Dialog>
+  )
+}
+```
+
+**Incorrect: useEffect to sync state up**
+
+```tsx
+function ForwardMessageDialog() {
+  const [input, setInput] = useState('')
+  return (
+    <Dialog>
+      <ForwardMessageComposer onInputChange={setInput} />
+      <MessagePreview input={input} />
+    </Dialog>
+  )
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+  const [state, setState] = useState(initialState)
+  useEffect(() => {
+    onInputChange(state.input) // Sync on every change 😬
+  }, [state.input])
+}
+```
+
+**Incorrect: reading state from ref on submit**
+
+```tsx
+function ForwardMessageDialog() {
+  const stateRef = useRef(null)
+  return (
+    <Dialog>
+      <ForwardMessageComposer stateRef={stateRef} />
+      <ForwardButton onPress={() => submit(stateRef.current)} />
+    </Dialog>
+  )
+}
+```
+
+**Correct: state lifted to provider**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        <ForwardMessageComposer />
+        <MessagePreview /> {/* Custom components can access state and actions */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton /> {/* Custom components can access state and actions */}
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+function ForwardButton() {
+  const { actions } = use(Composer.Context)
+  return <Button onPress={actions.submit}>Forward</Button>
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+
+submit action because it's within the provider. Even though it's a one-off
+
+component, it can still access the composer's state and actions from outside the
+
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+
+nested inside each other—they just need to be within the same provider.
+
+---
+
+## 3. Implementation Patterns
+
+**Impact: MEDIUM**
+
+Specific techniques for implementing compound components and
+context providers.
+
+### 3.1 Create Explicit Component Variants
+
+**Impact: MEDIUM (self-documenting code, no hidden conditionals)**
+
+Instead of one component with many boolean props, create explicit variant
+
+components. Each variant composes the pieces it needs. The code documents
+
+itself.
+
+**Incorrect: one component, many modes**
+
+```tsx
+// What does this component actually render?
+<Composer
+  isThread
+  isEditing={false}
+  channelId='abc'
+  showAttachments
+  showFormatting={false}
+/>
+```
+
+**Correct: explicit variants**
+
+```tsx
+// Immediately clear what this renders
+<ThreadComposer channelId="abc" />
+
+// Or
+<EditMessageComposer messageId="xyz" />
+
+// Or
+<ForwardMessageComposer messageId="123" />
+```
+
+Each implementation is unique, explicit and self-contained. Yet they can each
+
+use shared parts.
+
+**Implementation:**
+
+```tsx
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <ThreadProvider channelId={channelId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <AlsoSendToChannelField channelId={channelId} />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Submit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ThreadProvider>
+  )
+}
+
+function EditMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <EditMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.CancelEdit />
+          <Composer.SaveEdit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </EditMessageProvider>
+  )
+}
+
+function ForwardMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <ForwardMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input placeholder="Add a message, if you'd like." />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Mentions />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ForwardMessageProvider>
+  )
+}
+```
+
+Each variant is explicit about:
+
+- What provider/state it uses
+
+- What UI elements it includes
+
+- What actions are available
+
+No boolean prop combinations to reason about. No impossible states.
+
+### 3.2 Prefer Composing Children Over Render Props
+
+**Impact: MEDIUM (cleaner composition, better readability)**
+
+Use `children` for composition instead of `renderX` props. Children are more
+
+readable, compose naturally, and don't require understanding callback
+
+signatures.
+
+**Incorrect: render props**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+}: {
+  renderHeader?: () => React.ReactNode
+  renderFooter?: () => React.ReactNode
+  renderActions?: () => React.ReactNode
+}) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {renderFooter ? renderFooter() : <DefaultFooter />}
+      {renderActions?.()}
+    </form>
+  )
+}
+
+// Usage is awkward and inflexible
+return (
+  <Composer
+    renderHeader={() => <CustomHeader />}
+    renderFooter={() => (
+      <>
+        <Formatting />
+        <Emojis />
+      </>
+    )}
+    renderActions={() => <SubmitButton />}
+  />
+)
+```
+
+**Correct: compound components with children**
+
+```tsx
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerFooter({ children }: { children: React.ReactNode }) {
+  return <footer className='flex'>{children}</footer>
+}
+
+// Usage is flexible
+return (
+  <Composer.Frame>
+    <CustomHeader />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Emojis />
+      <SubmitButton />
+    </Composer.Footer>
+  </Composer.Frame>
+)
+```
+
+**When render props are appropriate:**
+
+```tsx
+// Render props work well when you need to pass data back
+<List
+  data={items}
+  renderItem={({ item, index }) => <Item item={item} index={index} />}
+/>
+```
+
+Use render props when the parent needs to provide data or state to the child.
+
+Use children when composing static structure.
+
+---
+
+## 4. React 19 APIs
+
+**Impact: MEDIUM**
+
+React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
+
+### 4.1 React 19 API Changes
+
+**Impact: MEDIUM (cleaner component definitions and context usage)**
+
+> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
+
+In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
+
+**Incorrect: forwardRef in React 19**
+
+```tsx
+const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
+  return <TextInput ref={ref} {...props} />
+})
+```
+
+**Correct: ref as a regular prop**
+
+```tsx
+function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
+  return <TextInput ref={ref} {...props} />
+}
+```
+
+**Incorrect: useContext in React 19**
+
+```tsx
+const value = useContext(MyContext)
+```
+
+**Correct: use instead of useContext**
+
+```tsx
+const value = use(MyContext)
+```
+
+`use()` can also be called conditionally, unlike `useContext()`.
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://react.dev/learn/passing-data-deeply-with-context](https://react.dev/learn/passing-data-deeply-with-context)
+3. [https://react.dev/reference/react/use](https://react.dev/reference/react/use)
diff --git a/skills/vercel/composition-patterns/README.md b/skills/vercel/composition-patterns/README.md
new file mode 100644
index 0000000..01f359b
--- /dev/null
+++ b/skills/vercel/composition-patterns/README.md
@@ -0,0 +1,60 @@
+# React Composition Patterns
+
+A structured repository for React composition patterns that scale. These
+patterns help avoid boolean prop proliferation by using compound components,
+lifting state, and composing internals.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `metadata.json` - Document metadata (version, organization, abstract)
+- **`AGENTS.md`** - Compiled output (generated)
+
+## Rules
+
+### Component Architecture (CRITICAL)
+
+- `architecture-avoid-boolean-props.md` - Don't add boolean props to customize
+  behavior
+- `architecture-compound-components.md` - Structure as compound components with
+  shared context
+
+### State Management (HIGH)
+
+- `state-lift-state.md` - Lift state into provider components
+- `state-context-interface.md` - Define clear context interfaces
+  (state/actions/meta)
+- `state-decouple-implementation.md` - Decouple state management from UI
+
+### Implementation Patterns (MEDIUM)
+
+- `patterns-children-over-render-props.md` - Prefer children over renderX props
+- `patterns-explicit-variants.md` - Create explicit component variants
+
+## Core Principles
+
+1. **Composition over configuration** — Instead of adding props, let consumers
+   compose
+2. **Lift your state** — State in providers, not trapped in components
+3. **Compose your internals** — Subcomponents access context, not props
+4. **Explicit variants** — Create ThreadComposer, EditComposer, not Composer
+   with isThread
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `architecture-` for Component Architecture
+   - `state-` for State Management
+   - `patterns-` for Implementation Patterns
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+
+## Impact Levels
+
+- `CRITICAL` - Foundational patterns, prevents unmaintainable code
+- `HIGH` - Significant maintainability improvements
+- `MEDIUM` - Good practices for cleaner code
diff --git a/skills/vercel/composition-patterns/SKILL.md b/skills/vercel/composition-patterns/SKILL.md
new file mode 100644
index 0000000..d07025b
--- /dev/null
+++ b/skills/vercel/composition-patterns/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: vercel-composition-patterns
+description:
+  React composition patterns that scale. Use when refactoring components with
+  boolean prop proliferation, building flexible component libraries, or
+  designing reusable APIs. Triggers on tasks involving compound components,
+  render props, context providers, or component architecture. Includes React 19
+  API changes.
+license: MIT
+metadata:
+  author: vercel
+  version: '1.0.0'
+---
+
+# React Composition Patterns
+
+Composition patterns for building flexible, maintainable React components. Avoid
+boolean prop proliferation by using compound components, lifting state, and
+composing internals. These patterns make codebases easier for both humans and AI
+agents to work with as they scale.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Refactoring components with many boolean props
+- Building reusable component libraries
+- Designing flexible component APIs
+- Reviewing component architecture
+- Working with compound components or context providers
+
+## Rule Categories by Priority
+
+| Priority | Category                | Impact | Prefix          |
+| -------- | ----------------------- | ------ | --------------- |
+| 1        | Component Architecture  | HIGH   | `architecture-` |
+| 2        | State Management        | MEDIUM | `state-`        |
+| 3        | Implementation Patterns | MEDIUM | `patterns-`     |
+| 4        | React 19 APIs           | MEDIUM | `react19-`      |
+
+## Quick Reference
+
+### 1. Component Architecture (HIGH)
+
+- `architecture-avoid-boolean-props` - Don't add boolean props to customize
+  behavior; use composition
+- `architecture-compound-components` - Structure complex components with shared
+  context
+
+### 2. State Management (MEDIUM)
+
+- `state-decouple-implementation` - Provider is the only place that knows how
+  state is managed
+- `state-context-interface` - Define generic interface with state, actions, meta
+  for dependency injection
+- `state-lift-state` - Move state into provider components for sibling access
+
+### 3. Implementation Patterns (MEDIUM)
+
+- `patterns-explicit-variants` - Create explicit variant components instead of
+  boolean modes
+- `patterns-children-over-render-props` - Use children for composition instead
+  of renderX props
+
+### 4. React 19 APIs (MEDIUM)
+
+> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.
+
+- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/architecture-avoid-boolean-props.md
+rules/state-context-interface.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel/composition-patterns/metadata.json b/skills/vercel/composition-patterns/metadata.json
new file mode 100644
index 0000000..3470b74
--- /dev/null
+++ b/skills/vercel/composition-patterns/metadata.json
@@ -0,0 +1,11 @@
+{
+  "version": "1.0.0",
+  "organization": "Engineering",
+  "date": "January 2026",
+  "abstract": "Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.",
+  "references": [
+    "https://react.dev",
+    "https://react.dev/learn/passing-data-deeply-with-context",
+    "https://react.dev/reference/react/use"
+  ]
+}
diff --git a/skills/vercel/composition-patterns/rules/_sections.md b/skills/vercel/composition-patterns/rules/_sections.md
new file mode 100644
index 0000000..f921dd4
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/_sections.md
@@ -0,0 +1,29 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Component Architecture (architecture)
+
+**Impact:** HIGH  
+**Description:** Fundamental patterns for structuring components to avoid prop
+proliferation and enable flexible composition.
+
+## 2. State Management (state)
+
+**Impact:** MEDIUM  
+**Description:** Patterns for lifting state and managing shared context across
+composed components.
+
+## 3. Implementation Patterns (patterns)
+
+**Impact:** MEDIUM  
+**Description:** Specific techniques for implementing compound components and
+context providers.
+
+## 4. React 19 APIs (react19)
+
+**Impact:** MEDIUM  
+**Description:** React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
diff --git a/skills/vercel/composition-patterns/rules/_template.md b/skills/vercel/composition-patterns/rules/_template.md
new file mode 100644
index 0000000..119a301
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/_template.md
@@ -0,0 +1,24 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: brief description of impact
+tags: composition, components
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect:**
+
+```tsx
+// Bad code example
+```
+
+**Correct:**
+
+```tsx
+// Good code example
+```
+
+Reference: [Link](https://example.com)
diff --git a/skills/vercel/composition-patterns/rules/architecture-avoid-boolean-props.md b/skills/vercel/composition-patterns/rules/architecture-avoid-boolean-props.md
new file mode 100644
index 0000000..ccee19c
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/architecture-avoid-boolean-props.md
@@ -0,0 +1,100 @@
+---
+title: Avoid Boolean Prop Proliferation
+impact: CRITICAL
+impactDescription: prevents unmaintainable component variants
+tags: composition, props, architecture
+---
+
+## Avoid Boolean Prop Proliferation
+
+Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
+component behavior. Each boolean doubles possible states and creates
+unmaintainable conditional logic. Use composition instead.
+
+**Incorrect (boolean props create exponential complexity):**
+
+```tsx
+function Composer({
+  onSubmit,
+  isThread,
+  channelId,
+  isDMThread,
+  dmId,
+  isEditing,
+  isForwarding,
+}: Props) {
+  return (
+    <form>
+      <Header />
+      <Input />
+      {isDMThread ? (
+        <AlsoSendToDMField id={dmId} />
+      ) : isThread ? (
+        <AlsoSendToChannelField id={channelId} />
+      ) : null}
+      {isEditing ? (
+        <EditActions />
+      ) : isForwarding ? (
+        <ForwardActions />
+      ) : (
+        <DefaultActions />
+      )}
+      <Footer onSubmit={onSubmit} />
+    </form>
+  )
+}
+```
+
+**Correct (composition eliminates conditionals):**
+
+```tsx
+// Channel composer
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Attachments />
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Thread composer - adds "also send to channel" field
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <AlsoSendToChannelField id={channelId} />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Edit composer - different footer actions
+function EditComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.CancelEdit />
+        <Composer.SaveEdit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+```
+
+Each variant is explicit about what it renders. We can share internals without
+sharing a single monolithic parent.
diff --git a/skills/vercel/composition-patterns/rules/architecture-compound-components.md b/skills/vercel/composition-patterns/rules/architecture-compound-components.md
new file mode 100644
index 0000000..e5e3043
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/architecture-compound-components.md
@@ -0,0 +1,112 @@
+---
+title: Use Compound Components
+impact: HIGH
+impactDescription: enables flexible composition without prop drilling
+tags: composition, compound-components, architecture
+---
+
+## Use Compound Components
+
+Structure complex components as compound components with a shared context. Each
+subcomponent accesses shared state via context, not props. Consumers compose the
+pieces they need.
+
+**Incorrect (monolithic component with render props):**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+  showAttachments,
+  showFormatting,
+  showEmojis,
+}: Props) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {showAttachments && <Attachments />}
+      {renderFooter ? (
+        renderFooter()
+      ) : (
+        <Footer>
+          {showFormatting && <Formatting />}
+          {showEmojis && <Emojis />}
+          {renderActions?.()}
+        </Footer>
+      )}
+    </form>
+  )
+}
+```
+
+**Correct (compound components with shared context):**
+
+```tsx
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+
+function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
+  return (
+    <ComposerContext value={{ state, actions, meta }}>
+      {children}
+    </ComposerContext>
+  )
+}
+
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta: { inputRef },
+  } = use(ComposerContext)
+  return (
+    <TextInput
+      ref={inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+
+function ComposerSubmit() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Send</Button>
+}
+
+// Export as compound component
+const Composer = {
+  Provider: ComposerProvider,
+  Frame: ComposerFrame,
+  Input: ComposerInput,
+  Submit: ComposerSubmit,
+  Header: ComposerHeader,
+  Footer: ComposerFooter,
+  Attachments: ComposerAttachments,
+  Formatting: ComposerFormatting,
+  Emojis: ComposerEmojis,
+}
+```
+
+**Usage:**
+
+```tsx
+<Composer.Provider state={state} actions={actions} meta={meta}>
+  <Composer.Frame>
+    <Composer.Header />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Submit />
+    </Composer.Footer>
+  </Composer.Frame>
+</Composer.Provider>
+```
+
+Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
diff --git a/skills/vercel/composition-patterns/rules/patterns-children-over-render-props.md b/skills/vercel/composition-patterns/rules/patterns-children-over-render-props.md
new file mode 100644
index 0000000..d4345ee
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/patterns-children-over-render-props.md
@@ -0,0 +1,87 @@
+---
+title: Prefer Composing Children Over Render Props
+impact: MEDIUM
+impactDescription: cleaner composition, better readability
+tags: composition, children, render-props
+---
+
+## Prefer Children Over Render Props
+
+Use `children` for composition instead of `renderX` props. Children are more
+readable, compose naturally, and don't require understanding callback
+signatures.
+
+**Incorrect (render props):**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+}: {
+  renderHeader?: () => React.ReactNode
+  renderFooter?: () => React.ReactNode
+  renderActions?: () => React.ReactNode
+}) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {renderFooter ? renderFooter() : <DefaultFooter />}
+      {renderActions?.()}
+    </form>
+  )
+}
+
+// Usage is awkward and inflexible
+return (
+  <Composer
+    renderHeader={() => <CustomHeader />}
+    renderFooter={() => (
+      <>
+        <Formatting />
+        <Emojis />
+      </>
+    )}
+    renderActions={() => <SubmitButton />}
+  />
+)
+```
+
+**Correct (compound components with children):**
+
+```tsx
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerFooter({ children }: { children: React.ReactNode }) {
+  return <footer className='flex'>{children}</footer>
+}
+
+// Usage is flexible
+return (
+  <Composer.Frame>
+    <CustomHeader />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Emojis />
+      <SubmitButton />
+    </Composer.Footer>
+  </Composer.Frame>
+)
+```
+
+**When render props are appropriate:**
+
+```tsx
+// Render props work well when you need to pass data back
+<List
+  data={items}
+  renderItem={({ item, index }) => <Item item={item} index={index} />}
+/>
+```
+
+Use render props when the parent needs to provide data or state to the child.
+Use children when composing static structure.
diff --git a/skills/vercel/composition-patterns/rules/patterns-explicit-variants.md b/skills/vercel/composition-patterns/rules/patterns-explicit-variants.md
new file mode 100644
index 0000000..56e32e8
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/patterns-explicit-variants.md
@@ -0,0 +1,100 @@
+---
+title: Create Explicit Component Variants
+impact: MEDIUM
+impactDescription: self-documenting code, no hidden conditionals
+tags: composition, variants, architecture
+---
+
+## Create Explicit Component Variants
+
+Instead of one component with many boolean props, create explicit variant
+components. Each variant composes the pieces it needs. The code documents
+itself.
+
+**Incorrect (one component, many modes):**
+
+```tsx
+// What does this component actually render?
+<Composer
+  isThread
+  isEditing={false}
+  channelId='abc'
+  showAttachments
+  showFormatting={false}
+/>
+```
+
+**Correct (explicit variants):**
+
+```tsx
+// Immediately clear what this renders
+<ThreadComposer channelId="abc" />
+
+// Or
+<EditMessageComposer messageId="xyz" />
+
+// Or
+<ForwardMessageComposer messageId="123" />
+```
+
+Each implementation is unique, explicit and self-contained. Yet they can each
+use shared parts.
+
+**Implementation:**
+
+```tsx
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <ThreadProvider channelId={channelId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <AlsoSendToChannelField channelId={channelId} />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Submit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ThreadProvider>
+  )
+}
+
+function EditMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <EditMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.CancelEdit />
+          <Composer.SaveEdit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </EditMessageProvider>
+  )
+}
+
+function ForwardMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <ForwardMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input placeholder="Add a message, if you'd like." />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Mentions />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ForwardMessageProvider>
+  )
+}
+```
+
+Each variant is explicit about:
+
+- What provider/state it uses
+- What UI elements it includes
+- What actions are available
+
+No boolean prop combinations to reason about. No impossible states.
diff --git a/skills/vercel/composition-patterns/rules/react19-no-forwardref.md b/skills/vercel/composition-patterns/rules/react19-no-forwardref.md
new file mode 100644
index 0000000..e0d8f8a
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/react19-no-forwardref.md
@@ -0,0 +1,42 @@
+---
+title: React 19 API Changes
+impact: MEDIUM
+impactDescription: cleaner component definitions and context usage
+tags: react19, refs, context, hooks
+---
+
+## React 19 API Changes
+
+> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
+
+In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
+
+**Incorrect (forwardRef in React 19):**
+
+```tsx
+const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
+  return <TextInput ref={ref} {...props} />
+})
+```
+
+**Correct (ref as a regular prop):**
+
+```tsx
+function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
+  return <TextInput ref={ref} {...props} />
+}
+```
+
+**Incorrect (useContext in React 19):**
+
+```tsx
+const value = useContext(MyContext)
+```
+
+**Correct (use instead of useContext):**
+
+```tsx
+const value = use(MyContext)
+```
+
+`use()` can also be called conditionally, unlike `useContext()`.
diff --git a/skills/vercel/composition-patterns/rules/state-context-interface.md b/skills/vercel/composition-patterns/rules/state-context-interface.md
new file mode 100644
index 0000000..d961bed
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/state-context-interface.md
@@ -0,0 +1,191 @@
+---
+title: Define Generic Context Interfaces for Dependency Injection
+impact: HIGH
+impactDescription: enables dependency-injectable state across use-cases
+tags: composition, context, state, typescript, dependency-injection
+---
+
+## Define Generic Context Interfaces for Dependency Injection
+
+Define a **generic interface** for your component context with three parts:
+`state`, `actions`, and `meta`. This interface is a contract that any provider
+can implement—enabling the same UI components to work with completely different
+state implementations.
+
+**Core principle:** Lift state, compose internals, make state
+dependency-injectable.
+
+**Incorrect (UI coupled to specific state implementation):**
+
+```tsx
+function ComposerInput() {
+  // Tightly coupled to a specific hook
+  const { input, setInput } = useChannelComposerState()
+  return <TextInput value={input} onChangeText={setInput} />
+}
+```
+
+**Correct (generic interface enables dependency injection):**
+
+```tsx
+// Define a GENERIC interface that any provider can implement
+interface ComposerState {
+  input: string
+  attachments: Attachment[]
+  isSubmitting: boolean
+}
+
+interface ComposerActions {
+  update: (updater: (state: ComposerState) => ComposerState) => void
+  submit: () => void
+}
+
+interface ComposerMeta {
+  inputRef: React.RefObject<TextInput>
+}
+
+interface ComposerContextValue {
+  state: ComposerState
+  actions: ComposerActions
+  meta: ComposerMeta
+}
+
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+```
+
+**UI components consume the interface, not the implementation:**
+
+```tsx
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta,
+  } = use(ComposerContext)
+
+  // This component works with ANY provider that implements the interface
+  return (
+    <TextInput
+      ref={meta.inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+```
+
+**Different providers implement the same interface:**
+
+```tsx
+// Provider A: Local state for ephemeral forms
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const inputRef = useRef(null)
+  const submit = useForwardMessage()
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update: setState, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+
+// Provider B: Global synced state for channels
+function ChannelProvider({ channelId, children }: Props) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+```
+
+**The same composed UI works with both:**
+
+```tsx
+// Works with ForwardMessageProvider (local state)
+<ForwardMessageProvider>
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ForwardMessageProvider>
+
+// Works with ChannelProvider (global synced state)
+<ChannelProvider channelId="abc">
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ChannelProvider>
+```
+
+**Custom UI outside the component can access state and actions:**
+
+The provider boundary is what matters—not the visual nesting. Components that
+need shared state don't have to be inside the `Composer.Frame`. They just need
+to be within the provider.
+
+```tsx
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        {/* The composer UI */}
+        <Composer.Frame>
+          <Composer.Input placeholder="Add a message, if you'd like." />
+          <Composer.Footer>
+            <Composer.Formatting />
+            <Composer.Emojis />
+          </Composer.Footer>
+        </Composer.Frame>
+
+        {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
+        <MessagePreview />
+
+        {/* Actions at the bottom of the dialog */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton />
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
+function ForwardButton() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Forward</Button>
+}
+
+// This preview lives OUTSIDE Composer.Frame but can read composer's state!
+function MessagePreview() {
+  const { state } = use(ComposerContext)
+  return <Preview message={state.input} attachments={state.attachments} />
+}
+```
+
+The `ForwardButton` and `MessagePreview` are not visually inside the composer
+box, but they can still access its state and actions. This is the power of
+lifting state into providers.
+
+The UI is reusable bits you compose together. The state is dependency-injected
+by the provider. Swap the provider, keep the UI.
diff --git a/skills/vercel/composition-patterns/rules/state-decouple-implementation.md b/skills/vercel/composition-patterns/rules/state-decouple-implementation.md
new file mode 100644
index 0000000..71a5afa
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/state-decouple-implementation.md
@@ -0,0 +1,113 @@
+---
+title: Decouple State Management from UI
+impact: MEDIUM
+impactDescription: enables swapping state implementations without changing UI
+tags: composition, state, architecture
+---
+
+## Decouple State Management from UI
+
+The provider component should be the only place that knows how state is managed.
+UI components consume the context interface—they don't know if state comes from
+useState, Zustand, or a server sync.
+
+**Incorrect (UI coupled to state implementation):**
+
+```tsx
+function ChannelComposer({ channelId }: { channelId: string }) {
+  // UI component knows about global state implementation
+  const state = useGlobalChannelState(channelId)
+  const { submit, updateInput } = useChannelSync(channelId)
+
+  return (
+    <Composer.Frame>
+      <Composer.Input
+        value={state.input}
+        onChange={(text) => sync.updateInput(text)}
+      />
+      <Composer.Submit onPress={() => sync.submit()} />
+    </Composer.Frame>
+  )
+}
+```
+
+**Correct (state management isolated in provider):**
+
+```tsx
+// Provider handles all state management details
+function ChannelProvider({
+  channelId,
+  children,
+}: {
+  channelId: string
+  children: React.ReactNode
+}) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update, submit }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// UI component only knows about the context interface
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Usage
+function Channel({ channelId }: { channelId: string }) {
+  return (
+    <ChannelProvider channelId={channelId}>
+      <ChannelComposer />
+    </ChannelProvider>
+  )
+}
+```
+
+**Different providers, same UI:**
+
+```tsx
+// Local state for ephemeral forms
+function ForwardMessageProvider({ children }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// Global synced state for channels
+function ChannelProvider({ channelId, children }) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+
+  return (
+    <Composer.Provider state={state} actions={{ update, submit }}>
+      {children}
+    </Composer.Provider>
+  )
+}
+```
+
+The same `Composer.Input` component works with both providers because it only
+depends on the context interface, not the implementation.
diff --git a/skills/vercel/composition-patterns/rules/state-lift-state.md b/skills/vercel/composition-patterns/rules/state-lift-state.md
new file mode 100644
index 0000000..d7fe27b
--- /dev/null
+++ b/skills/vercel/composition-patterns/rules/state-lift-state.md
@@ -0,0 +1,125 @@
+---
+title: Lift State into Provider Components
+impact: HIGH
+impactDescription: enables state sharing outside component boundaries
+tags: composition, state, context, providers
+---
+
+## Lift State into Provider Components
+
+Move state management into dedicated provider components. This allows sibling
+components outside the main UI to access and modify state without prop drilling
+or awkward refs.
+
+**Incorrect (state trapped inside component):**
+
+```tsx
+function ForwardMessageComposer() {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer />
+    </Composer.Frame>
+  )
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+  return (
+    <Dialog>
+      <ForwardMessageComposer />
+      <MessagePreview /> {/* Needs composer state */}
+      <DialogActions>
+        <CancelButton />
+        <ForwardButton /> {/* Needs to call submit */}
+      </DialogActions>
+    </Dialog>
+  )
+}
+```
+
+**Incorrect (useEffect to sync state up):**
+
+```tsx
+function ForwardMessageDialog() {
+  const [input, setInput] = useState('')
+  return (
+    <Dialog>
+      <ForwardMessageComposer onInputChange={setInput} />
+      <MessagePreview input={input} />
+    </Dialog>
+  )
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+  const [state, setState] = useState(initialState)
+  useEffect(() => {
+    onInputChange(state.input) // Sync on every change 😬
+  }, [state.input])
+}
+```
+
+**Incorrect (reading state from ref on submit):**
+
+```tsx
+function ForwardMessageDialog() {
+  const stateRef = useRef(null)
+  return (
+    <Dialog>
+      <ForwardMessageComposer stateRef={stateRef} />
+      <ForwardButton onPress={() => submit(stateRef.current)} />
+    </Dialog>
+  )
+}
+```
+
+**Correct (state lifted to provider):**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        <ForwardMessageComposer />
+        <MessagePreview /> {/* Custom components can access state and actions */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton /> {/* Custom components can access state and actions */}
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+function ForwardButton() {
+  const { actions } = use(Composer.Context)
+  return <Button onPress={actions.submit}>Forward</Button>
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+submit action because it's within the provider. Even though it's a one-off
+component, it can still access the composer's state and actions from outside the
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+nested inside each other—they just need to be within the same provider.
diff --git a/skills/vercel/deploy-to-vercel/SKILL.md b/skills/vercel/deploy-to-vercel/SKILL.md
new file mode 100644
index 0000000..a0251ce
--- /dev/null
+++ b/skills/vercel/deploy-to-vercel/SKILL.md
@@ -0,0 +1,296 @@
+---
+name: deploy-to-vercel
+description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
+metadata:
+  author: vercel
+  version: "3.0.0"
+---
+
+# Deploy to Vercel
+
+Deploy any project to Vercel. **Always deploy as preview** (not production) unless the user explicitly asks for production.
+
+The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.
+
+## Step 1: Gather Project State
+
+Run all four checks before deciding which method to use:
+
+```bash
+# 1. Check for a git remote
+git remote get-url origin 2>/dev/null
+
+# 2. Check if locally linked to a Vercel project (either file means linked)
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+
+# 3. Check if the Vercel CLI is installed and authenticated
+vercel whoami 2>/dev/null
+
+# 4. List available teams (if authenticated)
+vercel teams list --format json 2>/dev/null
+```
+
+### Team selection
+
+If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.
+
+Pass the team slug via `--scope` on all subsequent CLI commands (`vercel deploy`, `vercel link`, `vercel inspect`, etc.):
+
+```bash
+vercel deploy [path] -y --no-wait --scope <team-slug>
+```
+
+If the project is already linked (`.vercel/project.json` or `.vercel/repo.json` exists), the `orgId` in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.
+
+**About the `.vercel/` directory:** A linked project has either:
+- `.vercel/project.json` — created by `vercel link` (single project linking). Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — created by `vercel link --repo` (repo-based linking). Contains `orgId`, `remoteName`, and a `projects` array mapping directories to Vercel project IDs.
+
+Either file means the project is linked. Check for both.
+
+**Do NOT** use `vercel project inspect`, `vercel ls`, or `vercel link` to detect state in an unlinked directory — without a `.vercel/` config, they will interactively prompt (or with `--yes`, silently link as a side-effect). Only `vercel whoami` is safe to run anywhere.
+
+## Step 2: Choose a Deploy Method
+
+### Linked (`.vercel/` exists) + has git remote → Git Push
+
+This is the ideal state. The project is linked and has git integration.
+
+1. **Ask the user before pushing.** Never push without explicit approval:
+   ```
+   This project is connected to Vercel via git. I can commit and push to
+   trigger a deployment. Want me to proceed?
+   ```
+
+2. **Commit and push:**
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+   Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually `main`) gets a production deployment.
+
+3. **Retrieve the preview URL.** If the CLI is authenticated:
+   ```bash
+   sleep 5
+   vercel ls --format json
+   ```
+   The JSON output has a `deployments` array. Find the latest entry — its `url` field is the preview URL.
+
+   If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.
+
+---
+
+### Linked (`.vercel/` exists) + no git remote → `vercel deploy`
+
+The project is linked but there's no git repo. Deploy directly with the CLI.
+
+```bash
+vercel deploy [path] -y --no-wait
+```
+
+Use `--no-wait` so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+For production deploys (only if user explicitly asks):
+```bash
+vercel deploy [path] --prod -y --no-wait
+```
+
+---
+
+### Not linked + CLI is authenticated → Link first, then deploy
+
+The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.
+
+1. **Ask the user which team to deploy to.** Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.
+
+2. **Once a team is selected, proceed directly to linking.** Tell the user what will happen but do not ask for separate confirmation:
+   ```
+   Linking this project to <team name> on Vercel. This will create a Vercel
+   project to deploy to and enable automatic deployments on future git pushes.
+   ```
+
+3. **If a git remote exists**, use repo-based linking with the selected team scope:
+   ```bash
+   vercel link --repo --scope <team-slug>
+   ```
+   This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates `.vercel/repo.json`. This is much more reliable than `vercel link` (without `--repo`), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
+
+   **If there is no git remote**, fall back to standard linking:
+   ```bash
+   vercel link --scope <team-slug>
+   ```
+   This prompts the user to select or create a project. It creates `.vercel/project.json`.
+
+4. **Then deploy using the best available method:**
+   - If a git remote exists → commit and push (see git push method above)
+   - If no git remote → `vercel deploy [path] -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status
+
+---
+
+### Not linked + CLI not authenticated → Install, auth, link, deploy
+
+The Vercel CLI isn't set up at all.
+
+1. **Install the CLI (if not already installed):**
+   ```bash
+   npm install -g vercel
+   ```
+
+2. **Authenticate:**
+   ```bash
+   vercel login
+   ```
+   The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the **no-auth fallback** below.
+
+3. **Ask which team to deploy to** — present team slugs from `vercel teams list --format json` as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.
+
+4. **Link the project** with the selected team scope (use `--repo` if a git remote exists, plain `vercel link` otherwise):
+   ```bash
+   vercel link --repo --scope <team-slug>   # if git remote exists
+   vercel link --scope <team-slug>          # if no git remote
+   ```
+
+5. **Deploy** using the best available method (git push if remote exists, otherwise `vercel deploy -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status).
+
+---
+
+### No-Auth Fallback — claude.ai sandbox
+
+**When to use:** Last resort when the CLI can't be installed or authenticated in the claude.ai sandbox. This requires no authentication — it returns a **Preview URL** (live site) and a **Claim URL** (transfer to your Vercel account).
+
+```bash
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
+```
+
+**Arguments:**
+- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
+
+**Examples:**
+```bash
+# Deploy current directory
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
+
+# Deploy specific project
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
+
+# Deploy existing tarball
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
+```
+
+The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+---
+
+### No-Auth Fallback — Codex sandbox
+
+**When to use:** In the Codex sandbox where the CLI may not be authenticated. Codex runs in a sandboxed environment by default — try the CLI first, and fall back to the deploy script if auth fails.
+
+1. **Check whether the Vercel CLI is installed** (no escalation needed for this check):
+   ```bash
+   command -v vercel
+   ```
+
+2. **If `vercel` is installed**, try deploying with the CLI:
+   ```bash
+   vercel deploy [path] -y --no-wait
+   ```
+
+3. **If `vercel` is not installed, or the CLI fails with "No existing credentials found"**, use the fallback script:
+   ```bash
+   skill_dir="<path-to-skill>"
+
+   # Deploy current directory
+   bash "$skill_dir/resources/deploy-codex.sh"
+
+   # Deploy specific project
+   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
+
+   # Deploy existing tarball
+   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
+   ```
+
+The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+**Escalated network access:** Only escalate the actual deploy command if sandboxing blocks the network call (`sandbox_permissions=require_escalated`). Do **not** escalate the `command -v vercel` check.
+
+---
+
+## Agent-Specific Notes
+
+### Claude Code / terminal-based agents
+
+You have full shell access. Do NOT use the `/mnt/skills/` path. Follow the decision flow above using the CLI directly.
+
+For the no-auth fallback, run the deploy script from the skill's installed location:
+```bash
+bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
+```
+The path may vary depending on where the user installed the skill.
+
+### Sandboxed environments (claude.ai)
+
+You likely cannot run `vercel login` or `git push`. Go directly to the **no-auth fallback — claude.ai sandbox**.
+
+### Codex
+
+Codex runs in a sandbox. Check if the CLI is available first, then fall back to the deploy script. Go to the **no-auth fallback — Codex sandbox**.
+
+---
+
+## Output
+
+Always show the user the deployment URL.
+
+- **Git push:** Use `vercel ls --format json` to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
+- **CLI deploy:** Show the URL returned by `vercel deploy --no-wait`. Use `vercel inspect <url>` to check build status and report it to the user.
+- **No-auth fallback:** Show both the preview URL and the claim URL:
+  ```
+  Deployment successful!
+
+  Preview URL: https://my-app-abc123.vercel.app
+  Claim URL:   https://vercel.com/claim-deployment?code=...
+
+  View your site at the Preview URL.
+  To transfer this deployment to your Vercel account, visit the Claim URL.
+  ```
+
+**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
+
+---
+
+## Troubleshooting
+
+### Network Egress Error (claude.ai)
+
+If deployment fails due to network restrictions on claude.ai, tell the user:
+
+```
+Deployment failed due to network restrictions. To fix this:
+
+1. Go to https://claude.ai/settings/capabilities
+2. Add *.vercel.com to the allowed domains
+3. Try deploying again
+```
+
+### Escalated Network Access (Codex / sandboxed environments)
+
+If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (`sandbox_permissions=require_escalated`). Do not escalate the initial CLI availability check — only escalate the actual deploy command.
+
+Example guidance to the user:
+```
+The deploy needs escalated network access to deploy to Vercel. I can rerun
+the command with escalated permissions — want me to proceed?
+```
+
+### CLI Auth Failure
+
+If `vercel login` or `vercel deploy` fails with authentication errors, fall back to the no-auth deploy script (claude.ai or Codex variant, depending on the environment).
diff --git a/skills/vercel/deploy-to-vercel/resources/deploy-codex.sh b/skills/vercel/deploy-to-vercel/resources/deploy-codex.sh
new file mode 100755
index 0000000..af07d0f
--- /dev/null
+++ b/skills/vercel/deploy-to-vercel/resources/deploy-codex.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script for Codex (via claimable deploy endpoint)
+# Usage: ./deploy-codex.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://codex-deploy-skills.vercel.sh/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+    local pkg_json="$1"
+
+    if [ ! -f "$pkg_json" ]; then
+        echo "null"
+        return
+    fi
+
+    local content=$(cat "$pkg_json")
+
+    # Helper to check if a package exists in dependencies or devDependencies.
+    # Use exact matching by default, with a separate prefix matcher for scoped
+    # package families like "@remix-run/".
+    has_dep_exact() {
+        echo "$content" | grep -q "\"$1\""
+    }
+
+    has_dep_prefix() {
+        echo "$content" | grep -q "\"$1"
+    }
+
+    # Order matters - check more specific frameworks first
+
+    # Blitz
+    if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+    # Next.js
+    if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+    # Gatsby
+    if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+    # Remix
+    if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+    # React Router (v7 framework mode)
+    if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+    # TanStack Start
+    if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+    # Astro
+    if has_dep_exact "astro"; then echo "astro"; return; fi
+
+    # Hydrogen (Shopify)
+    if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+    # SvelteKit
+    if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+    # Svelte (standalone)
+    if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+    # Nuxt
+    if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+    # Vue with Vitepress
+    if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+    # Vue with Vuepress
+    if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+    # Gridsome
+    if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+    # SolidStart
+    if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+    # Docusaurus
+    if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+    # RedwoodJS
+    if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+    # Hexo
+    if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+    # Eleventy
+    if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+    # Angular / Ionic Angular
+    if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+    if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+    # Ionic React
+    if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+    # Create React App
+    if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+    # Ember
+    if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+    # Dojo
+    if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+    # Polymer
+    if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+    # Preact
+    if has_dep_exact "preact"; then echo "preact"; return; fi
+
+    # Stencil
+    if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+    # UmiJS
+    if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+    # Sapper (legacy Svelte)
+    if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+    # Saber
+    if has_dep_exact "saber"; then echo "saber"; return; fi
+
+    # Sanity
+    if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+    if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+    # Storybook
+    if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+    # NestJS
+    if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+    # Elysia
+    if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+    # Hono
+    if has_dep_exact "hono"; then echo "hono"; return; fi
+
+    # Fastify
+    if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+    # h3
+    if has_dep_exact "h3"; then echo "h3"; return; fi
+
+    # Nitro
+    if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+    # Express
+    if has_dep_exact "express"; then echo "express"; return; fi
+
+    # Vite (generic - check last among JS frameworks)
+    if has_dep_exact "vite"; then echo "vite"; return; fi
+
+    # Parcel
+    if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+    # No framework detected
+    echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+    if [ "$CLEANUP_TEMP" = true ]; then
+        rm -rf "$TEMP_DIR"
+    fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+    # Input is already a tarball, use it directly
+    echo "Using provided tarball..." >&2
+    TARBALL="$INPUT_PATH"
+    CLEANUP_TEMP=false
+    # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+    # Input is a directory, need to tar it
+    PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+    # Detect framework from package.json
+    FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+    # Stage files into a temporary directory to avoid mutating the source tree.
+    mkdir -p "$STAGING_DIR"
+    echo "Staging project files..." >&2
+    tar -C "$PROJECT_PATH" \
+        --exclude='node_modules' \
+        --exclude='.git' \
+        --exclude='.env' \
+        --exclude='.env.*' \
+        -cf - . | tar -C "$STAGING_DIR" -xf -
+
+    # Check if this is a static HTML project (no package.json)
+    if [ ! -f "$PROJECT_PATH/package.json" ]; then
+        # Find HTML files in root
+        HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+        HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+        # If there's exactly one HTML file and it's not index.html, rename it
+        if [ "$HTML_COUNT" -eq 1 ]; then
+            HTML_FILE=$(echo "$HTML_FILES" | head -1)
+            BASENAME=$(basename "$HTML_FILE")
+            if [ "$BASENAME" != "index.html" ]; then
+                echo "Renaming $BASENAME to index.html..." >&2
+                mv "$HTML_FILE" "$STAGING_DIR/index.html"
+            fi
+        fi
+    fi
+
+    # Create tarball from the staging directory
+    echo "Creating deployment package..." >&2
+    tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+    echo "Error: Input must be a directory or a .tgz file" >&2
+    exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+    echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+    ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+    echo "Error: $ERROR_MSG" >&2
+    exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+    echo "Error: Could not extract preview URL from response" >&2
+    echo "$RESPONSE" >&2
+    exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60  # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+    HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+    if [ "$HTTP_STATUS" -eq 200 ]; then
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    elif [ "$HTTP_STATUS" -ge 500 ]; then
+        # 5xx means still building/deploying
+        echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+        sleep 5
+        ATTEMPT=$((ATTEMPT + 1))
+    elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+        # 4xx might be an error or the app itself returns 4xx - it's responding
+        echo "" >&2
+        echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+        break
+    else
+        # Any other status, assume it's ready
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+    echo "" >&2
+    echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL:   $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/skills/vercel/deploy-to-vercel/resources/deploy.sh b/skills/vercel/deploy-to-vercel/resources/deploy.sh
new file mode 100755
index 0000000..a458da6
--- /dev/null
+++ b/skills/vercel/deploy-to-vercel/resources/deploy.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script (via claimable deploy endpoint)
+# Usage: ./deploy.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://claude-skills-deploy.vercel.com/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+    local pkg_json="$1"
+
+    if [ ! -f "$pkg_json" ]; then
+        echo "null"
+        return
+    fi
+
+    local content=$(cat "$pkg_json")
+
+    # Helper to check if a package exists in dependencies or devDependencies.
+    # Use exact matching by default, with a separate prefix matcher for scoped
+    # package families like "@remix-run/".
+    has_dep_exact() {
+        echo "$content" | grep -q "\"$1\""
+    }
+
+    has_dep_prefix() {
+        echo "$content" | grep -q "\"$1"
+    }
+
+    # Order matters - check more specific frameworks first
+
+    # Blitz
+    if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+    # Next.js
+    if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+    # Gatsby
+    if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+    # Remix
+    if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+    # React Router (v7 framework mode)
+    if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+    # TanStack Start
+    if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+    # Astro
+    if has_dep_exact "astro"; then echo "astro"; return; fi
+
+    # Hydrogen (Shopify)
+    if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+    # SvelteKit
+    if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+    # Svelte (standalone)
+    if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+    # Nuxt
+    if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+    # Vue with Vitepress
+    if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+    # Vue with Vuepress
+    if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+    # Gridsome
+    if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+    # SolidStart
+    if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+    # Docusaurus
+    if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+    # RedwoodJS
+    if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+    # Hexo
+    if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+    # Eleventy
+    if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+    # Angular / Ionic Angular
+    if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+    if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+    # Ionic React
+    if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+    # Create React App
+    if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+    # Ember
+    if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+    # Dojo
+    if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+    # Polymer
+    if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+    # Preact
+    if has_dep_exact "preact"; then echo "preact"; return; fi
+
+    # Stencil
+    if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+    # UmiJS
+    if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+    # Sapper (legacy Svelte)
+    if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+    # Saber
+    if has_dep_exact "saber"; then echo "saber"; return; fi
+
+    # Sanity
+    if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+    if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+    # Storybook
+    if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+    # NestJS
+    if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+    # Elysia
+    if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+    # Hono
+    if has_dep_exact "hono"; then echo "hono"; return; fi
+
+    # Fastify
+    if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+    # h3
+    if has_dep_exact "h3"; then echo "h3"; return; fi
+
+    # Nitro
+    if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+    # Express
+    if has_dep_exact "express"; then echo "express"; return; fi
+
+    # Vite (generic - check last among JS frameworks)
+    if has_dep_exact "vite"; then echo "vite"; return; fi
+
+    # Parcel
+    if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+    # No framework detected
+    echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+    if [ "$CLEANUP_TEMP" = true ]; then
+        rm -rf "$TEMP_DIR"
+    fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+    # Input is already a tarball, use it directly
+    echo "Using provided tarball..." >&2
+    TARBALL="$INPUT_PATH"
+    CLEANUP_TEMP=false
+    # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+    # Input is a directory, need to tar it
+    PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+    # Detect framework from package.json
+    FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+    # Stage files into a temporary directory to avoid mutating the source tree.
+    mkdir -p "$STAGING_DIR"
+    echo "Staging project files..." >&2
+    tar -C "$PROJECT_PATH" \
+        --exclude='node_modules' \
+        --exclude='.git' \
+        --exclude='.env' \
+        --exclude='.env.*' \
+        -cf - . | tar -C "$STAGING_DIR" -xf -
+
+    # Check if this is a static HTML project (no package.json)
+    if [ ! -f "$PROJECT_PATH/package.json" ]; then
+        # Find HTML files in root
+        HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+        HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+        # If there's exactly one HTML file and it's not index.html, rename it
+        if [ "$HTML_COUNT" -eq 1 ]; then
+            HTML_FILE=$(echo "$HTML_FILES" | head -1)
+            BASENAME=$(basename "$HTML_FILE")
+            if [ "$BASENAME" != "index.html" ]; then
+                echo "Renaming $BASENAME to index.html..." >&2
+                mv "$HTML_FILE" "$STAGING_DIR/index.html"
+            fi
+        fi
+    fi
+
+    # Create tarball from the staging directory
+    echo "Creating deployment package..." >&2
+    tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+    echo "Error: Input must be a directory or a .tgz file" >&2
+    exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+    echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+    ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+    echo "Error: $ERROR_MSG" >&2
+    exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+    echo "Error: Could not extract preview URL from response" >&2
+    echo "$RESPONSE" >&2
+    exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60  # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+    HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+    if [ "$HTTP_STATUS" -eq 200 ]; then
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    elif [ "$HTTP_STATUS" -ge 500 ]; then
+        # 5xx means still building/deploying
+        echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+        sleep 5
+        ATTEMPT=$((ATTEMPT + 1))
+    elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+        # 4xx might be an error or the app itself returns 4xx - it's responding
+        echo "" >&2
+        echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+        break
+    else
+        # Any other status, assume it's ready
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+    echo "" >&2
+    echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL:   $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/skills/vercel/react-best-practices/AGENTS.md b/skills/vercel/react-best-practices/AGENTS.md
new file mode 100644
index 0000000..4e340a5
--- /dev/null
+++ b/skills/vercel/react-best-practices/AGENTS.md
@@ -0,0 +1,3810 @@
+# React Best Practices
+
+**Version 1.0.0**  
+Vercel Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React and Next.js codebases. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
+   - 1.1 [Check Cheap Conditions Before Async Flags](#11-check-cheap-conditions-before-async-flags)
+   - 1.2 [Defer Await Until Needed](#12-defer-await-until-needed)
+   - 1.3 [Dependency-Based Parallelization](#13-dependency-based-parallelization)
+   - 1.4 [Prevent Waterfall Chains in API Routes](#14-prevent-waterfall-chains-in-api-routes)
+   - 1.5 [Promise.all() for Independent Operations](#15-promiseall-for-independent-operations)
+   - 1.6 [Strategic Suspense Boundaries](#16-strategic-suspense-boundaries)
+2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
+   - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
+   - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
+   - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
+   - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
+   - 2.5 [Prefer Statically Analyzable Paths](#25-prefer-statically-analyzable-paths)
+   - 2.6 [Preload Based on User Intent](#26-preload-based-on-user-intent)
+3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
+   - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
+   - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
+   - 3.3 [Avoid Shared Module State for Request Data](#33-avoid-shared-module-state-for-request-data)
+   - 3.4 [Cross-Request LRU Caching](#34-cross-request-lru-caching)
+   - 3.5 [Hoist Static I/O to Module Level](#35-hoist-static-io-to-module-level)
+   - 3.6 [Minimize Serialization at RSC Boundaries](#36-minimize-serialization-at-rsc-boundaries)
+   - 3.7 [Parallel Data Fetching with Component Composition](#37-parallel-data-fetching-with-component-composition)
+   - 3.8 [Parallel Nested Data Fetching](#38-parallel-nested-data-fetching)
+   - 3.9 [Per-Request Deduplication with React.cache()](#39-per-request-deduplication-with-reactcache)
+   - 3.10 [Use after() for Non-Blocking Operations](#310-use-after-for-non-blocking-operations)
+4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
+   - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
+   - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
+   - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
+   - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
+5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
+   - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering)
+   - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point)
+   - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
+   - 5.4 [Don't Define Components Inside Components](#54-dont-define-components-inside-components)
+   - 5.5 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#55-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
+   - 5.6 [Extract to Memoized Components](#56-extract-to-memoized-components)
+   - 5.7 [Narrow Effect Dependencies](#57-narrow-effect-dependencies)
+   - 5.8 [Put Interaction Logic in Event Handlers](#58-put-interaction-logic-in-event-handlers)
+   - 5.9 [Split Combined Hook Computations](#59-split-combined-hook-computations)
+   - 5.10 [Subscribe to Derived State](#510-subscribe-to-derived-state)
+   - 5.11 [Use Functional setState Updates](#511-use-functional-setstate-updates)
+   - 5.12 [Use Lazy State Initialization](#512-use-lazy-state-initialization)
+   - 5.13 [Use Transitions for Non-Urgent Updates](#513-use-transitions-for-non-urgent-updates)
+   - 5.14 [Use useDeferredValue for Expensive Derived Renders](#514-use-usedeferredvalue-for-expensive-derived-renders)
+   - 5.15 [Use useRef for Transient Values](#515-use-useref-for-transient-values)
+6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
+   - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
+   - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
+   - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
+   - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
+   - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
+   - 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches)
+   - 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide)
+   - 6.8 [Use defer or async on Script Tags](#68-use-defer-or-async-on-script-tags)
+   - 6.9 [Use Explicit Conditional Rendering](#69-use-explicit-conditional-rendering)
+   - 6.10 [Use React DOM Resource Hints](#610-use-react-dom-resource-hints)
+   - 6.11 [Use useTransition Over Manual Loading States](#611-use-usetransition-over-manual-loading-states)
+7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
+   - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
+   - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
+   - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
+   - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
+   - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
+   - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
+   - 7.7 [Defer Non-Critical Work with requestIdleCallback](#77-defer-non-critical-work-with-requestidlecallback)
+   - 7.8 [Early Length Check for Array Comparisons](#78-early-length-check-for-array-comparisons)
+   - 7.9 [Early Return from Functions](#79-early-return-from-functions)
+   - 7.10 [Hoist RegExp Creation](#710-hoist-regexp-creation)
+   - 7.11 [Use flatMap to Map and Filter in One Pass](#711-use-flatmap-to-map-and-filter-in-one-pass)
+   - 7.12 [Use Loop for Min/Max Instead of Sort](#712-use-loop-for-minmax-instead-of-sort)
+   - 7.13 [Use Set/Map for O(1) Lookups](#713-use-setmap-for-o1-lookups)
+   - 7.14 [Use toSorted() Instead of sort() for Immutability](#714-use-tosorted-instead-of-sort-for-immutability)
+8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
+   - 8.1 [Do Not Put Effect Events in Dependency Arrays](#81-do-not-put-effect-events-in-dependency-arrays)
+   - 8.2 [Initialize App Once, Not Per Mount](#82-initialize-app-once-not-per-mount)
+   - 8.3 [Store Event Handlers in Refs](#83-store-event-handlers-in-refs)
+   - 8.4 [useEffectEvent for Stable Callback Refs](#84-useeffectevent-for-stable-callback-refs)
+
+---
+
+## 1. Eliminating Waterfalls
+
+**Impact: CRITICAL**
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+### 1.1 Check Cheap Conditions Before Async Flags
+
+**Impact: HIGH (avoids unnecessary async work when a synchronous guard already fails)**
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag()
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag()
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.
+
+### 1.2 Defer Await Until Needed
+
+**Impact: HIGH (avoids blocking unused code paths)**
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect: blocks both branches**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct: only blocks when needed**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example: early return optimization**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).
+
+### 1.3 Dependency-Based Parallelization
+
+**Impact: CRITICAL (2-10× improvement)**
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect: profile waits for config unnecessarily**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct: config and profile run in parallel**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+### 1.4 Prevent Waterfall Chains in API Routes
+
+**Impact: CRITICAL (2-10× improvement)**
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect: config waits for auth, data waits for both**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct: auth and config start immediately**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
+
+### 1.5 Promise.all() for Independent Operations
+
+**Impact: CRITICAL (2-10× improvement)**
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect: sequential execution, 3 round trips**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct: parallel execution, 1 round trip**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### 1.6 Strategic Suspense Boundaries
+
+**Impact: HIGH (faster initial paint)**
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect: wrapper blocked by data fetching**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct: wrapper shows immediately, data streams in**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative: share promise across components**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+
+- SEO-critical content above the fold
+
+- Small, fast queries where suspense overhead isn't worth it
+
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL**
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### 2.1 Avoid Barrel File Imports
+
+**Impact: CRITICAL (200-800ms import cost, slow builds)**
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect: imports entire library**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct - Next.js 13.5+ (recommended):**
+
+```tsx
+// Keep the standard imports - Next.js transforms them to direct imports
+import { Check, X, Menu } from 'lucide-react'
+// Full TypeScript support, no manual path wrangling
+```
+
+This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
+
+**Correct - Direct imports (non-Next.js projects):**
+
+```tsx
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
+
+These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+### 2.2 Conditional Module Loading
+
+**Impact: HIGH (loads large data only when needed)**
+
+Load large data or modules only when a feature is activated.
+
+**Example: lazy-load animation frames**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
+
+### 2.3 Defer Non-Critical Third-Party Libraries
+
+**Impact: MEDIUM (loads after hydration)**
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect: blocks initial bundle**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct: loads after hydration**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+### 2.4 Dynamic Imports for Heavy Components
+
+**Impact: CRITICAL (directly affects TTI and LCP)**
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect: Monaco bundles with main chunk ~300KB**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct: Monaco loads on demand**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+### 2.5 Prefer Statically Analyzable Paths
+
+**Impact: HIGH (avoids accidental broad bundles and file traces)**
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+
+- Larger server bundles
+
+- Slower builds
+
+- Worse cold starts
+
+- More memory use
+
+**Incorrect: the bundler cannot tell what may be imported**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct: use an explicit map of allowed modules**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+**Incorrect: a 2-value enum still hides the final path from static analysis**
+
+```ts
+const baseDir = path.join(process.cwd(), 'content/' + contentKind)
+```
+
+**Correct: make each final path literal at the callsite**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [https://nextjs.org/docs/app/api-reference/config/next-config-js/output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [https://nextjs.org/learn/seo/dynamic-imports](https://nextjs.org/learn/seo/dynamic-imports), [https://vite.dev/guide/features.html](https://vite.dev/guide/features.html), [https://esbuild.github.io/api/](https://esbuild.github.io/api/), [https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [https://webpack.js.org/guides/dependency-management/](https://webpack.js.org/guides/dependency-management/)
+
+### 2.6 Preload Based on User Intent
+
+**Impact: MEDIUM (reduces perceived latency)**
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example: preload on hover/focus**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example: preload when feature flag is enabled**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
+
+---
+
+## 3. Server-Side Performance
+
+**Impact: HIGH**
+
+Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+### 3.1 Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect: no authentication check**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct: authentication inside the action**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
+
+### 3.2 Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect: duplicates array**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct: sends 3 strings**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+**Operations breaking deduplication: create new references**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
+
+### 3.3 Avoid Shared Module State for Request Data
+
+**Impact: HIGH (prevents concurrency bugs and request data leaks)**
+
+For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
+
+Treat module scope on the server as process-wide shared memory, not request-local state.
+
+**Incorrect: request data leaks across concurrent renders**
+
+```tsx
+let currentUser: User | null = null
+
+export default async function Page() {
+  currentUser = await auth()
+  return <Dashboard />
+}
+
+async function Dashboard() {
+  return <div>{currentUser?.name}</div>
+}
+```
+
+If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
+
+**Correct: keep request data local to the render tree**
+
+```tsx
+export default async function Page() {
+  const user = await auth()
+  return <Dashboard user={user} />
+}
+
+function Dashboard({ user }: { user: User | null }) {
+  return <div>{user?.name}</div>
+}
+```
+
+Safe exceptions:
+
+- Immutable static assets or config loaded once at module scope
+
+- Shared caches intentionally designed for cross-request reuse and keyed correctly
+
+- Process-wide singletons that do not store request- or user-specific mutable data
+
+For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).
+
+### 3.4 Cross-Request LRU Caching
+
+**Impact: HIGH (caches across requests)**
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+
+### 3.5 Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect: reads font file on every request**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct: loads once at module initialization**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Correct: synchronous fs at module level**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Incorrect: reads config on every call**
+
+```typescript
+import fs from 'node:fs/promises'
+
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+
+  return render(template, data, config)
+}
+```
+
+**Correct: hoists config and template to module level**
+
+```typescript
+import fs from 'node:fs/promises'
+
+const configPromise = fs
+  .readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ])
+
+  return render(template, data, config)
+}
+```
+
+When to use this pattern:
+
+- Loading fonts for OG image generation
+
+- Loading static logos, icons, or watermarks
+
+- Reading configuration files that don't change at runtime
+
+- Loading email templates or other static templates
+
+- Any static asset that's the same across all requests
+
+When not to use this pattern:
+
+- Assets that vary per request or user
+
+- Files that may change during runtime (use caching with TTL instead)
+
+- Large files that would consume too much memory if kept loaded
+
+- Sensitive data that shouldn't persist in memory
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
+
+### 3.6 Minimize Serialization at RSC Boundaries
+
+**Impact: HIGH (reduces data transfer size)**
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect: serializes all 50 fields**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct: serializes only 1 field**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
+
+### 3.7 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect: Sidebar waits for Page's fetch to complete**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct: both fetch simultaneously**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
+
+### 3.8 Parallel Nested Data Fetching
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect: a single slow item blocks all nested fetches**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct: each item chains its own nested fetch**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.
+
+### 3.9 Per-Request Deduplication with React.cache()
+
+**Impact: MEDIUM (deduplicates within request)**
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect: always cache miss**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct: cache hit**
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+If you must pass objects, pass the same reference:
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+
+- Heavy computations
+
+- Authentication checks
+
+- File system operations
+
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)
+
+### 3.10 Use after() for Non-Blocking Operations
+
+**Impact: MEDIUM (faster response times)**
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect: blocks response**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+
+- Audit logging
+
+- Sending notifications
+
+- Cache invalidation
+
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
+
+---
+
+## 4. Client-Side Data Fetching
+
+**Impact: MEDIUM-HIGH**
+
+Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+### 4.1 Deduplicate Global Event Listeners
+
+**Impact: LOW (single listener for N components)**
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect: N instances = N listeners**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct: N instances = 1 listener**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
+
+### 4.2 Use Passive Event Listeners for Scrolling Performance
+
+**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
+
+### 4.3 Use SWR for Automatic Deduplication
+
+**Impact: MEDIUM-HIGH (automatic deduplication)**
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect: no deduplication, each instance fetches**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct: multiple instances share one request**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
+
+### 4.4 Version and Minimize localStorage Data
+
+**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
+
+---
+
+## 5. Re-render Optimization
+
+**Impact: MEDIUM**
+
+Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+### 5.1 Calculate Derived State During Rendering
+
+**Impact: MEDIUM (avoids redundant renders and state drift)**
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect: redundant state and effect**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct: derive during render**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect)
+
+### 5.2 Defer State Reads to Usage Point
+
+**Impact: MEDIUM (avoids unnecessary subscriptions)**
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect: subscribes to all searchParams changes**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct: reads on demand, no subscription**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+### 5.3 Do not wrap a simple expression with a primitive result type in useMemo
+
+**Impact: LOW-MEDIUM (wasted computation on every render)**
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+### 5.4 Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect: remounts on every render**
+
+```tsx
+function UserProfile({ user, theme }) {
+  // Defined inside to access `theme` - BAD
+  const Avatar = () => (
+    <img
+      src={user.avatarUrl}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+
+  // Defined inside to access `user` - BAD
+  const Stats = () => (
+    <div>
+      <span>{user.followers} followers</span>
+      <span>{user.posts} posts</span>
+    </div>
+  )
+
+  return (
+    <div>
+      <Avatar />
+      <Stats />
+    </div>
+  )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct: pass props instead**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+  return (
+    <img
+      src={src}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+  return (
+    <div>
+      <span>{followers} followers</span>
+      <span>{posts} posts</span>
+    </div>
+  )
+}
+
+function UserProfile({ user, theme }) {
+  return (
+    <div>
+      <Avatar src={user.avatarUrl} theme={theme} />
+      <Stats followers={user.followers} posts={user.posts} />
+    </div>
+  )
+}
+```
+
+**Symptoms of this bug:**
+
+- Input fields lose focus on every keystroke
+
+- Animations restart unexpectedly
+
+- `useEffect` cleanup/setup runs on every parent render
+
+- Scroll position resets inside the component
+
+### 5.5 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+**Impact: MEDIUM (restores memoization by using a constant for default value)**
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect: `onClick` has different values on every rerender**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct: stable default value**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+### 5.6 Extract to Memoized Components
+
+**Impact: MEDIUM (enables early returns)**
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect: computes avatar even when loading**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct: skips computation when loading**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
+
+### 5.7 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect: re-runs on any user field change**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct: re-runs only when id changes**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
+
+### 5.8 Put Interaction Logic in Event Handlers
+
+**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect: event modeled as state + effect**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct: do it in the handler**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+### 5.9 Split Combined Hook Computations
+
+**Impact: MEDIUM (avoids recomputing independent steps)**
+
+When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.
+
+**Incorrect: changing `sortOrder` recomputes filtering**
+
+```tsx
+const sortedProducts = useMemo(() => {
+  const filtered = products.filter((p) => p.category === category)
+  const sorted = filtered.toSorted((a, b) =>
+    sortOrder === "asc" ? a.price - b.price : b.price - a.price
+  )
+  return sorted
+}, [products, category, sortOrder])
+```
+
+**Correct: filtering only recomputes when products or category change**
+
+```tsx
+const filteredProducts = useMemo(
+  () => products.filter((p) => p.category === category),
+  [products, category]
+)
+
+const sortedProducts = useMemo(
+  () =>
+    filteredProducts.toSorted((a, b) =>
+      sortOrder === "asc" ? a.price - b.price : b.price - a.price
+    ),
+  [filteredProducts, sortOrder]
+)
+```
+
+This pattern also applies to `useEffect` when combining unrelated side effects:
+
+**Incorrect: both effects run when either dependency changes**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+  document.title = `${pageTitle} | My App`
+}, [pathname, pageTitle])
+```
+
+**Correct: effects run independently**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+}, [pathname])
+
+useEffect(() => {
+  document.title = `${pageTitle} | My App`
+}, [pageTitle])
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.
+
+### 5.10 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect: re-renders on every pixel change**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct: re-renders only when boolean changes**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+### 5.11 Use Functional setState Updates
+
+**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect: requires state as dependency**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct: stable callbacks, no stale closures**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+
+2. **No stale closures** - Always operates on the latest state value
+
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+
+- Inside useCallback/useMemo when state is needed
+
+- Event handlers that reference state
+
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+
+- Setting state from props/arguments only: `setName(newName)`
+
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
+
+### 5.12 Use Lazy State Initialization
+
+**Impact: MEDIUM (wasted computation on every render)**
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect: runs on every render**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct: runs only once**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
+
+### 5.13 Use Transitions for Non-Urgent Updates
+
+**Impact: MEDIUM (maintains UI responsiveness)**
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect: blocks UI on every scroll**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct: non-blocking updates**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+### 5.14 Use useDeferredValue for Expensive Derived Renders
+
+**Impact: MEDIUM (keeps input responsive during heavy computation)**
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect: input feels laggy while filtering**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const filtered = items.filter(item => fuzzyMatch(item, query))
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  )
+}
+```
+
+**Correct: input stays snappy, results render when ready**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const deferredQuery = useDeferredValue(query)
+  const filtered = useMemo(
+    () => items.filter(item => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery]
+  )
+  const isStale = query !== deferredQuery
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  )
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+
+- Expensive visualizations (charts, graphs) reacting to input
+
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [https://react.dev/reference/react/useDeferredValue](https://react.dev/reference/react/useDeferredValue)
+
+### 5.15 Use useRef for Transient Values
+
+**Impact: MEDIUM (avoids unnecessary re-renders on frequent updates)**
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect: renders every update**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct: no re-render for tracking**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```
+
+---
+
+## 6. Rendering Performance
+
+**Impact: MEDIUM**
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+### 6.1 Animate SVG Wrapper Instead of SVG Element
+
+**Impact: LOW (enables hardware acceleration)**
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect: animating SVG directly - no hardware acceleration**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct: animating wrapper div - hardware accelerated**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect: excessive precision**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct: 1 decimal place**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
+
+### 6.5 Prevent Hydration Mismatch Without Flickering
+
+**Impact: MEDIUM (avoids visual flicker and hydration errors)**
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect: breaks SSR**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect: visual flickering**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct: no flicker, no hydration mismatch**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
+
+### 6.6 Suppress Expected Hydration Mismatches
+
+**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect: known mismatch warnings**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct: suppress expected mismatch only**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```
+
+### 6.7 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+### 6.8 Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect: blocks rendering**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        <script src="https://example.com/analytics.js" />
+        <script src="/scripts/utils.js" />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <>
+      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
+      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
+    </>
+  )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+Reference: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
+
+### 6.9 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect: renders "0" when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct: renders nothing when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+### 6.10 Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example: preconnect to third-party APIs**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+  prefetchDNS('https://analytics.example.com')
+  preconnect('https://api.example.com')
+
+  return <main>{/* content */}</main>
+}
+```
+
+**Example: preload critical fonts and styles**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+  // Preload font file
+  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+  // Fetch and apply critical stylesheet immediately
+  preinit('/styles/critical.css', { as: 'style' })
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+**Example: preload modules for code-split routes**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+  const preloadDashboard = () => {
+    preloadModule('/dashboard.js', { as: 'script' })
+  }
+
+  return (
+    <nav>
+      <a href="/dashboard" onMouseEnter={preloadDashboard}>
+        Dashboard
+      </a>
+    </nav>
+  )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+
+|-----|----------|
+
+| `prefetchDNS` | Third-party domains you'll connect to later |
+
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+
+| `preload` | Critical resources needed for current page |
+
+| `preloadModule` | JS modules for likely next navigation |
+
+| `preinit` | Stylesheets/scripts that must execute early |
+
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [https://react.dev/reference/react-dom#resource-preloading-apis](https://react.dev/reference/react-dom#resource-preloading-apis)
+
+### 6.11 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect: manual loading state**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct: useTransition with built-in pending state**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+
+- **Error resilience**: Pending state correctly resets even if the transition throws
+
+- **Better responsiveness**: Keeps the UI responsive during updates
+
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [https://react.dev/reference/react/useTransition](https://react.dev/reference/react/useTransition)
+
+---
+
+## 7. JavaScript Performance
+
+**Impact: LOW-MEDIUM**
+
+Micro-optimizations for hot paths can add up to meaningful improvements.
+
+### 7.1 Avoid Layout Thrashing
+
+**Impact: MEDIUM (prevents forced synchronous layouts and reduces performance bottlenecks)**
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK: browser batches style changes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect: interleaved reads and writes force reflows**
+
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct: batch writes, then read once**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct: batch reads, then writes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Better: use CSS classes**
+
+**React example:**
+
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+Cache object property lookups in hot paths.
+
+**Incorrect: 3 lookups × N iterations**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct: 1 lookup total**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect: redundant computation**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct: cached results**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+### 7.5 Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect: reads storage on every call**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct: Map cache**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important: invalidate on external changes**
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect: 3 iterations**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct: 1 iteration**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
+
+### 7.7 Defer Non-Critical Work with requestIdleCallback
+
+**Impact: MEDIUM (keeps UI responsive during background tasks)**
+
+Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
+
+**Incorrect: blocks main thread during user interaction**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // These block the main thread immediately
+  analytics.track('search', { query })
+  saveToRecentSearches(query)
+  prefetchTopResults(results.slice(0, 3))
+}
+```
+
+**Correct: defers non-critical work to idle time**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // Defer non-critical work to idle periods
+  requestIdleCallback(() => {
+    analytics.track('search', { query })
+  })
+
+  requestIdleCallback(() => {
+    saveToRecentSearches(query)
+  })
+
+  requestIdleCallback(() => {
+    prefetchTopResults(results.slice(0, 3))
+  })
+}
+```
+
+**With timeout for required work:**
+
+```typescript
+// Ensure analytics fires within 2 seconds even if browser stays busy
+requestIdleCallback(
+  () => analytics.track('page_view', { path: location.pathname }),
+  { timeout: 2000 }
+)
+```
+
+**Chunking large tasks:**
+
+```typescript
+function processLargeDataset(items: Item[]) {
+  let index = 0
+
+  function processChunk(deadline: IdleDeadline) {
+    // Process items while we have idle time (aim for <50ms chunks)
+    while (index < items.length && deadline.timeRemaining() > 0) {
+      processItem(items[index])
+      index++
+    }
+
+    // Schedule next chunk if more items remain
+    if (index < items.length) {
+      requestIdleCallback(processChunk)
+    }
+  }
+
+  requestIdleCallback(processChunk)
+}
+```
+
+**With fallback for unsupported browsers:**
+
+```typescript
+const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
+
+scheduleIdleWork(() => {
+  // Non-critical work
+})
+```
+
+**When to use:**
+
+- Analytics and telemetry
+
+- Saving state to localStorage/IndexedDB
+
+- Prefetching resources for likely next actions
+
+- Processing non-urgent data transformations
+
+- Lazy initialization of non-critical features
+
+**When NOT to use:**
+
+- User-initiated actions that need immediate feedback
+
+- Rendering updates the user is waiting for
+
+- Time-sensitive operations
+
+### 7.8 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect: always runs expensive comparison**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+
+- It avoids mutating the original arrays
+
+- It returns early when a difference is found
+
+### 7.9 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect: processes all items even after finding answer**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct: returns immediately on first error**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
+
+### 7.10 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect: new RegExp every render**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct: memoize or hoist**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning: global regex has mutable state**
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.11 Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect: 2 iterations, intermediate array**
+
+```typescript
+const userNames = users
+  .map(user => user.isActive ? user.name : null)
+  .filter(Boolean)
+```
+
+**Correct: 1 iteration, no intermediate array**
+
+```typescript
+const userNames = users.flatMap(user =>
+  user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+  .map(r => r.success ? r.data.email : null)
+  .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+  r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+  .map(s => parseInt(s, 10))
+  .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+
+- Transforming items while filtering some out
+
+- Conditional mapping where some inputs produce no output
+
+- Parsing/validating where invalid inputs should be skipped
+
+### 7.12 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative: Math.min/Math.max for small arrays**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
+
+### 7.13 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+### 7.14 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect: mutates original array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct: creates new array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support: fallback for older browsers**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Do Not Put Effect Events in Dependency Arrays
+
+**Impact: LOW (avoids unnecessary effect re-runs and lint errors)**
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect: Effect Event added as a dependency**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId, handleConnected])
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct: depend on reactive values, not the Effect Event**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId])
+}
+```
+
+Reference: [https://react.dev/reference/react/useEffectEvent#effect-event-in-deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)
+
+### 8.2 Initialize App Once, Not Per Mount
+
+**Impact: LOW-MEDIUM (avoids duplicate init in development)**
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect: runs twice in dev, re-runs on remount**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct: once per app load**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+### 8.3 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect: re-subscribes on every render**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct: stable subscription**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.4 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect: effect re-runs on every callback change**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct: using React's useEffectEvent**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/skills/vercel/react-best-practices/README.md b/skills/vercel/react-best-practices/README.md
new file mode 100644
index 0000000..f283e1c
--- /dev/null
+++ b/skills/vercel/react-best-practices/README.md
@@ -0,0 +1,123 @@
+# React Best Practices
+
+A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `src/` - Build scripts and utilities
+- `metadata.json` - Document metadata (version, organization, abstract)
+- __`AGENTS.md`__ - Compiled output (generated)
+- __`test-cases.json`__ - Test cases for LLM evaluation (generated)
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Build AGENTS.md from rules:
+   ```bash
+   pnpm build
+   ```
+
+3. Validate rule files:
+   ```bash
+   pnpm validate
+   ```
+
+4. Extract test cases:
+   ```bash
+   pnpm extract-tests
+   ```
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `async-` for Eliminating Waterfalls (Section 1)
+   - `bundle-` for Bundle Size Optimization (Section 2)
+   - `server-` for Server-Side Performance (Section 3)
+   - `client-` for Client-Side Data Fetching (Section 4)
+   - `rerender-` for Re-render Optimization (Section 5)
+   - `rendering-` for Rendering Performance (Section 6)
+   - `js-` for JavaScript Performance (Section 7)
+   - `advanced-` for Advanced Patterns (Section 8)
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+```markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example
+```
+
+Optional explanatory text after examples.
+
+Reference: [Link](https://example.com)
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `async-parallel.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+- IDs (e.g., 1.1, 1.2) are auto-generated during build
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, major performance gains
+- `HIGH` - Significant performance improvements
+- `MEDIUM-HIGH` - Moderate-high gains
+- `MEDIUM` - Moderate performance improvements
+- `LOW-MEDIUM` - Low-medium gains
+- `LOW` - Incremental improvements
+
+## Scripts
+
+- `pnpm build` - Compile rules into AGENTS.md
+- `pnpm validate` - Validate all rule files
+- `pnpm extract-tests` - Extract test cases for LLM evaluation
+- `pnpm dev` - Build and validate
+
+## Contributing
+
+When adding or modifying rules:
+
+1. Use the correct filename prefix for your section
+2. Follow the `_template.md` structure
+3. Include clear bad/good examples with explanations
+4. Add appropriate tags
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+6. Rules are automatically sorted by title - no need to manage numbers!
+
+## Acknowledgments
+
+Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).
diff --git a/skills/vercel/react-best-practices/SKILL.md b/skills/vercel/react-best-practices/SKILL.md
new file mode 100644
index 0000000..237988d
--- /dev/null
+++ b/skills/vercel/react-best-practices/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable import and file-system paths to avoid broad bundles and traces
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
+- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-parallel-nested-fetching` - Chain nested fetches per item in Promise.all
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-split-combined-hooks` - Split hooks with independent dependencies
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+- `js-request-idle-callback` - Defer non-critical work to browser idle time
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel/react-best-practices/metadata.json b/skills/vercel/react-best-practices/metadata.json
new file mode 100644
index 0000000..3bec38b
--- /dev/null
+++ b/skills/vercel/react-best-practices/metadata.json
@@ -0,0 +1,15 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://nextjs.org",
+    "https://swr.vercel.app",
+    "https://github.com/shuding/better-all",
+    "https://github.com/isaacs/node-lru-cache",
+    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast"
+  ]
+}
diff --git a/skills/vercel/react-best-practices/rules/_sections.md b/skills/vercel/react-best-practices/rules/_sections.md
new file mode 100644
index 0000000..4d20c14
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/_sections.md
@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+## 2. Bundle Size Optimization (bundle)
+
+**Impact:** CRITICAL  
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+## 3. Server-Side Performance (server)
+
+**Impact:** HIGH  
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+## 4. Client-Side Data Fetching (client)
+
+**Impact:** MEDIUM-HIGH  
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+## 5. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM  
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+## 6. Rendering Performance (rendering)
+
+**Impact:** MEDIUM  
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+
+## 7. JavaScript Performance (js)
+
+**Impact:** LOW-MEDIUM  
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+
+## 8. Advanced Patterns (advanced)
+
+**Impact:** LOW  
+**Description:** Advanced patterns for specific cases that require careful implementation.
diff --git a/skills/vercel/react-best-practices/rules/_template.md b/skills/vercel/react-best-practices/rules/_template.md
new file mode 100644
index 0000000..1e9e707
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/_template.md
@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel/react-best-practices/rules/advanced-effect-event-deps.md b/skills/vercel/react-best-practices/rules/advanced-effect-event-deps.md
new file mode 100644
index 0000000..24d901b
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/advanced-effect-event-deps.md
@@ -0,0 +1,56 @@
+---
+title: Do Not Put Effect Events in Dependency Arrays
+impact: LOW
+impactDescription: avoids unnecessary effect re-runs and lint errors
+tags: advanced, hooks, useEffectEvent, dependencies, effects
+---
+
+## Do Not Put Effect Events in Dependency Arrays
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect (Effect Event added as a dependency):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId, handleConnected])
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct (depend on reactive values, not the Effect Event):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId])
+}
+```
+
+Reference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)
diff --git a/skills/vercel/react-best-practices/rules/advanced-event-handler-refs.md b/skills/vercel/react-best-practices/rules/advanced-event-handler-refs.md
new file mode 100644
index 0000000..97e7ade
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/advanced-event-handler-refs.md
@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
diff --git a/skills/vercel/react-best-practices/rules/advanced-init-once.md b/skills/vercel/react-best-practices/rules/advanced-init-once.md
new file mode 100644
index 0000000..73ee38e
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/advanced-init-once.md
@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
diff --git a/skills/vercel/react-best-practices/rules/advanced-use-latest.md b/skills/vercel/react-best-practices/rules/advanced-use-latest.md
new file mode 100644
index 0000000..9c7cb50
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/advanced-use-latest.md
@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/async-api-routes.md b/skills/vercel/react-best-practices/rules/async-api-routes.md
new file mode 100644
index 0000000..6feda1e
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/async-api-routes.md
@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
diff --git a/skills/vercel/react-best-practices/rules/async-cheap-condition-before-await.md b/skills/vercel/react-best-practices/rules/async-cheap-condition-before-await.md
new file mode 100644
index 0000000..5799d7f
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/async-cheap-condition-before-await.md
@@ -0,0 +1,37 @@
+---
+title: Check Cheap Conditions Before Async Flags
+impact: HIGH
+impactDescription: avoids unnecessary async work when a synchronous guard already fails
+tags: async, await, feature-flags, short-circuit, conditional
+---
+
+## Check Cheap Conditions Before Async Flags
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag()
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag()
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.
diff --git a/skills/vercel/react-best-practices/rules/async-defer-await.md b/skills/vercel/react-best-practices/rules/async-defer-await.md
new file mode 100644
index 0000000..460b5e1
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/async-defer-await.md
@@ -0,0 +1,82 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).
diff --git a/skills/vercel/react-best-practices/rules/async-dependencies.md b/skills/vercel/react-best-practices/rules/async-dependencies.md
new file mode 100644
index 0000000..0484eba
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/async-dependencies.md
@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
diff --git a/skills/vercel/react-best-practices/rules/async-parallel.md b/skills/vercel/react-best-practices/rules/async-parallel.md
new file mode 100644
index 0000000..64133f6
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/async-parallel.md
@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
diff --git a/skills/vercel/react-best-practices/rules/async-suspense-boundaries.md b/skills/vercel/react-best-practices/rules/async-suspense-boundaries.md
new file mode 100644
index 0000000..1fbc05b
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/async-suspense-boundaries.md
@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
diff --git a/skills/vercel/react-best-practices/rules/bundle-analyzable-paths.md b/skills/vercel/react-best-practices/rules/bundle-analyzable-paths.md
new file mode 100644
index 0000000..8276f15
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/bundle-analyzable-paths.md
@@ -0,0 +1,63 @@
+---
+title: Prefer Statically Analyzable Paths
+impact: HIGH
+impactDescription: avoids accidental broad bundles and file traces
+tags: bundle, nextjs, vite, webpack, rollup, esbuild, path
+---
+
+## Prefer Statically Analyzable Paths
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+- Larger server bundles
+- Slower builds
+- Worse cold starts
+- More memory use
+
+### Import Paths
+
+**Incorrect (the bundler cannot tell what may be imported):**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct (use an explicit map of allowed modules):**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+### File-System Paths
+
+**Incorrect (a 2-value enum still hides the final path from static analysis):**
+
+```ts
+const baseDir = path.join(process.cwd(), 'content/' + contentKind)
+```
+
+**Correct (make each final path literal at the callsite):**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [Next.js output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [Next.js dynamic imports](https://nextjs.org/learn/seo/dynamic-imports), [Vite features](https://vite.dev/guide/features.html), [esbuild API](https://esbuild.github.io/api/), [Rollup dynamic import vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [Webpack dependency management](https://webpack.js.org/guides/dependency-management/)
diff --git a/skills/vercel/react-best-practices/rules/bundle-barrel-imports.md b/skills/vercel/react-best-practices/rules/bundle-barrel-imports.md
new file mode 100644
index 0000000..22d1050
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/bundle-barrel-imports.md
@@ -0,0 +1,60 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct - Next.js 13.5+ (recommended):**
+
+```js
+// next.config.js - automatically optimizes barrel imports at build time
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+```
+
+```tsx
+// Keep the standard imports - Next.js transforms them to direct imports
+import { Check, X, Menu } from 'lucide-react'
+// Full TypeScript support, no manual path wrangling
+```
+
+This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
+
+**Correct - Direct imports (non-Next.js projects):**
+
+```tsx
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
+
+These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/skills/vercel/react-best-practices/rules/bundle-conditional.md b/skills/vercel/react-best-practices/rules/bundle-conditional.md
new file mode 100644
index 0000000..99d6fc9
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/bundle-conditional.md
@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
diff --git a/skills/vercel/react-best-practices/rules/bundle-defer-third-party.md b/skills/vercel/react-best-practices/rules/bundle-defer-third-party.md
new file mode 100644
index 0000000..db041d1
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/bundle-defer-third-party.md
@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/bundle-dynamic-imports.md b/skills/vercel/react-best-practices/rules/bundle-dynamic-imports.md
new file mode 100644
index 0000000..60b6269
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/bundle-dynamic-imports.md
@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/bundle-preload.md b/skills/vercel/react-best-practices/rules/bundle-preload.md
new file mode 100644
index 0000000..7000504
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/bundle-preload.md
@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
diff --git a/skills/vercel/react-best-practices/rules/client-event-listeners.md b/skills/vercel/react-best-practices/rules/client-event-listeners.md
new file mode 100644
index 0000000..aad4ae9
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/client-event-listeners.md
@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/client-localstorage-schema.md b/skills/vercel/react-best-practices/rules/client-localstorage-schema.md
new file mode 100644
index 0000000..d30a1a7
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/client-localstorage-schema.md
@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
diff --git a/skills/vercel/react-best-practices/rules/client-passive-event-listeners.md b/skills/vercel/react-best-practices/rules/client-passive-event-listeners.md
new file mode 100644
index 0000000..ce39a88
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/client-passive-event-listeners.md
@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
diff --git a/skills/vercel/react-best-practices/rules/client-swr-dedup.md b/skills/vercel/react-best-practices/rules/client-swr-dedup.md
new file mode 100644
index 0000000..2a430f2
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/client-swr-dedup.md
@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
diff --git a/skills/vercel/react-best-practices/rules/js-batch-dom-css.md b/skills/vercel/react-best-practices/rules/js-batch-dom-css.md
new file mode 100644
index 0000000..a62d84e
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-batch-dom-css.md
@@ -0,0 +1,107 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK (browser batches style changes):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct (batch reads, then writes):**
+```typescript
+function avoidThrashing(element: HTMLElement) {
+  // Read phase - all layout queries first
+  const rect1 = element.getBoundingClientRect()
+  const offsetWidth = element.offsetWidth
+  const offsetHeight = element.offsetHeight
+  
+  // Write phase - all style changes after
+  element.style.width = '100px'
+  element.style.height = '200px'
+}
+```
+
+**Better: use CSS classes**
+```css
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+```
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**React example:**
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
diff --git a/skills/vercel/react-best-practices/rules/js-cache-function-results.md b/skills/vercel/react-best-practices/rules/js-cache-function-results.md
new file mode 100644
index 0000000..180f8ac
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-cache-function-results.md
@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/skills/vercel/react-best-practices/rules/js-cache-property-access.md b/skills/vercel/react-best-practices/rules/js-cache-property-access.md
new file mode 100644
index 0000000..39eec90
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-cache-property-access.md
@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/js-cache-storage.md b/skills/vercel/react-best-practices/rules/js-cache-storage.md
new file mode 100644
index 0000000..aa4a30c
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-cache-storage.md
@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
diff --git a/skills/vercel/react-best-practices/rules/js-combine-iterations.md b/skills/vercel/react-best-practices/rules/js-combine-iterations.md
new file mode 100644
index 0000000..044d017
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-combine-iterations.md
@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/js-early-exit.md b/skills/vercel/react-best-practices/rules/js-early-exit.md
new file mode 100644
index 0000000..f46cb89
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-early-exit.md
@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/js-flatmap-filter.md b/skills/vercel/react-best-practices/rules/js-flatmap-filter.md
new file mode 100644
index 0000000..ee0edf0
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-flatmap-filter.md
@@ -0,0 +1,60 @@
+---
+title: Use flatMap to Map and Filter in One Pass
+impact: LOW-MEDIUM
+impactDescription: eliminates intermediate array
+tags: javascript, arrays, flatMap, filter, performance
+---
+
+## Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect (2 iterations, intermediate array):**
+
+```typescript
+const userNames = users
+  .map(user => user.isActive ? user.name : null)
+  .filter(Boolean)
+```
+
+**Correct (1 iteration, no intermediate array):**
+
+```typescript
+const userNames = users.flatMap(user =>
+  user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+  .map(r => r.success ? r.data.email : null)
+  .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+  r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+  .map(s => parseInt(s, 10))
+  .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+- Transforming items while filtering some out
+- Conditional mapping where some inputs produce no output
+- Parsing/validating where invalid inputs should be skipped
diff --git a/skills/vercel/react-best-practices/rules/js-hoist-regexp.md b/skills/vercel/react-best-practices/rules/js-hoist-regexp.md
new file mode 100644
index 0000000..dae3fef
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-hoist-regexp.md
@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
diff --git a/skills/vercel/react-best-practices/rules/js-index-maps.md b/skills/vercel/react-best-practices/rules/js-index-maps.md
new file mode 100644
index 0000000..9d357a0
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-index-maps.md
@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.
diff --git a/skills/vercel/react-best-practices/rules/js-length-check-first.md b/skills/vercel/react-best-practices/rules/js-length-check-first.md
new file mode 100644
index 0000000..8b89573
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-length-check-first.md
@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found
diff --git a/skills/vercel/react-best-practices/rules/js-min-max-loop.md b/skills/vercel/react-best-practices/rules/js-min-max-loop.md
new file mode 100644
index 0000000..4b6656e
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-min-max-loop.md
@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
diff --git a/skills/vercel/react-best-practices/rules/js-request-idle-callback.md b/skills/vercel/react-best-practices/rules/js-request-idle-callback.md
new file mode 100644
index 0000000..d81927e
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-request-idle-callback.md
@@ -0,0 +1,105 @@
+---
+title: Defer Non-Critical Work with requestIdleCallback
+impact: MEDIUM
+impactDescription: keeps UI responsive during background tasks
+tags: javascript, performance, idle, scheduling, analytics
+---
+
+## Defer Non-Critical Work with requestIdleCallback
+
+**Impact: MEDIUM (keeps UI responsive during background tasks)**
+
+Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
+
+**Incorrect (blocks main thread during user interaction):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // These block the main thread immediately
+  analytics.track('search', { query })
+  saveToRecentSearches(query)
+  prefetchTopResults(results.slice(0, 3))
+}
+```
+
+**Correct (defers non-critical work to idle time):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // Defer non-critical work to idle periods
+  requestIdleCallback(() => {
+    analytics.track('search', { query })
+  })
+
+  requestIdleCallback(() => {
+    saveToRecentSearches(query)
+  })
+
+  requestIdleCallback(() => {
+    prefetchTopResults(results.slice(0, 3))
+  })
+}
+```
+
+**With timeout for required work:**
+
+```typescript
+// Ensure analytics fires within 2 seconds even if browser stays busy
+requestIdleCallback(
+  () => analytics.track('page_view', { path: location.pathname }),
+  { timeout: 2000 }
+)
+```
+
+**Chunking large tasks:**
+
+```typescript
+function processLargeDataset(items: Item[]) {
+  let index = 0
+
+  function processChunk(deadline: IdleDeadline) {
+    // Process items while we have idle time (aim for <50ms chunks)
+    while (index < items.length && deadline.timeRemaining() > 0) {
+      processItem(items[index])
+      index++
+    }
+
+    // Schedule next chunk if more items remain
+    if (index < items.length) {
+      requestIdleCallback(processChunk)
+    }
+  }
+
+  requestIdleCallback(processChunk)
+}
+```
+
+**With fallback for unsupported browsers:**
+
+```typescript
+const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
+
+scheduleIdleWork(() => {
+  // Non-critical work
+})
+```
+
+**When to use:**
+
+- Analytics and telemetry
+- Saving state to localStorage/IndexedDB
+- Prefetching resources for likely next actions
+- Processing non-urgent data transformations
+- Lazy initialization of non-critical features
+
+**When NOT to use:**
+
+- User-initiated actions that need immediate feedback
+- Rendering updates the user is waiting for
+- Time-sensitive operations
diff --git a/skills/vercel/react-best-practices/rules/js-set-map-lookups.md b/skills/vercel/react-best-practices/rules/js-set-map-lookups.md
new file mode 100644
index 0000000..680a489
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-set-map-lookups.md
@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
diff --git a/skills/vercel/react-best-practices/rules/js-tosorted-immutable.md b/skills/vercel/react-best-practices/rules/js-tosorted-immutable.md
new file mode 100644
index 0000000..eae8b3f
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/js-tosorted-immutable.md
@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement
diff --git a/skills/vercel/react-best-practices/rules/rendering-activity.md b/skills/vercel/react-best-practices/rules/rendering-activity.md
new file mode 100644
index 0000000..c957a49
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-activity.md
@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
diff --git a/skills/vercel/react-best-practices/rules/rendering-animate-svg-wrapper.md b/skills/vercel/react-best-practices/rules/rendering-animate-svg-wrapper.md
new file mode 100644
index 0000000..646744c
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-animate-svg-wrapper.md
@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
diff --git a/skills/vercel/react-best-practices/rules/rendering-conditional-render.md b/skills/vercel/react-best-practices/rules/rendering-conditional-render.md
new file mode 100644
index 0000000..7e866f5
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-conditional-render.md
@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
diff --git a/skills/vercel/react-best-practices/rules/rendering-content-visibility.md b/skills/vercel/react-best-practices/rules/rendering-content-visibility.md
new file mode 100644
index 0000000..aa66563
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-content-visibility.md
@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
diff --git a/skills/vercel/react-best-practices/rules/rendering-hoist-jsx.md b/skills/vercel/react-best-practices/rules/rendering-hoist-jsx.md
new file mode 100644
index 0000000..32d2f3f
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-hoist-jsx.md
@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
diff --git a/skills/vercel/react-best-practices/rules/rendering-hydration-no-flicker.md b/skills/vercel/react-best-practices/rules/rendering-hydration-no-flicker.md
new file mode 100644
index 0000000..5cf0e79
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-hydration-no-flicker.md
@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
diff --git a/skills/vercel/react-best-practices/rules/rendering-hydration-suppress-warning.md b/skills/vercel/react-best-practices/rules/rendering-hydration-suppress-warning.md
new file mode 100644
index 0000000..24ba251
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-hydration-suppress-warning.md
@@ -0,0 +1,30 @@
+---
+title: Suppress Expected Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: avoids noisy hydration warnings for known differences
+tags: rendering, hydration, ssr, nextjs
+---
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/rendering-resource-hints.md b/skills/vercel/react-best-practices/rules/rendering-resource-hints.md
new file mode 100644
index 0000000..1290bef
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-resource-hints.md
@@ -0,0 +1,85 @@
+---
+title: Use React DOM Resource Hints
+impact: HIGH
+impactDescription: reduces load time for critical resources
+tags: rendering, preload, preconnect, prefetch, resource-hints
+---
+
+## Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example (preconnect to third-party APIs):**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+  prefetchDNS('https://analytics.example.com')
+  preconnect('https://api.example.com')
+
+  return <main>{/* content */}</main>
+}
+```
+
+**Example (preload critical fonts and styles):**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+  // Preload font file
+  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+  // Fetch and apply critical stylesheet immediately
+  preinit('/styles/critical.css', { as: 'style' })
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+**Example (preload modules for code-split routes):**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+  const preloadDashboard = () => {
+    preloadModule('/dashboard.js', { as: 'script' })
+  }
+
+  return (
+    <nav>
+      <a href="/dashboard" onMouseEnter={preloadDashboard}>
+        Dashboard
+      </a>
+    </nav>
+  )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+|-----|----------|
+| `prefetchDNS` | Third-party domains you'll connect to later |
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+| `preload` | Critical resources needed for current page |
+| `preloadModule` | JS modules for likely next navigation |
+| `preinit` | Stylesheets/scripts that must execute early |
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [React DOM Resource Preloading APIs](https://react.dev/reference/react-dom#resource-preloading-apis)
diff --git a/skills/vercel/react-best-practices/rules/rendering-script-defer-async.md b/skills/vercel/react-best-practices/rules/rendering-script-defer-async.md
new file mode 100644
index 0000000..ee275ed
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-script-defer-async.md
@@ -0,0 +1,68 @@
+---
+title: Use defer or async on Script Tags
+impact: HIGH
+impactDescription: eliminates render-blocking
+tags: rendering, script, defer, async, performance
+---
+
+## Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect (blocks rendering):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        <script src="https://example.com/analytics.js" />
+        <script src="/scripts/utils.js" />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        {/* Independent script - use async */}
+        <script src="https://example.com/analytics.js" async />
+        {/* DOM-dependent script - use defer */}
+        <script src="/scripts/utils.js" defer />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <>
+      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
+      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
+    </>
+  )
+}
+```
+
+Reference: [MDN - Script element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
diff --git a/skills/vercel/react-best-practices/rules/rendering-svg-precision.md b/skills/vercel/react-best-practices/rules/rendering-svg-precision.md
new file mode 100644
index 0000000..6d77128
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-svg-precision.md
@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
diff --git a/skills/vercel/react-best-practices/rules/rendering-usetransition-loading.md b/skills/vercel/react-best-practices/rules/rendering-usetransition-loading.md
new file mode 100644
index 0000000..0c1b0b9
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rendering-usetransition-loading.md
@@ -0,0 +1,75 @@
+---
+title: Use useTransition Over Manual Loading States
+impact: LOW
+impactDescription: reduces re-renders and improves code clarity
+tags: rendering, transitions, useTransition, loading, state
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct (useTransition with built-in pending state):**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+- **Error resilience**: Pending state correctly resets even if the transition throws
+- **Better responsiveness**: Keeps the UI responsive during updates
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)
diff --git a/skills/vercel/react-best-practices/rules/rerender-defer-reads.md b/skills/vercel/react-best-practices/rules/rerender-defer-reads.md
new file mode 100644
index 0000000..e867c95
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-defer-reads.md
@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/rerender-dependencies.md b/skills/vercel/react-best-practices/rules/rerender-dependencies.md
new file mode 100644
index 0000000..47a4d92
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-dependencies.md
@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
diff --git a/skills/vercel/react-best-practices/rules/rerender-derived-state-no-effect.md b/skills/vercel/react-best-practices/rules/rerender-derived-state-no-effect.md
new file mode 100644
index 0000000..3d9fe40
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-derived-state-no-effect.md
@@ -0,0 +1,40 @@
+---
+title: Calculate Derived State During Rendering
+impact: MEDIUM
+impactDescription: avoids redundant renders and state drift
+tags: rerender, derived-state, useEffect, state
+---
+
+## Calculate Derived State During Rendering
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect (redundant state and effect):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct (derive during render):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
diff --git a/skills/vercel/react-best-practices/rules/rerender-derived-state.md b/skills/vercel/react-best-practices/rules/rerender-derived-state.md
new file mode 100644
index 0000000..e5c899f
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-derived-state.md
@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/rerender-functional-setstate.md b/skills/vercel/react-best-practices/rules/rerender-functional-setstate.md
new file mode 100644
index 0000000..b004ef4
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-functional-setstate.md
@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
diff --git a/skills/vercel/react-best-practices/rules/rerender-lazy-state-init.md b/skills/vercel/react-best-practices/rules/rerender-lazy-state-init.md
new file mode 100644
index 0000000..4ecb350
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-lazy-state-init.md
@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
diff --git a/skills/vercel/react-best-practices/rules/rerender-memo-with-default-value.md b/skills/vercel/react-best-practices/rules/rerender-memo-with-default-value.md
new file mode 100644
index 0000000..6357049
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-memo-with-default-value.md
@@ -0,0 +1,38 @@
+---
+
+title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+impact: MEDIUM
+impactDescription: restores memoization by using a constant for default value
+tags: rerender, memo, optimization
+
+---
+
+## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
diff --git a/skills/vercel/react-best-practices/rules/rerender-memo.md b/skills/vercel/react-best-practices/rules/rerender-memo.md
new file mode 100644
index 0000000..f8982ab
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-memo.md
@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
diff --git a/skills/vercel/react-best-practices/rules/rerender-move-effect-to-event.md b/skills/vercel/react-best-practices/rules/rerender-move-effect-to-event.md
new file mode 100644
index 0000000..dd58a1a
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-move-effect-to-event.md
@@ -0,0 +1,45 @@
+---
+title: Put Interaction Logic in Event Handlers
+impact: MEDIUM
+impactDescription: avoids effect re-runs and duplicate side effects
+tags: rerender, useEffect, events, side-effects, dependencies
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
diff --git a/skills/vercel/react-best-practices/rules/rerender-no-inline-components.md b/skills/vercel/react-best-practices/rules/rerender-no-inline-components.md
new file mode 100644
index 0000000..d97592a
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-no-inline-components.md
@@ -0,0 +1,82 @@
+---
+title: Don't Define Components Inside Components
+impact: HIGH
+impactDescription: prevents remount on every render
+tags: rerender, components, remount, performance
+---
+
+## Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect (remounts on every render):**
+
+```tsx
+function UserProfile({ user, theme }) {
+  // Defined inside to access `theme` - BAD
+  const Avatar = () => (
+    <img
+      src={user.avatarUrl}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+
+  // Defined inside to access `user` - BAD
+  const Stats = () => (
+    <div>
+      <span>{user.followers} followers</span>
+      <span>{user.posts} posts</span>
+    </div>
+  )
+
+  return (
+    <div>
+      <Avatar />
+      <Stats />
+    </div>
+  )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct (pass props instead):**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+  return (
+    <img
+      src={src}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+  return (
+    <div>
+      <span>{followers} followers</span>
+      <span>{posts} posts</span>
+    </div>
+  )
+}
+
+function UserProfile({ user, theme }) {
+  return (
+    <div>
+      <Avatar src={user.avatarUrl} theme={theme} />
+      <Stats followers={user.followers} posts={user.posts} />
+    </div>
+  )
+}
+```
+
+**Symptoms of this bug:**
+- Input fields lose focus on every keystroke
+- Animations restart unexpectedly
+- `useEffect` cleanup/setup runs on every parent render
+- Scroll position resets inside the component
diff --git a/skills/vercel/react-best-practices/rules/rerender-simple-expression-in-memo.md b/skills/vercel/react-best-practices/rules/rerender-simple-expression-in-memo.md
new file mode 100644
index 0000000..59dfab0
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-simple-expression-in-memo.md
@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/rerender-split-combined-hooks.md b/skills/vercel/react-best-practices/rules/rerender-split-combined-hooks.md
new file mode 100644
index 0000000..89d8056
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-split-combined-hooks.md
@@ -0,0 +1,64 @@
+---
+title: Split Combined Hook Computations
+impact: MEDIUM
+impactDescription: avoids recomputing independent steps
+tags: rerender, useMemo, useEffect, dependencies, optimization
+---
+
+## Split Combined Hook Computations
+
+When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.
+
+**Incorrect (changing `sortOrder` recomputes filtering):**
+
+```tsx
+const sortedProducts = useMemo(() => {
+  const filtered = products.filter((p) => p.category === category)
+  const sorted = filtered.toSorted((a, b) =>
+    sortOrder === "asc" ? a.price - b.price : b.price - a.price
+  )
+  return sorted
+}, [products, category, sortOrder])
+```
+
+**Correct (filtering only recomputes when products or category change):**
+
+```tsx
+const filteredProducts = useMemo(
+  () => products.filter((p) => p.category === category),
+  [products, category]
+)
+
+const sortedProducts = useMemo(
+  () =>
+    filteredProducts.toSorted((a, b) =>
+      sortOrder === "asc" ? a.price - b.price : b.price - a.price
+    ),
+  [filteredProducts, sortOrder]
+)
+```
+
+This pattern also applies to `useEffect` when combining unrelated side effects:
+
+**Incorrect (both effects run when either dependency changes):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+  document.title = `${pageTitle} | My App`
+}, [pathname, pageTitle])
+```
+
+**Correct (effects run independently):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+}, [pathname])
+
+useEffect(() => {
+  document.title = `${pageTitle} | My App`
+}, [pageTitle])
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.
diff --git a/skills/vercel/react-best-practices/rules/rerender-transitions.md b/skills/vercel/react-best-practices/rules/rerender-transitions.md
new file mode 100644
index 0000000..d99f43f
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-transitions.md
@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/rerender-use-deferred-value.md b/skills/vercel/react-best-practices/rules/rerender-use-deferred-value.md
new file mode 100644
index 0000000..619c04b
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-use-deferred-value.md
@@ -0,0 +1,59 @@
+---
+title: Use useDeferredValue for Expensive Derived Renders
+impact: MEDIUM
+impactDescription: keeps input responsive during heavy computation
+tags: rerender, useDeferredValue, optimization, concurrent
+---
+
+## Use useDeferredValue for Expensive Derived Renders
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect (input feels laggy while filtering):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const filtered = items.filter(item => fuzzyMatch(item, query))
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  )
+}
+```
+
+**Correct (input stays snappy, results render when ready):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const deferredQuery = useDeferredValue(query)
+  const filtered = useMemo(
+    () => items.filter(item => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery]
+  )
+  const isStale = query !== deferredQuery
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  )
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+- Expensive visualizations (charts, graphs) reacting to input
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [React useDeferredValue](https://react.dev/reference/react/useDeferredValue)
diff --git a/skills/vercel/react-best-practices/rules/rerender-use-ref-transient-values.md b/skills/vercel/react-best-practices/rules/rerender-use-ref-transient-values.md
new file mode 100644
index 0000000..cf04b81
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/rerender-use-ref-transient-values.md
@@ -0,0 +1,73 @@
+---
+title: Use useRef for Transient Values
+impact: MEDIUM
+impactDescription: avoids unnecessary re-renders on frequent updates
+tags: rerender, useref, state, performance
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/server-after-nonblocking.md b/skills/vercel/react-best-practices/rules/server-after-nonblocking.md
new file mode 100644
index 0000000..e8f5b26
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-after-nonblocking.md
@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
diff --git a/skills/vercel/react-best-practices/rules/server-auth-actions.md b/skills/vercel/react-best-practices/rules/server-auth-actions.md
new file mode 100644
index 0000000..ee82c04
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-auth-actions.md
@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
diff --git a/skills/vercel/react-best-practices/rules/server-cache-lru.md b/skills/vercel/react-best-practices/rules/server-cache-lru.md
new file mode 100644
index 0000000..ef6938a
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-cache-lru.md
@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
diff --git a/skills/vercel/react-best-practices/rules/server-cache-react.md b/skills/vercel/react-best-practices/rules/server-cache-react.md
new file mode 100644
index 0000000..87c9ca3
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-cache-react.md
@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
diff --git a/skills/vercel/react-best-practices/rules/server-dedup-props.md b/skills/vercel/react-best-practices/rules/server-dedup-props.md
new file mode 100644
index 0000000..fb24a25
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-dedup-props.md
@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
diff --git a/skills/vercel/react-best-practices/rules/server-hoist-static-io.md b/skills/vercel/react-best-practices/rules/server-hoist-static-io.md
new file mode 100644
index 0000000..25205c2
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-hoist-static-io.md
@@ -0,0 +1,149 @@
+---
+title: Hoist Static I/O to Module Level
+impact: HIGH
+impactDescription: avoids repeated file/network I/O per request
+tags: server, io, performance, next.js, route-handlers, og-image
+---
+
+## Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect (reads font file on every request):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct (loads once at module initialization):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Correct (synchronous fs at module level):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Incorrect (reads config on every call):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+
+  return render(template, data, config)
+}
+```
+
+**Correct (hoists config and template to module level):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+const configPromise = fs
+  .readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ])
+
+  return render(template, data, config)
+}
+```
+
+When to use this pattern:
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+When not to use this pattern:
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
diff --git a/skills/vercel/react-best-practices/rules/server-no-shared-module-state.md b/skills/vercel/react-best-practices/rules/server-no-shared-module-state.md
new file mode 100644
index 0000000..ff7d9f2
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-no-shared-module-state.md
@@ -0,0 +1,50 @@
+---
+title: Avoid Shared Module State for Request Data
+impact: HIGH
+impactDescription: prevents concurrency bugs and request data leaks
+tags: server, rsc, ssr, concurrency, security, state
+---
+
+## Avoid Shared Module State for Request Data
+
+For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
+
+Treat module scope on the server as process-wide shared memory, not request-local state.
+
+**Incorrect (request data leaks across concurrent renders):**
+
+```tsx
+let currentUser: User | null = null
+
+export default async function Page() {
+  currentUser = await auth()
+  return <Dashboard />
+}
+
+async function Dashboard() {
+  return <div>{currentUser?.name}</div>
+}
+```
+
+If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
+
+**Correct (keep request data local to the render tree):**
+
+```tsx
+export default async function Page() {
+  const user = await auth()
+  return <Dashboard user={user} />
+}
+
+function Dashboard({ user }: { user: User | null }) {
+  return <div>{user?.name}</div>
+}
+```
+
+Safe exceptions:
+
+- Immutable static assets or config loaded once at module scope
+- Shared caches intentionally designed for cross-request reuse and keyed correctly
+- Process-wide singletons that do not store request- or user-specific mutable data
+
+For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).
diff --git a/skills/vercel/react-best-practices/rules/server-parallel-fetching.md b/skills/vercel/react-best-practices/rules/server-parallel-fetching.md
new file mode 100644
index 0000000..1affc83
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-parallel-fetching.md
@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
diff --git a/skills/vercel/react-best-practices/rules/server-parallel-nested-fetching.md b/skills/vercel/react-best-practices/rules/server-parallel-nested-fetching.md
new file mode 100644
index 0000000..be1dc25
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-parallel-nested-fetching.md
@@ -0,0 +1,34 @@
+---
+title: Parallel Nested Data Fetching
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, promise-chaining
+---
+
+## Parallel Nested Data Fetching
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect (a single slow item blocks all nested fetches):**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct (each item chains its own nested fetch):**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.
diff --git a/skills/vercel/react-best-practices/rules/server-serialization.md b/skills/vercel/react-best-practices/rules/server-serialization.md
new file mode 100644
index 0000000..39c5c41
--- /dev/null
+++ b/skills/vercel/react-best-practices/rules/server-serialization.md
@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
diff --git a/skills/vercel/react-native-skills/AGENTS.md b/skills/vercel/react-native-skills/AGENTS.md
new file mode 100644
index 0000000..d263eb9
--- /dev/null
+++ b/skills/vercel/react-native-skills/AGENTS.md
@@ -0,0 +1,2897 @@
+# React Native Skills
+
+**Version 1.0.0**  
+Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React Native codebases. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React Native applications, designed for AI agents and LLMs. Contains 35+ rules across 13 categories, prioritized by impact from critical (core rendering, list performance) to incremental (fonts, imports). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Core Rendering](#1-core-rendering) — **CRITICAL**
+   - 1.1 [Never Use && with Potentially Falsy Values](#11-never-use--with-potentially-falsy-values)
+   - 1.2 [Wrap Strings in Text Components](#12-wrap-strings-in-text-components)
+2. [List Performance](#2-list-performance) — **HIGH**
+   - 2.1 [Avoid Inline Objects in renderItem](#21-avoid-inline-objects-in-renderitem)
+   - 2.2 [Hoist callbacks to the root of lists](#22-hoist-callbacks-to-the-root-of-lists)
+   - 2.3 [Keep List Items Lightweight](#23-keep-list-items-lightweight)
+   - 2.4 [Optimize List Performance with Stable Object References](#24-optimize-list-performance-with-stable-object-references)
+   - 2.5 [Pass Primitives to List Items for Memoization](#25-pass-primitives-to-list-items-for-memoization)
+   - 2.6 [Use a List Virtualizer for Any List](#26-use-a-list-virtualizer-for-any-list)
+   - 2.7 [Use Compressed Images in Lists](#27-use-compressed-images-in-lists)
+   - 2.8 [Use Item Types for Heterogeneous Lists](#28-use-item-types-for-heterogeneous-lists)
+3. [Animation](#3-animation) — **HIGH**
+   - 3.1 [Animate Transform and Opacity Instead of Layout Properties](#31-animate-transform-and-opacity-instead-of-layout-properties)
+   - 3.2 [Prefer useDerivedValue Over useAnimatedReaction](#32-prefer-usederivedvalue-over-useanimatedreaction)
+   - 3.3 [Use GestureDetector for Animated Press States](#33-use-gesturedetector-for-animated-press-states)
+4. [Scroll Performance](#4-scroll-performance) — **HIGH**
+   - 4.1 [Never Track Scroll Position in useState](#41-never-track-scroll-position-in-usestate)
+5. [Navigation](#5-navigation) — **HIGH**
+   - 5.1 [Use Native Navigators for Navigation](#51-use-native-navigators-for-navigation)
+6. [React State](#6-react-state) — **MEDIUM**
+   - 6.1 [Minimize State Variables and Derive Values](#61-minimize-state-variables-and-derive-values)
+   - 6.2 [Use fallback state instead of initialState](#62-use-fallback-state-instead-of-initialstate)
+   - 6.3 [useState Dispatch updaters for State That Depends on Current Value](#63-usestate-dispatch-updaters-for-state-that-depends-on-current-value)
+7. [State Architecture](#7-state-architecture) — **MEDIUM**
+   - 7.1 [State Must Represent Ground Truth](#71-state-must-represent-ground-truth)
+8. [React Compiler](#8-react-compiler) — **MEDIUM**
+   - 8.1 [Destructure Functions Early in Render (React Compiler)](#81-destructure-functions-early-in-render-react-compiler)
+   - 8.2 [Use .get() and .set() for Reanimated Shared Values (not .value)](#82-use-get-and-set-for-reanimated-shared-values-not-value)
+9. [User Interface](#9-user-interface) — **MEDIUM**
+   - 9.1 [Measuring View Dimensions](#91-measuring-view-dimensions)
+   - 9.2 [Modern React Native Styling Patterns](#92-modern-react-native-styling-patterns)
+   - 9.3 [Use contentInset for Dynamic ScrollView Spacing](#93-use-contentinset-for-dynamic-scrollview-spacing)
+   - 9.4 [Use contentInsetAdjustmentBehavior for Safe Areas](#94-use-contentinsetadjustmentbehavior-for-safe-areas)
+   - 9.5 [Use expo-image for Optimized Images](#95-use-expo-image-for-optimized-images)
+   - 9.6 [Use Galeria for Image Galleries and Lightbox](#96-use-galeria-for-image-galleries-and-lightbox)
+   - 9.7 [Use Native Menus for Dropdowns and Context Menus](#97-use-native-menus-for-dropdowns-and-context-menus)
+   - 9.8 [Use Native Modals Over JS-Based Bottom Sheets](#98-use-native-modals-over-js-based-bottom-sheets)
+   - 9.9 [Use Pressable Instead of Touchable Components](#99-use-pressable-instead-of-touchable-components)
+10. [Design System](#10-design-system) — **MEDIUM**
+   - 10.1 [Use Compound Components Over Polymorphic Children](#101-use-compound-components-over-polymorphic-children)
+11. [Monorepo](#11-monorepo) — **LOW**
+   - 11.1 [Install Native Dependencies in App Directory](#111-install-native-dependencies-in-app-directory)
+   - 11.2 [Use Single Dependency Versions Across Monorepo](#112-use-single-dependency-versions-across-monorepo)
+12. [Third-Party Dependencies](#12-third-party-dependencies) — **LOW**
+   - 12.1 [Import from Design System Folder](#121-import-from-design-system-folder)
+13. [JavaScript](#13-javascript) — **LOW**
+   - 13.1 [Hoist Intl Formatter Creation](#131-hoist-intl-formatter-creation)
+14. [Fonts](#14-fonts) — **LOW**
+   - 14.1 [Load fonts natively at build time](#141-load-fonts-natively-at-build-time)
+
+---
+
+## 1. Core Rendering
+
+**Impact: CRITICAL**
+
+Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+### 1.1 Never Use && with Potentially Falsy Values
+
+**Impact: CRITICAL (prevents production crash)**
+
+Never use `{value && <Component />}` when `value` could be an empty string or
+
+`0`. These are falsy but JSX-renderable—React Native will try to render them as
+
+text outside a `<Text>` component, causing a hard crash in production.
+
+**Incorrect: crashes if count is 0 or name is ""**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name && <Text>{name}</Text>}
+      {count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+// If name="" or count=0, renders the falsy value → crash
+```
+
+**Correct: ternary with null**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name ? <Text>{name}</Text> : null}
+      {count ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+**Correct: explicit boolean coercion**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {!!name && <Text>{name}</Text>}
+      {!!count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+```
+
+**Best: early return**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  if (!name) return null
+
+  return (
+    <View>
+      <Text>{name}</Text>
+      {count > 0 ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+Early returns are clearest. When using conditionals inline, prefer ternary or
+
+explicit boolean checks.
+
+**Lint rule:** Enable `react/jsx-no-leaked-render` from
+
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)
+
+to catch this automatically.
+
+### 1.2 Wrap Strings in Text Components
+
+**Impact: CRITICAL (prevents runtime crash)**
+
+Strings must be rendered inside `<Text>`. React Native crashes if a string is a
+
+direct child of `<View>`.
+
+**Incorrect: crashes**
+
+```tsx
+import { View } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return <View>Hello, {name}!</View>
+}
+// Error: Text strings must be rendered within a <Text> component.
+```
+
+**Correct:**
+
+```tsx
+import { View, Text } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return (
+    <View>
+      <Text>Hello, {name}!</Text>
+    </View>
+  )
+}
+```
+
+---
+
+## 2. List Performance
+
+**Impact: HIGH**
+
+Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+### 2.1 Avoid Inline Objects in renderItem
+
+**Impact: HIGH (prevents unnecessary re-renders of memoized list items)**
+
+Don't create new objects inside `renderItem` to pass as props. Inline objects
+
+create new references on every render, breaking memoization. Pass primitive
+
+values directly from `item` instead.
+
+**Incorrect: inline object breaks memoization**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        <UserRow
+          // Bad: new object on every render
+          user={{ id: item.id, name: item.name, avatar: item.avatar }}
+        />
+      )}
+    />
+  )
+}
+```
+
+**Incorrect: inline style object**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Bad: new style object on every render
+    style={{ backgroundColor: item.isActive ? 'green' : 'gray' }}
+  />
+)}
+```
+
+**Correct: pass item directly or primitives**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        // Good: pass the item directly
+        <UserRow user={item} />
+      )}
+    />
+  )
+}
+```
+
+**Correct: pass primitives, derive inside child**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    id={item.id}
+    name={item.name}
+    isActive={item.isActive}
+  />
+)}
+
+const UserRow = memo(function UserRow({ id, name, isActive }: Props) {
+  // Good: derive style inside memoized component
+  const backgroundColor = isActive ? 'green' : 'gray'
+  return <View style={[styles.row, { backgroundColor }]}>{/* ... */}</View>
+})
+```
+
+**Correct: hoist static styles in module scope**
+
+```tsx
+const activeStyle = { backgroundColor: 'green' }
+const inactiveStyle = { backgroundColor: 'gray' }
+
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Good: stable references
+    style={item.isActive ? activeStyle : inactiveStyle}
+  />
+)}
+```
+
+Passing primitives or stable references allows `memo()` to skip re-renders when
+
+the actual values haven't changed.
+
+**Note:** If you have the React Compiler enabled, it handles memoization
+
+automatically and these manual optimizations become less critical.
+
+### 2.2 Hoist callbacks to the root of lists
+
+**Impact: MEDIUM (Fewer re-renders and faster lists)**
+
+When passing callback functions to list items, create a single instance of the
+
+callback at the root of the list. Items should then call it with a unique
+
+identifier.
+
+**Incorrect: creates a new callback on each render**
+
+```typescript
+return (
+  <LegendList
+    renderItem={({ item }) => {
+      // bad: creates a new callback on each render
+      const onPress = () => handlePress(item.id)
+      return <Item key={item.id} item={item} onPress={onPress} />
+    }}
+  />
+)
+```
+
+**Correct: a single function instance passed to each item**
+
+```typescript
+const onPress = useCallback(() => handlePress(item.id), [handlePress, item.id])
+
+return (
+  <LegendList
+    renderItem={({ item }) => (
+      <Item key={item.id} item={item} onPress={onPress} />
+    )}
+  />
+)
+```
+
+Reference: [https://example.com](https://example.com)
+
+### 2.3 Keep List Items Lightweight
+
+**Impact: HIGH (reduces render time for visible items during scroll)**
+
+List items should be as inexpensive as possible to render. Minimize hooks, avoid
+
+queries, and limit React Context access. Virtualized lists render many items
+
+during scroll—expensive items cause jank.
+
+**Incorrect: heavy list item**
+
+```tsx
+function ProductRow({ id }: { id: string }) {
+  // Bad: query inside list item
+  const { data: product } = useQuery(['product', id], () => fetchProduct(id))
+  // Bad: multiple context accesses
+  const theme = useContext(ThemeContext)
+  const user = useContext(UserContext)
+  const cart = useContext(CartContext)
+  // Bad: expensive computation
+  const recommendations = useMemo(
+    () => computeRecommendations(product),
+    [product]
+  )
+
+  return <View>{/* ... */}</View>
+}
+```
+
+**Correct: lightweight list item**
+
+```tsx
+function ProductRow({ name, price, imageUrl }: Props) {
+  // Good: receives only primitives, minimal hooks
+  return (
+    <View>
+      <Image source={{ uri: imageUrl }} />
+      <Text>{name}</Text>
+      <Text>{price}</Text>
+    </View>
+  )
+}
+```
+
+**Move data fetching to parent:**
+
+```tsx
+// Parent fetches all data once
+function ProductList() {
+  const { data: products } = useQuery(['products'], fetchProducts)
+
+  return (
+    <LegendList
+      data={products}
+      renderItem={({ item }) => (
+        <ProductRow name={item.name} price={item.price} imageUrl={item.image} />
+      )}
+    />
+  )
+}
+```
+
+**For shared values, use Zustand selectors instead of Context:**
+
+```tsx
+// Incorrect: Context causes re-render when any cart value changes
+function ProductRow({ id, name }: Props) {
+  const { items } = useContext(CartContext)
+  const inCart = items.includes(id)
+  // ...
+}
+
+// Correct: Zustand selector only re-renders when this specific value changes
+function ProductRow({ id, name }: Props) {
+  // use Set.has (created once at the root) instead of Array.includes()
+  const inCart = useCartStore((s) => s.items.has(id))
+  // ...
+}
+```
+
+**Guidelines for list items:**
+
+- No queries or data fetching
+
+- No expensive computations (move to parent or memoize at parent level)
+
+- Prefer Zustand selectors over React Context
+
+- Minimize useState/useEffect hooks
+
+- Pass pre-computed values as props
+
+The goal: list items should be simple rendering functions that take props and
+
+return JSX.
+
+### 2.4 Optimize List Performance with Stable Object References
+
+**Impact: CRITICAL (virtualization relies on reference stability)**
+
+Don't map or filter data before passing to virtualized lists. Virtualization
+
+relies on object reference stability to know what changed—new references cause
+
+full re-renders of all visible items. Attempt to prevent frequent renders at the
+
+list-parent level.
+
+Where needed, use context selectors within list items.
+
+**Incorrect: creates new object references on every keystroke**
+
+```tsx
+function DomainSearch() {
+  const { keyword, setKeyword } = useKeywordZustandState()
+  const { data: tlds } = useTlds()
+
+  // Bad: creates new objects on every render, reparenting the entire list on every keystroke
+  const domains = tlds.map((tld) => ({
+    domain: `${keyword}.${tld.name}`,
+    tld: tld.name,
+    price: tld.price,
+  }))
+
+  return (
+    <>
+      <TextInput value={keyword} onChangeText={setKeyword} />
+      <LegendList
+        data={domains}
+        renderItem={({ item }) => <DomainItem item={item} keyword={keyword} />}
+      />
+    </>
+  )
+}
+```
+
+**Correct: stable references, transform inside items**
+
+```tsx
+const renderItem = ({ item }) => <DomainItem tld={item} />
+
+function DomainSearch() {
+  const { data: tlds } = useTlds()
+
+  return (
+    <LegendList
+      // good: as long as the data is stable, LegendList will not re-render the entire list
+      data={tlds}
+      renderItem={renderItem}
+    />
+  )
+}
+
+function DomainItem({ tld }: { tld: Tld }) {
+  // good: transform within items, and don't pass the dynamic data as a prop
+  // good: use a selector function from zustand to receive a stable string back
+  const domain = useKeywordZustandState((s) => s.keyword + '.' + tld.name)
+  return <Text>{domain}</Text>
+}
+```
+
+**Updating parent array reference:**
+
+```tsx
+// good: creates a new array instance without mutating the inner objects
+// good: parent array reference is unaffected by typing and updating "keyword"
+const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
+
+return <LegendList data={sortedTlds} renderItem={renderItem} />
+```
+
+Creating a new array instance can be okay, as long as its inner object
+
+references are stable. For instance, if you sort a list of objects:
+
+Even though this creates a new array instance `sortedTlds`, the inner object
+
+references are stable.
+
+**With zustand for dynamic data: avoids parent re-renders**
+
+```tsx
+function DomainItemFavoriteButton({ tld }: { tld: Tld }) {
+  const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))
+  return <TldFavoriteButton isFavorited={isFavorited} />
+}
+```
+
+Virtualization can now skip items that haven't changed when typing. Only visible
+
+items (~20) re-render on keystroke, rather than the parent.
+
+**Deriving state within list items based on parent data (avoids parent
+
+re-renders):**
+
+For components where the data is conditional based on the parent state, this
+
+pattern is even more important. For example, if you are checking if an item is
+
+favorited, toggling favorites only re-renders one component if the item itself
+
+is in charge of accessing the state rather than the parent:
+
+Note: if you're using the React Compiler, you can read React Context values
+
+directly within list items. Although this is slightly slower than using a
+
+Zustand selector in most cases, the effect may be negligible.
+
+### 2.5 Pass Primitives to List Items for Memoization
+
+**Impact: HIGH (enables effective memo() comparison)**
+
+When possible, pass only primitive values (strings, numbers, booleans) as props
+
+to list item components. Primitives enable shallow comparison in `memo()` to
+
+work correctly, skipping re-renders when values haven't changed.
+
+**Incorrect: object prop requires deep comparison**
+
+```tsx
+type User = { id: string; name: string; email: string; avatar: string }
+
+const UserRow = memo(function UserRow({ user }: { user: User }) {
+  // memo() compares user by reference, not value
+  // If parent creates new user object, this re-renders even if data is same
+  return <Text>{user.name}</Text>
+})
+
+renderItem={({ item }) => <UserRow user={item} />}
+```
+
+This can still be optimized, but it is harder to memoize properly.
+
+**Correct: primitive props enable shallow comparison**
+
+```tsx
+const UserRow = memo(function UserRow({
+  id,
+  name,
+  email,
+}: {
+  id: string
+  name: string
+  email: string
+}) {
+  // memo() compares each primitive directly
+  // Re-renders only if id, name, or email actually changed
+  return <Text>{name}</Text>
+})
+
+renderItem={({ item }) => (
+  <UserRow id={item.id} name={item.name} email={item.email} />
+)}
+```
+
+**Pass only what you need:**
+
+```tsx
+// Incorrect: passing entire item when you only need name
+<UserRow user={item} />
+
+// Correct: pass only the fields the component uses
+<UserRow name={item.name} avatarUrl={item.avatar} />
+```
+
+**For callbacks, hoist or use item ID:**
+
+```tsx
+// Incorrect: inline function creates new reference
+<UserRow name={item.name} onPress={() => handlePress(item.id)} />
+
+// Correct: pass ID, handle in child
+<UserRow id={item.id} name={item.name} />
+
+const UserRow = memo(function UserRow({ id, name }: Props) {
+  const handlePress = useCallback(() => {
+    // use id here
+  }, [id])
+  return <Pressable onPress={handlePress}><Text>{name}</Text></Pressable>
+})
+```
+
+Primitive props make memoization predictable and effective.
+
+**Note:** If you have the React Compiler enabled, you do not need to use
+
+`memo()` or `useCallback()`, but the object references still apply.
+
+### 2.6 Use a List Virtualizer for Any List
+
+**Impact: HIGH (reduced memory, faster mounts)**
+
+Use a list virtualizer like LegendList or FlashList instead of ScrollView with
+
+mapped children—even for short lists. Virtualizers only render visible items,
+
+reducing memory usage and mount time. ScrollView renders all children upfront,
+
+which gets expensive quickly.
+
+**Incorrect: ScrollView renders all items at once**
+
+```tsx
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <ScrollView>
+      {items.map((item) => (
+        <ItemCard key={item.id} item={item} />
+      ))}
+    </ScrollView>
+  )
+}
+// 50 items = 50 components mounted, even if only 10 visible
+```
+
+**Correct: virtualizer renders only visible items**
+
+```tsx
+import { LegendList } from '@legendapp/list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+      estimatedItemSize={80}
+    />
+  )
+}
+// Only ~10-15 visible items mounted at a time
+```
+
+**Alternative: FlashList**
+
+```tsx
+import { FlashList } from '@shopify/flash-list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <FlashList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+    />
+  )
+}
+```
+
+Benefits apply to any screen with scrollable content—profiles, settings, feeds,
+
+search results. Default to virtualization.
+
+### 2.7 Use Compressed Images in Lists
+
+**Impact: HIGH (faster load times, less memory)**
+
+Always load compressed, appropriately-sized images in lists. Full-resolution
+
+images consume excessive memory and cause scroll jank. Request thumbnails from
+
+your server or use an image CDN with resize parameters.
+
+**Incorrect: full-resolution images**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  return (
+    <View>
+      {/* 4000x3000 image loaded for a 100x100 thumbnail */}
+      <Image
+        source={{ uri: product.imageUrl }}
+        style={{ width: 100, height: 100 }}
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+**Correct: request appropriately-sized image**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  // Request a 200x200 image (2x for retina)
+  const thumbnailUrl = `${product.imageUrl}?w=200&h=200&fit=cover`
+
+  return (
+    <View>
+      <Image
+        source={{ uri: thumbnailUrl }}
+        style={{ width: 100, height: 100 }}
+        contentFit='cover'
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+Use an optimized image component with built-in caching and placeholder support,
+
+such as `expo-image` or `SolitoImage` (which uses `expo-image` under the hood).
+
+Request images at 2x the display size for retina screens.
+
+### 2.8 Use Item Types for Heterogeneous Lists
+
+**Impact: HIGH (efficient recycling, less layout thrashing)**
+
+When a list has different item layouts (messages, images, headers, etc.), use a
+
+`type` field on each item and provide `getItemType` to the list. This puts items
+
+into separate recycling pools so a message component never gets recycled into an
+
+image component.
+
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
+
+**Incorrect: single component with conditionals**
+
+```tsx
+type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }
+
+function ListItem({ item }: { item: Item }) {
+  if (item.isHeader) {
+    return <HeaderItem title={item.text} />
+  }
+  if (item.imageUrl) {
+    return <ImageItem url={item.imageUrl} />
+  }
+  return <MessageItem text={item.text} />
+}
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      renderItem={({ item }) => <ListItem item={item} />}
+      recycleItems
+    />
+  )
+}
+```
+
+**Correct: typed items with separate components**
+
+```tsx
+type HeaderItem = { id: string; type: 'header'; title: string }
+type MessageItem = { id: string; type: 'message'; text: string }
+type ImageItem = { id: string; type: 'image'; url: string }
+type FeedItem = HeaderItem | MessageItem | ImageItem
+
+function Feed({ items }: { items: FeedItem[] }) {
+  return (
+    <LegendList
+      data={items}
+      keyExtractor={(item) => item.id}
+      getItemType={(item) => item.type}
+      renderItem={({ item }) => {
+        switch (item.type) {
+          case 'header':
+            return <SectionHeader title={item.title} />
+          case 'message':
+            return <MessageRow text={item.text} />
+          case 'image':
+            return <ImageRow url={item.url} />
+        }
+      }}
+      recycleItems
+    />
+  )
+}
+```
+
+**Why this matters:**
+
+```tsx
+<LegendList
+  data={items}
+  keyExtractor={(item) => item.id}
+  getItemType={(item) => item.type}
+  getEstimatedItemSize={(index, item, itemType) => {
+    switch (itemType) {
+      case 'header':
+        return 48
+      case 'message':
+        return 72
+      case 'image':
+        return 300
+      default:
+        return 72
+    }
+  }}
+  renderItem={({ item }) => {
+    /* ... */
+  }}
+  recycleItems
+/>
+```
+
+- **Recycling efficiency**: Items with the same type share a recycling pool
+
+- **No layout thrashing**: A header never recycles into an image cell
+
+- **Type safety**: TypeScript can narrow the item type in each branch
+
+- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for
+
+  accurate estimates per type
+
+---
+
+## 3. Animation
+
+**Impact: HIGH**
+
+GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+### 3.1 Animate Transform and Opacity Instead of Layout Properties
+
+**Impact: HIGH (GPU-accelerated animations, no layout recalculation)**
+
+Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.
+
+**Incorrect: animates height, triggers layout every frame**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    height: withTiming(expanded ? 200 : 0), // triggers layout on every frame
+    overflow: 'hidden',
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+**Correct: animates scaleY, GPU-accelerated**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scaleY: withTiming(expanded ? 1 : 0) },
+    ],
+    opacity: withTiming(expanded ? 1 : 0),
+  }))
+
+  return (
+    <Animated.View style={[{ height: 200, transformOrigin: 'top' }, animatedStyle]}>
+      {children}
+    </Animated.View>
+  )
+}
+```
+
+**Correct: animates translateY for slide animations**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function SlideIn({ visible }: { visible: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateY: withTiming(visible ? 0 : 100) },
+    ],
+    opacity: withTiming(visible ? 1 : 0),
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.
+
+### 3.2 Prefer useDerivedValue Over useAnimatedReaction
+
+**Impact: MEDIUM (cleaner code, automatic dependency tracking)**
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+
+`useAnimatedReaction`. Derived values are declarative, automatically track
+
+dependencies, and return a value you can use directly. Animated reactions are
+
+for side effects, not derivations.
+
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)
+
+**Incorrect: useAnimatedReaction for derivation**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+  const opacity = useSharedValue(1)
+
+  useAnimatedReaction(
+    () => progress.value,
+    (current) => {
+      opacity.value = 1 - current
+    }
+  )
+
+  // ...
+}
+```
+
+**Correct: useDerivedValue**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+
+  const opacity = useDerivedValue(() => 1 - progress.get())
+
+  // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+### 3.3 Use GestureDetector for Animated Press States
+
+**Impact: MEDIUM (UI thread animations, smoother press feedback)**
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+
+`Gesture.Tap()` and shared values instead of Pressable's
+
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+
+JS thread round-trip for press animations.
+
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)
+
+**Incorrect: Pressable with JS thread callbacks**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  const scale = useSharedValue(1)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }))
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onPressIn={() => (scale.value = withTiming(0.95))}
+      onPressOut={() => (scale.value = withTiming(1))}
+    >
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </Pressable>
+  )
+}
+```
+
+**Correct: GestureDetector with UI thread worklets**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+  interpolate,
+  runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  // Store the press STATE (0 = not pressed, 1 = pressed)
+  const pressed = useSharedValue(0)
+
+  const tap = Gesture.Tap()
+    .onBegin(() => {
+      pressed.set(withTiming(1))
+    })
+    .onFinalize(() => {
+      pressed.set(withTiming(0))
+    })
+    .onEnd(() => {
+      runOnJS(onPress)()
+    })
+
+  // Derive visual values from the state
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+    ],
+  }))
+
+  return (
+    <GestureDetector gesture={tap}>
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </GestureDetector>
+  )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+---
+
+## 4. Scroll Performance
+
+**Impact: HIGH**
+
+Tracking scroll position without causing render thrashing.
+
+### 4.1 Never Track Scroll Position in useState
+
+**Impact: HIGH (prevents render thrashing during scroll)**
+
+Never store scroll position in `useState`. Scroll events fire rapidly—state
+
+updates cause render thrashing and dropped frames. Use a Reanimated shared value
+
+for animations or a ref for non-reactive tracking.
+
+**Incorrect: useState causes jank**
+
+```tsx
+import { useState } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const [scrollY, setScrollY] = useState(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
+
+**Correct: Reanimated for animations**
+
+```tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedScrollHandler,
+} from 'react-native-reanimated'
+
+function Feed() {
+  const scrollY = useSharedValue(0)
+
+  const onScroll = useAnimatedScrollHandler({
+    onScroll: (e) => {
+      scrollY.value = e.contentOffset.y // runs on UI thread, no re-render
+    },
+  })
+
+  return (
+    <Animated.ScrollView
+      onScroll={onScroll}
+      // higher number has better performance, but it fires less often.
+      // unset this if you need higher precision over performance.
+      scrollEventThrottle={16}
+    />
+  )
+}
+```
+
+**Correct: ref for non-reactive tracking**
+
+```tsx
+import { useRef } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const scrollY = useRef(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    scrollY.current = e.nativeEvent.contentOffset.y // no re-render
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
+
+---
+
+## 5. Navigation
+
+**Impact: HIGH**
+
+Using native navigators for stack and tab navigation instead of
+JS-based alternatives.
+
+### 5.1 Use Native Navigators for Navigation
+
+**Impact: HIGH (native performance, platform-appropriate UI)**
+
+Always use native navigators instead of JS-based ones. Native navigators use
+
+platform APIs (UINavigationController on iOS, Fragment on Android) for better
+
+performance and native behavior.
+
+**For stacks:** Use `@react-navigation/native-stack` or expo-router's default
+
+stack (which uses native-stack). Avoid `@react-navigation/stack`.
+
+**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native
+
+tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.
+
+- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
+
+- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
+
+- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
+
+- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)
+
+**Incorrect: JS stack navigator**
+
+```tsx
+import { createStackNavigator } from '@react-navigation/stack'
+
+const Stack = createStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct: native stack with react-navigation**
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct: expo-router uses native stack by default**
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function Layout() {
+  return <Stack />
+}
+```
+
+**Incorrect: JS bottom tabs**
+
+```tsx
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'
+
+const Tab = createBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen name='Home' component={HomeScreen} />
+      <Tab.Screen name='Settings' component={SettingsScreen} />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct: native bottom tabs with react-navigation**
+
+```tsx
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
+
+const Tab = createNativeBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen
+        name='Home'
+        component={HomeScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'house' }),
+        }}
+      />
+      <Tab.Screen
+        name='Settings'
+        component={SettingsScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'gear' }),
+        }}
+      />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct: expo-router native tabs**
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name='index'>
+        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name='settings'>
+        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='gear' md='settings' />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  )
+}
+```
+
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+
+behind the translucent tab bar. If you need to disable this, use
+
+`disableAutomaticContentInsets` on the trigger.
+
+**Incorrect: custom header component**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    header: () => <CustomHeader title='Profile' />,
+  }}
+/>
+```
+
+**Correct: native header options**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    title: 'Profile',
+    headerLargeTitleEnabled: true,
+    headerSearchBarOptions: {
+      placeholder: 'Search',
+    },
+  }}
+/>
+```
+
+Native headers support iOS large titles, search bars, blur effects, and proper
+
+safe area handling automatically.
+
+- **Performance**: Native transitions and gestures run on the UI thread
+
+- **Platform behavior**: Automatic iOS large titles, Android material design
+
+- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
+
+  areas
+
+- **Accessibility**: Platform accessibility features work automatically
+
+---
+
+## 6. React State
+
+**Impact: MEDIUM**
+
+Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+### 6.1 Minimize State Variables and Derive Values
+
+**Impact: MEDIUM (fewer re-renders, less state drift)**
+
+Use the fewest state variables possible. If a value can be computed from existing state or props, derive it during render instead of storing it in state. Redundant state causes unnecessary re-renders and can drift out of sync.
+
+**Incorrect: redundant state**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const [total, setTotal] = useState(0)
+  const [itemCount, setItemCount] = useState(0)
+
+  useEffect(() => {
+    setTotal(items.reduce((sum, item) => sum + item.price, 0))
+    setItemCount(items.length)
+  }, [items])
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Correct: derived values**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const total = items.reduce((sum, item) => sum + item.price, 0)
+  const itemCount = items.length
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Another example:**
+
+```tsx
+// Incorrect: storing both firstName, lastName, AND fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const [fullName, setFullName] = useState('')
+
+// Correct: derive fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const fullName = `${firstName} ${lastName}`
+```
+
+State should be the minimal source of truth. Everything else is derived.
+
+Reference: [https://react.dev/learn/choosing-the-state-structure](https://react.dev/learn/choosing-the-state-structure)
+
+### 6.2 Use fallback state instead of initialState
+
+**Impact: MEDIUM (reactive fallbacks without syncing)**
+
+Use `undefined` as initial state and nullish coalescing (`??`) to fall back to
+
+parent or server values. State represents user intent only—`undefined` means
+
+"user hasn't chosen yet." This enables reactive fallbacks that update when the
+
+source changes, not just on initial render.
+
+**Incorrect: syncs state, loses reactivity**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [enabled, setEnabled] = useState(defaultEnabled)
+  // If fallbackEnabled changes, state is stale
+  // State mixes user intent with default value
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**Correct: state is user intent, reactive fallback**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [_enabled, setEnabled] = useState<boolean | undefined>(undefined)
+  const enabled = _enabled ?? defaultEnabled
+  // undefined = user hasn't touched it, falls back to prop
+  // If defaultEnabled changes, component reflects it
+  // Once user interacts, their choice persists
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**With server data:**
+
+```tsx
+function ProfileForm({ data }: { data: User }) {
+  const [_theme, setTheme] = useState<string | undefined>(undefined)
+  const theme = _theme ?? data.theme
+  // Shows server value until user overrides
+  // Server refetch updates the fallback automatically
+
+  return <ThemePicker value={theme} onChange={setTheme} />
+}
+```
+
+### 6.3 useState Dispatch updaters for State That Depends on Current Value
+
+**Impact: MEDIUM (avoids stale closures, prevents unnecessary re-renders)**
+
+When the next state depends on the current state, use a dispatch updater
+
+(`setState(prev => ...)`) instead of reading the state variable directly in a
+
+callback. This avoids stale closures and ensures you're comparing against the
+
+latest value.
+
+**Incorrect: reads state directly**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  // size may be stale in this closure
+  if (size?.width !== width || size?.height !== height) {
+    setSize({ width, height })
+  }
+}
+```
+
+**Correct: dispatch updater**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => {
+    if (prev?.width === width && prev?.height === height) return prev
+    return { width, height }
+  })
+}
+```
+
+Returning the previous value from the updater skips the re-render.
+
+For primitive states, you don't need to compare values before firing a
+
+re-render.
+
+**Incorrect: unnecessary comparison for primitive state**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => (prev === width ? prev : width))
+}
+```
+
+**Correct: sets primitive state directly**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize(width)
+}
+```
+
+However, if the next state depends on the current state, you should still use a
+
+dispatch updater.
+
+**Incorrect: reads state directly from the callback**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount(count + 1)
+}
+```
+
+**Correct: dispatch updater**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount((prev) => prev + 1)
+}
+```
+
+---
+
+## 7. State Architecture
+
+**Impact: MEDIUM**
+
+Ground truth principles for state variables and derived values.
+
+### 7.1 State Must Represent Ground Truth
+
+**Impact: HIGH (cleaner logic, easier debugging, single source of truth)**
+
+State variables—both React `useState` and Reanimated shared values—should
+
+represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),
+
+not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive
+
+visual values from state using computation or interpolation.
+
+**Incorrect: storing the visual output**
+
+```tsx
+const scale = useSharedValue(1)
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    scale.set(withTiming(0.95))
+  })
+  .onFinalize(() => {
+    scale.set(withTiming(1))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.get() }],
+}))
+```
+
+**Correct: storing the state, deriving the visual**
+
+```tsx
+const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    pressed.set(withTiming(1))
+  })
+  .onFinalize(() => {
+    pressed.set(withTiming(0))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],
+}))
+```
+
+**Why this matters:**
+
+State variables should represent real "state", not necessarily a desired end
+
+result.
+
+1. **Single source of truth** — The state (`pressed`) describes what's
+
+   happening; visuals are derived
+
+2. **Easier to extend** — Adding opacity, rotation, or other effects just
+
+   requires more interpolations from the same state
+
+3. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`
+
+4. **Reusable logic** — The same `pressed` value can drive multiple visual
+
+   properties
+
+**Same principle for React state:**
+
+```tsx
+// Incorrect: storing derived values
+const [isExpanded, setIsExpanded] = useState(false)
+const [height, setHeight] = useState(0)
+
+useEffect(() => {
+  setHeight(isExpanded ? 200 : 0)
+}, [isExpanded])
+
+// Correct: derive from state
+const [isExpanded, setIsExpanded] = useState(false)
+const height = isExpanded ? 200 : 0
+```
+
+State is the minimal truth. Everything else is derived.
+
+---
+
+## 8. React Compiler
+
+**Impact: MEDIUM**
+
+Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+### 8.1 Destructure Functions Early in Render (React Compiler)
+
+**Impact: HIGH (stable references, fewer re-renders)**
+
+This rule is only applicable if you are using the React Compiler.
+
+Destructure functions from hooks at the top of render scope. Never dot into
+
+objects to call functions. Destructured functions are stable references; dotting
+
+creates new references and breaks memoization.
+
+**Incorrect: dotting into object**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton(props) {
+  const router = useRouter()
+
+  // bad: react-compiler will key the cache on "props" and "router", which are objects that change each render
+  const handlePress = () => {
+    props.onSave()
+    router.push('/success') // unstable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
+
+**Correct: destructure early**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton({ onSave }) {
+  const { push } = useRouter()
+
+  // good: react-compiler will key on push and onSave
+  const handlePress = () => {
+    onSave()
+    push('/success') // stable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
+
+### 8.2 Use .get() and .set() for Reanimated Shared Values (not .value)
+
+**Impact: LOW (required for React Compiler compatibility)**
+
+With React Compiler enabled, use `.get()` and `.set()` instead of reading or
+
+writing `.value` directly on Reanimated shared values. The compiler can't track
+
+property access—explicit methods ensure correct behavior.
+
+**Incorrect: breaks with React Compiler**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.value = count.value + 1 // opts out of react compiler
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.value}`} />
+}
+```
+
+**Correct: React Compiler compatible**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.set(count.get() + 1)
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.get()}`} />
+}
+```
+
+See the
+
+[Reanimated docs](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/#react-compiler-support)
+
+for more.
+
+---
+
+## 9. User Interface
+
+**Impact: MEDIUM**
+
+Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+### 9.1 Measuring View Dimensions
+
+**Impact: MEDIUM (synchronous measurement, avoid unnecessary re-renders)**
+
+Use both `useLayoutEffect` (synchronous) and `onLayout` (for updates). The sync
+
+measurement gives you the initial size immediately; `onLayout` keeps it current
+
+when the view changes. For non-primitive states, use a dispatch updater to
+
+compare values and avoid unnecessary re-renders.
+
+**Height only:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [height, setHeight] = useState<number | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    // Sync measurement on mount (RN 0.82+)
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setHeight(rect.height)
+    // Pre-0.82: ref.current?.measure((x, y, w, h) => setHeight(h))
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    setHeight(e.nativeEvent.layout.height)
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+**Both dimensions:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+type Size = { width: number; height: number }
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [size, setSize] = useState<Size | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setSize({ width: rect.width, height: rect.height })
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout
+    setSize((prev) => {
+      // for non-primitive states, compare values before firing a re-render
+      if (prev?.width === width && prev?.height === height) return prev
+      return { width, height }
+    })
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+Use functional setState to compare—don't read state directly in the callback.
+
+### 9.2 Modern React Native Styling Patterns
+
+**Impact: MEDIUM (consistent design, smoother borders, cleaner layouts)**
+
+Follow these styling patterns for cleaner, more consistent React Native code.
+
+**Always use `borderCurve: 'continuous'` with `borderRadius`:**
+
+**Use `gap` instead of margin for spacing between elements:**
+
+```tsx
+// Incorrect – margin on children
+<View>
+  <Text style={{ marginBottom: 8 }}>Title</Text>
+  <Text style={{ marginBottom: 8 }}>Subtitle</Text>
+</View>
+
+// Correct – gap on parent
+<View style={{ gap: 8 }}>
+  <Text>Title</Text>
+  <Text>Subtitle</Text>
+</View>
+```
+
+**Use `padding` for space within, `gap` for space between:**
+
+```tsx
+<View style={{ padding: 16, gap: 12 }}>
+  <Text>First</Text>
+  <Text>Second</Text>
+</View>
+```
+
+**Use `experimental_backgroundImage` for linear gradients:**
+
+```tsx
+// Incorrect – third-party gradient library
+<LinearGradient colors={['#000', '#fff']} />
+
+// Correct – native CSS gradient syntax
+<View
+  style={{
+    experimental_backgroundImage: 'linear-gradient(to bottom, #000, #fff)',
+  }}
+/>
+```
+
+**Use CSS `boxShadow` string syntax for shadows:**
+
+```tsx
+// Incorrect – legacy shadow objects or elevation
+{ shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1 }
+{ elevation: 4 }
+
+// Correct – CSS box-shadow syntax
+{ boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)' }
+```
+
+**Avoid multiple font sizes – use weight and color for emphasis:**
+
+```tsx
+// Incorrect – varying font sizes for hierarchy
+<Text style={{ fontSize: 18 }}>Title</Text>
+<Text style={{ fontSize: 14 }}>Subtitle</Text>
+<Text style={{ fontSize: 12 }}>Caption</Text>
+
+// Correct – consistent size, vary weight and color
+<Text style={{ fontWeight: '600' }}>Title</Text>
+<Text style={{ color: '#666' }}>Subtitle</Text>
+<Text style={{ color: '#999' }}>Caption</Text>
+```
+
+Limiting font sizes creates visual consistency. Use `fontWeight` (bold/semibold)
+
+and grayscale colors for hierarchy instead.
+
+### 9.3 Use contentInset for Dynamic ScrollView Spacing
+
+**Impact: LOW (smoother updates, no layout recalculation)**
+
+When adding space to the top or bottom of a ScrollView that may change
+
+(keyboard, toolbars, dynamic content), use `contentInset` instead of padding.
+
+Changing `contentInset` doesn't trigger layout recalculation—it adjusts the
+
+scroll area without re-rendering content.
+
+**Incorrect: padding causes layout recalculation**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView contentContainerStyle={{ paddingBottom: bottomOffset }}>
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset triggers full layout recalculation
+```
+
+**Correct: contentInset for dynamic spacing**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView
+      contentInset={{ bottom: bottomOffset }}
+      scrollIndicatorInsets={{ bottom: bottomOffset }}
+    >
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset only adjusts scroll bounds
+```
+
+Use `scrollIndicatorInsets` alongside `contentInset` to keep the scroll
+
+indicator aligned. For static spacing that never changes, padding is fine.
+
+### 9.4 Use contentInsetAdjustmentBehavior for Safe Areas
+
+**Impact: MEDIUM (native safe area handling, no layout shifts)**
+
+Use `contentInsetAdjustmentBehavior="automatic"` on the root ScrollView instead of wrapping content in SafeAreaView or manual padding. This lets iOS handle safe area insets natively with proper scroll behavior.
+
+**Incorrect: SafeAreaView wrapper**
+
+```tsx
+import { SafeAreaView, ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <ScrollView>
+        <View>
+          <Text>Content</Text>
+        </View>
+      </ScrollView>
+    </SafeAreaView>
+  )
+}
+```
+
+**Incorrect: manual safe area padding**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+function MyScreen() {
+  const insets = useSafeAreaInsets()
+
+  return (
+    <ScrollView contentContainerStyle={{ paddingTop: insets.top }}>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+**Correct: native content inset adjustment**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <ScrollView contentInsetAdjustmentBehavior='automatic'>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+The native approach handles dynamic safe areas (keyboard, toolbars) and allows content to scroll behind the status bar naturally.
+
+### 9.5 Use expo-image for Optimized Images
+
+**Impact: HIGH (memory efficiency, caching, blurhash placeholders, progressive loading)**
+
+Use `expo-image` instead of React Native's `Image`. It provides memory-efficient caching, blurhash placeholders, progressive loading, and better performance for lists.
+
+**Incorrect: React Native Image**
+
+```tsx
+import { Image } from 'react-native'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**Correct: expo-image**
+
+```tsx
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**With blurhash placeholder:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  placeholder={{ blurhash: 'LGF5]+Yk^6#M@-5c,1J5@[or[Q6.' }}
+  contentFit="cover"
+  transition={200}
+  style={styles.image}
+/>
+```
+
+**With priority and caching:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  priority="high"
+  cachePolicy="memory-disk"
+  style={styles.hero}
+/>
+```
+
+**Key props:**
+
+- `placeholder` — Blurhash or thumbnail while loading
+
+- `contentFit` — `cover`, `contain`, `fill`, `scale-down`
+
+- `transition` — Fade-in duration (ms)
+
+- `priority` — `low`, `normal`, `high`
+
+- `cachePolicy` — `memory`, `disk`, `memory-disk`, `none`
+
+- `recyclingKey` — Unique key for list recycling
+
+For cross-platform (web + native), use `SolitoImage` from `solito/image` which uses `expo-image` under the hood.
+
+Reference: [https://docs.expo.dev/versions/latest/sdk/image/](https://docs.expo.dev/versions/latest/sdk/image/)
+
+### 9.6 Use Galeria for Image Galleries and Lightbox
+
+**Impact: MEDIUM**
+
+For image galleries with lightbox (tap to fullscreen), use `@nandorojo/galeria`.
+
+It provides native shared element transitions with pinch-to-zoom, double-tap
+
+zoom, and pan-to-close. Works with any image component including `expo-image`.
+
+**Incorrect: custom modal implementation**
+
+```tsx
+function ImageGallery({ urls }: { urls: string[] }) {
+  const [selected, setSelected] = useState<string | null>(null)
+
+  return (
+    <>
+      {urls.map((url) => (
+        <Pressable key={url} onPress={() => setSelected(url)}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Pressable>
+      ))}
+      <Modal visible={!!selected} onRequestClose={() => setSelected(null)}>
+        <Image source={{ uri: selected! }} style={styles.fullscreen} />
+      </Modal>
+    </>
+  )
+}
+```
+
+**Correct: Galeria with expo-image**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function ImageGallery({ urls }: { urls: string[] }) {
+  return (
+    <Galeria urls={urls}>
+      {urls.map((url, index) => (
+        <Galeria.Image index={index} key={url}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Galeria.Image>
+      ))}
+    </Galeria>
+  )
+}
+```
+
+**Single image:**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return (
+    <Galeria urls={[url]}>
+      <Galeria.Image>
+        <Image source={{ uri: url }} style={styles.avatar} />
+      </Galeria.Image>
+    </Galeria>
+  )
+}
+```
+
+**With low-res thumbnails and high-res fullscreen:**
+
+```tsx
+<Galeria urls={highResUrls}>
+  {lowResUrls.map((url, index) => (
+    <Galeria.Image index={index} key={url}>
+      <Image source={{ uri: url }} style={styles.thumbnail} />
+    </Galeria.Image>
+  ))}
+</Galeria>
+```
+
+**With FlashList:**
+
+```tsx
+<Galeria urls={urls}>
+  <FlashList
+    data={urls}
+    renderItem={({ item, index }) => (
+      <Galeria.Image index={index}>
+        <Image source={{ uri: item }} style={styles.thumbnail} />
+      </Galeria.Image>
+    )}
+    numColumns={3}
+    estimatedItemSize={100}
+  />
+</Galeria>
+```
+
+Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image
+
+component.
+
+Reference: [https://github.com/nandorojo/galeria](https://github.com/nandorojo/galeria)
+
+### 9.7 Use Native Menus for Dropdowns and Context Menus
+
+**Impact: HIGH (native accessibility, platform-consistent UX)**
+
+Use native platform menus instead of custom JS implementations. Native menus
+
+provide built-in accessibility, consistent platform UX, and better performance.
+
+Use [zeego](https://zeego.dev) for cross-platform native menus.
+
+**Incorrect: custom JS menu**
+
+```tsx
+import { useState } from 'react'
+import { View, Pressable, Text } from 'react-native'
+
+function MyMenu() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <View>
+      <Pressable onPress={() => setOpen(!open)}>
+        <Text>Open Menu</Text>
+      </Pressable>
+      {open && (
+        <View style={{ position: 'absolute', top: 40 }}>
+          <Pressable onPress={() => console.log('edit')}>
+            <Text>Edit</Text>
+          </Pressable>
+          <Pressable onPress={() => console.log('delete')}>
+            <Text>Delete</Text>
+          </Pressable>
+        </View>
+      )}
+    </View>
+  )
+}
+```
+
+**Correct: native menu with zeego**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MyMenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Open Menu</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='edit' onSelect={() => console.log('edit')}>
+          <DropdownMenu.ItemTitle>Edit</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Item
+          key='delete'
+          destructive
+          onSelect={() => console.log('delete')}
+        >
+          <DropdownMenu.ItemTitle>Delete</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Context menu: long-press**
+
+```tsx
+import * as ContextMenu from 'zeego/context-menu'
+
+function MyContextMenu() {
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <View style={{ padding: 20 }}>
+          <Text>Long press me</Text>
+        </View>
+      </ContextMenu.Trigger>
+
+      <ContextMenu.Content>
+        <ContextMenu.Item key='copy' onSelect={() => console.log('copy')}>
+          <ContextMenu.ItemTitle>Copy</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+
+        <ContextMenu.Item key='paste' onSelect={() => console.log('paste')}>
+          <ContextMenu.ItemTitle>Paste</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+      </ContextMenu.Content>
+    </ContextMenu.Root>
+  )
+}
+```
+
+**Checkbox items:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function SettingsMenu() {
+  const [notifications, setNotifications] = useState(true)
+
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Settings</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.CheckboxItem
+          key='notifications'
+          value={notifications}
+          onValueChange={() => setNotifications((prev) => !prev)}
+        >
+          <DropdownMenu.ItemIndicator />
+          <DropdownMenu.ItemTitle>Notifications</DropdownMenu.ItemTitle>
+        </DropdownMenu.CheckboxItem>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Submenus:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MenuWithSubmenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Options</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='home' onSelect={() => console.log('home')}>
+          <DropdownMenu.ItemTitle>Home</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Sub>
+          <DropdownMenu.SubTrigger key='more'>
+            <DropdownMenu.ItemTitle>More Options</DropdownMenu.ItemTitle>
+          </DropdownMenu.SubTrigger>
+
+          <DropdownMenu.SubContent>
+            <DropdownMenu.Item key='settings'>
+              <DropdownMenu.ItemTitle>Settings</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+
+            <DropdownMenu.Item key='help'>
+              <DropdownMenu.ItemTitle>Help</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+          </DropdownMenu.SubContent>
+        </DropdownMenu.Sub>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+Reference: [https://zeego.dev/components/dropdown-menu](https://zeego.dev/components/dropdown-menu)
+
+### 9.8 Use Native Modals Over JS-Based Bottom Sheets
+
+**Impact: HIGH (native performance, gestures, accessibility)**
+
+Use native `<Modal>` with `presentationStyle="formSheet"` or React Navigation
+
+v7's native form sheet instead of JS-based bottom sheet libraries. Native modals
+
+have built-in gestures, accessibility, and better performance. Rely on native UI
+
+for low-level primitives.
+
+**Incorrect: JS-based bottom sheet**
+
+```tsx
+import BottomSheet from 'custom-js-bottom-sheet'
+
+function MyScreen() {
+  const sheetRef = useRef<BottomSheet>(null)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => sheetRef.current?.expand()} title='Open' />
+      <BottomSheet ref={sheetRef} snapPoints={['50%', '90%']}>
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </BottomSheet>
+    </View>
+  )
+}
+```
+
+**Correct: native Modal with formSheet**
+
+```tsx
+import { Modal, View, Text, Button } from 'react-native'
+
+function MyScreen() {
+  const [visible, setVisible] = useState(false)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => setVisible(true)} title='Open' />
+      <Modal
+        visible={visible}
+        presentationStyle='formSheet'
+        animationType='slide'
+        onRequestClose={() => setVisible(false)}
+      >
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </Modal>
+    </View>
+  )
+}
+```
+
+**Correct: React Navigation v7 native form sheet**
+
+```tsx
+// In your navigator
+<Stack.Screen
+  name='Details'
+  component={DetailsScreen}
+  options={{
+    presentation: 'formSheet',
+    sheetAllowedDetents: 'fitToContents',
+  }}
+/>
+```
+
+Native modals provide swipe-to-dismiss, proper keyboard avoidance, and
+
+accessibility out of the box.
+
+### 9.9 Use Pressable Instead of Touchable Components
+
+**Impact: LOW (modern API, more flexible)**
+
+Never use `TouchableOpacity` or `TouchableHighlight`. Use `Pressable` from
+
+`react-native` or `react-native-gesture-handler` instead.
+
+**Incorrect: legacy Touchable components**
+
+```tsx
+import { TouchableOpacity } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <TouchableOpacity onPress={onPress} activeOpacity={0.7}>
+      <Text>Press me</Text>
+    </TouchableOpacity>
+  )
+}
+```
+
+**Correct: Pressable**
+
+```tsx
+import { Pressable } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Press me</Text>
+    </Pressable>
+  )
+}
+```
+
+**Correct: Pressable from gesture handler for lists**
+
+```tsx
+import { Pressable } from 'react-native-gesture-handler'
+
+function ListItem({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Item</Text>
+    </Pressable>
+  )
+}
+```
+
+Use `react-native-gesture-handler` Pressable inside scrollable lists for better
+
+gesture coordination, as long as you are using the ScrollView from
+
+`react-native-gesture-handler` as well.
+
+**For animated press states (scale, opacity changes):** Use `GestureDetector`
+
+with Reanimated shared values instead of Pressable's style callback. See the
+
+`animation-gesture-detector-press` rule.
+
+---
+
+## 10. Design System
+
+**Impact: MEDIUM**
+
+Architecture patterns for building maintainable component
+libraries.
+
+### 10.1 Use Compound Components Over Polymorphic Children
+
+**Impact: MEDIUM (flexible composition, clearer API)**
+
+Don't create components that can accept a string if they aren't a text node. If
+
+a component can receive a string child, it must be a dedicated `*Text`
+
+component. For components like buttons, which can have both a View (or
+
+Pressable) together with text, use compound components, such a `Button`,
+
+`ButtonText`, and `ButtonIcon`.
+
+**Incorrect: polymorphic children**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+type ButtonProps = {
+  children: string | React.ReactNode
+  icon?: React.ReactNode
+}
+
+function Button({ children, icon }: ButtonProps) {
+  return (
+    <Pressable>
+      {icon}
+      {typeof children === 'string' ? <Text>{children}</Text> : children}
+    </Pressable>
+  )
+}
+
+// Usage is ambiguous
+<Button icon={<Icon />}>Save</Button>
+<Button><CustomText>Save</CustomText></Button>
+```
+
+**Correct: compound components**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+function Button({ children }: { children: React.ReactNode }) {
+  return <Pressable>{children}</Pressable>
+}
+
+function ButtonText({ children }: { children: React.ReactNode }) {
+  return <Text>{children}</Text>
+}
+
+function ButtonIcon({ children }: { children: React.ReactNode }) {
+  return <>{children}</>
+}
+
+// Usage is explicit and composable
+<Button>
+  <ButtonIcon><SaveIcon /></ButtonIcon>
+  <ButtonText>Save</ButtonText>
+</Button>
+
+<Button>
+  <ButtonText>Cancel</ButtonText>
+</Button>
+```
+
+---
+
+## 11. Monorepo
+
+**Impact: LOW**
+
+Dependency management and native module configuration in
+monorepos.
+
+### 11.1 Install Native Dependencies in App Directory
+
+**Impact: CRITICAL (required for autolinking to work)**
+
+In a monorepo, packages with native code must be installed in the native app's
+
+directory directly. Autolinking only scans the app's `node_modules`—it won't
+
+find native dependencies installed in other packages.
+
+**Incorrect: native dep in shared package only**
+
+```typescript
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # missing react-native-reanimated
+```
+
+Autolinking fails—native code not linked.
+
+**Correct: native dep in app directory**
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Even if the shared package uses the native dependency, the app must also list it
+
+for autolinking to detect and link the native code.
+
+### 11.2 Use Single Dependency Versions Across Monorepo
+
+**Impact: MEDIUM (avoids duplicate bundles, version conflicts)**
+
+Use a single version of each dependency across all packages in your monorepo.
+
+Prefer exact versions over ranges. Multiple versions cause duplicate code in
+
+bundles, runtime conflicts, and inconsistent behavior across packages.
+
+Use a tool like syncpack to enforce this. As a last resort, use yarn resolutions
+
+or npm overrides.
+
+**Incorrect: version ranges, multiple versions**
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.0.0"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.5.0"
+  }
+}
+```
+
+**Correct: exact versions, single source of truth**
+
+```json
+// package.json (root)
+{
+  "pnpm": {
+    "overrides": {
+      "react-native-reanimated": "3.16.1"
+    }
+  }
+}
+
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Use your package manager's override/resolution feature to enforce versions at
+
+the root. When adding dependencies, specify exact versions without `^` or `~`.
+
+---
+
+## 12. Third-Party Dependencies
+
+**Impact: LOW**
+
+Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+### 12.1 Import from Design System Folder
+
+**Impact: LOW (enables global changes and easy refactoring)**
+
+Re-export dependencies from a design system folder. App code imports from there,
+
+not directly from packages. This enables global changes and easy refactoring.
+
+**Incorrect: imports directly from package**
+
+```tsx
+import { View, Text } from 'react-native'
+import { Button } from '@ui/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+**Correct: imports from design system**
+
+```tsx
+import { View } from '@/components/view'
+import { Text } from '@/components/text'
+import { Button } from '@/components/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+Start by simply re-exporting. Customize later without changing app code.
+
+---
+
+## 13. JavaScript
+
+**Impact: LOW**
+
+Micro-optimizations like hoisting expensive object creation.
+
+### 13.1 Hoist Intl Formatter Creation
+
+**Impact: LOW-MEDIUM (avoids expensive object recreation)**
+
+Don't create `Intl.DateTimeFormat`, `Intl.NumberFormat`, or
+
+`Intl.RelativeTimeFormat` inside render or loops. These are expensive to
+
+instantiate. Hoist to module scope when the locale/options are static.
+
+**Incorrect: new formatter every render**
+
+```tsx
+function Price({ amount }: { amount: number }) {
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  })
+  return <Text>{formatter.format(amount)}</Text>
+}
+```
+
+**Correct: hoisted to module scope**
+
+```tsx
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+})
+
+function Price({ amount }: { amount: number }) {
+  return <Text>{currencyFormatter.format(amount)}</Text>
+}
+```
+
+**For dynamic locales, memoize:**
+
+```tsx
+const dateFormatter = useMemo(
+  () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),
+  [locale]
+)
+```
+
+**Common formatters to hoist:**
+
+```tsx
+// Module-level formatters
+const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })
+const timeFormatter = new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })
+const percentFormatter = new Intl.NumberFormat('en-US', { style: 'percent' })
+const relativeFormatter = new Intl.RelativeTimeFormat('en-US', {
+  numeric: 'auto',
+})
+```
+
+Creating `Intl` objects is significantly more expensive than `RegExp` or plain
+
+objects—each instantiation parses locale data and builds internal lookup tables.
+
+---
+
+## 14. Fonts
+
+**Impact: LOW**
+
+Native font loading for improved performance.
+
+### 14.1 Load fonts natively at build time
+
+**Impact: LOW (fonts available at launch, no async loading)**
+
+Use the `expo-font` config plugin to embed fonts at build time instead of
+
+`useFonts` or `Font.loadAsync`. Embedded fonts are more efficient.
+
+[Expo Font Documentation](https://docs.expo.dev/versions/latest/sdk/font/)
+
+**Incorrect: async font loading**
+
+```tsx
+import { useFonts } from 'expo-font'
+import { Text, View } from 'react-native'
+
+function App() {
+  const [fontsLoaded] = useFonts({
+    'Geist-Bold': require('./assets/fonts/Geist-Bold.otf'),
+  })
+
+  if (!fontsLoaded) {
+    return null
+  }
+
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+**Correct: config plugin, fonts embedded at build**
+
+```tsx
+import { Text, View } from 'react-native'
+
+function App() {
+  // No loading state needed—font is already available
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+After adding fonts to the config plugin, run `npx expo prebuild` and rebuild the
+
+native app.
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://reactnative.dev](https://reactnative.dev)
+3. [https://docs.swmansion.com/react-native-reanimated](https://docs.swmansion.com/react-native-reanimated)
+4. [https://docs.swmansion.com/react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler)
+5. [https://docs.expo.dev](https://docs.expo.dev)
+6. [https://legendapp.com/open-source/legend-list](https://legendapp.com/open-source/legend-list)
+7. [https://github.com/nandorojo/galeria](https://github.com/nandorojo/galeria)
+8. [https://zeego.dev](https://zeego.dev)
diff --git a/skills/vercel/react-native-skills/README.md b/skills/vercel/react-native-skills/README.md
new file mode 100644
index 0000000..854db9f
--- /dev/null
+++ b/skills/vercel/react-native-skills/README.md
@@ -0,0 +1,165 @@
+# React Native Guidelines
+
+A structured repository for creating and maintaining React Native Best Practices
+optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `metadata.json` - Document metadata (version, organization, abstract)
+- **`AGENTS.md`** - Compiled output (generated)
+
+## Rules
+
+### Core Rendering (CRITICAL)
+
+- `rendering-text-in-text-component.md` - Wrap strings in Text components
+- `rendering-no-falsy-and.md` - Avoid falsy && operator in JSX
+
+### List Performance (HIGH)
+
+- `list-performance-virtualize.md` - Use virtualized lists (LegendList,
+  FlashList)
+- `list-performance-function-references.md` - Keep stable object references
+- `list-performance-callbacks.md` - Hoist callbacks to list root
+- `list-performance-inline-objects.md` - Avoid inline objects in renderItem
+- `list-performance-item-memo.md` - Pass primitives for memoization
+- `list-performance-item-expensive.md` - Keep list items lightweight
+- `list-performance-images.md` - Use compressed images in lists
+- `list-performance-item-types.md` - Use item types for heterogeneous lists
+
+### Animation (HIGH)
+
+- `animation-gpu-properties.md` - Animate transform/opacity instead of layout
+- `animation-gesture-detector-press.md` - Use GestureDetector for press
+  animations
+- `animation-derived-value.md` - Prefer useDerivedValue over useAnimatedReaction
+
+### Scroll Performance (HIGH)
+
+- `scroll-position-no-state.md` - Never track scroll in useState
+
+### Navigation (HIGH)
+
+- `navigation-native-navigators.md` - Use native stack and native tabs
+
+### React State (MEDIUM)
+
+- `react-state-dispatcher.md` - Use functional setState updates
+- `react-state-fallback.md` - State should represent user intent only
+- `react-state-minimize.md` - Minimize state variables, derive values
+
+### State Architecture (MEDIUM)
+
+- `state-ground-truth.md` - State must represent ground truth
+
+### React Compiler (MEDIUM)
+
+- `react-compiler-destructure-functions.md` - Destructure functions early
+- `react-compiler-reanimated-shared-values.md` - Use .get()/.set() for shared
+  values
+
+### User Interface (MEDIUM)
+
+- `ui-expo-image.md` - Use expo-image for optimized images
+- `ui-image-gallery.md` - Use Galeria for lightbox/galleries
+- `ui-menus.md` - Native dropdown and context menus with Zeego
+- `ui-native-modals.md` - Use native Modal with formSheet
+- `ui-pressable.md` - Use Pressable instead of TouchableOpacity
+- `ui-measure-views.md` - Measuring view dimensions
+- `ui-safe-area-scroll.md` - Use contentInsetAdjustmentBehavior
+- `ui-scrollview-content-inset.md` - Use contentInset for dynamic spacing
+- `ui-styling.md` - Modern styling patterns (gap, boxShadow, gradients)
+
+### Design System (MEDIUM)
+
+- `design-system-compound-components.md` - Use compound components
+
+### Monorepo (LOW)
+
+- `monorepo-native-deps-in-app.md` - Install native deps in app directory
+- `monorepo-single-dependency-versions.md` - Single dependency versions
+
+### Third-Party Dependencies (LOW)
+
+- `imports-design-system-folder.md` - Import from design system folder
+
+### JavaScript (LOW)
+
+- `js-hoist-intl.md` - Hoist Intl formatter creation
+
+### Fonts (LOW)
+
+- `fonts-config-plugin.md` - Load fonts natively at build time
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `rendering-` for Core Rendering
+   - `list-performance-` for List Performance
+   - `animation-` for Animation
+   - `scroll-` for Scroll Performance
+   - `navigation-` for Navigation
+   - `react-state-` for React State
+   - `state-` for State Architecture
+   - `react-compiler-` for React Compiler
+   - `ui-` for User Interface
+   - `design-system-` for Design System
+   - `monorepo-` for Monorepo
+   - `imports-` for Third-Party Dependencies
+   - `js-` for JavaScript
+   - `fonts-` for Fonts
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+````markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```tsx
+// Bad code example
+```
+````
+
+**Correct (description of what's right):**
+
+```tsx
+// Good code example
+```
+
+Reference: [Link](https://example.com)
+
+```
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `animation-gpu-properties.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, causes crashes or broken UI
+- `HIGH` - Significant performance improvements
+- `MEDIUM` - Moderate performance improvements
+- `LOW` - Incremental improvements
+```
diff --git a/skills/vercel/react-native-skills/SKILL.md b/skills/vercel/react-native-skills/SKILL.md
new file mode 100644
index 0000000..7340186
--- /dev/null
+++ b/skills/vercel/react-native-skills/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: vercel-react-native-skills
+description:
+  React Native and Expo best practices for building performant mobile apps. Use
+  when building React Native components, optimizing list performance,
+  implementing animations, or working with native modules. Triggers on tasks
+  involving React Native, Expo, mobile performance, or native platform APIs.
+license: MIT
+metadata:
+  author: vercel
+  version: '1.0.0'
+---
+
+# React Native Skills
+
+Comprehensive best practices for React Native and Expo applications. Contains
+rules across multiple categories covering performance, animations, UI patterns,
+and platform-specific optimizations.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Building React Native or Expo apps
+- Optimizing list and scroll performance
+- Implementing animations with Reanimated
+- Working with images and media
+- Configuring native modules or fonts
+- Structuring monorepo projects with native dependencies
+
+## Rule Categories by Priority
+
+| Priority | Category         | Impact   | Prefix               |
+| -------- | ---------------- | -------- | -------------------- |
+| 1        | List Performance | CRITICAL | `list-performance-`  |
+| 2        | Animation        | HIGH     | `animation-`         |
+| 3        | Navigation       | HIGH     | `navigation-`        |
+| 4        | UI Patterns      | HIGH     | `ui-`                |
+| 5        | State Management | MEDIUM   | `react-state-`       |
+| 6        | Rendering        | MEDIUM   | `rendering-`         |
+| 7        | Monorepo         | MEDIUM   | `monorepo-`          |
+| 8        | Configuration    | LOW      | `fonts-`, `imports-` |
+
+## Quick Reference
+
+### 1. List Performance (CRITICAL)
+
+- `list-performance-virtualize` - Use FlashList for large lists
+- `list-performance-item-memo` - Memoize list item components
+- `list-performance-callbacks` - Stabilize callback references
+- `list-performance-inline-objects` - Avoid inline style objects
+- `list-performance-function-references` - Extract functions outside render
+- `list-performance-images` - Optimize images in lists
+- `list-performance-item-expensive` - Move expensive work outside items
+- `list-performance-item-types` - Use item types for heterogeneous lists
+
+### 2. Animation (HIGH)
+
+- `animation-gpu-properties` - Animate only transform and opacity
+- `animation-derived-value` - Use useDerivedValue for computed animations
+- `animation-gesture-detector-press` - Use Gesture.Tap instead of Pressable
+
+### 3. Navigation (HIGH)
+
+- `navigation-native-navigators` - Use native stack and native tabs over JS navigators
+
+### 4. UI Patterns (HIGH)
+
+- `ui-expo-image` - Use expo-image for all images
+- `ui-image-gallery` - Use Galeria for image lightboxes
+- `ui-pressable` - Use Pressable over TouchableOpacity
+- `ui-safe-area-scroll` - Handle safe areas in ScrollViews
+- `ui-scrollview-content-inset` - Use contentInset for headers
+- `ui-menus` - Use native context menus
+- `ui-native-modals` - Use native modals when possible
+- `ui-measure-views` - Use onLayout, not measure()
+- `ui-styling` - Use StyleSheet.create or Nativewind
+
+### 5. State Management (MEDIUM)
+
+- `react-state-minimize` - Minimize state subscriptions
+- `react-state-dispatcher` - Use dispatcher pattern for callbacks
+- `react-state-fallback` - Show fallback on first render
+- `react-compiler-destructure-functions` - Destructure for React Compiler
+- `react-compiler-reanimated-shared-values` - Handle shared values with compiler
+
+### 6. Rendering (MEDIUM)
+
+- `rendering-text-in-text-component` - Wrap text in Text components
+- `rendering-no-falsy-and` - Avoid falsy && for conditional rendering
+
+### 7. Monorepo (MEDIUM)
+
+- `monorepo-native-deps-in-app` - Keep native dependencies in app package
+- `monorepo-single-dependency-versions` - Use single versions across packages
+
+### 8. Configuration (LOW)
+
+- `fonts-config-plugin` - Use config plugins for custom fonts
+- `imports-design-system-folder` - Organize design system imports
+- `js-hoist-intl` - Hoist Intl object creation
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/list-performance-virtualize.md
+rules/animation-gpu-properties.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel/react-native-skills/metadata.json b/skills/vercel/react-native-skills/metadata.json
new file mode 100644
index 0000000..600eb5b
--- /dev/null
+++ b/skills/vercel/react-native-skills/metadata.json
@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "organization": "Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React Native applications, designed for AI agents and LLMs. Contains 35+ rules across 13 categories, prioritized by impact from critical (core rendering, list performance) to incremental (fonts, imports). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://reactnative.dev",
+    "https://docs.swmansion.com/react-native-reanimated",
+    "https://docs.swmansion.com/react-native-gesture-handler",
+    "https://docs.expo.dev",
+    "https://legendapp.com/open-source/legend-list",
+    "https://github.com/nandorojo/galeria",
+    "https://zeego.dev"
+  ]
+}
diff --git a/skills/vercel/react-native-skills/rules/_sections.md b/skills/vercel/react-native-skills/rules/_sections.md
new file mode 100644
index 0000000..0519cf2
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/_sections.md
@@ -0,0 +1,86 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Core Rendering (rendering)
+
+**Impact:** CRITICAL  
+**Description:** Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+## 2. List Performance (list-performance)
+
+**Impact:** HIGH  
+**Description:** Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+## 3. Animation (animation)
+
+**Impact:** HIGH  
+**Description:** GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+## 4. Scroll Performance (scroll)
+
+**Impact:** HIGH  
+**Description:** Tracking scroll position without causing render thrashing.
+
+## 5. Navigation (navigation)
+
+**Impact:** HIGH  
+**Description:** Using native navigators for stack and tab navigation instead of
+JS-based alternatives.
+
+## 6. React State (react-state)
+
+**Impact:** MEDIUM  
+**Description:** Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+## 7. State Architecture (state)
+
+**Impact:** MEDIUM  
+**Description:** Ground truth principles for state variables and derived values.
+
+## 8. React Compiler (react-compiler)
+
+**Impact:** MEDIUM  
+**Description:** Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+## 9. User Interface (ui)
+
+**Impact:** MEDIUM  
+**Description:** Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+## 10. Design System (design-system)
+
+**Impact:** MEDIUM  
+**Description:** Architecture patterns for building maintainable component
+libraries.
+
+## 11. Monorepo (monorepo)
+
+**Impact:** LOW  
+**Description:** Dependency management and native module configuration in
+monorepos.
+
+## 12. Third-Party Dependencies (imports)
+
+**Impact:** LOW  
+**Description:** Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+## 13. JavaScript (js)
+
+**Impact:** LOW  
+**Description:** Micro-optimizations like hoisting expensive object creation.
+
+## 14. Fonts (fonts)
+
+**Impact:** LOW  
+**Description:** Native font loading for improved performance.
diff --git a/skills/vercel/react-native-skills/rules/_template.md b/skills/vercel/react-native-skills/rules/_template.md
new file mode 100644
index 0000000..1e9e707
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/_template.md
@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel/react-native-skills/rules/animation-derived-value.md b/skills/vercel/react-native-skills/rules/animation-derived-value.md
new file mode 100644
index 0000000..310928a
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/animation-derived-value.md
@@ -0,0 +1,53 @@
+---
+title: Prefer useDerivedValue Over useAnimatedReaction
+impact: MEDIUM
+impactDescription: cleaner code, automatic dependency tracking
+tags: animation, reanimated, derived-value
+---
+
+## Prefer useDerivedValue Over useAnimatedReaction
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+`useAnimatedReaction`. Derived values are declarative, automatically track
+dependencies, and return a value you can use directly. Animated reactions are
+for side effects, not derivations.
+
+**Incorrect (useAnimatedReaction for derivation):**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+  const opacity = useSharedValue(1)
+
+  useAnimatedReaction(
+    () => progress.value,
+    (current) => {
+      opacity.value = 1 - current
+    }
+  )
+
+  // ...
+}
+```
+
+**Correct (useDerivedValue):**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+
+  const opacity = useDerivedValue(() => 1 - progress.get())
+
+  // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+Reference:
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)
diff --git a/skills/vercel/react-native-skills/rules/animation-gesture-detector-press.md b/skills/vercel/react-native-skills/rules/animation-gesture-detector-press.md
new file mode 100644
index 0000000..87c6782
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/animation-gesture-detector-press.md
@@ -0,0 +1,95 @@
+---
+title: Use GestureDetector for Animated Press States
+impact: MEDIUM
+impactDescription: UI thread animations, smoother press feedback
+tags: animation, gestures, press, reanimated
+---
+
+## Use GestureDetector for Animated Press States
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+`Gesture.Tap()` and shared values instead of Pressable's
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+JS thread round-trip for press animations.
+
+**Incorrect (Pressable with JS thread callbacks):**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  const scale = useSharedValue(1)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }))
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onPressIn={() => (scale.value = withTiming(0.95))}
+      onPressOut={() => (scale.value = withTiming(1))}
+    >
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </Pressable>
+  )
+}
+```
+
+**Correct (GestureDetector with UI thread worklets):**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+  interpolate,
+  runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  // Store the press STATE (0 = not pressed, 1 = pressed)
+  const pressed = useSharedValue(0)
+
+  const tap = Gesture.Tap()
+    .onBegin(() => {
+      pressed.set(withTiming(1))
+    })
+    .onFinalize(() => {
+      pressed.set(withTiming(0))
+    })
+    .onEnd(() => {
+      runOnJS(onPress)()
+    })
+
+  // Derive visual values from the state
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+    ],
+  }))
+
+  return (
+    <GestureDetector gesture={tap}>
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </GestureDetector>
+  )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+Reference:
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)
diff --git a/skills/vercel/react-native-skills/rules/animation-gpu-properties.md b/skills/vercel/react-native-skills/rules/animation-gpu-properties.md
new file mode 100644
index 0000000..5fda095
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/animation-gpu-properties.md
@@ -0,0 +1,65 @@
+---
+title: Animate Transform and Opacity Instead of Layout Properties
+impact: HIGH
+impactDescription: GPU-accelerated animations, no layout recalculation
+tags: animation, performance, reanimated, transform, opacity
+---
+
+## Animate Transform and Opacity Instead of Layout Properties
+
+Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.
+
+**Incorrect (animates height, triggers layout every frame):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    height: withTiming(expanded ? 200 : 0), // triggers layout on every frame
+    overflow: 'hidden',
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+**Correct (animates scaleY, GPU-accelerated):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scaleY: withTiming(expanded ? 1 : 0) },
+    ],
+    opacity: withTiming(expanded ? 1 : 0),
+  }))
+
+  return (
+    <Animated.View style={[{ height: 200, transformOrigin: 'top' }, animatedStyle]}>
+      {children}
+    </Animated.View>
+  )
+}
+```
+
+**Correct (animates translateY for slide animations):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function SlideIn({ visible }: { visible: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateY: withTiming(visible ? 0 : 100) },
+    ],
+    opacity: withTiming(visible ? 1 : 0),
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.
diff --git a/skills/vercel/react-native-skills/rules/design-system-compound-components.md b/skills/vercel/react-native-skills/rules/design-system-compound-components.md
new file mode 100644
index 0000000..d8239ee
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/design-system-compound-components.md
@@ -0,0 +1,66 @@
+---
+title: Use Compound Components Over Polymorphic Children
+impact: MEDIUM
+impactDescription: flexible composition, clearer API
+tags: design-system, components, composition
+---
+
+## Use Compound Components Over Polymorphic Children
+
+Don't create components that can accept a string if they aren't a text node. If
+a component can receive a string child, it must be a dedicated `*Text`
+component. For components like buttons, which can have both a View (or
+Pressable) together with text, use compound components, such a `Button`,
+`ButtonText`, and `ButtonIcon`.
+
+**Incorrect (polymorphic children):**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+type ButtonProps = {
+  children: string | React.ReactNode
+  icon?: React.ReactNode
+}
+
+function Button({ children, icon }: ButtonProps) {
+  return (
+    <Pressable>
+      {icon}
+      {typeof children === 'string' ? <Text>{children}</Text> : children}
+    </Pressable>
+  )
+}
+
+// Usage is ambiguous
+<Button icon={<Icon />}>Save</Button>
+<Button><CustomText>Save</CustomText></Button>
+```
+
+**Correct (compound components):**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+function Button({ children }: { children: React.ReactNode }) {
+  return <Pressable>{children}</Pressable>
+}
+
+function ButtonText({ children }: { children: React.ReactNode }) {
+  return <Text>{children}</Text>
+}
+
+function ButtonIcon({ children }: { children: React.ReactNode }) {
+  return <>{children}</>
+}
+
+// Usage is explicit and composable
+<Button>
+  <ButtonIcon><SaveIcon /></ButtonIcon>
+  <ButtonText>Save</ButtonText>
+</Button>
+
+<Button>
+  <ButtonText>Cancel</ButtonText>
+</Button>
+```
diff --git a/skills/vercel/react-native-skills/rules/fonts-config-plugin.md b/skills/vercel/react-native-skills/rules/fonts-config-plugin.md
new file mode 100644
index 0000000..39aa014
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/fonts-config-plugin.md
@@ -0,0 +1,71 @@
+---
+title: Load fonts natively at build time
+impact: LOW
+impactDescription: fonts available at launch, no async loading
+tags: fonts, expo, performance, config-plugin
+---
+
+## Use Expo Config Plugin for Font Loading
+
+Use the `expo-font` config plugin to embed fonts at build time instead of
+`useFonts` or `Font.loadAsync`. Embedded fonts are more efficient.
+
+**Incorrect (async font loading):**
+
+```tsx
+import { useFonts } from 'expo-font'
+import { Text, View } from 'react-native'
+
+function App() {
+  const [fontsLoaded] = useFonts({
+    'Geist-Bold': require('./assets/fonts/Geist-Bold.otf'),
+  })
+
+  if (!fontsLoaded) {
+    return null
+  }
+
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+**Correct (config plugin, fonts embedded at build):**
+
+```json
+// app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-font",
+        {
+          "fonts": ["./assets/fonts/Geist-Bold.otf"]
+        }
+      ]
+    ]
+  }
+}
+```
+
+```tsx
+import { Text, View } from 'react-native'
+
+function App() {
+  // No loading state needed—font is already available
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+After adding fonts to the config plugin, run `npx expo prebuild` and rebuild the
+native app.
+
+Reference:
+[Expo Font Documentation](https://docs.expo.dev/versions/latest/sdk/font/)
diff --git a/skills/vercel/react-native-skills/rules/imports-design-system-folder.md b/skills/vercel/react-native-skills/rules/imports-design-system-folder.md
new file mode 100644
index 0000000..8466dcb
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/imports-design-system-folder.md
@@ -0,0 +1,68 @@
+---
+title: Import from Design System Folder
+impact: LOW
+impactDescription: enables global changes and easy refactoring
+tags: imports, architecture, design-system
+---
+
+## Import from Design System Folder
+
+Re-export dependencies from a design system folder. App code imports from there,
+not directly from packages. This enables global changes and easy refactoring.
+
+**Incorrect (imports directly from package):**
+
+```tsx
+import { View, Text } from 'react-native'
+import { Button } from '@ui/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+**Correct (imports from design system):**
+
+```tsx
+// components/view.tsx
+import { View as RNView } from 'react-native'
+
+// ideal: pick the props you will actually use to control implementation
+export function View(
+  props: Pick<React.ComponentProps<typeof RNView>, 'style' | 'children'>
+) {
+  return <RNView {...props} />
+}
+```
+
+```tsx
+// components/text.tsx
+export { Text } from 'react-native'
+```
+
+```tsx
+// components/button.tsx
+export { Button } from '@ui/button'
+```
+
+```tsx
+import { View } from '@/components/view'
+import { Text } from '@/components/text'
+import { Button } from '@/components/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+Start by simply re-exporting. Customize later without changing app code.
diff --git a/skills/vercel/react-native-skills/rules/js-hoist-intl.md b/skills/vercel/react-native-skills/rules/js-hoist-intl.md
new file mode 100644
index 0000000..9af1c35
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/js-hoist-intl.md
@@ -0,0 +1,61 @@
+---
+title: Hoist Intl Formatter Creation
+impact: LOW-MEDIUM
+impactDescription: avoids expensive object recreation
+tags: javascript, intl, optimization, memoization
+---
+
+## Hoist Intl Formatter Creation
+
+Don't create `Intl.DateTimeFormat`, `Intl.NumberFormat`, or
+`Intl.RelativeTimeFormat` inside render or loops. These are expensive to
+instantiate. Hoist to module scope when the locale/options are static.
+
+**Incorrect (new formatter every render):**
+
+```tsx
+function Price({ amount }: { amount: number }) {
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  })
+  return <Text>{formatter.format(amount)}</Text>
+}
+```
+
+**Correct (hoisted to module scope):**
+
+```tsx
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+})
+
+function Price({ amount }: { amount: number }) {
+  return <Text>{currencyFormatter.format(amount)}</Text>
+}
+```
+
+**For dynamic locales, memoize:**
+
+```tsx
+const dateFormatter = useMemo(
+  () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),
+  [locale]
+)
+```
+
+**Common formatters to hoist:**
+
+```tsx
+// Module-level formatters
+const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })
+const timeFormatter = new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })
+const percentFormatter = new Intl.NumberFormat('en-US', { style: 'percent' })
+const relativeFormatter = new Intl.RelativeTimeFormat('en-US', {
+  numeric: 'auto',
+})
+```
+
+Creating `Intl` objects is significantly more expensive than `RegExp` or plain
+objects—each instantiation parses locale data and builds internal lookup tables.
diff --git a/skills/vercel/react-native-skills/rules/list-performance-callbacks.md b/skills/vercel/react-native-skills/rules/list-performance-callbacks.md
new file mode 100644
index 0000000..a0b3913
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-callbacks.md
@@ -0,0 +1,44 @@
+---
+title: Hoist callbacks to the root of lists
+impact: MEDIUM
+impactDescription: Fewer re-renders and faster lists
+tags: tag1, tag2
+---
+
+## List performance callbacks
+
+**Impact: HIGH (Fewer re-renders and faster lists)**
+
+When passing callback functions to list items, create a single instance of the
+callback at the root of the list. Items should then call it with a unique
+identifier.
+
+**Incorrect (creates a new callback on each render):**
+
+```typescript
+return (
+  <LegendList
+    renderItem={({ item }) => {
+      // bad: creates a new callback on each render
+      const onPress = () => handlePress(item.id)
+      return <Item key={item.id} item={item} onPress={onPress} />
+    }}
+  />
+)
+```
+
+**Correct (a single function instance passed to each item):**
+
+```typescript
+const onPress = useCallback(() => handlePress(item.id), [handlePress, item.id])
+
+return (
+  <LegendList
+    renderItem={({ item }) => (
+      <Item key={item.id} item={item} onPress={onPress} />
+    )}
+  />
+)
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel/react-native-skills/rules/list-performance-function-references.md b/skills/vercel/react-native-skills/rules/list-performance-function-references.md
new file mode 100644
index 0000000..9721929
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-function-references.md
@@ -0,0 +1,132 @@
+---
+title: Optimize List Performance with Stable Object References
+impact: CRITICAL
+impactDescription: virtualization relies on reference stability
+tags: lists, performance, flatlist, virtualization
+---
+
+## Optimize List Performance with Stable Object References
+
+Don't map or filter data before passing to virtualized lists. Virtualization
+relies on object reference stability to know what changed—new references cause
+full re-renders of all visible items. Attempt to prevent frequent renders at the
+list-parent level.
+
+Where needed, use context selectors within list items.
+
+**Incorrect (creates new object references on every keystroke):**
+
+```tsx
+function DomainSearch() {
+  const { keyword, setKeyword } = useKeywordZustandState()
+  const { data: tlds } = useTlds()
+
+  // Bad: creates new objects on every render, reparenting the entire list on every keystroke
+  const domains = tlds.map((tld) => ({
+    domain: `${keyword}.${tld.name}`,
+    tld: tld.name,
+    price: tld.price,
+  }))
+
+  return (
+    <>
+      <TextInput value={keyword} onChangeText={setKeyword} />
+      <LegendList
+        data={domains}
+        renderItem={({ item }) => <DomainItem item={item} keyword={keyword} />}
+      />
+    </>
+  )
+}
+```
+
+**Correct (stable references, transform inside items):**
+
+```tsx
+const renderItem = ({ item }) => <DomainItem tld={item} />
+
+function DomainSearch() {
+  const { data: tlds } = useTlds()
+
+  return (
+    <LegendList
+      // good: as long as the data is stable, LegendList will not re-render the entire list
+      data={tlds}
+      renderItem={renderItem}
+    />
+  )
+}
+
+function DomainItem({ tld }: { tld: Tld }) {
+  // good: transform within items, and don't pass the dynamic data as a prop
+  // good: use a selector function from zustand to receive a stable string back
+  const domain = useKeywordZustandState((s) => s.keyword + '.' + tld.name)
+  return <Text>{domain}</Text>
+}
+```
+
+**Updating parent array reference:**
+
+Creating a new array instance can be okay, as long as its inner object
+references are stable. For instance, if you sort a list of objects:
+
+```tsx
+// good: creates a new array instance without mutating the inner objects
+// good: parent array reference is unaffected by typing and updating "keyword"
+const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
+
+return <LegendList data={sortedTlds} renderItem={renderItem} />
+```
+
+Even though this creates a new array instance `sortedTlds`, the inner object
+references are stable.
+
+**With zustand for dynamic data (avoids parent re-renders):**
+
+```tsx
+const useSearchStore = create<{ keyword: string }>(() => ({ keyword: '' }))
+
+function DomainSearch() {
+  const { data: tlds } = useTlds()
+
+  return (
+    <>
+      <SearchInput />
+      <LegendList
+        data={tlds}
+        // if you aren't using React Compiler, wrap renderItem with useCallback
+        renderItem={({ item }) => <DomainItem tld={item} />}
+      />
+    </>
+  )
+}
+
+function DomainItem({ tld }: { tld: Tld }) {
+  // Select only what you need—component only re-renders when keyword changes
+  const keyword = useSearchStore((s) => s.keyword)
+  const domain = `${keyword}.${tld.name}`
+  return <Text>{domain}</Text>
+}
+```
+
+Virtualization can now skip items that haven't changed when typing. Only visible
+items (~20) re-render on keystroke, rather than the parent.
+
+**Deriving state within list items based on parent data (avoids parent
+re-renders):**
+
+For components where the data is conditional based on the parent state, this
+pattern is even more important. For example, if you are checking if an item is
+favorited, toggling favorites only re-renders one component if the item itself
+is in charge of accessing the state rather than the parent:
+
+```tsx
+function DomainItemFavoriteButton({ tld }: { tld: Tld }) {
+  const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))
+  return <TldFavoriteButton isFavorited={isFavorited} />
+}
+```
+
+Note: if you're using the React Compiler, you can read React Context values
+directly within list items. Although this is slightly slower than using a
+Zustand selector in most cases, the effect may be negligible.
diff --git a/skills/vercel/react-native-skills/rules/list-performance-images.md b/skills/vercel/react-native-skills/rules/list-performance-images.md
new file mode 100644
index 0000000..75a3baf
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-images.md
@@ -0,0 +1,53 @@
+---
+title: Use Compressed Images in Lists
+impact: HIGH
+impactDescription: faster load times, less memory
+tags: lists, images, performance, optimization
+---
+
+## Use Compressed Images in Lists
+
+Always load compressed, appropriately-sized images in lists. Full-resolution
+images consume excessive memory and cause scroll jank. Request thumbnails from
+your server or use an image CDN with resize parameters.
+
+**Incorrect (full-resolution images):**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  return (
+    <View>
+      {/* 4000x3000 image loaded for a 100x100 thumbnail */}
+      <Image
+        source={{ uri: product.imageUrl }}
+        style={{ width: 100, height: 100 }}
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+**Correct (request appropriately-sized image):**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  // Request a 200x200 image (2x for retina)
+  const thumbnailUrl = `${product.imageUrl}?w=200&h=200&fit=cover`
+
+  return (
+    <View>
+      <Image
+        source={{ uri: thumbnailUrl }}
+        style={{ width: 100, height: 100 }}
+        contentFit='cover'
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+Use an optimized image component with built-in caching and placeholder support,
+such as `expo-image` or `SolitoImage` (which uses `expo-image` under the hood).
+Request images at 2x the display size for retina screens.
diff --git a/skills/vercel/react-native-skills/rules/list-performance-inline-objects.md b/skills/vercel/react-native-skills/rules/list-performance-inline-objects.md
new file mode 100644
index 0000000..d5b6514
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-inline-objects.md
@@ -0,0 +1,97 @@
+---
+title: Avoid Inline Objects in renderItem
+impact: HIGH
+impactDescription: prevents unnecessary re-renders of memoized list items
+tags: lists, performance, flatlist, virtualization, memo
+---
+
+## Avoid Inline Objects in renderItem
+
+Don't create new objects inside `renderItem` to pass as props. Inline objects
+create new references on every render, breaking memoization. Pass primitive
+values directly from `item` instead.
+
+**Incorrect (inline object breaks memoization):**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        <UserRow
+          // Bad: new object on every render
+          user={{ id: item.id, name: item.name, avatar: item.avatar }}
+        />
+      )}
+    />
+  )
+}
+```
+
+**Incorrect (inline style object):**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Bad: new style object on every render
+    style={{ backgroundColor: item.isActive ? 'green' : 'gray' }}
+  />
+)}
+```
+
+**Correct (pass item directly or primitives):**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        // Good: pass the item directly
+        <UserRow user={item} />
+      )}
+    />
+  )
+}
+```
+
+**Correct (pass primitives, derive inside child):**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    id={item.id}
+    name={item.name}
+    isActive={item.isActive}
+  />
+)}
+
+const UserRow = memo(function UserRow({ id, name, isActive }: Props) {
+  // Good: derive style inside memoized component
+  const backgroundColor = isActive ? 'green' : 'gray'
+  return <View style={[styles.row, { backgroundColor }]}>{/* ... */}</View>
+})
+```
+
+**Correct (hoist static styles in module scope):**
+
+```tsx
+const activeStyle = { backgroundColor: 'green' }
+const inactiveStyle = { backgroundColor: 'gray' }
+
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Good: stable references
+    style={item.isActive ? activeStyle : inactiveStyle}
+  />
+)}
+```
+
+Passing primitives or stable references allows `memo()` to skip re-renders when
+the actual values haven't changed.
+
+**Note:** If you have the React Compiler enabled, it handles memoization
+automatically and these manual optimizations become less critical.
diff --git a/skills/vercel/react-native-skills/rules/list-performance-item-expensive.md b/skills/vercel/react-native-skills/rules/list-performance-item-expensive.md
new file mode 100644
index 0000000..f617a76
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-item-expensive.md
@@ -0,0 +1,94 @@
+---
+title: Keep List Items Lightweight
+impact: HIGH
+impactDescription: reduces render time for visible items during scroll
+tags: lists, performance, virtualization, hooks
+---
+
+## Keep List Items Lightweight
+
+List items should be as inexpensive as possible to render. Minimize hooks, avoid
+queries, and limit React Context access. Virtualized lists render many items
+during scroll—expensive items cause jank.
+
+**Incorrect (heavy list item):**
+
+```tsx
+function ProductRow({ id }: { id: string }) {
+  // Bad: query inside list item
+  const { data: product } = useQuery(['product', id], () => fetchProduct(id))
+  // Bad: multiple context accesses
+  const theme = useContext(ThemeContext)
+  const user = useContext(UserContext)
+  const cart = useContext(CartContext)
+  // Bad: expensive computation
+  const recommendations = useMemo(
+    () => computeRecommendations(product),
+    [product]
+  )
+
+  return <View>{/* ... */}</View>
+}
+```
+
+**Correct (lightweight list item):**
+
+```tsx
+function ProductRow({ name, price, imageUrl }: Props) {
+  // Good: receives only primitives, minimal hooks
+  return (
+    <View>
+      <Image source={{ uri: imageUrl }} />
+      <Text>{name}</Text>
+      <Text>{price}</Text>
+    </View>
+  )
+}
+```
+
+**Move data fetching to parent:**
+
+```tsx
+// Parent fetches all data once
+function ProductList() {
+  const { data: products } = useQuery(['products'], fetchProducts)
+
+  return (
+    <LegendList
+      data={products}
+      renderItem={({ item }) => (
+        <ProductRow name={item.name} price={item.price} imageUrl={item.image} />
+      )}
+    />
+  )
+}
+```
+
+**For shared values, use Zustand selectors instead of Context:**
+
+```tsx
+// Incorrect: Context causes re-render when any cart value changes
+function ProductRow({ id, name }: Props) {
+  const { items } = useContext(CartContext)
+  const inCart = items.includes(id)
+  // ...
+}
+
+// Correct: Zustand selector only re-renders when this specific value changes
+function ProductRow({ id, name }: Props) {
+  // use Set.has (created once at the root) instead of Array.includes()
+  const inCart = useCartStore((s) => s.items.has(id))
+  // ...
+}
+```
+
+**Guidelines for list items:**
+
+- No queries or data fetching
+- No expensive computations (move to parent or memoize at parent level)
+- Prefer Zustand selectors over React Context
+- Minimize useState/useEffect hooks
+- Pass pre-computed values as props
+
+The goal: list items should be simple rendering functions that take props and
+return JSX.
diff --git a/skills/vercel/react-native-skills/rules/list-performance-item-memo.md b/skills/vercel/react-native-skills/rules/list-performance-item-memo.md
new file mode 100644
index 0000000..634935e
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-item-memo.md
@@ -0,0 +1,82 @@
+---
+title: Pass Primitives to List Items for Memoization
+impact: HIGH
+impactDescription: enables effective memo() comparison
+tags: lists, performance, memo, primitives
+---
+
+## Pass Primitives to List Items for Memoization
+
+When possible, pass only primitive values (strings, numbers, booleans) as props
+to list item components. Primitives enable shallow comparison in `memo()` to
+work correctly, skipping re-renders when values haven't changed.
+
+**Incorrect (object prop requires deep comparison):**
+
+```tsx
+type User = { id: string; name: string; email: string; avatar: string }
+
+const UserRow = memo(function UserRow({ user }: { user: User }) {
+  // memo() compares user by reference, not value
+  // If parent creates new user object, this re-renders even if data is same
+  return <Text>{user.name}</Text>
+})
+
+renderItem={({ item }) => <UserRow user={item} />}
+```
+
+This can still be optimized, but it is harder to memoize properly.
+
+**Correct (primitive props enable shallow comparison):**
+
+```tsx
+const UserRow = memo(function UserRow({
+  id,
+  name,
+  email,
+}: {
+  id: string
+  name: string
+  email: string
+}) {
+  // memo() compares each primitive directly
+  // Re-renders only if id, name, or email actually changed
+  return <Text>{name}</Text>
+})
+
+renderItem={({ item }) => (
+  <UserRow id={item.id} name={item.name} email={item.email} />
+)}
+```
+
+**Pass only what you need:**
+
+```tsx
+// Incorrect: passing entire item when you only need name
+<UserRow user={item} />
+
+// Correct: pass only the fields the component uses
+<UserRow name={item.name} avatarUrl={item.avatar} />
+```
+
+**For callbacks, hoist or use item ID:**
+
+```tsx
+// Incorrect: inline function creates new reference
+<UserRow name={item.name} onPress={() => handlePress(item.id)} />
+
+// Correct: pass ID, handle in child
+<UserRow id={item.id} name={item.name} />
+
+const UserRow = memo(function UserRow({ id, name }: Props) {
+  const handlePress = useCallback(() => {
+    // use id here
+  }, [id])
+  return <Pressable onPress={handlePress}><Text>{name}</Text></Pressable>
+})
+```
+
+Primitive props make memoization predictable and effective.
+
+**Note:** If you have the React Compiler enabled, you do not need to use
+`memo()` or `useCallback()`, but the object references still apply.
diff --git a/skills/vercel/react-native-skills/rules/list-performance-item-types.md b/skills/vercel/react-native-skills/rules/list-performance-item-types.md
new file mode 100644
index 0000000..1027e4e
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-item-types.md
@@ -0,0 +1,104 @@
+---
+title: Use Item Types for Heterogeneous Lists
+impact: HIGH
+impactDescription: efficient recycling, less layout thrashing
+tags: list, performance, recycling, heterogeneous, LegendList
+---
+
+## Use Item Types for Heterogeneous Lists
+
+When a list has different item layouts (messages, images, headers, etc.), use a
+`type` field on each item and provide `getItemType` to the list. This puts items
+into separate recycling pools so a message component never gets recycled into an
+image component.
+
+**Incorrect (single component with conditionals):**
+
+```tsx
+type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }
+
+function ListItem({ item }: { item: Item }) {
+  if (item.isHeader) {
+    return <HeaderItem title={item.text} />
+  }
+  if (item.imageUrl) {
+    return <ImageItem url={item.imageUrl} />
+  }
+  return <MessageItem text={item.text} />
+}
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      renderItem={({ item }) => <ListItem item={item} />}
+      recycleItems
+    />
+  )
+}
+```
+
+**Correct (typed items with separate components):**
+
+```tsx
+type HeaderItem = { id: string; type: 'header'; title: string }
+type MessageItem = { id: string; type: 'message'; text: string }
+type ImageItem = { id: string; type: 'image'; url: string }
+type FeedItem = HeaderItem | MessageItem | ImageItem
+
+function Feed({ items }: { items: FeedItem[] }) {
+  return (
+    <LegendList
+      data={items}
+      keyExtractor={(item) => item.id}
+      getItemType={(item) => item.type}
+      renderItem={({ item }) => {
+        switch (item.type) {
+          case 'header':
+            return <SectionHeader title={item.title} />
+          case 'message':
+            return <MessageRow text={item.text} />
+          case 'image':
+            return <ImageRow url={item.url} />
+        }
+      }}
+      recycleItems
+    />
+  )
+}
+```
+
+**Why this matters:**
+
+- **Recycling efficiency**: Items with the same type share a recycling pool
+- **No layout thrashing**: A header never recycles into an image cell
+- **Type safety**: TypeScript can narrow the item type in each branch
+- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for
+  accurate estimates per type
+
+```tsx
+<LegendList
+  data={items}
+  keyExtractor={(item) => item.id}
+  getItemType={(item) => item.type}
+  getEstimatedItemSize={(index, item, itemType) => {
+    switch (itemType) {
+      case 'header':
+        return 48
+      case 'message':
+        return 72
+      case 'image':
+        return 300
+      default:
+        return 72
+    }
+  }}
+  renderItem={({ item }) => {
+    /* ... */
+  }}
+  recycleItems
+/>
+```
+
+Reference:
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
diff --git a/skills/vercel/react-native-skills/rules/list-performance-virtualize.md b/skills/vercel/react-native-skills/rules/list-performance-virtualize.md
new file mode 100644
index 0000000..8a393ba
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/list-performance-virtualize.md
@@ -0,0 +1,67 @@
+---
+title: Use a List Virtualizer for Any List
+impact: HIGH
+impactDescription: reduced memory, faster mounts
+tags: lists, performance, virtualization, scrollview
+---
+
+## Use a List Virtualizer for Any List
+
+Use a list virtualizer like LegendList or FlashList instead of ScrollView with
+mapped children—even for short lists. Virtualizers only render visible items,
+reducing memory usage and mount time. ScrollView renders all children upfront,
+which gets expensive quickly.
+
+**Incorrect (ScrollView renders all items at once):**
+
+```tsx
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <ScrollView>
+      {items.map((item) => (
+        <ItemCard key={item.id} item={item} />
+      ))}
+    </ScrollView>
+  )
+}
+// 50 items = 50 components mounted, even if only 10 visible
+```
+
+**Correct (virtualizer renders only visible items):**
+
+```tsx
+import { LegendList } from '@legendapp/list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+      estimatedItemSize={80}
+    />
+  )
+}
+// Only ~10-15 visible items mounted at a time
+```
+
+**Alternative (FlashList):**
+
+```tsx
+import { FlashList } from '@shopify/flash-list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <FlashList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+    />
+  )
+}
+```
+
+Benefits apply to any screen with scrollable content—profiles, settings, feeds,
+search results. Default to virtualization.
diff --git a/skills/vercel/react-native-skills/rules/monorepo-native-deps-in-app.md b/skills/vercel/react-native-skills/rules/monorepo-native-deps-in-app.md
new file mode 100644
index 0000000..ff85d76
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/monorepo-native-deps-in-app.md
@@ -0,0 +1,46 @@
+---
+title: Install Native Dependencies in App Directory
+impact: CRITICAL
+impactDescription: required for autolinking to work
+tags: monorepo, native, autolinking, installation
+---
+
+## Install Native Dependencies in App Directory
+
+In a monorepo, packages with native code must be installed in the native app's
+directory directly. Autolinking only scans the app's `node_modules`—it won't
+find native dependencies installed in other packages.
+
+**Incorrect (native dep in shared package only):**
+
+```
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # missing react-native-reanimated
+```
+
+Autolinking fails—native code not linked.
+
+**Correct (native dep in app directory):**
+
+```
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # also has react-native-reanimated
+```
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Even if the shared package uses the native dependency, the app must also list it
+for autolinking to detect and link the native code.
diff --git a/skills/vercel/react-native-skills/rules/monorepo-single-dependency-versions.md b/skills/vercel/react-native-skills/rules/monorepo-single-dependency-versions.md
new file mode 100644
index 0000000..1087dfa
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/monorepo-single-dependency-versions.md
@@ -0,0 +1,63 @@
+---
+title: Use Single Dependency Versions Across Monorepo
+impact: MEDIUM
+impactDescription: avoids duplicate bundles, version conflicts
+tags: monorepo, dependencies, installation
+---
+
+## Use Single Dependency Versions Across Monorepo
+
+Use a single version of each dependency across all packages in your monorepo.
+Prefer exact versions over ranges. Multiple versions cause duplicate code in
+bundles, runtime conflicts, and inconsistent behavior across packages.
+
+Use a tool like syncpack to enforce this. As a last resort, use yarn resolutions
+or npm overrides.
+
+**Incorrect (version ranges, multiple versions):**
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.0.0"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.5.0"
+  }
+}
+```
+
+**Correct (exact versions, single source of truth):**
+
+```json
+// package.json (root)
+{
+  "pnpm": {
+    "overrides": {
+      "react-native-reanimated": "3.16.1"
+    }
+  }
+}
+
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Use your package manager's override/resolution feature to enforce versions at
+the root. When adding dependencies, specify exact versions without `^` or `~`.
diff --git a/skills/vercel/react-native-skills/rules/navigation-native-navigators.md b/skills/vercel/react-native-skills/rules/navigation-native-navigators.md
new file mode 100644
index 0000000..035c5fd
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/navigation-native-navigators.md
@@ -0,0 +1,188 @@
+---
+title: Use Native Navigators for Navigation
+impact: HIGH
+impactDescription: native performance, platform-appropriate UI
+tags: navigation, react-navigation, expo-router, native-stack, tabs
+---
+
+## Use Native Navigators for Navigation
+
+Always use native navigators instead of JS-based ones. Native navigators use
+platform APIs (UINavigationController on iOS, Fragment on Android) for better
+performance and native behavior.
+
+**For stacks:** Use `@react-navigation/native-stack` or expo-router's default
+stack (which uses native-stack). Avoid `@react-navigation/stack`.
+
+**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native
+tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.
+
+### Stack Navigation
+
+**Incorrect (JS stack navigator):**
+
+```tsx
+import { createStackNavigator } from '@react-navigation/stack'
+
+const Stack = createStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct (native stack with react-navigation):**
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct (expo-router uses native stack by default):**
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function Layout() {
+  return <Stack />
+}
+```
+
+### Tab Navigation
+
+**Incorrect (JS bottom tabs):**
+
+```tsx
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'
+
+const Tab = createBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen name='Home' component={HomeScreen} />
+      <Tab.Screen name='Settings' component={SettingsScreen} />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct (native bottom tabs with react-navigation):**
+
+```tsx
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
+
+const Tab = createNativeBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen
+        name='Home'
+        component={HomeScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'house' }),
+        }}
+      />
+      <Tab.Screen
+        name='Settings'
+        component={SettingsScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'gear' }),
+        }}
+      />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct (expo-router native tabs):**
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name='index'>
+        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name='settings'>
+        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='gear' md='settings' />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  )
+}
+```
+
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+behind the translucent tab bar. If you need to disable this, use
+`disableAutomaticContentInsets` on the trigger.
+
+### Prefer Native Header Options Over Custom Components
+
+**Incorrect (custom header component):**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    header: () => <CustomHeader title='Profile' />,
+  }}
+/>
+```
+
+**Correct (native header options):**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    title: 'Profile',
+    headerLargeTitleEnabled: true,
+    headerSearchBarOptions: {
+      placeholder: 'Search',
+    },
+  }}
+/>
+```
+
+Native headers support iOS large titles, search bars, blur effects, and proper
+safe area handling automatically.
+
+### Why Native Navigators
+
+- **Performance**: Native transitions and gestures run on the UI thread
+- **Platform behavior**: Automatic iOS large titles, Android material design
+- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
+  areas
+- **Accessibility**: Platform accessibility features work automatically
+
+Reference:
+
+- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
+- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
+- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
+- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)
diff --git a/skills/vercel/react-native-skills/rules/react-compiler-destructure-functions.md b/skills/vercel/react-native-skills/rules/react-compiler-destructure-functions.md
new file mode 100644
index 0000000..f76c25a
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/react-compiler-destructure-functions.md
@@ -0,0 +1,50 @@
+---
+title: Destructure Functions Early in Render (React Compiler)
+impact: HIGH
+impactDescription: stable references, fewer re-renders
+tags: rerender, hooks, performance, react-compiler
+---
+
+## Destructure Functions Early in Render
+
+This rule is only applicable if you are using the React Compiler.
+
+Destructure functions from hooks at the top of render scope. Never dot into
+objects to call functions. Destructured functions are stable references; dotting
+creates new references and breaks memoization.
+
+**Incorrect (dotting into object):**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton(props) {
+  const router = useRouter()
+
+  // bad: react-compiler will key the cache on "props" and "router", which are objects that change each render
+  const handlePress = () => {
+    props.onSave()
+    router.push('/success') // unstable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
+
+**Correct (destructure early):**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton({ onSave }) {
+  const { push } = useRouter()
+
+  // good: react-compiler will key on push and onSave
+  const handlePress = () => {
+    onSave()
+    push('/success') // stable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
diff --git a/skills/vercel/react-native-skills/rules/react-compiler-reanimated-shared-values.md b/skills/vercel/react-native-skills/rules/react-compiler-reanimated-shared-values.md
new file mode 100644
index 0000000..0dcbaf4
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/react-compiler-reanimated-shared-values.md
@@ -0,0 +1,48 @@
+---
+title: Use .get() and .set() for Reanimated Shared Values (not .value)
+impact: LOW
+impactDescription: required for React Compiler compatibility
+tags: reanimated, react-compiler, shared-values
+---
+
+## Use .get() and .set() for Shared Values with React Compiler
+
+With React Compiler enabled, use `.get()` and `.set()` instead of reading or
+writing `.value` directly on Reanimated shared values. The compiler can't track
+property access—explicit methods ensure correct behavior.
+
+**Incorrect (breaks with React Compiler):**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.value = count.value + 1 // opts out of react compiler
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.value}`} />
+}
+```
+
+**Correct (React Compiler compatible):**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.set(count.get() + 1)
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.get()}`} />
+}
+```
+
+See the
+[Reanimated docs](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/#react-compiler-support)
+for more.
diff --git a/skills/vercel/react-native-skills/rules/react-state-dispatcher.md b/skills/vercel/react-native-skills/rules/react-state-dispatcher.md
new file mode 100644
index 0000000..93e8b6d
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/react-state-dispatcher.md
@@ -0,0 +1,91 @@
+---
+title: useState Dispatch updaters for State That Depends on Current Value
+impact: MEDIUM
+impactDescription: avoids stale closures, prevents unnecessary re-renders
+tags: state, hooks, useState, callbacks
+---
+
+## Use Dispatch Updaters for State That Depends on Current Value
+
+When the next state depends on the current state, use a dispatch updater
+(`setState(prev => ...)`) instead of reading the state variable directly in a
+callback. This avoids stale closures and ensures you're comparing against the
+latest value.
+
+**Incorrect (reads state directly):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  // size may be stale in this closure
+  if (size?.width !== width || size?.height !== height) {
+    setSize({ width, height })
+  }
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => {
+    if (prev?.width === width && prev?.height === height) return prev
+    return { width, height }
+  })
+}
+```
+
+Returning the previous value from the updater skips the re-render.
+
+For primitive states, you don't need to compare values before firing a
+re-render.
+
+**Incorrect (unnecessary comparison for primitive state):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => (prev === width ? prev : width))
+}
+```
+
+**Correct (sets primitive state directly):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize(width)
+}
+```
+
+However, if the next state depends on the current state, you should still use a
+dispatch updater.
+
+**Incorrect (reads state directly from the callback):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount(count + 1)
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount((prev) => prev + 1)
+}
+```
diff --git a/skills/vercel/react-native-skills/rules/react-state-fallback.md b/skills/vercel/react-native-skills/rules/react-state-fallback.md
new file mode 100644
index 0000000..204f346
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/react-state-fallback.md
@@ -0,0 +1,56 @@
+---
+title: Use fallback state instead of initialState
+impact: MEDIUM
+impactDescription: reactive fallbacks without syncing
+tags: state, hooks, derived-state, props, initialState
+---
+
+## Use fallback state instead of initialState
+
+Use `undefined` as initial state and nullish coalescing (`??`) to fall back to
+parent or server values. State represents user intent only—`undefined` means
+"user hasn't chosen yet." This enables reactive fallbacks that update when the
+source changes, not just on initial render.
+
+**Incorrect (syncs state, loses reactivity):**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [enabled, setEnabled] = useState(defaultEnabled)
+  // If fallbackEnabled changes, state is stale
+  // State mixes user intent with default value
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**Correct (state is user intent, reactive fallback):**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [_enabled, setEnabled] = useState<boolean | undefined>(undefined)
+  const enabled = _enabled ?? defaultEnabled
+  // undefined = user hasn't touched it, falls back to prop
+  // If defaultEnabled changes, component reflects it
+  // Once user interacts, their choice persists
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**With server data:**
+
+```tsx
+function ProfileForm({ data }: { data: User }) {
+  const [_theme, setTheme] = useState<string | undefined>(undefined)
+  const theme = _theme ?? data.theme
+  // Shows server value until user overrides
+  // Server refetch updates the fallback automatically
+
+  return <ThemePicker value={theme} onChange={setTheme} />
+}
+```
diff --git a/skills/vercel/react-native-skills/rules/react-state-minimize.md b/skills/vercel/react-native-skills/rules/react-state-minimize.md
new file mode 100644
index 0000000..64605b6
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/react-state-minimize.md
@@ -0,0 +1,65 @@
+---
+title: Minimize State Variables and Derive Values
+impact: MEDIUM
+impactDescription: fewer re-renders, less state drift
+tags: state, derived-state, hooks, optimization
+---
+
+## Minimize State Variables and Derive Values
+
+Use the fewest state variables possible. If a value can be computed from existing state or props, derive it during render instead of storing it in state. Redundant state causes unnecessary re-renders and can drift out of sync.
+
+**Incorrect (redundant state):**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const [total, setTotal] = useState(0)
+  const [itemCount, setItemCount] = useState(0)
+
+  useEffect(() => {
+    setTotal(items.reduce((sum, item) => sum + item.price, 0))
+    setItemCount(items.length)
+  }, [items])
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Correct (derived values):**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const total = items.reduce((sum, item) => sum + item.price, 0)
+  const itemCount = items.length
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Another example:**
+
+```tsx
+// Incorrect: storing both firstName, lastName, AND fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const [fullName, setFullName] = useState('')
+
+// Correct: derive fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const fullName = `${firstName} ${lastName}`
+```
+
+State should be the minimal source of truth. Everything else is derived.
+
+Reference: [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure)
diff --git a/skills/vercel/react-native-skills/rules/rendering-no-falsy-and.md b/skills/vercel/react-native-skills/rules/rendering-no-falsy-and.md
new file mode 100644
index 0000000..30f05d3
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/rendering-no-falsy-and.md
@@ -0,0 +1,74 @@
+---
+title: Never Use && with Potentially Falsy Values
+impact: CRITICAL
+impactDescription: prevents production crash
+tags: rendering, conditional, jsx, crash
+---
+
+## Never Use && with Potentially Falsy Values
+
+Never use `{value && <Component />}` when `value` could be an empty string or
+`0`. These are falsy but JSX-renderable—React Native will try to render them as
+text outside a `<Text>` component, causing a hard crash in production.
+
+**Incorrect (crashes if count is 0 or name is ""):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name && <Text>{name}</Text>}
+      {count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+// If name="" or count=0, renders the falsy value → crash
+```
+
+**Correct (ternary with null):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name ? <Text>{name}</Text> : null}
+      {count ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+**Correct (explicit boolean coercion):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {!!name && <Text>{name}</Text>}
+      {!!count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+```
+
+**Best (early return):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  if (!name) return null
+
+  return (
+    <View>
+      <Text>{name}</Text>
+      {count > 0 ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+Early returns are clearest. When using conditionals inline, prefer ternary or
+explicit boolean checks.
+
+**Lint rule:** Enable `react/jsx-no-leaked-render` from
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)
+to catch this automatically.
diff --git a/skills/vercel/react-native-skills/rules/rendering-text-in-text-component.md b/skills/vercel/react-native-skills/rules/rendering-text-in-text-component.md
new file mode 100644
index 0000000..fd1b9f4
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/rendering-text-in-text-component.md
@@ -0,0 +1,36 @@
+---
+title: Wrap Strings in Text Components
+impact: CRITICAL
+impactDescription: prevents runtime crash
+tags: rendering, text, core
+---
+
+## Wrap Strings in Text Components
+
+Strings must be rendered inside `<Text>`. React Native crashes if a string is a
+direct child of `<View>`.
+
+**Incorrect (crashes):**
+
+```tsx
+import { View } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return <View>Hello, {name}!</View>
+}
+// Error: Text strings must be rendered within a <Text> component.
+```
+
+**Correct:**
+
+```tsx
+import { View, Text } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return (
+    <View>
+      <Text>Hello, {name}!</Text>
+    </View>
+  )
+}
+```
diff --git a/skills/vercel/react-native-skills/rules/scroll-position-no-state.md b/skills/vercel/react-native-skills/rules/scroll-position-no-state.md
new file mode 100644
index 0000000..a5760cd
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/scroll-position-no-state.md
@@ -0,0 +1,82 @@
+---
+title: Never Track Scroll Position in useState
+impact: HIGH
+impactDescription: prevents render thrashing during scroll
+tags: scroll, performance, reanimated, useRef
+---
+
+## Never Track Scroll Position in useState
+
+Never store scroll position in `useState`. Scroll events fire rapidly—state
+updates cause render thrashing and dropped frames. Use a Reanimated shared value
+for animations or a ref for non-reactive tracking.
+
+**Incorrect (useState causes jank):**
+
+```tsx
+import { useState } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const [scrollY, setScrollY] = useState(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
+
+**Correct (Reanimated for animations):**
+
+```tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedScrollHandler,
+} from 'react-native-reanimated'
+
+function Feed() {
+  const scrollY = useSharedValue(0)
+
+  const onScroll = useAnimatedScrollHandler({
+    onScroll: (e) => {
+      scrollY.value = e.contentOffset.y // runs on UI thread, no re-render
+    },
+  })
+
+  return (
+    <Animated.ScrollView
+      onScroll={onScroll}
+      // higher number has better performance, but it fires less often.
+      // unset this if you need higher precision over performance.
+      scrollEventThrottle={16}
+    />
+  )
+}
+```
+
+**Correct (ref for non-reactive tracking):**
+
+```tsx
+import { useRef } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const scrollY = useRef(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    scrollY.current = e.nativeEvent.contentOffset.y // no re-render
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
diff --git a/skills/vercel/react-native-skills/rules/state-ground-truth.md b/skills/vercel/react-native-skills/rules/state-ground-truth.md
new file mode 100644
index 0000000..c3c4bd9
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/state-ground-truth.md
@@ -0,0 +1,80 @@
+---
+title: State Must Represent Ground Truth
+impact: HIGH
+impactDescription: cleaner logic, easier debugging, single source of truth
+tags: state, derived-state, reanimated, hooks
+---
+
+## State Must Represent Ground Truth
+
+State variables—both React `useState` and Reanimated shared values—should
+represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),
+not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive
+visual values from state using computation or interpolation.
+
+**Incorrect (storing the visual output):**
+
+```tsx
+const scale = useSharedValue(1)
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    scale.set(withTiming(0.95))
+  })
+  .onFinalize(() => {
+    scale.set(withTiming(1))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.get() }],
+}))
+```
+
+**Correct (storing the state, deriving the visual):**
+
+```tsx
+const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    pressed.set(withTiming(1))
+  })
+  .onFinalize(() => {
+    pressed.set(withTiming(0))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],
+}))
+```
+
+**Why this matters:**
+
+State variables should represent real "state", not necessarily a desired end
+result.
+
+1. **Single source of truth** — The state (`pressed`) describes what's
+   happening; visuals are derived
+2. **Easier to extend** — Adding opacity, rotation, or other effects just
+   requires more interpolations from the same state
+3. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`
+4. **Reusable logic** — The same `pressed` value can drive multiple visual
+   properties
+
+**Same principle for React state:**
+
+```tsx
+// Incorrect: storing derived values
+const [isExpanded, setIsExpanded] = useState(false)
+const [height, setHeight] = useState(0)
+
+useEffect(() => {
+  setHeight(isExpanded ? 200 : 0)
+}, [isExpanded])
+
+// Correct: derive from state
+const [isExpanded, setIsExpanded] = useState(false)
+const height = isExpanded ? 200 : 0
+```
+
+State is the minimal truth. Everything else is derived.
diff --git a/skills/vercel/react-native-skills/rules/ui-expo-image.md b/skills/vercel/react-native-skills/rules/ui-expo-image.md
new file mode 100644
index 0000000..72d768f
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-expo-image.md
@@ -0,0 +1,66 @@
+---
+title: Use expo-image for Optimized Images
+impact: HIGH
+impactDescription: memory efficiency, caching, blurhash placeholders, progressive loading
+tags: images, performance, expo-image, ui
+---
+
+## Use expo-image for Optimized Images
+
+Use `expo-image` instead of React Native's `Image`. It provides memory-efficient caching, blurhash placeholders, progressive loading, and better performance for lists.
+
+**Incorrect (React Native Image):**
+
+```tsx
+import { Image } from 'react-native'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**Correct (expo-image):**
+
+```tsx
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**With blurhash placeholder:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  placeholder={{ blurhash: 'LGF5]+Yk^6#M@-5c,1J5@[or[Q6.' }}
+  contentFit="cover"
+  transition={200}
+  style={styles.image}
+/>
+```
+
+**With priority and caching:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  priority="high"
+  cachePolicy="memory-disk"
+  style={styles.hero}
+/>
+```
+
+**Key props:**
+
+- `placeholder` — Blurhash or thumbnail while loading
+- `contentFit` — `cover`, `contain`, `fill`, `scale-down`
+- `transition` — Fade-in duration (ms)
+- `priority` — `low`, `normal`, `high`
+- `cachePolicy` — `memory`, `disk`, `memory-disk`, `none`
+- `recyclingKey` — Unique key for list recycling
+
+For cross-platform (web + native), use `SolitoImage` from `solito/image` which uses `expo-image` under the hood.
+
+Reference: [expo-image](https://docs.expo.dev/versions/latest/sdk/image/)
diff --git a/skills/vercel/react-native-skills/rules/ui-image-gallery.md b/skills/vercel/react-native-skills/rules/ui-image-gallery.md
new file mode 100644
index 0000000..ef26d96
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-image-gallery.md
@@ -0,0 +1,104 @@
+---
+title: Use Galeria for Image Galleries and Lightbox
+impact: MEDIUM
+impactDescription:
+  native shared element transitions, pinch-to-zoom, pan-to-close
+tags: images, gallery, lightbox, expo-image, ui
+---
+
+## Use Galeria for Image Galleries and Lightbox
+
+For image galleries with lightbox (tap to fullscreen), use `@nandorojo/galeria`.
+It provides native shared element transitions with pinch-to-zoom, double-tap
+zoom, and pan-to-close. Works with any image component including `expo-image`.
+
+**Incorrect (custom modal implementation):**
+
+```tsx
+function ImageGallery({ urls }: { urls: string[] }) {
+  const [selected, setSelected] = useState<string | null>(null)
+
+  return (
+    <>
+      {urls.map((url) => (
+        <Pressable key={url} onPress={() => setSelected(url)}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Pressable>
+      ))}
+      <Modal visible={!!selected} onRequestClose={() => setSelected(null)}>
+        <Image source={{ uri: selected! }} style={styles.fullscreen} />
+      </Modal>
+    </>
+  )
+}
+```
+
+**Correct (Galeria with expo-image):**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function ImageGallery({ urls }: { urls: string[] }) {
+  return (
+    <Galeria urls={urls}>
+      {urls.map((url, index) => (
+        <Galeria.Image index={index} key={url}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Galeria.Image>
+      ))}
+    </Galeria>
+  )
+}
+```
+
+**Single image:**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return (
+    <Galeria urls={[url]}>
+      <Galeria.Image>
+        <Image source={{ uri: url }} style={styles.avatar} />
+      </Galeria.Image>
+    </Galeria>
+  )
+}
+```
+
+**With low-res thumbnails and high-res fullscreen:**
+
+```tsx
+<Galeria urls={highResUrls}>
+  {lowResUrls.map((url, index) => (
+    <Galeria.Image index={index} key={url}>
+      <Image source={{ uri: url }} style={styles.thumbnail} />
+    </Galeria.Image>
+  ))}
+</Galeria>
+```
+
+**With FlashList:**
+
+```tsx
+<Galeria urls={urls}>
+  <FlashList
+    data={urls}
+    renderItem={({ item, index }) => (
+      <Galeria.Image index={index}>
+        <Image source={{ uri: item }} style={styles.thumbnail} />
+      </Galeria.Image>
+    )}
+    numColumns={3}
+    estimatedItemSize={100}
+  />
+</Galeria>
+```
+
+Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image
+component.
+
+Reference: [Galeria](https://github.com/nandorojo/galeria)
diff --git a/skills/vercel/react-native-skills/rules/ui-measure-views.md b/skills/vercel/react-native-skills/rules/ui-measure-views.md
new file mode 100644
index 0000000..8b783fe
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-measure-views.md
@@ -0,0 +1,78 @@
+---
+title: Measuring View Dimensions
+impact: MEDIUM
+impactDescription: synchronous measurement, avoid unnecessary re-renders
+tags: layout, measurement, onLayout, useLayoutEffect
+---
+
+## Measuring View Dimensions
+
+Use both `useLayoutEffect` (synchronous) and `onLayout` (for updates). The sync
+measurement gives you the initial size immediately; `onLayout` keeps it current
+when the view changes. For non-primitive states, use a dispatch updater to
+compare values and avoid unnecessary re-renders.
+
+**Height only:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [height, setHeight] = useState<number | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    // Sync measurement on mount (RN 0.82+)
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setHeight(rect.height)
+    // Pre-0.82: ref.current?.measure((x, y, w, h) => setHeight(h))
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    setHeight(e.nativeEvent.layout.height)
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+**Both dimensions:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+type Size = { width: number; height: number }
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [size, setSize] = useState<Size | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setSize({ width: rect.width, height: rect.height })
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout
+    setSize((prev) => {
+      // for non-primitive states, compare values before firing a re-render
+      if (prev?.width === width && prev?.height === height) return prev
+      return { width, height }
+    })
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+Use functional setState to compare—don't read state directly in the callback.
diff --git a/skills/vercel/react-native-skills/rules/ui-menus.md b/skills/vercel/react-native-skills/rules/ui-menus.md
new file mode 100644
index 0000000..5168bc2
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-menus.md
@@ -0,0 +1,174 @@
+---
+title: Use Native Menus for Dropdowns and Context Menus
+impact: HIGH
+impactDescription: native accessibility, platform-consistent UX
+tags: user-interface, menus, context-menus, zeego, accessibility
+---
+
+## Use Native Menus for Dropdowns and Context Menus
+
+Use native platform menus instead of custom JS implementations. Native menus
+provide built-in accessibility, consistent platform UX, and better performance.
+Use [zeego](https://zeego.dev) for cross-platform native menus.
+
+**Incorrect (custom JS menu):**
+
+```tsx
+import { useState } from 'react'
+import { View, Pressable, Text } from 'react-native'
+
+function MyMenu() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <View>
+      <Pressable onPress={() => setOpen(!open)}>
+        <Text>Open Menu</Text>
+      </Pressable>
+      {open && (
+        <View style={{ position: 'absolute', top: 40 }}>
+          <Pressable onPress={() => console.log('edit')}>
+            <Text>Edit</Text>
+          </Pressable>
+          <Pressable onPress={() => console.log('delete')}>
+            <Text>Delete</Text>
+          </Pressable>
+        </View>
+      )}
+    </View>
+  )
+}
+```
+
+**Correct (native menu with zeego):**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MyMenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Open Menu</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='edit' onSelect={() => console.log('edit')}>
+          <DropdownMenu.ItemTitle>Edit</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Item
+          key='delete'
+          destructive
+          onSelect={() => console.log('delete')}
+        >
+          <DropdownMenu.ItemTitle>Delete</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Context menu (long-press):**
+
+```tsx
+import * as ContextMenu from 'zeego/context-menu'
+
+function MyContextMenu() {
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <View style={{ padding: 20 }}>
+          <Text>Long press me</Text>
+        </View>
+      </ContextMenu.Trigger>
+
+      <ContextMenu.Content>
+        <ContextMenu.Item key='copy' onSelect={() => console.log('copy')}>
+          <ContextMenu.ItemTitle>Copy</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+
+        <ContextMenu.Item key='paste' onSelect={() => console.log('paste')}>
+          <ContextMenu.ItemTitle>Paste</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+      </ContextMenu.Content>
+    </ContextMenu.Root>
+  )
+}
+```
+
+**Checkbox items:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function SettingsMenu() {
+  const [notifications, setNotifications] = useState(true)
+
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Settings</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.CheckboxItem
+          key='notifications'
+          value={notifications}
+          onValueChange={() => setNotifications((prev) => !prev)}
+        >
+          <DropdownMenu.ItemIndicator />
+          <DropdownMenu.ItemTitle>Notifications</DropdownMenu.ItemTitle>
+        </DropdownMenu.CheckboxItem>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Submenus:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MenuWithSubmenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Options</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='home' onSelect={() => console.log('home')}>
+          <DropdownMenu.ItemTitle>Home</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Sub>
+          <DropdownMenu.SubTrigger key='more'>
+            <DropdownMenu.ItemTitle>More Options</DropdownMenu.ItemTitle>
+          </DropdownMenu.SubTrigger>
+
+          <DropdownMenu.SubContent>
+            <DropdownMenu.Item key='settings'>
+              <DropdownMenu.ItemTitle>Settings</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+
+            <DropdownMenu.Item key='help'>
+              <DropdownMenu.ItemTitle>Help</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+          </DropdownMenu.SubContent>
+        </DropdownMenu.Sub>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+Reference: [Zeego Documentation](https://zeego.dev/components/dropdown-menu)
diff --git a/skills/vercel/react-native-skills/rules/ui-native-modals.md b/skills/vercel/react-native-skills/rules/ui-native-modals.md
new file mode 100644
index 0000000..f560e11
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-native-modals.md
@@ -0,0 +1,77 @@
+---
+title: Use Native Modals Over JS-Based Bottom Sheets
+impact: HIGH
+impactDescription: native performance, gestures, accessibility
+tags: modals, bottom-sheet, native, react-navigation
+---
+
+## Use Native Modals Over JS-Based Bottom Sheets
+
+Use native `<Modal>` with `presentationStyle="formSheet"` or React Navigation
+v7's native form sheet instead of JS-based bottom sheet libraries. Native modals
+have built-in gestures, accessibility, and better performance. Rely on native UI
+for low-level primitives.
+
+**Incorrect (JS-based bottom sheet):**
+
+```tsx
+import BottomSheet from 'custom-js-bottom-sheet'
+
+function MyScreen() {
+  const sheetRef = useRef<BottomSheet>(null)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => sheetRef.current?.expand()} title='Open' />
+      <BottomSheet ref={sheetRef} snapPoints={['50%', '90%']}>
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </BottomSheet>
+    </View>
+  )
+}
+```
+
+**Correct (native Modal with formSheet):**
+
+```tsx
+import { Modal, View, Text, Button } from 'react-native'
+
+function MyScreen() {
+  const [visible, setVisible] = useState(false)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => setVisible(true)} title='Open' />
+      <Modal
+        visible={visible}
+        presentationStyle='formSheet'
+        animationType='slide'
+        onRequestClose={() => setVisible(false)}
+      >
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </Modal>
+    </View>
+  )
+}
+```
+
+**Correct (React Navigation v7 native form sheet):**
+
+```tsx
+// In your navigator
+<Stack.Screen
+  name='Details'
+  component={DetailsScreen}
+  options={{
+    presentation: 'formSheet',
+    sheetAllowedDetents: 'fitToContents',
+  }}
+/>
+```
+
+Native modals provide swipe-to-dismiss, proper keyboard avoidance, and
+accessibility out of the box.
diff --git a/skills/vercel/react-native-skills/rules/ui-pressable.md b/skills/vercel/react-native-skills/rules/ui-pressable.md
new file mode 100644
index 0000000..31c3d20
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-pressable.md
@@ -0,0 +1,61 @@
+---
+title: Use Pressable Instead of Touchable Components
+impact: LOW
+impactDescription: modern API, more flexible
+tags: ui, pressable, touchable, gestures
+---
+
+## Use Pressable Instead of Touchable Components
+
+Never use `TouchableOpacity` or `TouchableHighlight`. Use `Pressable` from
+`react-native` or `react-native-gesture-handler` instead.
+
+**Incorrect (legacy Touchable components):**
+
+```tsx
+import { TouchableOpacity } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <TouchableOpacity onPress={onPress} activeOpacity={0.7}>
+      <Text>Press me</Text>
+    </TouchableOpacity>
+  )
+}
+```
+
+**Correct (Pressable):**
+
+```tsx
+import { Pressable } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Press me</Text>
+    </Pressable>
+  )
+}
+```
+
+**Correct (Pressable from gesture handler for lists):**
+
+```tsx
+import { Pressable } from 'react-native-gesture-handler'
+
+function ListItem({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Item</Text>
+    </Pressable>
+  )
+}
+```
+
+Use `react-native-gesture-handler` Pressable inside scrollable lists for better
+gesture coordination, as long as you are using the ScrollView from
+`react-native-gesture-handler` as well.
+
+**For animated press states (scale, opacity changes):** Use `GestureDetector`
+with Reanimated shared values instead of Pressable's style callback. See the
+`animation-gesture-detector-press` rule.
diff --git a/skills/vercel/react-native-skills/rules/ui-safe-area-scroll.md b/skills/vercel/react-native-skills/rules/ui-safe-area-scroll.md
new file mode 100644
index 0000000..79812bc
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-safe-area-scroll.md
@@ -0,0 +1,65 @@
+---
+title: Use contentInsetAdjustmentBehavior for Safe Areas
+impact: MEDIUM
+impactDescription: native safe area handling, no layout shifts
+tags: safe-area, scrollview, layout
+---
+
+## Use contentInsetAdjustmentBehavior for Safe Areas
+
+Use `contentInsetAdjustmentBehavior="automatic"` on the root ScrollView instead of wrapping content in SafeAreaView or manual padding. This lets iOS handle safe area insets natively with proper scroll behavior.
+
+**Incorrect (SafeAreaView wrapper):**
+
+```tsx
+import { SafeAreaView, ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <ScrollView>
+        <View>
+          <Text>Content</Text>
+        </View>
+      </ScrollView>
+    </SafeAreaView>
+  )
+}
+```
+
+**Incorrect (manual safe area padding):**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+function MyScreen() {
+  const insets = useSafeAreaInsets()
+
+  return (
+    <ScrollView contentContainerStyle={{ paddingTop: insets.top }}>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+**Correct (native content inset adjustment):**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <ScrollView contentInsetAdjustmentBehavior='automatic'>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+The native approach handles dynamic safe areas (keyboard, toolbars) and allows content to scroll behind the status bar naturally.
diff --git a/skills/vercel/react-native-skills/rules/ui-scrollview-content-inset.md b/skills/vercel/react-native-skills/rules/ui-scrollview-content-inset.md
new file mode 100644
index 0000000..bbebc3b
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-scrollview-content-inset.md
@@ -0,0 +1,45 @@
+---
+title: Use contentInset for Dynamic ScrollView Spacing
+impact: LOW
+impactDescription: smoother updates, no layout recalculation
+tags: scrollview, layout, contentInset, performance
+---
+
+## Use contentInset for Dynamic ScrollView Spacing
+
+When adding space to the top or bottom of a ScrollView that may change
+(keyboard, toolbars, dynamic content), use `contentInset` instead of padding.
+Changing `contentInset` doesn't trigger layout recalculation—it adjusts the
+scroll area without re-rendering content.
+
+**Incorrect (padding causes layout recalculation):**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView contentContainerStyle={{ paddingBottom: bottomOffset }}>
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset triggers full layout recalculation
+```
+
+**Correct (contentInset for dynamic spacing):**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView
+      contentInset={{ bottom: bottomOffset }}
+      scrollIndicatorInsets={{ bottom: bottomOffset }}
+    >
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset only adjusts scroll bounds
+```
+
+Use `scrollIndicatorInsets` alongside `contentInset` to keep the scroll
+indicator aligned. For static spacing that never changes, padding is fine.
diff --git a/skills/vercel/react-native-skills/rules/ui-styling.md b/skills/vercel/react-native-skills/rules/ui-styling.md
new file mode 100644
index 0000000..3908de3
--- /dev/null
+++ b/skills/vercel/react-native-skills/rules/ui-styling.md
@@ -0,0 +1,87 @@
+---
+title: Modern React Native Styling Patterns
+impact: MEDIUM
+impactDescription: consistent design, smoother borders, cleaner layouts
+tags: styling, css, layout, shadows, gradients
+---
+
+## Modern React Native Styling Patterns
+
+Follow these styling patterns for cleaner, more consistent React Native code.
+
+**Always use `borderCurve: 'continuous'` with `borderRadius`:**
+
+```tsx
+// Incorrect
+{ borderRadius: 12 }
+
+// Correct – smoother iOS-style corners
+{ borderRadius: 12, borderCurve: 'continuous' }
+```
+
+**Use `gap` instead of margin for spacing between elements:**
+
+```tsx
+// Incorrect – margin on children
+<View>
+  <Text style={{ marginBottom: 8 }}>Title</Text>
+  <Text style={{ marginBottom: 8 }}>Subtitle</Text>
+</View>
+
+// Correct – gap on parent
+<View style={{ gap: 8 }}>
+  <Text>Title</Text>
+  <Text>Subtitle</Text>
+</View>
+```
+
+**Use `padding` for space within, `gap` for space between:**
+
+```tsx
+<View style={{ padding: 16, gap: 12 }}>
+  <Text>First</Text>
+  <Text>Second</Text>
+</View>
+```
+
+**Use `experimental_backgroundImage` for linear gradients:**
+
+```tsx
+// Incorrect – third-party gradient library
+<LinearGradient colors={['#000', '#fff']} />
+
+// Correct – native CSS gradient syntax
+<View
+  style={{
+    experimental_backgroundImage: 'linear-gradient(to bottom, #000, #fff)',
+  }}
+/>
+```
+
+**Use CSS `boxShadow` string syntax for shadows:**
+
+```tsx
+// Incorrect – legacy shadow objects or elevation
+{ shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1 }
+{ elevation: 4 }
+
+// Correct – CSS box-shadow syntax
+{ boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)' }
+```
+
+**Avoid multiple font sizes – use weight and color for emphasis:**
+
+```tsx
+// Incorrect – varying font sizes for hierarchy
+<Text style={{ fontSize: 18 }}>Title</Text>
+<Text style={{ fontSize: 14 }}>Subtitle</Text>
+<Text style={{ fontSize: 12 }}>Caption</Text>
+
+// Correct – consistent size, vary weight and color
+<Text style={{ fontWeight: '600' }}>Title</Text>
+<Text style={{ color: '#666' }}>Subtitle</Text>
+<Text style={{ color: '#999' }}>Caption</Text>
+```
+
+Limiting font sizes creates visual consistency. Use `fontWeight` (bold/semibold)
+and grayscale colors for hierarchy instead.
diff --git a/skills/vercel/react-view-transitions/AGENTS.md b/skills/vercel/react-view-transitions/AGENTS.md
new file mode 100644
index 0000000..8e21361
--- /dev/null
+++ b/skills/vercel/react-view-transitions/AGENTS.md
@@ -0,0 +1,955 @@
+# React View Transitions
+
+**Version 1.0.0**
+Vercel Engineering
+March 2026
+
+> **Note:**
+> This document is mainly for agents and LLMs to follow when implementing
+> view transitions in React applications. Humans may also find it useful,
+> but guidance here is optimized for automation and consistency by
+> AI-assisted workflows.
+
+---
+
+## Abstract
+
+Guide for implementing smooth, native-feeling animations using React's View Transition API. Covers the `<ViewTransition>` component, `addTransitionType`, CSS view transition pseudo-elements, shared element transitions, Suspense reveals, list reorder, directional navigation, and Next.js integration. Includes a step-by-step implementation workflow, ready-to-use CSS animation recipes, and common mistake warnings.
+
+---
+
+## Table of Contents
+
+1. [Core Reference](#when-to-animate)
+   - [When to Animate](#when-to-animate)
+   - [Availability](#availability)
+   - [Core Concepts](#core-concepts)
+   - [Styling with View Transition Classes](#styling-with-view-transition-classes)
+   - [Transition Types](#transition-types)
+   - [Shared Element Transitions](#shared-element-transitions)
+   - [Common Patterns](#common-patterns)
+   - [How Multiple VTs Interact](#how-multiple-vts-interact)
+   - [Next.js Integration](#nextjs-integration)
+   - [Accessibility](#accessibility)
+2. [Implementation Workflow](#implementation-workflow)
+   - [Step 1: Audit the App](#step-1-audit-the-app)
+   - [Step 2: Add CSS Recipes](#step-2-add-css-recipes)
+   - [Step 3: Isolate Persistent Elements](#step-3-isolate-persistent-elements)
+   - [Step 4: Add Directional Page Transitions](#step-4-add-directional-page-transitions)
+   - [Step 5: Add Suspense Reveals](#step-5-add-suspense-reveals)
+   - [Step 6: Add Shared Element Transitions](#step-6-add-shared-element-transitions)
+   - [Step 7: Verify Each Navigation Path](#step-7-verify-each-navigation-path)
+   - [Common Mistakes](#common-mistakes)
+3. [Patterns and Guidelines](#patterns-and-guidelines)
+4. [CSS Animation Recipes](#css-animation-recipes)
+5. [View Transitions in Next.js](#view-transitions-in-nextjs)
+
+---
+
+Animate between UI states using the browser's native `document.startViewTransition`. Declare *what* with `<ViewTransition>`, trigger *when* with `startTransition` / `useDeferredValue` / `Suspense`, control *how* with CSS classes. Unsupported browsers skip animations gracefully.
+
+## When to Animate
+
+Every `<ViewTransition>` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.
+
+Implement **all** applicable patterns from this list, in this order:
+
+| Priority | Pattern | What it communicates |
+|----------|---------|---------------------|
+| 1 | **Shared element** (`name`) | "Same thing — going deeper" |
+| 2 | **Suspense reveal** | "Data loaded" |
+| 3 | **List identity** (per-item `key`) | "Same items, new arrangement" |
+| 4 | **State change** (`enter`/`exit`) | "Something appeared/disappeared" |
+| 5 | **Route change** (layout-level) | "Going to a new place" |
+
+This is an implementation order, not a "pick one" list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.
+
+### Choosing Animation Style
+
+| Context | Animation | Why |
+|---------|-----------|-----|
+| Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth |
+| Lateral navigation (tab-to-tab) | Bare `<ViewTransition>` (fade) or `default="none"` | No depth to communicate |
+| Suspense reveal | `enter`/`exit` string props | Content arriving |
+| Revalidation / background refresh | `default="none"` | Silent — no animation needed |
+
+Reserve directional slides for hierarchical navigation (list → detail) and ordered sequences (prev/next photo, carousel, paginated results). For ordered sequences, the direction communicates position: "next" slides from right, "previous" from left. Lateral/unordered navigation (tab-to-tab) should not use directional slides — it falsely implies spatial depth.
+
+---
+
+## Availability
+
+- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
+- **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
+- Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation.
+
+---
+
+## Core Concepts
+
+### The `<ViewTransition>` Component
+
+```jsx
+import { ViewTransition } from 'react';
+
+<ViewTransition>
+  <Component />
+</ViewTransition>
+```
+
+React auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself.
+
+### Animation Triggers
+
+| Trigger | When it fires |
+|---------|--------------|
+| **enter** | VT first inserted during a Transition |
+| **exit** | VT first removed during a Transition |
+| **update** | DOM mutations inside a VT. With nested VTs, mutation applies to the innermost one |
+| **share** | Named VT unmounts and another with same `name` mounts in same Transition |
+
+Only `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate.
+
+### Critical Placement Rule
+
+VT only activates enter/exit if it appears **before any DOM nodes**:
+
+```jsx
+// Works
+<ViewTransition enter="auto" exit="auto"><div>Content</div></ViewTransition>
+
+// Broken — div wraps the VT
+<div><ViewTransition enter="auto" exit="auto"><div>Content</div></ViewTransition></div>
+```
+
+---
+
+## Styling with View Transition Classes
+
+Values: `"auto"` (browser cross-fade), `"none"` (disabled), `"class-name"` (custom CSS), or `{ [type]: value }` for type-specific animations.
+
+```jsx
+<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
+```
+
+If `default` is `"none"`, all triggers are off unless explicitly listed.
+
+### CSS Pseudo-Elements
+
+- `::view-transition-old(.class)` — outgoing snapshot
+- `::view-transition-new(.class)` — incoming snapshot
+- `::view-transition-group(.class)` — container
+- `::view-transition-image-pair(.class)` — old + new pair
+
+---
+
+## Transition Types
+
+Tag transitions with `addTransitionType` so VTs can pick different animations. Call it multiple times to stack types — different VTs in the tree react to different types:
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  addTransitionType('select-item');
+  router.push('/detail/1');
+});
+```
+
+Map types to CSS classes. Works on `enter`, `exit`, **and** `share`:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
+  exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
+  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
+  default="none"
+>
+  <Page />
+</ViewTransition>
+```
+
+`enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
+  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+  default="none"
+>
+```
+
+**TypeScript:** `ViewTransitionClassPerType` requires a `default` key.
+
+### `router.back()` and Browser Back Button
+
+`router.back()` and the browser's back/forward buttons do **not** trigger view transitions (`popstate` is synchronous, incompatible with `startViewTransition`). Use `router.push()` with an explicit URL instead.
+
+### Types and Suspense
+
+Types are available during navigation but **not** during subsequent Suspense reveals (separate transitions, no type). Use type maps for page-level enter/exit; use simple string props for Suspense reveals.
+
+---
+
+## Shared Element Transitions
+
+Same `name` on two VTs — one unmounting, one mounting — creates a shared element morph:
+
+```jsx
+<ViewTransition name="hero-image">
+  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
+</ViewTransition>
+
+// Other view — same name
+<ViewTransition name="hero-image">
+  <img src="/full.jpg" />
+</ViewTransition>
+```
+
+- Only one VT with a given `name` can be mounted at a time — use unique names. Watch for reusable components: if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Either make the name conditional (via a prop) or move the named VT out of the shared component into the specific consumer.
+- `share` takes precedence over `enter`/`exit`. Think through each navigation path: when no pair forms, `enter`/`exit` fires instead. Consider whether the element needs a fallback animation for those paths.
+- Never use fade-out exit on pages with shared morphs — use directional slide.
+
+---
+
+## Common Patterns
+
+### Enter/Exit
+
+```jsx
+{show && (
+  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
+)}
+```
+
+### List Reorder
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
+))}
+```
+
+Trigger inside `startTransition`. Avoid wrapper `<div>`s between list and VT.
+
+### Composing Shared Elements with List Identity
+
+Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element, use two nested `<ViewTransition>` boundaries:
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}>                                      {/* list identity */}
+    <Link href={`/items/${item.id}`}>
+      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* shared element */}
+        <Image src={item.image} />
+      </ViewTransition>
+      <p>{item.name}</p>
+    </Link>
+  </ViewTransition>
+))}
+```
+
+The outer VT handles list reorder/enter. The inner VT handles cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
+
+### Force Re-Enter with `key`
+
+```jsx
+<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
+  <ResultsGrid />
+</ViewTransition>
+```
+
+**Caution:** Wrapping `<Suspense>` with key remounts the boundary and refetches.
+
+### Suspense Fallback to Content
+
+Simple cross-fade:
+```jsx
+<ViewTransition>
+  <Suspense fallback={<Skeleton />}><Content /></Suspense>
+</ViewTransition>
+```
+
+Directional reveal:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+</Suspense>
+```
+
+---
+
+## How Multiple VTs Interact
+
+Every VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions don't compete.
+
+### Use `default="none"` Liberally
+
+Without it, every VT fires the browser cross-fade on **every** transition. Always use `default="none"` and explicitly enable only desired triggers.
+
+### Two Patterns Coexist
+
+**Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation.
+**Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type).
+
+They coexist because they fire at different moments. `default="none"` on both prevents cross-interference. Always pair `enter` with `exit`. Place directional VTs in page components, not layouts.
+
+### Nested VT Limitation
+
+When a parent VT exits, nested VTs inside it do **not** fire their own enter/exit — only the outermost VT animates. Per-item staggered animations during page navigation are not possible today. See [react#36135](https://github.com/facebook/react/pull/36135) for an experimental opt-in fix.
+
+---
+
+## Next.js Integration
+
+See the [View Transitions in Next.js](#view-transitions-in-nextjs) section below.
+
+---
+
+## Accessibility
+
+Always add reduced motion CSS to your global stylesheet:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(*),
+  ::view-transition-new(*),
+  ::view-transition-group(*) {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+```
+
+---
+
+# Implementation Workflow
+
+**Follow these steps in order.** Start with the audit — do not skip it. Copy the CSS recipes from the CSS Recipes section below — do not write your own animation CSS.
+
+## Step 1: Audit the App
+
+Before writing any code, scan the codebase thoroughly. Search for:
+
+- **Every `<Link>` and `router.push`** — open every file that contains one
+- **Every `<Suspense>` boundary** — check what its fallback renders
+- **Every page/route component** — each needs a VT placement decision
+- **Persistent elements** (headers, navbars, sidebars) — need `viewTransitionName` isolation
+- **Shared visual elements** on both source and target views
+- **Skeleton-to-content control pairs** — if a fallback renders a control that also exists in the real content, both need a matching `viewTransitionName`
+
+Then classify every navigation and produce a navigation map:
+
+```
+| Route           | Navigates to         | Direction    | VT pattern            |
+|-----------------|----------------------|--------------|-----------------------|
+| /               | /detail/[id]         | forward      | directional slide     |
+| /detail/[id]    | /                    | back         | directional slide     |
+| /detail/[id]    | /detail/[other]      | sequential   | directional slide (ordered prev/next) or key+share crossfade |
+| /tab/[a]        | /tab/[b]             | lateral      | key+share crossfade   |
+| (Suspense)      | (content loads)      | —            | slide-up reveal       |
+```
+
+For each shared element (`name` prop), note where a pair forms and where it doesn't — this determines whether you need `enter`/`exit` as a fallback alongside `share`.
+
+## Step 2: Add CSS Recipes
+
+Copy the **complete** CSS recipe set from the CSS Animation Recipes section below into your global stylesheet. Don't write your own — the recipes handle staggered timing, motion blur, and reduced motion.
+
+## Step 3: Isolate Persistent Elements
+
+```jsx
+<header style={{ viewTransitionName: "site-header" }}>...</header>
+```
+
+```css
+::view-transition-group(site-header) {
+  animation: none;
+  z-index: 100;
+}
+```
+
+For `backdrop-blur`/`backdrop-filter`, use the backdrop-blur workaround instead.
+
+## Step 4: Add Directional Page Transitions
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  router.push('/detail/1');
+});
+```
+
+Wrap each **page component** (not layout) in a type-keyed VT:
+
+```jsx
+<ViewTransition
+  enter={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
+  exit={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
+  default="none"
+>
+  <div>...page content...</div>
+</ViewTransition>
+```
+
+Extract into a reusable component so every page doesn't repeat the type map:
+
+```jsx
+export function DirectionalTransition({ children }: { children: React.ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+```
+
+**Rules:** Always pair `enter` with `exit`. Always include `default: "none"`. Place in page components, not layouts. Only use directional slides for hierarchical navigation or ordered sequences (prev/next).
+
+## Step 5: Add Suspense Reveals
+
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition enter="slide-up" default="none"><AsyncContent /></ViewTransition>
+</Suspense>
+```
+
+Use `default="none"` on content VT. Use simple string props (not type maps) — Suspense resolves have no type.
+
+## Step 6: Add Shared Element Transitions
+
+```jsx
+// Source view
+<ViewTransition name={`photo-${photo.id}`} share="morph" default="none">
+  <Image src={photo.src} ... />
+</ViewTransition>
+
+// Target view — same name
+<ViewTransition name={`photo-${photo.id}`} share="morph">
+  <Image src={photo.src} ... />
+</ViewTransition>
+```
+
+When list items contain shared elements, compose both patterns — two independent layers:
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}>                                        {/* list identity */}
+    <Link href={`/detail/${item.id}`}>
+      <ViewTransition name={`item-${item.id}`} share="morph" default="none">  {/* shared element */}
+        <Image src={item.image} ... />
+      </ViewTransition>
+    </Link>
+  </ViewTransition>
+))}
+```
+
+The outer VT handles list reorder/enter. The inner VT handles cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
+
+**Rules:** Names must be globally unique. Add `default="none"` on list-side shared elements.
+
+## Step 7: Verify Each Navigation Path
+
+Walk through every row in the navigation map from Step 1:
+
+- Does the VT mount/unmount, or stay mounted (same-route)?
+- For named VTs: does a shared pair form? If not, does `enter`/`exit` provide a fallback?
+- Does `default="none"` block an animation you actually want?
+- Do persistent elements stay static?
+- Do Suspense reveals animate independently from directional navigations?
+
+---
+
+## Common Mistakes
+
+- **Bare VT without `default="none"`** — fires cross-fade on every transition
+- **Directional VT in a layout** — layouts persist, enter/exit won't fire on route changes
+- **Fade-out exit with shared morphs** — conflicts with morph, use directional slide
+- **Writing custom animation CSS** — use the recipes
+- **Missing `default: "none"` in type-keyed objects** — TypeScript requires it, fallback is `"auto"`
+- **Type maps on Suspense reveals** — Suspense resolves have no type, use string props
+- **Raw `viewTransitionName` CSS to trigger animations** — React only starts view transitions when `<ViewTransition>` components are in the tree. Bare `viewTransitionName` is for isolating elements, not triggering animations.
+- **`update` trigger for same-route navigations** — nested VTs steal the mutation from the parent. Use `key` + `name` + `share` instead.
+- **Named VT in a reusable component** — if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Make the name conditional or move it to the specific consumer.
+- **`router.back()` for back navigation** — `router.back()` triggers synchronous `popstate`, incompatible with view transitions. Use `router.push()` with an explicit URL.
+
+For Next.js-specific steps, see the Next.js section below.
+
+---
+
+# Patterns and Guidelines
+
+## Searchable Grid with `useDeferredValue`
+
+```tsx
+'use client';
+
+import { useDeferredValue, useState, ViewTransition, Suspense } from 'react';
+
+export default function SearchableGrid({ itemsPromise }) {
+  const [search, setSearch] = useState('');
+  const deferredSearch = useDeferredValue(search);
+
+  return (
+    <>
+      <input value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
+      <ViewTransition>
+        <Suspense fallback={<GridSkeleton />}>
+          <ItemGrid itemsPromise={itemsPromise} search={deferredSearch} />
+        </Suspense>
+      </ViewTransition>
+    </>
+  );
+}
+```
+
+Per-item named VTs in deferred lists trigger cross-fades on every keystroke. Fix with `default="none"`.
+
+## Card Expand/Collapse with `startTransition`
+
+```tsx
+'use client';
+
+import { useState, useRef, startTransition, ViewTransition } from 'react';
+
+export default function ItemGrid({ items }) {
+  const [expandedId, setExpandedId] = useState(null);
+  const scrollRef = useRef(0);
+
+  return expandedId ? (
+    <ViewTransition enter="slide-in" name={`item-${expandedId}`}>
+      <ItemDetail
+        item={items.find(i => i.id === expandedId)}
+        onClose={() => {
+          startTransition(() => {
+            setExpandedId(null);
+            setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);
+          });
+        }}
+      />
+    </ViewTransition>
+  ) : (
+    <div className="grid grid-cols-3 gap-4">
+      {items.map(item => (
+        <ViewTransition key={item.id} name={`item-${item.id}`}>
+          <ItemCard
+            item={item}
+            onSelect={() => {
+              scrollRef.current = window.scrollY;
+              startTransition(() => setExpandedId(item.id));
+            }}
+          />
+        </ViewTransition>
+      ))}
+    </div>
+  );
+}
+```
+
+## Cross-Fade Without Remount
+
+Omit `key` to trigger update (cross-fade) instead of exit + enter. Avoids Suspense remount:
+
+```jsx
+<ViewTransition><TabPanel tab={activeTab} /></ViewTransition>
+```
+
+## Isolate Elements from Parent Animations
+
+Persistent elements get captured in page's transition snapshot. Fix with `viewTransitionName`:
+
+```jsx
+<nav style={{ viewTransitionName: "persistent-nav" }}>{/* ... */}</nav>
+```
+
+```css
+::view-transition-group(persistent-nav) { animation: none; z-index: 100; }
+```
+
+Same for floating elements (popovers, tooltips). Global fix: `::view-transition-group(*) { z-index: 100; }`
+
+## Shared Controls Between Skeleton and Content
+
+Give matching controls the same `viewTransitionName`. Don't put manual `viewTransitionName` on root DOM node inside `<ViewTransition>`.
+
+## Reusable Animated Collapse
+
+```jsx
+function AnimatedCollapse({ open, children }) {
+  if (!open) return null;
+  return <ViewTransition enter="expand-in" exit="collapse-out">{children}</ViewTransition>;
+}
+```
+
+## Preserve State with Activity
+
+```jsx
+<Activity mode={isVisible ? 'visible' : 'hidden'}>
+  <ViewTransition enter="slide-in" exit="slide-out"><Sidebar /></ViewTransition>
+</Activity>
+```
+
+## Exclude Elements with `useOptimistic`
+
+`useOptimistic` values update before snapshot, excluding them from animation. Use for controls; use committed state for animated content.
+
+---
+
+## View Transition Events
+
+Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Always return cleanup. `onShare` takes precedence.
+
+```jsx
+<ViewTransition
+  onEnter={(instance, types) => {
+    const anim = instance.new.animate(
+      [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
+      { duration: 300, easing: 'ease-out' }
+    );
+    return () => anim.cancel();
+  }}
+>
+  <Component />
+</ViewTransition>
+```
+
+`instance`: `.old`, `.new`, `.group`, `.imagePair`, `.name`
+
+---
+
+## Animation Timing
+
+| Interaction | Duration |
+|------------|----------|
+| Direct toggle | 100–200ms |
+| Route transition | 150–250ms |
+| Suspense reveal | 200–400ms |
+| Shared element morph | 300–500ms |
+
+---
+
+## Troubleshooting
+
+**VT not activating:** Ensure VT comes before any DOM node. Ensure `startTransition`.
+
+**"Two VTs with same name":** Names must be globally unique. Use IDs.
+
+**`router.back()` and browser back/forward skip animation:** Use `router.push()` with an explicit URL instead.
+
+**Only updates animate:** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.
+
+**Layout VT prevents page VTs from animating:** Nested VTs never fire enter/exit inside a parent VT. If your layout has a VT wrapping `{children}`, page-level enter/exit will silently not work. Remove the layout VT.
+
+**TS error "Property 'default' is missing":** Type-keyed objects require a `default` key.
+
+**Backdrop-blur flickers:** `::view-transition-old(name) { display: none }` + `::view-transition-new(name) { animation: none }`.
+
+**`border-radius` lost:** Apply `border-radius` directly to captured element.
+
+**Batching:** Multiple updates during animation are batched (A→B→C→D becomes B→D).
+
+---
+
+# CSS Animation Recipes
+
+Ready-to-use CSS for `<ViewTransition>` props. Copy into global stylesheet.
+
+## Timing Variables
+
+```css
+:root {
+  --duration-exit: 150ms;
+  --duration-enter: 210ms;
+  --duration-move: 400ms;
+}
+```
+
+### Shared Keyframes
+
+```css
+@keyframes fade {
+  from { filter: blur(3px); opacity: 0; }
+  to { filter: blur(0); opacity: 1; }
+}
+
+@keyframes slide {
+  from { translate: var(--slide-offset); }
+  to { translate: 0; }
+}
+
+@keyframes slide-y {
+  from { transform: translateY(var(--slide-y-offset, 10px)); }
+  to { transform: translateY(0); }
+}
+```
+
+## Fade
+
+```css
+::view-transition-old(.fade-out) {
+  animation: var(--duration-exit) ease-in fade reverse;
+}
+::view-transition-new(.fade-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both fade;
+}
+```
+
+## Slide (Vertical)
+
+```css
+::view-transition-old(.slide-down) {
+  animation:
+    var(--duration-exit) ease-out both fade reverse,
+    var(--duration-exit) ease-out both slide-y reverse;
+}
+::view-transition-new(.slide-up) {
+  animation:
+    var(--duration-enter) ease-in var(--duration-exit) both fade,
+    var(--duration-move) ease-in both slide-y;
+}
+```
+
+## Directional Navigation
+
+### Single-Class Approach
+
+```css
+::view-transition-old(.nav-forward) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-forward) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+
+::view-transition-old(.nav-back) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-back) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+```
+
+### Separate Enter/Exit Classes
+
+```css
+::view-transition-new(.slide-from-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+
+::view-transition-new(.slide-from-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+```
+
+## Shared Element Morph
+
+```css
+::view-transition-group(.morph) {
+  animation-duration: var(--duration-move);
+}
+::view-transition-image-pair(.morph) {
+  animation-name: via-blur;
+}
+@keyframes via-blur {
+  30% { filter: blur(3px); }
+}
+```
+
+**Note:** Shared element transitions take raster snapshots. For text with significant size differences (e.g., `<h3>` → `<h1>`), the old snapshot gets scaled up, producing a visible ghost artifact. Use `text-morph` for text shared elements.
+
+## Text Morph
+
+Avoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:
+
+```css
+::view-transition-group(.text-morph) {
+  animation-duration: var(--duration-move);
+}
+::view-transition-old(.text-morph) {
+  display: none;
+}
+::view-transition-new(.text-morph) {
+  animation: none;
+  object-fit: none;
+  object-position: left top;
+}
+```
+
+## Scale
+
+```css
+::view-transition-old(.scale-out) {
+  animation: var(--duration-exit) ease-in scale-down;
+}
+::view-transition-new(.scale-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;
+}
+@keyframes scale-down {
+  from { transform: scale(1); opacity: 1; }
+  to { transform: scale(0.85); opacity: 0; }
+}
+@keyframes scale-up {
+  from { transform: scale(0.85); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+```
+
+## Persistent Element Isolation
+
+```css
+::view-transition-group(persistent-nav) {
+  animation: none;
+  z-index: 100;
+}
+```
+
+### Backdrop-Blur Workaround
+
+```css
+::view-transition-old(persistent-nav) { display: none; }
+::view-transition-new(persistent-nav) { animation: none; }
+```
+
+## Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(*),
+  ::view-transition-new(*),
+  ::view-transition-group(*) {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+```
+
+---
+
+# View Transitions in Next.js
+
+## Setup
+
+```js
+// next.config.js
+experimental: { viewTransition: true }
+```
+
+Wraps every `<Link>` navigation in `document.startViewTransition`. Use `default="none"` to prevent competing animations. Do **not** install `react@canary` — the App Router already bundles it.
+
+## Next.js Implementation Additions
+
+**After Step 2:** Enable the experimental flag.
+
+**Step 4:** Use `transitionTypes` on `<Link>` (if available — see availability note below):
+```tsx
+<Link href="/photo/1" transitionTypes={["nav-forward"]}>View</Link>
+<Link href="/" transitionTypes={["nav-back"]}>Back</Link>
+```
+
+**After Step 6:** For same-route dynamic segments, use `key` + `name` + `share` pattern.
+
+## Layout-Level ViewTransition
+
+Don't add a layout-level VT wrapping `{children}` if pages have their own VTs — nested VTs never fire enter/exit inside a parent VT, so page-level enter/exit will silently not work. Remove the layout VT entirely. A bare VT in layout works only if pages have no VTs of their own. Layouts persist across navigations — don't use type-keyed maps in layouts.
+
+## The `transitionTypes` Prop
+
+Works in Server Components, no wrapper needed:
+```tsx
+<Link href="/products/1" transitionTypes={['nav-forward']}>View</Link>
+```
+
+**Availability:** Requires `experimental.viewTransition: true`. Available in Next.js 15+ canary builds and Next.js 16+. If unavailable, use `startTransition` + `addTransitionType` + `router.push()`. To check: `grep -r "transitionTypes" node_modules/next/dist/`. Reserve manual `startTransition` for non-link interactions.
+
+## `loading.tsx` as Suspense Boundary
+
+Next.js `loading.tsx` files are implicit `<Suspense>` boundaries. Wrap the skeleton in `<ViewTransition exit="...">` in `loading.tsx`, and the content in `<ViewTransition enter="..." default="none">` in the page. This is the Next.js-idiomatic equivalent of explicit `<Suspense fallback={...}>`. Same rules apply: use simple string props (not type maps) since Suspense reveals fire without transition types.
+
+## Server-Side Filtering with `router.replace`
+
+For search/sort/filter that re-renders on the server (via URL params), use `startTransition` + `router.replace`. VTs activate because the update is inside `startTransition`. List items wrapped in `<ViewTransition key={item.id}>` animate reorder. This is the server-component alternative to the client-side `useDeferredValue` pattern.
+
+## Two-Layer Pattern (Directional + Suspense)
+
+Directional slides + Suspense reveals coexist because they fire at different moments. Place the directional VT in the **page component** (not layout):
+
+```tsx
+<ViewTransition
+  enter={{ "nav-forward": "slide-from-right", default: "none" }}
+  exit={{ "nav-forward": "slide-to-left", default: "none" }}
+  default="none"
+>
+  <div>
+    <Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+      <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+    </Suspense>
+  </div>
+</ViewTransition>
+```
+
+## Shared Elements Across Routes
+
+```tsx
+// List page
+<Link href={`/products/${product.id}`} transitionTypes={['nav-forward']}>
+  <ViewTransition name={`product-${product.id}`}>
+    <Image src={product.image} alt={product.name} width={400} height={300} />
+  </ViewTransition>
+</Link>
+
+// Detail page — same name
+<ViewTransition name={`product-${product.id}`}>
+  <Image src={product.image} alt={product.name} width={800} height={600} />
+</ViewTransition>
+```
+
+## Same-Route Dynamic Segment Transitions
+
+Page stays mounted on dynamic segment change — enter/exit never fire. Use `key` + `name` + `share`:
+
+```tsx
+<Suspense fallback={<Skeleton />}>
+  <ViewTransition key={slug} name={`collection-${slug}`} share="auto" default="none">
+    <Content slug={slug} />
+  </ViewTransition>
+</Suspense>
+```
+
+## Server Components
+
+- `<ViewTransition>` works in Server and Client Components
+- `<Link transitionTypes>` works in Server Components
+- `addTransitionType` and programmatic nav require Client Components
diff --git a/skills/vercel/react-view-transitions/README.md b/skills/vercel/react-view-transitions/README.md
new file mode 100644
index 0000000..9f29bed
--- /dev/null
+++ b/skills/vercel/react-view-transitions/README.md
@@ -0,0 +1,42 @@
+# React View Transitions Skill
+
+An agent skill for implementing smooth, native-feeling animations using React's View Transition API.
+
+## What This Skill Covers
+
+- **`<ViewTransition>` component** — animation triggers (enter, exit, update, share), placement rules, View Transition Classes
+- **`addTransitionType`** — tagging transitions for directional or context-specific animations
+- **Shared element transitions** — morphing elements across different views
+- **View Transition Events** — imperative JavaScript animations via the Web Animations API
+- **CSS pseudo-elements** — `::view-transition-old`, `::view-transition-new`, `::view-transition-group`
+- **Next.js integration** — `experimental.viewTransition`, the `transitionTypes` prop on `next/link`, App Router patterns
+- **Accessibility** — `prefers-reduced-motion` handling
+- **Ready-to-use CSS recipes** — fade, slide, scale, directional navigation
+
+## Skill Structure
+
+```
+react-view-transitions/
+├── SKILL.md                      # Core skill (always loaded)
+├── AGENTS.md                     # Full compiled document (all references expanded)
+└── references/
+    ├── implementation.md         # Step-by-step implementation workflow
+    ├── patterns.md               # Real-world patterns, events API, troubleshooting
+    ├── nextjs.md                 # Next.js-specific patterns
+    └── css-recipes.md            # Copy-paste CSS animations
+```
+
+## Installation
+
+Install via [skills.sh](https://skills.sh):
+
+```bash
+npx skills install https://github.com/vercel-labs/react-view-transitions-skill
+```
+
+## Resources
+
+- [React `<ViewTransition>` docs](https://react.dev/reference/react/ViewTransition)
+- [React `addTransitionType` docs](https://react.dev/reference/react/addTransitionType)
+- [Next.js `viewTransition` config](https://nextjs.org/docs/app/api-reference/config/next-config-js/viewTransition)
+- [Next.js App Router Playground (view transitions)](https://github.com/vercel/next-app-router-playground/tree/main/app/view-transitions) — Vercel's reference implementation
diff --git a/skills/vercel/react-view-transitions/SKILL.md b/skills/vercel/react-view-transitions/SKILL.md
new file mode 100644
index 0000000..dcecd8e
--- /dev/null
+++ b/skills/vercel/react-view-transitions/SKILL.md
@@ -0,0 +1,320 @@
+---
+name: vercel-react-view-transitions
+description: Guide for implementing smooth, native-feeling animations using React's View Transition API (`<ViewTransition>` component, `addTransitionType`, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, `startViewTransition`, `ViewTransition`, transition types, or asks about animating between UI states in React without third-party animation libraries.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# React View Transitions
+
+Animate between UI states using the browser's native `document.startViewTransition`. Declare *what* with `<ViewTransition>`, trigger *when* with `startTransition` / `useDeferredValue` / `Suspense`, control *how* with CSS classes. Unsupported browsers skip animations gracefully.
+
+## When to Animate
+
+Every `<ViewTransition>` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.
+
+Implement **all** applicable patterns from this list, in this order:
+
+| Priority | Pattern | What it communicates |
+|----------|---------|---------------------|
+| 1 | **Shared element** (`name`) | "Same thing — going deeper" |
+| 2 | **Suspense reveal** | "Data loaded" |
+| 3 | **List identity** (per-item `key`) | "Same items, new arrangement" |
+| 4 | **State change** (`enter`/`exit`) | "Something appeared/disappeared" |
+| 5 | **Route change** (layout-level) | "Going to a new place" |
+
+This is an implementation order, not a "pick one" list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.
+
+### Choosing Animation Style
+
+| Context | Animation | Why |
+|---------|-----------|-----|
+| Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth |
+| Lateral navigation (tab-to-tab) | Bare `<ViewTransition>` (fade) or `default="none"` | No depth to communicate |
+| Suspense reveal | `enter`/`exit` string props | Content arriving |
+| Revalidation / background refresh | `default="none"` | Silent — no animation needed |
+
+Reserve directional slides for hierarchical navigation (list → detail) and ordered sequences (prev/next photo, carousel, paginated results). For ordered sequences, the direction communicates position: "next" slides from right, "previous" from left. Lateral/unordered navigation (tab-to-tab) should not use directional slides — it falsely implies spatial depth.
+
+---
+
+## Availability
+
+- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
+- **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
+- Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
+
+---
+
+## Implementation Workflow
+
+When adding view transitions to an existing app, **follow `references/implementation.md` step by step.** Start with the audit — do not skip it. Copy the CSS recipes from `references/css-recipes.md` into the global stylesheet — do not write your own animation CSS.
+
+---
+
+## Core Concepts
+
+### The `<ViewTransition>` Component
+
+```jsx
+import { ViewTransition } from 'react';
+
+<ViewTransition>
+  <Component />
+</ViewTransition>
+```
+
+React auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself.
+
+### Animation Triggers
+
+| Trigger | When it fires |
+|---------|--------------|
+| **enter** | `<ViewTransition>` first inserted during a Transition |
+| **exit** | `<ViewTransition>` first removed during a Transition |
+| **update** | DOM mutations inside a `<ViewTransition>`. With nested VTs, mutation applies to the innermost one |
+| **share** | Named VT unmounts and another with same `name` mounts in the same Transition |
+
+Only `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate.
+
+### Critical Placement Rule
+
+`<ViewTransition>` only activates enter/exit if it appears **before any DOM nodes**:
+
+```jsx
+// Works
+<ViewTransition enter="auto" exit="auto">
+  <div>Content</div>
+</ViewTransition>
+
+// Broken — div wraps the VT, suppressing enter/exit
+<div>
+  <ViewTransition enter="auto" exit="auto">
+    <div>Content</div>
+  </ViewTransition>
+</div>
+```
+
+---
+
+## Styling with View Transition Classes
+
+### Props
+
+Values: `"auto"` (browser cross-fade), `"none"` (disabled), `"class-name"` (custom CSS), or `{ [type]: value }` for type-specific animations.
+
+```jsx
+<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
+```
+
+If `default` is `"none"`, all triggers are off unless explicitly listed.
+
+### CSS Pseudo-Elements
+
+- `::view-transition-old(.class)` — outgoing snapshot
+- `::view-transition-new(.class)` — incoming snapshot
+- `::view-transition-group(.class)` — container
+- `::view-transition-image-pair(.class)` — old + new pair
+
+See `references/css-recipes.md` for ready-to-use animation recipes.
+
+---
+
+## Transition Types
+
+Tag transitions with `addTransitionType` so VTs can pick different animations based on context. Call it multiple times to stack types — different VTs in the tree react to different types:
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  addTransitionType('select-item');
+  router.push('/detail/1');
+});
+```
+
+Pass an object to map types to CSS classes. Works on `enter`, `exit`, **and** `share`:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
+  exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
+  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
+  default="none"
+>
+  <Page />
+</ViewTransition>
+```
+
+`enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
+  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+  default="none"
+>
+```
+
+**TypeScript:** `ViewTransitionClassPerType` requires a `default` key in the object.
+
+For apps with multiple pages, extract the type-keyed VT into a reusable wrapper:
+
+```jsx
+export function DirectionalTransition({ children }: { children: React.ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+```
+
+### `router.back()` and Browser Back Button
+
+`router.back()` and the browser's back/forward buttons do **not** trigger view transitions (`popstate` is synchronous, incompatible with `startViewTransition`). Use `router.push()` with an explicit URL instead.
+
+### Types and Suspense
+
+Types are available during navigation but **not** during subsequent Suspense reveals (separate transitions, no type). Use type maps for page-level enter/exit; use simple string props for Suspense reveals.
+
+---
+
+## Shared Element Transitions
+
+Same `name` on two VTs — one unmounting, one mounting — creates a shared element morph:
+
+```jsx
+<ViewTransition name="hero-image">
+  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
+</ViewTransition>
+
+// On the other view — same name
+<ViewTransition name="hero-image">
+  <img src="/full.jpg" />
+</ViewTransition>
+```
+
+- Only one VT with a given `name` can be mounted at a time — use unique names (`photo-${id}`). Watch for reusable components: if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Either make the name conditional (via a prop) or move the named VT out of the shared component into the specific consumer.
+- `share` takes precedence over `enter`/`exit`. Think through each navigation path: when no matching pair forms (e.g., the target page doesn't have the same name), `enter`/`exit` fires instead. Consider whether the element needs a fallback animation for those paths.
+- Never use a fade-out exit on pages with shared morphs — use a directional slide instead.
+
+---
+
+## Common Patterns
+
+### Enter/Exit
+
+```jsx
+{show && (
+  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
+)}
+```
+
+### List Reorder
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
+))}
+```
+
+Trigger inside `startTransition`. Avoid wrapper `<div>`s between list and VT.
+
+### Composing Shared Elements with List Identity
+
+Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element (e.g., an image that morphs into a detail view), use two nested `<ViewTransition>` boundaries:
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}>                                      {/* list identity */}
+    <Link href={`/items/${item.id}`}>
+      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* shared element */}
+        <Image src={item.image} />
+      </ViewTransition>
+      <p>{item.name}</p>
+    </Link>
+  </ViewTransition>
+))}
+```
+
+The outer VT handles list reorder/enter animations. The inner VT handles the cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
+
+### Force Re-Enter with `key`
+
+```jsx
+<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
+  <ResultsGrid />
+</ViewTransition>
+```
+
+**Caution:** If wrapping `<Suspense>`, changing `key` remounts the boundary and refetches.
+
+### Suspense Fallback to Content
+
+Simple cross-fade:
+```jsx
+<ViewTransition>
+  <Suspense fallback={<Skeleton />}><Content /></Suspense>
+</ViewTransition>
+```
+
+Directional reveal:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+</Suspense>
+```
+
+For more patterns, see `references/patterns.md`.
+
+---
+
+## How Multiple VTs Interact
+
+Every VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions (navigation vs later Suspense resolve) don't compete.
+
+### Use `default="none"` Liberally
+
+Without it, every VT fires the browser cross-fade on **every** transition — Suspense resolves, `useDeferredValue` updates, background revalidations. Always use `default="none"` and explicitly enable only desired triggers.
+
+### Two Patterns Coexist
+
+**Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation.
+**Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type).
+
+They coexist because they fire at different moments. `default="none"` on both prevents cross-interference. Always pair `enter` with `exit`. Place directional VTs in page components, not layouts.
+
+### Nested VT Limitation
+
+When a parent VT exits, nested VTs inside it do **not** fire their own enter/exit — only the outermost VT animates. Per-item staggered animations during page navigation are not possible today. See [react#36135](https://github.com/facebook/react/pull/36135) for an experimental opt-in fix.
+
+---
+
+## Next.js Integration
+
+For Next.js setup (`experimental.viewTransition` flag, `transitionTypes` prop on `next/link`, App Router patterns, Server Components), see `references/nextjs.md`.
+
+---
+
+## Accessibility
+
+Always add the reduced motion CSS from `references/css-recipes.md` to your global stylesheet.
+
+---
+
+## Reference Files
+
+- **`references/implementation.md`** — Step-by-step implementation workflow.
+- **`references/patterns.md`** — Patterns, animation timing, events API, troubleshooting.
+- **`references/css-recipes.md`** — Ready-to-use CSS animation recipes.
+- **`references/nextjs.md`** — Next.js App Router patterns and Server Component details.
+
+## Full Compiled Document
+
+For the complete guide with all reference files expanded: `AGENTS.md`
diff --git a/skills/vercel/react-view-transitions/metadata.json b/skills/vercel/react-view-transitions/metadata.json
new file mode 100644
index 0000000..aabe3e1
--- /dev/null
+++ b/skills/vercel/react-view-transitions/metadata.json
@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "March 2026",
+  "abstract": "Guide for implementing smooth, native-feeling animations using React's View Transition API. Covers the <ViewTransition> component, addTransitionType, CSS view transition pseudo-elements, shared element transitions, JavaScript animations via Web Animations API, and Next.js integration including the transitionTypes prop on next/link. Includes ready-to-use CSS animation recipes and real-world patterns from production Next.js apps.",
+  "references": [
+    "https://react.dev/reference/react/ViewTransition",
+    "https://react.dev/reference/react/addTransitionType",
+    "https://nextjs.org/docs/app/api-reference/config/next-config-js/viewTransition",
+    "https://github.com/vercel/next-app-router-playground/tree/main/app/view-transitions"
+  ]
+}
diff --git a/skills/vercel/react-view-transitions/references/css-recipes.md b/skills/vercel/react-view-transitions/references/css-recipes.md
new file mode 100644
index 0000000..f9c1fca
--- /dev/null
+++ b/skills/vercel/react-view-transitions/references/css-recipes.md
@@ -0,0 +1,242 @@
+# CSS Animation Recipes
+
+Ready-to-use CSS for `<ViewTransition>` props. Copy into your global stylesheet.
+
+---
+
+## Timing Variables
+
+```css
+:root {
+  --duration-exit: 150ms;
+  --duration-enter: 210ms;
+  --duration-move: 400ms;
+}
+```
+
+### Shared Keyframes
+
+```css
+@keyframes fade {
+  from { filter: blur(3px); opacity: 0; }
+  to { filter: blur(0); opacity: 1; }
+}
+
+@keyframes slide {
+  from { translate: var(--slide-offset); }
+  to { translate: 0; }
+}
+
+@keyframes slide-y {
+  from { transform: translateY(var(--slide-y-offset, 10px)); }
+  to { transform: translateY(0); }
+}
+```
+
+---
+
+## Fade
+
+```css
+::view-transition-old(.fade-out) {
+  animation: var(--duration-exit) ease-in fade reverse;
+}
+::view-transition-new(.fade-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both fade;
+}
+```
+
+Usage: `<ViewTransition enter="fade-in" exit="fade-out" />`
+
+---
+
+## Slide (Vertical)
+
+```css
+::view-transition-old(.slide-down) {
+  animation:
+    var(--duration-exit) ease-out both fade reverse,
+    var(--duration-exit) ease-out both slide-y reverse;
+}
+::view-transition-new(.slide-up) {
+  animation:
+    var(--duration-enter) ease-in var(--duration-exit) both fade,
+    var(--duration-move) ease-in both slide-y;
+}
+```
+
+Usage:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition default="none" enter="slide-up"><Content /></ViewTransition>
+</Suspense>
+```
+
+---
+
+## Directional Navigation
+
+### Separate Enter/Exit Classes
+
+```css
+::view-transition-new(.slide-from-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+
+::view-transition-new(.slide-from-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+```
+
+### Single-Class Approach
+
+```css
+::view-transition-old(.nav-forward) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-forward) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+
+::view-transition-old(.nav-back) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-back) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+```
+
+---
+
+## Shared Element Morph
+
+```css
+::view-transition-group(.morph) {
+  animation-duration: var(--duration-move);
+}
+
+::view-transition-image-pair(.morph) {
+  animation-name: via-blur;
+}
+
+@keyframes via-blur {
+  30% { filter: blur(3px); }
+}
+```
+
+Usage: `<ViewTransition name={`product-${id}`} share="morph" />`
+
+**Note:** Shared element transitions take raster snapshots. For text with significant size differences (e.g., `<h3>` → `<h1>`), the old snapshot gets scaled up, producing a visible ghost artifact. Use `text-morph` for text shared elements.
+
+## Text Morph
+
+Avoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:
+
+```css
+::view-transition-group(.text-morph) {
+  animation-duration: var(--duration-move);
+}
+::view-transition-old(.text-morph) {
+  display: none;
+}
+::view-transition-new(.text-morph) {
+  animation: none;
+  object-fit: none;
+  object-position: left top;
+}
+```
+
+Usage: `<ViewTransition name={`title-${id}`} share="text-morph" />`
+
+---
+
+## Scale
+
+```css
+::view-transition-old(.scale-out) {
+  animation: var(--duration-exit) ease-in scale-down;
+}
+::view-transition-new(.scale-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;
+}
+
+@keyframes scale-down {
+  from { transform: scale(1); opacity: 1; }
+  to { transform: scale(0.85); opacity: 0; }
+}
+@keyframes scale-up {
+  from { transform: scale(0.85); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+```
+
+Usage: `<ViewTransition enter="scale-in" exit="scale-out" />`
+
+---
+
+## Persistent Element Isolation
+
+```css
+::view-transition-group(persistent-nav) {
+  animation: none;
+  z-index: 100;
+}
+```
+
+### Backdrop-Blur Workaround
+
+For elements with `backdrop-filter`, hide the old snapshot to avoid flash:
+
+```css
+::view-transition-old(persistent-nav) {
+  display: none;
+}
+::view-transition-new(persistent-nav) {
+  animation: none;
+}
+```
+
+---
+
+## Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(*),
+  ::view-transition-new(*),
+  ::view-transition-group(*) {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+```
diff --git a/skills/vercel/react-view-transitions/references/implementation.md b/skills/vercel/react-view-transitions/references/implementation.md
new file mode 100644
index 0000000..e4207c9
--- /dev/null
+++ b/skills/vercel/react-view-transitions/references/implementation.md
@@ -0,0 +1,182 @@
+# Implementation Workflow
+
+Follow these steps in order when adding view transitions to an app. Each step builds on the previous one.
+
+## Step 1: Audit the App
+
+Before writing any code, scan the codebase thoroughly. Search for:
+
+- **Every `<Link>` and `router.push`** — these are your navigation triggers. Open every file that contains one.
+- **Every `<Suspense>` boundary** — each one is a candidate for a reveal animation. Check what its fallback renders.
+- **Every page/route component** — list them all. Each page needs a VT placement decision.
+- **Persistent elements** — headers, navbars, sidebars, sticky controls that stay on screen across navigations. These need `viewTransitionName` isolation.
+- **Shared visual elements** — images, cards, or avatars that appear on both a source and target view (e.g., a thumbnail in a list and the same image on a detail page).
+- **Skeleton-to-content control pairs** — if a Suspense fallback renders a control (search input, tab bar) that also exists in the real content, both need a matching `viewTransitionName`.
+
+Then classify every navigation and produce a navigation map:
+
+```
+| Route           | Navigates to         | Direction    | VT pattern            |
+|-----------------|----------------------|--------------|-----------------------|
+| /               | /detail/[id]         | forward      | directional slide     |
+| /detail/[id]    | /                    | back         | directional slide     |
+| /detail/[id]    | /detail/[other]      | sequential   | directional slide (ordered prev/next) or key+share crossfade |
+| /tab/[a]        | /tab/[b]             | lateral      | key+share crossfade   |
+| (Suspense)      | (content loads)      | —            | slide-up reveal       |
+```
+
+For each shared element (`name` prop), note every navigation where a pair forms and where it doesn't — this determines whether you need `enter`/`exit` as a fallback alongside `share`.
+
+## Step 2: Add CSS Recipes
+
+Copy the **complete** CSS recipe set from `css-recipes.md` into your global stylesheet. This includes timing variables, shared keyframes, fade, slide (vertical), directional navigation (forward/back), shared element morph, persistent element isolation, and reduced motion.
+
+Do not write your own animation CSS — the recipes handle staggered timing, motion blur on morphs, and reduced motion that are easy to get wrong. You can customize timing variables (`--duration-exit`, `--duration-enter`, `--duration-move`) after the initial setup.
+
+## Step 3: Isolate Persistent Elements
+
+For every persistent element identified in Step 1, add a `viewTransitionName` style to pull it out of the page content's transition snapshot:
+
+```jsx
+<header style={{ viewTransitionName: "site-header" }}>...</header>
+```
+
+Then add the persistent element isolation CSS from `css-recipes.md` (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the backdrop-blur workaround from `css-recipes.md` instead.
+
+If a Suspense fallback mirrors a persistent control (e.g., a skeleton search input), give both the real control and the skeleton the same `viewTransitionName` so they morph in place.
+
+## Step 4: Add Directional Page Transitions
+
+For hierarchical navigations identified in Step 1, tag the navigation direction using `addTransitionType` inside `startTransition`:
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  router.push('/detail/1');
+});
+```
+
+Then wrap each **page component** (not layout) in a type-keyed `<ViewTransition>`:
+
+```jsx
+<ViewTransition
+  enter={{
+    "nav-forward": "nav-forward",
+    "nav-back": "nav-back",
+    default: "none",
+  }}
+  exit={{
+    "nav-forward": "nav-forward",
+    "nav-back": "nav-back",
+    default: "none",
+  }}
+  default="none"
+>
+  <div>...page content...</div>
+</ViewTransition>
+```
+
+The `nav-forward` and `nav-back` CSS classes from `css-recipes.md` produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
+
+Extract this into a reusable component so every page doesn't repeat the verbose type map:
+
+```jsx
+export function DirectionalTransition({ children }: { children: React.ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+```
+
+This also becomes the single place to adjust if you add new transition types later.
+
+**Rules:**
+- Always pair `enter` with `exit` — without an exit animation, the old page disappears instantly while the new one animates in.
+- Always include `default: "none"` in type map objects and `default="none"` on the component — otherwise it fires on every transition.
+- Place the directional `<ViewTransition>` in each page component, not in a layout. Layouts persist across navigations and never trigger enter/exit.
+- Only use directional slides for hierarchical navigation or ordered sequences (prev/next). Lateral/sibling navigation (tab-to-tab) should use a bare `<ViewTransition>` (cross-fade) or `default="none"`.
+
+## Step 5: Add Suspense Reveals
+
+For every `<Suspense>` boundary identified in Step 1, wrap the fallback and content in separate `<ViewTransition>`s:
+
+```jsx
+<Suspense
+  fallback={
+    <ViewTransition exit="slide-down">
+      <Skeleton />
+    </ViewTransition>
+  }
+>
+  <ViewTransition enter="slide-up" default="none">
+    <AsyncContent />
+  </ViewTransition>
+</Suspense>
+```
+
+This example uses `slide-down` / `slide-up` for directional vertical motion. For a simpler reveal, a bare `<ViewTransition>` around the `<Suspense>` gives a cross-fade with zero configuration. Choose based on the spatial meaning — consult the "Choosing the Right Animation Style" table in the main skill file.
+
+**Rules:**
+- Always use `default="none"` on the content `<ViewTransition>` to prevent re-animation on revalidation or unrelated transitions.
+- Use simple string props (not type maps) on Suspense `<ViewTransition>`s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.
+
+## Step 6: Add Shared Element Transitions
+
+For every shared visual element identified in Step 1, add matching named `<ViewTransition>` wrappers on both the source and target views:
+
+```jsx
+// On the source view (e.g., list/grid page)
+<ViewTransition name={`photo-${photo.id}`} share="morph" default="none">
+  <Image src={photo.src} ... />
+</ViewTransition>
+
+// On the target view (e.g., detail page) — same name
+<ViewTransition name={`photo-${photo.id}`} share="morph">
+  <Image src={photo.src} ... />
+</ViewTransition>
+```
+
+The `share="morph"` class uses the morph recipe from `css-recipes.md` (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
+
+When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — see "Composing Shared Elements with List Identity" in `SKILL.md`.
+
+**Rules:**
+- Names must be globally unique — use prefixes like `photo-${id}`.
+- Add `default="none"` on list-side shared elements to prevent per-item cross-fades on filter/search updates.
+
+## Step 7: Verify Each Navigation Path
+
+Walk through every row in the navigation map from Step 1 and confirm:
+
+- Does the VT mount/unmount on this navigation, or does it stay mounted (same-route)?
+- For named VTs: does a shared pair form? If not, does `enter`/`exit` provide a fallback?
+- Does `default="none"` block an animation you actually want?
+- Do persistent elements stay static (not sliding with page content)?
+- Do Suspense reveals animate independently from directional navigations?
+
+If any path produces no animation or competing animations, revisit the relevant step.
+
+---
+
+## Common Mistakes
+
+- **Bare `<ViewTransition>` without props** — without `default="none"`, it fires the browser's default cross-fade on every transition (every navigation, every Suspense resolve, every revalidation). Always set `default="none"` and explicitly enable only the triggers you want.
+- **Directional `<ViewTransition>` in a layout** — layouts persist across navigations and never unmount/remount. `enter`/`exit` props won't fire on route changes. Place the outer type-keyed `<ViewTransition>` in each page component.
+- **Fade-out exit with shared element morphs** — the page dissolving conflicts with the morph. Use a directional slide exit instead.
+- **Writing custom animation CSS** — the recipes in `css-recipes.md` handle staggered timing, motion blur on morphs, and reduced motion. Copy them; don't reinvent them.
+- **Missing `default: "none"` in type-keyed objects** — TypeScript requires a `default` key, and without it the fallback is `"auto"` which fires on every transition.
+- **Type maps on Suspense reveals** — Suspense resolves fire as separate transitions with no type. Type-keyed props won't match — use simple string props instead.
+- **Raw `viewTransitionName` CSS to trigger animations** — React only calls `document.startViewTransition` when `<ViewTransition>` components are in the tree. A bare `viewTransitionName` style is for isolating elements from a parent's snapshot, not for triggering animations.
+- **`update` trigger for same-route navigations** — nested VTs inside the content steal the mutation from the parent, so `update` never fires on the outer VT. Use `key` + `name` + `share` instead.
+- **Named VT in a reusable component** — if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Make the name conditional or move it to the specific consumer.
+- **`router.back()` for back navigation** — `router.back()` triggers synchronous `popstate`, incompatible with view transitions. Use `router.push()` with an explicit URL.
+
+---
+
+For Next.js-specific implementation steps (config flag, `transitionTypes` on `<Link>`, same-route dynamic segments), see `nextjs.md`.
diff --git a/skills/vercel/react-view-transitions/references/nextjs.md b/skills/vercel/react-view-transitions/references/nextjs.md
new file mode 100644
index 0000000..06a96c7
--- /dev/null
+++ b/skills/vercel/react-view-transitions/references/nextjs.md
@@ -0,0 +1,176 @@
+# View Transitions in Next.js
+
+## Setup
+
+`<ViewTransition>` works out of the box for `startTransition`/`Suspense` updates. To also animate `<Link>` navigations:
+
+```js
+// next.config.js
+const nextConfig = {
+  experimental: { viewTransition: true },
+};
+module.exports = nextConfig;
+```
+
+This wraps every `<Link>` navigation in `document.startViewTransition`. Any VT with `default="auto"` fires on **every** link click — use `default="none"` to prevent competing animations.
+
+Do **not** install `react@canary` — see SKILL.md "Availability" for details.
+
+---
+
+## Next.js Implementation Additions
+
+When following `implementation.md`, apply these additions:
+
+**After Step 2:** Enable the experimental flag above.
+
+**Step 4:** Use `transitionTypes` on `<Link>` — see "The `transitionTypes` Prop" section below for usage and availability.
+
+**After Step 6:** For same-route dynamic segments (e.g., `/collection/[slug]`), use the `key` + `name` + `share` pattern — see Same-Route Dynamic Segment Transitions below.
+
+---
+
+## Layout-Level ViewTransition
+
+**Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** Nested VTs never fire enter/exit when inside a parent VT — page-level enter/exit will silently not work. Remove the layout VT entirely.
+
+A bare `<ViewTransition>` in layout works only if pages have **no** VTs of their own.
+
+**Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts.
+
+---
+
+## The `transitionTypes` Prop on `next/link`
+
+No wrapper component needed, works in Server Components:
+
+```tsx
+<Link href="/products/1" transitionTypes={['transition-to-detail']}>View Product</Link>
+```
+
+Replaces the manual pattern of `onNavigate` + `startTransition` + `addTransitionType` + `router.push()`. Reserve manual `startTransition` for non-link interactions (buttons, forms).
+
+**Availability:** `transitionTypes` requires `experimental.viewTransition: true` and is available in Next.js 15+ canary builds and Next.js 16+. If unavailable, use `startTransition` + `addTransitionType` + `router.push()` (see Programmatic Navigation below). To check: `grep -r "transitionTypes" node_modules/next/dist/` — if no results, fall back to programmatic navigation.
+
+---
+
+## Programmatic Navigation
+
+```tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { startTransition, addTransitionType } from 'react';
+
+function handleNavigate(href: string) {
+  const router = useRouter();
+  startTransition(() => {
+    addTransitionType('nav-forward');
+    router.push(href);
+  });
+}
+```
+
+---
+
+## Server-Side Filtering with `router.replace`
+
+For search/sort/filter that re-renders on the server (via URL params), use `startTransition` + `router.replace`. VTs activate because the state update is inside `startTransition`:
+
+```tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { startTransition } from 'react';
+
+function handleSort(sort: string) {
+  const router = useRouter();
+  startTransition(() => {
+    router.replace(`?sort=${sort}`);
+  });
+}
+```
+
+List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side `useDeferredValue` pattern in `patterns.md`.
+
+---
+
+## Two-Layer Pattern (Directional + Suspense)
+
+Directional slides + Suspense reveals coexist because they fire at different moments. Place the directional VT in the **page component** (not layout):
+
+```tsx
+<ViewTransition
+  enter={{ "nav-forward": "slide-from-right", default: "none" }}
+  exit={{ "nav-forward": "slide-to-left", default: "none" }}
+  default="none"
+>
+  <div>
+    <Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+      <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+    </Suspense>
+  </div>
+</ViewTransition>
+```
+
+---
+
+## `loading.tsx` as Suspense Boundary
+
+Next.js `loading.tsx` is an implicit `<Suspense>` boundary. Wrap the skeleton in `<ViewTransition exit="...">` in `loading.tsx`, and the content in `<ViewTransition enter="..." default="none">` in the page:
+
+```tsx
+// loading.tsx
+<ViewTransition exit="slide-down"><PhotoGridSkeleton /></ViewTransition>
+
+// page.tsx
+<ViewTransition enter="slide-up" default="none"><PhotoGrid photos={photos} /></ViewTransition>
+```
+
+Same rules as explicit `<Suspense>`: use simple string props (not type maps) since Suspense reveals fire without transition types.
+
+---
+
+## Shared Elements Across Routes
+
+```tsx
+// List page
+{products.map((product) => (
+  <Link key={product.id} href={`/products/${product.id}`} transitionTypes={['nav-forward']}>
+    <ViewTransition name={`product-${product.id}`}>
+      <Image src={product.image} alt={product.name} width={400} height={300} />
+    </ViewTransition>
+  </Link>
+))}
+
+// Detail page — same name
+<ViewTransition name={`product-${product.id}`}>
+  <Image src={product.image} alt={product.name} width={800} height={600} />
+</ViewTransition>
+```
+
+---
+
+## Same-Route Dynamic Segment Transitions
+
+When navigating between dynamic segments of the same route (e.g., `/collection/[slug]`), the page stays mounted — enter/exit never fire. Use `key` + `name` + `share`:
+
+```tsx
+<Suspense fallback={<Skeleton />}>
+  <ViewTransition key={slug} name={`collection-${slug}`} share="auto" default="none">
+    <Content slug={slug} />
+  </ViewTransition>
+</Suspense>
+```
+
+- `key={slug}` forces unmount/remount on change
+- `name` + `share="auto"` creates a shared element crossfade
+- VT inside `<Suspense>` (without keying Suspense) keeps old content visible during loading
+
+---
+
+## Server Components
+
+- `<ViewTransition>` works in both Server and Client Components
+- `<Link transitionTypes>` works in Server Components — no `'use client'` needed
+- `addTransitionType` and `startTransition` for programmatic nav require Client Components
diff --git a/skills/vercel/react-view-transitions/references/patterns.md b/skills/vercel/react-view-transitions/references/patterns.md
new file mode 100644
index 0000000..6919ea4
--- /dev/null
+++ b/skills/vercel/react-view-transitions/references/patterns.md
@@ -0,0 +1,262 @@
+# Patterns and Guidelines
+
+## Searchable Grid with `useDeferredValue`
+
+`useDeferredValue` makes filter updates a transition, activating `<ViewTransition>`:
+
+```tsx
+'use client';
+
+import { useDeferredValue, useState, ViewTransition, Suspense } from 'react';
+
+export default function SearchableGrid({ itemsPromise }) {
+  const [search, setSearch] = useState('');
+  const deferredSearch = useDeferredValue(search);
+
+  return (
+    <>
+      <input value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
+      <ViewTransition>
+        <Suspense fallback={<GridSkeleton />}>
+          <ItemGrid itemsPromise={itemsPromise} search={deferredSearch} />
+        </Suspense>
+      </ViewTransition>
+    </>
+  );
+}
+```
+
+Per-item `<ViewTransition name={...}>` inside a deferred list triggers cross-fades on every keystroke. Fix with `default="none"`:
+
+```tsx
+{filteredItems.map(item => (
+  <ViewTransition key={item.id} name={`item-${item.id}`} share="morph" default="none">
+    <ItemCard item={item} />
+  </ViewTransition>
+))}
+```
+
+## Card Expand/Collapse with `startTransition`
+
+Toggle between grid and detail view with shared element morph:
+
+```tsx
+'use client';
+
+import { useState, useRef, startTransition, ViewTransition } from 'react';
+
+export default function ItemGrid({ items }) {
+  const [expandedId, setExpandedId] = useState(null);
+  const scrollRef = useRef(0);
+
+  return expandedId ? (
+    <ViewTransition enter="slide-in" name={`item-${expandedId}`}>
+      <ItemDetail
+        item={items.find(i => i.id === expandedId)}
+        onClose={() => {
+          startTransition(() => {
+            setExpandedId(null);
+            setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);
+          });
+        }}
+      />
+    </ViewTransition>
+  ) : (
+    <div className="grid grid-cols-3 gap-4">
+      {items.map(item => (
+        <ViewTransition key={item.id} name={`item-${item.id}`}>
+          <ItemCard
+            item={item}
+            onSelect={() => {
+              scrollRef.current = window.scrollY;
+              startTransition(() => setExpandedId(item.id));
+            }}
+          />
+        </ViewTransition>
+      ))}
+    </div>
+  );
+}
+```
+
+## Type-Safe Transition Helpers
+
+Use `as const` arrays and derived types to prevent ID clashes:
+
+```tsx
+const transitionTypes = ['default', 'transition-to-detail', 'transition-to-list'] as const;
+const animationTypes = ['auto', 'none', 'animate-slide-from-left', 'animate-slide-from-right'] as const;
+
+type TransitionType = (typeof transitionTypes)[number];
+type AnimationType = (typeof animationTypes)[number];
+type TransitionMap = { default: AnimationType } & Partial<Record<Exclude<TransitionType, 'default'>, AnimationType>>;
+
+export function HorizontalTransition({ children, enter, exit }: {
+  children: React.ReactNode;
+  enter: TransitionMap;
+  exit: TransitionMap;
+}) {
+  return <ViewTransition enter={enter} exit={exit}>{children}</ViewTransition>;
+}
+```
+
+## Cross-Fade Without Remount
+
+Omit `key` to trigger an update (cross-fade) instead of exit + enter. Avoids Suspense remount/refetch:
+
+```jsx
+<ViewTransition>
+  <TabPanel tab={activeTab} />
+</ViewTransition>
+```
+
+Use `key` when content identity changes (state resets). Omit for cross-fades (tabs, panels, carousel).
+
+## Isolate Elements from Parent Animations
+
+### Persistent Layout Elements
+
+Persistent elements (headers, navbars, sidebars) get captured in the page's transition snapshot. Fix with `viewTransitionName`:
+
+```jsx
+<nav style={{ viewTransitionName: "persistent-nav" }}>{/* ... */}</nav>
+```
+
+Then add the persistent element isolation CSS from `css-recipes.md`. For `backdrop-blur`/`backdrop-filter`, use the backdrop-blur workaround from `css-recipes.md`.
+
+### Floating Elements
+
+Give popovers/tooltips their own `viewTransitionName`:
+
+```jsx
+<SelectPopover style={{ viewTransitionName: 'popover' }}>{options}</SelectPopover>
+```
+
+Global fix: see persistent element isolation in `css-recipes.md`.
+
+## Shared Controls Between Skeleton and Content
+
+Give matching controls in fallback and content the same `viewTransitionName`:
+
+```jsx
+// Fallback
+<input disabled placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />
+// Content
+<input placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />
+```
+
+Don't put manual `viewTransitionName` on the root DOM node inside `<ViewTransition>` — React's auto-generated name overrides it.
+
+## Reusable Animated Collapse
+
+```jsx
+function AnimatedCollapse({ open, children }) {
+  if (!open) return null;
+  return (
+    <ViewTransition enter="expand-in" exit="collapse-out">
+      {children}
+    </ViewTransition>
+  );
+}
+
+// Usage: toggle with startTransition
+<button onClick={() => startTransition(() => setOpen(o => !o))}>Toggle</button>
+<AnimatedCollapse open={open}><SectionContent /></AnimatedCollapse>
+```
+
+## Preserve State with Activity
+
+```jsx
+<Activity mode={isVisible ? 'visible' : 'hidden'}>
+  <ViewTransition enter="slide-in" exit="slide-out">
+    <Sidebar />
+  </ViewTransition>
+</Activity>
+```
+
+## Exclude Elements with `useOptimistic`
+
+`useOptimistic` values update before the transition snapshot, excluding them from animation. Use for controls (labels); use committed state for animated content:
+
+```tsx
+const [sort, setSort] = useState('newest');
+const [optimisticSort, setOptimisticSort] = useOptimistic(sort);
+
+function cycleSort() {
+  const nextSort = getNextSort(optimisticSort);
+  startTransition(() => {
+    setOptimisticSort(nextSort);  // before snapshot — no animation
+    setSort(nextSort);            // between snapshots — animates
+  });
+}
+
+<button>Sort: {LABELS[optimisticSort]}</button>
+{items.sort(comparators[sort]).map(item => (
+  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
+))}
+```
+
+---
+
+## View Transition Events
+
+Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Always return a cleanup function. `onShare` takes precedence over `onEnter`/`onExit`.
+
+```jsx
+<ViewTransition
+  onEnter={(instance, types) => {
+    const anim = instance.new.animate(
+      [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
+      { duration: 300, easing: 'ease-out' }
+    );
+    return () => anim.cancel();
+  }}
+>
+  <Component />
+</ViewTransition>
+```
+
+The `instance` object: `instance.old`, `instance.new`, `instance.group`, `instance.imagePair`, `instance.name`.
+
+The `types` array (second argument) lets you vary animation based on transition type.
+
+---
+
+## Animation Timing
+
+| Interaction | Duration |
+|------------|----------|
+| Direct toggle (expand/collapse) | 100–200ms |
+| Route transition (slide) | 150–250ms |
+| Suspense reveal (skeleton → content) | 200–400ms |
+| Shared element morph | 300–500ms |
+
+---
+
+## Troubleshooting
+
+**VT not activating:** Ensure `<ViewTransition>` comes before any DOM node. Ensure state update is inside `startTransition`.
+
+**"Two ViewTransition components with the same name":** Names must be globally unique. Use IDs: `name={`hero-${item.id}`}`.
+
+**`router.back()` and browser back/forward skip animation:** Use `router.push()` with an explicit URL instead. See SKILL.md "router.back() and Browser Back Button."
+
+**`flushSync` skips animations:** Use `startTransition` instead.
+
+**Only updates animate (no enter/exit):** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.
+
+**Layout VT prevents page VTs from animating:** Nested VTs never fire enter/exit inside a parent VT. If your layout has a VT wrapping `{children}`, page-level enter/exit will silently not work. Remove the layout VT.
+
+**List reorder not animating with `useOptimistic`:** Optimistic values resolve before snapshot. Use committed state for list order.
+
+**TS error "Property 'default' is missing":** Type-keyed objects require a `default` key.
+
+**Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
+
+**Backdrop-blur flickers:** Use the backdrop-blur workaround from `css-recipes.md`.
+
+**`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
+
+**Skeleton controls slide away:** Give matching controls the same `viewTransitionName`.
+
+**Batching:** Multiple updates during animation are batched. A→B→C→D becomes B→D.
diff --git a/skills/vercel/vercel-cli-with-tokens/SKILL.md b/skills/vercel/vercel-cli-with-tokens/SKILL.md
new file mode 100644
index 0000000..814423d
--- /dev/null
+++ b/skills/vercel/vercel-cli-with-tokens/SKILL.md
@@ -0,0 +1,353 @@
+---
+name: vercel-cli-with-tokens
+description: Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel CLI with Tokens
+
+Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.
+
+## Step 1: Locate the Vercel Token
+
+Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
+
+### A) `VERCEL_TOKEN` is already set in the environment
+
+```bash
+printenv VERCEL_TOKEN
+```
+
+If this returns a value, you're ready. Skip to Step 2.
+
+### B) Token is in a `.env` file under `VERCEL_TOKEN`
+
+```bash
+grep '^VERCEL_TOKEN=' .env 2>/dev/null
+```
+
+If found, export it:
+
+```bash
+export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
+```
+
+### C) Token is in a `.env` file under a different name
+
+Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):
+
+```bash
+grep -i 'vercel' .env 2>/dev/null
+```
+
+Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:
+
+```bash
+export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
+```
+
+### D) No token found — ask the user
+
+If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
+
+---
+
+**Important:** Once `VERCEL_TOKEN` is exported as an environment variable, the Vercel CLI reads it natively — **do not pass it as a `--token` flag**. Putting secrets in command-line arguments exposes them in shell history and process listings.
+
+```bash
+# Bad — token visible in shell history and process listings
+vercel deploy --token "vca_abc123"
+
+# Good — CLI reads VERCEL_TOKEN from the environment
+export VERCEL_TOKEN="vca_abc123"
+vercel deploy
+```
+
+## Step 2: Locate the Project and Team
+
+Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.
+
+```bash
+# Check environment
+printenv VERCEL_PROJECT_ID
+printenv VERCEL_ORG_ID
+
+# Or check .env
+grep -i 'vercel' .env 2>/dev/null
+```
+
+**If you have a project URL** (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:
+
+```bash
+# e.g. "my-team" from "https://vercel.com/my-team/my-project"
+echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
+```
+
+**If you have both `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` in your environment**, export them — the CLI will use these automatically and skip any `.vercel/` directory:
+
+```bash
+export VERCEL_ORG_ID="<org-id>"
+export VERCEL_PROJECT_ID="<project-id>"
+```
+
+Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.
+
+## CLI Setup
+
+Ensure the Vercel CLI is installed and up to date:
+
+```bash
+npm install -g vercel
+vercel --version
+```
+
+## Deploying a Project
+
+Always deploy as **preview** unless the user explicitly requests production. Choose a method based on what you have available.
+
+### Quick Deploy (have project ID — no linking needed)
+
+When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:
+
+```bash
+vercel deploy -y --no-wait
+```
+
+With a team scope (either via `VERCEL_ORG_ID` or `--scope`):
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Production (only when explicitly requested):
+
+```bash
+vercel deploy --prod --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Full Deploy Flow (no project ID — need to link)
+
+Use this when you have a token and team but no pre-existing project ID.
+
+#### Check project state first
+
+```bash
+# Does the project have a git remote?
+git remote get-url origin 2>/dev/null
+
+# Is it already linked to a Vercel project?
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+```
+
+#### Link the project
+
+**With git remote (preferred):**
+
+```bash
+vercel link --repo --scope <team-slug> -y
+```
+
+Reads the git remote and connects to the matching Vercel project. Creates `.vercel/repo.json`. More reliable than plain `vercel link`, which matches by directory name.
+
+**Without git remote:**
+
+```bash
+vercel link --scope <team-slug> -y
+```
+
+Creates `.vercel/project.json`.
+
+**Link to a specific project by name:**
+
+```bash
+vercel link --project <project-name> --scope <team-slug> -y
+```
+
+If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.
+
+#### Deploy after linking
+
+**A) Git Push Deploy — has git remote (preferred)**
+
+Git pushes trigger automatic Vercel deployments.
+
+1. **Ask the user before pushing.** Never push without explicit approval.
+2. Commit and push:
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+3. Vercel builds automatically. Non-production branches get preview deployments.
+4. Retrieve the deployment URL:
+   ```bash
+   sleep 5
+   vercel ls --format json --scope <team-slug>
+   ```
+   Find the latest entry in the `deployments` array.
+
+**B) CLI Deploy — no git remote**
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Deploying from a Remote Repository (code not cloned locally)
+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url>
+   cd <repo-name>
+   ```
+2. Link to Vercel:
+   ```bash
+   vercel link --repo --scope <team-slug> -y
+   ```
+3. Deploy via git push (if you have push access) or CLI deploy.
+
+### About `.vercel/` Directory
+
+A linked project has either:
+- `.vercel/project.json` — from `vercel link`. Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — from `vercel link --repo`. Contains `orgId`, `remoteName`, and a `projects` map.
+
+Not needed when `VERCEL_ORG_ID` + `VERCEL_PROJECT_ID` are both set in the environment.
+
+**Do NOT** run `vercel project inspect` or `vercel link` in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. `vercel ls` is safe (in an unlinked directory it defaults to showing all deployments for the scope). `vercel whoami` is safe anywhere.
+
+## Managing Environment Variables
+
+```bash
+# Set for all environments
+echo "value" | vercel env add VAR_NAME --scope <team-slug>
+
+# Set for a specific environment (production, preview, development)
+echo "value" | vercel env add VAR_NAME production --scope <team-slug>
+
+# List environment variables
+vercel env ls --scope <team-slug>
+
+# Pull env vars to local .env.local file
+vercel env pull --scope <team-slug>
+
+# Remove a variable
+vercel env rm VAR_NAME --scope <team-slug> -y
+```
+
+## Inspecting Deployments
+
+```bash
+# List recent deployments
+vercel ls --format json --scope <team-slug>
+
+# Inspect a specific deployment
+vercel inspect <deployment-url>
+
+# View build logs (requires Vercel CLI v35+)
+vercel inspect <deployment-url> --logs
+
+# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
+vercel logs <deployment-url>
+```
+
+## Managing Domains
+
+```bash
+# List domains
+vercel domains ls --scope <team-slug>
+
+# Add a domain to the project — linked or env-linked directory (1 arg)
+vercel domains add <domain> --scope <team-slug>
+
+# Add a domain — unlinked directory (requires <project> positional)
+vercel domains add <domain> <project> --scope <team-slug>
+```
+
+## Stripe Projects Plan Changes
+
+If this project is managed by Stripe Projects. **Ask the user before running any paid or destructive plan change** — upgrades bill a real card, downgrades remove seats.
+
+First run `stripe projects status --json` to confirm the Vercel resource's local name. The examples below assume the default (`vercel-plan`); substitute the actual name if it was renamed at `stripe projects add` time.
+
+- **Upgrade to Pro:** `stripe projects add vercel/pro` (or `stripe projects upgrade vercel-plan pro`)
+- **Downgrade to Hobby:** `stripe projects downgrade vercel-plan hobby`
+
+### What Pro gives you
+
+- $20/month platform fee, includes $20/month of usage credit.
+- Turbo build machines (30 vCPUs, 60 GB memory) by default for new projects — significantly faster builds than Hobby.
+- 1 deploying seat + unlimited free Viewer seats (read-only collaborators, preview comments).
+- Higher included allocations (1 TB Fast Data Transfer, 10M Edge Requests per month).
+- Paid add-ons available: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.
+
+Full details: https://vercel.com/docs/plans/pro-plan
+
+## Working Agreement
+
+- **Never pass `VERCEL_TOKEN` as a `--token` flag.** Export it as an environment variable and let the CLI read it natively.
+- **Check the environment for tokens before asking the user.** Look in the current env and `.env` files first.
+- **Default to preview deployments.** Only deploy to production when explicitly asked.
+- **Ask before pushing to git.** Never push commits without the user's approval.
+- **Do not modify `.vercel/` files directly.** The CLI manages this directory. Reading them (e.g. to verify `orgId`) is fine.
+- **Do not curl/fetch deployed URLs to verify.** Just return the link to the user.
+- **Use `--format json`** when structured output will help with follow-up steps.
+- **Use `-y`** on commands that prompt for confirmation to avoid interactive blocking.
+
+## Troubleshooting
+
+### Token not found
+
+Check the environment and any `.env` files present:
+
+```bash
+printenv | grep -i vercel
+grep -i vercel .env 2>/dev/null
+```
+
+### Authentication error
+
+If the CLI fails with `Authentication required`:
+- The token may be expired or invalid.
+- Verify: `vercel whoami` (uses `VERCEL_TOKEN` from environment).
+- Ask the user for a fresh token.
+
+### Wrong team
+
+Verify the scope is correct:
+
+```bash
+vercel whoami --scope <team-slug>
+```
+
+### Build failure
+
+Check the build logs:
+
+```bash
+vercel inspect <deployment-url> --logs
+```
+
+Common causes:
+- Missing dependencies — ensure `package.json` is complete and committed.
+- Missing environment variables — add with `vercel env add`.
+- Framework misconfiguration — check `vercel.json`. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from `package.json`; override with `vercel.json` if detection is wrong.
+
+### CLI not installed
+
+```bash
+npm install -g vercel
+```
diff --git a/skills/vercel/vercel-optimize/AGENTS.md b/skills/vercel/vercel-optimize/AGENTS.md
new file mode 100644
index 0000000..224505b
--- /dev/null
+++ b/skills/vercel/vercel-optimize/AGENTS.md
@@ -0,0 +1,48 @@
+# vercel-optimize
+
+Cross-agent entry point for the Vercel Optimize skill. The full procedure is in [SKILL.md](./SKILL.md).
+
+Use this skill when the user asks to optimize a Vercel project, reduce a Vercel bill, investigate slow or expensive routes, find caching opportunities, reduce function invocations, or produce a Vercel cost/performance report.
+
+Do not use it for projects that are not deployed on Vercel, greenfield projects with no traffic, or general code review.
+
+## Requirements
+
+- Node.js 20+
+- Vercel CLI with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api` support; v53+ is this skill's compatibility floor
+- Authenticated Vercel CLI session
+- Linked Vercel project directory (`vercel link`) for route metrics. `VERCEL_PROJECT_ID` can help resolve project config, but it does not replace directory linkage for `vercel metrics`. The project must resolve to a CLI-safe team or personal scope so `vercel metrics`, `vercel usage`, and `vercel contract` all run against the same account.
+- Observability Plus for per-route metric analysis
+
+## Procedure
+
+1. Read [SKILL.md](./SKILL.md).
+2. Collect Vercel signals before reading source files.
+3. Gate candidates with deterministic scripts.
+4. Investigate only files named by launched candidates.
+5. Verify recommendations mechanically before rendering the report.
+
+The hard rules are in [references/doctrine.md](./references/doctrine.md): observability first, deterministic gates, candidate-bound scope, and version-aware citations.
+
+## Install
+
+Preferred:
+
+```bash
+npx skills add vercel-labs/agent-skills --skill vercel-optimize
+```
+
+Manual project install:
+
+```bash
+mkdir -p .agents/skills
+cp -R <agent-skills-repo>/skills/vercel-optimize .agents/skills/
+```
+
+Then add this to the project `AGENTS.md`:
+
+```md
+When optimizing Vercel cost or performance, follow
+`.agents/skills/vercel-optimize/SKILL.md` before proposing changes.
+Collect Vercel metrics before reading source files.
+```
diff --git a/skills/vercel/vercel-optimize/CONTRIBUTING.md b/skills/vercel/vercel-optimize/CONTRIBUTING.md
new file mode 100644
index 0000000..361b5bc
--- /dev/null
+++ b/skills/vercel/vercel-optimize/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing to `vercel-optimize`
+
+Keep changes small, metric-grounded, and fixture-tested. Runtime code lives in `skills/vercel-optimize`; tests and fixtures live in `packages/vercel-optimize-tests` so installed skills stay small.
+
+## Common changes
+
+| Change | Edit | Test |
+|---|---|---|
+| Gate | `lib/gates/<id>.mjs`, `lib/gates/index.mjs` | `node --test packages/vercel-optimize-tests/test/*gate*.test.mjs` |
+| Scanner | `lib/scanners/<id>.mjs`, `lib/scanners/index.mjs` | Scanner-specific test in `packages/vercel-optimize-tests/test/` |
+| Citation | `references/docs-library.json` | `node skills/vercel-optimize/scripts/check-citations.mjs` |
+| Support topic | `references/support-topics/<id>.md` | `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs` |
+| Playbook | `references/playbooks/<profile>.md` and selection matrix in `references/scoring.md` | `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs` |
+| Renderer or verifier | `lib/render-report.mjs`, `lib/verify-claim.mjs`, or related module | Focused test plus full test suite |
+
+Generated docs:
+
+```bash
+node skills/vercel-optimize/scripts/build-docs.mjs
+node skills/vercel-optimize/scripts/check-docs-fresh.mjs
+```
+
+Full test loop:
+
+```bash
+node --test packages/vercel-optimize-tests/test/*.test.mjs
+node skills/vercel-optimize/scripts/check-docs-fresh.mjs
+node skills/vercel-optimize/scripts/check-citations.mjs
+```
+
+## Rules
+
+- No runtime dependencies. Scripts use Node.js 20+ built-ins and the Vercel CLI.
+- No recommendation without a Vercel metric signal, code evidence when code changes are proposed, and an allow-listed citation.
+- No invented URLs, exact savings projections, or version-mismatched framework APIs.
+- No internal repo paths, service names, customer names, or captured private output in fixtures.
+- Keep generated report copy customer-facing. Put debug details behind `--debug-out`.
+
+## Output contracts
+
+Every JSON-emitting script must be deterministic: stable key order, stable sort order, 2-space indentation, trailing newline. If a consumed schema changes, update the schema version and the fixture tests in the same PR.
diff --git a/skills/vercel/vercel-optimize/README.md b/skills/vercel/vercel-optimize/README.md
new file mode 100644
index 0000000..75d7327
--- /dev/null
+++ b/skills/vercel/vercel-optimize/README.md
@@ -0,0 +1,91 @@
+# vercel-optimize
+
+Optimize cost and performance for supported projects on Vercel.
+
+This skill uses Vercel metrics to find high-impact improvements in your app. Every recommendation is backed by observed data, scoped code evidence, and version-aware docs.
+
+[![skills.sh](https://skills.sh/b/vercel-labs/agent-skills)](https://skills.sh/vercel-labs/agent-skills)
+
+## Install
+
+Install just this skill:
+
+```bash
+npx skills add vercel-labs/agent-skills --skill vercel-optimize
+```
+
+Manual install: copy `skills/vercel-optimize` into `.agents/skills/vercel-optimize` and reference `SKILL.md` from your project `AGENTS.md`.
+
+## Requirements
+
+- Node.js 20+
+- Vercel CLI with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api` support (`npm i -g vercel@latest`). The skill enforces v53+ as its compatibility floor.
+- Authenticated Vercel CLI session (`vercel login`)
+- Linked Vercel project directory (`vercel link`) for route metrics. `VERCEL_PROJECT_ID` can resolve project config, but it does not replace directory linkage for `vercel metrics`. The project must resolve to a CLI-safe team or personal scope so `vercel metrics`, `vercel usage`, and `vercel contract` all run against the same account.
+- Observability Plus for metric-backed route ranking
+- Code-backed recommendation coverage is strongest for Next.js and SvelteKit, supported for Nuxt route mapping with generic checks, and limited for Astro. Hono, Remix, and unknown frameworks pause up front.
+
+If route-level metrics are unavailable, the skill pauses before scanner-only mode. Scanner-only can catch traffic-independent code issues, but it cannot rank hot routes or prove cost impact.
+
+## Use
+
+From the Vercel project directory, ask your coding agent:
+
+```text
+optimize this Vercel project
+```
+
+The agent should collect metrics first. If it starts by reading source files or guessing from `vercel.json`, the skill was not loaded correctly.
+
+## Roadmap
+
+| Attribute | Status |
+|---|---|
+| Route-level Vercel Function invocations, duration, TTFB, and cold starts | Supported |
+| Vercel Function CPU, memory, and GB-hours | Supported |
+| Request volume, cache hit rate, HTTP status, and method distribution | Supported |
+| Fast Data Transfer and bot traffic patterns | Supported |
+| ISR reads, writes, and over-revalidation | Supported |
+| Routing Middleware volume and duration | Supported |
+| External API latency, volume, and transfer bytes | Supported |
+| Core Web Vitals from Speed Insights | Supported |
+| Image Optimization usage, source hosts, and source bytes | Supported |
+| Build Minutes fan-out | Supported |
+| Usage spikes by billing service | Supported |
+| Bot Protection and BotID configuration | Supported |
+| Fluid Compute configuration and compute signals | Supported |
+| Region pinning and project configuration mismatches | Supported |
+| Observability Events cost attribution | Supported |
+| Route-to-file recommendations for Next.js and SvelteKit | Supported |
+| Nuxt route mapping with generic/platform checks | Supported |
+| Generic route mapping and platform checks for Astro | Supported |
+| Hono route-to-file mapping | Planned |
+| Remix route-to-file mapping | Planned |
+| AI Gateway usage and cost optimization | Planned |
+| Sandbox usage and cost optimization | Planned |
+| Blob, Edge Config, Runtime Cache, Workflows, Queues, Flags, and Microfrontends billing dimensions | Planned |
+
+## What You Get
+
+- Ranked recommendations tied to observed Vercel metrics
+- Specific route and file references when source changes are justified
+- Before/after code for ready recommendations
+- Citations from a curated, version-aware documentation allow-list
+- Held-back findings when evidence is real but not strong enough for a recommendation
+- A concise final message plus a full Markdown report
+
+## Trust Model
+
+- Metrics come first. Code investigation starts only after signals are collected.
+- Gates are deterministic JavaScript thresholds. No LLM decides whether a metric qualifies.
+- Citations are allow-listed. Unknown URLs and version-mismatched framework docs are stripped.
+- Project config contradictions are rejected. For example, the verifier blocks "enable Fluid Compute" when Fluid Compute is already on.
+- Cost impact uses magnitude framing, not invented exact savings.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). New gates, scanners, playbooks, citations, and sanitizers need fixture coverage in `packages/vercel-optimize-tests`.
+
+## License
+
+MIT
diff --git a/skills/vercel/vercel-optimize/SKILL.md b/skills/vercel/vercel-optimize/SKILL.md
new file mode 100644
index 0000000..c8a6d6d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/SKILL.md
@@ -0,0 +1,322 @@
+---
+name: vercel-optimize
+description: "Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verified files and version-aware Vercel/framework docs. Trigger for Vercel bill reduction, slow or expensive routes, caching opportunities, Function Invocations, Build Minutes, Fast Data Transfer, Core Web Vitals, Bot Management, Fluid compute, or cost breakdown requests."
+metadata:
+  version: "1.2.0"
+---
+
+# Vercel Optimize
+
+Run an observability-first Vercel optimization audit. Do not inspect source files until `signals.json` exists and a deterministic gate points to a route, file, or project setting.
+
+Core doctrine: read [references/doctrine.md](references/doctrine.md) if any rule is unclear.
+
+- Metrics first. Recommendations start from Vercel production signals, not repo-wide grep.
+- Deterministic gates. `scripts/gate-investigations.mjs` decides what deserves investigation.
+- Candidate-bound scope. Read only files named by a candidate or a route-local import chain.
+- Version-aware citations. Use only `references/docs-library.json`; invalid or version-mismatched citations are stripped.
+- Customer copy. Read [references/voice.md](references/voice.md) before writing report text or chat output.
+
+## Prerequisites
+
+- Vercel CLI v53+ with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api`.
+- Authenticated CLI session: `vercel login`.
+- Linked app directory: `vercel link`. `VERCEL_PROJECT_ID` can help resolve project config, but `vercel metrics` still requires directory linkage. The link or environment must include the intended project org/team/user scope so the collector can resolve a CLI-safe `--scope` and keep `vercel metrics`, `vercel usage`, and `vercel contract` on the same account.
+- Node.js 20+.
+- Observability Plus for route-level metric-backed recommendations.
+
+Never put auth tokens in shell commands. Do not type `VERCEL_TOKEN=...`, `--token ...`, or `Authorization: Bearer ...` into commands that may be echoed in chat.
+
+## Framework Support
+
+The preflight reads `package.json` and sets expectations before metric fan-out.
+
+| Framework | Status | Notes |
+|---|---|---|
+| Next.js App Router | supported | strongest route mapping, scanners, playbooks, citations |
+| Next.js Pages Router | supported | scoped to Pages Router idioms when detected |
+| SvelteKit | supported | route mapping for `src/routes` files and SvelteKit scanner |
+| Nuxt | supported | route mapping plus generic/platform checks; fewer framework-specific recs |
+| Astro | limited | route mapping plus generic checks; fewer framework-specific recs |
+| Hono / Remix / unknown | blocked by default | continue only if the user accepts a limited platform/code-only audit |
+
+If unsupported, stop and ask before scanning or gating:
+
+```text
+This project uses <framework>. Vercel Optimize supports metric-backed code recommendations for Next.js, SvelteKit, and Nuxt. Astro support is limited. For <framework>, I can still run a limited platform/scanner audit, but route-level Vercel metrics may not map back to source files.
+
+Do you want me to continue with the limited audit, or stop here?
+```
+
+If the user continues, rerun collection with `--continue-unsupported-framework`.
+
+## Run Directory
+
+Use a fresh run directory for every audit. Do not reuse briefs, sub-agent outputs, or reports across runs.
+
+```bash
+RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"
+```
+
+## Pipeline
+
+### 1. Collect, scan, and merge signals
+
+Run from the linked app directory or pass `--cwd` where a script supports it. Keep stdout JSON separate from stderr logs. Do not combine streams.
+
+```bash
+node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
+node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$RUN_DIR/vercel-signals.json"
+
+node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
+node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
+```
+
+Collection details, schemas, metric IDs, and degradation behavior live in [references/data-collection.md](references/data-collection.md). The metric registry is [lib/queries.mjs](lib/queries.mjs); keep all queries on the shared 14-day window.
+
+`collect-signals.mjs` resolves the linked project owner to `commandScope.cliScope` and verifies that the resolved account can read the resolved project before it checks Observability Plus. Downstream scripts reuse that scope for every Vercel CLI command that accepts `--scope`. Do not run `vercel usage`, `vercel metrics`, or `vercel contract` manually without the same scope; unscoped usage can report the user's personal organization while route metrics come from the team project.
+
+If project or scope resolution is ambiguous, stop and ask the user which Vercel project and team/personal scope they want audited. Do not infer the intended scope from the current `vercel whoami` team, and do not proceed with metrics, usage, or contract collection until the link, an exact project match in `.vercel/repo.json`, or `VERCEL_PROJECT_ID` + `VERCEL_ORG_ID` identifies the intended account.
+
+Use this prompt for `PROJECT_SCOPE_UNRESOLVED`, `SCOPE_UNRESOLVED`, or `PROJECT_SCOPE_MISMATCH`:
+
+```text
+I can't safely identify the Vercel project and account for this audit yet.
+
+Please confirm the Vercel project name or ID and the team slug/name, or tell me it's under your personal account. Once confirmed, I'll relink or rerun collection against that exact scope before checking metrics.
+```
+
+### 1.1 Stop on blockers
+
+Check blockers before gating:
+
+```bash
+jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"
+```
+
+Required actions:
+
+- `frameworkSupportBlocker === "unsupported_framework"`: use the unsupported-framework prompt above.
+- `PROJECT_SCOPE_UNRESOLVED`, `SCOPE_UNRESOLVED`, or `PROJECT_SCOPE_MISMATCH`: stop and ask which Vercel project and team/personal scope the user wants audited. For team projects, rerun after `vercel link --yes --project <project-name-or-id> --team <team-slug>`; for personal projects, rerun after linking under the intended user account or after setting both `VERCEL_PROJECT_ID` and `VERCEL_ORG_ID`.
+- `observabilityPlusBlocker === null`: continue.
+- `no_traffic`: tell the user route metrics are sparse; continue only if they accept limited output.
+- `payment_required` or `no_oplus_probe`: render [references/observability-plus.md](references/observability-plus.md) verbatim and ask.
+- `project_disabled`: tell the user to enable Observability Plus for the project or accept a limited audit.
+- `daily_quota_exceeded`: stop and tell the user the Observability query quota is exhausted; retry after the next UTC midnight reset, or ask whether to continue with a limited code-only audit.
+- `not_linked`: link the app directory, then rerun Step 1. If app path and project are known:
+
+```bash
+vercel link --yes --project <project-name-or-id> --cwd <app-dir>
+# add --team <team-id-or-slug> when known
+```
+
+- `forbidden` or `project_not_found`: fix auth/team scope. Do not pitch Observability Plus.
+- `all_failed_other`: show the raw error code and ask whether to continue in limited code-only mode.
+
+Do not silently fall back to code-only mode. If the user accepts a limited audit, rerun collection with:
+
+```bash
+node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
+```
+
+Then scan and merge again.
+
+### 2. Gate candidates
+
+```bash
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"
+```
+
+Output shape:
+
+- `toLaunch`: code-scope candidates to investigate.
+- `platform`: project/account-scope recommendations.
+- `gated`: skipped, covered, or disqualified candidates that must still appear in the report.
+- `budget`: candidate budget and selection mode.
+
+Default budget is 6 code-scope candidates with a diversity guardrail. To expand:
+
+```bash
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates 12 > "$RUN_DIR/gate.json"
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates all > "$RUN_DIR/gate.json"
+```
+
+Generated candidate docs: [references/candidates.md](references/candidates.md).
+
+### 2.1 Ask about audit scope when needed
+
+Before deep-dive, run:
+
+```bash
+node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"
+```
+
+If `shouldAsk` is false, continue.
+
+If `shouldAsk` is true:
+
+1. Print `exactChatMessage.body` exactly as returned. Do not summarize, truncate, reorder, or rewrite it.
+2. Then ask `questionText` using `questionPayload` when the host supports structured questions.
+3. If the user chooses a different number, rerun the gate with `--max-candidates <choice>`.
+
+Never put the long preview inside the question field. The preview and the question are separate surfaces.
+
+### 2.2 Deep-dive and reconcile
+
+```bash
+node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <project-dir> > "$RUN_DIR/investigation-evidence.json"
+
+node scripts/reconcile-candidates.mjs "$RUN_DIR/investigation-evidence.json" \
+  --gate "$RUN_DIR/gate.json" \
+  --out "$RUN_DIR/reconciled-investigation.json"
+```
+
+`--cwd` must be the linked project directory so `deep-dive.mjs` can verify the same project link and reuse `signals.json.commandScope.cliScope` for any follow-up `vercel metrics` calls.
+
+Reconciliation deterministically converts disproven candidates into observations before any source investigation:
+
+- `metric_mismatch`
+- `error_storm`
+- `deployment_regression`
+- `scanner_only_no_metric`
+
+### 2.3 Generate briefs and investigate
+
+List the work:
+
+```bash
+node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" --list > "$RUN_DIR/briefs-manifest.json"
+```
+
+Generate one brief for every entry in `briefs-manifest.json.briefs`. The `group` can be `toLaunch` or `platform`; do not generate only `toLaunch` briefs.
+
+```bash
+mkdir -p "$RUN_DIR/briefs" "$RUN_DIR/sub-agent-outputs"
+node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" \
+  --group <brief.group> --index <brief.index> --out "$RUN_DIR/briefs/<brief.group>-<brief.index>.md"
+```
+
+Use `briefs-manifest.json.briefs[].label` for visible worker names, for example `Low cache-hit route on /docs/llm-digest/[...slug]`, not `toLaunch-7`.
+
+Fan-out rule:
+
+- 1-2 briefs: investigate inline.
+- 3+ briefs: spawn one sub-agent per brief when the host supports it.
+- Hosts without sub-agents: run inline serially.
+
+Sub-agent contract:
+
+- The brief is the whole prompt.
+- Read only files listed in the brief, plus route-local imports when needed.
+- Emit one JSON recommendation or one JSON no-change finding using [references/recommendations.md](references/recommendations.md).
+- Do not cite URLs outside the provided citation subset.
+- Do not recommend framework features unavailable in the detected version.
+
+If a sub-agent reaches for repo-wide grep, the candidate is malformed; drop or abstain rather than widening scope.
+
+### 2.4 Collect outputs
+
+Save each raw investigation result in `$RUN_DIR/sub-agent-outputs/`, then collect:
+
+```bash
+node scripts/collect-sub-agent-outputs.mjs \
+  --manifest "$RUN_DIR/briefs-manifest.json" \
+  --out "$RUN_DIR/recommendations.json" \
+  "$RUN_DIR/sub-agent-outputs/"
+```
+
+The collector extracts JSON, prepends pre-resolved records, enforces manifest order, and fails on missing, duplicate, unknown, or mismatched `candidateRef` values.
+
+### 3. Verify recommendations
+
+```bash
+node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
+  --signals "$RUN_DIR/signals.json" \
+  --repo-root <project-dir> \
+  --out "$RUN_DIR/verify.json"
+```
+
+This script extracts claims, verifies files/citations/version fit, grades quality, applies sanitizers, emits `verifiedRecommendations`, `withheldRecommendations`, `renderableRecommendations`, and creates `regenPlan` for failed or unsafe recommendations.
+
+Recommendation schema, writing rules, sanitizer order, and grading rules: [references/recommendations.md](references/recommendations.md). Verification rules: [references/verification.md](references/verification.md).
+
+For each `regenPlan` entry, rerun the same brief with a `Previous attempt failed these checks` section listing `topFailures`. Keep the regenerated output only if verification improves without gutting citations.
+
+### 4. Render report and final message
+
+```bash
+node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
+  --project <name> \
+  --out "$RUN_DIR/report.md" \
+  --message-out "$RUN_DIR/final-message.json"
+```
+
+Use `--debug-out "$RUN_DIR/debug.json"` only when developing the skill. Customer Markdown and chat output must not expose `passRate`, `quality`, sanitizer trails, raw sub-agent names, or other implementation fields.
+
+After rendering, print `final-message.json.body` verbatim and stop. Do not add highlights, debug notes, raw counts, sub-agent summaries, or extra explanation. Render-time dedupe, platform caps, and hard-safety drops can change the customer-visible count, so never summarize from raw `verify.json`.
+
+Report structure and impact framing: [references/scoring.md](references/scoring.md).
+
+## Recommendation Rules
+
+Every recommendation must:
+
+- Trace to a launched candidate, platform candidate, pre-resolved observation, or verified traffic-independent scanner finding.
+- Include observed metric evidence from `signals.json` or `evidence.deepDive`.
+- Cite verified files with line numbers when code is involved.
+- Include at least one allowed citation that applies to the detected framework/version.
+- Use precise observed performance numbers.
+- Use cost magnitude phrases only; never customer-facing `$N` savings.
+- Do not recommend duration reductions for Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`). These are generated orchestration routes for durable step/flow execution and should be hard-gated before investigation.
+- Workflow recommendations must name the boundary being changed. Valid examples: enqueue durable work and return a run ID instead of awaiting completion, fix stream replay/closure/locks, or reduce verified excess Workflow Steps/Storage. Do not infer cost savings from Workflow endpoint wall-clock duration.
+- For streaming, SSE, resumable chat, or other intentionally long-lived routes, do not frame wall-clock function duration as a problem by itself. Require evidence of avoidable pre-first-byte work, high active CPU, duplicate invocations, or post-response work that can move out of the user-visible path.
+- Name a specific cache policy when recommending caching.
+- Keep unsafe responses dynamic unless evidence proves they are safe to cache: auth-sensitive paths, errors, fallback responses, missing content, invalid requests, geolocation/device-varying output, and unversioned dynamic URLs.
+
+Never recommend "verify X is on" for facts already present in `signals.project`, including Fluid compute status, memory tier, regions, in-function concurrency, and timeout.
+
+## Scanner Rules
+
+Scanner findings are supplementary. Drop findings annotated `COLD-PATH` or `NO-ROUTE-MAPPING` unless the scanner declares `metadata.trafficIndependent === true`.
+
+Traffic-independent examples: middleware matcher, source maps, React Compiler config, build settings. Route-local cache or data-fetch patterns need route-level traffic evidence.
+
+Scanner docs: [references/scanner-patterns.md](references/scanner-patterns.md).
+
+## Final Customer Terms
+
+Use:
+
+- `recommendations ready`
+- `observations from investigation`
+- `investigated, no change recommended`
+- `not investigated in this run`
+
+Avoid:
+
+- `sub-agent`
+- `abstention`
+- `passRate`
+- `quality score`
+- `gate`
+- `LLM`
+
+## Failure Copy
+
+Use these messages without adding sales copy or process detail.
+
+**No traffic in the last 14 days:**
+
+> This project has no meaningful traffic in the last 14 days, so route-level metrics are sparse. I can still check traffic-independent scanner findings and project settings, but I cannot rank route fixes until traffic accumulates.
+
+**Route-level metrics unavailable:**
+
+> Use the verbatim choice template in [references/observability-plus.md](references/observability-plus.md). Do not silently fall back to code-only mode; present the two-path choice: enable Observability Plus and rerun the metric-backed audit, or accept a limited code-only run.
+
+**Project is not linked:**
+
+> This worktree is not linked to a Vercel project. Run `vercel link --yes --project <project-name-or-id> --cwd <app-dir>` and rerun the audit. If the team is known, add `--team <team-id-or-slug>`.
+
+**Most route-to-file mappings failed:**
+
+> The route inventory matched fewer than half of the routes we saw in observability. This is common in monorepos with custom routing. I've surfaced what I can match; the rest appear in the "Not investigated in this run" section.
diff --git a/skills/vercel/vercel-optimize/lib/auth-route.mjs b/skills/vercel/vercel-optimize/lib/auth-route.mjs
new file mode 100644
index 0000000..96fd457
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/auth-route.mjs
@@ -0,0 +1,23 @@
+// Auth routes carry user state and must not be cached at CDN edge.
+
+export const AUTH_ROUTE_REGEX =
+  /(login|logout|auth|account|dashboard|checkout|cart|profile|session|me)(?:\/|$)/i;
+
+export function isAuthRoute(route) {
+  return AUTH_ROUTE_REGEX.test(String(route ?? ''));
+}
+
+// Non-cache candidates pass through — errors/slowness on auth routes still warrant investigation.
+export function applyAuthDisqualifier(candidate) {
+  const cacheKinds = new Set(['uncached_route', 'cache_header_gap']);
+  if (!cacheKinds.has(candidate.kind)) return candidate;
+  if (!candidate.route) return candidate;
+  if (isAuthRoute(candidate.route)) {
+    return {
+      ...candidate,
+      disqualified: true,
+      disqualifyReason: 'auth-like route — should not be cached at edge',
+    };
+  }
+  return candidate;
+}
diff --git a/skills/vercel/vercel-optimize/lib/budget-summary.mjs b/skills/vercel/vercel-optimize/lib/budget-summary.mjs
new file mode 100644
index 0000000..fcb1aaa
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/budget-summary.mjs
@@ -0,0 +1,182 @@
+// Checkpoint between gate and deep-dive. Asks only when budget was default AND >=1 candidate got skipped — every question is a tax on the user.
+
+import { createHash } from 'node:crypto';
+import { formatCandidateLine } from './display-labels.mjs';
+
+const TOP_INVESTIGATING_PREVIEW = 5;
+const MAX_FULL_INVESTIGATING_PREVIEW = 10;
+export function buildBudgetSummary(gate) {
+  const toLaunch = Array.isArray(gate?.toLaunch) ? gate.toLaunch : [];
+  const gated = Array.isArray(gate?.gated) ? gate.gated : [];
+  const budgetSource = gate?.budget?.source ?? 'default';
+  const currentBudget =
+    typeof gate?.budget?.maxCandidates === 'number'
+      ? gate.budget.maxCandidates
+      : (gate?.budget?.maxCandidates === 'all' ? Infinity : 6);
+
+  // Only budget skips can be reached by raising the budget; disqualified/coveredBy can't.
+  const skippedByBudget = gated.filter((g) =>
+    typeof g.gatedReason === 'string' && g.gatedReason.startsWith('skippedByBudget')
+  );
+  const skipped = skippedByBudget.length;
+  const totalPassed = toLaunch.length + skipped;
+
+  const reasonParts = [];
+  if (budgetSource !== 'default') reasonParts.push(`user pre-set budget via ${budgetSource}`);
+  if (skipped === 0) reasonParts.push('no candidates skipped by budget');
+  const shouldAsk = budgetSource === 'default' && skipped > 0;
+  const reason = shouldAsk
+    ? `default budget skipped ${skipped} candidate(s); ask user whether to expand`
+    : reasonParts.join('; ') || 'no expansion possible';
+
+  const summarize = (c) => ({
+    kind: c.kind,
+    route: c.route ?? c.hostname ?? null,
+    displayRoute: c.displayRoute ?? null,
+    o11ySignal: c.o11ySignal ?? null,
+    priority: c.priority ?? null,
+  });
+
+  const investigatingPreviewCount = typeof currentBudget === 'number' && currentBudget <= MAX_FULL_INVESTIGATING_PREVIEW
+    ? currentBudget
+    : TOP_INVESTIGATING_PREVIEW;
+  const topInvestigating = toLaunch.slice(0, investigatingPreviewCount).map(summarize);
+  const topSkipped = skippedByBudget.map(summarize);
+  const options = buildOptions(toLaunch.length, skipped);
+  const questionText = buildQuestionText({ shouldAsk, totalPassed, currentBudget });
+  const printContract = shouldAsk
+    ? 'Print chatPreview verbatim by copying exactChatMessage.body as a chat message before asking questionText. Do not summarize, truncate, reorder, shorten, or rewrite options.'
+    : null;
+  const questionPayload = shouldAsk ? buildQuestionPayload(questionText, options) : null;
+  const chatPreview = buildChatPreview({ shouldAsk, totalPassed, currentBudget, skipped, topInvestigating, topSkipped, reason });
+  const exactChatMessage = buildExactChatMessage(chatPreview);
+  return {
+    shouldAsk,
+    reason,
+    totalPassed,
+    currentBudget: currentBudget === Infinity ? 'all' : currentBudget,
+    budgetSource,
+    skipped,
+    topInvestigating,
+    topSkipped,
+    options,
+    printContract,
+    chatPreview,
+    exactChatMessage,
+    printCheck: shouldAsk ? buildPrintCheck({ exactChatMessage, skipped }) : null,
+    questionText,
+    questionPayload,
+  };
+}
+
+function buildChatPreview({ shouldAsk, totalPassed, currentBudget, skipped, topInvestigating, topSkipped, reason }) {
+  if (!shouldAsk) return `Audit scope: no question needed — ${reason}.`;
+  const lines = [];
+  lines.push(`Found ${totalPassed} potential issue${totalPassed === 1 ? '' : 's'} worth checking. By default I'll inspect the ${currentBudget} strongest now; ${skipped} will stay in the report for a larger run.`);
+  lines.push(`Choose a larger scope if you want broader coverage. More checks take longer.`);
+  if (topInvestigating.length > 0) {
+    lines.push('');
+    lines.push(`Checking now${topInvestigating.length < currentBudget ? ` (${topInvestigating.length} shown)` : ''}:`);
+    topInvestigating.forEach((c, i) => lines.push(`  ${i + 1}. ${formatCandidateLine(c)}`));
+  }
+  if (topSkipped.length > 0) {
+    lines.push('');
+    lines.push(`Only checked if you expand this run (${topSkipped.length}):`);
+    topSkipped.forEach((c, i) => lines.push(`  ${i + 1}. ${formatCandidateLine(c)}`));
+  }
+  return lines.join('\n');
+}
+
+function buildExactChatMessage(body) {
+  return {
+    body,
+    lineCount: body.split('\n').length,
+    sha256: createHash('sha256').update(body).digest('hex'),
+  };
+}
+
+function buildPrintCheck({ exactChatMessage, skipped }) {
+  return {
+    bodyField: 'exactChatMessage.body',
+    sameAs: 'chatPreview',
+    requiredLineCount: exactChatMessage.lineCount,
+    requiredSha256: exactChatMessage.sha256,
+    requiredSkippedRows: skipped,
+    requiredSkippedHeading: `Only checked if you expand this run (${skipped}):`,
+    forbiddenSummaryPatterns: [
+      '\\btop skipped\\b',
+      '\\bmore (?:candidate|candidates|routes|entries|items|in gated list)\\b',
+      '\\b\\d+\\s*[-–—]\\s*\\d+\\.\\s+\\d+\\s+more\\b',
+      '\\betc\\.\\b',
+    ],
+    instruction: 'The budget message is valid only when every line from exactChatMessage.body is preserved exactly. If you cannot verify that, print exactChatMessage.body again before asking the question.',
+  };
+}
+
+function buildQuestionText({ shouldAsk, totalPassed, currentBudget }) {
+  if (!shouldAsk) return '';
+  return `How many potential issues should I check in this run?`;
+}
+
+function buildOptions(currentCount, skippedCount) {
+  if (skippedCount === 0) return [];
+  const total = currentCount + skippedCount;
+  return [
+    {
+      label: `Check ${currentCount} (default)`,
+      value: currentCount,
+      recommended: true,
+      description: 'Fastest first pass; checks the strongest cost and performance signals.',
+      rationale: 'fastest first pass; checks the strongest cost and performance signals',
+    },
+    {
+      label: `Check all ${total}`,
+      value: 'all',
+      recommended: false,
+      description: 'Most complete; takes longer because every flagged route is investigated.',
+      rationale: 'most complete; takes longer because every flagged route is investigated',
+    },
+    {
+      label: 'Pick a number',
+      value: 'custom',
+      recommended: false,
+      description: `Check more than ${currentCount} without running the full ${total}.`,
+      rationale: `checks more than ${currentCount} without running the full ${total}`,
+    },
+  ];
+}
+
+function buildQuestionPayload(questionText, options) {
+  return {
+    questions: [{
+      question: questionText,
+      header: 'Audit scope',
+      multiSelect: false,
+      options: options.map((o) => ({
+        label: o.label,
+        description: o.description ?? o.rationale,
+      })),
+    }],
+  };
+}
+
+export function renderBudgetSummaryMarkdown(s) {
+  const lines = [];
+  lines.push(`## Audit scope`);
+  lines.push('');
+  if (!s.shouldAsk) {
+    lines.push(`_No question needed — ${s.reason}._`);
+    return lines.join('\n');
+  }
+  for (const ln of s.chatPreview.split('\n')) lines.push(ln);
+  lines.push('');
+  lines.push('### Options');
+  lines.push('');
+  for (const o of s.options) {
+    const tag = o.recommended ? ' (recommended)' : '';
+    lines.push(`- **${o.label}${tag}** — ${o.rationale}`);
+  }
+  lines.push('');
+  lines.push(`**Question:** ${s.questionText}`);
+  return lines.join('\n');
+}
diff --git a/skills/vercel/vercel-optimize/lib/citations.mjs b/skills/vercel/vercel-optimize/lib/citations.mjs
new file mode 100644
index 0000000..4d6f362
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/citations.mjs
@@ -0,0 +1,139 @@
+// Curated doc library — the allow-list for recommender citations.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const LIBRARY_PATH = join(HERE, '..', 'references', 'docs-library.json');
+
+let cached;
+
+export async function loadLibrary() {
+  if (cached) return cached;
+  const raw = await readFile(LIBRARY_PATH, 'utf-8');
+  cached = JSON.parse(raw);
+  return cached;
+}
+
+export async function isKnownUrl(url) {
+  const lib = await loadLibrary();
+  return lib.urls.some(e => e.url === url);
+}
+
+export async function lookupUrl(url) {
+  const lib = await loadLibrary();
+  return lib.urls.find(e => e.url === url);
+}
+
+export async function lookupSkillRule(ref) {
+  const lib = await loadLibrary();
+  const m = ref.match(/^([\w-]+):([\w-]+)$/);
+  if (!m) return undefined;
+  return lib.ruleSkillRefs.find(r => r.skill === m[1] && r.rule === m[2]);
+}
+
+// Narrow semver subset: "*", "fw@*", "fw@14", "fw@>=15.0.0", "fw@<X", "fw@X.Y", "fw@X.Y.Z", "a || b".
+export function matchesFrameworkVersion(pattern, framework, version) {
+  if (pattern === '*') return true;
+
+  if (pattern.includes('||')) {
+    return pattern.split('||').map(p => p.trim()).some(p =>
+      matchesFrameworkVersion(p, framework, version)
+    );
+  }
+
+  const m = pattern.match(/^([\w-]+)@(.+)$/);
+  if (!m) return false;
+  const [, fw, range] = m;
+
+  if (fw !== framework) return false;
+  if (range === '*') return true;
+
+  const verParts = parseVersion(version);
+  if (!verParts) return false;
+
+  let m2 = range.match(/^>=\s*(.+)$/);
+  if (m2) {
+    const min = parseVersion(m2[1]);
+    return min ? compareVersion(verParts, min) >= 0 : false;
+  }
+
+  m2 = range.match(/^<\s*(.+)$/);
+  if (m2) {
+    const max = parseVersion(m2[1]);
+    return max ? compareVersion(verParts, max) < 0 : false;
+  }
+
+  if (/^\d+$/.test(range)) {
+    return verParts[0] === Number(range);
+  }
+
+  m2 = range.match(/^(\d+)\.(\d+)$/);
+  if (m2) {
+    return verParts[0] === Number(m2[1]) && verParts[1] === Number(m2[2]);
+  }
+
+  const exact = parseVersion(range);
+  if (exact) return compareVersion(verParts, exact) === 0;
+
+  return false;
+}
+
+function parseVersion(v) {
+  const m = String(v).replace(/^[v^~]+/, '').match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return null;
+  return [Number(m[1]) || 0, Number(m[2]) || 0, Number(m[3]) || 0];
+}
+
+function compareVersion(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+// Filtered subset embedded in recommender prompt — LLM never sees URLs for features not in user's stack.
+export async function libraryForStack(framework, version) {
+  const lib = await loadLibrary();
+  const matches = (frameworks) =>
+    frameworks.some(p => matchesFrameworkVersion(p, framework, version) || p === '*');
+  return {
+    urls: lib.urls.filter(e => matches(e.applicableFrameworks)),
+    ruleSkillRefs: lib.ruleSkillRefs.filter(r => matches(r.applicableFrameworks)),
+  };
+}
+
+export async function sanitizeCitations(rec, framework, version) {
+  const lib = await loadLibrary();
+  const strippedUnknown = [];
+  const strippedVersion = [];
+  const kept = [];
+
+  for (const cite of rec.citations ?? []) {
+    const ruleRef = await lookupSkillRule(cite);
+    if (ruleRef) {
+      if (matchesFrameworkVersion(ruleRef.applicableFrameworks.join(' || '), framework, version) || ruleRef.applicableFrameworks.includes('*')) {
+        kept.push(cite);
+      } else {
+        strippedVersion.push(cite);
+      }
+      continue;
+    }
+
+    const entry = lib.urls.find(e => e.url === cite);
+    if (!entry) {
+      strippedUnknown.push(cite);
+      continue;
+    }
+    if (entry.applicableFrameworks.includes('*') ||
+        entry.applicableFrameworks.some(p => matchesFrameworkVersion(p, framework, version))) {
+      kept.push(cite);
+    } else {
+      strippedVersion.push(cite);
+    }
+  }
+
+  rec.citations = kept;
+  return { rec, strippedUnknown, strippedVersion };
+}
diff --git a/skills/vercel/vercel-optimize/lib/cost-coverage.mjs b/skills/vercel/vercel-optimize/lib/cost-coverage.mjs
new file mode 100644
index 0000000..09a8b19
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/cost-coverage.mjs
@@ -0,0 +1,143 @@
+// Maps billing line items to gate coverage so report surfaces uncovered dimensions (Sandbox, AI Gateway, Build, …) as blind spots.
+
+// Service → billing dimension. dim=null means uncovered. Substring match — Vercel billing names are stable but untyped.
+const SERVICE_DIMENSION = [
+  { match: /^Function Duration$/i,                       dim: 'function-duration' },
+  { match: /^Function Invocations$/i,                    dim: 'function-duration' },
+  { match: /^Fluid Active CPU$/i,                        dim: 'function-duration' },
+  { match: /^Fluid Provisioned Memory$/i,                dim: 'function-duration' },
+  { match: /^Edge Requests$/i,                           dim: 'edge-requests' },
+  { match: /^Edge Requests.*Additional CPU Duration/i,   dim: 'edge-requests' },
+  { match: /^Edge Function Execution Units$/i,           dim: 'edge-requests' },
+  { match: /^Edge Middleware Invocations$/i,             dim: 'edge-requests' },
+  { match: /^ISR (Reads|Writes)$/i,                      dim: 'isr' },
+  { match: /^Speed Insights( Data Points)?$/i,           dim: 'speed-insights' },
+  { match: /^Image Optimization/i,                       dim: 'image-optimization' },
+  // Indirect: bot-protection gate addresses bandwidth/edge spend.
+  { match: /^Fast Data Transfer$/i,                      dim: 'edge-requests' },
+  { match: /^Fast Origin Transfer$/i,                    dim: 'edge-requests' },
+
+  // Uncovered.
+  { match: /^Sandbox/i,                                  dim: null, family: 'sandbox' },
+  { match: /^AI Gateway$/i,                              dim: null, family: 'ai-gateway' },
+  { match: /^Build Minutes$/i,                           dim: 'build', family: 'build' },
+  { match: /^Build CPU Minutes$/i,                       dim: 'build', family: 'build' },
+  { match: /^Private Data Transfer$/i,                   dim: null, family: 'private-network' },
+  { match: /^Secure Compute Network$/i,                  dim: null, family: 'private-network' },
+  { match: /^Drains Volume$/i,                           dim: null, family: 'drains' },
+  { match: /^Observability Events$/i,                    dim: 'observability-events', family: 'observability-events' },
+  { match: /^Blob/i,                                     dim: null, family: 'blob' },
+  { match: /^Edge Config (Reads|Writes)$/i,              dim: null, family: 'edge-config' },
+  { match: /^Runtime Cache/i,                            dim: null, family: 'runtime-cache' },
+  { match: /^Microfrontends/i,                           dim: null, family: 'microfrontends' },
+  { match: /^Workflow/i,                                 dim: null, family: 'workflow' },
+  { match: /^Queue/i,                                    dim: null, family: 'queues' },
+  { match: /^Flag Requests$/i,                           dim: null, family: 'flags' },
+  { match: /^Flags Explorer/i,                           dim: null, family: 'flags' },
+  { match: /^BotID/i,                                    dim: null, family: 'botid' },
+  { match: /^Firewall/i,                                 dim: null, family: 'firewall' },
+  { match: /^Vercel Agent$/i,                            dim: null, family: 'vercel-agent' },
+
+  // Fixed costs (seats, contracts) — not actionable.
+  { match: /^v0 /i,                                      dim: null, family: 'fixed', actionable: false },
+  { match: /^Additional Team Seats$/i,                   dim: null, family: 'fixed', actionable: false },
+  { match: /^SAML$/i,                                    dim: null, family: 'fixed', actionable: false },
+  { match: /^HIPAA BAA$/i,                               dim: null, family: 'fixed', actionable: false },
+  { match: /^SIEM Integration$/i,                        dim: null, family: 'fixed', actionable: false },
+  { match: /^Web Analytics/i,                            dim: null, family: 'fixed', actionable: false },
+  { match: /^Static IPs$/i,                              dim: null, family: 'fixed', actionable: false },
+  { match: /^Bulk Redirects$/i,                          dim: null, family: 'fixed', actionable: false },
+  { match: /^Preview Deployment Suffix$/i,               dim: null, family: 'fixed', actionable: false },
+  { match: /^Rolling Releases$/i,                        dim: null, family: 'fixed', actionable: false },
+  { match: /^Observability Plus$/i,                      dim: null, family: 'fixed', actionable: false },
+  { match: /^Platform Customer Usage$/i,                 dim: null, family: 'fixed', actionable: false },
+  { match: /^Advanced Deployment Protection$/i,          dim: null, family: 'fixed', actionable: false },
+];
+
+export function classifyService(serviceName, activeDims) {
+  if (!serviceName) return { covered: false, family: 'unknown' };
+  for (const e of SERVICE_DIMENSION) {
+    if (e.match.test(serviceName)) {
+      if (e.dim && activeDims.has(e.dim)) return { covered: true, dim: e.dim };
+      return { covered: false, family: e.family ?? 'unknown', actionable: e.actionable ?? true };
+    }
+  }
+  return { covered: false, family: 'unknown', actionable: true };
+}
+
+export function computeCostCoverage(usage, gates) {
+  const services = Array.isArray(usage?.services) ? usage.services : [];
+  const activeDims = new Set(
+    (gates ?? [])
+      .map((g) => g?.metadata?.billingDimension)
+      .filter((d) => typeof d === 'string' && d !== 'mixed')
+  );
+  let total = 0;
+  let covered = 0;
+  let uncovered = 0;
+  const byFamily = new Map();
+
+  for (const s of services) {
+    const billed = Number(s.billedCost ?? 0);
+    if (!Number.isFinite(billed) || billed <= 0) continue;
+    total += billed;
+    const c = classifyService(s.name, activeDims);
+    if (c.covered) {
+      covered += billed;
+      continue;
+    }
+    uncovered += billed;
+    const key = c.family;
+    const prev = byFamily.get(key) ?? { family: key, billed: 0, services: [], actionable: c.actionable !== false };
+    prev.billed += billed;
+    prev.services.push({ name: s.name, billed });
+    prev.actionable = prev.actionable && (c.actionable !== false);
+    byFamily.set(key, prev);
+  }
+
+  const uncoveredByFamily = [...byFamily.values()]
+    .sort((a, b) => b.billed - a.billed)
+    .map((f) => ({ ...f, services: f.services.sort((a, b) => b.billed - a.billed) }));
+
+  // Pick top gaps globally so multiple families surface (Sandbox + AI Gateway + Build, not 5 Sandbox sub-services). Exclude fixed costs — seats aren't actionable workload.
+  const allActionableServices = [];
+  for (const family of uncoveredByFamily) {
+    if (!family.actionable) continue;
+    for (const s of family.services) {
+      allActionableServices.push({ name: s.name, billed: s.billed, family: family.family });
+    }
+  }
+  allActionableServices.sort((a, b) => b.billed - a.billed);
+  const topGaps = allActionableServices.slice(0, 5).map((s) => ({
+    ...s,
+    share: total > 0 ? s.billed / total : 0,
+  }));
+  return { totalBilled: total, coveredBilled: covered, uncoveredBilled: uncovered, uncoveredByFamily, topGaps };
+}
+
+export function renderCostCoverageMarkdown(coverage) {
+  if (!coverage || !Number.isFinite(coverage.totalBilled) || coverage.totalBilled <= 0) return [];
+  const { totalBilled, coveredBilled, uncoveredBilled, topGaps } = coverage;
+  const actionableGaps = topGaps.filter((g) => g.share >= 0.01); // 1%+ share
+  if (actionableGaps.length === 0) return [];
+  const lines = [];
+  lines.push('');
+  lines.push('### Coverage gaps');
+  lines.push('');
+  const coveredPct = totalBilled > 0 ? (coveredBilled / totalBilled) * 100 : 0;
+  const uncoveredPct = totalBilled > 0 ? (uncoveredBilled / totalBilled) * 100 : 0;
+  lines.push(`This audit has metric coverage for **$${coveredBilled.toFixed(0)} (${coveredPct.toFixed(0)}%)** of this bill via function-duration, edge-requests, ISR, middleware, and image-optimization dimensions. **$${uncoveredBilled.toFixed(0)} (${uncoveredPct.toFixed(0)}%)** sits in billed areas this run cannot analyze safely, including the top actionable items below:`);
+  lines.push('');
+  lines.push('| Service | Billed | Share | Family | Coverage |');
+  lines.push('|---|---|---|---|---|');
+  for (const g of actionableGaps) {
+    lines.push(`| ${escapeCell(g.name)} | $${g.billed.toFixed(2)} | ${(g.share * 100).toFixed(1)}% | ${g.family} | _not analyzed in this run_ |`);
+  }
+  lines.push('');
+  lines.push('_Recommendations in this report address the covered dimensions. The uncovered rows are not ignored; they need a separate investigation before we can make safe recommendations._');
+  return lines;
+}
+
+function escapeCell(s) {
+  return String(s ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
diff --git a/skills/vercel/vercel-optimize/lib/dedup-recs.mjs b/skills/vercel/vercel-optimize/lib/dedup-recs.mjs
new file mode 100644
index 0000000..c5e30c2
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/dedup-recs.mjs
@@ -0,0 +1,325 @@
+const NO_VALUE = '<none>';
+
+export function dedupeRecommendations(recommendations = []) {
+  if (!Array.isArray(recommendations)) {
+    throw new TypeError('dedupeRecommendations recommendations must be an array');
+  }
+
+  const byKey = new Map();
+  const order = [];
+  for (const rec of recommendations) {
+    if (!rec || typeof rec !== 'object' || rec.abstain === true) {
+      order.push(rec);
+      continue;
+    }
+
+    const key = recommendationKey(rec);
+    if (!byKey.has(key)) {
+      const normalized = withDedupMetadata(rec);
+      byKey.set(key, normalized);
+      order.push({ __dedupKey: key });
+      continue;
+    }
+
+    const current = byKey.get(key);
+    const merged = mergeDuplicateRecs(current, rec);
+    byKey.set(key, merged);
+  }
+
+  return order.map((entry) => entry?.__dedupKey ? byKey.get(entry.__dedupKey) : entry);
+}
+
+export function recommendationKey(rec) {
+  const intent = dedupIntent(rec);
+  const bucket = intent === 'cache-control:s-maxage'
+    ? NO_VALUE
+    : String(rec?.bucket ?? NO_VALUE);
+  return JSON.stringify([
+    bucket,
+    dedupEditTarget(rec),
+    primarySkillRule(rec),
+    intent,
+  ]);
+}
+
+export function normalizePath(path) {
+  if (typeof path !== 'string' || path.trim() === '') return NO_VALUE;
+  return path
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+/g, '/')
+    .replace(/:(\d+)(?::\d+)?$/, '');
+}
+
+export function primarySkillRule(rec) {
+  const citations = Array.isArray(rec?.citations) ? rec.citations : [];
+  return citations.find((c) => typeof c === 'string' && /^[A-Za-z][\w-]*:[A-Za-z][\w-]*$/.test(c)) ?? NO_VALUE;
+}
+
+export function fixShape(rec) {
+  if (typeof rec?.fixShape === 'string' && rec.fixShape.trim()) {
+    return normalizeFixText(rec.fixShape);
+  }
+  const primaryText = [rec?.fix, rec?.desiredBehavior]
+    .filter((v) => typeof v === 'string' && v.trim())
+    .join('\n');
+  const text = primaryText || rec?.what;
+  return normalizeFixText(text);
+}
+
+export function dedupIntent(rec) {
+  if (isSMaxageCacheHeaderRec(rec)) return 'cache-control:s-maxage';
+  if (isCacheLifeRec(rec)) return cacheLifeIntent(rec);
+  const sharedFunction = sharedFunctionTarget(rec);
+  if (sharedFunction) return `parallel-shared-helper:${sharedFunction}`;
+  return fixShape(rec);
+}
+
+export function dedupEditTarget(rec) {
+  return sharedFunctionTarget(rec) ?? normalizePath(firstAffectedFile(rec));
+}
+
+function firstAffectedFile(rec) {
+  const direct = affectedFiles(rec);
+  const editTarget = referencedCodeFiles(rec, ['fix', 'desiredBehavior', 'currentBehavior'])[0];
+  if (editTarget) return editTarget;
+  const referenced = referencedCodeFiles(rec)
+    .find((file) => direct.includes(file));
+  if (referenced) return referenced;
+  return Array.isArray(rec?.affectedFiles) ? rec.affectedFiles[0] : null;
+}
+
+function affectedFiles(rec) {
+  return Array.isArray(rec?.affectedFiles)
+    ? rec.affectedFiles.map(normalizePath).filter((file) => file !== NO_VALUE)
+    : [];
+}
+
+function referencedCodeFiles(rec, fields = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior', 'verify']) {
+  const text = fields
+    .map((field) => rec?.[field])
+    .filter((v) => typeof v === 'string' && v.trim())
+    .join('\n');
+  const matches = text.match(/(?:^|[\s`'"(])((?:\.{1,2}\/|[A-Za-z0-9_.@-]+\/)[A-Za-z0-9_./@[\]()-]+\.(?:mjs|cjs|js|jsx|ts|tsx))/g) ?? [];
+  return unique(matches.map((m) =>
+    normalizePath(m.replace(/^[\s`'"(]+/, ''))
+  ).filter((file) => file !== NO_VALUE));
+}
+
+function isSMaxageCacheHeaderRec(rec) {
+  const text = [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.desiredBehavior,
+    ...(Array.isArray(rec?.citations) ? rec.citations : []),
+  ].filter(Boolean).join('\n');
+  return /\bs-maxage\b/i.test(text) &&
+    /\b(?:Cache-Control|CDN cache|cdn-cache|caching\/cdn-cache)\b/i.test(text);
+}
+
+function isCacheLifeRec(rec) {
+  const text = [
+    rec?.candidateRef,
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.desiredBehavior,
+    ...(Array.isArray(rec?.citations) ? rec.citations : []),
+  ].filter(Boolean).join('\n');
+  return /^isr_overrevalidation:/.test(String(rec?.candidateRef ?? '')) &&
+    /\bcacheLife\s*\(|\bcacheLife\b/i.test(text);
+}
+
+function sharedFunctionTarget(rec) {
+  const rule = primarySkillRule(rec);
+  if (!/(?:^|:)async-parallel$|(?:^|:)server-parallel-fetching$|(?:^|:)async-suspense-boundaries$/.test(rule)) {
+    return null;
+  }
+  const text = [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.currentBehavior,
+    rec?.desiredBehavior,
+  ].filter((v) => typeof v === 'string' && v.trim()).join('\n');
+  const names = [
+    ...text.matchAll(/\b(?:get|fetch|load|read|render|create|generate|filter|resolve)[A-Z][A-Za-z0-9_]*\b/g),
+  ].map((m) => m[0]);
+  const stop = new Set([
+    'getPayload',
+    'draftMode',
+    'notFound',
+    'redirect',
+    'Promise',
+    'Response',
+    'NextResponse',
+  ]);
+  const candidates = names.filter((name) => !stop.has(name));
+  if (candidates.length === 0) return null;
+  const score = new Map();
+  for (const name of candidates) {
+    score.set(name, (score.get(name) ?? 0) + 1);
+  }
+  return [...score.entries()]
+    .sort((a, b) => b[1] - a[1] || text.indexOf(a[0]) - text.indexOf(b[0]))
+    .map(([name]) => `function:${name}`)[0] ?? null;
+}
+
+function cacheLifeIntent(rec) {
+  const text = [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.desiredBehavior,
+    rec?.verify,
+  ].filter(Boolean).join('\n');
+  const profiles = unique(
+    [...text.matchAll(/\bcacheLife\s*\(\s*['"`]([^'"`]+)['"`]/g)]
+      .map((m) => m[1])
+  );
+  const tags = unique([
+    ...[...text.matchAll(/\bcacheTag\s*\(([^)]*)\)/gs)].flatMap((m) => {
+      const args = m[1] ?? '';
+      return [
+        ...[...args.matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]),
+        ...[...args.matchAll(/`([^`]+)`/g)].map((x) => x[1].includes('${') ? `${x[1].split('${')[0]}*` : x[1]),
+      ];
+    }),
+  ]);
+  const invalidation = /\b(?:revalidateTag|updateTag)\s*\(/.test(text) ? 'with-invalidation-api' : 'no-invalidation-api';
+  return [
+    'next-cache:cache-life',
+    profiles.join('|') || NO_VALUE,
+    tags.join('|') || NO_VALUE,
+    invalidation,
+  ].join(':');
+}
+
+function unique(values) {
+  return Array.from(new Set(values.filter((v) => typeof v === 'string' && v.trim()).map((v) => v.trim()))).sort();
+}
+
+function normalizeFixText(text) {
+  if (typeof text !== 'string' || text.trim() === '') return NO_VALUE;
+  return text
+    .toLowerCase()
+    .replace(/```[\s\S]*?```/g, ' codeblock ')
+    .replace(/`[^`]*`/g, ' code ')
+    .replace(/\b\d+(?:\.\d+)?(?:ms|s|%|kb|mb|gb|k|m)?\b/g, '#')
+    .replace(/[^a-z0-9#]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .slice(0, 80)
+    .join(' ') || NO_VALUE;
+}
+
+function withDedupMetadata(rec) {
+  const existing = normalizedAppliesAlsoTo(rec.appliesAlsoTo);
+  const count = Math.max(
+    numericCount(rec.corroborationCount),
+    1 + existing.length,
+  );
+  return existing.length > 0 || count > 1
+    ? { ...rec, appliesAlsoTo: existing, corroborationCount: count }
+    : { ...rec };
+}
+
+function mergeDuplicateRecs(a, b) {
+  const aScore = recScore(a);
+  const bScore = recScore(b);
+  const winner = bScore > aScore ? b : a;
+  const loser = winner === a ? b : a;
+  const winnerExisting = normalizedAppliesAlsoTo(winner.appliesAlsoTo);
+  const loserExisting = normalizedAppliesAlsoTo(loser.appliesAlsoTo);
+  const appliesAlsoTo = uniqueAppliesAlsoTo([
+    ...winnerExisting,
+    appliesAlsoEntry(loser),
+    ...loserExisting,
+  ]);
+  const corroborationCount =
+    numericCount(winner.corroborationCount) + numericCount(loser.corroborationCount);
+  return {
+    ...winner,
+    appliesAlsoTo,
+    corroborationCount: Math.max(corroborationCount, 1 + appliesAlsoTo.length),
+  };
+}
+
+function recScore(rec) {
+  const priority = typeof rec?.priority === 'number' ? rec.priority : 0;
+  const quality = typeof rec?.quality?.overall === 'number' ? rec.quality.overall : 0;
+  return (priority * 1_000_000_000_000) + signalMagnitude(rec) + quality;
+}
+
+function signalMagnitude(rec) {
+  const text = [
+    rec?.o11ySignal,
+    rec?.why,
+    rec?.what,
+    rec?.impact,
+  ].filter((v) => typeof v === 'string' && v.trim()).join('\n');
+  const inv = parseNumber(text, /(?:inv|invocations?|function invocations?|requests?)[:=]\s*([\d,]+)/i);
+  const p95 = parseNumber(text, /(?:p95|95th percentile(?: duration)?)[:=]?\s*([\d,]+)\s*ms/i);
+  const errors = parseNumber(text, /(?:errs|errors?)[:=]\s*([\d,]+)/i);
+  const writes = parseNumber(text, /writes[:=]\s*([\d,]+)/i);
+  const reads = parseNumber(text, /reads[:=]\s*([\d,]+)/i);
+  if (inv != null && p95 != null) return inv * p95;
+  if (errors != null) return errors;
+  if (writes != null && reads != null) return writes + reads;
+  if (inv != null) return inv;
+  return 0;
+}
+
+function parseNumber(text, re) {
+  const match = re.exec(text);
+  if (!match) return null;
+  const value = Number(String(match[1]).replace(/,/g, ''));
+  return Number.isFinite(value) ? value : null;
+}
+
+function numericCount(value) {
+  return Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+function appliesAlsoEntry(rec) {
+  return {
+    candidateRef: rec?.candidateRef ?? null,
+    affectedFiles: Array.isArray(rec?.affectedFiles)
+      ? rec.affectedFiles.map(normalizePath).filter((p) => p !== NO_VALUE)
+      : [],
+    o11ySignal: rec?.o11ySignal ?? null,
+    what: rec?.what ?? null,
+  };
+}
+
+function normalizedAppliesAlsoTo(entries) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .filter((e) => e && typeof e === 'object')
+    .map((e) => ({
+      candidateRef: e.candidateRef ?? null,
+      affectedFiles: Array.isArray(e.affectedFiles)
+        ? e.affectedFiles.map(normalizePath).filter((p) => p !== NO_VALUE)
+        : [],
+      o11ySignal: e.o11ySignal ?? null,
+      what: e.what ?? null,
+    }));
+}
+
+function uniqueAppliesAlsoTo(entries) {
+  const seen = new Set();
+  const out = [];
+  for (const entry of entries) {
+    const key = JSON.stringify([
+      entry.candidateRef ?? NO_VALUE,
+      entry.affectedFiles?.join(',') ?? NO_VALUE,
+      entry.what ?? NO_VALUE,
+    ]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(entry);
+  }
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/deep-dive.mjs b/skills/vercel/vercel-optimize/lib/deep-dive.mjs
new file mode 100644
index 0000000..3d1c02e
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/deep-dive.mjs
@@ -0,0 +1,350 @@
+// Per-candidate deep-dive query specs. Runs after gate, before sub-agent reads source.
+//
+// CLI quirks:
+//   - Multi `-a` flag is NOT supported. One percentile per query.
+//   - External-API "calling route" dim is `origin_route` (NOT `route`).
+
+// Same window as broad pass so rolls are comparable.
+import { TIME_WINDOW } from './queries.mjs';
+
+export { TIME_WINDOW };
+
+// Per-query is scoped to one route/hostname, so cardinality stays small — higher than broad-pass caps.
+const DEPLOYMENT_LIMIT = 10;
+const ERROR_DEPLOYMENT_LIMIT = 30;
+const ERROR_CODE_LIMIT = 50;
+const WAF_RULE_LIMIT = 20;
+const MIDDLEWARE_PATH_LIMIT = 50;
+const CALLER_LIMIT = 20;
+
+// OData escapes a literal `'` inside a string by doubling it (`it's` → `it''s`).
+export function escapeODataString(s) {
+  if (typeof s !== 'string') return '';
+  return s.replace(/'/g, "''");
+}
+
+export function odataEq(dim, value) {
+  return `${dim} eq '${escapeODataString(value)}'`;
+}
+
+export function odataAnd(...conds) {
+  return conds.filter(Boolean).join(' and ');
+}
+
+export const SPEC_GENERATORS = {
+  slow_route(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    // cacheBreakdown/bandwidthByCache let sub-agent see miss-path cost on static routes (dynamic='error' can still show p95=900ms over millions of requests).
+    return [
+      ...latencyPercentiles('latency', 'vercel.function_invocation.function_duration_ms', f),
+      ...latencyPercentiles('ttfb', 'vercel.function_invocation.ttfb_ms', f),
+      ...latencyPercentiles('cpu', 'vercel.function_invocation.function_cpu_time_ms', f, ['p95']),
+      {
+        id: 'startTypeSplit',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['function_start_type'],
+        filter: f,
+        broadPassEquivalent: { key: 'fnStartTypeByRoute', routeFilter: route, projectDims: ['function_start_type'] },
+      },
+      // function-invocation status (5xx from function) — distinct from request-level status, can't reuse broad-pass.
+      {
+        id: 'statusDistribution',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['http_status'],
+        filter: f,
+      },
+      {
+        id: 'perDeployment',
+        metricId: 'vercel.function_invocation.function_duration_ms',
+        aggregation: 'p95',
+        groupBy: ['deployment_id'],
+        filter: f,
+        limit: DEPLOYMENT_LIMIT,
+      },
+      {
+        id: 'cacheBreakdown',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+        broadPassEquivalent: { key: 'requestsByRouteCache', routeFilter: route, projectDims: ['cache_result'] },
+      },
+      // broad-pass bandwidthByCacheResult is account-wide, so per-route still required.
+      {
+        id: 'bandwidthByCache',
+        metricId: 'vercel.request.fdt_total_bytes',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+    ];
+  },
+
+  uncached_route(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'cacheBreakdown',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+        broadPassEquivalent: { key: 'requestsByRouteCache', routeFilter: route, projectDims: ['cache_result'] },
+      },
+      {
+        id: 'methodDistribution',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['request_method'],
+        filter: f,
+        broadPassEquivalent: { key: 'requestsByRouteMethod', routeFilter: route, projectDims: ['request_method'] },
+      },
+      {
+        id: 'botShare',
+        metricId: 'vercel.request.fdt_total_bytes',
+        aggregation: 'sum',
+        groupBy: ['bot_category'],
+        filter: f,
+      },
+      {
+        id: 'bandwidthByCache',
+        metricId: 'vercel.request.fdt_total_bytes',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+    ];
+  },
+
+  cold_start(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'startTypeSplit',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['function_start_type'],
+        filter: f,
+      },
+      {
+        id: 'coldVsWarmLatencyP95',
+        metricId: 'vercel.function_invocation.function_duration_ms',
+        aggregation: 'p95',
+        groupBy: ['function_start_type'],
+        filter: f,
+      },
+      {
+        id: 'coldByDeployment',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['deployment_id'],
+        filter: odataAnd(f, odataEq('function_start_type', 'cold')),
+        limit: DEPLOYMENT_LIMIT,
+      },
+    ];
+  },
+
+  route_errors(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'errorStatusPattern',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['http_status'],
+        filter: odataAnd(f, "http_status ge '500'"),
+      },
+      {
+        id: 'errorCodes',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['error_code'],
+        filter: f,
+        limit: ERROR_CODE_LIMIT,
+      },
+      {
+        id: 'errorsByDeployment',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['deployment_id', 'http_status'],
+        filter: f,
+        limit: ERROR_DEPLOYMENT_LIMIT,
+      },
+    ];
+  },
+
+  external_api_slow(c) {
+    const host = c.hostname;
+    if (!host) return [];
+    const f = odataEq('origin_hostname', host);
+    return [
+      ...latencyPercentiles('latency', 'vercel.external_api_request.request_duration_ms', f),
+      {
+        // "calling route" dim is origin_route (verified via metrics schema).
+        id: 'callersByRoute',
+        metricId: 'vercel.external_api_request.count',
+        aggregation: 'sum',
+        groupBy: ['origin_route'],
+        filter: f,
+        limit: CALLER_LIMIT,
+      },
+      {
+        id: 'transferBytes',
+        metricId: 'vercel.external_api_request.transfer_bytes',
+        aggregation: 'sum',
+        groupBy: [],
+        filter: f,
+      },
+    ];
+  },
+
+  isr_overrevalidation(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'writePattern',
+        metricId: 'vercel.isr_operation.write_units',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+      {
+        id: 'readPattern',
+        metricId: 'vercel.isr_operation.read_units',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+    ];
+  },
+
+  cwv_poor(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      ...latencyPercentiles('lcp', 'vercel.speed_insights_metric.lcp', f, ['p50', 'p75', 'p95']),
+      ...latencyPercentiles('inp', 'vercel.speed_insights_metric.inp', f, ['p50', 'p75', 'p95']),
+      ...latencyPercentiles('cls', 'vercel.speed_insights_metric.cls', f, ['p50', 'p75', 'p95']),
+    ];
+  },
+
+  middleware_heavy(_c) {
+    // Account-scope. Surface top middleware-paths so recommender has named targets.
+    return [
+      {
+        id: 'topMiddlewarePaths',
+        metricId: 'vercel.middleware_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['request_path'],
+        limit: MIDDLEWARE_PATH_LIMIT,
+      },
+    ];
+  },
+
+  platform_fluid_compute(_c) {
+    // Broad-pass fnStartTypeByRoute already covers this account-scope rec; runner notes reuse.
+    return [];
+  },
+
+  platform_bot_protection(_c) {
+    return [
+      {
+        id: 'wafRuleFirings',
+        metricId: 'vercel.firewall_action.count',
+        aggregation: 'sum',
+        groupBy: ['waf_rule_id'],
+        limit: WAF_RULE_LIMIT,
+      },
+    ];
+  },
+
+  observability_events_attribution(_c) {
+    // Account-scope billing signal; broad-pass usage and existing route/cache/middleware metrics carry the evidence.
+    return [];
+  },
+
+  usage_spike_triage(_c) {
+    // Daily billing breakdown is already in the gate evidence; no per-candidate metrics query exists.
+    return [];
+  },
+
+  build_minutes_fanout(_c) {
+    // Account-scope billing signal + scanner findings carry the evidence; no per-candidate query.
+    return [];
+  },
+
+  region_misconfig(_c) {
+    // Branch 2 (scanner-only) — per-region TTFB metric unavailable today, so no deep-dive query.
+    return [];
+  },
+};
+
+// Scanner-driven kinds skip deep-dive — evidence already in scanner findings (file + line).
+export const SCANNER_KINDS = new Set([
+  'image_optimization',
+  'cache_header_gap',
+  'rendering_candidate',
+  'use_cache_date_stamp',
+  'cache_components_suspense_dedupe',
+]);
+
+export function specsForCandidate(candidate) {
+  const kind = candidate?.kind;
+  if (!kind) return [];
+  if (SCANNER_KINDS.has(kind)) return [];
+  const gen = SPEC_GENERATORS[kind];
+  if (!gen) return [];
+  return gen(candidate).map((s) => ({ since: TIME_WINDOW, ...s }));
+}
+
+// One spec per percentile — CLI does not support `-a p50 -a p95` multi-aggregation.
+function latencyPercentiles(idPrefix, metricId, filter, percentiles = ['p50', 'p75', 'p95', 'p99']) {
+  return percentiles.map((p) => ({
+    id: `${idPrefix}.${p}`,
+    metricId,
+    aggregation: p,
+    groupBy: [],
+    filter,
+  }));
+}
+
+// Dot-notation spec ids (`latency.p95`) nest under their group prefix.
+export function mergeIntoEvidence(results) {
+  const out = {};
+  for (const r of results) {
+    const id = r?.spec?.id;
+    if (!id) continue;
+    const dot = id.indexOf('.');
+    if (dot > -1) {
+      const head = id.slice(0, dot);
+      const leaf = id.slice(dot + 1);
+      if (!out[head]) out[head] = {};
+      out[head][leaf] = simplify(r);
+    } else {
+      out[id] = simplify(r);
+    }
+  }
+  return out;
+}
+
+// Avoid leaking raw CLI payload / candidate+spec wrapper into evidence — keep summary-only.
+function simplify(r) {
+  if (!r || r.ok === false) return { error: r?.error ?? 'unknown' };
+  // Check rows before value so tabular results with both stay tabular.
+  if (Array.isArray(r.rows)) return r.rows;
+  if ('value' in r) return r.value;
+  return null;
+}
diff --git a/skills/vercel/vercel-optimize/lib/display-labels.mjs b/skills/vercel/vercel-optimize/lib/display-labels.mjs
new file mode 100644
index 0000000..e8f90f8
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/display-labels.mjs
@@ -0,0 +1,185 @@
+import { canonicalizeRoute } from './route-normalize.mjs';
+
+const KIND_LABELS = new Map([
+  ['slow_route', 'Slow route'],
+  ['uncached_route', 'Low cache-hit route'],
+  ['cold_start', 'Cold starts'],
+  ['route_errors', 'Route errors'],
+  ['cache_header_gap', 'Missing cache headers'],
+  ['image_optimization', 'Image optimization'],
+  ['external_api_slow', 'Slow external API'],
+  ['isr_overrevalidation', 'ISR over-revalidation'],
+  ['middleware_heavy', 'Heavy middleware'],
+  ['cwv_poor', 'Poor Core Web Vitals'],
+  ['platform_fluid_compute', 'Fluid Compute usage'],
+  ['platform_bot_protection', 'Bot traffic'],
+  ['rendering_candidate', 'Rendering opportunity'],
+  ['missing_cache_headers', 'Missing cache headers'],
+  ['max_age_without_s_maxage', 'Browser-only cache header'],
+  ['force_dynamic', 'Forced dynamic rendering'],
+  ['headers_in_page', 'Dynamic API in page'],
+  ['unoptimized_image', 'Image optimization gap'],
+  ['large_static_asset', 'Large static asset'],
+  ['source_maps_production', 'Production source maps'],
+  ['edge_heavy_import', 'Heavy Edge import'],
+]);
+
+const SIGNAL_LABELS = new Map([
+  ['inv', 'function invocations'],
+  ['runs', 'function invocations'],
+  ['middleware_inv', 'middleware invocations'],
+  ['total_req', 'total requests'],
+  ['requests', 'requests'],
+  ['p95', '95th percentile duration'],
+  ['p75', '75th percentile duration'],
+  ['5xx', '5xx error rate'],
+  ['errs', '5xx errors'],
+  ['rate', '5xx error rate'],
+  ['cache', 'cache hit rate'],
+  ['get', 'GET request share'],
+  ['cold', 'cold start rate'],
+  ['writes', 'ISR write units'],
+  ['reads', 'ISR read units'],
+  ['w/r', 'ISR writes per read'],
+  ['ratio', 'ratio'],
+  ['host', 'host'],
+  ['calls', 'external API calls'],
+  ['edge_cost', 'Edge Request cost units'],
+  ['bot_protection', 'Bot Protection'],
+  ['bot_fdt_pct', 'bot Fast Data Transfer share'],
+  ['LCP', 'Largest Contentful Paint (LCP)'],
+  ['INP', 'Interaction to Next Paint (INP)'],
+  ['CLS', 'Cumulative Layout Shift (CLS)'],
+]);
+
+const REQUEST_COUNT_KINDS = new Set([
+  'uncached_route',
+]);
+
+const PUBLIC_ASSIGNMENT_LABELS = new Map([
+  ...SIGNAL_LABELS,
+  ['deepDive.latency.p95', 'deepDive latency p95'],
+  ['deepDive.cpu.p95', 'deepDive CPU p95'],
+  ['deepDive.ttfb.p95', 'deepDive TTFB p95'],
+  ['cpu.p95', 'CPU p95'],
+  ['latency.p95', 'latency p95'],
+  ['ttfb.p95', 'TTFB p95'],
+  ['cache_result', 'cache result'],
+  ['http_status', 'HTTP status'],
+  ['error_code', 'error code'],
+  ['status', 'status'],
+  ['count', 'count'],
+]);
+
+export function formatKind(kind) {
+  if (!kind) return 'Candidate';
+  if (KIND_LABELS.has(kind)) return KIND_LABELS.get(kind);
+  return String(kind)
+    .split(/[_-]+/g)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ') || 'Candidate';
+}
+
+export function formatRoute(candidate) {
+  const route = candidate?.displayRoute ?? candidate?.route ?? candidate?.hostname ?? null;
+  if (route) return String(canonicalizeRoute(route));
+  if (Array.isArray(candidate?.files) && candidate.files.length > 0) return candidate.files[0];
+  return 'account-wide';
+}
+
+export function formatSignal(signal, context = {}) {
+  if (typeof signal !== 'string' || signal.trim() === '') return 'no signal recorded';
+
+  const parts = signal
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => formatSignalPart(part, context));
+
+  return parts.length > 0 ? parts.join('; ') : signal;
+}
+
+export function formatPublicText(value) {
+  if (value == null) return '';
+  return normalizeObservedWindowUnits(String(value))
+    .replace(/\bo11y\b/gi, 'observability')
+    .replace(/\bcache[- ]components gotcha\b/gi, 'Cache Components edge case')
+    .replace(/\bcache_result\b(?!\s*=)/g, 'cache result')
+    .replace(/\bhttp_status\b(?!\s*=)/g, 'HTTP status')
+    .replace(/\berror_code\b(?!\s*=)/g, 'error code')
+    .replace(/,(?=\s*([A-Za-z0-9][\w./-]*)=)/g, (match, key) =>
+      PUBLIC_ASSIGNMENT_LABELS.has(key) ? '; ' : match
+    )
+    .replace(/\b([A-Za-z0-9][\w./-]*)=([^,;\s]+)/g, (match, key, rawValue) => {
+      const label = PUBLIC_ASSIGNMENT_LABELS.get(key);
+      if (!label) return match;
+      return `${label}: ${formatSignalValue(key, rawValue)}`;
+    })
+    .replace(/\b(cache breakdown[^.!?\n;]{0,160}?)\b(?:function\s+)?invocations\b/gi, (match, prefix) =>
+      /\bstatus distribution\b/i.test(prefix) ? match : `${prefix}requests`
+    )
+    .replace(/\b(cache breakdown[^.!?\n;]{0,220}?\bout of\s+[\d,]+)\s+invocations\b/gi, '$1 requests')
+    .replace(/\b(cache hits over\s+[\d,.]+(?:\s?(?:K|M|B))?)\s+invocations\b/gi, '$1 requests')
+    .replace(/\b(?:function\s+)?invocations\b([^.!?\n;]{0,120}\b(?:empty\s+)?cache result(?: label)?\b)/gi, 'requests$1');
+}
+
+export function normalizeObservedWindowUnits(value) {
+  if (value == null) return '';
+  return String(value)
+    .replace(/(?<!\$)\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/mo\b/gi, '$1/window')
+    .replace(/\bmonthly\s+function\s+invocations\b/gi, 'function invocations/window')
+    .replace(/\b(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\/mo\b/gi, '$1/window')
+    .replace(/\bmonthly\s+(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\b/gi, '$1/window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+function\s+invocations\s+per month\b/gi, '$1 function invocations/window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+(requests?|GETs|invocations?|bytes|writes?|reads?|errors?)\s+per month\b/gi, '$1 $2/window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/window\s+(requests?|GETs|(?:function\s+)?invocations?|bytes|egress|bandwidth|writes?|reads?|errors?)\b/gi, '$1 $2 in this window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+(requests?|GETs|(?:function\s+)?invocations?|bytes|egress|bandwidth|writes?|reads?|errors?)\/window\b/gi, '$1 $2 in this window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/window\b/gi, '$1 in this window')
+    .replace(/\b(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\/window\b/gi, '$1 in this window');
+}
+
+export function formatCandidateLine(candidate) {
+  return `${formatKind(candidate?.kind)} on ${formatRoute(candidate)} - ${formatSignal(candidate?.o11ySignal, candidate)}`;
+}
+
+export function formatCandidateLabel(candidate) {
+  return `${formatKind(candidate?.kind)} on ${formatRoute(candidate)}`;
+}
+
+function formatSignalPart(part, context = {}) {
+  const eq = part.indexOf('=');
+  if (eq === -1) return part;
+
+  const key = part.slice(0, eq).trim();
+  const value = part.slice(eq + 1).trim();
+  const label = signalLabel(key, context);
+  return `${label}: ${formatSignalValue(key, value)}`;
+}
+
+function signalLabel(key, context = {}) {
+  const kind = typeof context === 'string' ? context : context?.kind;
+  if (key === 'inv' && REQUEST_COUNT_KINDS.has(kind)) return 'requests';
+  return SIGNAL_LABELS.get(key) ?? humanizeKey(key);
+}
+
+function humanizeKey(key) {
+  return String(key)
+    .replaceAll('.', ' ')
+    .replaceAll('_', ' ')
+    .replaceAll('-', ' ')
+    .trim();
+}
+
+function formatSignalValue(key, value) {
+  if (key === 'inv' || key === 'runs' || key === 'middleware_inv' || key === 'total_req' || key === 'requests' || key === 'calls' || key === 'errs' || key === 'writes' || key === 'reads') {
+    return formatNumberLike(value);
+  }
+  return value;
+}
+
+function formatNumberLike(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return value;
+  return new Intl.NumberFormat('en-US', { maximumFractionDigits: 2 }).format(n);
+}
diff --git a/skills/vercel/vercel-optimize/lib/extract-claims.mjs b/skills/vercel/vercel-optimize/lib/extract-claims.mjs
new file mode 100644
index 0000000..6ddecfd
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/extract-claims.mjs
@@ -0,0 +1,550 @@
+// Extract mechanically-verifiable claims from a rec without parsing LLM prose. High precision, not recall.
+
+export function extractClaims(rec, ctx = {}) {
+  const claims = [];
+  const repoRoot = ctx.repoRoot;
+  const projectRootDirectory = normalizeProjectRootDirectory(ctx.projectRootDirectory);
+  const framework = ctx.framework;
+  const frameworkVersion = ctx.version;
+  const cacheComponents = ctx.cacheComponents;
+  const signals = ctx.signals;
+  const projectFacts = Array.isArray(ctx.projectFacts) ? ctx.projectFacts : [];
+
+  // One synthetic claim asserts rec doesn't contradict any already-on project fact (Fluid, in-function concurrency, …).
+  if (projectFacts.length > 0) {
+    claims.push({
+      type: 'does_not_contradict_project_config',
+      rec,
+      projectFacts,
+      sourceField: 'projectFacts',
+    });
+  }
+
+  for (const cite of asArray(rec.citations)) {
+    // Skill-rule refs are filtered upstream — skip version check.
+    if (/^[\w-]+:[\w-]+$/.test(cite)) {
+      claims.push({ type: 'citation_in_library', url: cite, sourceField: 'citations' });
+      continue;
+    }
+    claims.push({ type: 'citation_in_library', url: cite, sourceField: 'citations' });
+    if (framework && frameworkVersion) {
+      claims.push({
+        type: 'citation_applies_to_version',
+        url: cite,
+        framework,
+        frameworkVersion,
+        sourceField: 'citations',
+      });
+    }
+  }
+
+  for (const f of asArray(rec.affectedFiles)) {
+    claims.push({ type: 'file_exists', file: f, repoRoot, projectRootDirectory, sourceField: 'affectedFiles' });
+  }
+
+  // findingRefs lack a pattern, so we only check file existence.
+  for (const ref of asArray(rec.findingRefs)) {
+    const m = String(ref).match(/^(.+?):\d+$/);
+    if (m && !claims.some((c) => c.type === 'file_exists' && c.file === m[1])) {
+      claims.push({ type: 'file_exists', file: m[1], repoRoot, projectRootDirectory, sourceField: 'findingRefs' });
+    }
+  }
+
+  const cacheFiles = cacheRecommendationFiles(rec);
+  if (isCacheCandidate(rec)) {
+    claims.push({
+      type: 'cache_policy_positive_or_no_ready_rec',
+      rec,
+      sourceField: 'cache-policy',
+    });
+  }
+  if (cacheFiles.length > 0) {
+    claims.push({
+      type: 'cache_vary_matches_dynamic_inputs',
+      rec,
+      files: cacheFiles,
+      repoRoot,
+      projectRootDirectory,
+      sourceField: 'cache-safety',
+    });
+    if (mentionsVaryHeader(rec)) {
+      claims.push({
+        type: 'cache_vary_cardinality_safe',
+        rec,
+        sourceField: 'cache-vary-cardinality',
+      });
+    }
+    claims.push({
+      type: 'cache_rec_not_error_dominated_or_acknowledged',
+      rec,
+      signals,
+      sourceField: 'cache-error-safety',
+    });
+    claims.push({
+      type: 'cache_control_header_syntax',
+      rec,
+      sourceField: 'cache-header-syntax',
+    });
+    claims.push({
+      type: 'cache_control_headers_citation',
+      rec,
+      sourceField: 'cache-header-citation',
+    });
+    if (mentionsCachedNotFoundOr404(rec)) {
+      claims.push({
+        type: 'cache_404_long_ttl_safety',
+        rec,
+        sourceField: 'cache-404-safety',
+      });
+    }
+  }
+
+  if (mentionsNextCachedNotFound(rec)) {
+    claims.push({
+      type: 'next_cached_not_found_causal_support',
+      rec,
+      framework,
+      frameworkVersion,
+      sourceField: 'next-cache-not-found',
+    });
+  }
+
+  if (mentionsNextStableCacheApi(rec)) {
+    claims.push({
+      type: 'next_stable_cache_api_for_version',
+      rec,
+      framework,
+      frameworkVersion,
+      sourceField: 'next-cache-api-version',
+    });
+  }
+
+  if (mentionsNext16RuntimeCacheApiMismatch(rec)) {
+    claims.push({
+      type: 'next_runtime_cache_api_for_version',
+      rec,
+      framework,
+      frameworkVersion,
+      sourceField: 'next-runtime-cache-api-version',
+    });
+  }
+
+  if (mentionsRuntimeCacheWhenCacheComponents(rec)) {
+    claims.push({
+      type: 'next_cache_components_runtime_cache_preference',
+      rec,
+      framework,
+      frameworkVersion,
+      cacheComponents,
+      sourceField: 'next-cache-components-runtime-cache-preference',
+    });
+  }
+
+  if (mentionsMultipleCacheLifeCalls(rec)) {
+    claims.push({
+      type: 'next_cache_life_single_execution',
+      rec,
+      framework,
+      frameworkVersion,
+      sourceField: 'next-cache-life-single-execution',
+    });
+  }
+
+  if (mentionsCacheLifetimeChange(rec)) {
+    claims.push({
+      type: 'next_cache_lifetime_freshness_supported',
+      rec,
+      files: recommendationFiles(rec),
+      repoRoot,
+      projectRootDirectory,
+      sourceField: 'next-cache-lifetime-freshness',
+    });
+  }
+
+  if (mentionsNextCacheComponentsStaticShellTarget(rec)) {
+    claims.push({
+      type: 'next_cache_components_route_chain_file',
+      rec,
+      framework,
+      frameworkVersion,
+      cacheComponents,
+      signals,
+      sourceField: 'next-cache-components-route-chain',
+    });
+  }
+
+  if (mentionsCacheLifeCdnHeaderClaim(rec)) {
+    claims.push({
+      type: 'next_cache_life_cdn_header_semantics',
+      rec,
+      framework,
+      frameworkVersion,
+      sourceField: 'next-cache-life-cdn-header-semantics',
+    });
+  }
+
+  if (mentionsImageResponseHeaders(rec)) {
+    claims.push({
+      type: 'image_response_headers_citation',
+      rec,
+      framework,
+      frameworkVersion,
+      sourceField: 'image-response-headers',
+    });
+  }
+
+  if (mentionsNextImagePriorityRecommendation(rec)) {
+    claims.push({
+      type: 'next_image_priority_api_for_version',
+      rec,
+      framework,
+      frameworkVersion,
+      sourceField: 'next-image-priority-api',
+    });
+  }
+
+  if (mentionsNextCacheComponentsRouteSegmentConfig(rec)) {
+    claims.push({
+      type: 'next_cache_components_route_segment_config',
+      rec,
+      framework,
+      frameworkVersion,
+      cacheComponents,
+      sourceField: 'next-route-segment-config',
+    });
+  }
+
+  if (mentionsRouteLevelRevalidate(rec)) {
+    claims.push({
+      type: 'next_route_revalidate_static_prereq',
+      rec,
+      framework,
+      frameworkVersion,
+      cacheComponents,
+      repoRoot,
+      projectRootDirectory,
+      sourceField: 'next-route-revalidate-static-prereq',
+    });
+  }
+
+  if (mentionsExistingCacheTagInvalidation(rec)) {
+    claims.push({
+      type: 'next_cache_tag_invalidation_supported',
+      rec,
+      repoRoot,
+      projectRootDirectory,
+      sourceField: 'next-cache-tag-invalidation',
+    });
+  }
+
+  if (mentionsUnsafeImmutableDynamicRoute(rec)) {
+    claims.push({
+      type: 'immutable_dynamic_route_safety',
+      rec,
+      sourceField: 'immutable-dynamic-route',
+    });
+  }
+
+  if (mentionsAuthSensitiveParallelization(rec)) {
+    claims.push({
+      type: 'auth_guard_parallelization_safety',
+      rec,
+      sourceField: 'auth-parallelization',
+    });
+  }
+
+  if (mentionsParallelizationImpactOverclaim(rec)) {
+    claims.push({
+      type: 'parallelization_impact_not_overclaimed',
+      rec,
+      sourceField: 'parallelization-impact',
+    });
+  }
+
+  if (mentionsCpuBoundParallelization(rec)) {
+    claims.push({
+      type: 'parallelization_not_cpu_bound_work',
+      rec,
+      sourceField: 'parallelization-cpu-bound',
+    });
+  }
+
+  if (mentionsRuntimeErrorCause(rec)) {
+    claims.push({
+      type: 'runtime_error_cause_supported',
+      rec,
+      sourceField: 'runtime-error-cause',
+    });
+  }
+
+  if (mentionsCatchToNotFound(rec)) {
+    claims.push({
+      type: 'route_error_not_found_status_and_scope',
+      rec,
+      sourceField: 'route-error-catch-safety',
+    });
+  }
+
+  if (mentionsIgnoredBuildStepRecommendation(rec)) {
+    claims.push({
+      type: 'vercel_ignore_command_project_state',
+      rec,
+      signals,
+      sourceField: 'ignored-build-step-state',
+    });
+  }
+
+  if (mentionsTurboBuildCacheRecommendation(rec)) {
+    claims.push({
+      type: 'turbo_build_cache_safety',
+      rec,
+      files: recommendationFiles(rec),
+      repoRoot,
+      projectRootDirectory,
+      framework,
+      sourceField: 'turbo-build-cache-safety',
+    });
+  }
+
+  for (const c of asArray(rec.verifiableClaims)) {
+    if (c && typeof c === 'object' && typeof c.type === 'string') {
+      claims.push({
+        ...c,
+        repoRoot: c.repoRoot ?? repoRoot,
+        projectRootDirectory: c.projectRootDirectory ?? projectRootDirectory,
+        sourceField: 'verifiableClaims',
+      });
+    }
+  }
+
+  return claims;
+}
+
+function normalizeProjectRootDirectory(value) {
+  if (typeof value !== 'string' || value.trim() === '') return null;
+  return value.replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+}
+
+function cacheRecommendationFiles(rec) {
+  if (!recommendsSharedCache(rec)) return [];
+  return recommendationFiles(rec);
+}
+
+function isCacheCandidate(rec) {
+  return /^(?:uncached_route|cache_header_gap):/.test(String(rec?.candidateRef ?? ''));
+}
+
+function recommendationFiles(rec) {
+  const files = [
+    ...asArray(rec.affectedFiles),
+    ...asArray(rec.findingRefs)
+      .map((ref) => String(ref).match(/^(.+?):\d+$/)?.[1])
+      .filter(Boolean),
+  ];
+  return Array.from(new Set(files));
+}
+
+function recommendsSharedCache(rec) {
+  const haystack = [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.desiredBehavior,
+    rec?.verify,
+  ].filter(Boolean).join('\n');
+  return /\b(?:s-maxage|CDN-Cache-Control|Vercel-CDN-Cache-Control|Cache-Control)\b/i.test(haystack);
+}
+
+function mentionsVaryHeader(rec) {
+  return /\bVary\b/i.test(recText(rec));
+}
+
+function mentionsNextCachedNotFound(rec) {
+  const haystack = recText(rec);
+  return /\bnotFound\b/.test(haystack) &&
+    /['"`]use cache['"`]|\buse cache\b/i.test(haystack) &&
+    /\b(?:500|5xx|error rate|errors?)\b/i.test(haystack);
+}
+
+function mentionsNextStableCacheApi(rec) {
+  const haystack = recText(rec);
+  return /\bunstable_(?:cacheLife|cacheTag)\b/.test(haystack) ||
+    /\brevalidateTag\s*\([^)]*['"`][^'"`]+['"`]\s*\)/.test(haystack);
+}
+
+function mentionsNext16RuntimeCacheApiMismatch(rec) {
+  const haystack = recText(rec);
+  const citations = asArray(rec?.citations).join('\n');
+  return /\bunstable_cache\b/.test(haystack) &&
+    (/\bRuntime Cache\b/i.test(haystack) || /vercel\.com\/docs\/caching\/runtime-cache/i.test(citations));
+}
+
+function mentionsRuntimeCacheWhenCacheComponents(rec) {
+  const haystack = recText(rec);
+  const citations = asArray(rec?.citations).join('\n');
+  return /\b(?:Runtime Cache|@vercel\/functions|getCache\s*\(|setCache\s*\()\b/i.test(haystack) ||
+    /vercel\.com\/docs\/caching\/runtime-cache/i.test(citations);
+}
+
+function mentionsMultipleCacheLifeCalls(rec) {
+  const haystack = recText(rec);
+  const matches = haystack.match(/\bcacheLife\s*\(/g) ?? [];
+  return matches.length > 1;
+}
+
+function mentionsCacheLifetimeChange(rec) {
+  return /\bcacheLife\s*\(/.test(recText(rec));
+}
+
+function mentionsCacheLifeCdnHeaderClaim(rec) {
+  const haystack = recText(rec);
+  if (!/\bcacheLife\b/.test(haystack)) return false;
+  return /\bcacheLife\b[^.\n]{0,240}\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function)\b/i.test(haystack) ||
+    /\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function)\b[^.\n]{0,240}\bcacheLife\b/i.test(haystack) ||
+    /\b(?:no|never|without|missing)\s+cacheLife\b[^.\n]{0,240}\b(?:no|not|never|0%|every|per request|function)\b[^.\n]{0,120}\b(?:cache|cached|hit|runs?|invoke)/i.test(haystack);
+}
+
+function mentionsNextCacheComponentsStaticShellTarget(rec) {
+  const haystack = recText(rec);
+  if (!/\b(?:cacheComponents|Cache Components|cacheLife|cacheTag|['"`]use cache['"`]|use cache|static shell|pre[- ]?render|prerender)\b/i.test(haystack)) {
+    return false;
+  }
+  const files = [
+    ...asArray(rec?.affectedFiles),
+    ...asArray(rec?.findingRefs).map((ref) => String(ref).match(/^(.+?):\d+$/)?.[1]).filter(Boolean),
+  ];
+  return files.some((file) => /(^|\/)layout\.(?:tsx?|jsx?)$/.test(String(file)));
+}
+
+function mentionsImageResponseHeaders(rec) {
+  const haystack = recText(rec);
+  return /\bImageResponse\b/.test(haystack) &&
+    /\bheaders?\b[\s\S]{0,200}\b(?:Cache-Control|s-maxage|CDN|response)\b|\b(?:Cache-Control|s-maxage|CDN)\b[\s\S]{0,200}\bheaders?\b/i.test(haystack);
+}
+
+function mentionsNextImagePriorityRecommendation(rec) {
+  const haystack = recText(rec);
+  if (!/\b(?:next\/image|<Image\b|Image component|image)\b/i.test(haystack)) return false;
+  if (!/\bpriority\b/i.test(haystack)) return false;
+  if (/\b(?:deprecated|replace|remove|avoid)\b[^.\n]{0,120}\bpriority\b/i.test(haystack) ||
+      /\bpriority\b[^.\n]{0,120}\b(?:deprecated|replace|remove|avoid)\b/i.test(haystack)) {
+    return false;
+  }
+  return /\b(?:set|add|use|enable|mark|make|turn on|with)\b[^.\n]{0,120}\bpriority\b/i.test(haystack) ||
+    /<Image\b[^>]*\bpriority(?:\s|=|>)/i.test(haystack);
+}
+
+function mentionsNextCacheComponentsRouteSegmentConfig(rec) {
+  const haystack = recText(rec);
+  return /\b(?:export\s+const\s+)?(?:dynamicParams|fetchCache)\s*=/.test(haystack) ||
+    /\bexport\s+const\s+(?:dynamic|revalidate)\b/.test(haystack) ||
+    /\b(?:set|add|configure|use)\s+[^.\n]{0,80}\b(?:dynamicParams|fetchCache)\b/i.test(haystack) ||
+    /\broute segment config options?\b[^.\n]{0,120}\b(?:Route Handlers?|handlers?)\b[^.\n]{0,120}\b(?:no longer apply|do not apply|removed)\b/i.test(haystack) ||
+    /\b(?:revalidate|dynamic|fetchCache)\b[^.\n]{0,80}\broute segment (?:config|export)\b/i.test(haystack);
+}
+
+function mentionsRouteLevelRevalidate(rec) {
+  const haystack = recText(rec);
+  return /\bexport\s+const\s+revalidate\b/.test(haystack) ||
+    /\broute[- ]level\s+revalidate\b/i.test(haystack) ||
+    /\brevalidate\s*(?:=|:)\s*\d+\b[^.\n]{0,120}\b(?:page|layout|route segment|segment export)\b/i.test(haystack);
+}
+
+function mentionsExistingCacheTagInvalidation(rec) {
+  const haystack = recText(rec);
+  if (!/\bcacheTag\s*\(/.test(haystack)) return false;
+  if (!/\b(?:revalidateTag|updateTag|invalidate|invalidation|revalidation|webhook|CMS|content-sync|content sync|publish|deploy)\b/i.test(haystack)) {
+    return false;
+  }
+  return /\b(?:existing|current|already|keep|keeps|preserve|preserves|continue|continues|maintain|maintains|via)\b[\s\S]{0,180}\b(?:revalidateTag|updateTag|invalidate|invalidation|revalidation|event-driven|webhook|CMS|content-sync|content sync|publish|deploy|tags?)\b/i.test(haystack) ||
+    /\b(?:invalidation|revalidation)\s+is\s+already\b/i.test(haystack) ||
+    /\balready\s+event-driven\b/i.test(haystack);
+}
+
+function mentionsUnsafeImmutableDynamicRoute(rec) {
+  const haystack = recText(rec);
+  if (!/\bimmutable\b/i.test(haystack)) return false;
+  const files = [
+    ...asArray(rec?.affectedFiles),
+    ...asArray(rec?.findingRefs).map((ref) => String(ref).match(/^(.+?):\d+$/)?.[1]).filter(Boolean),
+  ];
+  const routeHandler = files.some((file) => /(?:^|\/)route\.[cm]?[jt]sx?$/.test(String(file)));
+  const apiRoute = /^cache_header_gap:\/api\//.test(String(rec?.candidateRef ?? ''));
+  return routeHandler || apiRoute;
+}
+
+function mentionsAuthSensitiveParallelization(rec) {
+  const haystack = recText(rec);
+  if (!/\b(?:parallelize|Promise\.all|run concurrently|start .* early)\b/i.test(haystack)) return false;
+  if (!/\b(?:auth|authorize|authorization|ownership|owns|owner|private|session|permission|access)\b/i.test(haystack)) return false;
+  return /\b(?:private|secret|token|registrant|account|user|ticket|payment|session)\w*\b/i.test(haystack);
+}
+
+function mentionsParallelizationImpactOverclaim(rec) {
+  const haystack = recText(rec);
+  if (!/\b(?:parallelize|Promise\.all|run concurrently|start .* early)\b/i.test(haystack)) return false;
+  return /\b(?:drop|drops|reduce|reduces|reduction|save|saves|shave|shaves)\b[^.\n]{0,200}\b(?:roughly|approximately|about|around|equal\s+to)?\s*(?:the\s+)?(?:duration\s+of\s+[A-Za-z_$][\w$]*\s*\(\s*\)|min\s*\([^)]*duration[^)]*\)|one\s+[\w-]+\s+round[- ]trip|one\s+await|one\s+network\s+call|one\s+database\s+query)/i.test(haystack);
+}
+
+function mentionsCpuBoundParallelization(rec) {
+  const haystack = recText(rec);
+  if (!/\b(?:parallelize|Promise\.all|run concurrently|start .* early)\b/i.test(haystack)) return false;
+  return /\b(?:cpu\.p95|CPU p95|cpu p95|CPU-bound|compute-bound|in-process compute|compileMDX|MDX compilation|compilation|render compute)\b/i.test(haystack);
+}
+
+function mentionsCachedNotFoundOr404(rec) {
+  const haystack = recText(rec);
+  if (!/\b(?:s-maxage|CDN-Cache-Control|Vercel-CDN-Cache-Control|Cache-Control)\b/i.test(haystack)) return false;
+  return /\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b/i.test(haystack);
+}
+
+function mentionsRuntimeErrorCause(rec) {
+  if (!/^route_errors:/.test(String(rec?.candidateRef ?? ''))) return false;
+  const haystack = recText(rec);
+  return /\b(?:ENOENT|ETIMEDOUT|ECONNRESET|outputFileTracing|missing\s+(?:file|mdx|module)|no\s+(?:matching|corresponding)\s+(?:file|mdx|post)|does\s+not\s+exist|signature\s+of|root cause|caused by|unhandled\s+exceptions?|uncaught(?:-exception)?|throws?|bubbles?\s+to\s+the\s+runtime|reads?\s+[^.]{0,80}(?:filePath|filesystem|file system|disk)|readFile)\b/i.test(haystack);
+}
+
+function mentionsCatchToNotFound(rec) {
+  if (!/^route_errors:/.test(String(rec?.candidateRef ?? ''))) return false;
+  const haystack = recText(rec);
+  return /\bcatch\b/i.test(haystack) &&
+    /\b(?:404|not[- ]found|not found|notFound)\b/i.test(haystack);
+}
+
+function mentionsIgnoredBuildStepRecommendation(rec) {
+  const haystack = recText(rec);
+  return /\b(?:Ignored Build Step|ignoreCommand|turbo-ignore|skip unaffected|unaffected projects?)\b/i.test(haystack) &&
+    /\b(?:add|set|configure|enable|use|introduce|wire|adopt|turn on)\b[^.\n]{0,180}\b(?:Ignored Build Step|ignoreCommand|turbo-ignore|skip unaffected|unaffected projects?)\b/i.test(haystack);
+}
+
+function mentionsTurboBuildCacheRecommendation(rec) {
+  const haystack = recText(rec);
+  if (!/\b(?:Turbo|Turborepo|turbo\.json|tasks\.build|build cache|build caching)\b/i.test(haystack)) return false;
+  return /\b(?:enable|re-enable|restore|turn on|set|remove)\b[^.\n]{0,220}\b(?:cache\s*:\s*false|tasks\.build\.cache|build cache|build caching|Turbo cache|Turborepo cache)\b/i.test(haystack) ||
+    /\b(?:cache\s*:\s*false|tasks\.build\.cache|build cache|build caching|Turbo cache|Turborepo cache)\b[^.\n]{0,220}\b(?:enable|re-enable|restore|turn on|set|remove)\b/i.test(haystack);
+}
+
+function recText(rec) {
+  return [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.currentBehavior,
+    rec?.desiredBehavior,
+    rec?.verify,
+  ].filter(Boolean).join('\n');
+}
+
+function asArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+export function summarizeClaimResults(results) {
+  const counts = { verified: 0, failed: 0, unsupported: 0, unverifiable: 0 };
+  for (const r of results) {
+    if (r?.disposition && counts[r.disposition] !== undefined) counts[r.disposition]++;
+  }
+  const verifiable = counts.verified + counts.failed;
+  const passRate = verifiable > 0 ? counts.verified / verifiable : 1;
+  return { ...counts, verifiable, passRate, total: results.length };
+}
diff --git a/skills/vercel/vercel-optimize/lib/framework-support.mjs b/skills/vercel/vercel-optimize/lib/framework-support.mjs
new file mode 100644
index 0000000..79fe0a1
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/framework-support.mjs
@@ -0,0 +1,67 @@
+export const CORE_SUPPORTED_FRAMEWORKS = ['next', 'sveltekit', 'nuxt'];
+export const LIMITED_FRAMEWORKS = ['astro'];
+
+const LABELS = {
+  next: 'Next.js',
+  sveltekit: 'SvelteKit',
+  nuxt: 'Nuxt',
+  astro: 'Astro',
+  hono: 'Hono',
+  remix: 'Remix',
+  unknown: 'unknown framework',
+};
+
+export function frameworkLabel(framework) {
+  return LABELS[normalizeFramework(framework)] ?? String(framework ?? 'unknown');
+}
+
+export function classifyFrameworkSupport(stack = {}) {
+  const framework = normalizeFramework(stack.framework);
+  const label = frameworkLabel(framework);
+  const supportedLabels = CORE_SUPPORTED_FRAMEWORKS.map(frameworkLabel);
+  const limitedLabels = LIMITED_FRAMEWORKS.map(frameworkLabel);
+
+  if (CORE_SUPPORTED_FRAMEWORKS.includes(framework)) {
+    return {
+      ok: true,
+      status: 'supported',
+      blocker: null,
+      framework,
+      label,
+      supportedFrameworks: supportedLabels,
+      limitedFrameworks: limitedLabels,
+      detail: `${label} is supported for metric-backed route-to-file investigations.`,
+    };
+  }
+
+  if (LIMITED_FRAMEWORKS.includes(framework)) {
+    return {
+      ok: true,
+      status: 'limited',
+      blocker: null,
+      framework,
+      label,
+      supportedFrameworks: supportedLabels,
+      limitedFrameworks: limitedLabels,
+      detail: `${label} support is limited. The skill can use Vercel metrics and generic platform checks, but framework-specific route-to-file recommendations may be sparse.`,
+    };
+  }
+
+  return {
+    ok: false,
+    status: 'unsupported',
+    blocker: 'unsupported_framework',
+    framework,
+    label,
+    supportedFrameworks: supportedLabels,
+    limitedFrameworks: limitedLabels,
+    detail: `${label} is not supported for metric-backed route-to-file investigations. Supported frameworks: ${supportedLabels.join(', ')}. Limited support: ${limitedLabels.join(', ')}.`,
+  };
+}
+
+function normalizeFramework(value) {
+  const raw = String(value ?? 'unknown').trim().toLowerCase();
+  if (raw === 'nextjs' || raw === 'next.js') return 'next';
+  if (raw === 'svelte' || raw === 'svelte-kit') return 'sveltekit';
+  return raw || 'unknown';
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/build-minutes-fanout.mjs b/skills/vercel/vercel-optimize/lib/gates/build-minutes-fanout.mjs
new file mode 100644
index 0000000..060d3c4
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/build-minutes-fanout.mjs
@@ -0,0 +1,69 @@
+// Build Minutes climb on monorepos when Turborepo cache is bypassed or every project rebuilds on every commit.
+// Threshold: Build Minutes line > 15% of total bill OR scanner emits any turbo-force-bypass finding (even at lower share).
+// Account-scoped because the lever is project-settings (Ignored Build Step, Elastic Build Machines), not code.
+export const metadata = {
+  id: 'build_minutes_fanout',
+  threshold: 'Build Minutes share > 0.15 OR turbo-force-bypass finding present',
+  billingDimension: 'build',
+  scope: 'account',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Build Minutes line dominates the bill or Turborepo cache is bypassed. On monorepos, unchanged work should be skipped through Vercel skip-unaffected behavior, a verified Ignored Build Step, and a complete Turbo cache contract.',
+};
+
+const BUILD_RE = /^Build (CPU )?Minutes$/i;
+const SCANNER_PATTERN = 'turbo-force-bypass';
+const SHARE_FLOOR = 0.15;
+
+export function gate(signals) {
+  const services = signals?.usage?.services;
+  const total = Array.isArray(services)
+    ? services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
+    : 0;
+  const buildBilled = Array.isArray(services)
+    ? services
+        .filter((s) => BUILD_RE.test(String(s?.name ?? '')))
+        .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
+    : 0;
+
+  const buildShare = total > 0 ? buildBilled / total : 0;
+
+  const findings = (signals?.codebase?.findings ?? []).filter((f) => f.pattern === SCANNER_PATTERN);
+
+  if (buildShare <= SHARE_FLOOR && findings.length === 0) return [];
+
+  const subtypes = unique(findings.map((f) => f.subtype).filter(Boolean));
+  const sampleFiles = unique(findings.map((f) => f.file).filter(Boolean)).slice(0, 4);
+
+  const reason = findings.length > 0
+    ? (buildShare > SHARE_FLOOR
+        ? 'Build Minutes share is high and Turborepo cache bypass detected in repo'
+        : 'Turborepo cache bypass detected in repo')
+    : 'Build Minutes line exceeds 15% of total billed cost';
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: sampleFiles,
+    priority: findings.length > 0 ? 65 : 50,
+    confidence: findings.length > 0 ? 0.86 : 0.74,
+    o11ySignal: `build_minutes_share=${(buildShare * 100).toFixed(0)}% scanner_findings=${findings.length}`,
+    reason,
+    question: findings.length > 0
+      ? `Turborepo cache bypass detected (${subtypes.join(', ')}). Which build pipeline forces a rebuild on every commit, and can Ignored Build Step + cache re-enable cut the project fan-out?`
+      : 'Build Minutes exceed 15% of the bill. Is Ignored Build Step configured? Is Turborepo cache active across builds? Would Elastic Build Machines reduce duration on hot builds?',
+    evidence: {
+      metric: 'usage.services',
+      buildBilled,
+      totalBilled: total,
+      buildShare,
+      scannerFindings: findings.length,
+      scannerSubtypes: subtypes,
+      sampleFiles,
+    },
+  }];
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/cold-start.mjs b/skills/vercel/vercel-optimize/lib/gates/cold-start.mjs
new file mode 100644
index 0000000..f048151
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/cold-start.mjs
@@ -0,0 +1,66 @@
+// Signal: `function_start_type` dimension on `vercel.function_invocation.count` (cold|hot|prewarmed).
+// Threshold WHY: 40%+ cold is fixable via Fluid keep-warm; 30% is the noise floor for serverless without keep-warm.
+// total>=1000/14d (~3/hr) keeps Poisson CI on cold rate at ~±5% near the 40% threshold.
+export const metadata = {
+  id: 'cold_start',
+  threshold: 'coldPct > 0.4 AND total >= 1000',
+  billingDimension: 'function-duration',
+  scope: 'route',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Routes where > 40% of invocations are cold-start, at meaningful traffic (>=1,000 total invocations in window). Cold starts add 200-800ms per request and break the perceived latency budget on cache-miss paths. The 40% threshold is where cold-rate becomes a real signal vs Poisson noise on serverless. Sourced from vercel.function_invocation.count grouped by function_start_type.',
+};
+
+export function gate(signals) {
+  const cs = extractColdStarts(signals);
+  return cs
+    .filter((r) => r.coldPct > 0.4 && r.total >= 1000)
+    .map((r) => ({
+      kind: metadata.id,
+      scope: 'route',
+      route: r.route,
+      files: [],
+      priority: Math.round(r.total * r.coldPct),
+      confidence: 0.92,
+      o11ySignal: `cold=${(r.coldPct * 100).toFixed(0)}%,inv=${r.total}`,
+      reason: 'high cold-start rate on hot route',
+      question: `What initialization or bundle overhead makes ${r.route} cold-start ${(r.coldPct * 100).toFixed(0)}% of ${r.total} invocations?`,
+      evidence: { metric: 'fnStartTypeByRoute', route: r.route, coldPct: r.coldPct, total: r.total, coldCount: r.coldCount ?? null },
+    }));
+}
+
+function extractColdStarts(signals) {
+  const live = signals.metrics?.fnStartTypeByRoute;
+  if (Array.isArray(live?.rows) && live.rows.some((r) => 'coldCount' in r || 'coldPct' in r)) {
+    return live.rows
+      .filter((r) => r.route)
+      .map((r) => ({
+        route: r.route,
+        total: r.total ?? 0,
+        coldCount: r.coldCount ?? 0,
+        coldPct: r.coldPct ?? 0,
+      }));
+  }
+
+  // Legacy fixture: pre-derived coldStartByRoute rows.
+  const direct = signals.metrics?.coldStartByRoute;
+  if (Array.isArray(direct?.rows)) {
+    return direct.rows
+      .filter((r) => r.route)
+      .map((r) => ({ route: r.route, coldPct: r.coldPct ?? 0, total: r.total ?? 0 }));
+  }
+
+  // Older legacy fixture: series + summary shape.
+  const legacy = signals.metrics?.coldStarts;
+  if (Array.isArray(legacy?.series)) {
+    return legacy.series
+      .map((s) => {
+        const total = s.summary?.count ?? 0;
+        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
+        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
+      })
+      .filter((r) => r.route);
+  }
+
+  return [];
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/contract.mjs b/skills/vercel/vercel-optimize/lib/gates/contract.mjs
new file mode 100644
index 0000000..6044dc8
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/contract.mjs
@@ -0,0 +1,79 @@
+const VALID_SCOPES = new Set(['route', 'file', 'account']);
+
+export class CandidateContractError extends Error {
+  constructor(errors) {
+    super(`gate candidate contract failed:\n${errors.map((e) => `- ${e}`).join('\n')}`);
+    this.name = 'CandidateContractError';
+    this.errors = errors;
+  }
+}
+
+export function validateCandidates(candidates, ctx = {}) {
+  if (!Array.isArray(candidates)) {
+    throw new CandidateContractError([`${ctx.source ?? 'gate'}: expected candidate array`]);
+  }
+  const errors = [];
+  for (let i = 0; i < candidates.length; i++) {
+    errors.push(...validateCandidate(candidates[i], { ...ctx, index: i }).errors);
+  }
+  if (errors.length > 0) throw new CandidateContractError(errors);
+  return candidates;
+}
+
+export function validateCandidate(candidate, ctx = {}) {
+  const label = candidateLabel(candidate, ctx);
+  const errors = [];
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    return { ok: false, errors: [`${label}: candidate must be an object`] };
+  }
+
+  if (!nonEmptyString(candidate.kind)) errors.push(`${label}: kind must be a non-empty string`);
+  if (!VALID_SCOPES.has(candidate.scope)) {
+    errors.push(`${label}: scope must be one of route, file, account`);
+  }
+  if (!Number.isFinite(candidate.priority)) errors.push(`${label}: priority must be a finite number`);
+  if (!Number.isFinite(candidate.confidence)) errors.push(`${label}: confidence must be a finite number`);
+  if (Array.isArray(candidate.files)) {
+    if (!candidate.files.every((f) => typeof f === 'string' && f.length > 0)) {
+      errors.push(`${label}: files must contain only non-empty strings`);
+    }
+  } else {
+    errors.push(`${label}: files must be an array`);
+  }
+  if (!nonEmptyString(candidate.reason)) errors.push(`${label}: reason must be a non-empty string`);
+  if (!nonEmptyString(candidate.question)) errors.push(`${label}: question must be a non-empty string`);
+
+  if (candidate.scope === 'route') {
+    const hasRoute = nonEmptyString(candidate.route);
+    const hasHostname = nonEmptyString(candidate.hostname);
+    if (!hasRoute && !hasHostname) {
+      errors.push(`${label}: route-scoped candidates must set route or hostname`);
+    }
+  }
+  if (candidate.scope === 'file') {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: file-scoped candidates must not set route or hostname`);
+    }
+    if (!Array.isArray(candidate.files) || candidate.files.length === 0) {
+      errors.push(`${label}: file-scoped candidates must include at least one file`);
+    }
+  }
+  if (candidate.scope === 'account') {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: account-scoped candidates must not set route or hostname`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function candidateLabel(candidate, ctx) {
+  const source = ctx.source ?? 'gate';
+  const index = ctx.index == null ? '?' : ctx.index;
+  const kind = candidate?.kind ?? '?';
+  return `${source}[${index}] ${kind}`;
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/cwv-poor.mjs b/skills/vercel/vercel-optimize/lib/gates/cwv-poor.mjs
new file mode 100644
index 0000000..8eadd8d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/cwv-poor.mjs
@@ -0,0 +1,87 @@
+// Thresholds are Google's "Poor" band (https://web.dev/articles/vitals): LCP p75 > 2500ms, INP > 200ms, CLS > 0.1.
+// When Speed Insights isn't wired up the metrics come back empty and the gate is a no-op.
+import { withRouteShapeWarnings } from '../route-normalize.mjs';
+
+export const metadata = {
+  id: 'cwv_poor',
+  threshold: 'LCP p75>2500 OR INP p75>200 OR CLS p75>0.1, AND speed_insights count > 50',
+  billingDimension: 'speed-insights',
+  scope: 'route',
+  sourceCitation: 'https://web.dev/articles/vitals',
+  description:
+    'Routes where Core Web Vitals fall into Google\'s "Poor" band on real-user traffic. LCP > 2500ms, INP > 200ms, or CLS > 0.1 each hurt SEO and conversion. Surfaces one candidate per (route, metric) pair to keep recommendations focused.',
+};
+
+// Below this floor p75 is too noisy to act on.
+const MIN_PER_ROUTE_SAMPLES = 50;
+
+export function gate(signals) {
+  const totalSamples = sumRows(signals.metrics?.cwvCount?.rows);
+  if (totalSamples === 0) return [];
+
+  const countByRoute = byRoute(signals.metrics?.cwvCountByRoute?.rows);
+  const lcpBy = byRoute(signals.metrics?.cwvLcpByRoute?.rows);
+  const inpBy = byRoute(signals.metrics?.cwvInpByRoute?.rows);
+  const clsBy = byRoute(signals.metrics?.cwvClsByRoute?.rows);
+
+  const routes = new Set([...lcpBy.keys(), ...inpBy.keys(), ...clsBy.keys()]);
+  const out = [];
+  for (const route of routes) {
+    const routeSamples = countByRoute.get(route) ?? 0;
+    if (routeSamples < MIN_PER_ROUTE_SAMPLES) continue;
+    const lcp = lcpBy.get(route);
+    const inp = inpBy.get(route);
+    const cls = clsBy.get(route);
+    const issues = [];
+    if (lcp != null && lcp > 2500) issues.push({ metric: 'LCP', value: Math.round(lcp), threshold: 2500, unit: 'ms' });
+    if (inp != null && inp > 200) issues.push({ metric: 'INP', value: Math.round(inp), threshold: 200, unit: 'ms' });
+    if (cls != null && cls > 0.1) issues.push({ metric: 'CLS', value: round2(cls), threshold: 0.1, unit: '' });
+    if (issues.length === 0) continue;
+
+    const summary = issues.map((i) => `${i.metric}=${i.value}${i.unit}`).join(',');
+    out.push(withRouteShapeWarnings({
+      kind: metadata.id,
+      scope: 'route',
+      route,
+      files: [],
+      priority: issues.reduce((s, i) => s + ratioOverThreshold(i), 0) * 10,
+      confidence: 0.82,
+      o11ySignal: summary,
+      reason: 'real-user Core Web Vitals in poor band',
+      question: `On ${route}, ${summary}. Which client-side work (bundle weight, blocking scripts, layout shifts, hydration) is responsible, and which change would land first?`,
+      evidence: {
+        metric: 'cwv',
+        route,
+        lcpMs: lcp != null ? Math.round(lcp) : null,
+        inpMs: inp != null ? Math.round(inp) : null,
+        cls: cls != null ? round2(cls) : null,
+        issues,
+        totalSpeedInsightsSamples: totalSamples,
+        routeSpeedInsightsSamples: routeSamples,
+      },
+    }, signals));
+  }
+  return out;
+}
+
+function byRoute(rows) {
+  const m = new Map();
+  for (const r of rows ?? []) {
+    if (!r.route || r.value == null) continue;
+    m.set(r.route, r.value);
+  }
+  return m;
+}
+
+function sumRows(rows) {
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function ratioOverThreshold(i) {
+  return i.value / (i.threshold || 1);
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/external-api-slow.mjs b/skills/vercel/vercel-optimize/lib/gates/external-api-slow.mjs
new file mode 100644
index 0000000..b47ba5b
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/external-api-slow.mjs
@@ -0,0 +1,55 @@
+// Volume floor pairs p75 with call_count so a single 5s cron/day doesn't fire the gate.
+const MIN_CALL_COUNT = 500;
+
+export const metadata = {
+  id: 'external_api_slow',
+  threshold: `p75Ms > 2000 AND callCount >= ${MIN_CALL_COUNT}`,
+  billingDimension: 'function-duration',
+  scope: 'route',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'External API hostnames with p75 latency above 2 seconds AND at least 500 calls in the window. External API latency is a primary driver of function duration cost when the upstream is on a hot path; a single slow stale call isn\'t worth recommending against.',
+};
+
+export function gate(signals) {
+  const apis = extractExternalApis(signals);
+  const calls = extractCallCounts(signals);
+  return apis
+    .map((a) => ({ ...a, callCount: calls.get(a.hostname) ?? 0 }))
+    .filter((a) => a.p75Ms > 2000 && a.callCount >= MIN_CALL_COUNT)
+    .map((a) => ({
+      kind: metadata.id,
+      scope: 'route',
+      route: null,
+      files: [],
+      hostname: a.hostname,
+      // Weight by latency × call volume so 100k-call/2.1s outranks 1k-call/8s.
+      priority: Math.round((a.p75Ms * a.callCount) / 1000),
+      confidence: 0.88,
+      o11ySignal: `host=${a.hostname},p75=${a.p75Ms}ms,calls=${a.callCount}`,
+      reason: 'slow external dependency on hot path',
+      question: `Which routes call ${a.hostname} (p75=${a.p75Ms}ms across ${a.callCount} calls), and can the call be parallelized, cached, or moved off the critical path?`,
+      evidence: { metric: 'externalApiP75', hostname: a.hostname, p75Ms: a.p75Ms, callCount: a.callCount },
+    }));
+}
+
+function extractExternalApis(signals) {
+  const m = signals.metrics?.externalApiP75;
+  if (!m?.ok && !Array.isArray(m?.rows)) return [];
+  return (m?.rows ?? [])
+    .map((r) => ({
+      hostname: r.origin_hostname,
+      p75Ms: Math.round(r.value ?? 0),
+    }))
+    .filter((a) => a.hostname);
+}
+
+function extractCallCounts(signals) {
+  const m = signals.metrics?.externalApiCount;
+  const out = new Map();
+  if (!m) return out;
+  for (const r of m.rows ?? []) {
+    if (r?.origin_hostname) out.set(r.origin_hostname, r.value ?? 0);
+  }
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/hard-gates.mjs b/skills/vercel/vercel-optimize/lib/gates/hard-gates.mjs
new file mode 100644
index 0000000..6d08ded
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/hard-gates.mjs
@@ -0,0 +1,73 @@
+import { canonicalizeRoute } from '../route-normalize.mjs';
+
+export const FLAGS_ENDPOINT = '/.well-known/vercel/flags';
+export const VERCEL_FLAGS_PACKAGES = [
+  '@vercel/flags',
+  '@vercel/flags/next',
+  '@vercel/flags/sveltekit',
+  '@vercel/flags/nuxt',
+];
+export const WORKFLOW_ENDPOINT_PREFIXES = [
+  '/.well-known/workflow',
+  '/api/.well-known/workflow',
+];
+
+export function applyHardGates(candidates, signals = {}) {
+  const allowed = [];
+  const gated = [];
+  for (const candidate of candidates) {
+    if (isFlagsEndpointCandidate(candidate)) {
+      gated.push({
+        ...candidate,
+        gatedReason: flagsEndpointReason(signals),
+      });
+      continue;
+    }
+    if (isWorkflowRuntimeEndpointCandidate(candidate)) {
+      gated.push({
+        ...candidate,
+        gatedReason: workflowEndpointReason(signals),
+      });
+      continue;
+    }
+    allowed.push(candidate);
+  }
+  return { allowed, gated };
+}
+
+export function isFlagsEndpointCandidate(candidate) {
+  if (!candidate || candidate.scope === 'account') return false;
+  const route = normalizeRoute(candidate.route);
+  return route === FLAGS_ENDPOINT;
+}
+
+export function isWorkflowRuntimeEndpointCandidate(candidate) {
+  if (!candidate || candidate.scope === 'account') return false;
+  const route = normalizeRoute(candidate.route);
+  if (!route) return false;
+  return WORKFLOW_ENDPOINT_PREFIXES.some((prefix) => (
+    route === prefix || route.startsWith(`${prefix}/`)
+  ));
+}
+
+function normalizeRoute(route) {
+  if (typeof route !== 'string') return null;
+  const normalized = canonicalizeRoute(route).replace(/\/+$/, '');
+  return normalized === '' ? '/' : normalized;
+}
+
+function flagsEndpointReason(signals) {
+  const packages = signals.stack?.vercelFlagsPackages;
+  if (Array.isArray(packages) && packages.length > 0) {
+    return `hardGated: ${FLAGS_ENDPOINT} is the Vercel Flags endpoint (${packages.join(', ')} detected), not an optimization target`;
+  }
+  return `hardGated: ${FLAGS_ENDPOINT} is the Vercel Flags endpoint, not an optimization target`;
+}
+
+function workflowEndpointReason(signals) {
+  const packages = signals.stack?.workflowPackages;
+  if (Array.isArray(packages) && packages.length > 0) {
+    return `hardGated: Vercel Workflow runtime endpoint (${packages.join(', ')} detected); long-running step/flow requests are expected orchestration, not an app-route optimization target`;
+  }
+  return 'hardGated: Vercel Workflow runtime endpoint; long-running step/flow requests are expected orchestration, not an app-route optimization target';
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/index.mjs b/skills/vercel/vercel-optimize/lib/gates/index.mjs
new file mode 100644
index 0000000..345c1e7
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/index.mjs
@@ -0,0 +1,45 @@
+import * as uncachedRoute from './uncached-route.mjs';
+import * as slowRoute from './slow-route.mjs';
+import * as routeErrors from './route-errors.mjs';
+import * as coldStart from './cold-start.mjs';
+import * as isrOverrevalidation from './isr-overrevalidation.mjs';
+import * as cwvPoor from './cwv-poor.mjs';
+import * as platformFluidCompute from './platform-fluid-compute.mjs';
+import * as platformBotProtection from './platform-bot-protection.mjs';
+import * as middlewareHeavy from './middleware-heavy.mjs';
+import * as externalApiSlow from './external-api-slow.mjs';
+import * as scannerDriven from './scanner-driven.mjs';
+import * as observabilityEventsAttribution from './observability-events-attribution.mjs';
+import * as usageSpikeTriage from './usage-spike-triage.mjs';
+import * as buildMinutesFanout from './build-minutes-fanout.mjs';
+import * as regionMisconfig from './region-misconfig.mjs';
+
+// Intentionally NOT registered:
+//   - `oversized_memory`: Fluid Compute floor is 2GB; per-route memory right-sizing isn't a customer lever.
+//   - `deploy_regression`: overlaps Vercel Agent Investigations; `vercel inspect` 404s across teams. slow_route deep-dive already carries per-deployment p95 trend.
+export const gates = [
+  uncachedRoute,
+  slowRoute,
+  routeErrors,
+  coldStart,
+  isrOverrevalidation,
+  cwvPoor,
+  externalApiSlow,
+  scannerDriven,
+  // Account-scoped last so platform-scoped sort doesn't dilute code-scoped priority ordering during budget application.
+  platformFluidCompute,
+  platformBotProtection,
+  middlewareHeavy,
+  observabilityEventsAttribution,
+  usageSpikeTriage,
+  buildMinutesFanout,
+  regionMisconfig,
+];
+
+// Overridable via `--max-candidates N` or `VERCEL_OPTIMIZE_MAX_CANDIDATES` (accepts `all`).
+// `MAX_CODE_CANDIDATES` is a back-compat alias for tests importing the old name.
+export const DEFAULT_MAX_CODE_CANDIDATES = 6;
+export const MAX_CODE_CANDIDATES = DEFAULT_MAX_CODE_CANDIDATES;
+
+// Bump on any threshold change so report + iteration baselines can detect gate-logic drift.
+export const GATE_VERSION = '1.8.0';
diff --git a/skills/vercel/vercel-optimize/lib/gates/isr-overrevalidation.mjs b/skills/vercel/vercel-optimize/lib/gates/isr-overrevalidation.mjs
new file mode 100644
index 0000000..86769a9
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/isr-overrevalidation.mjs
@@ -0,0 +1,62 @@
+// ISR writes re-execute the page render. A w/r ratio above 0.5 means writes are
+// happening at least once for every two reads — high enough for the default
+// audit to spend investigation budget. writes>100 avoids flapping on quiet routes.
+export const metadata = {
+  id: 'isr_overrevalidation',
+  threshold: 'writes/reads > 0.5 AND writes > 100',
+  billingDimension: 'isr',
+  scope: 'route',
+  sourceCitation: 'https://vercel.com/docs/incremental-static-regeneration',
+  description:
+    'ISR routes with > 1 write per 2 reads. The revalidate interval is too aggressive relative to read traffic — many reads pay to regenerate. Investigate whether the page can tolerate a longer revalidate window or on-demand revalidation via revalidateTag.',
+};
+
+export function gate(signals) {
+  const rows = extractRows(signals);
+  return rows
+    .filter((r) => r.writes > 100 && r.reads > 0 && r.writes / r.reads > 0.5)
+    .map((r) => {
+      const ratio = r.writes / r.reads;
+      return {
+        kind: metadata.id,
+        scope: 'route',
+        route: r.route,
+        files: [],
+        priority: Math.round(r.writes),
+        confidence: 0.88,
+        o11ySignal: `writes=${r.writes},reads=${r.reads},w/r=${ratio.toFixed(2)}`,
+        reason: 'ISR revalidating faster than read traffic justifies',
+        question: `On ${r.route}, ${r.writes} ISR writes against ${r.reads} reads (${(ratio * 100).toFixed(0)} writes per 100 reads) — what is the current revalidate interval and can it be lengthened or switched to on-demand?`,
+        evidence: {
+          metric: 'isrWritesByRoute',
+          route: r.route,
+          writes: r.writes,
+          reads: r.reads,
+          ratio,
+        },
+      };
+    });
+}
+
+function extractRows(signals) {
+  const writes = signals.metrics?.isrWritesByRoute?.rows ?? [];
+  const reads = signals.metrics?.isrReadsByRoute?.rows ?? [];
+
+  const writeByRoute = new Map();
+  for (const r of writes) {
+    if (!r.route) continue;
+    writeByRoute.set(r.route, (writeByRoute.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+  const readByRoute = new Map();
+  for (const r of reads) {
+    if (!r.route) continue;
+    readByRoute.set(r.route, (readByRoute.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+
+  const routes = new Set([...writeByRoute.keys(), ...readByRoute.keys()]);
+  return [...routes].map((route) => ({
+    route,
+    writes: writeByRoute.get(route) ?? 0,
+    reads: readByRoute.get(route) ?? 0,
+  }));
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/middleware-heavy.mjs b/skills/vercel/vercel-optimize/lib/gates/middleware-heavy.mjs
new file mode 100644
index 0000000..416605c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/middleware-heavy.mjs
@@ -0,0 +1,51 @@
+// Middleware runs in front of every matching request and is billed as edge invocations.
+// If >50% of traffic hits middleware, the matcher is probably broader than necessary.
+export const metadata = {
+  id: 'middleware_heavy',
+  threshold: 'middlewareInv/totalInv > 0.5 AND middlewareInv > 1000',
+  billingDimension: 'edge-requests',
+  scope: 'account',
+  sourceCitation: 'https://nextjs.org/docs/app/building-your-application/routing/middleware',
+  description:
+    'Middleware invocations cover > 50% of total requests at non-trivial volume. The matcher is probably broader than necessary; narrow it to the paths that actually need auth/rewrites/headers.',
+};
+
+export function gate(signals) {
+  const middlewareInv = sumRows(signals.metrics?.middlewareCount?.rows);
+  if (middlewareInv < 1000) return [];
+
+  const totalInv = sumRows(signals.metrics?.requestsByRouteCache?.rows);
+  if (totalInv === 0) return [];
+
+  const ratio = middlewareInv / totalInv;
+  if (ratio <= 0.5) return [];
+
+  const top = [...(signals.metrics?.middlewareCount?.rows ?? [])]
+    .filter((r) => r.request_path)
+    .sort((a, b) => (b.value ?? 0) - (a.value ?? 0))
+    .slice(0, 5)
+    .map((r) => ({ request_path: r.request_path, count: r.value ?? 0 }));
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: [],
+    priority: Math.round(middlewareInv / 1000),
+    confidence: 0.84,
+    o11ySignal: `middleware_inv=${middlewareInv},total_req=${totalInv},ratio=${(ratio * 100).toFixed(0)}%`,
+    reason: 'middleware ran on more than half of all requests',
+    question: `Middleware invocations (${middlewareInv}) are ${(ratio * 100).toFixed(0)}% of all requests (${totalInv}). Which paths in middleware.ts require interception, and can the matcher be narrowed to exclude static assets, images, and routes that do not need rewriting?`,
+    evidence: {
+      metric: 'middlewareCount',
+      middlewareInv,
+      totalInv,
+      ratio,
+      topPaths: top,
+    },
+  }];
+}
+
+function sumRows(rows) {
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/observability-events-attribution.mjs b/skills/vercel/vercel-optimize/lib/gates/observability-events-attribution.mjs
new file mode 100644
index 0000000..85a1f94
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/observability-events-attribution.mjs
@@ -0,0 +1,56 @@
+// Observability Events is the metered SKU under Observability Plus.
+// Threshold at >20% surfaces material spend; >30% is the critical band.
+// Drivers correlate with low cache hit rate, high middleware invocation, and high custom-span cardinality.
+export const metadata = {
+  id: 'observability_events_attribution',
+  threshold: 'observabilityEventsShare > 0.20 (critical at > 0.30)',
+  billingDimension: 'observability-events',
+  scope: 'account',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Observability Events line item exceeds 20% of total billed cost. High share usually traces to low cache hit rate, middleware-heavy traffic, or unconstrained custom-span cardinality. No sampling lever exists for Observability Plus; reduce upstream invocations instead.',
+};
+
+const EVENTS_RE = /^Observability Events$/i;
+
+export function gate(signals) {
+  const services = signals?.usage?.services;
+  if (!Array.isArray(services) || services.length === 0) return [];
+
+  const total = sumBilled(services);
+  if (total <= 0) return [];
+
+  const eventsBilled = services
+    .filter((s) => EVENTS_RE.test(String(s?.name ?? '')))
+    .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
+  if (eventsBilled <= 0) return [];
+
+  const share = eventsBilled / total;
+  if (share <= 0.20) return [];
+
+  const critical = share > 0.30;
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: [],
+    priority: critical ? 70 : 55,
+    confidence: 0.82,
+    o11ySignal: `observability_events_share=${(share * 100).toFixed(0)}%`,
+    reason: critical
+      ? 'observability events exceed 30% of total billed cost'
+      : 'observability events exceed 20% of total billed cost',
+    question: `Observability Events are ${(share * 100).toFixed(0)}% of the bill. Which routes drive event volume — low-cache-hit traffic, broad middleware invocation, or high custom-span cardinality — and can event volume be reduced upstream of the meter?`,
+    evidence: {
+      metric: 'usage.services',
+      eventsBilled,
+      totalBilled: total,
+      observabilityEventsShare: share,
+      critical,
+    },
+  }];
+}
+
+function sumBilled(services) {
+  return services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/platform-bot-protection.mjs b/skills/vercel/vercel-optimize/lib/gates/platform-bot-protection.mjs
new file mode 100644
index 0000000..035f063
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/platform-bot-protection.mjs
@@ -0,0 +1,115 @@
+// Recommend BotID only when there's EVIDENCE of bot traffic or scale large enough that the rec is defensible.
+// Without an evidence gate the rec fires on quiet hobby sites and erodes trust.
+const MIN_BOT_PCT = 0.05;
+const MIN_EDGE_COST = 25;          // halved for 14d window
+const MIN_TOTAL_REQUESTS = 14_000; // ~14k/14d matches the prior 30k/30d rate
+const MIN_TOTAL_FDT_BYTES = 1_000_000;
+
+export const metadata = {
+  id: 'platform_bot_protection',
+  threshold: 'botIdEnabled=false AND (botPct >= 0.05 OR edge_cost >= $25/window OR requests >= 14k/14d)',
+  billingDimension: 'edge-requests',
+  scope: 'account',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'When BotID is disabled AND there is evidence (observed bot bandwidth share, edge cost, or substantial request volume) that bot traffic is non-trivial. Bot traffic inflates edge request counts without delivering user value; staged bot protection can reduce waste on bot-heavy projects. Skipped on quiet projects with no bot evidence — the recommendation would be noise.',
+};
+
+export function gate(signals) {
+  // BotID surfaces under several legacy fields; check all.
+  const botEnabled =
+    signals.project?.security?.botIdEnabled === true
+    || signals.project?.security?.botProtection === true
+    || signals.project?.botProtection?.enabled === true
+    || signals.project?.delegatedProtection?.bot === true;
+  if (botEnabled) return [];
+
+  // Project config failed — we can't tell if BotID is on, so stay silent.
+  if (signals.project?.error) return [];
+
+  const totalRequests = totalRequestsFromSignals(signals);
+  const botShare = computeBotShare(signals);
+  const edgeService = (signals.usage?.services ?? []).find(
+    (s) => /edge.request/i.test(s.name ?? '')
+  );
+  const edgeCost = edgeService?.billedCost ?? null;
+
+  // Require observable bot share, edge cost, OR substantial traffic — otherwise rec is just config nagging.
+  const hasObservedBots = botShare?.botPct != null && botShare.botPct >= MIN_BOT_PCT;
+  const hasMaterialEdgeCost = edgeCost != null && edgeCost >= MIN_EDGE_COST;
+  const hasSubstantialTraffic = totalRequests >= MIN_TOTAL_REQUESTS;
+  if (!hasObservedBots && !hasMaterialEdgeCost && !hasSubstantialTraffic) return [];
+
+  const challengeRule = signals.project?.security?.managedRules?.bot_filter;
+  const ruleNote = challengeRule?.active
+    ? `firewall bot_filter rule active (action=${challengeRule.action ?? '?'})`
+    : 'no firewall bot_filter rule';
+
+  // Kicker on high observed bot share — harder evidence than config alone.
+  let priority = edgeCost != null ? Math.max(20, Math.round(edgeCost)) : 30;
+  if (botShare?.botPct != null && botShare.botPct > 0.2) priority += 20;
+
+  // Confidence bumps when we can SEE bot traffic, not just infer from config.
+  let confidence = edgeCost != null ? 0.85 : 0.6;
+  if (botShare?.botPct != null && botShare.botPct > 0.2) confidence = Math.min(0.95, confidence + 0.05);
+
+  const botShareNote = botShare?.botPct != null
+    ? `bot_fdt_pct=${(botShare.botPct * 100).toFixed(0)}%`
+    : 'bot_fdt_pct=unknown';
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: [],
+    priority,
+    confidence,
+    o11ySignal: edgeCost != null
+      ? `edge_cost=${edgeCost.toFixed(0)},bot_protection=disabled,${botShareNote},${ruleNote}`
+      : `requests=${totalRequests},bot_protection=disabled,${botShareNote},${ruleNote}`,
+    reason: botShare?.botPct != null && botShare.botPct > 0.2
+      ? 'BotID disabled with observable bot bandwidth share'
+      : 'BotID disabled with observable traffic',
+    question: botShare?.botPct != null && botShare.botPct > 0.2
+      ? `Bot traffic accounts for ${(botShare.botPct * 100).toFixed(0)}% of FDT bytes (top category: ${botShare.topCategory ?? 'unknown'}). Would enabling BotID + a challenge rule reduce that share?`
+      : 'Would enabling BotID (Bot Protection) reduce edge request volume from automated traffic?',
+    evidence: {
+      botEnabled: false,
+      edgeCost,
+      totalRequests,
+      managedRules: challengeRule ?? null,
+      botShare: botShare ?? null,
+    },
+  }];
+}
+
+function totalRequestsFromSignals(signals) {
+  const rows = signals.metrics?.requestsByRouteCache?.rows;
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}
+
+// CLI convention: bot_category="" means "not classified as a bot" (human + unclassified); any non-empty = bot.
+function computeBotShare(signals) {
+  const rows = signals.metrics?.fdtByBot?.rows;
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  let humanBytes = 0;
+  let botBytes = 0;
+  let topCategory = null;
+  let topBytes = 0;
+  for (const r of rows) {
+    const v = r.value ?? 0;
+    const cat = r.bot_category ?? '';
+    if (cat === '') {
+      humanBytes += v;
+    } else {
+      botBytes += v;
+      if (v > topBytes) {
+        topBytes = v;
+        topCategory = cat;
+      }
+    }
+  }
+  const total = humanBytes + botBytes;
+  if (total < MIN_TOTAL_FDT_BYTES) return null;
+  return { humanBytes, botBytes, botPct: botBytes / total, topCategory };
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/platform-fluid-compute.mjs b/skills/vercel/vercel-optimize/lib/gates/platform-fluid-compute.mjs
new file mode 100644
index 0000000..6985698
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/platform-fluid-compute.mjs
@@ -0,0 +1,83 @@
+// Second branch (slow p95 + traffic floor) keeps the gate useful on teams where
+// cold-start isn't directly observable — common on CLI v53 — trading specificity for coverage.
+export const metadata = {
+  id: 'platform_fluid_compute',
+  threshold: 'fluid=false AND (any cold_start signal OR any route with p95>1000ms AND inv>1000)',
+  billingDimension: 'function-duration',
+  scope: 'account',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'When Fluid Compute is disabled on a project that shows cold-start pressure (high cold-start rate) or sustained slow function p95 on hot routes. Fluid Compute reduces cold starts via instance reuse — recommend turning it on at the project level rather than per-route.',
+};
+
+export function gate(signals) {
+  // If project config failed to load we can't tell if Fluid is on; recommending it when already-on
+  // erodes trust badly, so stay silent and let Strengths note the gap.
+  if (signals.project?.error) return [];
+
+  const fluidEnabled =
+    signals.project?.resourceConfig?.fluid === true
+    || signals.project?.defaultResourceConfig?.fluid === true;
+  if (fluidEnabled) return [];
+
+  const cold = extractHighColdRoutes(signals);
+  const slow = extractSlowHotRoutes(signals);
+  if (cold.length === 0 && slow.length === 0) return [];
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: [],
+    priority: 50,
+    confidence: cold.length > 0 ? 0.85 : 0.65,
+    o11ySignal: cold.length > 0
+      ? `${cold.length} route(s) with high cold-start rate`
+      : `${slow.length} hot route(s) with p95>1s; cold-start not directly observable`,
+    reason: cold.length > 0
+      ? 'cold starts observed and Fluid Compute is disabled'
+      : 'slow hot routes and Fluid Compute is disabled',
+    question: 'Would enabling Fluid Compute reduce cold-start and warm-instance reuse overhead for the observed hot routes?',
+    evidence: { fluidEnabled, highColdRoutes: cold.slice(0, 5), slowHotRoutes: slow.slice(0, 5) },
+  }];
+}
+
+function extractHighColdRoutes(signals) {
+  const live = signals.metrics?.fnStartTypeByRoute?.rows;
+  if (Array.isArray(live) && live.some((r) => 'coldCount' in r || 'coldPct' in r)) {
+    return live.filter((r) => r.route && (r.coldPct ?? 0) > 0.3 && (r.total ?? 0) > 100);
+  }
+  // Legacy pre-derived fixture shape.
+  const direct = signals.metrics?.coldStartByRoute?.rows;
+  if (Array.isArray(direct)) {
+    return direct.filter((r) => r.route && (r.coldPct ?? 0) > 0.3 && (r.total ?? 0) > 100);
+  }
+  const legacy = signals.metrics?.coldStarts?.series;
+  if (Array.isArray(legacy)) {
+    return legacy
+      .map((s) => {
+        const total = s.summary?.count ?? 0;
+        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
+        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
+      })
+      .filter((r) => r.route && r.coldPct > 0.3 && r.total > 100);
+  }
+  return [];
+}
+
+function extractSlowHotRoutes(signals) {
+  const dur = signals.metrics?.fnDurationP95ByRoute?.rows;
+  const cache = signals.metrics?.requestsByRouteCache?.rows;
+  if (!Array.isArray(dur)) return [];
+
+  // Sum requests per route across cache_result.
+  const inv = new Map();
+  for (const r of (cache ?? [])) {
+    if (!r.route) continue;
+    inv.set(r.route, (inv.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+  return dur
+    .filter((r) => r.route)
+    .map((r) => ({ route: r.route, p95Ms: Math.round(r.value ?? 0), invocations: inv.get(r.route) ?? 0 }))
+    // inv>500 floor is the 14d-window equivalent of the old 1000/30d.
+    .filter((r) => r.p95Ms > 1000 && r.invocations > 500);
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/region-misconfig.mjs b/skills/vercel/vercel-optimize/lib/gates/region-misconfig.mjs
new file mode 100644
index 0000000..354b99c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/region-misconfig.mjs
@@ -0,0 +1,64 @@
+// Region-misconfig gate. Branch 2 (scanner-only) — per-region TTFB data gap.
+//
+// The intended Branch 1 (region-grouped TTFB metric) was preflight-tested but the
+// CLI returned INTERNAL_ERROR for the `--group-by route --group-by function_region`
+// combination, and SAML re-auth blocked single-dim verification (see Phase 0 in
+// plans/wild-splashing-flamingo.md). Ship scanner-only with `evidence.dataGap` and
+// add the query later when verifiable.
+//
+// Fires when a single-region pin is found AND the project has meaningful surface area
+// (routes.length > 20). Skips multi-region configs (informational only).
+export const metadata = {
+  id: 'region_misconfig',
+  threshold: 'single-region pin found AND routes.length > 20 (scanner-only branch)',
+  billingDimension: 'function-duration',
+  scope: 'account',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    "A single function region is pinned in `vercel.json` or per-route `preferredRegion`. Without per-region TTFB data (data gap), the gate can't quantify the geographic latency cost — but a single-region pin on a project with 20+ routes is worth auditing against Speed Insights traffic geo.",
+};
+
+const ROUTE_FLOOR = 20;
+const SCANNER_PATTERN = 'region-pin-in-config';
+
+export function gate(signals) {
+  const findings = (signals?.codebase?.findings ?? []).filter((f) => f.pattern === SCANNER_PATTERN);
+  if (findings.length === 0) return [];
+
+  const routes = signals?.codebase?.routes ?? [];
+  if (routes.length < ROUTE_FLOOR) return [];
+
+  const singleRegionFindings = findings.filter((f) => Array.isArray(f.regions) && f.regions.length === 1);
+  if (singleRegionFindings.length === 0) return [];
+
+  const allPinned = new Set();
+  for (const f of singleRegionFindings) {
+    for (const r of f.regions ?? []) allPinned.add(r);
+  }
+  const regionList = [...allPinned];
+
+  // If multiple distinct single-region pins exist across files, the surface is partly
+  // multi-region by accident; that's noteworthy but lower priority.
+  const homogeneous = regionList.length === 1;
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: singleRegionFindings.map((f) => f.file).slice(0, 6),
+    priority: homogeneous ? 42 : 38,
+    confidence: 0.6, // low — no per-region TTFB data
+    o11ySignal: `pinned_regions=${regionList.join(',')} routes=${routes.length}`,
+    reason: homogeneous
+      ? `all functions pinned to a single region (${regionList[0]}) on a project with ${routes.length} routes`
+      : `${regionList.length} different single-region pins across files`,
+    question: 'Are the pinned function regions aligned with the dominant user geography and the data source location? Speed Insights TTFB-by-country can ground the comparison.',
+    evidence: {
+      metric: 'codebase.findings',
+      pinnedRegions: regionList,
+      findingsCount: singleRegionFindings.length,
+      routeCount: routes.length,
+      sampleFiles: singleRegionFindings.slice(0, 3).map((f) => ({ file: f.file, regions: f.regions, subtype: f.subtype })),
+      dataGap: 'region-grouped-TTFB-unavailable',
+    },
+  }];
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/route-errors.mjs b/skills/vercel/vercel-optimize/lib/gates/route-errors.mjs
new file mode 100644
index 0000000..98b819a
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/route-errors.mjs
@@ -0,0 +1,80 @@
+// Errored function invocations still bill at full duration, so high-volume 5xx is a cost issue, not just reliability.
+import { withRouteShapeWarnings } from '../route-normalize.mjs';
+
+const MIN_VOLUME_FOR_RATE_EMISSION = 1000;
+
+export const metadata = {
+  id: 'route_errors',
+  threshold: `count > 250 OR (totalRequests >= ${MIN_VOLUME_FOR_RATE_EMISSION} AND errorRate > 0.01)`,
+  billingDimension: 'function-duration',
+  scope: 'route',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Routes producing > 250 5xx errors over the window, or with > 1% error rate on at least 1,000 total requests. Errored function invocations still bill at full duration; high error rates also poison user experience.',
+};
+
+export function gate(signals) {
+  const errors = extractErrors(signals);
+  return errors
+    .filter((e) => e.count > 250 || (e.total >= MIN_VOLUME_FOR_RATE_EMISSION && (e.errorRate ?? 0) > 0.01))
+    .map((e) => withRouteShapeWarnings({
+      kind: metadata.id,
+      scope: 'route',
+      route: e.route,
+      files: [],
+      priority: e.count,
+      confidence: 0.93,
+      o11ySignal: e.errorRate != null
+        ? `errs=${e.count},rate=${(e.errorRate * 100).toFixed(1)}%`
+        : `errs=${e.count}`,
+      reason: 'concentrated 5xx errors',
+      question: `Why does ${e.route} produce ${e.count} 5xx errors over the window, and what code path is failing?`,
+      evidence: { metric: e.metric, route: e.route, count: e.count, totalRequests: e.total, errorRate: e.errorRate },
+    }, signals));
+}
+
+function extractErrors(signals) {
+  const fnStatus = signals.metrics?.fnStatusByRoute;
+  if (Array.isArray(fnStatus?.rows)) return extractFromStatusRows(fnStatus.rows, 'fnStatusByRoute');
+
+  const m = signals.metrics?.requestsByRouteStatus;
+  const cache = signals.metrics?.requestsByRouteCache;
+  if (!m?.ok && !Array.isArray(m?.rows)) return [];
+
+  const errors = extractFromStatusRows(m?.rows ?? [], 'requestsByRouteStatus');
+
+  // cache rollup is summed across cache_result, giving per-route total request count.
+  const totalByRoute = new Map();
+  for (const row of (cache?.rows ?? [])) {
+    if (!row.route) continue;
+    totalByRoute.set(row.route, (totalByRoute.get(row.route) ?? 0) + (row.value ?? 0));
+  }
+
+  return errors.map((e) => {
+    const total = totalByRoute.get(e.route) ?? 0;
+    return {
+      ...e,
+      total,
+      errorRate: total > 0 ? e.count / total : null,
+    };
+  });
+}
+
+function extractFromStatusRows(rows, metric) {
+  const errByRoute = new Map();
+  const totalByRoute = new Map();
+  for (const row of rows) {
+    const route = row.route;
+    if (!route) continue;
+    const v = row.value ?? 0;
+    const status = String(row.http_status ?? '');
+    if (/^5\d\d$/.test(status)) errByRoute.set(route, (errByRoute.get(route) ?? 0) + v);
+    totalByRoute.set(route, (totalByRoute.get(route) ?? 0) + v);
+  }
+
+  return [...errByRoute.entries()].map(([route, count]) => {
+    const total = totalByRoute.get(route) ?? 0;
+    const errorRate = total > 0 ? count / total : null;
+    return { route, count, total, errorRate, metric };
+  });
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/scanner-driven.mjs b/skills/vercel/vercel-optimize/lib/gates/scanner-driven.mjs
new file mode 100644
index 0000000..a698f18
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/scanner-driven.mjs
@@ -0,0 +1,122 @@
+// Signal source is the codebase itself, not traffic. COLD-PATH and NO-ROUTE-MAPPING findings
+// are dropped unless the scanner sets trafficIndependent (build configs, middleware matchers, etc.).
+// Annotation happens in scan-codebase.mjs; gates here just read scanner.o11ySignal.
+
+export const SCANNER_GATES = [
+  { id: 'image_optimization', patterns: ['unoptimized-image'], threshold: 2,
+    billingDimension: 'image-optimization', priority: 30 },
+  { id: 'cache_header_gap', patterns: ['max-age-without-s-maxage', 'missing-cache-headers'], threshold: 1,
+    billingDimension: 'edge-requests', priority: 40 },
+  { id: 'rendering_candidate', patterns: ['force-dynamic', 'headers-in-page'], threshold: 3,
+    billingDimension: 'function-duration', priority: 35 },
+  { id: 'use_cache_date_stamp', patterns: ['use-cache-date-stamp'], threshold: 1,
+    billingDimension: 'isr', priority: 45 },
+  { id: 'cache_components_suspense_dedupe', patterns: ['cache-components-suspense-dedupe'], threshold: 1,
+    billingDimension: 'function-duration', priority: 38 },
+];
+
+export const metadata = {
+  id: 'scanner-driven',
+  threshold: 'per-kind: scanner matches.length >= threshold',
+  billingDimension: 'mixed',
+  scope: 'mixed',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Configured kinds emitted from scanner output. Each requires a minimum match count to avoid noise. Findings on cold-path or unmappable files are dropped unless the underlying scanner is trafficIndependent.',
+};
+
+export function gate(signals) {
+  const findings = signals.codebase?.findings ?? [];
+  if (findings.length === 0) return [];
+
+  const candidates = [];
+
+  for (const cfg of SCANNER_GATES) {
+    const matched = findings.filter((f) => {
+      if (!cfg.patterns.includes(f.pattern)) return false;
+      if (!f.trafficIndependent) {
+        if (!f.o11ySignal || f.o11ySignal === 'scanner-only') return false;
+        if (f.o11ySignal === 'COLD-PATH') return false;
+        if (f.o11ySignal === 'NO-ROUTE-MAPPING') return false;
+      }
+      if (cfg.id === 'cache_header_gap' && observedCacheHitRate(f.o11ySignal) >= 90) return false;
+      return true;
+    });
+
+    for (const group of groupFindings(cfg, matched)) {
+      if (group.findings.length < cfg.threshold) continue;
+      candidates.push(candidateForGroup(cfg, group));
+    }
+  }
+
+  return candidates;
+}
+
+function groupFindings(cfg, findings) {
+  const groups = new Map();
+  for (const finding of findings) {
+    const scope = finding.route ? 'route' : 'file';
+    const target = scope === 'route' ? finding.route : finding.file;
+    if (!target) continue;
+    const key = `${cfg.id}:${scope}:${target}`;
+    if (!groups.has(key)) groups.set(key, { scope, target, findings: [] });
+    groups.get(key).findings.push(finding);
+  }
+  return [...groups.values()];
+}
+
+function candidateForGroup(cfg, group) {
+  const matched = group.findings;
+  const route = group.scope === 'route' ? group.target : null;
+  return {
+    kind: cfg.id,
+    scope: group.scope,
+    route,
+    files: uniqueStrings(matched.map((m) => m.file)).slice(0, 6),
+    priority: cfg.priority + Math.min(matched.length, 10),
+    confidence: 0.88,
+    o11ySignal: matched
+      .map((m) => m.o11ySignal)
+      .find((s) => s && s !== 'COLD-PATH' && s !== 'NO-ROUTE-MAPPING')
+      ?? 'scanner-only',
+    reason: `${matched.length} ${cfg.patterns.join('+')} finding(s)`,
+    question: questionFor(cfg.id, matched),
+    evidence: {
+      scannerMatches: matched.length,
+      patterns: cfg.patterns,
+      scope: group.scope,
+      route,
+      sampleFiles: matched.slice(0, 3).map((m) => ({ file: m.file, line: m.line })),
+    },
+  };
+}
+
+function questionFor(kindId, matched) {
+  const sample = matched.slice(0, 3).map((m) => m.file).join(', ');
+  switch (kindId) {
+    case 'image_optimization':
+      return `Which raw <img> tags in ${sample} should move to next/image (or the framework's image component)?`;
+    case 'cache_header_gap':
+      return `Should the route handlers in ${sample} set Cache-Control with s-maxage to serve from the CDN?`;
+    case 'rendering_candidate':
+      return `Why are the routes in ${sample} forced to dynamic rendering, and can any of them tolerate ISR or static generation?`;
+    case 'use_cache_date_stamp':
+      return `Which 'use cache' boundaries in ${sample} embed new Date()/Date.now()/Math.random() that destabilizes cache keys, and can the timestamps be hoisted to a build constant or moved into a client useEffect?`;
+    case 'cache_components_suspense_dedupe':
+      return `In ${sample}, which repeated fetch or helper is being re-invoked across separate <Suspense> boundaries, and can the promise be hoisted to the page level or moved to 'use cache: remote' for cross-boundary dedupe?`;
+    default:
+      return `Investigate ${matched.length} ${kindId} finding(s).`;
+  }
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((v) => typeof v === 'string' && v.length > 0))];
+}
+
+function observedCacheHitRate(signal) {
+  if (typeof signal !== 'string') return null;
+  const m = /\bcache=([\d.]+)%/.exec(signal);
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : null;
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/select-candidates.mjs b/skills/vercel/vercel-optimize/lib/gates/select-candidates.mjs
new file mode 100644
index 0000000..b52a9eb
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/select-candidates.mjs
@@ -0,0 +1,134 @@
+// Deterministic launch selection for the code-scope investigation budget.
+//
+// Raw priority still orders candidates inside each pass. The default budget is
+// impact-first, with failure-mode diversity when a kind's top signal is large
+// enough to justify taking a first-pass slot.
+
+const DEFAULT_KIND_CAPS = new Map([
+  ['slow_route', 2],
+  ['uncached_route', 2],
+  ['route_errors', 2],
+]);
+
+const DIVERSITY_ELIGIBILITY = new Map([
+  // A handful of 5xx errors can pass the route_errors gate because the rate is
+  // high, but that should not displace much larger cost/performance signals in
+  // the default six-candidate pass.
+  ['route_errors', (candidate) => numberFromEvidence(candidate, 'count') >= 1000],
+
+  // Scanner-driven cache findings are valuable, but the default pass should
+  // spend a slot only when observability shows meaningful route traffic or a
+  // very slow route handler.
+  ['cache_header_gap', (candidate) => {
+    const invocations = numberFromSignal(candidate?.o11ySignal, 'inv');
+    const p95Ms = durationMsFromSignal(candidate?.o11ySignal, 'p95');
+    return invocations >= 50_000 || p95Ms >= 2000;
+  }],
+  ['rendering_candidate', (candidate) => numberFromSignal(candidate?.o11ySignal, 'inv') >= 50_000],
+]);
+
+export function selectLaunchCandidates(candidates, budget, { diversify = false } = {}) {
+  const pool = Array.isArray(candidates) ? candidates : [];
+  if (budget === Infinity) {
+    return { selected: pool, skipped: [], selectionMode: 'all' };
+  }
+  if (!Number.isInteger(budget) || budget < 1) {
+    throw new TypeError('selectLaunchCandidates budget must be a positive integer or Infinity');
+  }
+  if (!diversify) {
+    return {
+      selected: pool.slice(0, budget),
+      skipped: pool.slice(budget),
+      selectionMode: 'priority',
+    };
+  }
+
+  const selected = [];
+  const selectedKeys = new Set();
+  const countsByKind = new Map();
+
+  const add = (candidate) => {
+    const key = candidateIdentity(candidate);
+    if (selectedKeys.has(key)) return false;
+    selectedKeys.add(key);
+    selected.push(candidate);
+    const kind = candidate.kind ?? '<unknown>';
+    countsByKind.set(kind, (countsByKind.get(kind) ?? 0) + 1);
+    return true;
+  };
+
+  // First pass: one candidate per failure mode, preserving the existing sorted
+  // order. This is where the default run gets broad coverage, but only for
+  // kinds whose signal is strong enough for a default slot.
+  for (const candidate of pool) {
+    if (selected.length >= budget) break;
+    const kind = candidate.kind ?? '<unknown>';
+    if ((countsByKind.get(kind) ?? 0) > 0) continue;
+    if (!isDiversityEligible(candidate)) continue;
+    add(candidate);
+  }
+
+  // Second pass: allow a second entry for high-frequency families, but avoid
+  // letting slow_route consume the entire default budget when other kinds exist.
+  for (const candidate of pool) {
+    if (selected.length >= budget) break;
+    const kind = candidate.kind ?? '<unknown>';
+    const cap = DEFAULT_KIND_CAPS.get(kind) ?? 1;
+    if ((countsByKind.get(kind) ?? 0) >= cap) continue;
+    if (!isDiversityEligible(candidate)) continue;
+    add(candidate);
+  }
+
+  // Final fill: if the project only has one or two candidate kinds, use the
+  // whole requested budget rather than leaving slots empty.
+  for (const candidate of pool) {
+    if (selected.length >= budget) break;
+    add(candidate);
+  }
+
+  return {
+    selected,
+    skipped: pool.filter((candidate) => !selectedKeys.has(candidateIdentity(candidate))),
+    selectionMode: 'diverse-default',
+  };
+}
+
+function candidateIdentity(candidate) {
+  return [
+    candidate?.kind ?? '',
+    candidate?.route ?? '',
+    candidate?.hostname ?? '',
+    candidate?.scope ?? '',
+    candidate?.o11ySignal ?? '',
+  ].join('\u0000');
+}
+
+function isDiversityEligible(candidate) {
+  const fn = DIVERSITY_ELIGIBILITY.get(candidate?.kind);
+  return fn ? fn(candidate) : true;
+}
+
+function numberFromEvidence(candidate, key) {
+  const value = candidate?.evidence?.[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function numberFromSignal(signal, key) {
+  if (typeof signal !== 'string') return 0;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(?:^|,)${escaped}=([\\d.]+)`);
+  const m = re.exec(signal);
+  if (!m) return 0;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function durationMsFromSignal(signal, key) {
+  if (typeof signal !== 'string') return 0;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(?:^|,)${escaped}=([\\d.]+)ms`);
+  const m = re.exec(signal);
+  if (!m) return 0;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : 0;
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/slow-route.mjs b/skills/vercel/vercel-optimize/lib/gates/slow-route.mjs
new file mode 100644
index 0000000..262e5b5
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/slow-route.mjs
@@ -0,0 +1,88 @@
+// Primary threshold (p95>500 AND inv>=1400) WHY: 1.4k/14d is the floor where p95 stabilizes statistically
+// and a 3-5x performance win still pays for engineering time. Secondary (p95>1500 AND inv>=250) catches "catastrophically
+// slow at any volume" — usually a broken sync call or cold-start chain the customer wants to know about.
+//
+// 5xx disqualifier: when error rate >50% the route is failing, not slow — latency reflects crash time,
+// not work time. route_errors covers it independently; we disqualify here so budget isn't spent on a
+// sub-agent that will correctly abstain.
+
+import { withRouteShapeWarnings } from '../route-normalize.mjs';
+
+const ERROR_RATE_DISQUALIFY_THRESHOLD = 0.5;
+
+export const metadata = {
+  id: 'slow_route',
+  threshold: '(p95 > 500 AND inv >= 1400) OR (p95 > 1500 AND inv >= 250); disqualified when 5xx rate > 50%; Vercel Workflow runtime endpoints are hard-gated',
+  billingDimension: 'function-duration',
+  scope: 'route',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Routes with p95 function duration above 500ms at meaningful traffic (>=1,400 invocations in window), OR catastrophically slow routes (>1500ms p95 at any volume >=250). High duration drives both function-duration cost and user-perceived latency. Investigate sequential awaits, slow external APIs, missing caching, N+1 patterns. Routes with >50% 5xx rate are disqualified — those are reliability problems, not performance tuning targets, and surface via route_errors instead. Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`) are hard-gated before launch because long-running step/flow requests are expected orchestration, not app-route bottlenecks.',
+};
+
+export function gate(signals) {
+  const routes = extractFunctionRoutes(signals);
+  const errorRates = extractErrorRatesByRoute(signals);
+  return routes
+    .filter((r) => (r.p95Ms > 500 && r.invocations >= 1400) || (r.p95Ms > 1500 && r.invocations >= 250))
+    .map((r) => {
+      const errorRate = errorRates.get(r.route);
+      const candidate = {
+        kind: metadata.id,
+        scope: 'route',
+        route: r.route,
+        files: [],
+        priority: Math.round(r.p95Ms * Math.max(r.invocations, 1) / 1000),
+        confidence: 0.94,
+        o11ySignal: `inv=${r.invocations},p95=${r.p95Ms}ms${errorRate != null ? `,5xx=${(errorRate * 100).toFixed(0)}%` : ''}`,
+        reason: 'slow high-traffic route',
+        question: `What is the concrete bottleneck in ${r.route} (p95=${r.p95Ms}ms over ${r.invocations} invocations), and which file-level change would reduce it?`,
+        evidence: { metric: 'fnDurationP95ByRoute', route: r.route, p95Ms: r.p95Ms, invocations: r.invocations, errorRate },
+      };
+      if (errorRate != null && errorRate > ERROR_RATE_DISQUALIFY_THRESHOLD) {
+        candidate.disqualified = true;
+        candidate.disqualifyReason = `high error rate (${(errorRate * 100).toFixed(0)}% 5xx — reliability issue, not performance; covered by route_errors gate)`;
+      }
+      return withRouteShapeWarnings(candidate, signals);
+    });
+}
+
+// Routes without status data are absent from the map → gate falls back to "no disqualification".
+function extractErrorRatesByRoute(signals) {
+  const m = signals.metrics?.fnStatusByRoute;
+  const out = new Map();
+  if (!Array.isArray(m?.rows)) return out;
+  const perRoute = new Map();
+  for (const row of m.rows) {
+    if (!row?.route) continue;
+    const v = row.value ?? 0;
+    const prior = perRoute.get(row.route) ?? { errors5xx: 0, total: 0 };
+    if (/^5/.test(String(row.http_status ?? ''))) prior.errors5xx += v;
+    prior.total += v;
+    perRoute.set(row.route, prior);
+  }
+  for (const [route, r] of perRoute) {
+    if (r.total > 0) out.set(route, r.errors5xx / r.total);
+  }
+  return out;
+}
+
+function extractFunctionRoutes(signals) {
+  const dur = signals.metrics?.fnDurationP95ByRoute;
+  if (!dur?.ok && !Array.isArray(dur?.rows)) return [];
+  const req = signals.metrics?.requestsByRouteCache;
+
+  const invByRoute = new Map();
+  for (const row of (req?.rows ?? [])) {
+    if (!row.route) continue;
+    invByRoute.set(row.route, (invByRoute.get(row.route) ?? 0) + (row.value ?? 0));
+  }
+
+  return (dur?.rows ?? [])
+    .filter((r) => r.route)
+    .map((r) => ({
+      route: r.route,
+      p95Ms: Math.round(r.value ?? 0),
+      invocations: invByRoute.get(r.route) ?? 0,
+    }));
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/types.d.ts b/skills/vercel/vercel-optimize/lib/gates/types.d.ts
new file mode 100644
index 0000000..ac454dc
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/types.d.ts
@@ -0,0 +1,38 @@
+export type CandidateScope = 'route' | 'file' | 'account';
+
+export interface GateMetadata {
+  id: string;
+  threshold: string;
+  billingDimension: string;
+  scope: CandidateScope | 'mixed';
+  sourceCitation?: string;
+  description?: string;
+}
+
+export interface Candidate {
+  kind: string;
+  scope: CandidateScope;
+  route?: string | null;
+  hostname?: string | null;
+  files: string[];
+  priority: number;
+  confidence: number;
+  o11ySignal?: string;
+  reason: string;
+  question: string;
+  evidence?: Record<string, unknown>;
+  disqualified?: boolean;
+  disqualifyReason?: string;
+  warnings?: string[];
+}
+
+export interface Signals {
+  metrics?: Record<string, unknown>;
+  codebase?: {
+    findings?: Array<Record<string, unknown>>;
+    routes?: Array<Record<string, unknown>>;
+  };
+  project?: Record<string, unknown>;
+  usage?: Record<string, unknown>;
+  stack?: Record<string, unknown>;
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/uncached-route.mjs b/skills/vercel/vercel-optimize/lib/gates/uncached-route.mjs
new file mode 100644
index 0000000..3898f59
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/uncached-route.mjs
@@ -0,0 +1,93 @@
+// getShare>0.20 filter WHY: a route that's >80% POST/PUT/DELETE is a mutation endpoint
+// where 0% cache is correct — recommending caching there is wrong.
+// cache_result values STALE/REVALIDATED/BYPASS fold into "total but not HIT" — matches the "uncached" framing.
+
+import { withRouteShapeWarnings } from '../route-normalize.mjs';
+
+const MIN_GET_SHARE = 0.20;
+
+/** @type {import('./types.d.ts').GateMetadata} */
+export const metadata = {
+  id: 'uncached_route',
+  threshold: `requests > 500 AND hitRate < 0.5 AND getShare > ${MIN_GET_SHARE} (missing getShare is gated)`,
+  billingDimension: 'edge-requests',
+  scope: 'route',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Routes serving > 500 requests/period at < 50% cache hit AND at least 20% GET traffic. Each uncached GET request reaches the function, costing edge requests + function duration. Routes that are mostly POST/PUT/DELETE (Server Actions, mutations) are skipped — 0% cache is correct behavior there. Routes with missing method-share data are gated instead of launched. Auth-gated routes are disqualified separately.',
+};
+
+/**
+ * @param {import('./types.d.ts').Signals} signals
+ * @returns {import('./types.d.ts').Candidate[]}
+ */
+export function gate(signals) {
+  const rates = extractCacheHitRates(signals);
+  const methods = extractMethodShares(signals);
+  return rates
+    .map((r) => ({ ...r, getShare: methods.get(r.route) ?? null }))
+    .filter((r) => r.requests > 500 && r.hitRate < 0.5)
+    .filter((r) => r.getShare === null || r.getShare > MIN_GET_SHARE)
+    .map((r) => {
+      const candidate = withRouteShapeWarnings({
+        kind: metadata.id,
+        scope: 'route',
+        route: r.route,
+        files: [],
+        priority: Math.round(r.requests * (1 - r.hitRate)),
+        confidence: r.getShare === null ? 0.5 : 0.92,
+        o11ySignal: `requests=${r.requests},cache=${(r.hitRate * 100).toFixed(0)}%${r.getShare !== null ? `,get=${(r.getShare * 100).toFixed(0)}%` : ''}`,
+        reason: 'uncached high-traffic route',
+        question: `Why does ${r.route} have ${(r.hitRate * 100).toFixed(0)}% cache hit rate on ${r.requests} requests in this metrics window, and is it safe to cache at the edge?`,
+        evidence: { metric: 'requestsByRouteCache', route: r.route, requests: r.requests, hitRate: r.hitRate, getShare: r.getShare },
+      }, signals);
+      if (r.getShare !== null) return candidate;
+      return {
+        ...candidate,
+        disqualified: true,
+        disqualifyReason: 'missing GET-share data — route method mix is required before recommending edge caching',
+        warnings: [...new Set([...(candidate.warnings ?? []), 'method-share:missing'])],
+      };
+    });
+}
+
+function extractCacheHitRates(signals) {
+  const m = signals.metrics?.requestsByRouteCache;
+  if (!m?.ok && !Array.isArray(m?.rows)) return [];
+
+  const perRoute = new Map();
+  for (const row of (m?.rows ?? [])) {
+    const route = row.route;
+    if (!route) continue;
+    const value = row.value ?? 0;
+    const prior = perRoute.get(route) ?? { route, hits: 0, total: 0 };
+    if (row.cache_result === 'HIT') prior.hits += value;
+    prior.total += value;
+    perRoute.set(route, prior);
+  }
+
+  return [...perRoute.values()].map((r) => ({
+    route: r.route,
+    requests: r.total,
+    hitRate: r.total > 0 ? r.hits / r.total : 0,
+  }));
+}
+
+function extractMethodShares(signals) {
+  const m = signals.metrics?.requestsByRouteMethod;
+  const out = new Map();
+  if (!Array.isArray(m?.rows)) return out;
+  const perRoute = new Map();
+  for (const row of m.rows) {
+    if (!row?.route) continue;
+    const v = row.value ?? 0;
+    const prior = perRoute.get(row.route) ?? { gets: 0, total: 0 };
+    if ((row.request_method ?? '').toUpperCase() === 'GET') prior.gets += v;
+    prior.total += v;
+    perRoute.set(row.route, prior);
+  }
+  for (const [route, r] of perRoute) {
+    if (r.total > 0) out.set(route, r.gets / r.total);
+  }
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/gates/usage-spike-triage.mjs b/skills/vercel/vercel-optimize/lib/gates/usage-spike-triage.mjs
new file mode 100644
index 0000000..feff90c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/gates/usage-spike-triage.mjs
@@ -0,0 +1,121 @@
+// Detects per-day billing spikes by inspecting usage.breakdown.data[] (daily granularity).
+// Fires when any single day's total bill > 2× the window mean, OR a single SKU's day value > 3× its window mean.
+// Emits one candidate per spiking SKU (or 'total' when the spike is broad).
+// Degrades gracefully when daily data is unavailable — common path because the skill prefers --group-by project, which omits daily breakdown.
+export const metadata = {
+  id: 'usage_spike_triage',
+  threshold: 'any-day total > 2x mean OR any-day SKU > 3x SKU mean',
+  billingDimension: 'mixed',
+  scope: 'account',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'A single day in the billing window deviates sharply from the window baseline. Triage branches: bot or AI crawler spike, viral moment, pricing-model migration (legacy SKU → new), code regression. Without daily-granularity data, this gate stays dormant.',
+};
+
+const TOTAL_MULTIPLIER = 2;
+const SKU_MULTIPLIER = 3;
+const MIN_BILLED_FLOOR = 5; // skip spikes whose absolute value is too small to matter
+
+export function gate(signals) {
+  const days = signals?.usage?.breakdown?.data;
+  if (!Array.isArray(days) || days.length < 3) return [];
+
+  const dayTotals = days.map(dayTotal);
+  const mean = dayTotals.reduce((a, b) => a + b, 0) / dayTotals.length;
+  if (mean <= MIN_BILLED_FLOOR) return [];
+
+  const totalSpikeDays = dayTotals
+    .map((value, idx) => ({ idx, value }))
+    .filter((d) => d.value > mean * TOTAL_MULTIPLIER && d.value > MIN_BILLED_FLOOR);
+
+  const skuStats = aggregateSkuStats(days);
+  const skuSpikes = [];
+  for (const stat of skuStats) {
+    if (stat.mean <= MIN_BILLED_FLOOR) continue;
+    for (const sample of stat.samples) {
+      if (sample.value > stat.mean * SKU_MULTIPLIER && sample.value > MIN_BILLED_FLOOR) {
+        skuSpikes.push({
+          name: stat.name,
+          dayIndex: sample.idx,
+          dayValue: sample.value,
+          skuMean: stat.mean,
+          multiplier: stat.mean > 0 ? sample.value / stat.mean : null,
+        });
+      }
+    }
+  }
+
+  if (totalSpikeDays.length === 0 && skuSpikes.length === 0) return [];
+
+  const candidates = [];
+  if (totalSpikeDays.length > 0) {
+    const peak = totalSpikeDays.reduce((a, b) => (a.value > b.value ? a : b));
+    candidates.push({
+      kind: metadata.id,
+      scope: 'account',
+      files: [],
+      priority: 60,
+      confidence: 0.78,
+      o11ySignal: `total_spike day_idx=${peak.idx} day_billed=${peak.value.toFixed(2)} window_mean=${mean.toFixed(2)} mult=${(peak.value / mean).toFixed(1)}x`,
+      reason: 'total billed cost on one day exceeds 2× the window mean',
+      question: 'Which workload generated the day-over-day spike — bot or AI-crawler traffic on a cacheable route, a viral event, a pricing-model migration, or a code regression?',
+      evidence: {
+        metric: 'usage.breakdown.data.total',
+        spikeDay: peak.idx,
+        spikeBilled: peak.value,
+        windowMean: mean,
+        multiplier: peak.value / mean,
+        skuName: 'total',
+      },
+    });
+  }
+  // Up to 3 SKU-specific candidates; the rest fold into 'multiple SKUs spiking' framing.
+  const orderedSkuSpikes = skuSpikes.sort((a, b) => b.dayValue - a.dayValue).slice(0, 3);
+  for (const spike of orderedSkuSpikes) {
+    candidates.push({
+      kind: metadata.id,
+      scope: 'account',
+      files: [],
+      priority: 55,
+      confidence: 0.78,
+      o11ySignal: `sku_spike sku="${spike.name}" day_idx=${spike.dayIndex} day_billed=${spike.dayValue.toFixed(2)} sku_mean=${spike.skuMean.toFixed(2)} mult=${spike.multiplier.toFixed(1)}x`,
+      reason: `${spike.name} on one day exceeds 3× its window mean`,
+      question: `${spike.name} spiked ${spike.multiplier.toFixed(1)}× on day ${spike.dayIndex}. Which event (bot traffic, viral content, deploy regression, integration sync) drove it, and is the spiking SKU one the skill already covers?`,
+      evidence: {
+        metric: 'usage.breakdown.data.services',
+        skuName: spike.name,
+        spikeDay: spike.dayIndex,
+        spikeBilled: spike.dayValue,
+        skuMean: spike.skuMean,
+        multiplier: spike.multiplier,
+      },
+    });
+  }
+  return candidates;
+}
+
+function dayTotal(day) {
+  if (Array.isArray(day?.services)) {
+    return day.services.reduce((a, s) => a + Number(s.billedCost ?? s.cost ?? 0), 0);
+  }
+  return Number(day?.billedCost ?? day?.cost ?? 0);
+}
+
+function aggregateSkuStats(days) {
+  const byName = new Map();
+  days.forEach((day, idx) => {
+    const services = Array.isArray(day?.services) ? day.services : [];
+    for (const svc of services) {
+      const name = String(svc?.name ?? '').trim();
+      if (!name) continue;
+      const value = Number(svc.billedCost ?? svc.cost ?? 0);
+      if (!byName.has(name)) byName.set(name, { name, samples: [] });
+      byName.get(name).samples.push({ idx, value });
+    }
+  });
+  for (const stat of byName.values()) {
+    const sum = stat.samples.reduce((a, s) => a + s.value, 0);
+    stat.mean = stat.samples.length > 0 ? sum / stat.samples.length : 0;
+  }
+  return [...byName.values()];
+}
diff --git a/skills/vercel/vercel-optimize/lib/grade-recommendation.mjs b/skills/vercel/vercel-optimize/lib/grade-recommendation.mjs
new file mode 100644
index 0000000..ca577e9
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/grade-recommendation.mjs
@@ -0,0 +1,155 @@
+// 4-axis rubric (specificity, actionability, grounding, evidence) → bucket. See references/recommendations.md.
+// Account-scope (platform_*) recs use a separate grounding/evidence pair — they structurally cannot produce file:line.
+
+const HEDGE_WORDS = /\b(consider|might|may|could|perhaps|maybe|likely|probably)\b/gi;
+const VERB_OPENERS = /^\s*(?:[-*]\s+|\d+[.)]\s+|[*_]+)?(?:add|set|enable|disable|replace|remove|move|wrap|cache|defer|parallelize|introduce|configure|update|change|switch|opt[-\s]?in|opt[-\s]?out|export|import|install|run|delete|rename)/im;
+const COUNT_WORDS_RE = /\b(errors?|queries|invocations|requests|reads|writes|bytes|fetch(?:es)?|calls?|hits?|misses?|seconds?|images?|deployments?|cold[- ]?starts?|users?)\b/gi;
+const UNIT_RE = /\b\d[\d.,]*\s*(?:%|ms|s|sec|seconds?|min|minutes?|h|hours?|GB|MB|KB|K|M|B|rps|qps|req\/s|reqs?\/min)\b/gi;
+const CODE_FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`\n]{10,}`/g;
+const FILE_LINE_RE = /[\w/.\-()\[\]]+\.\w+:\d+/g;
+
+// Grounding + evidence are lie-detectors — weighted higher than specificity/actionability, which LLMs can game with fluff.
+const W = { grounding: 0.35, evidence: 0.30, specificity: 0.20, actionability: 0.15 };
+
+export function gradeRecommendation(rec, ctx = {}) {
+  const accountScope = isAccountScope(rec);
+  const specificity = scoreSpecificity(rec);
+  const actionability = scoreActionability(rec);
+  const grounding = accountScope ? scoreGroundingAccount(rec) : scoreGrounding(rec, ctx);
+  const evidence = accountScope ? scoreEvidenceAccount(rec) : scoreEvidence(rec);
+  const overall = roundTo(
+    grounding * W.grounding + evidence * W.evidence + specificity * W.specificity + actionability * W.actionability,
+    4,
+  );
+  return {
+    specificity, actionability, grounding, evidence, overall,
+    grade: grade(overall),
+    scope: accountScope ? 'account' : 'route',
+  };
+}
+
+function isAccountScope(rec) {
+  if (rec?.scope === 'account') return true;
+  const ref = rec?.candidateRef;
+  if (typeof ref === 'string' && ref.startsWith('platform_')) return true;
+  return false;
+}
+
+function grade(overall) {
+  if (overall >= 0.85) return 'Excellent';
+  if (overall >= 0.70) return 'Good';
+  if (overall >= 0.55) return 'Fair';
+  return 'Poor';
+}
+
+function scoreSpecificity(rec) {
+  let s = 0;
+  const codeText = [rec.fix, rec.currentBehavior, rec.desiredBehavior].filter((x) => typeof x === 'string').join('\n');
+  const hasFence = CODE_FENCE_RE.test(codeText);
+  CODE_FENCE_RE.lastIndex = 0;
+  if (hasFence) s += 0.5;
+  if (INLINE_CODE_RE.test(codeText)) s += 0.2;
+  INLINE_CODE_RE.lastIndex = 0;
+  if (Array.isArray(rec.affectedFiles) && rec.affectedFiles.length > 0) s += 0.2;
+  if (Array.isArray(rec.findingRefs) && rec.findingRefs.some((r) => /:\d+/.test(r))) s += 0.3;
+  return Math.min(1, roundTo(s, 4));
+}
+
+function scoreActionability(rec) {
+  const text = typeof rec.fix === 'string' ? rec.fix : '';
+  if (!text) return 0;
+  let s = 0;
+  if (VERB_OPENERS.test(text)) s += 0.35;
+  const stepCount = (text.match(/(?:^|\n)\s*(?:\d+[.)]\s+|[-*]\s+)/g) ?? []).length;
+  if (stepCount >= 2) s += 0.35;
+  else if (stepCount === 1) s += 0.15;
+  const hedges = (text.match(HEDGE_WORDS) ?? []).length;
+  HEDGE_WORDS.lastIndex = 0;
+  s -= Math.min(0.3, hedges * 0.1);
+  // Baseline so a verb-only one-liner still scores.
+  s += 0.3;
+  return Math.max(0, Math.min(1, roundTo(s, 4)));
+}
+
+function scoreGrounding(rec, ctx) {
+  let s = 0;
+  const knownFindings = Array.isArray(ctx.knownFindings) ? ctx.knownFindings : [];
+  const findingKeys = new Set(knownFindings.map((f) => `${f.file}:${f.line}`));
+  const refs = Array.isArray(rec.findingRefs) ? rec.findingRefs : [];
+  const matched = refs.filter((r) => findingKeys.has(r));
+  if (matched.length > 0) s += 0.5;
+  else if (refs.length > 0) s += 0.25;
+  if (Array.isArray(rec.affectedFiles) && rec.affectedFiles.length > 0) s += 0.25;
+  const fenceText = [rec.currentBehavior, rec.desiredBehavior].filter((x) => typeof x === 'string').join('\n');
+  if (CODE_FENCE_RE.test(fenceText)) s += 0.25;
+  CODE_FENCE_RE.lastIndex = 0;
+  if (typeof rec.candidateRef === 'string' && rec.candidateRef.length > 0) s += 0.1;
+  return Math.min(1, roundTo(s, 4));
+}
+
+function scoreEvidence(rec) {
+  const text = [rec.what, rec.why, rec.fix, rec.verify]
+    .filter((x) => typeof x === 'string').join('\n');
+  if (!text) return 0;
+  const counts = (text.match(COUNT_WORDS_RE) ?? []).length;
+  COUNT_WORDS_RE.lastIndex = 0;
+  const units = (text.match(UNIT_RE) ?? []).length;
+  UNIT_RE.lastIndex = 0;
+  const filelines = (text.match(FILE_LINE_RE) ?? []).length;
+  FILE_LINE_RE.lastIndex = 0;
+  // file:line is the gold standard.
+  let s = Math.min(0.5, filelines * 0.2)
+        + Math.min(0.3, units * 0.075)
+        + Math.min(0.2, counts * 0.05);
+  return Math.min(1, roundTo(s, 4));
+}
+
+// No findingRefs/code fences possible — grade structural tie to gate + signal-quoting.
+function scoreGroundingAccount(rec) {
+  let s = 0;
+  if (typeof rec.candidateRef === 'string' && rec.candidateRef.startsWith('platform_')) s += 0.4;
+  else if (typeof rec.candidateRef === 'string' && rec.candidateRef.length > 0) s += 0.2;
+  // Quoting deep-dive data in why/fix is the account-scope equivalent of citing file:line.
+  const text = [rec.why, rec.fix, rec.verify].filter((x) => typeof x === 'string').join('\n');
+  const units = (text.match(UNIT_RE) ?? []).length;
+  UNIT_RE.lastIndex = 0;
+  if (units >= 3) s += 0.4;
+  else if (units >= 1) s += 0.2;
+  const citations = Array.isArray(rec.citations) ? rec.citations.length : 0;
+  if (citations >= 2) s += 0.2;
+  else if (citations >= 1) s += 0.1;
+  return Math.min(1, roundTo(s, 4));
+}
+
+// Heavily weighted toward magnitude quoting — vague platform recs should score low.
+function scoreEvidenceAccount(rec) {
+  const text = [rec.what, rec.why, rec.fix, rec.verify]
+    .filter((x) => typeof x === 'string').join('\n');
+  if (!text) return 0;
+  const counts = (text.match(COUNT_WORDS_RE) ?? []).length;
+  COUNT_WORDS_RE.lastIndex = 0;
+  const units = (text.match(UNIT_RE) ?? []).length;
+  UNIT_RE.lastIndex = 0;
+  // Higher weight than route-scope variant — file:line gold standard isn't available.
+  let s = Math.min(0.55, units * 0.15) + Math.min(0.35, counts * 0.08);
+  if (typeof rec.o11ySignal === 'string' && rec.o11ySignal.length > 0) s += 0.1;
+  return Math.min(1, roundTo(s, 4));
+}
+
+function roundTo(n, d) {
+  const f = 10 ** d;
+  return Math.round(n * f) / f;
+}
+
+// 0.55 = Poor/Fair boundary. Recommending Poor-graded items erodes trust faster than the marginal recall benefit.
+export function applyQualityFloor(recs, floor = 0.55) {
+  const kept = [];
+  const dropped = [];
+  for (const rec of recs) {
+    const o = rec?.quality?.overall ?? 0;
+    if (o < floor) dropped.push({ rec, reason: `quality.overall=${o} < floor=${floor}` });
+    else kept.push(rec);
+  }
+  return { kept, dropped };
+}
diff --git a/skills/vercel/vercel-optimize/lib/impact-label.mjs b/skills/vercel/vercel-optimize/lib/impact-label.mjs
new file mode 100644
index 0000000..b9bb61e
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/impact-label.mjs
@@ -0,0 +1,126 @@
+import { impactMagnitude } from './impact-magnitude.mjs';
+
+const SLOW_ROUTE_P95_THRESHOLD_MS = 500;
+const CACHE_HIT_THRESHOLD_PCT = 50;
+const COLD_START_THRESHOLD_PCT = 40;
+const RELIABILITY_TARGET_PCT = 0.1;
+
+export function computeImpactLabel(rec, signals = {}) {
+  const il = rec?.impactLabel ?? {};
+  if (il.performance) return il.performance;
+  if (il.costPhrase) return il.costPhrase;
+
+  if (typeof rec?.estimatedSavingsUsd === 'number' && rec.impactTier) {
+    const magnitude = impactMagnitude({
+      currentCost: rec.estimatedSavingsUsd,
+      impactTier: rec.impactTier,
+    });
+    return magnitude.phrase;
+  }
+
+  return synthesizeImpactFromSignal(rec, signals);
+}
+
+export function synthesizeImpactFromSignal(rec, signals = {}) {
+  const tier = rec?.impactTier;
+  const sig = [
+    rec?.o11ySignal,
+    rec?.evidence?.o11ySignal,
+    rec?.why,
+    rec?.what,
+  ].filter((v) => typeof v === 'string' && v.trim()).join('\n') || null;
+  if (!sig || !tier) return null;
+  const m = String(sig);
+  const inv = parseSigNumber(m, /inv=([\d,]+)/);
+  const p95 = parseSigNumber(m, /p95=([\d,]+)ms/);
+  const cachePct = parseSigNumber(m, /cache=([\d.]+)%/);
+  const coldPct = parseSigNumber(m, /cold=([\d.]+)%/);
+  const buildSharePct = parseSigNumber(m, /build_minutes_share=([\d.]+)%/i) ??
+    parseSigNumber(m, /build(?: CPU)? minutes share:?\s*([\d.]+)%/i);
+  const errors = parseSigNumber(m, /errs=([\d,]+)/);
+  const errorRatePct = parseSigNumber(m, /rate=([\d.]+)%/);
+  const writes = parseSigNumber(m, /writes=([\d,]+)/);
+  const reads = parseSigNumber(m, /reads=([\d,]+)/);
+  const cwvIssues = [
+    cwvIssue('LCP', parseSigNumber(m, /LCP=([\d.]+)ms/i), 2500, 'ms'),
+    cwvIssue('INP', parseSigNumber(m, /INP=([\d.]+)ms/i), 200, 'ms'),
+    cwvIssue('CLS', parseSigNumber(m, /CLS=([\d.]+)/i), 0.1, ''),
+  ].filter(Boolean);
+
+  if (cwvIssues.length > 0) {
+    return `${tier} impact — bring ${joinEnglish(cwvIssues.map(formatCwvIssue))}.`;
+  }
+  if (errors != null && errorRatePct != null) {
+    const reductionPct = Math.ceil(Math.max(0, (1 - (RELIABILITY_TARGET_PCT / errorRatePct)) * 100));
+    return `${tier} impact — cut 5xx rate by ~${reductionPct}% to get below ${RELIABILITY_TARGET_PCT}% (current ${errorRatePct}%, ${formatInteger(errors)} errors in this window).`;
+  }
+  if (errors != null) {
+    return `${tier} impact — resolve ${formatInteger(errors)} billed 5xx errors in this window.`;
+  }
+  if (cachePct != null && inv != null) {
+    if (cachePct < CACHE_HIT_THRESHOLD_PCT) {
+      return `${tier} impact — current cache hit rate is ${cachePct}% across ${formatInteger(inv)} requests in this window; the gate fires below ${CACHE_HIT_THRESHOLD_PCT}%.`;
+    }
+    if (p95 == null) {
+      return `${tier} impact — current cache hit rate is ${cachePct}% across ${formatInteger(inv)} requests in this window; this recommendation targets the remaining uncached traffic.`;
+    }
+  }
+  if (writes != null && reads != null) {
+    const ratio = reads > 0 ? writes / reads : null;
+    return ratio == null
+      ? `${tier} impact — ${formatInteger(writes)} ISR write units with no recorded read units in this window.`
+      : `${tier} impact — ${formatInteger(writes)} ISR write units vs ${formatInteger(reads)} read units in this window (${round2(ratio)} writes per read).`;
+  }
+  if (p95 != null && inv != null) {
+    const multiple = p95 / SLOW_ROUTE_P95_THRESHOLD_MS;
+    return `${tier} impact — current 95th percentile duration is ${formatInteger(p95)}ms across ${formatInteger(inv)} function invocations in this window (${round1(multiple)}x the ${formatInteger(SLOW_ROUTE_P95_THRESHOLD_MS)}ms slow-route threshold).`;
+  }
+  if (coldPct != null) {
+    return `${tier} impact — current cold-start share is ${coldPct}%; the gate fires above ${COLD_START_THRESHOLD_PCT}%.`;
+  }
+  if (rec?.candidateRef?.startsWith('build_minutes_fanout:') || rec?.kind === 'build_minutes_fanout') {
+    return buildSharePct != null
+      ? `${tier} impact — Build CPU Minutes account for ${buildSharePct}% of observed billed cost in this window.`
+      : `${tier} impact — Build CPU Minutes exceeded the gate threshold in this window.`;
+  }
+  return `${tier} impact — see follow-up metrics for magnitude.`;
+}
+
+function cwvIssue(metric, value, threshold, unit) {
+  if (value == null || value <= threshold) return null;
+  return { metric, value, threshold, unit };
+}
+
+function formatCwvIssue(i) {
+  const current = i.metric === 'CLS' ? round2(i.value) : Math.round(i.value);
+  if (i.unit === 'ms') {
+    return `${i.metric} below ${formatInteger(i.threshold)}ms (current ${formatInteger(current)}ms)`;
+  }
+  return `${i.metric} below ${i.threshold}${i.unit} (current ${current}${i.unit})`;
+}
+
+function joinEnglish(parts) {
+  if (parts.length <= 1) return parts[0] ?? '';
+  if (parts.length === 2) return `${parts[0]} and ${parts[1]}`;
+  return `${parts.slice(0, -1).join(', ')}, and ${parts.at(-1)}`;
+}
+
+function parseSigNumber(s, re) {
+  const m = re.exec(s);
+  if (!m) return null;
+  const n = Number(String(m[1]).replace(/,/g, ''));
+  return Number.isFinite(n) ? n : null;
+}
+
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function formatInteger(n) {
+  if (!Number.isFinite(n)) return String(n);
+  return Math.round(n).toLocaleString('en-US');
+}
diff --git a/skills/vercel/vercel-optimize/lib/impact-magnitude.mjs b/skills/vercel/vercel-optimize/lib/impact-magnitude.mjs
new file mode 100644
index 0000000..e81c0ea
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/impact-magnitude.mjs
@@ -0,0 +1,60 @@
+// Rule: precision for performance, magnitudes for cost. Customer-facing phrases never contain $N literals.
+
+export function impactMagnitude({ currentCost, impactTier }) {
+  const fraction = { high: 0.4, medium: 0.2, low: 0.1 }[impactTier] ?? 0.2;
+  const estUsd = (currentCost ?? 0) * fraction;
+
+  if (estUsd < 5) {
+    return { magnitude: 'negligible', phrase: 'small cost impact at current traffic' };
+  }
+  if (estUsd < 50) {
+    return { magnitude: 'small', phrase: 'low-tens of dollars per month at current traffic' };
+  }
+  if (estUsd < 500) {
+    return { magnitude: 'medium', phrase: 'hundreds of dollars per month at current traffic' };
+  }
+  if (estUsd < 5000) {
+    return { magnitude: 'large', phrase: 'low-thousands of dollars per month at current traffic' };
+  }
+  return { magnitude: 'very-large', phrase: 'thousands+ of dollars per month at current traffic' };
+}
+
+// Preserves Postgres placeholders ($1, $2, …) — digits with no comma/period/k/m suffix.
+export function stripDollarLiterals(text) {
+  if (!text || typeof text !== 'string') return { text, stripped: 0 };
+
+  let count = 0;
+  const cleaned = text.replace(
+    /\$[\d][\d.,]*(?:[kKmMbB])?(?:\/[\dA-Za-z]+)?/g,
+    (m) => {
+      if (/^\$\d+$/.test(m)) return m;
+      count++;
+      return 'the billed cost';
+    }
+  );
+
+  return { text: cleaned, stripped: count };
+}
+
+export function applyDollarStrip(rec) {
+  const fields = ['what', 'why', 'fix', 'impact', 'currentBehavior', 'desiredBehavior', 'before', 'after'];
+  let totalStripped = 0;
+  for (const f of fields) {
+    if (typeof rec[f] !== 'string') continue;
+    // Preserve code-fence content so example snippets aren't mangled.
+    const fences = [];
+    rec[f] = rec[f].replace(/```[\s\S]*?```/g, (m) => {
+      fences.push(m);
+      return `__FENCE_${fences.length - 1}__`;
+    });
+    const { text, stripped } = stripDollarLiterals(rec[f]);
+    rec[f] = text;
+    totalStripped += stripped;
+    rec[f] = rec[f].replace(/__FENCE_(\d+)__/g, (_, i) => fences[Number(i)]);
+  }
+  if (totalStripped > 0) {
+    rec.sanitizerTrail = rec.sanitizerTrail ?? [];
+    rec.sanitizerTrail.push(`$-strip:${totalStripped}`);
+  }
+  return rec;
+}
diff --git a/skills/vercel/vercel-optimize/lib/investigation-brief.mjs b/skills/vercel/vercel-optimize/lib/investigation-brief.mjs
new file mode 100644
index 0000000..d526723
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/investigation-brief.mjs
@@ -0,0 +1,610 @@
+// Sub-agent investigation brief — the entire prompt the sub-agent sees.
+// Constraints: target ≤ 12 KB per brief; deterministic (same input → byte-identical output, modulo generatedAt).
+
+import { isAbsolute, join, normalize, relative } from 'node:path';
+import { loadLibrary, matchesFrameworkVersion } from './citations.mjs';
+import { deriveProjectFacts } from './project-facts.mjs';
+import { renderSupportTopics } from './support-topics.mjs';
+
+const NON_LAYOUT_FILE_CAP = 12;
+const LAYOUT_FILE_CAP = 3;
+
+// Playbook is a tilt, not a requirement.
+export function inferPlaybook(signals) {
+  const deps = signals?.stack?.deps ?? {};
+  const codebaseStack = signals?.codebase?.stack ?? {};
+  const routes = signals?.codebase?.routes ?? [];
+  const routePaths = routes.map((r) => r.routePath ?? '');
+  const services = Array.isArray(signals?.usage?.services) ? signals.usage.services : [];
+
+  const has = (name) => Boolean(deps[name]);
+  const hasPrefix = (prefix) => Object.keys(deps).some((k) => k === prefix || k.startsWith(prefix));
+  const anyRouteMatches = (re) => routePaths.some((p) => re.test(p));
+  const usageHas = (re, minBilled = 0) =>
+    services.some((s) => re.test(String(s?.name ?? '')) && Number(s?.billedCost ?? s?.cost ?? 0) > minBilled);
+
+  // AI app first — billing shape (AI Gateway > Sandbox > Function Duration) overrides
+  // the ecommerce/saas tilt when both apply (an "AI shopping assistant" lives in ai-application's
+  // priority patterns, not the cart-checkout ones).
+  const aiDep =
+    has('@vercel/sandbox')
+    || has('@vercel/ai-gateway')
+    || has('ai')
+    || has('openai')
+    || has('@anthropic-ai/sdk')
+    || hasPrefix('@ai-sdk/');
+  const aiUsage = usageHas(/^AI Gateway$/i) || usageHas(/^Sandbox/i);
+  if (aiDep || aiUsage) {
+    return 'ai-application';
+  }
+  if (has('stripe') || has('@stripe/stripe-js') || has('react-stripe-js') ||
+      anyRouteMatches(/^\/(cart|checkout|products?)\b/i)) {
+    return 'ecommerce';
+  }
+  if (has('next-auth') || has('@clerk/nextjs') || has('@workos-inc/authkit-nextjs') ||
+      anyRouteMatches(/^\/(admin|dashboard|settings|account|billing)\b/i)) {
+    return 'saas';
+  }
+  if (routes.length > 0 && routes.every((r) => /^\/api\//.test(r.routePath ?? ''))) {
+    return 'api-service';
+  }
+  if (codebaseStack.hasAppRouter || codebaseStack.hasPagesRouter) {
+    if (anyRouteMatches(/^\/(blog|docs|posts?|articles?|guides?)\b/i)) return 'content-site';
+    if (anyRouteMatches(/^\/\(?marketing\)?\b/i)) return 'marketing';
+  }
+  return null;
+}
+
+// SvelteKit/Nuxt/Astro have framework-shaped advice that doesn't fit the Next.js-flavored profile playbooks — both can ship together.
+export function inferFrameworkPlaybook(signals) {
+  const stack = signals?.stack ?? signals?.codebase?.stack ?? {};
+  switch (stack.framework) {
+    case 'sveltekit': return 'sveltekit';
+    default: return null;
+  }
+}
+
+// Empty result = no source files; investigate via evidence only (legitimate for platform_* candidates).
+// Workspace imports expand one level deep — keeps brief small. A thin shell page.tsx delegates work; bottleneck usually lives in workspace files.
+export function resolveFiles(candidate, signals) {
+  const route = candidate.route;
+  const routes = signals?.codebase?.routes ?? [];
+  if (Array.isArray(candidate.files) && candidate.files.length > 0) {
+    return capBriefFiles(candidate.files, route ? closestAncestorLayoutFiles(route, routes) : [], routes);
+  }
+  if (!route) return [];
+  const nonLayoutRoutes = routes.filter((r) => r.type !== 'layout');
+  const layoutFiles = closestAncestorLayoutFiles(route, routes);
+  let matched = nonLayoutRoutes.filter((r) => r.routePath === route);
+  if (matched.length === 0) {
+    // Fuzzy: prefer max literal-segment matches so `/event/[code]/teaser` beats `/event/[code]/[location]` when candidate is `/event/[*]/teaser`.
+    const scored = nonLayoutRoutes
+      .map((r) => ({ r, score: routePathMatchScore(r.routePath, route) }))
+      .filter((x) => x.score > 0);
+    if (scored.length === 0) return capBriefFiles([], layoutFiles, routes);
+    const top = Math.max(...scored.map((s) => s.score));
+    matched = scored.filter((s) => s.score === top).map((s) => s.r);
+  }
+  const direct = matched.map((r) => r.file).filter(Boolean);
+  const workspaceImports = matched
+    .flatMap((r) => Array.isArray(r.workspaceImports) ? r.workspaceImports : [])
+    .filter(Boolean);
+  return capBriefFiles(uniq([...direct, ...workspaceImports]), layoutFiles, routes);
+}
+
+// literal-segment match × 10, dynamic × 1, pure equality = sentinel that always wins.
+export function routePathMatchScore(routePath, metricPath) {
+  if (typeof routePath !== 'string' || typeof metricPath !== 'string') return 0;
+  if (routePath === metricPath) return 1000 + routePath.split('/').filter(Boolean).length;
+  const rTokens = routePath.split('/').filter(Boolean);
+  const mTokens = metricPath.split('/').filter(Boolean);
+  let ri = 0, mi = 0, literals = 0, dynamicMatches = 0;
+  while (ri < rTokens.length && mi < mTokens.length) {
+    const r = rTokens[ri];
+    const m = mTokens[mi];
+    if (isCatchAllPlaceholder(r)) return 1 + literals * 10 + dynamicMatches;
+    if (r === m) { literals++; ri++; mi++; continue; }
+    // Route patterns may match concrete metric paths, and route/metric dynamic
+    // placeholders may match each other. A metric-side placeholder must not
+    // match a static route literal: that would let `/docs/[...slug]` traffic
+    // attach to an unrelated static scanner route like `/docs/llms.txt`.
+    if (isDynamicPlaceholder(r) && !isCatchAllPlaceholder(m)) { dynamicMatches++; ri++; mi++; continue; }
+    return 0;
+  }
+  if (ri === rTokens.length - 1 && /^\[\[\.\.\..+\]\]$/.test(rTokens[ri]) && mi === mTokens.length) {
+    return 1 + literals * 10 + dynamicMatches;
+  }
+  if (ri !== rTokens.length || mi !== mTokens.length) {
+    return trailingSingleDynamicPartialScore(rTokens, mTokens, ri, mi, literals, dynamicMatches);
+  }
+  return 1 + literals * 10 + dynamicMatches;
+}
+
+export function routePathsMatch(routePath, metricPath) {
+  return routePathMatchScore(routePath, metricPath) > 0;
+}
+
+function isDynamicPlaceholder(token) {
+  return /^\[.*\]$/.test(token);
+}
+function isSingleDynamicPlaceholder(token) {
+  return /^\[[^[.\].][^\]]*\]$/.test(token);
+}
+function isCatchAllPlaceholder(token) {
+  return /^\[(?:\[\.\.\..+\]|\.\.\..+)\]$/.test(token) || /^\[\.\.\..+\]$/.test(token) || /^\[\[\.\.\..+\]\]$/.test(token);
+}
+
+function trailingSingleDynamicPartialScore(rTokens, mTokens, ri, mi, literals, dynamicMatches) {
+  const rRemaining = rTokens.length - ri;
+  const mRemaining = mTokens.length - mi;
+  if (Math.abs(rRemaining - mRemaining) !== 1) return 0;
+  if (rRemaining !== 0 && mRemaining !== 0) return 0;
+  const lastRouteToken = rTokens[ri - 1];
+  const lastMetricToken = mTokens[mi - 1];
+  if (!isSingleDynamicPlaceholder(lastRouteToken) && !isSingleDynamicPlaceholder(lastMetricToken)) return 0;
+  return literals * 10 + dynamicMatches;
+}
+
+function uniq(xs) { return Array.from(new Set(xs)); }
+
+function briefRoots(signals) {
+  const codebase = signals?.codebase ?? {};
+  const appRoot = typeof codebase.rootDir === 'string' && codebase.rootDir.length > 0
+    ? normalize(codebase.rootDir)
+    : null;
+  const repoRoot = typeof codebase.monorepoRoot === 'string' && codebase.monorepoRoot.length > 0
+    ? normalize(codebase.monorepoRoot)
+    : appRoot;
+  return { appRoot, repoRoot };
+}
+
+function absoluteBriefPath(file, roots) {
+  if (typeof file !== 'string' || file.length === 0) return null;
+  if (isAbsolute(file)) return normalize(file);
+  const base = isRepoRelativePath(file) ? roots.repoRoot : roots.appRoot;
+  return base ? normalize(join(base, file)) : null;
+}
+
+function repoRelativeBriefPath(file, roots) {
+  if (typeof file !== 'string' || file.length === 0) return null;
+  const normalized = normalize(file);
+  if (isRepoRelativePath(normalized)) return normalized;
+  const abs = absoluteBriefPath(file, roots);
+  if (!abs || !roots.repoRoot) return normalized;
+  const rel = normalize(relative(roots.repoRoot, abs));
+  return rel.startsWith('..') ? normalized : rel;
+}
+
+function isRepoRelativePath(file) {
+  return /^(apps|packages)\//.test(file);
+}
+
+function capBriefFiles(nonLayoutCandidates, layoutCandidates, routes) {
+  const knownLayoutFiles = new Set(routes.filter((r) => r.type === 'layout').map((r) => r.file).filter(Boolean));
+  const nonLayout = [];
+  const layouts = [];
+  for (const f of uniq(nonLayoutCandidates)) {
+    if (knownLayoutFiles.has(f) || isLayoutPath(f)) layouts.push(f);
+    else nonLayout.push(f);
+  }
+  for (const f of layoutCandidates) layouts.push(f);
+  return [
+    ...uniq(nonLayout).slice(0, NON_LAYOUT_FILE_CAP),
+    ...uniq(layouts).slice(0, LAYOUT_FILE_CAP),
+  ];
+}
+
+function closestAncestorLayoutFiles(route, routes) {
+  if (!route) return [];
+  return routes
+    .filter((r) => r.type === 'layout' && r.file && layoutAppliesToRoute(r.routePath, route))
+    .sort((a, b) =>
+      routeDepth(b.routePath) - routeDepth(a.routePath)
+      || a.file.localeCompare(b.file)
+    )
+    .map((r) => r.file);
+}
+
+function layoutAppliesToRoute(layoutPath, routePath) {
+  if (typeof layoutPath !== 'string' || typeof routePath !== 'string') return false;
+  if (layoutPath === '/') return true;
+  const layoutTokens = layoutPath.split('/').filter(Boolean);
+  const routeTokens = routePath.split('/').filter(Boolean);
+  if (layoutTokens.length > routeTokens.length) return false;
+  for (let i = 0; i < layoutTokens.length; i++) {
+    const l = layoutTokens[i];
+    const r = routeTokens[i];
+    if (isCatchAllPlaceholder(l)) return true;
+    if (l === r) continue;
+    if (isDynamicPlaceholder(l) || isDynamicPlaceholder(r)) continue;
+    return false;
+  }
+  return true;
+}
+
+function routeDepth(routePath) {
+  return String(routePath ?? '').split('/').filter(Boolean).length;
+}
+
+function isLayoutPath(file) {
+  return /(^|\/)(?:\+layout(?:\.server)?|layout)\.(?:svelte|tsx?|jsx?)$/.test(String(file ?? ''));
+}
+
+// Tells the sub-agent which signals are missing so it doesn't conflate "no data" with "no bottleneck."
+export function summarizeDeepDiveFailures(deepDive) {
+  if (!deepDive || typeof deepDive !== 'object') return null;
+  const entries = Object.entries(deepDive);
+  if (entries.length === 0) return null;
+  const failures = entries.filter(([, v]) => isFailureEntry(v));
+  if (failures.length === 0) return null;
+  // Surface when ≥50% failed OR ≥3 distinct signals failed.
+  if (failures.length / entries.length < 0.5 && failures.length < 3) return null;
+  const failedIds = failures.map(([k]) => k).slice(0, 6).join(', ');
+  const codes = uniq(failures.map(([, v]) => v?.code ?? v?.error ?? 'unknown')).slice(0, 3).join(' / ');
+  return `${failures.length} of ${entries.length} deep-dive signals failed (${failedIds}${failures.length > 6 ? ', …' : ''}) — error: ${codes}.`;
+}
+
+function isFailureEntry(v) {
+  if (!v || typeof v !== 'object') return false;
+  if (v.ok === false) return true;
+  if (typeof v.code === 'string' && v.code !== 'OK') return true;
+  if (typeof v.error === 'string' && v.error.length > 0) return true;
+  return false;
+}
+
+export async function citationSubset(candidateKind, framework, version) {
+  const lib = await loadLibrary();
+  const versionOk = (entry) =>
+    entry.applicableFrameworks.includes('*') ||
+    entry.applicableFrameworks.some((p) => matchesFrameworkVersion(p, framework, version));
+  const kindOk = (entry) => {
+    const at = Array.isArray(entry.appliesTo) ? entry.appliesTo : [];
+    return at.length === 0 || at.includes(candidateKind);
+  };
+  return {
+    urls: lib.urls.filter((e) => versionOk(e) && kindOk(e)),
+    ruleSkillRefs: lib.ruleSkillRefs.filter((r) => versionOk(r) && kindOk(r)),
+  };
+}
+
+// Per-kind hints tell the investigator which comparison to draw first.
+export const KIND_INTERPRETATION_HINTS = {
+  slow_route: [
+    'Compare `cpu.p95` vs `latency.p95`. If cpu << latency, the bottleneck is wall-clock / external IO / awaits — look for sequential awaits, slow DB queries, slow external APIs. If cpu ≈ latency, look for in-process compute (rendering, JSON serialization, crypto).',
+    'Compare `ttfb.p95` vs `latency.p95`. If ttfb ≈ latency, response generation finishes near the end — streaming or `after()` may shift perceived latency.',
+    'For streaming, SSE, resumable chat, or other intentionally long-lived routes, do not treat high wall-clock duration alone as a bug. Recommend a change only when evidence shows avoidable pre-first-byte work, high active CPU, duplicate invocations, or post-response work that can move out of the user-visible path.',
+    'Inspect `perDeployment`: a 2x step between deployments points to a regression introduced in the newer deployment. Frame the rec as "regression introduced in <deployment_id>" rather than a generic perf claim.',
+    'Inspect `startTypeSplit.cold` share. >5% cold means cold starts contribute meaningfully — Fluid Compute or warmer keep-alive is on the table.',
+    'Inspect `statusDistribution`. A non-trivial 3xx/4xx slice may be inflating p95 because redirects/auth bounces still count as invocations.',
+    'Inspect `cacheBreakdown`. If the route uses Next.js `dynamic = \'error\'` (or otherwise static) but the breakdown shows substantial MISS/BYPASS counts, the latency lives on the cache-miss path — investigate the origin fetch / ISR revalidation cost, NOT in-handler compute. `bandwidthByCache` tells you the byte cost of those misses.',
+  ],
+  uncached_route: [
+    '`cacheBreakdown` tells you what fraction is BYPASS vs HIT vs MISS. BYPASS without explicit `Cache-Control` directives in the response is the canonical fix.',
+    '`methodDistribution`: GET-only routes are cacheable; POST/PUT/DELETE are not. If the route is GET-heavy but BYPASSing, the cache headers are missing or wrong.',
+    '`botShare` (bandwidth by bot_category): if bots dominate uncached bandwidth, the right rec may be Bot Protection rather than route caching.',
+    '`bandwidthByCache`: pair with cacheBreakdown to confirm the dollar/bandwidth impact of moving uncached → cached.',
+    'A ready cache recommendation must name a positive cache policy. If the right answer is `no-store`, emit no recommendation / observation instead of a cache fix.',
+  ],
+  cold_start: [
+    '`startTypeSplit`: cold vs hot vs prewarmed. Fluid Compute meaningfully helps when cold > 5%.',
+    '`coldVsWarmLatencyP95`: how much SLOWER is cold than warm. If 5x+, cold starts are amplifying tail latency, not just adding fixed overhead.',
+    '`coldByDeployment`: if cold-start cluster around the newest deployment, the slowdown is a regression — check imports, init code, framework upgrade.',
+  ],
+  route_errors: [
+    '`errorStatusPattern`: distinguishes 500 (app crash) vs 502/503 (gateway/upstream timeout) vs 504 (downstream timeout).',
+    '`errorCodes`: a non-empty error_code dimension narrows to a specific failure class (e.g., FUNCTION_INVOCATION_TIMEOUT).',
+    '`errorsByDeployment`: a deployment-localized spike points to a regression.',
+  ],
+  external_api_slow: [
+    '`latency.p95` vs `latency.p99`: spreads point to flaky upstream; narrow gap points to slow-by-design.',
+    '`callersByRoute` (`origin_route` dim): which of OUR routes call this upstream — that\'s where the rec should land.',
+    '`transferBytes`: large payloads suggest caching or partial-response opportunities at our edge.',
+  ],
+  isr_overrevalidation: [
+    '`writePattern` (write_units by cache_result) — STALE writes vs HIT writes. STALE-write means the revalidate ran on every stale request.',
+    '`readPattern` (read_units by cache_result) — HIT vs MISS. Low MISS means cache fills are not the issue.',
+    'If writes / reads > 0.5, the revalidate cadence is too aggressive; lengthen `revalidate` or switch to on-demand `revalidateTag`.',
+  ],
+  cwv_poor: [
+    '`lcp`/`inp`/`cls` percentiles. p75 > Web Vitals "Good" threshold is the bar.',
+    'LCP > 2500ms → server response or critical image. INP > 200ms → long tasks / heavy JS on interaction. CLS > 0.1 → layout shift, usually images/ads/fonts.',
+  ],
+  middleware_heavy: [
+    '`topMiddlewarePaths`: paths that hit middleware most. If non-asset paths dominate, the matcher is too broad — narrow to the request shapes that actually need middleware.',
+  ],
+  platform_fluid_compute: [
+    'Cross-check the broad-pass `fnStartTypeByRoute` for cold-rate concentration. If a few routes carry most cold starts, frame the rec around those routes rather than fleet-wide.',
+  ],
+  platform_bot_protection: [
+    '`wafRuleFirings`: which managed rules are already firing (challenge/block). If `bot_filter` is already challenging but you still see significant bot bandwidth, BotID adds a verified-human signal that lets the WAF do its job.',
+  ],
+};
+
+export function buildBrief({
+  candidate,
+  candidateIndex,
+  candidateGroup,
+  files,
+  signals,
+  citations,
+  playbookId,
+  playbookBody,
+  frameworkPlaybookId,
+  frameworkPlaybookBody,
+  supportTopics = [],
+  generatedAt,
+}) {
+  const stack = signals?.stack ?? signals?.codebase?.stack ?? {};
+  const framework = stack.framework ?? 'unknown';
+  const version = stack.frameworkVersion ?? 'unknown';
+  const kind = candidate.kind;
+  const routeOrHost = candidate.route ?? candidate.hostname ?? null;
+  const interp = KIND_INTERPRETATION_HINTS[kind] ?? [];
+  const candidateRef = candidate.candidateRef ?? `${kind}:${routeOrHost ?? '<account>'}`;
+  const roots = briefRoots(signals);
+
+  const lines = [];
+  lines.push(`# Investigation brief — ${kind}${routeOrHost ? ` — ${routeOrHost}` : ''}`);
+  lines.push('');
+  lines.push('You are a Vercel-optimize investigation sub-agent. Your job is to investigate ONE evidence-backed candidate and emit ONE recommendation JSON. Stay narrow. Stay grounded. Do NOT widen the search.');
+  lines.push('');
+  lines.push(`Brief id: \`${candidateGroup}#${candidateIndex}\` · candidateRef: \`${candidateRef}\``);
+  if (generatedAt) lines.push(`Generated: ${generatedAt}`);
+  lines.push('');
+
+  lines.push('## Candidate');
+  lines.push('');
+  lines.push(`- **Kind:** \`${kind}\``);
+  lines.push(`- **Scope:** ${candidate.scope ?? 'route'}`);
+  if (routeOrHost) lines.push(`- **Target:** \`${routeOrHost}\``);
+  if (roots.repoRoot) lines.push(`- **Repo root:** \`${roots.repoRoot}\``);
+  if (roots.appRoot) lines.push(`- **App root:** \`${roots.appRoot}\``);
+  if (candidate.o11ySignal) lines.push(`- **o11y signal at gate-time:** \`${candidate.o11ySignal}\``);
+  lines.push(`- **Confidence:** ${candidate.confidence ?? 'n/a'}`);
+  lines.push(`- **Priority:** ${candidate.priority ?? 'n/a'}`);
+  if (candidate.disqualified) {
+    lines.push(`- **⚠ Disqualifier present:** ${candidate.disqualifyReason ?? 'disqualified'}`);
+  }
+  lines.push('');
+  lines.push(`**Gate question (the hypothesis you're verifying):** ${candidate.question ?? '(no question)'}`);
+  lines.push('');
+  if (Array.isArray(files) && files.length > 0) {
+    lines.push('**Files you may read (read ONLY these — open each one directly, NOT a repo-wide grep):**');
+    lines.push(`_Capped at ${NON_LAYOUT_FILE_CAP} non-layout files + up to ${LAYOUT_FILE_CAP} layouts._`);
+    // Tag route vs workspace-import — workspace files are usually where the bottleneck lives.
+    const routes = signals?.codebase?.routes ?? [];
+    const routeScores = routes.filter((r) => r.type !== 'layout').map((r) => ({
+      r,
+      score: routePathMatchScore(r.routePath, routeOrHost),
+    })).filter((x) => x.score > 0);
+    const topScore = routeScores.length > 0 ? Math.max(...routeScores.map((x) => x.score)) : 0;
+    const routeFiles = new Set(
+      routeScores.filter((x) => x.score === topScore).map((x) => x.r.file).filter(Boolean)
+    );
+    const layoutFiles = new Set(closestAncestorLayoutFiles(routeOrHost, routes));
+    const workspaceImportFiles = [];
+    for (const f of files) {
+      const tag = layoutFiles.has(f) || isLayoutPath(f)
+        ? '(layout)'
+        : routeFiles.has(f) ? '(route)' : '(workspace import)';
+      if (tag === '(workspace import)') workspaceImportFiles.push(f);
+      const repoRel = repoRelativeBriefPath(f, roots) ?? f;
+      const abs = absoluteBriefPath(f, roots);
+      const sourceSuffix = repoRel !== f ? ` (scan path: \`${f}\`)` : '';
+      const absSuffix = abs && abs !== repoRel ? ` — open \`${abs}\`` : '';
+      lines.push(`- \`${repoRel}\` ${tag}${sourceSuffix}${absSuffix}`);
+    }
+    if ([...routeFiles].length > 0 && workspaceImportFiles.length > 0) {
+      lines.push('');
+      lines.push('_The route file is often a thin shell that re-exports from a workspace package. If the route file has no awaits / heavy imports / data fetching of its own, the bottleneck almost certainly lives in one of the (workspace import) files above — read those._');
+    }
+  } else {
+    lines.push('**Files:** none mapped to this candidate. Either the gate is account-scope (platform_*) or the scanner could not resolve a route→file mapping (legitimate data gap). Work from the deep-dive evidence alone.');
+  }
+  lines.push('');
+
+  lines.push('## Stack context');
+  lines.push('');
+  lines.push(`- **Framework:** \`${framework}@${version}\``);
+  if (stack.hasAppRouter) lines.push('- **Router:** App Router');
+  if (stack.hasPagesRouter) lines.push('- **Router:** Pages Router');
+  if (stack.orm && stack.orm !== 'none') lines.push(`- **ORM:** ${stack.orm}`);
+  if (stack.isMonorepo) lines.push('- **Monorepo:** yes (watch for cross-package effects)');
+  lines.push('');
+
+  // Negative-space filter: sub-agent must not recommend toggling on something already on.
+  const projectFacts = deriveProjectFacts(signals);
+  if (projectFacts.length > 0) {
+    lines.push('## Project config (already on — do NOT recommend toggling)');
+    lines.push('');
+    lines.push('These settings are already enabled on the project. A recommendation that says "enable X" or "turn on X" for any of these is wrong and will be rejected by the verifier. Treat them as the starting state for your investigation.');
+    lines.push('');
+    for (const f of projectFacts) lines.push(`- ${f.briefLine}`);
+    lines.push('');
+  }
+
+  lines.push('## Deep-dive evidence (already collected — do NOT re-query)');
+  lines.push('');
+  const deepDive = candidate?.evidence?.deepDive ?? {};
+  const failureNotice = summarizeDeepDiveFailures(deepDive);
+  if (failureNotice) {
+    lines.push(`> ⚠ **Deep-dive partly incomplete.** ${failureNotice}`);
+    lines.push('>');
+    lines.push(`> The base evidence below is still valid — \`o11ySignal=${candidate.o11ySignal ?? '(unset)'}\` came directly from the gate's broad-pass query and is unaffected. Investigate against that signal and any deep-dive keys that DID populate. Do not conflate "missing data" with "no bottleneck": if the data didn't come back, abstain on the missing dimensions, not on the candidate as a whole.`);
+    lines.push('');
+  }
+  lines.push('Treat these as ground truth. Cite the specific paths and values verbatim in `why` and `verify`. Numeric values are rounded to 4 decimal places.');
+  lines.push('');
+  lines.push('**Units legend** — all duration/timing fields below are in **milliseconds** (`latency.*`, `ttfb.*`, `cpu.p95`, `memory.*`). All `value` fields under `startTypeSplit` / `statusDistribution` / `methodDistribution` / `cacheBreakdown` are **invocation counts**. `botShare` / `bandwidthByCache` values are **bytes**. `perDeployment.value` is **p95 latency in ms** for that deployment.');
+  lines.push('');
+  lines.push('```json');
+  lines.push(JSON.stringify(deepDive, null, 2));
+  lines.push('```');
+  lines.push('');
+  if (interp.length > 0) {
+    lines.push('**How to read the evidence for this candidate kind:**');
+    lines.push('');
+    for (const h of interp) lines.push(`- ${h}`);
+    lines.push('');
+  }
+
+  const cachePolicyHints = cachePolicyGuidance(kind, stack);
+  if (cachePolicyHints.length > 0) {
+    lines.push('## Cache-policy decision');
+    lines.push('');
+    lines.push('Pick the narrowest cache mechanism that matches the source. Do not default to `no-store`; if data is unsafe to cache, abstain or emit a no-change observation.');
+    lines.push('');
+    for (const h of cachePolicyHints) lines.push(`- ${h}`);
+    lines.push('');
+  }
+
+  lines.push(...renderSupportTopics(supportTopics));
+  if (supportTopics.length > 0) lines.push('');
+
+  lines.push('## Citation library (USE ONLY THESE)');
+  lines.push('');
+  lines.push(`You may cite ONLY these URLs and skill-rule references. They are filtered for \`${framework}@${version}\` and the candidate kind \`${kind}\`. Any other URL will be stripped by the \`unknown-citation\` sanitizer; any URL whose version range doesn't cover \`${framework}@${version}\` will be stripped by \`version-mismatch\`.`);
+  lines.push('');
+  lines.push('### URLs');
+  if (citations.urls.length === 0) {
+    lines.push('_(no URLs match this kind + version — investigate, but the rec may fail `missing-citation`; consider abstaining)_');
+  } else {
+    for (const e of citations.urls) {
+      lines.push(`- \`${e.url}\` — ${e.topic}`);
+    }
+  }
+  lines.push('');
+  lines.push('### Skill-rule references');
+  if (citations.ruleSkillRefs.length === 0) {
+    lines.push('_(none applicable)_');
+  } else {
+    for (const r of citations.ruleSkillRefs) {
+      lines.push(`- \`${r.skill}:${r.rule}\` — ${r.topic}`);
+    }
+  }
+  lines.push('');
+
+  if (playbookId && playbookBody) {
+    lines.push(`## Playbook hint (\`${playbookId}\`)`);
+    lines.push('');
+    lines.push(playbookBody.trim());
+    lines.push('');
+    lines.push('_Use the playbook to tilt phrasing and pattern priority. NEVER invent a claim because the playbook mentions a pattern — only emit it if the evidence supports it._');
+    lines.push('');
+  }
+  if (frameworkPlaybookId && frameworkPlaybookBody) {
+    lines.push(`## Framework-specific playbook (\`${frameworkPlaybookId}\`)`);
+    lines.push('');
+    lines.push(frameworkPlaybookBody.trim());
+    lines.push('');
+    lines.push(`_Framework-shaped advice for ${framework}. Same rule: evidence-grounded only._`);
+    lines.push('');
+  }
+
+  lines.push('## Two valid outcomes');
+  lines.push('');
+  lines.push('Your job is to answer the gate question above. There are exactly two valid outcomes:');
+  lines.push('');
+  lines.push('**A. Emit a recommendation** (schema below) — ONLY when you found a verifiable file:line cause that the deep-dive evidence supports.');
+  lines.push('');
+  lines.push('**B. Abstain** — when the gate\'s hypothesis does not survive contact with the source. Emit:');
+  lines.push('```json');
+  lines.push(`{"abstain": true, "candidateRef": "${candidateRef}", "reason": "<one-sentence explanation grounded in what you found vs what the gate assumed>"}`);
+  lines.push('```');
+  lines.push('Abstaining is the RIGHT call when evidence is ambiguous, when the bottleneck isn\'t in the resolved files, or when the gate\'s hypothesis was wrong (e.g. an "uncached_route" candidate where the route is mostly POST traffic and uncacheable by protocol). Abstention is preferred over a speculative rec. The orchestrator surfaces abstentions in the trust section of the final report.');
+  lines.push('');
+  lines.push('**B1. Abstain with an observation** — when you find something real while abstaining (e.g., perDeployment regression, error-rate spike, infrastructure config gap) that the customer should know about but isn\'t a perf rec in the gate\'s framing. Emit:');
+  lines.push('```json');
+  lines.push(`{
+  "abstain": true,
+  "candidateRef": "${candidateRef}",
+  "reason": "<why you abstained from a perf rec>",
+  "observation": {
+    "summary": "<one-line headline — what you noticed>",
+    "evidence": "<the deep-dive datum or file:line that backs it>",
+    "suggestedAction": "<what the customer should do next>",
+    "kind": "regression | error_storm | config_gap | upstream_dependency | other"
+  }
+}`);
+  lines.push('```');
+  lines.push('Use `observation` ONLY when the finding is grounded in specific evidence the gate already gave you. Do NOT invent observations to fill the slot. The renderer surfaces these in a separate "Observations from investigation" section.');
+  lines.push('');
+
+  lines.push('## Investigation protocol');
+  lines.push('');
+  lines.push('1. **Read ONLY the files listed under "Files you may read".** Do NOT `grep -r` the repo. If you find yourself wanting to widen the search, stop and re-read the gate question. If it doesn\'t constrain the search, abstain.');
+  lines.push('2. Read each file, then run targeted `grep` / `ast-grep` inside it to count patterns. Verify line numbers exactly.');
+  lines.push('3. Follow imports within the chain only when relevant to the gate question (one level deep max).');
+  lines.push('4. Stop after 5 files exhausted, or when you have a verified root cause.');
+  lines.push('5. Drop findings that fail mechanical verification (file missing, pattern not present, etc.).');
+  lines.push('6. **Zero-finding case:** if you read the named file(s) and find no mechanism that matches the gate question, abstain (Outcome B). Do NOT invent a rec to fill the slot.');
+  lines.push('7. **Evidence-contradicts-source case:** if the deep-dive shows a real signal (e.g. high p95) but the source looks fine (no awaits, no heavy imports, small render), the bottleneck is upstream (DB, external API, or in code not shown). Abstain with reason "evidence and source diverge."');
+  lines.push('');
+
+  lines.push('## Pre-emit self-check');
+  lines.push('');
+  lines.push('Before emitting a recommendation (Outcome A), verify ALL of:');
+  lines.push('- Every file in `affectedFiles` appears in "Files you may read" as a repo-relative path. If a line shows `(scan path: ...)`, do not use the scan path in JSON.');
+  lines.push('- `why` quotes at least one specific `file:line` AND at least one deep-dive datum (e.g. `ttfb.p95=576ms`).');
+  lines.push('- Every citation appears in the library above. No invented URLs.');
+  lines.push('- `currentBehavior` snippet appears in the actual file (not a paraphrase).');
+  lines.push('- No `$N` dollar literals in any customer-facing field.');
+  lines.push('');
+  lines.push('If ANY of these fails, fix the rec OR switch to Outcome B (abstain).');
+  lines.push('');
+
+  lines.push('## Required output (one JSON object, no prose around it)');
+  lines.push('');
+  lines.push('```json');
+  lines.push(`{
+  "what": "...",                  // 1 line, verb-first, scope-explicit. NO "$N" literals.
+  "why": "...",                   // 1-2 sentences. MUST cite ≥1 file:line AND ≥1 deep-dive datum (e.g. "ttfb.p95=576ms while cpu.p95=117ms").
+  "fix": "...",                   // step-by-step. Reference the specific files.
+  "bucket": "performance",        // "cost" | "performance" | "reliability"
+  "effort": "medium",             // "low" | "medium" | "high"
+  "affectedFiles": ["..."],       // repo-relative paths from the Files list above
+  "currentBehavior": "\`\`\`ts\\n...current snippet...\\n\`\`\`",
+  "desiredBehavior": "\`\`\`ts\\n...target snippet...\\n\`\`\`",
+  "verify": "Re-run \`vercel metrics ...\` and watch the named metric.",
+  "citations": ["<url-from-library>", "skill:rule"],
+  "candidateRef": "${candidateRef}",
+  "findingRefs": ["src/.../file.ts:42"],
+  "impactTier": "high",           // "high" | "medium" | "low"
+  "billingDimension": "function-duration"   // see references/recommendations.md schema
+}`);
+  lines.push('```');
+  lines.push('');
+
+  lines.push('## Critical rules');
+  lines.push('');
+  lines.push('Ordered by priority — top is most important.');
+  lines.push('');
+  lines.push('1. **`why` must cite a specific `file:line` AND a specific deep-dive datum.** Both. Not one or the other. This is THE quality gate — recs without both will be dropped by the verifier.');
+  lines.push(`2. **No invented citations.** Only URLs and refs from the library above. The \`unknown-citation\` sanitizer strips anything else.`);
+  lines.push(`3. **No version-mismatched features.** This project is \`${framework}@${version}\` — do not recommend APIs unavailable in that version. The version-aware library above is your filter.`);
+  lines.push(`4. **No \`$N\` dollar literals** in customer-facing fields. Use magnitude phrases ("hundreds of dollars per month at current traffic"). The \`$-strip\` sanitizer strips them, but emitting them is wasted output.`);
+  lines.push('5. **Stay within scope.** Do not investigate other routes or fleet-wide patterns; that is the orchestrator\'s job. If this candidate doesn\'t yield a finding, abstain (Outcome B above).');
+  lines.push('6. **Vercel voice.** Sharp teammate, clear, competent, no fluff. Lead with observed metrics and the user action. Avoid marketing language (`leverage`, `streamline`, `powerful`), filler adverbs (`just`, `simply`, `actually`), hedged starts (`Consider`, `You may want to`), rhetorical reframes, and arrows in prose. Do not expose internal terms like `sub-agent`, `abstention`, `passRate`, or `quality score`. Product names: `Observability Plus`, `Vercel Functions`, `fluid compute` mid-sentence, `BotID`, `AI Gateway`, `AI SDK`, `Edge Config`, `Routing Middleware`, `Web Analytics`. Explain `function invocations` and `95th percentile`; do not use `inv` or `p95` in customer output. See `references/voice.md`.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function cachePolicyGuidance(kind, stack = {}) {
+  if (!['uncached_route', 'cache_header_gap'].includes(kind)) return [];
+  const framework = stack.framework ?? 'unknown';
+  const cacheComponents = stack.cacheComponents === true;
+  const hints = [
+    'Whole public GET response: recommend `Cache-Control` / `CDN-Cache-Control` with `s-maxage` and `stale-while-revalidate`; name the TTL/freshness window and required `Vary` headers. Avoid high-cardinality `Vary` headers such as `X-Vercel-IP-Latitude` or `X-Vercel-IP-Longitude`; use coarser geography only when the product can tolerate it.',
+    'Fallback, 404, auth, preview, webhook, mutation, and per-user branches: keep them uncached or short-lived while caching only the safe success branch.',
+  ];
+  if (framework === 'next') {
+    if (cacheComponents) {
+      hints.push('Next.js with Cache Components: for reusable data inside the render path, prefer `use cache` / `use cache: remote` plus `cacheLife()` and `cacheTag()` when invalidation evidence exists.');
+    } else {
+      hints.push('Next.js data fetch path: use `fetch(..., { next: { revalidate: seconds } })` or route-level `revalidate` only when it matches the project version and route semantics. Before recommending route-level `export const revalidate`, inspect the page/layout route chain for `cookies()`, `headers()`, `draftMode()`, `connection()`, and auth helpers; if any parent layout is request-time dynamic, require `next build` or manifest proof that the route is still ISR/static, otherwise abstain.');
+    }
+  }
+  hints.push('Reusable server data where whole-response CDN caching is unsafe: recommend Runtime Cache only when the same result is reused across requests and the freshness/invalidation story is explicit.');
+  return hints;
+}
diff --git a/skills/vercel/vercel-optimize/lib/observation-safety.mjs b/skills/vercel/vercel-optimize/lib/observation-safety.mjs
new file mode 100644
index 0000000..1a628cd
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/observation-safety.mjs
@@ -0,0 +1,174 @@
+export function splitCustomerSafeObservations(observations, abstentions = [], signals = {}) {
+  const safe = [];
+  const heldBack = [];
+  for (const observation of Array.isArray(observations) ? observations : []) {
+    const unsafeReason = unsupportedObservationReason(observation, abstentions, signals);
+    if (unsafeReason) {
+      heldBack.push({
+        candidateRef: observation?.candidateRef ?? null,
+        reason: unsafeReason,
+        needsEvidence: true,
+      });
+    } else {
+      safe.push(observation);
+    }
+  }
+  return { observations: safe, heldBackObservations: heldBack };
+}
+
+function unsupportedObservationReason(observation, abstentions = [], signals = {}) {
+  if (contradictsNoChangeReason(observation, abstentions)) {
+    return 'This observation repeated an action that another investigation rejected. Re-run with a single scoped candidate before applying it.';
+  }
+  if (hasUnsupportedWafBotCategoryClaim(observation)) {
+    return 'This observation described an Observability bot category as a WAF-rule condition without supported rule evidence. Re-run with documented WAF condition evidence before applying it.';
+  }
+  if (hasUnsafeBotProtectionObservation(observation)) {
+    return 'This observation recommended Bot Protection or WAF changes without a staged safe-rollout plan and allowlist review. Promote it to a verified platform recommendation before applying it.';
+  }
+  if (hasStaleNextCacheApiObservation(observation, signals)) {
+    return 'This observation used a cache API that does not match the detected framework-version evidence. Re-run with the current Next.js cache evidence before applying it.';
+  }
+  if (hasUnsupportedFrameworkCausalClaim(observation)) {
+    return 'This observation made a framework-specific cause claim that verification could not support. Re-run with runtime logs or official framework evidence before applying it.';
+  }
+  if (hasUnsupportedStaticGenerationClaim(observation)) {
+    return 'This observation made a static-generation behavior claim that verification could not support. Re-run with route-manifest or runtime evidence before applying it.';
+  }
+  if (hasUnsupportedSourceAbsenceClaim(observation)) {
+    return 'This observation made a source-file absence claim that verification could not support. Re-run with a file-existence check or runtime logs before applying it.';
+  }
+  if (hasUnsupportedCacheLifeCdnClaim(observation)) {
+    return 'This observation depended on an unsupported cacheLife-to-CDN claim. Re-run with production header evidence before applying it.';
+  }
+  if (hasUnsupportedRuntimeRootCauseClaim(observation)) {
+    return 'This observation made a runtime root-cause claim that needs log, stack, or upstream response evidence before it can ship.';
+  }
+  if (hasImplementationGradeObservationAction(observation)) {
+    return 'This observation described an implementation change that needs the ready-to-apply recommendation evidence bar before it can ship.';
+  }
+  return null;
+}
+
+function observationText(observation) {
+  return [
+    observation?.summary,
+    observation?.evidence,
+    observation?.suggestedAction,
+  ].filter(Boolean).join(' ');
+}
+
+function evidenceText(observation) {
+  return [
+    observation?.summary,
+    observation?.evidence,
+  ].filter(Boolean).join(' ');
+}
+
+function hasUnsupportedWafBotCategoryClaim(observation) {
+  const text = observationText(observation);
+  if (!/\bWAF\b/i.test(text)) return false;
+  return /\bbot_category\s*=/i.test(text) ||
+    /\btarget(?:ing)?\s+(?:browser_impersonation|automated_browser|ecommerce|monitor)\b/i.test(text);
+}
+
+function hasUnsafeBotProtectionObservation(observation) {
+  const text = observationText(observation);
+  if (!/\b(?:Bot Protection|BotID|bot_filter|WAF|managed bot rules?)\b/i.test(text)) return false;
+  const recommendsAction = /\b(?:enable|add|create|configure|challenge|deny|block|rate-limit|target)\b/i.test(String(observation?.suggestedAction ?? ''));
+  if (!recommendsAction) return false;
+  const hasSafeRollout = /\b(?:staged|log mode|log action|dry run)\b/i.test(text);
+  const hasAllowlist = /\ballowlist|exclusions?\b/i.test(text);
+  return !(hasSafeRollout && hasAllowlist);
+}
+
+function hasStaleNextCacheApiObservation(observation, signals = {}) {
+  const text = observationText(observation);
+  if (!/\bunstable_cache\b/.test(text)) return false;
+  if (signals?.stack?.framework !== 'next') return false;
+  const major = parseInt(String(signals?.stack?.frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  return Number.isFinite(major) && major >= 16;
+}
+
+function hasImplementationGradeObservationAction(observation) {
+  const action = String(observation?.suggestedAction ?? '');
+  if (action.trim() === '') return false;
+  if (/\b(?:use cache:\s*remote|unstable_cache|Cache-Control|s-maxage|cacheLife|export const revalidate|checkBotId|BotID)\b/i.test(action)) return true;
+  return /\b(?:enable|add|wrap|apply|move|parallelize|set|create|configure|deny|challenge|block|fix|replace|refactor|rewrite|upgrade|downgrade)\b/i.test(action) ||
+    /\bcache\s+(?:the|this|that|shared|public|origin|response|route|data|lookup|fetch|helper)\b/i.test(action) ||
+    /\bturn\s+(?:on|off)\b/i.test(action) ||
+    /\bswitch\s+(?:to|from|the|this)\b/i.test(action) ||
+    /\buse\s+Promise\.all\b/i.test(action) ||
+    /\b(?:raise|lower|increase|decrease)\s+(?:the\s+)?(?:TTL|timeout|memory|CPU|cache|cache lifetime|duration)\b/i.test(action);
+}
+
+function contradictsNoChangeReason(observation, abstentions) {
+  const target = candidateTarget(observation?.candidateRef);
+  if (!target) return false;
+  const lowerObservationText = observationText(observation).toLowerCase();
+  const relevantReasons = abstentions
+    .filter((a) => candidateTarget(a?.candidateRef) === target)
+    .map((a) => String(a?.reason ?? '').toLowerCase());
+  if (relevantReasons.length === 0) return false;
+
+  if (/\bparalleliz(?:e|ing)\b/.test(lowerObservationText) &&
+      /\bgetsession\b/.test(lowerObservationText) &&
+      relevantReasons.some((reason) => /\bgetsession\b/.test(reason) && /\b(?:gates?|redirect|auth-preserving|blocked)\b/.test(reason))) {
+    return true;
+  }
+  return false;
+}
+
+function candidateTarget(ref) {
+  if (typeof ref !== 'string') return null;
+  const idx = ref.indexOf(':');
+  if (idx === -1) return null;
+  return ref.slice(idx + 1);
+}
+
+function hasUnsupportedFrameworkCausalClaim(observation) {
+  const text = observationText(observation).toLowerCase();
+  if (!text.includes('notfound') || !text.includes('use cache')) return false;
+  return (
+    /known next\.js cache components edge case/.test(text) ||
+    /next\.js\s+\d+(?:\.\d+)?[^.]{0,120}treats[^.]{0,120}dynamic api/.test(text) ||
+    /can surface as 5xx/.test(text) ||
+    /surface as 500/.test(text) ||
+    /instead of throwing inside (?:the )?cache/.test(text) ||
+    /cache boundary/.test(text)
+  );
+}
+
+function hasUnsupportedStaticGenerationClaim(observation) {
+  const text = observationText(observation).toLowerCase();
+  if (!/\bgeneratestaticparams\b/.test(text)) return false;
+  return /\b(?:returns?\s*(?:an\s+)?empty|\[\])\b[^.\n]{0,240}\b(?:every request|on[- ]demand|no params? (?:are )?prebuilt|populate generatestaticparams|served from (?:the )?cdn|hit bucket|cachebreakdown)\b/i.test(text) ||
+    /\b(?:every request|on[- ]demand|no params? (?:are )?prebuilt|populate generatestaticparams|served from (?:the )?cdn|hit bucket|cachebreakdown)\b[^.\n]{0,240}\b(?:returns?\s*(?:an\s+)?empty|\[\])\b/i.test(text) ||
+    /\bdynamic\s*=\s*['"`]error['"`]\b[^.\n]{0,240}\b(?:generatestaticparams|dynamicparams|every request|on[- ]demand)\b/i.test(text);
+}
+
+function hasUnsupportedSourceAbsenceClaim(observation) {
+  const ref = String(observation?.candidateRef ?? '');
+  if (!ref.startsWith('route_errors:')) return false;
+  const text = observationText(observation).toLowerCase();
+  return /\b(?:enoent|no\s+(?:matching|corresponding)\s+(?:mdx|file|post)|missing\s+(?:mdx|file|post)|does\s+not\s+exist|not\s+found\s+on\s+disk)\b/.test(text);
+}
+
+function hasUnsupportedCacheLifeCdnClaim(observation) {
+  return hasUnsupportedCacheLifeCdnText(observationText(observation));
+}
+
+export function hasUnsupportedCacheLifeCdnText(text) {
+  if (typeof text !== 'string' || !/\bcacheLife\b/i.test(text)) return false;
+  if (/\btoLaunch-\d+\b/i.test(text)) return true;
+  return /\bcacheLife\b[^.\n]{0,240}\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function|canonical|toLaunch-\d+)\b/i.test(text) ||
+    /\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function|canonical|toLaunch-\d+)\b[^.\n]{0,240}\bcacheLife\b/i.test(text) ||
+    /\b(?:no|never|without|missing)\s+cacheLife\b[^.\n]{0,240}\b(?:no|not|never|0%|every|per request|function)\b[^.\n]{0,120}\b(?:cache|cached|hit|runs?|invoke)/i.test(text);
+}
+
+function hasUnsupportedRuntimeRootCauseClaim(observation) {
+  const text = observationText(observation);
+  if (!/\b(?:caused by|root cause|responsible for failures|would produce)\b/i.test(text)) return false;
+  if (!/\b(?:5xx|500|error|failures?)\b/i.test(text)) return false;
+  return !/\b(?:logs?\s+(?:show|confirm|include|contain)|stack\s+(?:shows|trace|evidence)|trace\s+(?:shows|confirms)|exception\s+(?:shows|confirms)|response body\s+(?:shows|confirms)|runtime evidence)\b/i.test(evidenceText(observation));
+}
diff --git a/skills/vercel/vercel-optimize/lib/project-facts.mjs b/skills/vercel/vercel-optimize/lib/project-facts.mjs
new file mode 100644
index 0000000..279635a
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/project-facts.mjs
@@ -0,0 +1,99 @@
+// Single source for "already on" project facts. Feeds report Strengths, sub-agent brief, and verifier contradiction check.
+// contradictPhrases must lowercase exactly — verifier does case-insensitive substring match.
+
+// Stable order = byte-identical brief output. Empty result when project config didn't load — don't pretend.
+export function deriveProjectFacts(signals) {
+  const out = [];
+  const cfg = signals?.project?.defaultResourceConfig;
+  const projectErr = signals?.project?.error;
+  if (!cfg || projectErr) return out;
+
+  if (cfg.fluid === true) {
+    out.push({
+      id: 'fluid_compute',
+      strength: 'Fluid Compute is enabled (`defaultResourceConfig.fluid=true`) — instance reuse + reduced cold starts active.',
+      briefLine: 'Fluid Compute is ENABLED on this project (`defaultResourceConfig.fluid=true`). Do not recommend toggling it on.',
+      contradictPhrases: [
+        'enable fluid compute',
+        'enable fluid',
+        'turn on fluid compute',
+        'switch to fluid compute',
+        'migrate to fluid compute',
+        'opt in to fluid compute',
+      ],
+    });
+  }
+  if (cfg.elasticConcurrencyEnabled === true) {
+    out.push({
+      id: 'in_function_concurrency',
+      strength: 'In-function concurrency is enabled — multiple invocations share a single function instance, lowering active CPU costs on I/O-bound work.',
+      briefLine: 'In-function concurrency is ENABLED. Do not recommend toggling it on.',
+      contradictPhrases: [
+        'enable in-function concurrency',
+        'enable elastic concurrency',
+        'turn on in-function concurrency',
+        'enable concurrent invocations',
+      ],
+    });
+  }
+  if (cfg.functionDefaultMemoryType === 'standard') {
+    out.push({
+      id: 'memory_standard',
+      strength: 'Function memory tier: Standard (2GB) — the cost-efficient default; upgrade to Performance (4GB) only with memory, CPU-bound, or latency-sensitive route evidence.',
+      briefLine: 'Function memory tier is Standard (2GB), the cost-efficient default. Recommending an upgrade to Performance (4GB) requires memory, CPU-bound, or latency-sensitive route evidence.',
+      contradictPhrases: [],
+    });
+  } else if (cfg.functionDefaultMemoryType === 'performance') {
+    out.push({
+      id: 'memory_performance',
+      strength: 'Function memory tier: **Performance (4GB)** — verify this is intentional; Performance costs ~2x Standard. If your routes don\'t saturate Standard\'s memory headroom, downgrade.',
+      briefLine: 'Function memory tier is Performance (4GB). Do not recommend upgrading further — the next valid tier change is downgrading to Standard.',
+      contradictPhrases: [
+        'upgrade memory to performance',
+        'upgrade to performance memory',
+        'switch to performance memory',
+        'enable performance memory',
+      ],
+    });
+  }
+  if (Array.isArray(cfg.functionDefaultRegions) && cfg.functionDefaultRegions.length > 0) {
+    const r = cfg.functionDefaultRegions;
+    out.push({
+      id: 'function_regions',
+      strength: `Function regions: \`${r.join(', ')}\` (${r.length === 1 ? 'single region' : 'multi-region'}).`,
+      briefLine: `Function regions configured: ${r.join(', ')}. If your rec hinges on region placement, it must accept this configuration as the starting point.`,
+      contradictPhrases: [],
+    });
+  }
+  if (cfg.functionZeroConfigFailover === true) {
+    out.push({
+      id: 'zero_config_failover',
+      strength: 'Function failover is enabled in project config.',
+      briefLine: 'Function failover is ENABLED in project config. Do not recommend enabling it.',
+      contradictPhrases: [
+        'enable zero-config failover',
+        'enable multi-region failover',
+        'turn on zero-config failover',
+      ],
+    });
+  }
+  return out;
+}
+
+// `why` excluded — citing a fact as evidence ("fluid is on, so …") is legitimate, not contradiction.
+export function findRecContradictions(rec, facts) {
+  if (!rec || typeof rec !== 'object') return [];
+  if (!Array.isArray(facts) || facts.length === 0) return [];
+  const haystack = [
+    rec.what,
+    rec.fix,
+    rec.desiredBehavior,
+    rec.currentBehavior,
+  ]
+    .map((s) => (typeof s === 'string' ? s.toLowerCase() : ''))
+    .join('\n');
+  if (!haystack) return [];
+  return facts.filter((f) =>
+    (f.contradictPhrases ?? []).some((p) => haystack.includes(p.toLowerCase()))
+  );
+}
diff --git a/skills/vercel/vercel-optimize/lib/queries.mjs b/skills/vercel/vercel-optimize/lib/queries.mjs
new file mode 100644
index 0000000..77503b0
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/queries.mjs
@@ -0,0 +1,315 @@
+// Declarative metric-query registry. Single source for every `vercel metrics ...` call.
+//
+// CLI default --since is 1h. Mixing 1h with 14d windows silently produces incompatible rollups — every query MUST pass since: TIME_WINDOW. test/time-window.test.mjs enforces this.
+// 14d: long enough for weekly cycles, short enough to surface recent regressions before stale data dilutes them.
+
+import { normalizeSummary } from './vercel.mjs';
+
+export const TIME_WINDOW = '14d';
+
+// CLI default cardinality cap is 10 — too small for a typical app.
+const ROUTE_LIMIT = 200;
+const HOST_LIMIT = 50;
+const DIM_LIMIT = 50;
+
+// CLI emits value under `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).
+function defaultNormalize(metricId, aggregation, groupBy) {
+  return (resp) => ({ rows: normalizeSummary(resp, metricId, aggregation, groupBy) });
+}
+
+// Collapse (route × function_start_type) rows into one row per route. Observed values: "cold", "hot", "prewarmed".
+function normalizeColdStart(metricId, aggregation) {
+  return (resp) => {
+    const rows = normalizeSummary(resp, metricId, aggregation, ['route', 'function_start_type']);
+    const byRoute = new Map();
+    for (const r of rows) {
+      if (!r.route) continue;
+      const prior = byRoute.get(r.route) ?? { route: r.route, total: 0, coldCount: 0, warmCount: 0, prewarmedCount: 0 };
+      const v = r.value ?? 0;
+      prior.total += v;
+      if (r.function_start_type === 'cold') prior.coldCount += v;
+      else if (r.function_start_type === 'hot') prior.warmCount += v;
+      else if (r.function_start_type === 'prewarmed') prior.prewarmedCount += v;
+      byRoute.set(r.route, prior);
+    }
+    return {
+      rows: [...byRoute.values()].map((r) => ({
+        ...r,
+        coldPct: r.total > 0 ? r.coldCount / r.total : 0,
+      })),
+    };
+  };
+}
+
+export const QUERIES = [
+  {
+    id: 'requestsByRouteCache',
+    metricId: 'vercel.request.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'cache_result'],
+    limit: ROUTE_LIMIT,
+    description: 'Request count per route × cache_result. Source of cache hit rate; total invocations folds across cache_result.',
+  },
+  {
+    id: 'fnDurationP95ByRoute',
+    metricId: 'vercel.function_invocation.function_duration_ms',
+    aggregation: 'p95',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p95 wall-clock function duration per route. Canonical slow-route signal.',
+  },
+  {
+    id: 'requestsByRouteStatus',
+    metricId: 'vercel.request.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'http_status'],
+    limit: ROUTE_LIMIT,
+    description: 'Request count per route × http_status. Compatibility fallback for older route_errors fixtures.',
+  },
+  {
+    id: 'fnStatusByRoute',
+    metricId: 'vercel.function_invocation.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'http_status'],
+    limit: ROUTE_LIMIT,
+    description: 'Function invocation count per route × http_status. Canonical 5xx source for slow_route disqualification and route_errors.',
+  },
+  {
+    id: 'requestsByRouteMethod',
+    metricId: 'vercel.request.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'request_method'],
+    limit: ROUTE_LIMIT,
+    description: 'Request count per route × request_method. Uncached_route gate uses this to skip mostly-POST routes (Server Actions, mutations) where 0% cache is correct behavior.',
+  },
+  {
+    id: 'externalApiP75',
+    metricId: 'vercel.external_api_request.request_duration_ms',
+    aggregation: 'p75',
+    groupBy: ['origin_hostname'],
+    limit: HOST_LIMIT,
+    description: 'p75 external API duration per origin hostname.',
+  },
+
+  {
+    id: 'fnStartTypeByRoute',
+    metricId: 'vercel.function_invocation.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'function_start_type'],
+    limit: ROUTE_LIMIT,
+    description: 'Function invocation count split by cold | hot | prewarmed. Feeds cold_start gate.',
+    normalizer: normalizeColdStart('vercel.function_invocation.count', 'sum'),
+  },
+  {
+    id: 'fnGbHrByRoute',
+    metricId: 'vercel.function_invocation.function_duration_gbhr',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Billed GB-hours per route (function duration in Fluid billing).',
+  },
+  {
+    id: 'fnCpuMsByRoute',
+    metricId: 'vercel.function_invocation.function_cpu_time_ms',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Active CPU time per route. Fluid Compute bills on this; high CPU = expensive route.',
+  },
+  {
+    id: 'fnPeakMemoryByRoute',
+    metricId: 'vercel.function_invocation.peak_memory_mb',
+    aggregation: 'max',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Peak memory observed per route. Compared against provisioned to right-size.',
+  },
+  {
+    id: 'fnProvisionedMemoryByRoute',
+    metricId: 'vercel.function_invocation.provisioned_memory_mb',
+    aggregation: 'max',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Provisioned memory per route. Feeds oversized_memory gate.',
+  },
+  {
+    id: 'fnTtfbP95ByRoute',
+    metricId: 'vercel.function_invocation.ttfb_ms',
+    aggregation: 'p95',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Server-measured time-to-first-byte per route. Complements function_duration_ms p95.',
+  },
+
+  {
+    id: 'fdtByRoute',
+    metricId: 'vercel.request.fdt_total_bytes',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Fast Data Transfer bytes per route. Bandwidth cost driver.',
+  },
+  {
+    id: 'fdtByBot',
+    metricId: 'vercel.request.fdt_total_bytes',
+    aggregation: 'sum',
+    groupBy: ['bot_category'],
+    limit: DIM_LIMIT,
+    description: 'FDT bytes by bot category. Empty `bot_category` = human traffic; non-empty = bots.',
+  },
+  {
+    id: 'fdtByCache',
+    metricId: 'vercel.request.fdt_total_bytes',
+    aggregation: 'sum',
+    groupBy: ['cache_result'],
+    limit: DIM_LIMIT,
+    description: 'FDT bytes by cache_result. Uncached vs cached bandwidth.',
+  },
+
+  {
+    id: 'middlewareCount',
+    metricId: 'vercel.middleware_invocation.count',
+    aggregation: 'sum',
+    groupBy: ['request_path'],
+    limit: ROUTE_LIMIT,
+    description: 'Middleware invocations per request_path. Heavy middleware traffic = missing matcher.',
+  },
+  {
+    id: 'middlewareDurationP95',
+    metricId: 'vercel.middleware_invocation.duration_ms',
+    aggregation: 'p95',
+    groupBy: ['request_path'],
+    limit: ROUTE_LIMIT,
+    description: 'p95 middleware duration per request_path.',
+  },
+
+  {
+    id: 'isrReadsByRoute',
+    metricId: 'vercel.isr_operation.read_units',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'ISR read units per route. Healthy when high relative to writes.',
+  },
+  {
+    id: 'isrWritesByRoute',
+    metricId: 'vercel.isr_operation.write_units',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'ISR write units per route. High writes/reads = over-aggressive revalidate.',
+  },
+
+  {
+    id: 'imageCount',
+    metricId: 'vercel.image_transformation.count',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Total image transformations performed.',
+  },
+  {
+    id: 'imageByHost',
+    metricId: 'vercel.image_transformation.count',
+    aggregation: 'sum',
+    groupBy: ['source_image_hostname'],
+    limit: HOST_LIMIT,
+    description: 'Image transformations per source hostname. Identify which hosts dominate the bill.',
+  },
+  {
+    id: 'imageSourceBytes',
+    metricId: 'vercel.image_transformation.source_size_bytes',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Bytes of source images optimized. High = ingress bandwidth cost.',
+  },
+
+  {
+    id: 'cwvLcpByRoute',
+    metricId: 'vercel.speed_insights_metric.lcp',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 Largest Contentful Paint per route. > 2500ms = poor.',
+  },
+  {
+    id: 'cwvInpByRoute',
+    metricId: 'vercel.speed_insights_metric.inp',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 Interaction to Next Paint per route. > 200ms = poor.',
+  },
+  {
+    id: 'cwvClsByRoute',
+    metricId: 'vercel.speed_insights_metric.cls',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 Cumulative Layout Shift per route. > 0.1 = poor.',
+  },
+  {
+    id: 'cwvTtfbByRoute',
+    metricId: 'vercel.speed_insights_metric.ttfb_ms',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 client-measured TTFB per route.',
+  },
+  {
+    id: 'cwvCount',
+    metricId: 'vercel.speed_insights_metric.count',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Total Speed Insights measurements. Use to decide whether CWV gates have enough signal.',
+  },
+  {
+    id: 'cwvCountByRoute',
+    metricId: 'vercel.speed_insights_metric.count',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Speed Insights measurements per route. CWV route gates require at least 50 samples on the specific route.',
+  },
+
+  {
+    id: 'firewallByAction',
+    metricId: 'vercel.firewall_action.count',
+    aggregation: 'sum',
+    groupBy: ['waf_action'],
+    limit: DIM_LIMIT,
+    description: 'Firewall action count per waf_action (allow | challenge | block | log).',
+  },
+  {
+    id: 'botIdChecks',
+    metricId: 'vercel.bot_id_check.count',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Total BotID checks. > 0 confirms BotID is wired up; = 0 confirms it is not.',
+  },
+
+  {
+    id: 'externalApiCount',
+    metricId: 'vercel.external_api_request.count',
+    aggregation: 'sum',
+    groupBy: ['origin_hostname'],
+    limit: HOST_LIMIT,
+    description: 'External API call count per origin hostname.',
+  },
+  {
+    id: 'externalApiBytes',
+    metricId: 'vercel.external_api_request.transfer_bytes',
+    aggregation: 'sum',
+    groupBy: ['origin_hostname'],
+    limit: HOST_LIMIT,
+    description: 'Outbound bytes per external API hostname.',
+  },
+];
+
+export function normalizerFor(entry) {
+  if (entry.normalizer) return entry.normalizer;
+  return defaultNormalize(entry.metricId, entry.aggregation, entry.groupBy);
+}
diff --git a/skills/vercel/vercel-optimize/lib/reconcile-candidates.mjs b/skills/vercel/vercel-optimize/lib/reconcile-candidates.mjs
new file mode 100644
index 0000000..472b089
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/reconcile-candidates.mjs
@@ -0,0 +1,372 @@
+// Deterministic post-deep-dive reconciliation.
+//
+// Runs after metrics deep-dive and before investigation briefs. Its job is to
+// prevent weak candidates from consuming investigator budget when the
+// follow-up metric evidence already disproves or reframes the gate hypothesis.
+
+const SLOW_ROUTE_P95_THRESHOLD_MS = 500;
+const ERROR_RATE_DOMINATES_THRESHOLD = 0.5;
+const DEPLOYMENT_OUTLIER_MULTIPLE = 2;
+const DEPLOYMENT_OUTLIER_MIN_MS = 1000;
+const ROUTE_ERROR_CONFIRMATION_RATIO = 0.1;
+const UNCACHED_HEALTHY_HIT_RATE = 0.9;
+const UNCACHED_MIN_GET_SHARE = 0.2;
+const ISR_WRITE_FLOOR = 100;
+const ISR_WRITE_READ_RATIO_THRESHOLD = 0.5;
+
+const SCANNER_ONLY_KINDS = new Set([
+  'cache_header_gap',
+  'image_optimization',
+  'rendering_candidate',
+]);
+
+export function reconcileInvestigation(investigation, { gate = null } = {}) {
+  if (!investigation || typeof investigation !== 'object') {
+    throw new TypeError('reconcileInvestigation investigation must be an object');
+  }
+
+  const preResolvedRecords = [];
+  const reconciliation = {
+    droppedBeforeInvestigation: 0,
+    reasons: {},
+  };
+
+  const reconcilePool = (pool, group) => {
+    if (!Array.isArray(pool)) return [];
+    const kept = [];
+    for (let i = 0; i < pool.length; i++) {
+      const candidate = pool[i];
+      const decision = reconcileCandidate(candidate, { group, index: i, gate });
+      if (decision.keep) {
+        kept.push(candidate);
+        continue;
+      }
+      reconciliation.droppedBeforeInvestigation++;
+      reconciliation.reasons[decision.reasonCode] = (reconciliation.reasons[decision.reasonCode] ?? 0) + 1;
+      preResolvedRecords.push(decision.record);
+    }
+    return kept;
+  };
+
+  const priorPreResolved = Array.isArray(investigation.preResolvedRecords)
+    ? investigation.preResolvedRecords
+    : [];
+
+  return {
+    ...investigation,
+    toLaunch: reconcilePool(investigation.toLaunch, 'toLaunch'),
+    platform: reconcilePool(investigation.platform, 'platform'),
+    preResolvedRecords: [...priorPreResolved, ...preResolvedRecords],
+    reconciliation: {
+      ...(investigation.reconciliation ?? {}),
+      ...reconciliation,
+    },
+  };
+}
+
+export function reconcileCandidate(candidate, ctx = {}) {
+  if (!candidate || typeof candidate !== 'object') return { keep: true };
+
+  const scannerOnly = scannerOnlyDecision(candidate, ctx);
+  if (scannerOnly) return scannerOnly;
+
+  if (candidate.kind === 'slow_route') {
+    const errorDecision = slowRouteErrorDecision(candidate, ctx);
+    if (errorDecision) return errorDecision;
+
+    const mismatchDecision = slowRouteMetricMismatchDecision(candidate, ctx);
+    if (mismatchDecision) return mismatchDecision;
+
+    const regressionDecision = deploymentRegressionDecision(candidate, ctx);
+    if (regressionDecision) return regressionDecision;
+  }
+
+  if (candidate.kind === 'route_errors') {
+    const mismatchDecision = routeErrorsMetricMismatchDecision(candidate, ctx);
+    if (mismatchDecision) return mismatchDecision;
+  }
+
+  if (candidate.kind === 'uncached_route') {
+    const cacheDecision = uncachedRouteCacheDecision(candidate, ctx);
+    if (cacheDecision) return cacheDecision;
+    const methodDecision = uncachedRouteMethodDecision(candidate, ctx);
+    if (methodDecision) return methodDecision;
+  }
+
+  if (candidate.kind === 'isr_overrevalidation') {
+    const isrDecision = isrOverrevalidationDecision(candidate, ctx);
+    if (isrDecision) return isrDecision;
+  }
+
+  return { keep: true };
+}
+
+function scannerOnlyDecision(candidate, ctx) {
+  if (!SCANNER_ONLY_KINDS.has(candidate.kind)) return null;
+  if (candidate.o11ySignal !== 'scanner-only') return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'scanner_only_no_metric',
+    reason: 'Static scanner found a possible optimization, but no Vercel metric tied traffic or cost to this target.',
+    observation: {
+      kind: 'scanner_only_no_metric',
+      summary: `${targetLabel(candidate)} has a static scanner finding, but no route-level Vercel metric signal.`,
+      evidence: `gate signal=${candidate.o11ySignal}`,
+      suggestedAction: 'Do not ship a recommendation from this finding unless a Vercel metric shows material traffic, cost, or latency for the same target.',
+    },
+  });
+}
+
+function slowRouteMetricMismatchDecision(candidate, ctx) {
+  const p95 = numberAt(candidate, ['evidence', 'deepDive', 'latency', 'p95']);
+  if (p95 == null) return null;
+  if (p95 >= SLOW_ROUTE_P95_THRESHOLD_MS) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive p95 (${formatMs(p95)}) is below the slow-route threshold, so the broad gate did not survive follow-up verification.`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged as slow in the broad pass, but follow-up p95 is below threshold.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.latency.p95=${formatMs(p95)}`,
+      suggestedAction: 'Skip code investigation for this run. Re-check only if the broad and follow-up windows converge in a later run.',
+    },
+  });
+}
+
+function slowRouteErrorDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'statusDistribution']);
+  if (rows.length === 0) return null;
+  let total = 0;
+  let errors = 0;
+  for (const row of rows) {
+    const value = numberValue(row?.value);
+    if (value == null) continue;
+    total += value;
+    if (/^5/.test(String(row.http_status ?? ''))) errors += value;
+  }
+  if (total <= 0) return null;
+  const rate = errors / total;
+  if (rate <= ERROR_RATE_DOMINATES_THRESHOLD) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'error_storm',
+    reason: `Function-level 5xx responses dominate this route (${formatPct(rate)}), so this is a reliability finding rather than a slow-route finding.`,
+    observation: {
+      kind: 'error_storm',
+      summary: `${targetLabel(candidate)} latency is dominated by function-level 5xx responses.`,
+      evidence: `deepDive.statusDistribution: ${formatInteger(errors)} 5xx of ${formatInteger(total)} function invocations (${formatPct(rate)})`,
+      suggestedAction: 'Investigate as route_errors with runtime logs and error classification before making performance recommendations.',
+    },
+  });
+}
+
+function deploymentRegressionDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'perDeployment'])
+    .filter((row) => row && typeof row.deployment_id === 'string' && numberValue(row.value) != null)
+    .map((row) => ({ deploymentId: row.deployment_id, p95: numberValue(row.value) }))
+    .sort((a, b) => b.p95 - a.p95);
+
+  if (rows.length < 3) return null;
+  const [worst, second] = rows;
+  if (!worst || !second || worst.p95 < DEPLOYMENT_OUTLIER_MIN_MS) return null;
+  if (worst.p95 < second.p95 * DEPLOYMENT_OUTLIER_MULTIPLE) return null;
+
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'deployment_regression',
+    reason: `One deployment is a large latency outlier (${worst.deploymentId} at ${formatMs(worst.p95)}), so the next action is regression triage rather than generic code optimization.`,
+    observation: {
+      kind: 'deployment_regression',
+      summary: `${targetLabel(candidate)} p95 is concentrated in one deployment.`,
+      evidence: `${worst.deploymentId} p95=${formatMs(worst.p95)} vs next highest ${second.deploymentId} p95=${formatMs(second.p95)}`,
+      suggestedAction: 'Compare the outlier deployment against the prior deployment and inspect runtime logs before recommending a code-level performance change.',
+    },
+  });
+}
+
+function routeErrorsMetricMismatchDecision(candidate, ctx) {
+  const broadErrors = numberAt(candidate, ['evidence', 'count']) ?? parseSignalNumber(candidate.o11ySignal, 'errs');
+  if (broadErrors == null || broadErrors < 1000) return null;
+  const rows = [
+    ...arrayAt(candidate, ['evidence', 'deepDive', 'errorStatusPattern']),
+    ...arrayAt(candidate, ['evidence', 'deepDive', 'errorsByDeployment']),
+  ];
+  if (rows.length === 0) return null;
+  let confirmed5xx = 0;
+  for (const row of rows) {
+    if (!/^5\d\d$/.test(String(row?.http_status ?? ''))) continue;
+    const value = numberValue(row?.value);
+    if (value != null) confirmed5xx += value;
+  }
+  // errorStatusPattern and errorsByDeployment can both be present; avoid
+  // double-count inflation by taking the lower non-zero route-level view when available.
+  const statusRows = arrayAt(candidate, ['evidence', 'deepDive', 'errorStatusPattern']);
+  const status5xx = sumRows(statusRows, (row) => /^5\d\d$/.test(String(row?.http_status ?? '')));
+  if (status5xx > 0) confirmed5xx = status5xx;
+  if (confirmed5xx >= broadErrors * ROUTE_ERROR_CONFIRMATION_RATIO) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive 5xx volume (${formatInteger(confirmed5xx)}) does not confirm the broad route_errors gate (${formatInteger(broadErrors)}).`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged for 5xx errors, but follow-up status data did not confirm the volume.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.confirmed5xx=${formatInteger(confirmed5xx)}`,
+      suggestedAction: 'Skip code recommendations from this run. Re-run with refreshed status metrics or runtime logs if the route is still suspected.',
+    },
+  });
+}
+
+function uncachedRouteCacheDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'cacheBreakdown']);
+  if (rows.length === 0) return null;
+  const total = sumRows(rows);
+  if (total <= 0) return null;
+  const hits = sumRows(rows, (row) => ['HIT', 'STALE'].includes(String(row?.cache_result ?? '').toUpperCase()));
+  const hitRate = hits / total;
+  if (hitRate < UNCACHED_HEALTHY_HIT_RATE) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive cache hit rate (${formatPct(hitRate)}) is already healthy, so the uncached-route gate did not survive follow-up verification.`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged as low-cache, but follow-up cache data is already healthy.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.cacheHitRate=${formatPct(hitRate)}`,
+      suggestedAction: 'Skip cache recommendations for this candidate unless a later run shows sustained MISS/BYPASS traffic.',
+    },
+  });
+}
+
+function uncachedRouteMethodDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'methodDistribution']);
+  if (rows.length === 0) return null;
+  const total = sumRows(rows);
+  if (total <= 0) return null;
+  const gets = sumRows(rows, (row) => String(row?.request_method ?? '').toUpperCase() === 'GET');
+  const getShare = gets / total;
+  if (getShare >= UNCACHED_MIN_GET_SHARE) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'protocol_mismatch',
+    reason: `Deep-dive GET share (${formatPct(getShare)}) is below the cacheable-route floor, so this is not a good shared-cache candidate.`,
+    observation: {
+      kind: 'protocol_mismatch',
+      summary: `${targetLabel(candidate)} is not GET-heavy enough for a shared-cache recommendation.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.getShare=${formatPct(getShare)}`,
+      suggestedAction: 'Do not recommend CDN caching for this route from aggregate traffic alone. Investigate write-path cost only if another metric gate fires.',
+    },
+  });
+}
+
+function isrOverrevalidationDecision(candidate, ctx) {
+  const writeRows = arrayAt(candidate, ['evidence', 'deepDive', 'writePattern']);
+  const readRows = arrayAt(candidate, ['evidence', 'deepDive', 'readPattern']);
+  if (writeRows.length === 0 && readRows.length === 0) return null;
+  const writes = sumRows(writeRows);
+  const reads = sumRows(readRows);
+  const ratio = reads > 0 ? writes / reads : (writes > 0 ? Infinity : 0);
+  if (reads <= 0) {
+    return dropWithObservation(candidate, ctx, {
+      reasonCode: 'metric_mismatch',
+      reason: 'Deep-dive ISR read units were not present, so the write/read over-revalidation signal was not confirmed.',
+      observation: {
+        kind: 'metric_mismatch',
+        summary: `${targetLabel(candidate)} was flagged for ISR over-revalidation, but follow-up ISR read data was empty.`,
+        evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${formatInteger(writes)}; deepDive.isrReads=${formatInteger(reads)}`,
+        suggestedAction: 'Skip ISR recommendations for this candidate unless a later run confirms both ISR writes and reads for the same route.',
+      },
+    });
+  }
+  if (writes >= ISR_WRITE_FLOOR && ratio > ISR_WRITE_READ_RATIO_THRESHOLD) return null;
+  const ratioLabel = ratio === Infinity ? 'Infinity' : ratio.toFixed(2);
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive ISR writes per read (${ratioLabel}) no longer crosses the over-revalidation threshold.`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged for ISR over-revalidation, but follow-up ISR data did not confirm it.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${formatInteger(writes)}; deepDive.isrReads=${formatInteger(reads)}; ratio=${ratioLabel}`,
+      suggestedAction: 'Skip ISR recommendations for this candidate unless a later run shows sustained write amplification.',
+    },
+  });
+}
+
+function dropWithObservation(candidate, ctx, { reasonCode, reason, observation }) {
+  return {
+    keep: false,
+    reasonCode,
+    record: {
+      abstain: true,
+      candidateRef: candidateRefFor(candidate),
+      reason,
+      observation,
+      reconciliation: {
+        droppedBeforeInvestigation: true,
+        reasonCode,
+        group: ctx.group ?? null,
+        index: Number.isInteger(ctx.index) ? ctx.index : null,
+      },
+    },
+  };
+}
+
+export function candidateRefFor(candidate, files = candidate?.files) {
+  if (!candidate || typeof candidate !== 'object') return 'unknown:<unknown>';
+  const target = candidate.route
+    ?? candidate.hostname
+    ?? (Array.isArray(files) && files.length > 0 ? `<account>#${files[0]}` : '<account>');
+  return `${candidate.kind ?? 'unknown'}:${target}`;
+}
+
+function targetLabel(candidate) {
+  return candidate.route ?? candidate.hostname ?? candidate.files?.[0] ?? 'account-level target';
+}
+
+function arrayAt(obj, path) {
+  let cur = obj;
+  for (const p of path) cur = cur?.[p];
+  return Array.isArray(cur) ? cur : [];
+}
+
+function numberAt(obj, path) {
+  let cur = obj;
+  for (const p of path) cur = cur?.[p];
+  return numberValue(cur);
+}
+
+function numberValue(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function sumRows(rows, predicate = () => true) {
+  if (!Array.isArray(rows)) return 0;
+  let total = 0;
+  for (const row of rows) {
+    if (!predicate(row)) continue;
+    const value = numberValue(row?.value);
+    if (value != null) total += value;
+  }
+  return total;
+}
+
+function parseSignalNumber(signal, key) {
+  if (typeof signal !== 'string') return null;
+  const re = new RegExp(`(?:^|,)${key}=([\\d,.]+)`);
+  const m = signal.match(re);
+  if (!m) return null;
+  const n = Number(m[1].replace(/,/g, ''));
+  return Number.isFinite(n) ? n : null;
+}
+
+function formatMs(value) {
+  const n = numberValue(value);
+  if (n == null) return String(value);
+  return `${Math.round(n)}ms`;
+}
+
+function formatPct(value) {
+  const n = numberValue(value);
+  if (n == null) return String(value);
+  return `${(n * 100).toFixed(n >= 0.1 ? 1 : 2)}%`;
+}
+
+function formatInteger(value) {
+  const n = numberValue(value);
+  if (n == null) return String(value);
+  return Math.round(n).toLocaleString('en-US');
+}
diff --git a/skills/vercel/vercel-optimize/lib/render-report.mjs b/skills/vercel/vercel-optimize/lib/render-report.mjs
new file mode 100644
index 0000000..864fd0b
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/render-report.mjs
@@ -0,0 +1,955 @@
+// Deterministic markdown renderer. Same inputs → byte-identical output (modulo caller-supplied generatedAt).
+
+import { createHash } from 'node:crypto';
+import { computeImpactLabel } from './impact-label.mjs';
+import { deriveProjectFacts } from './project-facts.mjs';
+import { canonicalizeRoute } from './route-normalize.mjs';
+import { computeCostCoverage, renderCostCoverageMarkdown } from './cost-coverage.mjs';
+import { gates as registeredGates } from './gates/index.mjs';
+import { formatCandidateLabel, formatKind, formatPublicText, formatRoute, formatSignal } from './display-labels.mjs';
+import { splitCustomerSafeObservations } from './observation-safety.mjs';
+
+const PLATFORM_CAP = 3;
+const GATED_TARGET_PREVIEW = 5;
+
+export function renderReport({ recommendations = [], gated = [], abstentions = [], observations = [], signals = {}, candidates = [], opts = {} } = {}) {
+  const safety = splitCustomerSafeObservations(observations, abstentions, signals);
+  observations = safety.observations;
+  abstentions = [...abstentions, ...safety.heldBackObservations];
+  assertValidObservations(observations);
+
+  const projectName = opts.projectName ?? signals.project?.name ?? '<project>';
+  const stack = signals.stack ?? signals.codebase?.stack ?? {};
+  const usage = signals.usage ?? null;
+  const plan = signals.plan ?? { plan: 'unknown', reason: '(not detected)' };
+
+  // Sub-agents don't always propagate o11ySignal/aliasRoutes — look them up by candidateRef and canonicalize the displayed ref.
+  recommendations = recommendations.map((r) => enrichRecFromCandidates(r, candidates));
+  const { needsEvidenceRows, noChangeRows } = splitInvestigationOutcomes(abstentions);
+
+  const lines = [];
+  lines.push(`# Vercel Optimization Report — ${projectName}`);
+  lines.push('');
+  lines.push(renderMetadataLine(stack, plan, usage, signals));
+  const coverageLine = renderCoverageLine(candidates, recommendations, signals, {
+    abstentions,
+    heldBackCount: opts.heldBackCount,
+    noChangeCount: opts.noChangeCount,
+  });
+  if (coverageLine) lines.push(coverageLine);
+  if (opts.generatedAt) {
+    lines.push('');
+    lines.push(`_Generated ${opts.generatedAt}_`);
+  }
+  lines.push('');
+
+  lines.push(...renderCostHeader(signals));
+  lines.push('');
+  lines.push(...renderCostBreakdown(usage, signals));
+  if (usage) {
+    const coverage = computeCostCoverage(usage, registeredGates);
+    lines.push(...renderCostCoverageMarkdown(coverage));
+  }
+  lines.push('');
+
+  const platformRecs = recommendations.filter(isPlatformScope).slice(0, PLATFORM_CAP);
+  const codeRecs = recommendations.filter((r) => !isPlatformScope(r));
+  const sorted = sortRecs(codeRecs);
+  const high = sorted.filter((r) => r.impactTier === 'high');
+  const medium = sorted.filter((r) => r.impactTier === 'medium');
+  const low = sorted.filter((r) => r.impactTier === 'low' || !r.impactTier);
+  lines.push('## Highest-impact recommendations');
+  lines.push('');
+  if (sorted.length === 0) {
+    lines.push('_No recommendations are ready to apply from this run._');
+  } else {
+    const top = sorted.slice(0, 5);
+    top.forEach((rec, i) => {
+      const candidate = candidateForDisplay(rec);
+      const signal = formatSignal(rec.o11ySignal ?? signalFromRec(rec) ?? '', candidate);
+      lines.push(`${i + 1}. **${formatCandidateLabel(candidate)}** — ${signal}`);
+      lines.push(`   - **What to do**: ${formatRecommendationText(rec.what ?? '')}`);
+      lines.push(`   - **Impact**: ${formatRecommendationText(impactString(rec, signals))}`);
+      if (rec.effort) lines.push(`   - **Effort**: ${rec.effort}`);
+      const cites = asArray(rec.citations);
+      if (cites.length > 0) lines.push(`   - **Citations**: ${cites.join(', ')}`);
+    });
+  }
+  lines.push('');
+
+  lines.push('## Recommendations');
+  lines.push('');
+  lines.push('### High impact');
+  lines.push('');
+  lines.push(...renderRecTable(high, signals));
+  lines.push('');
+  lines.push('### Medium impact');
+  lines.push('');
+  lines.push(...renderRecTable(medium, signals));
+  lines.push('');
+  if (low.length > 0) {
+    lines.push('### Low impact');
+    lines.push('');
+    lines.push(...renderRecTable(low, signals));
+    lines.push('');
+  }
+
+  lines.push('## Detailed recommendations');
+  lines.push('');
+  if (sorted.length === 0) {
+    lines.push('_No recommendations are ready to apply from this run._');
+  } else {
+    for (const [i, rec] of sorted.entries()) {
+      lines.push(...renderRecDetail(rec, i + 1, { signals }));
+    }
+  }
+  lines.push('');
+
+  lines.push('## Platform recommendations');
+  lines.push('');
+  if (platformRecs.length === 0) {
+    lines.push('_(none — the gate did not surface any platform-scope recommendations)_');
+  } else {
+    for (const [i, rec] of platformRecs.entries()) {
+      lines.push(...renderRecDetail(rec, i + 1, { compact: true, signals }));
+    }
+  }
+  lines.push('');
+
+  // Observations carry actionable signal discovered during investigation.
+  if (observations.length > 0) {
+    lines.push('## Observations from investigation');
+    lines.push('');
+    lines.push('These are real signals from the audit, but they are not ready-to-apply recommendations.');
+    lines.push('');
+    lines.push('| Candidate | Observation | Evidence | Suggested action | Kind |');
+    lines.push('|---|---|---|---|---|');
+    for (const o of observations) {
+      const ref = o.candidateRef ?? '(unspecified)';
+      lines.push(`| ${escape(displayCandidateRef(ref))} | ${escape(formatEvidenceText(o.summary))} | ${escape(formatEvidenceText(o.evidence ?? '_(none recorded)_'))} | ${escape(formatEvidenceText(o.suggestedAction ?? '_(none recorded)_'))} | ${escape(formatKind(o.kind ?? 'other'))} |`);
+    }
+    lines.push('');
+  }
+
+  // Trust mechanism: customer sees what was investigated and why no rec emerged.
+  if (needsEvidenceRows.length > 0) {
+    lines.push('## Needs more evidence');
+    lines.push('');
+    lines.push('These candidates were investigated, but automated checks kept the change out of the ready-to-apply list.');
+    lines.push('');
+    lines.push('| Candidate | Why it was held back |');
+    lines.push('|---|---|');
+    for (const a of needsEvidenceRows) {
+      const ref = a.candidateRef ?? '(unspecified)';
+      const reason = publicNoRecommendationReason(a.reason ?? '(no reason recorded)');
+      lines.push(`| ${escape(displayCandidateRef(ref))} | ${escape(reason)} |`);
+    }
+    lines.push('');
+  }
+
+  if (noChangeRows.length > 0) {
+    lines.push('## Investigated, no change recommended');
+    lines.push('');
+    lines.push('These candidates were checked and did not produce a supported change.');
+    lines.push('');
+    lines.push('| Candidate | Why no recommendation shipped |');
+    lines.push('|---|---|');
+    for (const a of noChangeRows) {
+      const ref = a.candidateRef ?? '(unspecified)';
+      const reason = publicNoRecommendationReason(a.reason ?? '(no reason recorded)');
+      lines.push(`| ${escape(displayCandidateRef(ref))} | ${escape(reason)} |`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Not investigated in this run');
+  lines.push('');
+  lines.push(...renderGatedTable(gated));
+  lines.push('');
+
+  lines.push('## Strengths');
+  lines.push('');
+  lines.push(...renderStrengths(signals));
+  lines.push('');
+
+  const configNotes = renderConfigurationNotes(signals);
+  if (configNotes.length > 0) {
+    lines.push('## Configuration notes');
+    lines.push('');
+    lines.push(...configNotes);
+    lines.push('');
+  }
+
+  lines.push('## Data gaps');
+  lines.push('');
+  lines.push(...renderDataGaps(signals));
+
+  return lines.join('\n');
+}
+
+function assertValidObservations(observations) {
+  if (!Array.isArray(observations)) {
+    throw new TypeError('renderReport observations must be an array');
+  }
+  for (const [i, o] of observations.entries()) {
+    if (!o || typeof o !== 'object') {
+      throw new TypeError(`renderReport observations[${i}] must be an object`);
+    }
+    if (typeof o.summary !== 'string' || o.summary.trim() === '') {
+      throw new TypeError(`renderReport observations[${i}].summary is required`);
+    }
+  }
+}
+
+export function buildFinalReportMessage({ reportPath, markdown, recommendations = [], signals = {}, maxRecommendations = 10 } = {}) {
+  const destination = reportPath || 'report.md';
+  const coverageLine = extractCoverageLine(markdown);
+  const lines = [`Report saved: ${destination}`];
+  if (coverageLine) {
+    lines.push('');
+    lines.push(stripDetailsLink(coverageLine));
+  } else {
+    lines.push('');
+    lines.push('Open the report for details. No coverage summary was available.');
+  }
+  const readyPreview = renderFinalRecommendationPreview(recommendations, signals, maxRecommendations);
+  if (readyPreview.length > 0) {
+    lines.push('');
+    lines.push(...readyPreview);
+  }
+  const body = lines.join('\n');
+  return {
+    body,
+    lineCount: lines.length,
+    sha256: createHash('sha256').update(body).digest('hex'),
+    reportPath: destination,
+    coverageLine: coverageLine ?? null,
+    recommendationsShown: readyPreview.filter((line) => /^\d+\./.test(line)).length,
+  };
+}
+
+function renderFinalRecommendationPreview(recommendations, signals, maxRecommendations) {
+  const ready = Array.isArray(recommendations)
+    ? sortRecs(recommendations.filter((r) => r && r.abstain !== true))
+    : [];
+  if (ready.length === 0) return [];
+  const max = Math.max(1, Math.min(Number.isInteger(maxRecommendations) ? maxRecommendations : 5, 10));
+  const shown = ready.slice(0, max);
+  const lines = ['Ready recommendations:'];
+  for (const [i, rec] of shown.entries()) {
+    lines.push(`${i + 1}. ${compactFinalText(rec.what ?? displayCandidate(rec))}`);
+    const impact = impactString(rec, signals);
+    if (impact && !/^_\(no impact framing recorded\)_$/.test(impact)) {
+      lines.push(`   Impact: ${compactFinalText(impact)}`);
+    }
+  }
+  const hidden = ready.length - shown.length;
+  if (hidden > 0) {
+    lines.push(`Open the report for ${hidden} more ready recommendation${hidden === 1 ? '' : 's'} and the full evidence.`);
+  }
+  return lines;
+}
+
+function compactFinalText(value) {
+  const text = formatRecommendationText(String(value ?? ''))
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (text.length <= 220) return text;
+  return `${text.slice(0, 217).trimEnd()}...`;
+}
+
+function extractCoverageLine(markdown) {
+  if (typeof markdown !== 'string') return null;
+  return markdown
+    .split('\n')
+    .find((line) => line.startsWith('**Coverage**:')) ?? null;
+}
+
+function stripDetailsLink(line) {
+  return String(line).replace(/\s*·\s*\[details\]\(#not-investigated-in-this-run\)\s*$/, '');
+}
+
+// Hidden when no candidates exist (e.g., observability blocker — nothing to cover).
+function renderCoverageLine(candidates, recommendations, signals, opts = {}) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return null;
+  const launched = candidates.filter((c) => !c.gatedReason && !c.disqualified && c.scope !== 'account');
+  const skippedByBudget = candidates.filter(
+    (c) => typeof c.gatedReason === 'string' && c.gatedReason.startsWith('skippedByBudget')
+  );
+  const coveredByDedup = candidates.filter(
+    (c) => typeof c.gatedReason === 'string' && c.gatedReason.startsWith('coveredBy')
+  );
+  const disqualified = candidates.filter(
+    (c) => typeof c.gatedReason === 'string' && c.gatedReason === c.disqualifyReason
+  );
+  const total = launched.length + skippedByBudget.length;
+  if (total === 0) return null;
+  const parts = [];
+  parts.push(`Found **${total}** potential issue${total === 1 ? '' : 's'} to check`);
+  parts.push(`${launched.length} investigated`);
+  if (skippedByBudget.length > 0) {
+    parts.push(`${skippedByBudget.length} left for a larger run — re-run with \`--max-candidates all\` to see the rest`);
+  }
+  if (coveredByDedup.length > 0) {
+    parts.push(`${coveredByDedup.length} similar route variant${coveredByDedup.length === 1 ? '' : 's'} grouped`);
+  }
+  const recCount = (recommendations ?? []).filter((r) => !r.abstain && !isPlatformScope(r)).length;
+  parts.push(`${recCount} recommendation${recCount === 1 ? '' : 's'} ready`);
+  const rawHeldBackCount = Number.isInteger(opts.heldBackCount)
+    ? opts.heldBackCount
+    : (Array.isArray(opts.abstentions) ? opts.abstentions.filter((a) => a?.needsEvidence === true).length : 0);
+  const heldBackCount = Math.min(rawHeldBackCount, Math.max(0, launched.length - recCount));
+  if (heldBackCount > 0) {
+    parts.push(`${heldBackCount} need more evidence`);
+  }
+  const rawNoChangeCount = Number.isInteger(opts.noChangeCount)
+    ? opts.noChangeCount
+    : (Array.isArray(opts.abstentions) ? opts.abstentions.length : 0);
+  const noChangeCount = Math.min(rawNoChangeCount, Math.max(0, launched.length - recCount - heldBackCount));
+  if (noChangeCount > 0) {
+    parts.push(`${noChangeCount} investigated, no change recommended`);
+  }
+  return `**Coverage**: ${parts.join('  ·  ')} · [details](#not-investigated-in-this-run)`;
+}
+
+function renderMetadataLine(stack, plan, usage, signals = {}) {
+  const fw = `${stack.framework ?? 'unknown'}@${stack.frameworkVersion ?? '?'}`;
+  const router = stack.hasAppRouter ? 'app-router' : stack.hasPagesRouter ? 'pages-router' : null;
+  const orm = stack.orm && stack.orm !== 'none' ? stack.orm : null;
+  const stackParts = [fw, router, orm].filter(Boolean).join(' | ');
+  const period = usage?.period
+    ? `${usage.period.from ?? '?'} → ${usage.period.to ?? '?'}`
+    : '(unavailable)';
+  const oplusLabel = observabilityLabel(signals, usage);
+  // Plan-inference reason is debug detail — only surface when plan is uncertain.
+  const planLabel = plan.plan === 'uncertain'
+    ? `${plan.plan} (${plan.reason ?? 'no signal'})`
+    : (plan.plan ?? 'unknown');
+  return `**Stack**: ${stackParts}  ·  **Plan**: ${planLabel}  ·  **Period**: ${period}  ·  **Observability**: ${oplusLabel}`;
+}
+
+function observabilityLabel(signals, usage) {
+  if (signals.observabilityPlusUsable === true) {
+    return 'Observability Plus enabled — per-route metrics included';
+  }
+  if (signals.observabilityPlusUsable === false) {
+    if (usage) {
+      return 'Per-route metrics unavailable — analysis based on billing + scanner findings';
+    }
+    if (signals.usageError === 'NOT_COLLECTED_OBSERVABILITY_BLOCKED') {
+      return 'Per-route metrics unavailable — audit paused before metric-backed route ranking';
+    }
+    return 'Per-route metrics unavailable — limited analysis based on scanner findings';
+  }
+  if (signals.observabilityPlus === true) {
+    return 'Observability Plus enabled — per-route metrics included';
+  }
+  if (signals.usageError === 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK') {
+    return 'Not checked — audit paused at unsupported-framework preflight';
+  }
+  if (signals.usageError === 'NOT_COLLECTED_OBSERVABILITY_BLOCKED') {
+    return 'Per-route metrics unavailable — audit paused before metric-backed route ranking';
+  }
+  if (usage) {
+    return 'Not enabled — analysis based on billing + scanner findings';
+  }
+  if (signals.observabilityPlus === false) {
+    return 'Not enabled — limited analysis only';
+  }
+  return 'Not checked — limited analysis only';
+}
+
+function renderCostHeader(signals) {
+  const scope = signals.usageScope;
+  if (scope === 'project') {
+    return ['## Cost breakdown (this project)'];
+  }
+  if (scope === 'team' && signals.usage) {
+    return [
+      '## Cost breakdown (team-wide — `vercel usage` has no per-project filter)',
+      '',
+      '_The Vercel CLI\'s `vercel usage` reports team-wide billing without a project filter (verified May 2026). This breakdown is the whole team\'s bill for the window. Per-route metrics in the rest of this report are project-scoped via `vercel metrics`._',
+    ];
+  }
+  return ['## Cost breakdown'];
+}
+
+function renderCostBreakdown(usage, signals) {
+  const lines = [];
+  const services = Array.isArray(usage?.services) ? usage.services : null;
+  if (services && services.length > 0) {
+    const chargedRows = services.filter((s) => {
+      const cost = serviceCost(s);
+      return cost === null || costRoundsToCents(cost) > 0;
+    });
+    if (chargedRows.length > 0) {
+      return renderServiceCostRows(chargedRows, {
+        costLabel: 'Billed cost',
+        costOf: serviceCost,
+        omittedZeroRows: services.length - chargedRows.length,
+        total: usage.totals?.billedCost,
+        totalLabel: 'Total billed',
+        totalSuffix: ' _(precise observed cost; future-savings framing is magnitude, never precise)_',
+      });
+    }
+
+    const effectiveRows = services.filter((s) => costRoundsToCents(serviceEffectiveCost(s)) > 0);
+    if (effectiveRows.length > 0) {
+      lines.push('_Net billed cost is $0.00 after included credits or allotments. Showing effective usage cost so active cost drivers are still visible._');
+      lines.push('');
+      return [
+        ...lines,
+        ...renderServiceCostRows(effectiveRows, {
+          costLabel: 'Effective cost',
+          costOf: serviceEffectiveCost,
+          omittedZeroRows: services.length - effectiveRows.length,
+          total: usage.totals?.effectiveCost,
+          totalLabel: 'Total effective cost',
+          totalSuffix: ' _(usage cost before included-credit or allotment offsets)_',
+        }),
+      ];
+    }
+
+    if (chargedRows.length === 0) {
+      const scope = signals.usageScope === 'team' ? 'team-wide ' : '';
+      lines.push(`_\`vercel usage\` returned a ${scope}billing payload, but every reported service cost was $0.00 for this window._`);
+      return lines;
+    }
+  }
+
+  // Fallback to o11y-derived ranking when usage payload missing.
+  const gbHr = signals.metrics?.fnGbHrByRoute?.rows ?? [];
+  const usageGap = missingUsageSentence(signals);
+  if (gbHr.length === 0) {
+    lines.push(`_${usageGap} Without per-route function GB-hour data, this report cannot rank cost drivers._`);
+    return lines;
+  }
+  const top = groupGbHoursByCanonicalRoute(gbHr)
+    .sort((a, b) => (b.value ?? 0) - (a.value ?? 0))
+    .slice(0, 10);
+  lines.push(`_${usageGap} Ranking by \`function_duration_gbhr\` instead. These do not translate to dollars directly, but they show which routes consume billable units._`);
+  lines.push('');
+  lines.push('| Route | GB-hr (sum, 14d) |');
+  lines.push('|---|---|');
+  for (const r of top) {
+    lines.push(`| ${escape(r.route ?? '(unnamed)')} | ${(r.value ?? 0).toFixed(4)} |`);
+  }
+  return lines;
+}
+
+function renderServiceCostRows(services, { costLabel, costOf, omittedZeroRows = 0, total = null, totalLabel, totalSuffix = '' }) {
+  const lines = [];
+  const rows = services.slice().sort((a, b) => (costOf(b) ?? 0) - (costOf(a) ?? 0));
+  // Drop Usage column when every cell is "(unspecified)" — happens when CLI emits pricingUnit=USD.
+  const usageCells = rows.map((s) => formatUsage(s));
+  const hasRealUsage = usageCells.some((c) => c !== '(unspecified)');
+  if (hasRealUsage) {
+    lines.push(`| Service | Usage | ${costLabel} |`);
+    lines.push('|---|---|---|');
+    for (let i = 0; i < rows.length; i++) {
+      const s = rows[i];
+      const costValue = costOf(s);
+      const cost = typeof costValue === 'number' ? `$${costValue.toFixed(2)}` : '(n/a)';
+      lines.push(`| ${escape(s.name ?? '(unnamed)')} | ${escape(usageCells[i])} | ${cost} |`);
+    }
+  } else {
+    lines.push(`| Service | ${costLabel} |`);
+    lines.push('|---|---|');
+    for (const s of rows) {
+      const costValue = costOf(s);
+      const cost = typeof costValue === 'number' ? `$${costValue.toFixed(2)}` : '(n/a)';
+      lines.push(`| ${escape(s.name ?? '(unnamed)')} | ${cost} |`);
+    }
+  }
+  if (omittedZeroRows > 0) {
+    lines.push('');
+    lines.push(`_${omittedZeroRows} zero-cost service ${omittedZeroRows === 1 ? 'row was' : 'rows were'} omitted._`);
+  }
+  if (typeof total === 'number') {
+    lines.push('');
+    lines.push(`**${totalLabel}: $${total.toFixed(2)}**${totalSuffix}`);
+  }
+  return lines;
+}
+
+function serviceCost(service) {
+  if (typeof service?.billedCost === 'number') return service.billedCost;
+  if (typeof service?.cost === 'number') return service.cost;
+  return null;
+}
+
+function serviceEffectiveCost(service) {
+  if (typeof service?.effectiveCost === 'number') return service.effectiveCost;
+  if (typeof service?.pricingQuantity === 'number' && service?.pricingUnit === 'USD') return service.pricingQuantity;
+  return 0;
+}
+
+function costRoundsToCents(cost) {
+  if (typeof cost !== 'number' || !Number.isFinite(cost)) return 0;
+  return Math.round(cost * 100) / 100;
+}
+
+function renderRecTable(recs, signals = {}) {
+  if (recs.length === 0) return ['_(none)_'];
+  const lines = [];
+  lines.push('| # | Bucket | What | Impact | Effort | Citations |');
+  lines.push('|---|---|---|---|---|---|');
+  recs.forEach((r, i) => {
+    const cites = asArray(r.citations).slice(0, 2).join('<br>');
+    lines.push(`| ${i + 1} | ${r.bucket ?? '?'} | ${escape(formatRecommendationText(r.what ?? ''))} | ${escape(formatRecommendationText(impactString(r, signals)))} | ${r.effort ?? '?'} | ${cites} |`);
+  });
+  return lines;
+}
+
+function renderRecDetail(rec, index, { compact = false, signals = {} } = {}) {
+  const lines = [];
+  lines.push(`### ${index}. ${formatRecommendationText(rec.what ?? '(no `what`)')}`);
+  lines.push('');
+  const meta = [
+    rec.bucket ? `**${rec.bucket}**` : null,
+    rec.effort ? `effort: ${rec.effort}` : null,
+    rec.impactTier ? `impact tier: ${rec.impactTier}` : null,
+    rec.candidateRef ? `candidate: ${displayCandidate(rec)}` : null,
+    rec.corroborationCount > 1 ? `corroborated: ${rec.corroborationCount}` : null,
+  ].filter(Boolean);
+  if (meta.length > 0) lines.push(`_${meta.join(' · ')}_`);
+  lines.push('');
+  const appliesAlsoTo = asArray(rec.appliesAlsoTo);
+  if (appliesAlsoTo.length > 0) {
+    const refs = appliesAlsoTo
+      .map((a) => a?.candidateRef)
+      .filter(Boolean)
+      .slice(0, 4);
+    if (refs.length > 0) {
+      const suffix = appliesAlsoTo.length > refs.length ? `, +${appliesAlsoTo.length - refs.length} more` : '';
+      lines.push(`_Also applies to: ${refs.map(displayCandidateRef).join(', ')}${suffix}._`);
+      lines.push('');
+    }
+  }
+  if (rec.why) {
+    lines.push('**Why**');
+    lines.push('');
+    lines.push(formatRecommendationText(rec.why));
+    lines.push('');
+  }
+  lines.push('**Impact**');
+  lines.push('');
+  lines.push(formatRecommendationText(impactString(rec, signals)));
+  lines.push('');
+  if (!compact && rec.fix) {
+    lines.push('**Fix**');
+    lines.push('');
+    lines.push(rec.fix);
+    lines.push('');
+  }
+  if (!compact && rec.currentBehavior) {
+    lines.push('**Before**');
+    lines.push('');
+    lines.push(rec.currentBehavior);
+    lines.push('');
+  }
+  if (!compact && rec.desiredBehavior) {
+    lines.push('**After**');
+    lines.push('');
+    lines.push(rec.desiredBehavior);
+    lines.push('');
+  }
+  if (rec.verify) {
+    lines.push('**Verify**');
+    lines.push('');
+    lines.push(formatRecommendationText(rec.verify));
+    lines.push('');
+  }
+  const cites = asArray(rec.citations);
+  if (cites.length > 0) {
+    lines.push('**Citations**');
+    lines.push('');
+    for (const c of cites) lines.push(`- \`${c}\``);
+    lines.push('');
+  }
+  lines.push('');
+  return lines;
+}
+
+function renderGatedTable(gated) {
+  if (!Array.isArray(gated) || gated.length === 0) {
+    return ['_(no candidates were held back)_'];
+  }
+  const groups = groupGatedCandidates(gated);
+  const lines = [];
+  lines.push('| Candidate type | Why not investigated | Targets | Count |');
+  lines.push('|---|---|---|---:|');
+  for (const group of groups) {
+    lines.push(`| ${escape(group.kind)} | ${escape(group.reason)} | ${formatGatedTargets(group.targets, group.count)} | ${group.count} |`);
+  }
+  return lines;
+}
+
+function formatGatedTargets(targets, count) {
+  const unique = [...new Set(targets.map((t) => String(t)))];
+  const shown = unique.slice(0, GATED_TARGET_PREVIEW).map((target) => escape(target));
+  const hidden = Math.max(0, count - shown.length);
+  if (hidden > 0) shown.push(`+${hidden} more`);
+  return shown.join('<br>');
+}
+
+function groupGatedCandidates(gated) {
+  const byKey = new Map();
+  for (const g of gated) {
+    const kind = formatKind(g.kind ?? '?');
+    const reason = publicGatedReason(g.gatedReason ?? g.disqualifyReason ?? '(no reason recorded)');
+    const target = formatRoute(g);
+    const key = `${kind}\u0000${reason}`;
+    const existing = byKey.get(key);
+    if (existing) {
+      existing.count += 1;
+      existing.targets.push(String(target));
+    } else {
+      byKey.set(key, { kind: String(kind), reason: String(reason), targets: [String(target)], count: 1 });
+    }
+  }
+  return Array.from(byKey.values());
+}
+
+function publicNoRecommendationReason(reason) {
+  return formatEvidenceText(String(reason))
+    .replace(/\bDropped at render:\s*/gi, '')
+    .replace(/\bverifier flagged for regen, but no regen happened\b/gi, 'needs stronger evidence before it is safe to apply')
+    .replace(/\bRe-run with a refreshed brief\.?/gi, 'Re-run the investigation after refreshing the evidence.')
+    .replace(/\bregen\b/gi, 're-check')
+    .replace(/\bverifier\b/gi, 'verification')
+    .replace(/\brec\b/gi, 'recommendation')
+    .replace(/\bsub[- ]agent\b/gi, 'investigation')
+    .replace(/\babstentions?\b/gi, 'no-change findings')
+    .replace(/\babstaining\b/gi, 'not recommending a change')
+    .replace(/\babstain(?:ed)?\b/gi, 'found no supported change')
+    .replace(/\bquality\s*\+\s*verification\b/gi, 'verification')
+    .replace(/\bquality\b/gi, 'review')
+    .replace(/\bsanitizers?\b/gi, 'checks');
+}
+
+function splitInvestigationOutcomes(abstentions) {
+  const rows = Array.isArray(abstentions) ? abstentions : [];
+  return {
+    needsEvidenceRows: rows.filter((a) => a?.needsEvidence === true),
+    noChangeRows: rows.filter((a) => a?.needsEvidence !== true),
+  };
+}
+
+function publicGatedReason(reason) {
+  return formatPublicText(String(reason))
+    .replace(/\bhardGated:\s*/gi, '')
+    .replace(/skippedByBudget\s*\(max-candidates=([^);]+)(?:;[^)]*)?\)/i, 'left for a larger run (max candidates: $1)')
+    .replace(/skippedByBudget\b/gi, 'left for a larger run')
+    .replace(/\s*;\s*raise with --max-candidates N or =all/gi, '')
+    .replace(/=all/g, 'all')
+    .replace(/\bcoveredBy\b/gi, 'covered by a higher-priority candidate')
+    .replace(/\bdisqualified\b/gi, 'not eligible');
+}
+
+function formatEvidenceText(value) {
+  const expanded = formatPublicText(value)
+    .replace(/\bdeepDive\b/gi, 'follow-up metric')
+    .replace(/\bdeep-dive\b/gi, 'follow-up metric')
+    .replace(/\blatency p95\b/gi, '95th percentile latency')
+    .replace(/\bttfb p95\b/gi, '95th percentile TTFB')
+    .replace(/\bcpu p95\b/gi, '95th percentile CPU time')
+    .replace(/\bp95\b/gi, '95th percentile')
+    .replace(/\bgate signal\b/gi, 'broad metric signal')
+    .replace(/\bo11ySignal\b/gi, 'observed signal')
+    .replace(/\bperDeployment\b/gi, 'per-deployment')
+    .replace(/\bstartTypeSplit\b/gi, 'start-type breakdown')
+    .replace(/\bstatusDistribution\b/gi, 'status distribution')
+    .replace(/\bcacheBreakdown\b/gi, 'cache breakdown')
+    .replace(/\bfunctionRoutes\b/gi, 'function routes')
+    .replace(/\bfnGbHrByRoute\b/gi, 'function duration by route');
+  return formatPublicText(expanded);
+}
+
+function formatRecommendationText(value) {
+  return formatEvidenceText(value)
+    .replace(/\bthe gate fires\b/gi, 'this audit flags the signal')
+    .replace(/\bships immediately\b/gi, 'can ship sooner');
+}
+
+function displayCandidate(value) {
+  return formatCandidateLabel(candidateForDisplay(value));
+}
+
+function candidateForDisplay(value) {
+  const parsed = parseCandidateRef(value?.candidateRef);
+  return parsed
+    ? displayCandidateObject(value, parsed)
+    : value;
+}
+
+function displayCandidateRef(ref) {
+  const parsed = parseCandidateRef(ref);
+  if (!parsed) return String(ref ?? '(unspecified)');
+  return formatCandidateLabel(displayCandidateObject({}, parsed));
+}
+
+function parseCandidateRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const [kind, ...rest] = ref.split(':');
+  const target = rest.join(':');
+  if (!kind || !target) return null;
+  return { kind, target };
+}
+
+function displayCandidateObject(base, parsed) {
+  if (parsed.target.startsWith('<account>#')) {
+    return { ...base, kind: parsed.kind, files: [parsed.target.slice('<account>#'.length)] };
+  }
+  if (parsed.target === '<account>') {
+    return { ...base, kind: parsed.kind };
+  }
+  return { ...base, kind: parsed.kind, route: parsed.target };
+}
+
+function groupGbHoursByCanonicalRoute(rows) {
+  const byRoute = new Map();
+  for (const row of rows) {
+    const route = row?.route ? canonicalizeRoute(row.route) : '(unnamed)';
+    byRoute.set(route, (byRoute.get(route) ?? 0) + (row?.value ?? 0));
+  }
+  return [...byRoute.entries()].map(([route, value]) => ({ route, value }));
+}
+
+function renderStrengths(signals) {
+  const lines = [];
+
+  // Stops agent from emitting "verify Fluid is on" recs. Source: defaultResourceConfig from project API.
+  const projectFacts = deriveProjectFacts(signals);
+  for (const f of projectFacts) {
+    if (String(f.id ?? '').startsWith('memory_')) continue;
+    lines.push(`- ${f.strength}`);
+  }
+
+  const cache = signals.metrics?.fdtByCache?.rows ?? [];
+  const hit = cache.find((r) => r.cache_result === 'HIT' || r.cache_result === 'STALE');
+  const miss = cache.find((r) => r.cache_result === 'MISS' || r.cache_result === 'BYPASS');
+  if (hit && miss && (hit.value ?? 0) > (miss.value ?? 0)) {
+    lines.push(`- Cache hit-rate is healthy at the bandwidth tier — HIT/STALE bandwidth (${formatBytes(hit.value)}) exceeds MISS/BYPASS (${formatBytes(miss.value)}).`);
+  }
+  const cold = signals.metrics?.fnStartTypeByRoute?.rows ?? [];
+  const totalInv = cold.reduce((s, r) => s + (r.total ?? 0), 0);
+  const totalCold = cold.reduce((s, r) => s + (r.coldCount ?? 0), 0);
+  if (totalInv > 1000) {
+    const coldPct = totalCold / totalInv;
+    if (coldPct < 0.02) lines.push(`- Cold-start rate is very low (${(coldPct * 100).toFixed(2)}%) — Fluid Compute or warm-instance reuse is doing its job.`);
+  }
+  const errors = signals.metrics?.requestsByRouteStatus?.rows ?? [];
+  const total5xx = errors.filter((r) => /^5/.test(r.http_status ?? '')).reduce((s, r) => s + (r.value ?? 0), 0);
+  const totalReq = errors.reduce((s, r) => s + (r.value ?? 0), 0);
+  if (totalReq > 1000) {
+    const rate = total5xx / totalReq;
+    if (rate < 0.001) lines.push(`- 5xx rate is very low (${(rate * 100).toFixed(3)}%) on ${formatNum(totalReq)} requests.`);
+  }
+  if (lines.length === 0) lines.push('_(no headline strengths to call out — see the gated table for signals we considered)_');
+  return lines;
+}
+
+function renderConfigurationNotes(signals) {
+  const projectFacts = deriveProjectFacts(signals);
+  return projectFacts
+    .filter((f) => String(f.id ?? '').startsWith('memory_'))
+    .map((f) => `- ${f.strength}`);
+}
+
+function renderDataGaps(signals) {
+  const lines = [];
+  const observabilityGap = observabilityDataGap(signals);
+  if (observabilityGap) lines.push(observabilityGap);
+  if (!signals.usage) lines.push(`- ${missingUsageSentence(signals)}`);
+  const cwvMetric = metricState(signals, 'cwvCount');
+  if (cwvMetric.failed) {
+    lines.push(`- Speed Insights metrics were not usable (\`${cwvMetric.code}\`), so LCP/INP/CLS analysis was skipped.`);
+  } else if (cwvMetric.collected) {
+    const cwv = cwvMetric.rows?.[0]?.value ?? 0;
+    if (cwv === 0) lines.push('- No Speed Insights measurements — Core Web Vitals analysis dormant. Wire up Speed Insights to enable LCP/INP/CLS recommendations.');
+  }
+  const isrMetric = metricState(signals, 'isrReadsByRoute');
+  if (isrMetric.collected) {
+    const isrR = isrMetric.rows ?? [];
+    if (isrR.length === 0) lines.push('- No ISR activity observed — either the project does not use ISR or no eligible routes had traffic in the window.');
+  }
+  const imageMetric = metricState(signals, 'imageCount');
+  if (imageMetric.collected) {
+    const images = imageMetric.rows?.[0]?.value ?? 0;
+    if (images === 0) lines.push('- No image transformations observed — either `next/image` is not used or no images served in the window.');
+  }
+  const middlewareMetric = metricState(signals, 'middlewareCount');
+  if (middlewareMetric.collected) {
+    const middleware = middlewareMetric.rows ?? [];
+    if (middleware.length === 0) lines.push('- No middleware invocations — either no `middleware.ts` is shipped or its matcher excludes all observed traffic.');
+  }
+  if (lines.length === 0) lines.push('_(no relevant gaps — every signal had data)_');
+  return lines;
+}
+
+function observabilityDataGap(signals = {}) {
+  if (signals.usageError === 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK') {
+    return '- Observability Plus was not checked because the audit paused at the unsupported-framework preflight.';
+  }
+  if (signals.observabilityPlusUsable === false) {
+    const blocker = signals.observabilityPlusBlocker;
+    if (blocker === 'project_disabled') {
+      return '- Per-route metrics unavailable — Observability Plus is disabled for this project.';
+    }
+    if (blocker === 'forbidden' || blocker === 'project_not_found') {
+      return '- Per-route metrics unavailable — the authenticated Vercel scope cannot read this project.';
+    }
+    if (blocker === 'not_linked') {
+      return '- Per-route metrics unavailable — the app directory is not linked to the Vercel project.';
+    }
+    if (blocker === 'no_oplus_probe') {
+      return '- Per-route metrics unavailable — Observability Plus was not detected for this scope.';
+    }
+    if (blocker === 'payment_required') {
+      return '- Per-route metrics unavailable — Observability Plus metrics were not usable for this scope.';
+    }
+    if (blocker === 'daily_quota_exceeded') {
+      return '- Per-route metrics unavailable — the Observability Plus query quota is exhausted for today.';
+    }
+    if (blocker === 'no_traffic') {
+      return '- Per-route metrics sparse — no route-level traffic was returned in the metrics window.';
+    }
+    if (blocker === 'all_failed_other') {
+      return '- Per-route metrics unavailable — all Observability Plus metric queries failed.';
+    }
+    if (blocker) {
+      return `- Per-route metrics unavailable — Observability Plus metrics returned \`${blocker}\`.`;
+    }
+    return '- Per-route metrics unavailable — Observability Plus data was not usable for this run.';
+  }
+  if (signals.observabilityPlus === false) {
+    return '- Observability Plus not enabled — per-route latency / cache-hit / cold-start metrics unavailable.';
+  }
+  return null;
+}
+
+function missingUsageSentence(signals = {}) {
+  const code = signals.usageError;
+  if (code === 'NOT_COLLECTED_OBSERVABILITY_BLOCKED') {
+    return '`vercel usage` was not collected because the audit paused before billing collection on the Observability Plus blocker.';
+  }
+  if (code === 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK') {
+    return '`vercel usage` was not collected because the audit paused at the unsupported-framework preflight.';
+  }
+  if (code === 'USAGE_CONTEXT_MISMATCH') {
+    return '`vercel usage` returned data for a different team context, so the billing breakdown was not used.';
+  }
+  if (code === 'USAGE_UNAVAILABLE') {
+    return '`vercel usage` returned `USAGE_UNAVAILABLE`; no billing breakdown was available from the Vercel CLI.';
+  }
+  if (typeof code === 'string' && code.trim() !== '') {
+    return `\`vercel usage\` returned \`${code}\`; no billing breakdown was available from the Vercel CLI.`;
+  }
+  return '`vercel usage` did not return a billing payload.';
+}
+
+function metricState(signals, id) {
+  const metrics = signals.metrics ?? {};
+  if (!Object.prototype.hasOwnProperty.call(metrics, id)) {
+    return { collected: false, failed: false, rows: null, code: null };
+  }
+  const metric = metrics[id] ?? {};
+  const failed = metric.ok === false;
+  return {
+    collected: !failed,
+    failed,
+    rows: Array.isArray(metric.rows) ? metric.rows : [],
+    code: metric.code ?? 'UNKNOWN',
+  };
+}
+
+function sortRecs(recs) {
+  return recs.slice().sort((a, b) => priorityScore(b) - priorityScore(a));
+}
+
+function priorityScore(rec) {
+  return typeof rec.priority === 'number' ? rec.priority : tierScore(rec.impactTier);
+}
+function tierScore(t) { return ({ high: 100, medium: 50, low: 10 })[t] ?? 0; }
+
+function isPlatformScope(rec) {
+  const k = String(rec.candidateRef ?? '').split(':')[0];
+  return k.startsWith('platform_') || rec.scope === 'account';
+}
+
+function impactString(rec, signals = {}) {
+  const label = computeImpactLabel(rec, signals);
+  if (label) return label;
+  return '_(no impact framing recorded)_';
+}
+
+function signalFromRec(rec) {
+  return rec.findingRefs?.[0] ?? null;
+}
+
+function formatUsage(s) {
+  if (typeof s.usage === 'string') return s.usage;
+  if (typeof s.usage === 'number') return formatNum(s.usage) + (s.unit ? ` ${s.unit}` : '');
+  return '(unspecified)';
+}
+
+function formatNum(n) {
+  if (!Number.isFinite(n)) return String(n);
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + 'M';
+  if (n >= 1_000) return (n / 1_000).toFixed(2) + 'K';
+  return String(n);
+}
+
+function formatBytes(b) {
+  if (!Number.isFinite(b)) return '(n/a)';
+  if (b >= 1e12) return (b / 1e12).toFixed(2) + ' TB';
+  if (b >= 1e9) return (b / 1e9).toFixed(2) + ' GB';
+  if (b >= 1e6) return (b / 1e6).toFixed(2) + ' MB';
+  if (b >= 1e3) return (b / 1e3).toFixed(2) + ' KB';
+  return Math.round(b) + ' B';
+}
+
+function escape(s) {
+  if (typeof s !== 'string') return String(s ?? '');
+  return s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+function asArray(v) { return Array.isArray(v) ? v : []; }
+
+function enrichRecFromCandidates(rec, candidates) {
+  if (!rec || typeof rec !== 'object') return rec;
+  if (!Array.isArray(candidates) || candidates.length === 0) return rec;
+  const ref = rec.candidateRef ?? null;
+  // Match on raw OR canonical kind:route so pre-dedup-canonicalization refs still resolve.
+  let match = null;
+  if (ref) {
+    const [kind, route] = String(ref).split(':');
+    const canonical = route ? canonicalizeRoute(route) : null;
+    match = candidates.find((c) => {
+      if (!c || c.kind !== kind) return false;
+      const cRoute = c.route ?? c.hostname ?? '<account>';
+      return cRoute === route || cRoute === canonical || canonicalizeRoute(cRoute) === canonical;
+    });
+  }
+  const canonicalRef = ref ? canonicalRefOf(ref) : ref;
+  const merged = { ...rec, candidateRef: canonicalRef };
+  if (match) {
+    if (!merged.o11ySignal && match.o11ySignal) merged.o11ySignal = match.o11ySignal;
+    if (!merged.displayRoute && match.displayRoute) merged.displayRoute = match.displayRoute;
+    if (!merged.aliasRoutes && Array.isArray(match.aliasRoutes) && match.aliasRoutes.length > 0) {
+      merged.aliasRoutes = match.aliasRoutes;
+    }
+    if (!merged.mergedCount && typeof match.mergedCount === 'number') {
+      merged.mergedCount = match.mergedCount;
+    }
+  }
+  return merged;
+}
+
+function canonicalRefOf(ref) {
+  const [kind, ...rest] = String(ref).split(':');
+  const route = rest.join(':');
+  if (!route) return ref;
+  return `${kind}:${canonicalizeRoute(route)}`;
+}
diff --git a/skills/vercel/vercel-optimize/lib/repo-root.mjs b/skills/vercel/vercel-optimize/lib/repo-root.mjs
new file mode 100644
index 0000000..696f9cb
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/repo-root.mjs
@@ -0,0 +1,86 @@
+// Auto-detect repo-root for claim verification. Priority: Vercel API rootDirectory > --repo-root > walk-up.
+// In a monorepo the sub-agent emits paths like `apps/<app>/src/...` and the verifier needs the prefix root, not the app dir.
+
+import { access } from 'node:fs/promises';
+import { join, dirname, resolve, normalize } from 'node:path';
+
+// Prefer affectedFiles[0] over findingRefs — findingRefs often share the same file.
+export function pickProbeFile(recs) {
+  for (const r of (recs ?? [])) {
+    if (r?.abstain) continue;
+    const af = Array.isArray(r?.affectedFiles) ? r.affectedFiles[0] : null;
+    if (typeof af === 'string' && af.length > 0) return af;
+    const ref = Array.isArray(r?.findingRefs) ? r.findingRefs[0] : null;
+    if (typeof ref === 'string' && ref.length > 0) {
+      const m = ref.match(/^(.+?):\d+$/);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+export async function fileResolvesAt(root, file) {
+  try {
+    await access(join(root, file));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function detectRepoRoot(probeFile, startDir, maxDepth = 10) {
+  let dir = resolve(startDir);
+  for (let depth = 0; depth < maxDepth; depth++) {
+    if (await fileResolvesAt(dir, probeFile)) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+// rootDirectory "apps/fixture-site" + cwd .../monorepo/apps/fixture-site → repo root .../monorepo.
+export function deriveRootFromSignals(signals, cwd = process.cwd()) {
+  const dir = signals?.project?.rootDirectory;
+  if (!dir || typeof dir !== 'string') return null;
+  const offset = normalize(dir).replace(/^\.\/?/, '').replace(/\/$/, '');
+  if (!offset) return null;
+  const cwdAbs = resolve(cwd);
+  // Match `<root>/<offset>` OR `<root>/<offset>/<more>` — orchestrator may run from a subdir.
+  const parts = cwdAbs.split('/');
+  const offsetParts = offset.split('/');
+  for (let start = parts.length - offsetParts.length; start >= 0; start--) {
+    const slice = parts.slice(start, start + offsetParts.length).join('/');
+    if (slice === offset) {
+      const root = parts.slice(0, start).join('/');
+      return root || '/';
+    }
+  }
+  return null;
+}
+
+export async function resolveRepoRoot(recs, suppliedRoot, cwd = process.cwd(), signals = null) {
+  if (signals) {
+    const apiRoot = deriveRootFromSignals(signals, cwd);
+    if (apiRoot) {
+      return { root: apiRoot, source: 'api', probe: null, apiOffset: signals?.project?.rootDirectory ?? null };
+    }
+  }
+
+  const probe = pickProbeFile(recs);
+  if (!probe) {
+    return { root: suppliedRoot ?? '.', source: suppliedRoot ? 'supplied' : 'default', probe: null };
+  }
+  if (suppliedRoot && await fileResolvesAt(suppliedRoot, probe)) {
+    return { root: suppliedRoot, source: 'supplied', probe };
+  }
+  const detected = await detectRepoRoot(probe, suppliedRoot ?? cwd);
+  if (detected) {
+    return {
+      root: detected,
+      source: suppliedRoot ? 'corrected' : 'auto-detected',
+      probe,
+    };
+  }
+  return { root: suppliedRoot ?? '.', source: suppliedRoot ? 'supplied' : 'default', probe };
+}
diff --git a/skills/vercel/vercel-optimize/lib/route-normalize.mjs b/skills/vercel/vercel-optimize/lib/route-normalize.mjs
new file mode 100644
index 0000000..2116252
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/route-normalize.mjs
@@ -0,0 +1,220 @@
+// Canonicalize Next.js 16 segment-tree metric route paths so gate dedup doesn't burn budget on N copies of the same source file.
+//
+// Next.js folds flag state into base64 prefix, dynamic placeholders into `$d$X`, route groups into `!K..p`, cache-lifecycle leaves into `__PAGE__.segment` / `_tree.segment` / `_index.segment`. ~4-10x dupes per page without canonicalization.
+//
+// This module is the ONLY place we touch Next.js metric path encoding — every gate calls canonicalizeRoute before aggregating.
+
+export const ROUTE_SHAPE_RE = /(?:^.{200,}$)|[\s'"`,;&=<>(){}!\\^|\u0000-\u001F]|%(?:22|5B|5C|7B|7D|20|3C|3E|26)|localhost:|https?:\/|\/\/(?!$)|[:,\$\s]$|\.segments?\/|__PAGE__|@[a-z]/i;
+
+export function isSegmentTreePath(route) {
+  if (typeof route !== 'string') return false;
+  return /\.segments(\/|$)/.test(route);
+}
+
+export function canonicalizeRoute(route) {
+  if (typeof route !== 'string' || route.length === 0) return route;
+  if (!isSegmentTreePath(route)) return stripRouteGroups(replaceBase64WithDynamic(route));
+
+  // Discard prefix (flag-state + dynamic value, both noise). Tail is the segment-tree node.
+  const idx = route.indexOf('.segments');
+  if (idx < 0) return route;
+  const segmentTail = route.slice(idx + '.segments'.length).replace(/^\//, '');
+
+  // _tree.segment / _index.segment have no per-segment tail — fall back to static head of prefix.
+  if (segmentTail === '_tree.segment' || segmentTail === '_index.segment') {
+    return canonicalizeBranchPrefix(route, idx);
+  }
+
+  const parts = segmentTail.split('/').filter((p) => p && !isMetricLeaf(p));
+  if (parts.length === 0) return canonicalizeBranchPrefix(route, idx);
+  const decoded = parts.map(decodeSegmentToken).filter(Boolean);
+  if (decoded.length === 0) return canonicalizeBranchPrefix(route, idx);
+  // scan-codebase's routePath enumeration drops route groups — match it or the route→file lookup breaks.
+  return stripRouteGroups('/' + decoded.join('/'));
+}
+
+function canonicalizeBranchPrefix(route, segmentsIdx) {
+  const prefix = route.slice(0, segmentsIdx);
+  const parts = prefix.split('/').filter(Boolean);
+  // Drop trailing dynamic value (e.g. "london") and base64 flag-state — neither is a route segment.
+  const cleaned = parts
+    .filter((p) => !isBase64FlagState(p))
+    .slice(0, -1);
+  if (cleaned.length === 0) return prefix || '/';
+  return '/' + cleaned.join('/');
+}
+
+function isMetricLeaf(token) {
+  return (
+    token === '__PAGE__.segment' ||
+    token === '_tree.segment' ||
+    token === '_index.segment' ||
+    token === '__page__.segment' ||
+    token.endsWith('.segment') && token.startsWith('_')
+  );
+}
+
+// Conservative heuristic for `eyJoYXNTZXNzaW9uIjpmYWxzZX0`-shape tokens: URL-safe base64 alphabet, length ≥16, mixed case.
+function isBase64FlagState(token) {
+  if (typeof token !== 'string') return false;
+  if (token.length < 16) return false;
+  return /^[A-Za-z0-9_-]+$/.test(token) && /[A-Z]/.test(token) && /[a-z]/.test(token);
+}
+
+// `/event/<base64>/teaser` → `/event/[*]/teaser`. Stripping entirely (old behavior) corrupted segment count and broke route→file lookup.
+function replaceBase64WithDynamic(route) {
+  if (typeof route !== 'string' || !route.startsWith('/')) return route;
+  const parts = route.split('/');
+  let mutated = false;
+  const replaced = parts.map((p, i) => {
+    if (i === 0) return p;
+    if (isBase64FlagState(p)) { mutated = true; return '[*]'; }
+    return p;
+  });
+  if (!mutated) return route;
+  return replaced.join('/') || '/';
+}
+
+// Route groups `(default)` never appear in rendered URLs — scan-codebase drops them, so canonical form must match.
+function stripRouteGroups(route) {
+  if (typeof route !== 'string' || !route.includes('(')) return route;
+  const parts = route.split('/');
+  const kept = parts.filter((p) => !/^\([^)]+\)$/.test(p));
+  const joined = kept.join('/');
+  return joined.startsWith('/') ? (joined || '/') : '/' + joined;
+}
+
+// $d$X → [X] · $oc$X → [[...X]] · $c$X → [...X] · !K…p → (group) · metric-leaves → dropped.
+function decodeSegmentToken(token) {
+  if (isMetricLeaf(token)) return '';
+
+  let t = token.endsWith('.segment') ? token.slice(0, -'.segment'.length) : token;
+
+  if (/^\$d\$/.test(t)) return `[${t.slice(3)}]`;
+  if (/^\$oc\$/.test(t)) return `[[...${t.slice(4)}]]`;
+  if (/^\$c\$/.test(t)) return `[...${t.slice(3)}]`;
+
+  // `!` is segment-tree marker; body is base64 of `(default)` etc. Accept only when decoded looks like `(name)`.
+  if (t.startsWith('!') && t.length > 1) {
+    const body = t.slice(1);
+    try {
+      const decoded = Buffer.from(body, 'base64').toString('utf-8');
+      if (/^\(.*\)$/.test(decoded)) return decoded;
+    } catch {
+      /* fall through on decode failure */
+    }
+  }
+
+  return t;
+}
+
+export function candidateKey(candidate) {
+  const route = candidate?.route ?? candidate?.hostname ?? null;
+  const kind = candidate?.kind ?? '?';
+  const canonical = route ? canonicalizeRoute(route) : '<account>';
+  return `${kind}::${canonical}`;
+}
+
+// Records alternates so the brief shows "all 4 cities collapse here" rather than a single per-city dupe.
+export function mergeCandidates(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  const winner = (b.priority ?? 0) > (a.priority ?? 0) ? b : a;
+  const loser = winner === a ? b : a;
+  const altRoutes = new Set([
+    ...(Array.isArray(winner.aliasRoutes) ? winner.aliasRoutes : []),
+    ...(Array.isArray(loser.aliasRoutes) ? loser.aliasRoutes : []),
+  ]);
+  if (loser.route && loser.route !== winner.route) altRoutes.add(loser.route);
+  return {
+    ...winner,
+    // Canonicalize so briefs/reports/deep-dives see the clean path.
+    route: canonicalizeRoute(winner.route),
+    aliasRoutes: [...altRoutes].sort(),
+    mergedCount: (winner.mergedCount ?? 1) + (loser.mergedCount ?? 1),
+  };
+}
+
+// Input assumed sorted priority desc; output preserves that order. Account-scope pass through unchanged.
+export function dedupeCandidates(candidates) {
+  const byKey = new Map();
+  const order = [];
+  const dropped = [];
+  for (const c of candidates) {
+    if (!c || c.scope === 'account' || (!c.route && !c.hostname)) {
+      order.push(c);
+      continue;
+    }
+    const key = candidateKey(c);
+    if (byKey.has(key)) {
+      const merged = mergeCandidates(byKey.get(key), c);
+      byKey.set(key, merged);
+      dropped.push({
+        candidate: c,
+        mergedInto: key,
+        reason: 'duplicate of higher-priority sibling (same source route after canonicalization)',
+      });
+    } else {
+      byKey.set(key, { ...c, route: c.route ? canonicalizeRoute(c.route) : c.route });
+      order.push({ __key: key });
+    }
+  }
+  const deduped = order.map((c) => (c && c.__key ? byKey.get(c.__key) : c));
+  return { deduped, dropped };
+}
+
+export function isLikelyNextRouteShape(route) {
+  return typeof route === 'string' && route.length > 0 && !ROUTE_SHAPE_RE.test(route);
+}
+
+export function routeShapeWarning(route, signals = {}) {
+  return routeShapeWarnings(route, signals)[0] ?? null;
+}
+
+export function routeShapeWarnings(route, signals = {}) {
+  if (typeof route !== 'string' || route.length === 0) return [];
+  const warnings = [];
+  if (ROUTE_SHAPE_RE.test(route)) warnings.push('route-shape:suspicious-metric-label');
+  const first = firstRouteSegment(canonicalizeRoute(route));
+  if (first && shouldWarnUnknownFirstSegment(first, signals)) {
+    warnings.push(`route-shape:unknown-first-segment:${first}`);
+  }
+  return warnings;
+}
+
+export function withRouteShapeWarnings(candidate, signals = {}) {
+  const warnings = routeShapeWarnings(candidate?.route, signals);
+  if (warnings.length === 0) return candidate;
+  return {
+    ...candidate,
+    warnings: [...new Set([...(Array.isArray(candidate.warnings) ? candidate.warnings : []), ...warnings])],
+  };
+}
+
+function firstRouteSegment(route) {
+  if (typeof route !== 'string') return null;
+  return route.split('/').filter(Boolean)[0] ?? null;
+}
+
+function shouldWarnUnknownFirstSegment(first, signals) {
+  const exempt = new Set(['_next', '_vercel', 'api', '.well-known']);
+  if (exempt.has(first)) return false;
+  const known = knownFirstSegments(signals);
+  if (known.size === 0) return false;
+  if ([...known].some(isDynamicPlaceholder)) return false;
+  return !known.has(first);
+}
+
+function knownFirstSegments(signals) {
+  const out = new Set();
+  const routes = signals.codebase?.routes ?? [];
+  for (const route of routes) {
+    const first = firstRouteSegment(route?.routePath);
+    if (first) out.add(first);
+  }
+  return out;
+}
+
+function isDynamicPlaceholder(segment) {
+  return /^\[.*\]$/.test(segment);
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/bot-protection-certainty.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/bot-protection-certainty.mjs
new file mode 100644
index 0000000..5de9a71
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/bot-protection-certainty.mjs
@@ -0,0 +1,38 @@
+// Bot Protection evidence is usually account-level summary data. Avoid turning
+// observed bot traffic into unsupported statements about exact WAF rule state.
+
+export const metadata = {
+  id: 'bot-protection-certainty',
+  description: 'Soften unsupported Bot Protection / WAF certainty and require a staged rollout caveat.',
+};
+
+const STRING_FIELDS = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior', 'verify'];
+
+export function apply(rec) {
+  if (!String(rec?.candidateRef ?? '').startsWith('platform_bot_protection:')) return {};
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    let after = before
+      .replace(/\bno\s+(?:firewall\s+)?bot_filter\s+rule\b/gi, 'the collected firewall summary did not show an enforced bot-filter rule')
+      .replace(/\b(?:bots?|bot traffic)\s+(?:is|are)\s+the\s+cause\b/gi, 'bot traffic is a likely contributor')
+      .replace(/\bwithout\s+false[- ]positive\s+risk\b/gi, 'with false-positive risk monitored during rollout')
+      .replace(/\bno\s+false[- ]positive\s+risk\b/gi, 'false-positive risk still needs rollout monitoring');
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`bot-protection-certainty:${field}`);
+    }
+  }
+
+  const text = STRING_FIELDS.map((field) => rec?.[field]).filter((s) => typeof s === 'string').join('\n');
+  if (/\b(?:Bot Protection|BotID|bot_filter|WAF)\b/i.test(text) &&
+      !/\bstaged\b[\s\S]{0,80}\b(?:log|allowlist|exclusions?)\b/i.test(text)) {
+    const caveat = ' Use a staged rollout that starts in Log mode where available, then moves to the appropriate Challenge or Deny action only after allowlist/exclusion review for known monitoring and partner clients.';
+    if (typeof rec.fix === 'string') rec.fix += caveat;
+    else rec.fix = caveat.trim();
+    tags.push('bot-protection-certainty:staged-rollout');
+  }
+
+  return tags.length > 0 ? { tags, needsReview: true } : {};
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/cache-tag-invalidation-certainty.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/cache-tag-invalidation-certainty.mjs
new file mode 100644
index 0000000..b635a57
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/cache-tag-invalidation-certainty.mjs
@@ -0,0 +1,30 @@
+// A cacheTag() in the cached function is not proof that CMS edits invalidate it.
+// The report must not claim "existing tags preserve instant updates" unless the
+// investigation verifies matching revalidateTag/updateTag paths.
+
+export const metadata = {
+  id: 'cache-tag-invalidation-certainty',
+  description: 'Remove unsupported certainty that existing cache tags already preserve CMS/on-demand invalidation.',
+};
+
+const STRING_FIELDS = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior', 'verify'];
+const UNSUPPORTED_TAG_CERTAINTY =
+  /\b(?:existing|current)\s+(?:cache\s+)?tags?\b[^.!?\n]{0,160}\b(?:preserve|keep|cover|maintain|ensure)\b[^.!?\n]{0,160}\b(?:instant|on-demand|CMS|content|publish|update|updates|invalidation|revalidation)\b[^.!?\n]*(?:[.!?]|$)/gi;
+const SAFE_REPLACEMENT =
+  'Confirm a matching revalidateTag() or updateTag() path for each cacheTag() before increasing the cache lifetime.';
+
+export function apply(rec) {
+  const text = STRING_FIELDS.map((field) => rec?.[field]).filter((s) => typeof s === 'string').join('\n');
+  if (!/\bcache(?:Life|Tag)\b/.test(text)) return {};
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    const after = before.replace(UNSUPPORTED_TAG_CERTAINTY, SAFE_REPLACEMENT);
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`cache-tag-invalidation-certainty:${field}`);
+    }
+  }
+  return tags.length > 0 ? { tags, needsReview: true } : {};
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/count-correct.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/count-correct.mjs
new file mode 100644
index 0000000..b28e17b
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/count-correct.mjs
@@ -0,0 +1,52 @@
+// Rewrite verifier-failed count claims to ground truth (or "a number of"
+// when actual isn't numeric) so we don't ship false precision.
+
+import { escapeRegex } from '../util.mjs';
+
+export const metadata = {
+  id: 'count-correct',
+  description: 'Rewrite count claims to verified ground truth (count-correct) or "a number of" (count-strip) when verifier disagrees.',
+};
+
+const COUNT_CLAIM_TYPES = new Set(['pattern_count', 'repo_count', 'cited_count_literal']);
+
+export function apply(rec, ctx = {}) {
+  const results = ctx.verifyResults ?? rec.verifyResults ?? rec.verification?.failed ?? null;
+  if (!Array.isArray(results) || results.length === 0) return {};
+
+  const tags = [];
+
+  for (const r of results) {
+    if (!r) continue;
+    const type = r.type ?? r.claimType;
+    if (!COUNT_CLAIM_TYPES.has(type)) continue;
+    const disp = r.disposition ?? (r.actual !== r.expected ? 'failed' : 'verified');
+    if (disp !== 'failed') continue;
+    const expected = r.expected;
+    const actual = r.actual;
+    const token = r.token ?? r.text ?? expected;
+    if (expected == null || token == null) continue;
+
+    if (typeof actual === 'number' && Number.isFinite(actual)) {
+      rewriteCount(rec, token, expected, `~${actual}`);
+      tags.push(`count-correct:${token}:${expected}->${actual}`);
+    } else {
+      rewriteCount(rec, token, expected, 'a number of');
+      tags.push(`count-strip:${token}`);
+    }
+  }
+
+  if (tags.length === 0) return {};
+  return { tags };
+}
+
+function rewriteCount(rec, token, oldCount, replacement) {
+  const fields = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior'];
+  // Matches "60", "~60", and "60+" — LLM commonly writes "60+ icons".
+  const oldEsc = escapeRegex(String(oldCount));
+  const re = new RegExp(`\\b~?${oldEsc}\\+?\\s+${escapeRegex(token)}\\b`, 'g');
+  for (const f of fields) {
+    if (typeof rec[f] !== 'string') continue;
+    rec[f] = rec[f].replace(re, `${replacement} ${token}`);
+  }
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/function-duration-invocations.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/function-duration-invocations.mjs
new file mode 100644
index 0000000..69bd0b1
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/function-duration-invocations.mjs
@@ -0,0 +1,38 @@
+// A function-duration optimization can reduce p95/CPU/GB-hr. It does not by
+// itself reduce function invocation count unless the fix also adds CDN/static
+// response caching.
+
+export const metadata = {
+  id: 'function-duration-invocations',
+  description: 'Remove false claims that slow-route data-cache fixes reduce function invocation count.',
+};
+
+const STRING_FIELDS = [
+  'what',
+  'why',
+  'fix',
+  'currentBehavior',
+  'desiredBehavior',
+  'verify',
+];
+
+const BAD_INVOCATION_CLAIM =
+  /\bfunction invocations?\b[^.!?\n]{0,120}\b(?:drop|drops|fall|falls|decrease|decreases|decline|declines|reduce|reduces|reduced|cut|cuts)\b[^.!?\n]*(?:[.!?]|$)|\b(?:drop|drops|fall|falls|decrease|decreases|decline|declines|reduce|reduces|reduced|cut|cuts)\b[^.!?\n]{0,120}\bfunction invocations?\b[^.!?\n]*(?:[.!?]|$)/gi;
+
+const SAFE_REPLACEMENT =
+  '95th percentile duration should drop; function invocation count may stay flat unless a separate CDN or static-rendering change is made.';
+
+export function apply(rec) {
+  if (!String(rec?.candidateRef ?? '').startsWith('slow_route:')) return {};
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    const after = before.replace(BAD_INVOCATION_CLAIM, SAFE_REPLACEMENT);
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`function-duration-invocations:${field}`);
+    }
+  }
+  return tags.length > 0 ? { tags } : {};
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/index.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/index.mjs
new file mode 100644
index 0000000..93f0a1f
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/index.mjs
@@ -0,0 +1,79 @@
+// Sanitizer orchestrator. Order matters: citation strippers must run
+// before missing-citation so an emptied citations[] still drops the rec.
+
+import { applyDollarStrip } from '../impact-magnitude.mjs';
+import { sanitizeCitations } from '../citations.mjs';
+import * as vercelDirectiveStrip from './vercel-directive-strip.mjs';
+import * as rateLimit from './rate-limit.mjs';
+import * as preRelease from './pre-release.mjs';
+import * as middlewareConflict from './middleware-conflict.mjs';
+import * as undeclaredDep from './undeclared-dep.mjs';
+import * as countCorrect from './count-correct.mjs';
+import * as renderingModeMislabel from './rendering-mode-mislabel.mjs';
+import * as windowUnits from './window-units.mjs';
+import * as functionDurationInvocations from './function-duration-invocations.mjs';
+import * as botProtectionCertainty from './bot-protection-certainty.mjs';
+import * as cacheTagInvalidationCertainty from './cache-tag-invalidation-certainty.mjs';
+import * as missingCitation from './missing-citation.mjs';
+
+export const SANITIZERS = [
+  vercelDirectiveStrip,
+  rateLimit,
+  preRelease,
+  middlewareConflict,
+  undeclaredDep,
+  countCorrect,
+  renderingModeMislabel,
+  windowUnits,
+  functionDurationInvocations,
+  botProtectionCertainty,
+  cacheTagInvalidationCertainty,
+];
+
+export function recordSanitizer(rec, tag) {
+  rec.sanitizerTrail = rec.sanitizerTrail ?? [];
+  rec.sanitizerTrail.push(tag);
+}
+
+export async function applySanitizers(rec, ctx = {}) {
+  applyDollarStrip(rec);
+
+  for (const s of SANITIZERS) {
+    const result = s.apply(rec, ctx) ?? {};
+    const tags = result.tags ?? (result.tag ? [result.tag] : []);
+    for (const t of tags) recordSanitizer(rec, t);
+    if (result.needsReview) rec.needsReview = true;
+    if (result.dropped) {
+      return { kept: false, rec, dropReason: tags[0] ?? `dropped-by:${s.metadata?.id ?? 'unknown'}` };
+    }
+  }
+
+  if (ctx.framework && ctx.version) {
+    const before = (rec.citations ?? []).slice();
+    const { strippedUnknown, strippedVersion } = await sanitizeCitations(rec, ctx.framework, ctx.version);
+    for (const u of strippedUnknown) recordSanitizer(rec, `unknown-citation:${u}`);
+    for (const u of strippedVersion) recordSanitizer(rec, `version-mismatch:${u}`);
+    const lostAny = strippedUnknown.length > 0 || strippedVersion.length > 0;
+    const lostAll = lostAny && (rec.citations ?? []).length === 0 && before.length > 0;
+    if (lostAll) rec.needsReview = true;
+  }
+
+  // missing-citation runs LAST so citation strippers above can starve a rec.
+  const missing = missingCitation.apply(rec, ctx) ?? {};
+  if (missing.dropped) {
+    return { kept: false, rec, dropReason: missing.tag ?? 'missing-citation' };
+  }
+
+  return { kept: true, rec };
+}
+
+export async function applySanitizersBatch(recs, ctx = {}) {
+  const kept = [];
+  const dropped = [];
+  for (const rec of recs) {
+    const r = await applySanitizers(rec, ctx);
+    if (r.kept) kept.push(r.rec);
+    else dropped.push({ rec: r.rec, dropReason: r.dropReason });
+  }
+  return { kept, dropped };
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/middleware-conflict.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/middleware-conflict.mjs
new file mode 100644
index 0000000..83abb4a
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/middleware-conflict.mjs
@@ -0,0 +1,36 @@
+// Append a caveat when a rec targets a route covered by middleware: e.g.
+// middleware setting Set-Cookie downstream poisons cache headers the rec
+// adds. Trusts finding.routesCovered rather than re-implementing Next's
+// matcher algorithm.
+
+import { extractRoute } from '../util.mjs';
+
+export const metadata = {
+  id: 'middleware-conflict',
+  description: 'Append caveat when rec targets a route covered by middleware.',
+};
+
+export function apply(rec, ctx = {}) {
+  const findings = ctx?.signals?.codebase?.findings ?? [];
+  const middlewareFinding = findings.find((f) => f?.scannerId === 'middleware-broad-matcher' || f?.id === 'middleware-broad-matcher');
+  if (!middlewareFinding) return {};
+
+  const route = extractRoute(rec);
+  if (!route) return {};
+
+  const matcher = middlewareFinding.detail?.matcher
+    ?? middlewareFinding.matcher
+    ?? '(unspecified matcher)';
+  const middlewareFile = middlewareFinding.file ?? middlewareFinding.path ?? 'middleware.ts';
+
+  const covered = middlewareFinding.detail?.routesCovered ?? middlewareFinding.routesCovered;
+  if (Array.isArray(covered) && covered.length > 0 && !covered.includes(route)) {
+    return {};
+  }
+
+  const tag = `middleware-conflict:${matcher}`;
+  const caveat = `\n\n_Caveat: Middleware at \`${middlewareFile}\` (matcher: \`${matcher}\`) may intercept \`${route}\` and alter request/response before this fix takes effect. Verify the middleware does not set headers (e.g. \`Set-Cookie\`) that would invalidate caching._`;
+
+  if (typeof rec.fix === 'string') rec.fix += caveat;
+  return { tag, needsReview: true };
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/missing-citation.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/missing-citation.mjs
new file mode 100644
index 0000000..2442d84
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/missing-citation.mjs
@@ -0,0 +1,16 @@
+// Final-gate sanitizer: drops a rec with no citations left after
+// unknown-citation + version-mismatch have run. Every rec must carry ≥1
+// citation.
+
+export const metadata = {
+  id: 'missing-citation',
+  description: 'Drop rec when citations[] is empty after other sanitizers.',
+};
+
+export function apply(rec, _ctx = {}) {
+  const cites = Array.isArray(rec.citations) ? rec.citations : [];
+  if (cites.length === 0) {
+    return { dropped: true, tag: 'missing-citation' };
+  }
+  return {};
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/pre-release.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/pre-release.mjs
new file mode 100644
index 0000000..c401da6
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/pre-release.mjs
@@ -0,0 +1,74 @@
+// Append a caveat (don't drop — customer may opt in to canary) when a
+// fix needs a canary/rc/beta dep version.
+
+import { matchesFrameworkVersion } from '../citations.mjs';
+
+const PRE_RELEASE_FEATURES = [
+  {
+    match: /\bppr\b|partial[- ]?prerendering/i,
+    requires: 'next@canary',
+    message: 'PPR is experimental — verify your Next.js version supports it as stable',
+  },
+  {
+    match: /\buse cache['"]?\s*directive\b|"use cache"|'use cache'/i,
+    requires: 'next@>=15.0.0',
+    message: 'use cache directive is stable in 15+',
+  },
+  {
+    match: /\bcacheLife\(/i,
+    requires: 'next@>=15.0.0',
+    message: 'cacheLife is stable in 15+',
+  },
+  {
+    match: /\bcacheTag\(/i,
+    requires: 'next@>=15.0.0',
+    message: 'cacheTag is stable in 15+',
+  },
+];
+
+const SEMVER_PRE_RELEASE_RE = /\b([\w-]+)@(\d+\.\d+\.\d+-(?:rc|beta|canary|alpha|next|exp)[\w.-]*)/g;
+
+export const metadata = {
+  id: 'pre-release',
+  description: 'Append caveat when fix targets a canary/rc/beta feature.',
+};
+
+export function apply(rec, ctx = {}) {
+  const text = [rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+  if (!text) return {};
+
+  const tags = [];
+  const caveats = [];
+
+  for (const feat of PRE_RELEASE_FEATURES) {
+    if (feat.match.test(text)) {
+      if (featureAvailableForStack(feat, ctx)) continue;
+      const tag = `pre-release:${feat.requires}`;
+      if (!tags.includes(tag)) {
+        tags.push(tag);
+        caveats.push(`Requires ${feat.requires} (${feat.message}).`);
+      }
+    }
+  }
+
+  for (const m of text.matchAll(SEMVER_PRE_RELEASE_RE)) {
+    const [, pkg, version] = m;
+    const tag = `pre-release:${pkg}@${version}`;
+    if (!tags.includes(tag)) {
+      tags.push(tag);
+      caveats.push(`Requires pre-release version: \`${pkg}@${version}\`.`);
+    }
+  }
+
+  if (tags.length === 0) return {};
+  const caveatBlock = '\n\n_Note: ' + caveats.join(' ') + '_';
+  if (typeof rec.fix === 'string') rec.fix += caveatBlock;
+  return { tags, needsReview: true };
+}
+
+function featureAvailableForStack(feat, ctx) {
+  if (!ctx?.framework || !ctx?.version) return false;
+  return matchesFrameworkVersion(feat.requires, ctx.framework, ctx.version);
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/rate-limit.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/rate-limit.mjs
new file mode 100644
index 0000000..9809a64
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/rate-limit.mjs
@@ -0,0 +1,67 @@
+// Prepend a caveat (don't drop — customer may be on a higher tier) when a
+// rec prescribes concurrency above a known provider rate limit.
+
+const PROVIDER_LIMITS = {
+  notion: { rps: 3, label: 'Notion', doc: 'https://developers.notion.com/reference/request-limits' },
+  openai: { rps: 30, label: 'OpenAI', doc: 'https://platform.openai.com/docs/guides/rate-limits' },
+  stripe: { rps: 100, label: 'Stripe', doc: 'https://docs.stripe.com/rate-limits' },
+  anthropic: { rps: 10, label: 'Anthropic', doc: 'https://docs.anthropic.com/en/api/rate-limits' },
+};
+
+export const metadata = {
+  id: 'rate-limit',
+  description: 'Prepend caveat when a rec prescribes concurrency above a known provider rate limit.',
+};
+
+const PROVIDER_RE = new RegExp(`\\b(${Object.keys(PROVIDER_LIMITS).join('|')})\\b`, 'gi');
+const CONCURRENCY_RE = /\b(?:concurrency|parallel|in\s+parallel|simultaneous|simultaneously|fan[- ]?out|Promise\.all)\b[^\d]{0,40}(\d{1,4})\b/gi;
+const CONCURRENCY_RE_REVERSE = /\b(\d{1,4})\s*(?:concurrent|parallel|simultaneous|in flight)\b/gi;
+
+export function apply(rec, _ctx = {}) {
+  const text = collectText(rec);
+  const providers = matchProviders(text);
+  if (providers.length === 0) return {};
+  const concurrency = matchConcurrency(text);
+  if (concurrency === null) return {};
+
+  const tags = [];
+  let prepend = '';
+  for (const key of providers) {
+    const limit = PROVIDER_LIMITS[key];
+    if (!limit) continue;
+    if (concurrency > limit.rps) {
+      const tag = `rate-limit:${limit.label}:${concurrency}/${limit.rps}`;
+      tags.push(tag);
+      prepend += `⚠ ${limit.label} rate-limits to ~${limit.rps} requests/second on first-tier plans; the prescribed concurrency of ${concurrency} may saturate the limit. Verify your tier before applying.\n\n`;
+    }
+  }
+  if (tags.length === 0) return {};
+  if (typeof rec.fix === 'string') rec.fix = prepend + rec.fix;
+  else rec.fix = prepend.trim();
+  return { tags, needsReview: true };
+}
+
+function collectText(rec) {
+  return [rec.what, rec.why, rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+}
+
+function matchProviders(text) {
+  const out = new Set();
+  for (const m of text.matchAll(PROVIDER_RE)) out.add(m[1].toLowerCase());
+  return [...out];
+}
+
+function matchConcurrency(text) {
+  let max = null;
+  for (const m of text.matchAll(CONCURRENCY_RE)) {
+    const n = Number(m[1]);
+    if (Number.isFinite(n) && (max === null || n > max)) max = n;
+  }
+  for (const m of text.matchAll(CONCURRENCY_RE_REVERSE)) {
+    const n = Number(m[1]);
+    if (Number.isFinite(n) && (max === null || n > max)) max = n;
+  }
+  return max;
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/rendering-mode-mislabel.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/rendering-mode-mislabel.mjs
new file mode 100644
index 0000000..27e5c37
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/rendering-mode-mislabel.mjs
@@ -0,0 +1,38 @@
+// Warn when a rec's claimed rendering mode (static/ISR/SSR) contradicts
+// the scanner-tagged mode for that route. No-op when the scanner didn't
+// tag a renderingMode — full AST inference isn't implemented yet.
+
+import { extractRoute } from '../util.mjs';
+
+const MODE_PATTERNS = {
+  static: /\bstatic(?:ally rendered)?\b|prerender(?:ed)?\b/i,
+  isr: /\bISR\b|incremental[- ]?static|revalidate\s*:\s*\d/i,
+  ssr: /\bSSR\b|server[- ]?side rendered|dynamic\s*=\s*['"]force-dynamic['"]/i,
+};
+
+export const metadata = {
+  id: 'rendering-mode-mislabel',
+  description: 'Catch recs that blame the wrong rendering mode (e.g. "convert from ISR" on a static page).',
+};
+
+export function apply(rec, ctx = {}) {
+  const route = extractRoute(rec);
+  if (!route) return {};
+  const routes = ctx?.signals?.codebase?.routes ?? [];
+  const match = routes.find((r) => r.routePath === route);
+  const actualMode = match?.renderingMode;
+  if (!actualMode) return {};
+
+  const text = [rec.what, rec.why, rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+  const claimedModes = Object.entries(MODE_PATTERNS)
+    .filter(([, re]) => re.test(text))
+    .map(([m]) => m);
+
+  if (claimedModes.length === 0 || claimedModes.includes(actualMode)) return {};
+
+  const warning = `\n\n_⚠ Rendering-mode mismatch: this rec describes the route as \`${claimedModes.join(', ')}\` but the scanner classified it as \`${actualMode}\`. Verify the rendering mode before applying._`;
+  if (typeof rec.fix === 'string') rec.fix += warning;
+  return { tag: `rendering-mode-mislabel:${claimedModes.join(',')}!=${actualMode}`, needsReview: true };
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/undeclared-dep.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/undeclared-dep.mjs
new file mode 100644
index 0000000..5dee0fe
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/undeclared-dep.mjs
@@ -0,0 +1,78 @@
+// Prepend `npm i <pkg>` when the fix imports a package missing from
+// package.json — otherwise pasted code hits a runtime error.
+
+const IMPORT_RE = /\bimport\s+(?:[\w*{}\s,]+\s+from\s+)?["']([^"']+)["']/g;
+const REQUIRE_RE = /\brequire\s*\(\s*["']([^"']+)["']\s*\)/g;
+// Captures package root from `pkg/sub` and `@scope/pkg/sub`.
+const PKG_ROOT_RE = /^(@[^/]+\/[^/]+|[^/]+)/;
+const NODE_BUILTINS = new Set([
+  'fs', 'fs/promises', 'path', 'os', 'crypto', 'http', 'https', 'http2', 'net',
+  'dns', 'tls', 'util', 'url', 'stream', 'buffer', 'events', 'process', 'child_process',
+  'cluster', 'worker_threads', 'inspector', 'perf_hooks', 'assert', 'console',
+  'querystring', 'string_decoder', 'tty', 'vm', 'zlib', 'readline', 'punycode',
+  'module', 'timers', 'async_hooks', 'v8', 'test', 'diagnostics_channel',
+]);
+
+export const metadata = {
+  id: 'undeclared-dep',
+  description: 'Prepend `npm i <pkg>` when fix imports a package not in package.json.',
+};
+
+export function apply(rec, ctx = {}) {
+  const pkg = ctx?.package ?? ctx?.signals?.package ?? null;
+  if (!pkg) return {};
+
+  const known = new Set([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+    ...Object.keys(pkg.peerDependencies ?? {}),
+    ...Object.keys(pkg.optionalDependencies ?? {}),
+  ]);
+
+  const text = [rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+  const codeBlocks = extractCodeBlocks(text);
+  const importedRoots = new Set();
+  for (const block of codeBlocks) {
+    for (const m of block.matchAll(IMPORT_RE)) {
+      const root = pkgRoot(m[1]);
+      if (root) importedRoots.add(root);
+    }
+    for (const m of block.matchAll(REQUIRE_RE)) {
+      const root = pkgRoot(m[1]);
+      if (root) importedRoots.add(root);
+    }
+  }
+
+  const undeclared = [...importedRoots]
+    .filter((r) => !r.startsWith('.'))
+    .filter((r) => !NODE_BUILTINS.has(r))
+    .filter((r) => !r.startsWith('node:'))
+    .filter((r) => !known.has(r));
+
+  if (undeclared.length === 0) return {};
+
+  const installLines = undeclared.map((p) => `\`npm i ${p}\``).join(', ');
+  const prepend = `**Add dependency first**: ${installLines}\n\n`;
+  if (typeof rec.fix === 'string') rec.fix = prepend + rec.fix;
+  else rec.fix = prepend.trim();
+  return { tags: undeclared.map((p) => `undeclared-dep:${p}`), needsReview: true };
+}
+
+function pkgRoot(specifier) {
+  if (!specifier) return null;
+  if (specifier.startsWith('.')) return specifier;
+  const m = specifier.match(PKG_ROOT_RE);
+  return m ? m[1] : null;
+}
+
+function extractCodeBlocks(text) {
+  const out = [];
+  const re = /```[\w-]*\n?([\s\S]*?)```/g;
+  let m;
+  while ((m = re.exec(text)) !== null) out.push(m[1]);
+  // Also scan raw text for rare inline imports outside code blocks.
+  out.push(text);
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/vercel-directive-strip.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/vercel-directive-strip.mjs
new file mode 100644
index 0000000..604f8af
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/vercel-directive-strip.mjs
@@ -0,0 +1,37 @@
+// Strip Cache-Control directives Vercel's CDN silently ignores
+// (stale-if-error, proxy-revalidate, must-revalidate). s-maxage/max-age/
+// stale-while-revalidate/no-store/private/public are honored — leave them.
+
+import { escapeRegex } from '../util.mjs';
+
+const STRIP_DIRECTIVES = ['stale-if-error', 'proxy-revalidate', 'must-revalidate'];
+
+export const metadata = {
+  id: 'vercel-directive-strip',
+  description: 'Strip cache-control directives Vercel\'s CDN does not honor.',
+};
+
+export function apply(rec, _ctx = {}) {
+  const fields = ['fix', 'currentBehavior', 'desiredBehavior'];
+  const strippedSet = new Set();
+  for (const f of fields) {
+    if (typeof rec[f] !== 'string') continue;
+    for (const directive of STRIP_DIRECTIVES) {
+      const re = new RegExp(`(?:,\\s*)?\\b${escapeRegex(directive)}\\b(?:\\s*,)?`, 'g');
+      if (re.test(rec[f])) {
+        rec[f] = rec[f]
+          .replace(new RegExp(`\\b${escapeRegex(directive)}\\b`, 'g'), '')
+          .replace(/,\s*,/g, ',')
+          .replace(/(['"])\s*,\s*/g, '$1, ')
+          .replace(/,\s*(['"])/g, ', $1')
+          .replace(/(['"])\s*,\s*(['"])/g, '$1, $2')
+          .replace(/\b(Cache-Control|cache-control)\b:\s*,\s*/g, '$1: ')
+          .replace(/(['"])\s*,\s*\1/g, '$1');
+        strippedSet.add(directive);
+      }
+    }
+  }
+  const stripped = [...strippedSet];
+  if (stripped.length === 0) return {};
+  return { tags: stripped.map((d) => `vercel-directive-strip:${d}`) };
+}
diff --git a/skills/vercel/vercel-optimize/lib/sanitizers/window-units.mjs b/skills/vercel/vercel-optimize/lib/sanitizers/window-units.mjs
new file mode 100644
index 0000000..f03bed6
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/sanitizers/window-units.mjs
@@ -0,0 +1,32 @@
+// The metrics window is fixed by collect-signals (currently 14d). Do not let
+// agent prose turn observed counts into monthly counts.
+
+import { normalizeObservedWindowUnits } from '../display-labels.mjs';
+
+export const metadata = {
+  id: 'window-units',
+  description: 'Rewrite observed /mo or monthly count units to /window so reports do not imply extrapolated monthly data.',
+};
+
+const STRING_FIELDS = [
+  'what',
+  'why',
+  'fix',
+  'currentBehavior',
+  'desiredBehavior',
+  'verify',
+];
+
+export function apply(rec) {
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    const after = normalizeObservedWindowUnits(before);
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`window-units:${field}`);
+    }
+  }
+  return tags.length > 0 ? { tags } : {};
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/cache-components-suspense-dedupe.mjs b/skills/vercel/vercel-optimize/lib/scanners/cache-components-suspense-dedupe.mjs
new file mode 100644
index 0000000..c28b202
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/cache-components-suspense-dedupe.mjs
@@ -0,0 +1,109 @@
+// Detects the Cache Components anti-pattern where `'use cache'` doesn't dedupe across
+// separate `<Suspense>` boundaries — each boundary triggers a separate evaluation of the
+// "shared" cached function, multiplying invocations and ISR write pressure.
+//
+// Simplified single-file heuristic (cross-file segment analysis is out of scope):
+//   File contains `'use cache'` directive (or `use cache` keyword)
+//   AND file has 2+ `<Suspense ...>` boundaries
+//   AND a repeated fetch URL or function call appears in the body.
+//
+// False positives are tolerable: the support-topic body recommends a known-good remediation
+// (hoist promise to page, or move to `'use cache: remote'`) whether or not the specific call
+// site is the exact one paying the cost. The verifier abstains when the file structure
+// doesn't match the pitfall.
+
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'cache-components-suspense-dedupe',
+  title: "'use cache' with multiple Suspense boundaries on the same data",
+  severity: 'medium',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    "Default `'use cache'` does not dedupe identical calls across separate `<Suspense>` boundaries on the same render. Each boundary re-invokes the cached function, multiplying function-duration cost and inflating ISR write churn when the output is large.",
+  fix:
+    "Hoist the promise to the page level (`const dataPromise = fetchData()` at the top, passed down to each Suspense child) OR move the shared fetch into a `'use cache: remote'` data-access layer so cross-request and cross-boundary dedupe applies.",
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/directives/use-cache',
+    'https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents',
+    'https://nextjs.org/docs/app/guides/migrating-to-cache-components',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '**/*.test.*', '**/*.spec.*'],
+  includeGlobs: [
+    '**/page.{ts,tsx,js,jsx}',
+    '**/layout.{ts,tsx,js,jsx}',
+    '**/components/**/*.{tsx,jsx}',
+  ],
+};
+
+const USE_CACHE_RE = /^[\t ]*['"]use cache['"]/m;
+const SUSPENSE_TAG_RE = /<Suspense\b/g;
+const FETCH_LITERAL_RE = /fetch\s*\(\s*(['"`])([^'"`]{6,200})\1/g;
+// Helper function calls that look like data-fetchers (lowercase camel, no JSX/HTML noise).
+const HELPER_CALL_RE = /\b(get|fetch|load|find|query|read)[A-Z][A-Za-z0-9_]+\s*\(/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!USE_CACHE_RE.test(content)) continue;
+
+    const suspenseCount = countMatches(content, SUSPENSE_TAG_RE);
+    if (suspenseCount < 2) continue;
+
+    const repeated = findRepeated(content);
+    if (repeated.length === 0) continue;
+
+    // Anchor the finding to the first repeated call site so the customer
+    // can locate the duplicate quickly.
+    const first = repeated[0];
+    out.push({
+      pattern: metadata.id,
+      file: path,
+      line: lineOf(content, first.firstIdx),
+      evidence: first.kind === 'fetch'
+        ? `fetch("${truncate(first.token, 60)}") called ${first.count}× across Suspense boundaries`
+        : `${first.token}() called ${first.count}× across Suspense boundaries`,
+      trafficIndependent: metadata.trafficIndependent,
+      subtype: first.kind === 'fetch' ? 'fetch-literal' : 'helper-call',
+    });
+  }
+  return out;
+}
+
+function countMatches(content, re) {
+  re.lastIndex = 0;
+  let n = 0;
+  while (re.exec(content) !== null) n++;
+  return n;
+}
+
+function findRepeated(content) {
+  const tokens = new Map(); // token -> { kind, count, firstIdx }
+  let m;
+  FETCH_LITERAL_RE.lastIndex = 0;
+  while ((m = FETCH_LITERAL_RE.exec(content)) !== null) {
+    record(tokens, m[2], 'fetch', m.index);
+  }
+  HELPER_CALL_RE.lastIndex = 0;
+  while ((m = HELPER_CALL_RE.exec(content)) !== null) {
+    const name = m[0].replace(/\s*\($/, '').trim();
+    record(tokens, name, 'helper', m.index);
+  }
+  return [...tokens.values()]
+    .filter((t) => t.count >= 2)
+    .sort((a, b) => b.count - a.count);
+}
+
+function record(map, token, kind, idx) {
+  if (!token) return;
+  if (!map.has(token)) {
+    map.set(token, { token, kind, count: 0, firstIdx: idx });
+  }
+  map.get(token).count++;
+}
+
+function truncate(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + '…';
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/edge-heavy-import.mjs b/skills/vercel/vercel-optimize/lib/scanners/edge-heavy-import.mjs
new file mode 100644
index 0000000..f42273d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/edge-heavy-import.mjs
@@ -0,0 +1,94 @@
+// Flag node-only / heavy imports in edge-runtime files (either a
+// middleware basename or an `export const runtime = 'edge'`). These
+// either fail at deploy (node: builtins, native bindings) or inflate
+// cold-start latency. Line-anchored matches + type-only-import skip
+// keep FP low.
+
+const EDGE_RUNTIME_RE = /export\s+const\s+runtime\s*=\s*['"]edge['"]/;
+const IMPORT_RE = /^\s*import\s+(?:type\s+)?(?:[^'"]*\s+from\s+)?['"]([^'"]+)['"]/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+const REQUIRE_RE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+const TYPE_IMPORT_RE = /^\s*import\s+type\s+/;
+
+const HEAVY_PATTERNS = [
+  /^node:/,
+  /^sharp$/,
+  /^@aws-sdk\//,
+  /^@prisma\/client$/,
+  /^prisma$/,
+  /^pg$/,
+  /^mysql2(?:\/|$)/,
+  /^puppeteer(?:-core)?(?:\/|$)/,
+  /^playwright(?:-core)?(?:\/|$)/,
+  /^bcrypt$/,
+  /^jsonwebtoken$/,
+  /^canvas$/,
+  /^@google-cloud\//,
+];
+
+export const metadata = {
+  id: 'edge-heavy-import',
+  title: 'Heavy / node-only import inside edge-runtime file',
+  severity: 'high',
+  billingDimension: 'function-duration',
+  trafficIndependent: true,
+  description:
+    'Edge runtime is a constrained sandbox with no node: builtins and a much smaller cold-start budget than Node functions. Heavy SDKs (sharp, @aws-sdk/*, @prisma/client, pg, puppeteer) either fail at deploy or inflate cold-start latency. Move the import to a Node runtime function, or replace with an edge-compatible alternative (e.g., neon-driver instead of pg).',
+  fix:
+    'Either (a) drop the `export const runtime = \'edge\'` so the route runs on Node (default in 2026), or (b) replace the heavy import with an edge-compatible alternative. For DB: use @neondatabase/serverless or @planetscale/database instead of pg/mysql2. For image: do the work in a Node route handler. For auth signing: use jose (Web Crypto) instead of jsonwebtoken.',
+  citations: [
+    'https://vercel.com/docs/functions/runtimes/edge-runtime',
+    'https://vercel.com/docs/fluid-compute',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '**/*.test.*', '**/*.spec.*'],
+  includeGlobs: ['**/*.{ts,tsx,js,mjs}'],
+};
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isEdgeRuntimeFile(path, content)) continue;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Type-only imports are erased at compile, never reach runtime.
+      if (TYPE_IMPORT_RE.test(line)) continue;
+      const specifiers = extractSpecifiers(line);
+      for (const spec of specifiers) {
+        const match = HEAVY_PATTERNS.find((re) => re.test(spec));
+        if (!match) continue;
+        out.push({
+          pattern: metadata.id,
+          file: path,
+          line: i + 1,
+          evidence: `import "${spec}" in edge-runtime file`,
+          edgeReason: isMiddleware(path) ? 'middleware (always edge)' : 'export const runtime = "edge"',
+          importedModule: spec,
+          trafficIndependent: metadata.trafficIndependent,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function isEdgeRuntimeFile(path, content) {
+  return isMiddleware(path) || EDGE_RUNTIME_RE.test(content);
+}
+
+function isMiddleware(path) {
+  return /(?:^|\/)middleware\.(ts|tsx|js|mjs)$/.test(path);
+}
+
+function extractSpecifiers(line) {
+  const out = new Set();
+  // IMPORT_RE has `gm` flag — reset lastIndex per call.
+  IMPORT_RE.lastIndex = 0;
+  let m;
+  while ((m = IMPORT_RE.exec(line)) !== null) out.add(m[1]);
+  DYNAMIC_IMPORT_RE.lastIndex = 0;
+  while ((m = DYNAMIC_IMPORT_RE.exec(line)) !== null) out.add(m[1]);
+  REQUIRE_RE.lastIndex = 0;
+  while ((m = REQUIRE_RE.exec(line)) !== null) out.add(m[1]);
+  return [...out];
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/force-dynamic.mjs b/skills/vercel/vercel-optimize/lib/scanners/force-dynamic.mjs
new file mode 100644
index 0000000..746cafd
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/force-dynamic.mjs
@@ -0,0 +1,42 @@
+export const metadata = {
+  id: 'force-dynamic',
+  title: "export const dynamic = 'force-dynamic'",
+  severity: 'medium',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    "force-dynamic disables static + ISR rendering. The route runs the function on every request. Sometimes necessary (cookies, headers, real-time data), often a habit that costs function-duration and edge-requests at scale.",
+  fix:
+    "Audit the route. If dynamic behavior comes from cookies()/headers()/searchParams, force-dynamic may be redundant — Next infers dynamic automatically. Consider revalidate / 'use cache' / generateStaticParams if any portion can be pre-rendered.",
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**'],
+  includeGlobs: ['**/route.{ts,tsx,js,jsx}', '**/page.{ts,tsx,js,jsx}'],
+};
+
+const RE = /export\s+const\s+dynamic\s*=\s*["']force-dynamic["']/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(path)) continue;
+    const m = RE.exec(content);
+    if (m) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: 'export const dynamic = "force-dynamic"',
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+import { lineOf } from '../util.mjs';
+
+function isApplicable(path) {
+  return /(\/route|\/page)\.(tsx?|jsx?)$/.test(path);
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/headers-in-page.mjs b/skills/vercel/vercel-optimize/lib/scanners/headers-in-page.mjs
new file mode 100644
index 0000000..cc91d06
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/headers-in-page.mjs
@@ -0,0 +1,44 @@
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'headers-in-page',
+  title: 'Dynamic API call forcing dynamic rendering',
+  severity: 'medium',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    'headers(), cookies(), and draftMode() are dynamic APIs. Reading them in a page/layout makes the entire segment dynamic — no ISR, no static generation, and a function invocation on every request.',
+  fix:
+    'Move the dynamic API call into a child Server Component that lives inside a Suspense boundary. The parent can stay static; only the leaf re-renders dynamically.',
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config',
+    'https://nextjs.org/docs/app/building-your-application/caching',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**'],
+  includeGlobs: ['**/{page,layout,template}.{tsx,jsx}'],
+};
+
+const RE = /\b(cookies|headers|draftMode)\s*\(\s*\)/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(path)) continue;
+    let m;
+    RE.lastIndex = 0;
+    while ((m = RE.exec(content)) !== null) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: `${m[1]}()`,
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+function isApplicable(path) {
+  return /\/(page|layout|template)\.(tsx|jsx)$/.test(path);
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/index.mjs b/skills/vercel/vercel-optimize/lib/scanners/index.mjs
new file mode 100644
index 0000000..9a35bf0
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/index.mjs
@@ -0,0 +1,35 @@
+import * as unoptimizedImage from './unoptimized-image.mjs';
+import * as forceDynamic from './force-dynamic.mjs';
+import * as middlewareBroad from './middleware-broad-matcher.mjs';
+import * as missingCacheHeaders from './missing-cache-headers.mjs';
+import * as maxAgeNoSMaxage from './max-age-without-s-maxage.mjs';
+import * as headersInPage from './headers-in-page.mjs';
+import * as sourceMapsProd from './source-maps-production.mjs';
+import * as prismaIncludeTree from './prisma-include-tree.mjs';
+import * as sveltekitPrerenderMissing from './sveltekit-prerender-missing.mjs';
+import * as largeStaticAsset from './large-static-asset.mjs';
+import * as edgeHeavyImport from './edge-heavy-import.mjs';
+import * as useCacheDateStamp from './use-cache-date-stamp.mjs';
+import * as cacheComponentsSuspenseDedupe from './cache-components-suspense-dedupe.mjs';
+import * as turboForceBypass from './turbo-force-bypass.mjs';
+import * as regionPinInConfig from './region-pin-in-config.mjs';
+
+// `use-client-cascade` is intentionally NOT registered: 0.3% conversion
+// rate, and client-bundle size isn't billed on Vercel.
+export const scanners = [
+  unoptimizedImage,
+  forceDynamic,
+  middlewareBroad,
+  missingCacheHeaders,
+  maxAgeNoSMaxage,
+  headersInPage,
+  sourceMapsProd,
+  prismaIncludeTree,
+  sveltekitPrerenderMissing,
+  largeStaticAsset,
+  edgeHeavyImport,
+  useCacheDateStamp,
+  cacheComponentsSuspenseDedupe,
+  turboForceBypass,
+  regionPinInConfig,
+];
diff --git a/skills/vercel/vercel-optimize/lib/scanners/large-static-asset.mjs b/skills/vercel/vercel-optimize/lib/scanners/large-static-asset.mjs
new file mode 100644
index 0000000..62b2d27
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/large-static-asset.mjs
@@ -0,0 +1,92 @@
+// Flag oversized assets under public/. Pure fs.stat — no parsing, no LLM.
+// 500 KB threshold is where bandwidth/first-paint start to bite (Vercel
+// Doctor's 4 KB triggers on favicons).
+
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, extname } from 'node:path';
+
+const THRESHOLD_BYTES = 500_000;
+const TOP_N = 20;
+
+const SKIP_EXTENSIONS = new Set(['.html', '.txt', '.xml', '.json', '.webmanifest', '.ico']);
+const SKIP_PATH_PREFIXES = ['.well-known/'];
+
+export const metadata = {
+  id: 'large-static-asset',
+  title: 'Large file in public/',
+  severity: 'medium',
+  billingDimension: 'bandwidth',
+  trafficIndependent: true,
+  description:
+    'Static assets in `public/` over 500 KB ship as-is from the CDN. Whether the cost is meaningful depends on traffic, but the candidate is binary — the file is either needed at that size or it can be optimized (compressed image, video transcode, or moved off the critical path).',
+  fix:
+    'Verify the asset is reachable on the customer-facing hot path. Then choose: (a) compress (convert PNG → AVIF/WebP; transcode MP4 to lower bitrate); (b) host externally (Vercel Blob, S3, or a media CDN with per-asset signed URLs); (c) lazy-load (defer to client-side fetch instead of bundling into initial HTML).',
+  citations: [
+    'https://vercel.com/docs/manage-cdn-usage',
+    'https://vercel.com/docs/image-optimization',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**'],
+  includeGlobs: ['public/**/*'],
+};
+
+// Walks public/ directly because collectFiles only emits text-readable
+// extensions — binary assets never reach the shared `files` array.
+export async function scan({ rootDir }) {
+  if (!rootDir) return [];
+  const root = join(rootDir, 'public');
+  const out = [];
+  try {
+    for await (const entry of walk(root)) {
+      if (shouldSkip(entry.relPath)) continue;
+      if (entry.size < THRESHOLD_BYTES) continue;
+      out.push({
+        pattern: metadata.id,
+        file: join('public', entry.relPath),
+        line: 1,
+        evidence: `${formatBytes(entry.size)} (${extname(entry.relPath) || 'no-ext'})`,
+        trafficIndependent: metadata.trafficIndependent,
+        sizeBytes: entry.size,
+      });
+    }
+  } catch {
+    return [];
+  }
+  out.sort((a, b) => b.sizeBytes - a.sizeBytes);
+  return out.slice(0, TOP_N);
+}
+
+async function* walk(dir, base = '') {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    const rel = base ? `${base}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      yield* walk(full, rel);
+      continue;
+    }
+    if (!e.isFile()) continue;
+    try {
+      const s = await stat(full);
+      yield { relPath: rel, size: s.size };
+    } catch { /* skip unreadable */ }
+  }
+}
+
+function shouldSkip(relPath) {
+  if (SKIP_PATH_PREFIXES.some((p) => relPath.startsWith(p))) return true;
+  const ext = extname(relPath).toLowerCase();
+  if (SKIP_EXTENSIONS.has(ext)) return true;
+  return false;
+}
+
+function formatBytes(b) {
+  if (b >= 1e9) return (b / 1e9).toFixed(2) + ' GB';
+  if (b >= 1e6) return (b / 1e6).toFixed(2) + ' MB';
+  if (b >= 1e3) return (b / 1e3).toFixed(1) + ' KB';
+  return b + ' B';
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/max-age-without-s-maxage.mjs b/skills/vercel/vercel-optimize/lib/scanners/max-age-without-s-maxage.mjs
new file mode 100644
index 0000000..91ee295
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/max-age-without-s-maxage.mjs
@@ -0,0 +1,42 @@
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'max-age-without-s-maxage',
+  title: 'Cache-Control: max-age without s-maxage',
+  severity: 'medium',
+  billingDimension: 'edge-requests',
+  trafficIndependent: false,
+  description:
+    'max-age caches in the browser; s-maxage caches at the CDN. Without s-maxage, every uncached visitor request invokes the function. Adding s-maxage often cuts function invocations by 80%+ on read-heavy routes.',
+  fix:
+    'Add s-maxage to the Cache-Control header. Example: Cache-Control: public, max-age=60, s-maxage=600, stale-while-revalidate=86400. Pair with explicit cache-bust strategy if content can change.',
+  citations: [
+    'https://vercel.com/docs/caching/cdn-cache',
+    'https://vercel.com/docs/caching/cache-control-headers',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '*.config.*'],
+  includeGlobs: ['**/*.{ts,tsx,js,jsx,mjs}'],
+};
+
+const RE = /Cache-Control[^"'`]*?max-age\s*=\s*\d+/gi;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (/\.test\.|\.spec\./.test(path)) continue;
+    let m;
+    RE.lastIndex = 0;
+    while ((m = RE.exec(content)) !== null) {
+      const hit = m[0];
+      if (/s-maxage/i.test(hit) || /CDN-Cache-Control/i.test(content.slice(Math.max(0, m.index - 100), m.index + hit.length + 100))) continue;
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: hit.slice(0, 160),
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/middleware-broad-matcher.mjs b/skills/vercel/vercel-optimize/lib/scanners/middleware-broad-matcher.mjs
new file mode 100644
index 0000000..1ab1bee
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/middleware-broad-matcher.mjs
@@ -0,0 +1,55 @@
+export const metadata = {
+  id: 'middleware-broad-matcher',
+  title: 'Middleware matcher missing or too broad',
+  severity: 'high',
+  billingDimension: 'edge-requests',
+  trafficIndependent: true,
+  description:
+    'middleware.ts without a config.matcher (or matcher: ["/(.*)"]) runs on every request including _next/static, _next/image, favicon.ico, and image asset fetches. Edge-request cost scales accordingly.',
+  fix:
+    'Scope the matcher to actual application paths. Example: matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"]',
+  citations: [
+    'https://nextjs.org/docs/app/building-your-application/routing/middleware',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**'],
+  includeGlobs: ['middleware.{ts,js,mjs}', 'src/middleware.{ts,js,mjs}'],
+};
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(path)) continue;
+
+    const exportsMiddleware = /export\s+(default\s+)?(async\s+)?function\s+middleware/.test(content)
+      || /export\s+const\s+middleware\s*=/.test(content);
+    if (!exportsMiddleware) continue;
+
+    const configBlock = content.match(/export\s+const\s+config\s*=\s*\{([\s\S]*?)\}/);
+    const matcherStr = configBlock && configBlock[1].match(/matcher\s*:\s*([^,}]+)/);
+
+    let problem = null;
+    if (!configBlock || !matcherStr) {
+      problem = 'no config.matcher (runs on every request)';
+    } else {
+      const m = matcherStr[1];
+      if (/['"`]\s*\/\s*['"`]/.test(m) || /['"`]\/\(\.\*\)['"`]/.test(m)) {
+        problem = 'matcher = "/" or "/(.*)" (still covers everything)';
+      }
+    }
+
+    if (problem) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: 1,
+        evidence: problem,
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+function isApplicable(path) {
+  return /(^|\/)middleware\.(ts|js|mjs)$/.test(path);
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/missing-cache-headers.mjs b/skills/vercel/vercel-optimize/lib/scanners/missing-cache-headers.mjs
new file mode 100644
index 0000000..1ea3c63
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/missing-cache-headers.mjs
@@ -0,0 +1,90 @@
+// Two checks emitted as `missing-cache-headers`:
+//   A. GET handler with no Cache-Control AND no auth signal.
+//   B. fetch() with `cache:'no-store'` / `next:{revalidate:0}` outside an
+//      auth window (~10 lines above, 5 below).
+
+export const metadata = {
+  id: 'missing-cache-headers',
+  title: 'Cacheable route or fetch with no caching (Cache-Control absent or no-store)',
+  severity: 'medium',
+  billingDimension: 'edge-requests',
+  trafficIndependent: false,
+  description:
+    'Two antipatterns: (a) GET handlers without explicit Cache-Control headers serve uncached; (b) fetch() calls with cache:"no-store" or next:{revalidate:0} opt out of caching even on cacheable upstream data. For non-auth routes / fetches, both are leaving cache hits on the floor.',
+  fix:
+    'For GET handlers: return a Response with Cache-Control: public, s-maxage=<seconds>, stale-while-revalidate=<window>. For fetch(): drop cache:"no-store" (use { next: { revalidate: <seconds> } } in Next.js) so the response is cached by the framework + CDN.',
+  citations: [
+    'https://vercel.com/docs/caching/cdn-cache',
+    'https://vercel.com/docs/caching/cache-control-headers',
+    'https://nextjs.org/docs/app/building-your-application/caching',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '**/*.test.*', '**/*.spec.*'],
+  // page/layout included: no-store fetches commonly hide in Server Components.
+  includeGlobs: [
+    '**/route.{ts,tsx,js,jsx}',
+    '**/api/**/*.{ts,tsx,js,jsx}',
+    '**/page.{ts,tsx,js,jsx}',
+    '**/layout.{ts,tsx,js,jsx}',
+  ],
+};
+
+// Covers NextAuth, Clerk, JWT, Bearer, plus Next dynamic-render APIs.
+// FP on cacheable routes that read a session is acceptable — verifier decides.
+const AUTH_RE = /\b(cookies\(\)|headers\(\)|getSession\(|getServerSession\(|currentUser\(|clerkClient|auth\(\)|verifyJWT|verifyToken|jwt\.verify|decode\(|Bearer\s|Authorization|supabase\.auth\.)/i;
+
+const NO_STORE_RE = /cache\s*:\s*['"]no-store['"]/;
+const REVALIDATE_ZERO_RE = /next\s*:\s*\{[^}]*revalidate\s*:\s*0\b/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(path)) continue;
+
+    const hasGetHandler =
+      /export\s+(async\s+)?function\s+GET/.test(content)
+      || /export\s+const\s+GET\s*=/.test(content);
+    if (hasGetHandler) {
+      const hasCacheControl =
+        /Cache-Control/i.test(content)
+        || /CDN-Cache-Control/i.test(content)
+        || /export\s+const\s+revalidate\s*=/.test(content);
+      if (!hasCacheControl && !AUTH_RE.test(content)) {
+        out.push({
+          pattern: metadata.id,
+          subtype: 'get-handler-no-cache-control',
+          file: path,
+          line: 1,
+          evidence: 'GET handler with no Cache-Control / revalidate / auth signal',
+          trafficIndependent: metadata.trafficIndependent,
+        });
+      }
+    }
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const noStoreHit = NO_STORE_RE.test(line);
+      const revalidateZeroHit = REVALIDATE_ZERO_RE.test(line);
+      if (!noStoreHit && !revalidateZeroHit) continue;
+      const start = Math.max(0, i - 10);
+      const end = Math.min(lines.length, i + 5);
+      const window = lines.slice(start, end).join('\n');
+      if (AUTH_RE.test(window)) continue;
+      // Mutation verbs legitimately don't cache.
+      if (/method\s*:\s*['"](?:POST|PUT|PATCH|DELETE)['"]/i.test(window)) continue;
+      out.push({
+        pattern: metadata.id,
+        subtype: noStoreHit ? 'fetch-no-store' : 'fetch-revalidate-zero',
+        file: path,
+        line: i + 1,
+        evidence: line.trim().slice(0, 200),
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+function isApplicable(path) {
+  return /\/(route|index|page|layout)\.(ts|tsx|js|jsx)$/.test(path) || /\/api\//.test(path);
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/prisma-include-tree.mjs b/skills/vercel/vercel-optimize/lib/scanners/prisma-include-tree.mjs
new file mode 100644
index 0000000..1b3a2ed
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/prisma-include-tree.mjs
@@ -0,0 +1,42 @@
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'prisma-include-tree-bloat',
+  title: 'Deep Prisma include tree (3+ levels)',
+  severity: 'high',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    'Nested .include({ x: { include: { y: { include: { z: ... } } } } }) makes Prisma issue a single huge join that scales O(N*M*K). Function duration explodes, memory spikes, often causes timeouts.',
+  fix:
+    'Replace with explicit .findMany() calls or scoped .include() of only what the consumer reads. Consider Prisma.select() to project specific fields. For lists, batch with DataLoader patterns.',
+  citations: [
+    'vercel-react-best-practices:server-parallel-fetching',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**'],
+  includeGlobs: ['**/*.{ts,tsx,js,jsx}'],
+};
+
+// Catches 3+ nesting levels of `include:` within a single object literal.
+const RE = /include\s*:\s*\{[\s\S]*?include\s*:\s*\{[\s\S]*?include\s*:/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (/\.test\.|\.spec\./.test(path)) continue;
+    let m;
+    RE.lastIndex = 0;
+    while ((m = RE.exec(content)) !== null) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: '3+ levels of nested Prisma .include()',
+        trafficIndependent: metadata.trafficIndependent,
+      });
+      // One finding per file is enough — agent investigates holistically.
+      break;
+    }
+  }
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/region-pin-in-config.mjs b/skills/vercel/vercel-optimize/lib/scanners/region-pin-in-config.mjs
new file mode 100644
index 0000000..6ac6c06
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/region-pin-in-config.mjs
@@ -0,0 +1,88 @@
+// Detects pinned function regions in vercel.json or per-route segment config.
+// Provides the "configured region" signal for the region-misconfig gate when a TTFB
+// breakdown by function_region isn't available (current state — see Phase 0 preflight
+// in plans/wild-splashing-flamingo.md).
+//
+// Subtypes:
+//   vercel-json-single   — vercel.json `regions: ["iad1"]` (single region, no failover)
+//   vercel-json-list     — vercel.json `regions: [...]` (multi-region; informational)
+//   segment-preferred    — `export const preferredRegion = 'iad1'` (or array)
+
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'region-pin-in-config',
+  title: 'Function region pinned in config',
+  severity: 'low',
+  billingDimension: 'function-duration',
+  trafficIndependent: true,
+  description:
+    "vercel.json `regions` or per-route `preferredRegion` is set. If the pinned region is far from the dominant user geo (or far from a data source) p95 TTFB suffers. This scanner provides the configured-region signal so the region-misconfig gate can recommend an audit.",
+  fix:
+    "Audit the pinned region against traffic geography (Speed Insights or Web Analytics by country) and data-source location. Consider multi-region if data lives in a fixed location and users are global; consider relocating if users are concentrated in one geography.",
+  citations: [
+    'https://vercel.com/docs/functions/configuring-functions/region',
+    'https://vercel.com/docs/functions/configuring-functions/region',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**'],
+  includeGlobs: [
+    'vercel.json',
+    '**/vercel.json',
+    '**/page.{ts,tsx,js,jsx}',
+    '**/route.{ts,tsx,js,jsx}',
+    '**/layout.{ts,tsx,js,jsx}',
+  ],
+};
+
+// Matches `regions: ["iad1"]`, `regions: ['iad1', 'sfo1']`, or `"regions": ["iad1"]`
+const VERCEL_JSON_REGIONS_RE = /['"]?regions['"]?\s*:\s*\[([^\]]+)\]/;
+// `export const preferredRegion = 'iad1'` OR `= ['iad1', 'sfo1']`
+const PREFERRED_REGION_RE = /export\s+const\s+preferredRegion\s*=\s*(['"][^'"]+['"]|\[[^\]]+\])/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    const name = path.split('/').pop();
+
+    if (name === 'vercel.json') {
+      const m = VERCEL_JSON_REGIONS_RE.exec(content);
+      if (m) {
+        const regions = parseRegionList(m[1]);
+        out.push({
+          pattern: metadata.id,
+          file: path,
+          line: lineOf(content, m.index),
+          evidence: `vercel.json regions: [${regions.join(', ')}]`,
+          trafficIndependent: metadata.trafficIndependent,
+          subtype: regions.length === 1 ? 'vercel-json-single' : 'vercel-json-list',
+          regions,
+        });
+      }
+      continue;
+    }
+
+    // Segment config files (page.tsx, route.ts, layout.tsx).
+    const m = PREFERRED_REGION_RE.exec(content);
+    if (m) {
+      const raw = m[1];
+      const regions = raw.startsWith('[') ? parseRegionList(raw.slice(1, -1)) : [raw.replace(/['"]/g, '')];
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: `preferredRegion = ${raw}`,
+        trafficIndependent: metadata.trafficIndependent,
+        subtype: 'segment-preferred',
+        regions,
+      });
+    }
+  }
+  return out;
+}
+
+function parseRegionList(inner) {
+  return inner
+    .split(',')
+    .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/source-maps-production.mjs b/skills/vercel/vercel-optimize/lib/scanners/source-maps-production.mjs
new file mode 100644
index 0000000..e3c50ed
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/source-maps-production.mjs
@@ -0,0 +1,36 @@
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'source-maps-production',
+  title: 'Source maps enabled in production',
+  severity: 'low',
+  billingDimension: 'edge-requests',
+  trafficIndependent: true,
+  description:
+    'productionBrowserSourceMaps: true ships .map files in the production bundle, increasing transfer size 30-100% per visitor. Useful for error reporting via Sentry; not useful for users.',
+  fix:
+    'Keep source maps generation but exclude them from the public bundle. Upload to your error tracker via build-time CI step; do not serve them with the deployment.',
+  citations: [
+    'https://nextjs.org/docs/messages/improper-devtool',
+  ],
+  excludeGlobs: [],
+  includeGlobs: ['next.config.{js,mjs,ts}', 'svelte.config.{js,mjs,ts}'],
+};
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!/^next\.config\.(js|mjs|ts)$/.test(path.split('/').pop() ?? '')) continue;
+    const m = /productionBrowserSourceMaps\s*:\s*true/.exec(content);
+    if (m) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: 'productionBrowserSourceMaps: true',
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/sveltekit-prerender-missing.mjs b/skills/vercel/vercel-optimize/lib/scanners/sveltekit-prerender-missing.mjs
new file mode 100644
index 0000000..e61a623
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/sveltekit-prerender-missing.mjs
@@ -0,0 +1,43 @@
+// Flag SvelteKit pages that haven't declared prerender/ssr/config — they
+// default to per-request function execution. Pages that have already opted
+// in or out are skipped; the investigator agent decides actual staticness.
+
+export const metadata = {
+  id: 'sveltekit-prerender-missing',
+  title: 'SvelteKit page without explicit prerender / ISR config',
+  severity: 'low',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    'SvelteKit page or +page.server.ts is missing an explicit `prerender`, `ssr`, or adapter `config.isr` declaration. Default is per-request function execution — investigate whether the route could be prerendered or ISR-cached.',
+  fix:
+    'If the page is static (no per-user / per-request data), add `export const prerender = true` in +page.ts or +page.server.ts. If the data refreshes on a schedule, prefer adapter-vercel\'s ISR option via `export const config = { isr: { expiration: 60 } }`.',
+  citations: [
+    'https://kit.svelte.dev/docs/page-options',
+    'https://kit.svelte.dev/docs/adapter-vercel',
+    'https://vercel.com/docs/incremental-static-regeneration',
+  ],
+  excludeGlobs: ['node_modules/**', '.svelte-kit/**', 'build/**', '__tests__/**'],
+  includeGlobs: ['src/routes/**/+page.svelte', 'src/routes/**/+page.server.{ts,js}', 'src/routes/+page.svelte', 'src/routes/+page.server.{ts,js}'],
+};
+
+const PRERENDER_RE = /export\s+const\s+prerender\b/;
+const SSR_RE = /export\s+const\s+ssr\b/;
+const CONFIG_RE = /export\s+const\s+config\s*=\s*\{[^}]*\b(isr|prerender|runtime|split|regions)\b/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!path.includes('/routes/')) continue;
+    if (PRERENDER_RE.test(content) || SSR_RE.test(content) || CONFIG_RE.test(content)) continue;
+    out.push({
+      pattern: metadata.id,
+      file: path,
+      // Absence-finding — no specific line, placeholder 1.
+      line: 1,
+      evidence: 'No `prerender`, `ssr`, or `config = { isr | runtime | ... }` export found',
+      trafficIndependent: metadata.trafficIndependent,
+    });
+  }
+  return out;
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/turbo-force-bypass.mjs b/skills/vercel/vercel-optimize/lib/scanners/turbo-force-bypass.mjs
new file mode 100644
index 0000000..62de072
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/turbo-force-bypass.mjs
@@ -0,0 +1,129 @@
+// Detects Turborepo cache bypass patterns that cause every commit to rebuild every project,
+// driving Build Minutes to dominate the bill on monorepos.
+//
+// Three signal subtypes:
+//   force-flag      — `TURBO_FORCE=true` env var or `turbo run ... --force` in build script
+//   cache-disabled  — `turbo.json` declares `"cache": false` for the build pipeline
+//   no-ignore-step  — repo has turbo.json and no repo-declared ignoreCommand;
+//                     verify Vercel's skip-unaffected project setting before recommending one
+//
+// This pattern has caused full-monorepo rebuilds on every commit. Build-skip
+// settings and right-sized build machines can reduce Build Minutes when the
+// project is rebuilding unchanged work.
+
+export const metadata = {
+  id: 'turbo-force-bypass',
+  title: 'Turborepo cache bypass on a monorepo',
+  severity: 'high',
+  billingDimension: 'build',
+  trafficIndependent: true, // build-time, fires regardless of route traffic
+  description:
+    "Turborepo's per-task cache can be bypassed by an explicit force flag, a `cache: false` config, or missing build-skip configuration. Every commit can rebuild unchanged work; Build Minutes climb with project count.",
+  fix:
+    "Remove `TURBO_FORCE=true` from build env/scripts unless intentional. Set `tasks.build.cache: true` in `turbo.json` (or remove the override), and include generated outputs in Turbo's cache contract. Prefer Vercel's skip-unaffected monorepo behavior when available; use `ignoreCommand` only when that setting cannot cover the project.",
+  citations: [
+    'https://vercel.com/docs/monorepos',
+    'https://vercel.com/docs/builds',
+    'https://turborepo.dev/docs/crafting-your-repository/caching',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**'],
+  includeGlobs: ['turbo.json', '**/turbo.json', 'package.json', '**/package.json', 'vercel.json', '**/vercel.json'],
+};
+
+const FORCE_ENV_RE = /TURBO_FORCE\s*=\s*(?:true|1)\b/;
+const FORCE_FLAG_RE = /\bturbo\s+(?:run\s+)?[a-z:_-]+[^\n&|;]*\s--force\b/;
+
+export function scan({ files }) {
+  const out = [];
+  let hasTurboJson = false;
+  let vercelJsonFile = null;
+  let vercelJsonContent = null;
+
+  for (const { path, content } of files) {
+    const name = path.split('/').pop();
+
+    if (name === 'turbo.json') {
+      hasTurboJson = true;
+      const buildCacheDisabled = detectBuildCacheDisabled(content);
+      if (buildCacheDisabled) {
+        out.push({
+          pattern: metadata.id,
+          file: path,
+          line: buildCacheDisabled.line,
+          evidence: 'turbo.json: tasks.build.cache = false',
+          trafficIndependent: metadata.trafficIndependent,
+          subtype: 'cache-disabled',
+        });
+      }
+      continue;
+    }
+
+    if (name === 'package.json') {
+      const scripts = safeScripts(content);
+      for (const [scriptName, body] of Object.entries(scripts)) {
+        if (FORCE_ENV_RE.test(body) || FORCE_FLAG_RE.test(body)) {
+          const line = lineOfMatch(content, body) ?? 1;
+          out.push({
+            pattern: metadata.id,
+            file: path,
+            line,
+            evidence: `package.json scripts.${scriptName}: ${truncate(body, 80)}`,
+            trafficIndependent: metadata.trafficIndependent,
+            subtype: 'force-flag',
+          });
+        }
+      }
+      continue;
+    }
+
+    if (name === 'vercel.json') {
+      vercelJsonFile = path;
+      vercelJsonContent = content;
+    }
+  }
+
+  // No-ignore-step: repo has turbo.json AND vercel.json lacks an ignoreCommand.
+  // This is an investigation prompt, not proof that the dashboard skip setting is off.
+  if (hasTurboJson && vercelJsonFile && !/"ignoreCommand"\s*:/.test(vercelJsonContent ?? '')) {
+    out.push({
+      pattern: metadata.id,
+      file: vercelJsonFile,
+      line: 1,
+      evidence: 'turbo repo without ignoreCommand in vercel.json; verify Vercel skip-unaffected setting',
+      trafficIndependent: metadata.trafficIndependent,
+      subtype: 'no-ignore-step',
+    });
+  }
+
+  return out;
+}
+
+function detectBuildCacheDisabled(content) {
+  // Tolerate JSONC comments and trailing commas — light scan, not full parse.
+  // Match `"build": { ... "cache": false ... }` within reasonable lookahead.
+  const buildTask = /"build"\s*:\s*\{([\s\S]{0,400}?)\}/.exec(content);
+  if (!buildTask) return null;
+  if (!/"cache"\s*:\s*false/.test(buildTask[1])) return null;
+  const lineNum = content.slice(0, buildTask.index).split('\n').length;
+  return { line: lineNum };
+}
+
+function safeScripts(content) {
+  try {
+    const parsed = JSON.parse(content);
+    return parsed?.scripts && typeof parsed.scripts === 'object' ? parsed.scripts : {};
+  } catch {
+    return {};
+  }
+}
+
+function lineOfMatch(haystack, needle) {
+  const idx = haystack.indexOf(needle);
+  if (idx < 0) return null;
+  return haystack.slice(0, idx).split('\n').length;
+}
+
+function truncate(s, n) {
+  if (typeof s !== 'string') return '';
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/unoptimized-image.mjs b/skills/vercel/vercel-optimize/lib/scanners/unoptimized-image.mjs
new file mode 100644
index 0000000..1f5824d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/unoptimized-image.mjs
@@ -0,0 +1,113 @@
+// Four image-optimization checks emitted as `unoptimized-image` findings.
+// `subtype` distinguishes raw-img / global-unoptimized / image-fill-no-sizes
+// / image-svg-no-unoptimized so the recommender can frame each separately.
+
+export const metadata = {
+  id: 'unoptimized-image',
+  title: 'Image optimization gap (raw <img>, global flag, missing sizes, or SVG mis-routed)',
+  severity: 'high',
+  billingDimension: 'image-optimization',
+  trafficIndependent: false,
+  description:
+    'Four shapes of image-cost waste: raw <img> tags bypass the framework Image component; `images.unoptimized: true` disables Vercel image optimization globally; <Image fill> without `sizes` forces serving the largest source variant; <Image src=".svg"> without `unoptimized` routes vector data through the raster pipeline.',
+  fix:
+    'For raw <img>: switch to next/image, enhanced-img (SvelteKit), <Image /> (Astro), or NuxtImg. For global unoptimized:true: remove the flag unless the project is hosted outside Vercel. For fill without sizes: add `sizes="(max-width: 768px) 100vw, 50vw"` or whatever matches your layout. For SVG: add `unoptimized` so the raw SVG ships instead of rastering it.',
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/components/image',
+    'https://vercel.com/docs/image-optimization',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', 'cypress/**', '*.test.*'],
+  includeGlobs: ['**/*.{tsx,jsx,html,svelte,astro,vue,js,mjs,ts}'],
+};
+
+const IMG_RE = /<img\s+[^>]*src\s*=\s*["'{`]/g;
+const GLOBAL_UNOPT_RE = /images\s*:\s*\{[^}]*\bunoptimized\s*:\s*true/;
+const IMAGE_TAG_RE = /<Image\b[^>]*?\/?>/g;
+const NEXT_IMAGE_IMPORT_RE = /from\s+['"]next\/image['"]/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (isJsxLike(path)) {
+      let m;
+      IMG_RE.lastIndex = 0;
+      while ((m = IMG_RE.exec(content)) !== null) {
+        out.push({
+          pattern: metadata.id,
+          subtype: 'raw-img',
+          file: path,
+          line: lineOf(content, m.index),
+          evidence: snippet(content, m.index),
+          trafficIndependent: metadata.trafficIndependent,
+        });
+      }
+    }
+
+    if (isNextConfig(path)) {
+      const match = GLOBAL_UNOPT_RE.exec(content);
+      if (match) {
+        out.push({
+          pattern: metadata.id,
+          subtype: 'global-unoptimized',
+          file: path,
+          line: lineOf(content, match.index),
+          evidence: 'images: { unoptimized: true } — disables Vercel image optimization for the entire project',
+          // Config-level flag affects every image regardless of route.
+          trafficIndependent: true,
+        });
+      }
+    }
+
+    // Only fire if next/image is imported — otherwise `Image` is some
+    // other component.
+    if (isJsxLike(path) && NEXT_IMAGE_IMPORT_RE.test(content)) {
+      let m;
+      IMAGE_TAG_RE.lastIndex = 0;
+      while ((m = IMAGE_TAG_RE.exec(content)) !== null) {
+        const tag = m[0];
+        const hasFill = /\bfill\b/.test(tag);
+        const hasSizes = /\bsizes\s*=/.test(tag);
+        if (hasFill && !hasSizes) {
+          out.push({
+            pattern: metadata.id,
+            subtype: 'image-fill-no-sizes',
+            file: path,
+            line: lineOf(content, m.index),
+            evidence: tag.slice(0, 200),
+            trafficIndependent: metadata.trafficIndependent,
+          });
+        }
+        // Inline data: URLs never round-trip through the optimizer.
+        const srcMatch = /\bsrc\s*=\s*["']([^"']+)["']/.exec(tag);
+        if (srcMatch) {
+          const src = srcMatch[1];
+          if (/\.svg(\?|$)/i.test(src) && !src.startsWith('data:') && !/\bunoptimized\b/.test(tag)) {
+            out.push({
+              pattern: metadata.id,
+              subtype: 'image-svg-no-unoptimized',
+              file: path,
+              line: lineOf(content, m.index),
+              evidence: tag.slice(0, 200),
+              trafficIndependent: metadata.trafficIndependent,
+            });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+import { lineOf } from '../util.mjs';
+
+function isJsxLike(path) {
+  return /\.(tsx|jsx|html|svelte|astro|vue)$/.test(path);
+}
+function isNextConfig(path) {
+  return /(?:^|\/)next\.config\.(js|mjs|ts|cjs)$/.test(path);
+}
+function snippet(text, idx) {
+  const start = text.lastIndexOf('\n', idx) + 1;
+  const end = text.indexOf('\n', idx);
+  return text.slice(start, end === -1 ? text.length : end).trim().slice(0, 160);
+}
diff --git a/skills/vercel/vercel-optimize/lib/scanners/use-cache-date-stamp.mjs b/skills/vercel/vercel-optimize/lib/scanners/use-cache-date-stamp.mjs
new file mode 100644
index 0000000..69d46aa
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/scanners/use-cache-date-stamp.mjs
@@ -0,0 +1,106 @@
+// Detects time/randomness primitives that destabilize `'use cache'` cache keys,
+// which manifests as ISR write amplification when the cached output embeds a timestamp
+// that changes per request.
+//
+// Triggers when a file contains the `'use cache'` directive AND uses `new Date(`,
+// `Date.now(`, or `Math.random(` outside client-only hooks (useEffect / useCallback /
+// useMemo). Replacing module-scope `new Date().getFullYear()` with a build-time
+// `buildYear` constant, and removing dates passed as `'use cache'` function
+// arguments, prevents repeated writes when the rendered output is otherwise stable.
+
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'use-cache-date-stamp',
+  title: "new Date() / Date.now() / Math.random() inside a 'use cache' file",
+  severity: 'high',
+  billingDimension: 'isr',
+  trafficIndependent: false,
+  description:
+    "`'use cache'` memoizes by argument identity AND prerender output. A timestamp baked into the cached output (`new Date().getFullYear()` in a footer, `Date.now()` in a payload field) forces a fresh ISR write on every regeneration even when the underlying data is unchanged. Random values have the same failure mode.",
+  fix:
+    "Replace module-scope `new Date()` with a build-time constant (`const buildYear = new Date().getFullYear()`) or move per-request timestamps into a client component inside `useEffect`. Do not pass dates as arguments to `'use cache'` functions — they invalidate the cache every call.",
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/directives/use-cache',
+    'https://nextjs.org/docs/app/api-reference/functions/cacheLife',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '**/*.test.*', '**/*.spec.*'],
+  includeGlobs: [
+    '**/page.{ts,tsx,js,jsx}',
+    '**/layout.{ts,tsx,js,jsx}',
+    '**/route.{ts,tsx,js,jsx}',
+    '**/lib/**/*.{ts,tsx,js,jsx}',
+    '**/app/**/*.{ts,tsx,js,jsx}',
+    '**/components/**/*.{ts,tsx,js,jsx}',
+  ],
+};
+
+const USE_CACHE_RE = /^[\t ]*['"]use cache['"]/m;
+const SUSPECT_RE = /\b(new Date\(|Date\.now\(|Math\.random\()/g;
+// Client-only hooks that don't affect server-side cache keys.
+const CLIENT_HOOK_RE = /\b(useEffect|useCallback|useMemo|useLayoutEffect)\s*\(/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!USE_CACHE_RE.test(content)) continue;
+
+    const clientHookRanges = collectRanges(content, CLIENT_HOOK_RE);
+    let match;
+    SUSPECT_RE.lastIndex = 0;
+    while ((match = SUSPECT_RE.exec(content)) !== null) {
+      if (isInsideAnyRange(match.index, clientHookRanges)) continue;
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, match.index),
+        evidence: match[0],
+        trafficIndependent: metadata.trafficIndependent,
+        subtype: classifySubtype(content, match.index),
+      });
+    }
+  }
+  return out;
+}
+
+function collectRanges(content, hookRe) {
+  const ranges = [];
+  hookRe.lastIndex = 0;
+  let m;
+  while ((m = hookRe.exec(content)) !== null) {
+    const open = content.indexOf('(', m.index);
+    if (open < 0) continue;
+    const close = findMatchingParen(content, open);
+    if (close < 0) continue;
+    ranges.push([open, close]);
+  }
+  return ranges;
+}
+
+function findMatchingParen(content, openIdx) {
+  let depth = 0;
+  for (let i = openIdx; i < content.length; i++) {
+    const c = content[i];
+    if (c === '(') depth++;
+    else if (c === ')') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function isInsideAnyRange(idx, ranges) {
+  for (const [a, b] of ranges) {
+    if (idx >= a && idx <= b) return true;
+  }
+  return false;
+}
+
+// `module-scope` if the suspect appears before the first function/class declaration.
+// `in-cache-fn` otherwise (likely inside a render or helper function body).
+function classifySubtype(content, idx) {
+  const head = content.slice(0, idx);
+  if (!/\bfunction\b|\bclass\b|=>\s*\{/.test(head)) return 'module-scope';
+  return 'in-cache-fn';
+}
diff --git a/skills/vercel/vercel-optimize/lib/support-topics.mjs b/skills/vercel/vercel-optimize/lib/support-topics.mjs
new file mode 100644
index 0000000..781bee5
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/support-topics.mjs
@@ -0,0 +1,355 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gates } from './gates/index.mjs';
+import { SCANNER_GATES } from './gates/scanner-driven.mjs';
+import {
+  loadLibrary,
+  lookupSkillRule,
+  lookupUrl,
+  matchesFrameworkVersion,
+} from './citations.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TOPICS_DIR = join(HERE, '..', 'references', 'support-topics');
+
+export const SUPPORT_TOPIC_LIMIT = 3;
+export const SUPPORT_TOPIC_TOTAL_CHAR_LIMIT = 2400;
+const DEFAULT_MAX_BRIEF_CHARS = 900;
+
+export const KNOWN_CANDIDATE_KINDS = new Set([
+  ...gates
+    .map((g) => g.metadata?.id)
+    .filter((id) => id && id !== 'scanner-driven'),
+  ...SCANNER_GATES.map((g) => g.id),
+]);
+
+export async function supportTopicSubset({
+  candidate,
+  signals = {},
+  framework,
+  version,
+  profile,
+  frameworkPlaybookId,
+  maxTopics = SUPPORT_TOPIC_LIMIT,
+  maxChars = SUPPORT_TOPIC_TOTAL_CHAR_LIMIT,
+} = {}) {
+  const stack = signals?.stack ?? signals?.codebase?.stack ?? {};
+  const fw = framework ?? stack.framework ?? 'unknown';
+  const fwVersion = version ?? stack.frameworkVersion ?? 'unknown';
+  const candidates = await loadSupportTopics();
+  const selected = [];
+  let usedChars = 0;
+
+  const sorted = candidates
+    .filter((t) => t.status === 'active')
+    .filter((t) => matchesCandidateKind(t, candidate?.kind))
+    .filter((t) => matchesFrameworks(t.frameworks, fw, fwVersion))
+    .filter((t) => matchesOptionalList(t.profiles, profile))
+    .filter((t) => matchesOptionalList(t.frameworkPlaybooks, frameworkPlaybookId))
+    .filter((t) => matchesRouter(t.routers, stack))
+    .filter((t) => matchesCandidateMetrics(t.metrics, candidate))
+    .filter((t) => matchesCandidateRoutePatterns(t.routePatterns, candidate))
+    .filter((t) => matchesScannerPatterns(t.scannerPatterns, candidate))
+    .sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id));
+
+  for (const topic of sorted) {
+    if (!await topicCitationsApply(topic, candidate?.kind, fw, fwVersion)) continue;
+    if (selected.length >= maxTopics) break;
+    const renderedChars = topic.title.length + topic.body.length + topic.id.length + 20;
+    if (selected.length > 0 && usedChars + renderedChars > maxChars) continue;
+    selected.push(topic);
+    usedChars += renderedChars;
+  }
+
+  return selected;
+}
+
+export async function loadSupportTopics({ includeDraft = false } = {}) {
+  let names = [];
+  try {
+    names = await readdir(TOPICS_DIR);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return [];
+    throw err;
+  }
+
+  const topics = [];
+  for (const name of names.sort()) {
+    if (!name.endsWith('.md') || name === 'README.md') continue;
+    const path = join(TOPICS_DIR, name);
+    const raw = await readFile(path, 'utf-8');
+    const topic = parseSupportTopic(raw, path);
+    if (includeDraft || topic.status === 'active') topics.push(topic);
+  }
+  return topics.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export async function validateSupportTopics() {
+  const topics = await loadSupportTopics({ includeDraft: true });
+  const errors = [];
+  const seen = new Set();
+  for (const topic of topics) {
+    errors.push(...await validateSupportTopic(topic));
+    if (seen.has(topic.id)) errors.push(`${topic.path}: duplicate topic id "${topic.id}"`);
+    seen.add(topic.id);
+  }
+  return { ok: errors.length === 0, errors, topics };
+}
+
+export function renderSupportTopics(topics = []) {
+  if (!Array.isArray(topics) || topics.length === 0) return [];
+  const lines = [];
+  lines.push('## Support topics (investigation guardrails)');
+  lines.push('');
+  lines.push('These are deterministic, candidate-scoped hints selected from `references/support-topics/`. They do not create recommendations. Use them only to decide what evidence to check, what to rule out, and when to abstain.');
+  lines.push('');
+  for (const topic of topics) {
+    lines.push(`### ${topic.title} (\`${topic.id}\`)`);
+    lines.push('');
+    lines.push(topic.body.trim());
+    lines.push('');
+  }
+  return lines;
+}
+
+export function parseSupportTopic(raw, path = '<memory>') {
+  const { frontmatter, body } = splitFrontmatter(raw, path);
+  const metadata = parseFrontmatter(frontmatter, path);
+  return normalizeTopic({ ...metadata, body: body.trim(), path });
+}
+
+function splitFrontmatter(raw, path) {
+  const text = String(raw ?? '');
+  if (!text.startsWith('---\n')) {
+    throw new Error(`${path}: support topic must start with --- frontmatter`);
+  }
+  const end = text.indexOf('\n---\n', 4);
+  if (end === -1) {
+    throw new Error(`${path}: support topic frontmatter must end with ---`);
+  }
+  return {
+    frontmatter: text.slice(4, end),
+    body: text.slice(end + '\n---\n'.length),
+  };
+}
+
+function parseFrontmatter(src, path) {
+  const out = {};
+  for (const rawLine of src.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = line.match(/^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/);
+    if (!m) throw new Error(`${path}: unsupported frontmatter line "${rawLine}"`);
+    const [, key, value] = m;
+    out[key] = parseFrontmatterValue(value, path, key);
+  }
+  return out;
+}
+
+function parseFrontmatterValue(value, path, key) {
+  if (value.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) throw new Error('not an array');
+      return parsed;
+    } catch (err) {
+      throw new Error(`${path}: ${key} must use strict JSON array syntax (${err.message})`);
+    }
+  }
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null') return null;
+  const quoted = value.match(/^"(.*)"$/) ?? value.match(/^'(.*)'$/);
+  return quoted ? quoted[1] : value;
+}
+
+function normalizeTopic(topic) {
+  const maxBriefChars = Number.isFinite(topic.maxBriefChars)
+    ? topic.maxBriefChars
+    : DEFAULT_MAX_BRIEF_CHARS;
+  return {
+    id: topic.id,
+    title: topic.title,
+    status: topic.status,
+    candidateKinds: toStringArray(topic.candidateKinds),
+    frameworks: toStringArray(topic.frameworks),
+    profiles: toStringArray(topic.profiles),
+    frameworkPlaybooks: toStringArray(topic.frameworkPlaybooks),
+    routers: toStringArray(topic.routers),
+    metrics: toStringArray(topic.metrics),
+    routePatterns: toStringArray(topic.routePatterns),
+    scannerPatterns: toStringArray(topic.scannerPatterns),
+    billingDimensions: toStringArray(topic.billingDimensions),
+    citations: toStringArray(topic.citations),
+    priority: Number(topic.priority),
+    maxBriefChars,
+    body: topic.body,
+    path: topic.path,
+  };
+}
+
+async function validateSupportTopic(topic) {
+  const errors = [];
+  const label = topic.path ?? topic.id ?? '<topic>';
+  const fileId = basename(label).replace(/\.md$/, '');
+
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(topic.id ?? '')) {
+    errors.push(`${label}: id must be kebab-case`);
+  }
+  if (fileId !== topic.id) errors.push(`${label}: filename must match id`);
+  if (!nonEmptyString(topic.title)) errors.push(`${label}: title is required`);
+  if (!['active', 'draft', 'deprecated'].includes(topic.status)) {
+    errors.push(`${label}: status must be active, draft, or deprecated`);
+  }
+  if (!Number.isFinite(topic.priority)) errors.push(`${label}: priority must be a number`);
+  if (!Number.isFinite(topic.maxBriefChars) || topic.maxBriefChars < 200 || topic.maxBriefChars > 1400) {
+    errors.push(`${label}: maxBriefChars must be between 200 and 1400`);
+  }
+  if (!nonEmptyArray(topic.candidateKinds)) {
+    errors.push(`${label}: candidateKinds must be a non-empty array`);
+  } else {
+    for (const kind of topic.candidateKinds) {
+      if (kind !== '*' && !KNOWN_CANDIDATE_KINDS.has(kind)) {
+        errors.push(`${label}: unknown candidate kind "${kind}"`);
+      }
+    }
+  }
+  if (!nonEmptyArray(topic.frameworks)) {
+    errors.push(`${label}: frameworks must be a non-empty array`);
+  } else {
+    for (const fw of topic.frameworks) {
+      if (fw !== '*' && !/^[\w-]+@/.test(fw)) {
+        errors.push(`${label}: framework "${fw}" must be "*" or "framework@range"`);
+      }
+    }
+  }
+  if (!nonEmptyArray(topic.citations)) {
+    errors.push(`${label}: citations must be a non-empty array`);
+  } else {
+    for (const citation of topic.citations) {
+      if (!await knownCitation(citation)) {
+        errors.push(`${label}: unknown citation "${citation}"`);
+      }
+    }
+  }
+  for (const pattern of topic.routePatterns) {
+    try {
+      new RegExp(pattern);
+    } catch (err) {
+      errors.push(`${label}: invalid routePatterns regex "${pattern}" (${err.message})`);
+    }
+  }
+  for (const heading of [
+    '## Investigation Brief',
+    '## Evidence To Check',
+    '## Do Not Recommend When',
+    '## Verification',
+  ]) {
+    if (!topic.body.includes(heading)) errors.push(`${label}: missing heading "${heading}"`);
+  }
+  if (topic.body.length > topic.maxBriefChars) {
+    errors.push(`${label}: body length ${topic.body.length} exceeds maxBriefChars ${topic.maxBriefChars}`);
+  }
+  if (/https?:\/\//.test(topic.body)) {
+    errors.push(`${label}: put URLs in frontmatter citations, not body text`);
+  }
+  if (/\/Users\/|(?:^|[\s`"'])apps\/[^/\s`"']+\/|[A-Za-z0-9_-]+\.ts:\d+/.test(topic.body)) {
+    errors.push(`${label}: body leaks internal implementation details`);
+  }
+  return errors;
+}
+
+function matchesCandidateKind(topic, candidateKind) {
+  if (!candidateKind) return false;
+  return topic.candidateKinds.includes('*') || topic.candidateKinds.includes(candidateKind);
+}
+
+function matchesFrameworks(frameworks, framework, version) {
+  return frameworks.some((pattern) =>
+    pattern === '*' || matchesFrameworkVersion(pattern, framework, version)
+  );
+}
+
+function matchesOptionalList(values, actual) {
+  if (!Array.isArray(values) || values.length === 0) return true;
+  return values.includes('*') || (actual != null && values.includes(actual));
+}
+
+function matchesRouter(routers, stack) {
+  if (!Array.isArray(routers) || routers.length === 0) return true;
+  if (routers.includes('*')) return true;
+  return (routers.includes('app') && stack?.hasAppRouter)
+    || (routers.includes('pages') && stack?.hasPagesRouter);
+}
+
+function matchesCandidateMetrics(metrics, candidate) {
+  if (!Array.isArray(metrics) || metrics.length === 0) return true;
+  if (metrics.includes('*')) return true;
+  const observed = new Set([
+    candidate?.evidence?.metric,
+    ...(candidate?.evidence?.issues ?? []).map((i) => i?.metric),
+  ].filter(Boolean).map((m) => String(m).toUpperCase()));
+  return metrics.some((m) => observed.has(String(m).toUpperCase()));
+}
+
+function matchesCandidateRoutePatterns(patterns, candidate) {
+  if (!Array.isArray(patterns) || patterns.length === 0) return true;
+  if (patterns.includes('*')) return true;
+  const route = candidate?.route ?? candidate?.path;
+  if (typeof route !== 'string' || route.length === 0) return false;
+  return patterns.some((p) => new RegExp(p).test(route));
+}
+
+function matchesScannerPatterns(patterns, candidate) {
+  if (!Array.isArray(patterns) || patterns.length === 0) return true;
+  const observed = new Set([
+    ...(candidate?.evidence?.patterns ?? []),
+    ...(candidate?.evidence?.deepDive?.patterns ?? []),
+  ].filter(Boolean));
+  if (observed.size === 0) return false;
+  return patterns.some((p) => observed.has(p));
+}
+
+function topicCitationsApply(topic, candidateKind, framework, version) {
+  if (!candidateKind) return false;
+  return topic.citations.every((citation) =>
+    citationApplies(citation, candidateKind, framework, version)
+  );
+}
+
+async function citationApplies(citation, candidateKind, framework, version) {
+  const lib = await loadLibrary();
+  const rule = lib.ruleSkillRefs.find((r) => `${r.skill}:${r.rule}` === citation);
+  if (rule) {
+    return rule.applicableFrameworks.includes('*')
+      || rule.applicableFrameworks.some((p) => matchesFrameworkVersion(p, framework, version));
+  }
+
+  const url = lib.urls.find((u) => u.url === citation);
+  if (!url) return false;
+  const kindOk = !Array.isArray(url.appliesTo)
+    || url.appliesTo.length === 0
+    || url.appliesTo.includes(candidateKind);
+  const versionOk = url.applicableFrameworks.includes('*')
+    || url.applicableFrameworks.some((p) => matchesFrameworkVersion(p, framework, version));
+  return kindOk && versionOk;
+}
+
+async function knownCitation(citation) {
+  return Boolean(await lookupUrl(citation) || await lookupSkillRule(citation));
+}
+
+function toStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === 'string' && v.length > 0);
+}
+
+function nonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
diff --git a/skills/vercel/vercel-optimize/lib/throttle.mjs b/skills/vercel/vercel-optimize/lib/throttle.mjs
new file mode 100644
index 0000000..9e8d519
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/throttle.mjs
@@ -0,0 +1,273 @@
+// Zero-dependency concurrency + rate-limit primitives for `vercel metrics`. API cap is 100 req / 60s / team.
+// CLI fails fast on 429 and doesn't surface Retry-After, so we back off blind.
+
+const DEFAULT_CONCURRENCY = 8;
+const DEFAULT_MAX_RETRIES = 3;
+// Wait most of a 60s window when rate-limited — we don't know how much headroom remains. Jitter prevents lockstep retry.
+const BASE_BACKOFF_MS = 60_000;
+const JITTER_MS = 15_000;
+// 20% headroom under the 100/60s cap for the user's other concurrent CLI usage.
+const DEFAULT_RATE_LIMIT = 80;
+const DEFAULT_RATE_WINDOW_MS = 60_000;
+const DAILY_OBSERVABILITY_LIMIT_RE = /daily.*observability.*query limit/i;
+
+let dailyQuotaBlock = null;
+
+export function resolveConcurrency() {
+  return parsePositiveIntEnv('VERCEL_OPTIMIZE_METRIC_CONCURRENCY', DEFAULT_CONCURRENCY);
+}
+
+// Format: VERCEL_OPTIMIZE_METRIC_RATE=N or N/60s.
+export function resolveRateLimit() {
+  const env = process.env.VERCEL_OPTIMIZE_METRIC_RATE;
+  if (env == null || env === '') return { maxCalls: DEFAULT_RATE_LIMIT, windowMs: DEFAULT_RATE_WINDOW_MS };
+  const m = String(env).trim().match(/^(\d+)(?:\/(\d+)([sm])?)?$/);
+  if (!m) return { maxCalls: DEFAULT_RATE_LIMIT, windowMs: DEFAULT_RATE_WINDOW_MS };
+  const maxCalls = Number(m[1]);
+  if (!Number.isInteger(maxCalls) || maxCalls < 1) {
+    return { maxCalls: DEFAULT_RATE_LIMIT, windowMs: DEFAULT_RATE_WINDOW_MS };
+  }
+  if (!m[2]) return { maxCalls, windowMs: DEFAULT_RATE_WINDOW_MS };
+  const unit = m[3] === 'm' ? 60_000 : 1_000;
+  const windowMs = Number(m[2]) * unit;
+  return { maxCalls, windowMs };
+}
+
+function parsePositiveIntEnv(name, defaultValue) {
+  const env = process.env[name];
+  if (env == null || env === '') return defaultValue;
+  const n = Number(env);
+  if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) return defaultValue;
+  return n;
+}
+
+// FIFO semaphore. Caller MUST call returned release() exactly once.
+export class SemaphoreAbortError extends Error {
+  constructor(result) {
+    super('Semaphore acquire aborted');
+    this.name = 'SemaphoreAbortError';
+    this.result = result;
+  }
+}
+
+export class Semaphore {
+  constructor(max) {
+    if (!Number.isInteger(max) || max < 1) {
+      throw new Error(`Semaphore: max must be a positive integer (got ${max})`);
+    }
+    this.max = max;
+    this.inFlight = 0;
+    this.waiters = [];
+  }
+
+  async acquire(opts = {}) {
+    const abortIf = opts.abortIf;
+    const preAbort = abortIf?.();
+    if (preAbort) throw new SemaphoreAbortError(preAbort);
+    if (this.inFlight < this.max) {
+      this.inFlight++;
+      return () => this.release();
+    }
+    await new Promise((resolve) => this.waiters.push(resolve));
+    const postAbort = abortIf?.();
+    if (postAbort) {
+      this.wakeNext();
+      throw new SemaphoreAbortError(postAbort);
+    }
+    this.inFlight++;
+    return () => this.release();
+  }
+
+  release() {
+    this.inFlight--;
+    this.wakeNext();
+  }
+
+  wakeNext() {
+    const next = this.waiters.shift();
+    if (next) next();
+  }
+
+  async run(fn, opts = {}) {
+    const release = await this.acquire(opts);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+}
+
+// Load-bearing — semaphore alone is insufficient (8 concurrent × ~1s queries = 480/min, well above the 100/min cap).
+export class SlidingWindowRateLimiter {
+  constructor(maxCalls, windowMs, opts = {}) {
+    if (!Number.isInteger(maxCalls) || maxCalls < 1) {
+      throw new Error(`SlidingWindowRateLimiter: maxCalls must be >=1 (got ${maxCalls})`);
+    }
+    if (!Number.isFinite(windowMs) || windowMs < 1) {
+      throw new Error(`SlidingWindowRateLimiter: windowMs must be >0 (got ${windowMs})`);
+    }
+    this.maxCalls = maxCalls;
+    this.windowMs = windowMs;
+    this.timestamps = []; // ascending order
+    this.now = opts.now ?? (() => Date.now());
+    this.sleep = opts.sleep ?? defaultSleep;
+  }
+
+  async acquire() {
+    while (true) {
+      this.prune();
+      if (this.timestamps.length < this.maxCalls) {
+        this.timestamps.push(this.now());
+        return;
+      }
+      // Small buffer avoids racing the window boundary.
+      const oldestExpiresAt = this.timestamps[0] + this.windowMs;
+      const sleepMs = Math.max(50, oldestExpiresAt - this.now() + 100);
+      await this.sleep(sleepMs);
+    }
+  }
+
+  prune() {
+    const cutoff = this.now() - this.windowMs;
+    while (this.timestamps.length > 0 && this.timestamps[0] < cutoff) {
+      this.timestamps.shift();
+    }
+  }
+}
+
+// Composes Semaphore + RateLimiter: bounds both burst (8 concurrent) and sustained throughput (80/60s).
+let metricThrottleSingleton = null;
+export function getMetricThrottle() {
+  if (!metricThrottleSingleton) {
+    const semaphore = new Semaphore(resolveConcurrency());
+    const { maxCalls, windowMs } = resolveRateLimit();
+    const rateLimiter = new SlidingWindowRateLimiter(maxCalls, windowMs);
+    metricThrottleSingleton = {
+      semaphore,
+      rateLimiter,
+      maxCalls,
+      windowMs,
+      async run(fn) {
+        const cached = getDailyQuotaBlock();
+        if (cached) return dailyQuotaResult(cached);
+        let release;
+        try {
+          release = await semaphore.acquire({ abortIf: () => {
+            const block = getDailyQuotaBlock();
+            return block ? dailyQuotaResult(block) : null;
+          } });
+        } catch (err) {
+          if (err instanceof SemaphoreAbortError) return err.result;
+          throw err;
+        }
+        try {
+          const afterAcquire = getDailyQuotaBlock();
+          if (afterAcquire) return dailyQuotaResult(afterAcquire);
+          await rateLimiter.acquire();
+          const result = await fn();
+          if (isDailyQuotaExceeded(result)) {
+            const block = setDailyQuotaBlocked(result);
+            return dailyQuotaResult(block, result);
+          }
+          return result;
+        } finally {
+          release();
+        }
+      },
+    };
+  }
+  return metricThrottleSingleton;
+}
+
+// Back-compat alias — returns the throttle object (compatible `.run(fn)` shape).
+export const getMetricSemaphore = getMetricThrottle;
+
+export function _resetMetricSemaphoreForTests() {
+  metricThrottleSingleton = null;
+  dailyQuotaBlock = null;
+}
+
+export async function retryOnRateLimit(fn, opts = {}) {
+  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const baseBackoffMs = opts.baseBackoffMs ?? BASE_BACKOFF_MS;
+  const jitterMs = opts.jitterMs ?? JITTER_MS;
+  const sleep = opts.sleep ?? defaultSleep;
+  const onRetry = opts.onRetry;
+
+  let attempt = 0;
+  while (true) {
+    const result = await fn();
+    if (!isRateLimited(result) || attempt >= maxRetries) return result;
+    attempt++;
+    // attempt 1 = 1x, 2 = 1.5x, 3 = 2x of base.
+    const factor = 1 + (attempt - 1) * 0.5;
+    const jitter = jitterMs > 0 ? Math.random() * jitterMs : 0;
+    const delay = Math.round(baseBackoffMs * factor + jitter);
+    if (onRetry) onRetry(attempt, delay, result);
+    await sleep(delay);
+  }
+}
+
+// Variants: code='RATE_LIMITED' (canonical), 'rate_limited', or 'EXIT_1' + stderr match.
+export function isRateLimited(result) {
+  if (!result || result.ok !== false) return false;
+  const code = String(result.code ?? '').toLowerCase();
+  if (code === 'rate_limited' || code === '429') return true;
+  const stderr = String(result.stderr ?? '').toLowerCase();
+  if (stderr.includes('rate limit') || stderr.includes('rate_limited') || stderr.includes('too many requests')) {
+    return true;
+  }
+  return false;
+}
+
+export function isDailyQuotaExceeded(result) {
+  if (!result || result.ok !== false) return false;
+  const code = String(result.code ?? '');
+  if (code.toUpperCase() === 'DAILY_QUOTA_EXCEEDED') return true;
+  const haystack = [
+    result.message,
+    result.stderr,
+    result.stdout,
+    result.detail,
+  ].filter(Boolean).join('\n');
+  return DAILY_OBSERVABILITY_LIMIT_RE.test(haystack);
+}
+
+export function setDailyQuotaBlocked(result, nowMs = Date.now()) {
+  dailyQuotaBlock = {
+    untilMs: utcMidnightAfter(nowMs),
+    originalCode: result?.code ?? null,
+    message: result?.message || result?.stderr || 'Daily Observability query limit reached.',
+  };
+  return dailyQuotaBlock;
+}
+
+export function getDailyQuotaBlock(nowMs = Date.now()) {
+  if (!dailyQuotaBlock) return null;
+  if (dailyQuotaBlock.untilMs <= nowMs) {
+    dailyQuotaBlock = null;
+    return null;
+  }
+  return dailyQuotaBlock;
+}
+
+export function utcMidnightAfter(nowMs) {
+  const d = new Date(nowMs);
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+}
+
+function dailyQuotaResult(block, sourceResult = null) {
+  return {
+    ...(sourceResult && typeof sourceResult === 'object' ? sourceResult : {}),
+    ok: false,
+    code: 'DAILY_QUOTA_EXCEEDED',
+    message: block.message,
+    cachedUntil: new Date(block.untilMs).toISOString(),
+    originalCode: sourceResult?.originalCode ?? sourceResult?.code ?? block.originalCode ?? undefined,
+  };
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
diff --git a/skills/vercel/vercel-optimize/lib/util.mjs b/skills/vercel/vercel-optimize/lib/util.mjs
new file mode 100644
index 0000000..c7031d3
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/util.mjs
@@ -0,0 +1,17 @@
+// Shared scanner + sanitizer helpers. Keep tiny — add only when duplicated 3+ times.
+
+// 1-based line number of `idx` in a multi-line string.
+export function lineOf(text, idx) {
+  return text.slice(0, idx).split('\n').length;
+}
+
+export function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// `slow_route:/api/products` → `/api/products`.
+export function extractRoute(rec) {
+  if (typeof rec?.candidateRef !== 'string') return null;
+  const m = rec.candidateRef.match(/^[^:]+:(.+)$/);
+  return m ? m[1] : null;
+}
diff --git a/skills/vercel/vercel-optimize/lib/vercel.mjs b/skills/vercel/vercel-optimize/lib/vercel.mjs
new file mode 100644
index 0000000..0810c70
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/vercel.mjs
@@ -0,0 +1,864 @@
+// Vercel CLI helpers. All shell-outs use execFile (not exec) — no shell injection. Error detection: exit code + JSON-parse first; stderr grep only as fallback (CLI error strings aren't a stable contract).
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, access } from 'node:fs/promises';
+import { join, win32 } from 'node:path';
+import { getMetricThrottle, isDailyQuotaExceeded, retryOnRateLimit } from './throttle.mjs';
+
+const exec = promisify(execFile);
+
+// On Windows, execFile cannot run the `vercel.cmd` shim directly: PATHEXT is not
+// applied by execFile, and .cmd/.bat require `shell: true` since Node 20 — but a
+// shell would mangle args containing spaces or URL query strings (e.g.
+// `vercel api '/v9/projects/:id?teamId=:org'`, `-f 'http_status ge 500'`). So we
+// resolve the Vercel package's JS entry from PATH and run it via `node` directly:
+// no shell, every arg passed verbatim. POSIX is unchanged (`vercel` on PATH).
+export function resolveVercelCommand({
+  platform = process.platform,
+  env = process.env,
+  execPath = process.execPath,
+  exists = existsSync,
+  readText = (file) => readFileSync(file, 'utf-8'),
+} = {}) {
+  if (platform !== 'win32') return { file: 'vercel', prefix: [] };
+
+  const pathValue = env.PATH || env.Path || env.path || '';
+  for (const dir of pathValue.split(win32.delimiter).filter(Boolean)) {
+    const entry = resolveVercelPackageEntry(dir, exists);
+    if (entry) return { file: execPath, prefix: [entry] };
+
+    const shimEntry = resolveVercelShimEntry(dir, exists, readText);
+    if (shimEntry) return { file: execPath, prefix: [shimEntry] };
+  }
+
+  return { file: execPath, prefix: [], missing: true };
+}
+
+function resolveVercelPackageEntry(dir, exists) {
+  const packageRoots = [
+    win32.join(dir, 'node_modules', 'vercel'),
+    win32.join(win32.dirname(dir), 'vercel'),
+  ];
+  for (const root of packageRoots) {
+    for (const rel of ['dist/vc.js', 'dist/index.js']) {
+      const entry = win32.join(root, rel);
+      if (exists(entry)) return entry;
+    }
+  }
+  return null;
+}
+
+function resolveVercelShimEntry(dir, exists, readText) {
+  for (const bin of ['vercel.cmd', 'vc.cmd']) {
+    const shim = win32.join(dir, bin);
+    if (!exists(shim)) continue;
+    let raw;
+    try {
+      raw = readText(shim);
+    } catch {
+      continue;
+    }
+    const match = raw.match(/["']([^"'\r\n]*vercel[\\/]+dist[\\/]+(?:vc|index)\.js)["']/i);
+    if (!match) continue;
+    const entry = normalizeWindowsShimTarget(match[1], dir);
+    if (exists(entry)) return entry;
+  }
+  return null;
+}
+
+function normalizeWindowsShimTarget(target, dir) {
+  const baseDir = `${dir}${win32.sep}`;
+  const expanded = target
+    .replace(/%~dp0/gi, baseDir)
+    .replace(/%dp0%/gi, baseDir)
+    .replace(/\$basedir/g, dir);
+  return win32.normalize(win32.isAbsolute(expanded) ? expanded : win32.resolve(dir, expanded));
+}
+
+async function runVercel(args, opts = {}) {
+  const command = resolveVercelCommand({ env: opts.env });
+  if (command.missing) {
+    const err = new Error('VERCEL_NOT_INSTALLED: `vercel` CLI not found in PATH. Install with `npm i -g vercel@latest`.');
+    err.code = 'ENOENT';
+    throw err;
+  }
+  return await exec(command.file, [...command.prefix, ...args], { windowsHide: true, ...opts });
+}
+
+const MIN_CLI_VERSION = [53, 0, 0];
+
+// Pre-v53 lacks `vercel metrics` and `vercel contract`.
+export async function checkCliVersion() {
+  let raw;
+  try {
+    const { stdout } = await runVercel(['--version']);
+    raw = stdout.trim();
+  } catch (err) {
+    throw new Error('VERCEL_NOT_INSTALLED: `vercel` CLI not found in PATH. Install with `npm i -g vercel@latest`.');
+  }
+  const m = raw.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!m) throw new Error(`VERCEL_VERSION_UNPARSEABLE: ${raw}`);
+  const v = [Number(m[1]), Number(m[2]), Number(m[3])];
+  for (let i = 0; i < 3; i++) {
+    if (v[i] > MIN_CLI_VERSION[i]) return v;
+    if (v[i] < MIN_CLI_VERSION[i]) {
+      throw new Error(
+        `VERCEL_CLI_TOO_OLD: have ${v.join('.')}, need >= ${MIN_CLI_VERSION.join('.')}. Upgrade with \`npm i -g vercel@latest\`.`
+      );
+    }
+  }
+  return v;
+}
+
+export async function checkAuth() {
+  try {
+    await runVercel(['whoami']);
+  } catch {
+    throw new Error('NOT_AUTH: run `vercel login`.');
+  }
+}
+
+export async function getCliIdentity() {
+  const r = await runVercelJson(['whoami', '--format', 'json']);
+  return r.ok ? r.data : null;
+}
+
+// Supports newer `.vercel/repo.json` (multi-project) + legacy `.vercel/project.json` (single-project).
+export async function readProjectJson(cwd = process.cwd()) {
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'repo.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    const projects = Array.isArray(parsed?.projects) ? parsed.projects.filter((p) => p?.id) : [];
+    if (projects.length > 1) {
+      throw new Error('AMBIGUOUS_PROJECT_LINK: `.vercel/repo.json` contains multiple projects. Run from the linked app directory, or pass the intended projectId together with VERCEL_ORG_ID.');
+    }
+    const first = projects[0];
+    if (first?.id) {
+      return { projectId: first.id, orgId: first.orgId ?? null, source: 'repo.json' };
+    }
+  } catch (err) {
+    if (err?.message?.startsWith('AMBIGUOUS_PROJECT_LINK:')) throw err;
+    /* fall through */
+  }
+
+  // Legacy single-project format.
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'project.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed?.projectId) {
+      return { projectId: parsed.projectId, orgId: parsed.orgId ?? null, source: 'project.json' };
+    }
+  } catch { /* fall through */ }
+
+  return null;
+}
+
+// Does NOT auto-run `vercel link` — interactive surprises bad.
+export async function resolveProjectId(explicit, cwd = process.cwd()) {
+  if (explicit) {
+    const linked = process.env.VERCEL_ORG_ID
+      ? null
+      : await readLinkedOwnerForProjectId(explicit, cwd);
+    return {
+      projectId: explicit,
+      orgId: process.env.VERCEL_ORG_ID || linked?.orgId || null,
+      source: linked?.source ? `arg+${linked.source}` : 'arg',
+    };
+  }
+  if (process.env.VERCEL_PROJECT_ID) {
+    const linked = process.env.VERCEL_ORG_ID
+      ? null
+      : await readLinkedOwnerForProjectId(process.env.VERCEL_PROJECT_ID, cwd);
+    return {
+      projectId: process.env.VERCEL_PROJECT_ID,
+      orgId: process.env.VERCEL_ORG_ID || linked?.orgId || null,
+      source: linked?.source ? `env+${linked.source}` : 'env',
+    };
+  }
+  return await readProjectJson(cwd);
+}
+
+async function readLinkedOwnerForProjectId(projectId, cwd = process.cwd()) {
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'repo.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    const matches = (Array.isArray(parsed?.projects) ? parsed.projects : [])
+      .filter((p) => p?.id && String(p.id) === String(projectId));
+    if (matches.length > 1) {
+      throw new Error('AMBIGUOUS_PROJECT_LINK: `.vercel/repo.json` contains multiple entries for the requested projectId. Ask the user to confirm the intended Vercel team/personal scope.');
+    }
+    const match = matches[0];
+    if (match?.orgId) return { orgId: match.orgId, source: 'repo.json' };
+  } catch (err) {
+    if (err?.message?.startsWith('AMBIGUOUS_PROJECT_LINK:')) throw err;
+    /* fall through */
+  }
+
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'project.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (String(parsed?.projectId ?? '') === String(projectId) && parsed?.orgId) {
+      return { orgId: parsed.orgId, source: 'project.json' };
+    }
+  } catch { /* fall through */ }
+
+  return null;
+}
+
+export async function resolveCommandScope(project = {}) {
+  const orgId = project?.orgId ?? null;
+
+  if (!orgId) {
+    return {
+      ok: false,
+      cliScope: null,
+      source: 'missing-org-scope',
+      required: true,
+      error: 'PROJECT_SCOPE_UNRESOLVED',
+      detail: 'The project was resolved without an owner account, so the collector cannot prove which Vercel scope to query.',
+    };
+  }
+
+  const identity = await getCliIdentity();
+  const currentTeam = identity?.team ?? null;
+
+  if (String(orgId).startsWith('team_')) {
+    if (currentTeam?.id === orgId && currentTeam?.slug) {
+      return {
+        ok: true,
+        cliScope: currentTeam.slug,
+        source: 'whoami-current-team',
+        required: true,
+        teamId: orgId,
+        detail: 'Resolved linked team ID to the current CLI team slug.',
+      };
+    }
+
+    const team = await getTeamInfo(orgId);
+    if (team.ok && team.slug) {
+      return {
+        ok: true,
+        cliScope: team.slug,
+        source: 'team-api',
+        required: true,
+        teamId: orgId,
+        detail: 'Resolved linked team ID to a Vercel CLI scope slug.',
+      };
+    }
+
+    return {
+      ok: false,
+      cliScope: null,
+      source: 'team-api',
+      required: true,
+      teamId: orgId,
+      error: team.error ?? 'TEAM_SCOPE_UNRESOLVED',
+      detail: 'Could not resolve the linked team ID to a Vercel CLI scope slug.',
+    };
+  }
+
+  if (String(orgId).startsWith('usr_')) {
+    const user = identity?.user ?? identity ?? {};
+    const userId = user.id ?? identity?.id ?? null;
+    const username = user.username ?? identity?.username ?? null;
+    if ((!userId || userId === orgId) && username) {
+      return {
+        ok: true,
+        cliScope: username,
+        source: 'whoami-user',
+        required: true,
+        userId: orgId,
+        detail: 'Resolved linked user ID to a Vercel CLI username scope.',
+      };
+    }
+    return {
+      ok: false,
+      cliScope: null,
+      source: 'whoami-user',
+      required: true,
+      userId: orgId,
+      error: 'USER_SCOPE_UNRESOLVED',
+      detail: 'Could not resolve the linked user ID to the authenticated Vercel username.',
+    };
+  }
+
+  return {
+    ok: true,
+    cliScope: orgId,
+    source: 'linked-org-scope',
+    required: true,
+    detail: 'Using the linked org value as the Vercel CLI scope.',
+  };
+}
+
+async function getTeamInfo(teamIdOrSlug) {
+  const r = await runVercelJson(['api', `/v2/teams/${encodeURIComponent(teamIdOrSlug)}`]);
+  if (!r.ok) return { ok: false, error: r.code ?? 'UNKNOWN' };
+  const team = r.data?.team ?? r.data ?? {};
+  return {
+    ok: true,
+    id: team.id ?? null,
+    slug: team.slug ?? null,
+    name: team.name ?? null,
+  };
+}
+
+// Some commands emit `{error: {...}}` on stdout AND exit non-zero — parse stdout first; embedded `error` is the most reliable signal.
+// 32 MiB buffer: 14d function-duration timeseries across many routes exceeds Node's 1 MiB default.
+export async function runVercelJson(args, opts = {}) {
+  let stdout = '';
+  let stderr = '';
+  let exitCode = 0;
+  try {
+    const r = await runVercel(args, { maxBuffer: 32 * 1024 * 1024, ...opts });
+    stdout = r.stdout;
+    stderr = r.stderr;
+  } catch (err) {
+    stdout = err.stdout || '';
+    stderr = err.stderr || '';
+    exitCode = err.code ?? err.exitCode ?? 1;
+  }
+  const safeStderr = redactSensitiveText(stderr);
+
+  if (stdout && stdout.trim().startsWith('{')) {
+    try {
+      const data = JSON.parse(stdout);
+      if (data && typeof data === 'object' && data.error) {
+        const failure = {
+          ok: false,
+          code: data.error.code || `EXIT_${exitCode}`,
+          message: redactSensitiveText(data.error.message || ''),
+          allowedValues: data.error.allowedValues,
+          stderr: safeStderr,
+        };
+        return isDailyQuotaExceeded(failure)
+          ? { ...failure, code: 'DAILY_QUOTA_EXCEEDED', originalCode: failure.code }
+          : failure;
+      }
+      if (exitCode === 0) return { ok: true, data };
+      // Exit non-zero, no `error` key, parseable stdout → still useful.
+      return { ok: true, data };
+    } catch {
+      /* fall through to stderr categorization */
+    }
+  }
+
+  // Metrics schema returns a top-level array.
+  if (stdout && stdout.trim().startsWith('[')) {
+    try {
+      const data = JSON.parse(stdout);
+      if (exitCode === 0) return { ok: true, data };
+    } catch { /* fall through */ }
+  }
+
+  return {
+    ok: false,
+    code: categorizeError(exitCode, stderr),
+    stderr: safeStderr,
+  };
+}
+
+export function redactSensitiveText(value) {
+  return String(value ?? '')
+    .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]{12,}/gi, '$1 [REDACTED]')
+    .replace(/\b(Authorization:\s*)[^\r\n]+/gi, '$1[REDACTED]')
+    .replace(/\b(x-vercel-id:\s*)[^\r\n]+/gi, '$1[REDACTED]')
+    .replace(/\b(VERCEL_TOKEN|TURBO_TOKEN|NPM_TOKEN|NODE_AUTH_TOKEN|GITHUB_TOKEN)=("[^"]+"|'[^']+'|[^\s"'`]+)/g, '$1=[REDACTED]')
+    .replace(/(--token(?:=|\s+))("[^"]+"|'[^']+'|[^\s"'`]+)/gi, '$1[REDACTED]')
+    .replace(/\b(prj|team|usr)_[A-Za-z0-9]{8,}\b/g, '$1_[REDACTED]')
+    .replace(/("token"\s*:\s*")[^"]{8,}(")/gi, '$1[REDACTED]$2');
+}
+
+// CLI doesn't emit machine-readable error codes for these states — stderr substring is fallback only.
+function categorizeError(exitCode, stderr) {
+  const lc = (stderr || '').toLowerCase();
+  if (isDailyQuotaExceeded({ ok: false, stderr })) return 'DAILY_QUOTA_EXCEEDED';
+  if (lc.includes('observability plus')) return 'OPLUS_REQUIRED';
+  if (lc.includes('costs not found')) return 'USAGE_UNAVAILABLE';
+  if (lc.includes('project not found')) return 'PROJECT_NOT_FOUND';
+  if (lc.includes('not linked') || lc.includes('no project')) return 'NOT_LINKED';
+  if (lc.includes('log in') || lc.includes('credentials')) return 'NOT_AUTH';
+  if (lc.includes('rate limit') || lc.includes('429')) return 'RATE_LIMIT';
+  if (lc.includes('permission') || lc.includes('not authorized') || lc.includes('403'))
+    return 'FORBIDDEN';
+  return `EXIT_${exitCode}`;
+}
+
+// Schema is global per team — pass scope so we hit the right team rather than user's currentTeam.
+export async function hasObservabilityPlus(scope) {
+  const r = await runVercelJson(scopedArgs(['metrics', 'schema', '--format', 'json'], scope));
+  return r.ok;
+}
+
+export async function getMetricsSchema(scope) {
+  const r = await runVercelJson(scopedArgs(['metrics', 'schema', '--format', 'json'], scope));
+  return r.ok ? r.data : null;
+}
+
+export async function checkObservabilityPlusConfiguration({ orgId, projectId } = {}) {
+  if (!orgId) {
+    return {
+      ok: false,
+      source: 'observability-configuration-api',
+      blocker: 'unknown',
+      detail: 'No team ID was available for the Observability Plus configuration preflight.',
+    };
+  }
+  if (String(orgId).startsWith('usr_')) {
+    return {
+      ok: false,
+      source: 'observability-configuration-api',
+      access: null,
+      blocker: 'unknown',
+      detail: 'The Observability Plus team configuration preflight is not available for a user-owned project; falling back to the scoped metrics probe.',
+    };
+  }
+  const qs = `?teamId=${encodeURIComponent(orgId)}`;
+  const r = await runVercelJson(['api', `/v1/observability/manage/configuration/projects${qs}`]);
+  return classifyObservabilityPlusConfiguration(r, { projectId });
+}
+
+export function classifyObservabilityPlusConfiguration(result, { projectId } = {}) {
+  const source = 'observability-configuration-api';
+  if (result?.ok) {
+    const disabledProjects = Array.isArray(result.data?.disabledProjects) ? result.data.disabledProjects : [];
+    const disabled = projectId
+      ? disabledProjects.find((p) => String(p?.id ?? '') === String(projectId))
+      : null;
+    if (disabled) {
+      return {
+        ok: true,
+        source,
+        access: false,
+        blocker: 'project_disabled',
+        detail: 'Observability Plus is enabled for the team but disabled for this project.',
+        disabledProject: {
+          id: disabled.id,
+          name: disabled.name ?? null,
+          disabledAt: disabled.disabledAt ?? null,
+        },
+      };
+    }
+    return {
+      ok: true,
+      source,
+      access: true,
+      blocker: null,
+      detail: 'Observability Plus is enabled for this team/project.',
+    };
+  }
+
+  const code = String(result?.code ?? 'unknown').toLowerCase();
+  const text = `${result?.message ?? ''}\n${result?.stderr ?? ''}`.toLowerCase();
+  const mentionsObservabilityPlusNotEnabled =
+    /observability plus[\s\S]{0,160}not enabled/.test(text) ||
+    /not enabled[\s\S]{0,160}observability plus/.test(text) ||
+    /subscription to observability plus[\s\S]{0,160}required/.test(text);
+  if (code === 'oplus_required' || ((code === 'not_found' || code === '404') && mentionsObservabilityPlusNotEnabled)) {
+    return {
+      ok: true,
+      source,
+      access: false,
+      blocker: 'no_oplus_probe',
+      detail: 'Route-level metrics are unavailable because Observability Plus is not enabled for this team.',
+    };
+  }
+  if (/forbidden|not_authorized|403/.test(code) || /forbidden|not authorized|permission|403/.test(text)) {
+    return {
+      ok: false,
+      source,
+      access: null,
+      blocker: 'forbidden',
+      detail: 'Could not read Observability Plus configuration for this team. Run `vercel switch <team>` and verify access.',
+    };
+  }
+  if (/not_auth|unauthorized|401/.test(code) || /unauthorized|log in|credentials|401/.test(text)) {
+    return {
+      ok: false,
+      source,
+      access: null,
+      blocker: 'forbidden',
+      detail: 'Could not read Observability Plus configuration because the Vercel CLI is not authenticated.',
+    };
+  }
+  return {
+    ok: false,
+    source,
+    access: null,
+    blocker: 'unknown',
+    detail: `Could not determine Observability Plus configuration before querying metrics (code=${code}).`,
+  };
+}
+
+// Returns `{ok, ...}`. CLI summary defaults to top 10 groups under --group-by; widen via opts.limit.
+export async function queryMetric(metricId, opts = {}) {
+  const args = ['metrics', metricId, '--format', 'json'];
+  if (opts.aggregation) args.push('-a', opts.aggregation);
+  for (const dim of opts.groupBy ?? []) args.push('--group-by', dim);
+  if (opts.filter) args.push('-f', opts.filter);
+  if (opts.since) args.push('--since', opts.since);
+  if (opts.until) args.push('--until', opts.until);
+  if (opts.limit) args.push('--limit', String(opts.limit));
+
+  // 3-layer protection: semaphore (8 concurrent) + sliding-window (80/60s) + retryOnRateLimit (3× 60-90s jitter). payment_required is terminal.
+  const throttle = getMetricThrottle();
+  const onRetry = (attempt, delayMs) => {
+    console.error(`[queryMetric] ${metricId} hit RATE_LIMITED; retry ${attempt}/3 after ${(delayMs / 1000).toFixed(0)}s`);
+  };
+  return await throttle.run(() =>
+    retryOnRateLimit(() => runVercelJson(scopedArgs(args, opts.scope)), { onRetry })
+  );
+}
+
+// Team-owned projects need `?teamId=<orgId>` to avoid current-team drift. User-
+// owned projects use the authenticated user context and should not pass teamId.
+export async function getProjectConfig(projectId, orgId) {
+  const qs = orgId && !String(orgId).startsWith('usr_')
+    ? `?teamId=${encodeURIComponent(orgId)}`
+    : '';
+  const r = await runVercelJson(['api', `/v9/projects/${projectId}${qs}`]);
+  return r.ok ? r.data : { error: r.code, stderr: r.stderr };
+}
+
+// USAGE_UNAVAILABLE distinguishes "no Costs feature" from genuine emptiness.
+export async function getUsage({ days = 14, scope, groupByProject = true } = {}) {
+  const toDate = new Date();
+  const fromDate = new Date(toDate.getTime() - days * 86400000);
+  const fmt = (d) => d.toISOString().slice(0, 10);
+  const args = [
+    'usage',
+    '--format', 'json',
+    '--from', fmt(fromDate),
+    '--to', fmt(toDate),
+  ];
+  // The CLI rejects --breakdown with --group-by. Project grouping is higher
+  // value for this skill because every recommendation must be project-scoped.
+  if (groupByProject) args.push('--group-by', 'project');
+  else args.push('--breakdown', 'daily');
+  return await runVercelJson(scopedArgs(args, scope));
+}
+
+// CLI `--group-by project` returns project buckets under groupBy.data. Older
+// breakdown-shaped fixtures tag service rows with projectId; keep both paths.
+export function filterUsageByProject(usage, projectId, projectName = null) {
+  if (!usage || !projectId) return { filtered: null, matched: false, unattributedTotal: 0 };
+  if (usage.groupBy?.dimension === 'project' && Array.isArray(usage.groupBy.data)) {
+    const project = usage.groupBy.data.find((entry) => projectMatches(entry, projectId, projectName));
+    if (!project) return { filtered: null, matched: false, unattributedTotal: 0 };
+    return {
+      filtered: {
+        ...usage,
+        groupBy: { ...usage.groupBy, data: [project] },
+        services: Array.isArray(project.services) ? project.services : [],
+        totals: project.totals ?? null,
+        project: { name: project.name ?? projectName ?? null, projectId: project.projectId ?? projectId },
+      },
+      matched: true,
+      unattributedTotal: 0,
+    };
+  }
+  const breakdown = usage.breakdown;
+  if (!breakdown || !Array.isArray(breakdown.data)) {
+    return { filtered: null, matched: false, unattributedTotal: 0 };
+  }
+  const out = {
+    ...usage,
+    breakdown: { ...breakdown, data: [] },
+  };
+  let matchedAny = false;
+  let projectTotal = 0;
+  let unattributedTotal = 0;
+
+  for (const day of breakdown.data) {
+    const services = Array.isArray(day.services) ? day.services : [];
+    const projectRows = services.filter((s) => projectMatches(s, projectId, projectName));
+    const unattributedRows = services.filter((s) => !s.projectId && !s.project);
+    for (const r of projectRows) projectTotal += (r.billedCost ?? r.cost ?? 0);
+    for (const r of unattributedRows) unattributedTotal += (r.billedCost ?? r.cost ?? 0);
+    if (projectRows.length === 0) continue;
+    matchedAny = true;
+    out.breakdown.data.push({ ...day, services: projectRows });
+  }
+
+  if (!matchedAny) return { filtered: null, matched: false, unattributedTotal };
+
+  out.services = aggregateServicesByName(out.breakdown.data);
+  out.totals = { billedCost: projectTotal };
+  return { filtered: out, matched: true, unattributedTotal };
+}
+
+function projectMatches(serviceRow, projectId, projectName = null) {
+  if (!serviceRow) return false;
+  if (serviceRow.projectId === projectId) return true;
+  if (projectName && serviceRow.name === projectName) return true;
+  if (projectName && serviceRow.project === projectName) return true;
+  if (serviceRow.project === projectId) return true;
+  if (serviceRow.project && (serviceRow.project.id === projectId || serviceRow.project.projectId === projectId || serviceRow.project.name === projectName)) return true;
+  return false;
+}
+
+function aggregateServicesByName(days) {
+  const byName = new Map();
+  for (const day of days) {
+    for (const s of (day.services ?? [])) {
+      const key = s.name ?? '(unnamed)';
+      const prev = byName.get(key) ?? { name: key, billedCost: 0, pricingQuantity: 0, pricingUnit: s.pricingUnit ?? null };
+      prev.billedCost += (s.billedCost ?? s.cost ?? 0);
+      prev.pricingQuantity += (s.pricingQuantity ?? 0);
+      byName.set(key, prev);
+    }
+  }
+  return Array.from(byName.values()).sort((a, b) => (b.billedCost ?? 0) - (a.billedCost ?? 0));
+}
+
+export async function getContract(scope) {
+  const r = await runVercelJson(scopedArgs(['contract', '--format', 'json'], scope));
+  return r.ok ? r.data : null;
+}
+
+export async function getAccountPlan(scope) {
+  const currentTeamId = scope ? null : await getCurrentTeamId();
+  const teamScope = scope || currentTeamId;
+
+  if (teamScope && !String(teamScope).startsWith('usr_')) {
+    const team = await getBillingPlanFromPath(`/v2/teams/${encodeURIComponent(teamScope)}`, 'team.billing.plan');
+    if (team.plan !== 'unknown' || !/not_found|404/i.test(String(team.error ?? ''))) {
+      return team;
+    }
+    // Older project links can carry a user/org id instead of a team id. If the
+    // team lookup misses, fall back to the authenticated user's billing record.
+  }
+
+  return await getBillingPlanFromPath('/v2/user', 'user.billing.plan');
+}
+
+async function getCurrentTeamId() {
+  const identity = await getCliIdentity();
+  return identity?.team?.id ?? null;
+}
+
+async function getBillingPlanFromPath(path, source) {
+  const r = await runVercelJson(['api', path]);
+  if (!r.ok) {
+    return {
+      plan: 'unknown',
+      reason: `${source} unavailable (${r.code ?? 'unknown'})`,
+      source,
+      error: r.code ?? 'unknown',
+    };
+  }
+
+  const parsed = extractBillingPlan(r.data);
+  if (!parsed) {
+    return {
+      plan: 'unknown',
+      reason: `${source} missing from Vercel API response`,
+      source,
+    };
+  }
+
+  return {
+    ...parsed,
+    reason: `${source}=${parsed.plan}`,
+    source,
+  };
+}
+
+export function extractBillingPlan(data) {
+  const raw =
+    data?.billing?.plan ??
+    data?.team?.billing?.plan ??
+    data?.user?.billing?.plan ??
+    null;
+  const plan = normalizeBillingPlan(raw);
+  return plan ? { plan, rawPlan: raw } : null;
+}
+
+function normalizeBillingPlan(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (value === 'hobby' || value === 'pro' || value === 'enterprise') return value;
+  return null;
+}
+
+// Primary source: billing.plan from `/v2/teams/:team` or `/v2/user`.
+// Fallbacks: contract category, then recent billed usage for legacy CLI/API gaps.
+export function inferPlan(contract, opts = {}) {
+  const accountPlan = extractPlanOption(opts?.accountPlan);
+  if (accountPlan) {
+    return {
+      plan: accountPlan.plan,
+      reason: accountPlan.reason ?? `${accountPlan.source ?? 'billing.plan'}=${accountPlan.plan}`,
+    };
+  }
+
+  const commits = contract?.commitments ?? [];
+
+  if (commits.length > 0) {
+    const c0 = commits[0] ?? {};
+    // category field names are tentative — try several.
+    const category = c0.category ?? c0.commitmentCategory ?? c0.type ?? null;
+    if (category === 'Spend' || category === 'spend') {
+      return { plan: 'pro', reason: `commitment category=${category}` };
+    }
+    if (category === 'Usage' || category === 'usage') {
+      return { plan: 'enterprise', reason: `commitment category=${category}` };
+    }
+    return { plan: 'uncertain', reason: `unknown commitment category=${category}` };
+  }
+
+  const totalCost = opts?.usageTotalCost;
+  if (typeof totalCost === 'number' && totalCost > 0) {
+    return {
+      plan: 'pro',
+      reason: `commitments=[] but usage=$${totalCost.toFixed(2)}/window — Pro pay-as-you-go (Hobby teams don't bill)`,
+    };
+  }
+
+  return {
+    plan: 'uncertain',
+    reason: typeof totalCost === 'number' && totalCost === 0
+      ? 'no commitments and no billed usage in window (could be Hobby, or Pro with no recent billing)'
+      : 'no commitments on contract; usage unavailable',
+  };
+}
+
+function extractPlanOption(accountPlan) {
+  if (!accountPlan) return null;
+  if (typeof accountPlan === 'string') {
+    const plan = normalizeBillingPlan(accountPlan);
+    return plan ? { plan, reason: `billing.plan=${plan}` } : null;
+  }
+
+  const plan = normalizeBillingPlan(accountPlan.plan);
+  if (!plan) return null;
+  return {
+    plan,
+    reason: accountPlan.reason ?? (
+      accountPlan.source
+        ? `${accountPlan.source}=${plan}`
+        : `billing.plan=${plan}`
+    ),
+    source: accountPlan.source ?? null,
+  };
+}
+
+export async function detectStack(cwd = process.cwd()) {
+  const pkgPath = join(cwd, 'package.json');
+  let pkg = {};
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+  } catch {
+    return baselineStack();
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  const framework =
+    deps.next ? 'next' :
+    deps.nuxt ? 'nuxt' :
+    deps.astro ? 'astro' :
+    deps['@sveltejs/kit'] ? 'sveltekit' :
+    deps['@remix-run/react'] ? 'remix' :
+    deps.hono ? 'hono' :
+    'unknown';
+
+  const frameworkVersion = (() => {
+    const m = { next: 'next', nuxt: 'nuxt', astro: 'astro', sveltekit: '@sveltejs/kit', remix: '@remix-run/react', hono: 'hono' };
+    const dep = m[framework];
+    if (!dep) return null;
+    return (deps[dep] || '').replace(/^[\^~]/, '') || null;
+  })();
+
+  const hasAppRouter = await pathExists(join(cwd, 'app')) || await pathExists(join(cwd, 'src/app'));
+  const hasPagesRouter = await pathExists(join(cwd, 'pages')) || await pathExists(join(cwd, 'src/pages'));
+  const typescript = await pathExists(join(cwd, 'tsconfig.json'));
+  const cacheComponents = framework === 'next'
+    ? await detectNextCacheComponents(cwd)
+    : null;
+
+  const orm =
+    deps.prisma || deps['@prisma/client'] ? 'prisma' :
+    deps['drizzle-orm'] ? 'drizzle' :
+    deps.kysely ? 'kysely' :
+    'none';
+  const vercelFlagsPackages = [
+    '@vercel/flags',
+    '@vercel/flags/next',
+    '@vercel/flags/sveltekit',
+    '@vercel/flags/nuxt',
+  ].filter((name) => deps[name]);
+  const workflowPackages = Object.keys(deps)
+    .filter((name) => name === 'workflow' || name.startsWith('@workflow/'))
+    .sort();
+
+  const isMonorepo =
+    !!pkg.workspaces ||
+    await pathExists(join(cwd, 'pnpm-workspace.yaml')) ||
+    await pathExists(join(cwd, 'lerna.json'));
+
+  return {
+    framework,
+    frameworkVersion,
+    hasAppRouter,
+    hasPagesRouter,
+    cacheComponents,
+    typescript,
+    orm,
+    isMonorepo,
+    rootDirectory: null,
+    hasVercelFlagsPackage: vercelFlagsPackages.length > 0,
+    vercelFlagsPackages,
+    hasWorkflowPackage: workflowPackages.length > 0,
+    workflowPackages,
+  };
+}
+
+function baselineStack() {
+  return {
+    framework: 'unknown', frameworkVersion: null,
+    hasAppRouter: false, hasPagesRouter: false, cacheComponents: null, typescript: false,
+    orm: 'none', isMonorepo: false, rootDirectory: null,
+    hasVercelFlagsPackage: false, vercelFlagsPackages: [],
+    hasWorkflowPackage: false, workflowPackages: [],
+  };
+}
+
+async function detectNextCacheComponents(cwd) {
+  for (const name of ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs']) {
+    try {
+      const content = await readFile(join(cwd, name), 'utf-8');
+      if (/\bcacheComponents\s*:\s*true\b/.test(content)) return true;
+      if (/\bcacheComponents\s*:\s*false\b/.test(content)) return false;
+    } catch {}
+  }
+  return null;
+}
+
+async function pathExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+// `--scope <teamId>` is buggy on several subcommands (silently falls back to
+// currentTeam). Resolve raw account IDs to slugs/usernames before scoped calls.
+function scopedArgs(args, scope) {
+  if (!scope) return args;
+  if (typeof scope === 'string' && /^(team|usr)_/.test(scope)) {
+    throw new Error('RAW_ID_SCOPE_UNRESOLVED: resolve the linked org/user ID to a CLI scope slug before running Vercel commands.');
+  }
+  return [...args, '--scope', scope];
+}
+
+// CLI summary field is `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).
+export function normalizeSummary(metricResponse, metricId, aggregation, groupBy = []) {
+  if (!metricResponse || metricResponse.error) return [];
+  const field = `${metricId.replace(/\./g, '_')}_${aggregation}`;
+  const rows = Array.isArray(metricResponse.summary) ? metricResponse.summary : [];
+  return rows.map((row) => {
+    const out = { value: row[field] ?? null };
+    for (const dim of groupBy) {
+      if (row[dim] !== undefined) out[dim] = row[dim];
+    }
+    return out;
+  });
+}
diff --git a/skills/vercel/vercel-optimize/lib/verify-claim.mjs b/skills/vercel/vercel-optimize/lib/verify-claim.mjs
new file mode 100644
index 0000000..b8e68a9
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/verify-claim.mjs
@@ -0,0 +1,1296 @@
+// Pure async claim verifier. No LLM, no network — fs + grep only.
+
+import { readFile, access, readdir } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { dirname, isAbsolute, join, normalize } from 'node:path';
+import { promisify } from 'node:util';
+import { isKnownUrl, sanitizeCitations } from './citations.mjs';
+import { findRecContradictions } from './project-facts.mjs';
+import { canonicalizeRoute } from './route-normalize.mjs';
+
+const execFileP = promisify(execFile);
+const cacheInvalidationFileCache = new Map();
+
+// Bad inputs surface as `unsupported` — never throws.
+export async function verifyClaim(claim) {
+  if (!claim || typeof claim !== 'object') {
+    return { disposition: 'unverifiable', reason: 'claim is not an object' };
+  }
+  switch (claim.type) {
+    case 'file_exists':                  return verifyFileExists(claim);
+    case 'pattern_count':                return verifyPatternCount(claim);
+    case 'pattern_exists':               return verifyPatternExists(claim);
+    case 'pattern_absent':               return verifyPatternAbsent(claim);
+    case 'code_snippet':                 return verifyCodeSnippet(claim);
+    case 'repo_count':                   return verifyRepoCount(claim);
+    case 'citation_in_library':          return verifyCitationInLibrary(claim);
+    case 'citation_applies_to_version':  return verifyCitationAppliesToVersion(claim);
+    case 'cache_vary_matches_dynamic_inputs': return verifyCacheVaryMatchesDynamicInputs(claim);
+    case 'cache_vary_cardinality_safe': return verifyCacheVaryCardinalitySafe(claim);
+    case 'next_cached_not_found_causal_support': return verifyNextCachedNotFoundCausalSupport(claim);
+    case 'next_stable_cache_api_for_version': return verifyNextStableCacheApiForVersion(claim);
+    case 'next_runtime_cache_api_for_version': return verifyNextRuntimeCacheApiForVersion(claim);
+    case 'next_cache_components_runtime_cache_preference': return verifyNextCacheComponentsRuntimeCachePreference(claim);
+    case 'next_cache_life_single_execution': return verifyNextCacheLifeSingleExecution(claim);
+    case 'next_cache_lifetime_freshness_supported': return verifyNextCacheLifetimeFreshnessSupported(claim);
+    case 'next_cache_components_route_chain_file': return verifyNextCacheComponentsRouteChainFile(claim);
+    case 'next_cache_life_cdn_header_semantics': return verifyNextCacheLifeCdnHeaderSemantics(claim);
+    case 'image_response_headers_citation': return verifyImageResponseHeadersCitation(claim);
+    case 'next_image_priority_api_for_version': return verifyNextImagePriorityApiForVersion(claim);
+    case 'next_cache_components_route_segment_config': return verifyNextCacheComponentsRouteSegmentConfig(claim);
+    case 'next_route_revalidate_static_prereq': return verifyNextRouteRevalidateStaticPrereq(claim);
+    case 'next_cache_tag_invalidation_supported': return verifyNextCacheTagInvalidationSupported(claim);
+    case 'cache_rec_not_error_dominated_or_acknowledged': return verifyCacheRecNotErrorDominatedOrAcknowledged(claim);
+    case 'cache_control_header_syntax': return verifyCacheControlHeaderSyntax(claim);
+    case 'cache_control_headers_citation': return verifyCacheControlHeadersCitation(claim);
+    case 'cache_policy_positive_or_no_ready_rec': return verifyCachePolicyPositiveOrNoReadyRec(claim);
+    case 'cache_404_long_ttl_safety': return verifyCache404LongTtlSafety(claim);
+    case 'route_error_not_found_status_and_scope': return verifyRouteErrorNotFoundStatusAndScope(claim);
+    case 'immutable_dynamic_route_safety': return verifyImmutableDynamicRouteSafety(claim);
+    case 'auth_guard_parallelization_safety': return verifyAuthGuardParallelizationSafety(claim);
+    case 'parallelization_impact_not_overclaimed': return verifyParallelizationImpactNotOverclaimed(claim);
+    case 'parallelization_not_cpu_bound_work': return verifyParallelizationNotCpuBoundWork(claim);
+    case 'runtime_error_cause_supported': return verifyRuntimeErrorCauseSupported(claim);
+    case 'vercel_ignore_command_project_state': return verifyVercelIgnoreCommandProjectState(claim);
+    case 'turbo_build_cache_safety': return verifyTurboBuildCacheSafety(claim);
+    case 'does_not_contradict_project_config': return verifyNoProjectConfigContradiction(claim);
+    default:
+      return { disposition: 'unverifiable', reason: `unknown claim type: ${claim.type}` };
+  }
+}
+
+// Catches "enable fluid compute" recs that the brief negative-space filter let through.
+async function verifyNoProjectConfigContradiction({ rec, projectFacts }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'no rec attached to claim' };
+  if (!Array.isArray(projectFacts) || projectFacts.length === 0) {
+    return { disposition: 'unverifiable', reason: 'no project facts available' };
+  }
+  const hits = findRecContradictions(rec, projectFacts);
+  if (hits.length === 0) {
+    return { disposition: 'verified', reason: 'rec does not contradict any already-on project setting' };
+  }
+  const ids = hits.map((h) => h.id).join(', ');
+  return {
+    disposition: 'failed',
+    reason: `rec contradicts project config: recommends toggling on already-enabled ${ids}`,
+  };
+}
+
+async function verifyFileExists(claim) {
+  const { file } = claim;
+  if (!file) return { disposition: 'unsupported', reason: 'file_exists requires file' };
+  try {
+    await firstAccessiblePath(claim);
+    return { disposition: 'verified', reason: `${file} exists` };
+  } catch {
+    return { disposition: 'failed', reason: `${file} does not exist` };
+  }
+}
+
+async function verifyPatternCount(claim) {
+  const { file, pattern, expected } = claim;
+  if (!file || !pattern) return { disposition: 'unsupported', reason: 'pattern_count requires file + pattern' };
+  let content;
+  try { ({ content } = await readClaimFile(claim)); }
+  catch { return { disposition: 'failed', reason: `cannot read ${file}` }; }
+
+  // "42" alone (from `filename:42`) is a line number, not a pattern.
+  if (/^\d+$/.test(pattern.trim())) {
+    return { disposition: 'unsupported', reason: 'pattern looks like a line number, not a pattern' };
+  }
+
+  const re = compilePattern(pattern, 'g');
+  const matches = content.match(re) ?? [];
+  const actual = matches.length;
+  return actual === expected
+    ? { disposition: 'verified', actual, expected, reason: 'exact count match' }
+    : { disposition: 'failed', actual, expected, reason: `count mismatch: claim=${expected}, actual=${actual}` };
+}
+
+async function verifyPatternExists(claim) {
+  const { file, pattern } = claim;
+  if (!file || !pattern) return { disposition: 'unsupported', reason: 'pattern_exists requires file + pattern' };
+  try {
+    const { content } = await readClaimFile(claim);
+    const found = compilePattern(pattern, '').test(content);
+    return { disposition: found ? 'verified' : 'failed', reason: found ? 'pattern present' : 'pattern not found' };
+  } catch {
+    return { disposition: 'failed', reason: `cannot read ${file}` };
+  }
+}
+
+async function verifyPatternAbsent(claim) {
+  const { file, pattern } = claim;
+  if (!file || !pattern) return { disposition: 'unsupported', reason: 'prose-of-absence: claim requires file + pattern to verify' };
+  try {
+    const { content } = await readClaimFile(claim);
+    const found = compilePattern(pattern, '').test(content);
+    return { disposition: !found ? 'verified' : 'failed', reason: !found ? 'pattern absent as claimed' : 'pattern present despite claim of absence' };
+  } catch {
+    return { disposition: 'failed', reason: `cannot read ${file}` };
+  }
+}
+
+async function verifyCodeSnippet(claim) {
+  const { file, snippet, repoRoot = '.' } = claim;
+  if (!file || !snippet) return { disposition: 'unsupported', reason: 'code_snippet requires file + snippet' };
+  try {
+    const { content } = await readClaimFile(claim);
+    const norm = (s) => s.replace(/\s+/g, ' ').trim();
+    if (norm(content).includes(norm(snippet))) {
+      return { disposition: 'verified', reason: 'snippet found in cited file' };
+    }
+    const elsewhere = await snippetFoundElsewhere(repoRoot, snippet, file);
+    if (elsewhere) {
+      return { disposition: 'unsupported', reason: `snippet exists in ${elsewhere}, not in cited ${file}` };
+    }
+    return { disposition: 'failed', reason: 'snippet not found in cited file or repo' };
+  } catch {
+    return { disposition: 'failed', reason: `cannot read ${file}` };
+  }
+}
+
+async function verifyRepoCount({ pattern, expected, repoRoot = '.' }) {
+  if (!pattern || expected == null) return { disposition: 'unsupported', reason: 'repo_count requires pattern + expected' };
+  let actual = 0;
+  const re = compilePattern(pattern, '');
+  for await (const path of walkFiles(repoRoot)) {
+    try {
+      const content = await readFile(path, 'utf-8');
+      if (re.test(content)) actual++;
+    } catch {}
+  }
+  return actual === expected
+    ? { disposition: 'verified', actual, expected, reason: 'exact file count match' }
+    : { disposition: 'failed', actual, expected, reason: `file count: claim=${expected}, actual=${actual}` };
+}
+
+async function verifyCitationInLibrary({ url }) {
+  if (!url) return { disposition: 'unsupported', reason: 'citation_in_library requires url' };
+  if (/^[\w-]+:[\w-]+$/.test(url)) {
+    return { disposition: 'verified', reason: 'skill-rule reference format (allowed)' };
+  }
+  const known = await isKnownUrl(url);
+  return known
+    ? { disposition: 'verified', reason: 'URL in curated library' }
+    : { disposition: 'failed', reason: 'URL not in curated library — likely hallucination' };
+}
+
+async function verifyCitationAppliesToVersion({ url, framework, frameworkVersion }) {
+  if (!url || !framework || !frameworkVersion) {
+    return { disposition: 'unsupported', reason: 'requires url + framework + frameworkVersion' };
+  }
+  const fakeRec = { citations: [url] };
+  const { rec, strippedVersion, strippedUnknown } = await sanitizeCitations(fakeRec, framework, frameworkVersion);
+  if (strippedUnknown.length > 0) {
+    return { disposition: 'failed', reason: 'URL not in library' };
+  }
+  if (strippedVersion.length > 0) {
+    return { disposition: 'failed', reason: `URL not applicable to ${framework}@${frameworkVersion}` };
+  }
+  return rec.citations.length > 0
+    ? { disposition: 'verified', reason: `URL applies to ${framework}@${frameworkVersion}` }
+    : { disposition: 'unsupported', reason: 'sanitizer stripped all citations for unknown reason' };
+}
+
+async function verifyCacheVaryMatchesDynamicInputs({ rec, files, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec || !Array.isArray(files) || files.length === 0) {
+    return { disposition: 'unsupported', reason: 'cache_vary_matches_dynamic_inputs requires rec + files' };
+  }
+
+  let usesVercelGeo = false;
+  for (const file of files) {
+    try {
+      const { content } = await readClaimFile({ file, repoRoot, projectRootDirectory });
+      if (/\bgeolocation\s*\(/.test(content) ||
+          /\b\w+\.geo\??\./.test(content) ||
+          /['"]x-vercel-ip-(?:country|country-region|city|latitude|longitude|postal-code|timezone)['"]/i.test(content)) {
+        usesVercelGeo = true;
+        break;
+      }
+    } catch {}
+  }
+  if (!usesVercelGeo) {
+    return { disposition: 'verified', reason: 'cache rec does not touch Vercel geolocation inputs' };
+  }
+
+  const text = [rec.what, rec.why, rec.fix, rec.currentBehavior, rec.desiredBehavior, rec.verify]
+    .filter(Boolean)
+    .join('\n');
+  const hasCoarseGeoVary = hasHeaderValue(text, 'Vary', /(?:^|,\s*)X-Vercel-IP-(?:Country|Country-Region|City)(?:\s*,|$)/i);
+  if (hasCoarseGeoVary) {
+    return { disposition: 'verified', reason: 'cache rec varies by a coarse Vercel geolocation header for geolocation-dependent output' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cache rec touches Vercel geolocation but does not vary by a coarse Vercel geolocation header such as X-Vercel-IP-Country, X-Vercel-IP-Country-Region, or X-Vercel-IP-City',
+  };
+}
+
+async function verifyCacheVaryCardinalitySafe({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_vary_cardinality_safe requires rec' };
+  const text = recText(rec);
+  const varyValues = extractHeaderValues(text, 'Vary').join(', ');
+  if (!varyValues) {
+    return { disposition: 'verified', reason: 'no concrete Vary header value detected' };
+  }
+  if (/\bX-Vercel-IP-(?:Latitude|Longitude|Postal-Code)\b/i.test(varyValues)) {
+    return {
+      disposition: 'failed',
+      reason: 'Vary on X-Vercel-IP-Latitude, X-Vercel-IP-Longitude, or X-Vercel-IP-Postal-Code creates very high-cardinality CDN cache keys; use a coarser geography header when safe, or leave the response uncached',
+    };
+  }
+  return { disposition: 'verified', reason: 'Vary header avoids known high-cardinality geolocation headers' };
+}
+
+async function verifyNextCachedNotFoundCausalSupport({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cached_not_found_causal_support requires rec' };
+  const text = recText(rec);
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  const hasSpecificCitation = /nextjs\.org\/docs\/app\/api-reference\/functions\/not-found/i.test(citations) &&
+    /nextjs\.org\/docs\/app\/api-reference\/directives\/use-cache/i.test(citations);
+  const hasRuntimeStack = /\b(?:stack|logs?|trace)\b[\s\S]{0,120}\b(?:NEXT_|notFound|NEXT_HTTP_ERROR_FALLBACK|Error:)\b/i.test(text);
+  if (hasSpecificCitation || hasRuntimeStack) {
+    return { disposition: 'verified', reason: 'cached notFound causal claim has Next-specific citation or runtime stack evidence' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'notFound() inside use cache was claimed as a 5xx cause without Next-specific citation or runtime stack evidence',
+  };
+}
+
+async function verifyNextStableCacheApiForVersion({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_stable_cache_api_for_version requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'stable Next.js 16 cache API requirement does not apply' };
+  }
+  const text = recText(rec);
+  if (/\bunstable_(?:cacheLife|cacheTag)\b/.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'Next.js 16 rec uses unstable cache API; use cacheLife/cacheTag from next/cache',
+    };
+  }
+  if (/\brevalidateTag\s*\([^)]*['"`][^'"`]+['"`]\s*\)/.test(text) &&
+      !/\brevalidateTag\s*\([^)]*['"`][^'"`]+['"`]\s*,/.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'Next.js 16 revalidateTag examples must include the cache-life profile argument',
+    };
+  }
+  return { disposition: 'verified', reason: 'Next.js 16 cache API usage matches stable names' };
+}
+
+async function verifyNextRuntimeCacheApiForVersion({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_runtime_cache_api_for_version requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Next.js 16 Runtime Cache API requirement does not apply' };
+  }
+  const text = recText(rec);
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  if (/\bunstable_cache\b/.test(text) &&
+      (/\bRuntime Cache\b/i.test(text) || /vercel\.com\/docs\/caching\/runtime-cache/i.test(citations))) {
+    return {
+      disposition: 'failed',
+      reason: 'Next.js 16 Runtime Cache recommendations must use use cache: remote or fetch with force-cache, not unstable_cache',
+    };
+  }
+  return { disposition: 'verified', reason: 'Next.js Runtime Cache API usage matches project version' };
+}
+
+async function verifyNextCacheComponentsRuntimeCachePreference({ rec, framework, cacheComponents }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_components_runtime_cache_preference requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  if (cacheComponents !== true) {
+    return { disposition: 'verified', reason: 'Cache Components not detected as enabled' };
+  }
+  const text = recText(rec);
+  if (/\buse cache:\s*remote\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'recommendation uses framework-native remote cache for Cache Components project' };
+  }
+  if (/\b(?:fallback|only if|when Cache Components (?:is|are) unavailable|if cacheComponents is false)\b[^.\n]{0,180}\b(?:Runtime Cache|@vercel\/functions|getCache\s*\()/i.test(text)) {
+    return { disposition: 'verified', reason: 'Runtime Cache is framed as a fallback, not the primary Cache Components path' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Next.js Cache Components is enabled; prefer `use cache: remote` before recommending lower-level Runtime Cache APIs',
+  };
+}
+
+async function verifyNextCacheLifeSingleExecution({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_life_single_execution requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Next.js 16 cacheLife execution rule does not apply' };
+  }
+  const text = recText(rec);
+  const calls = [...text.matchAll(/\bcacheLife\s*\(/g)].map((m) => m.index ?? -1).filter((i) => i >= 0);
+  if (calls.length <= 1) {
+    return { disposition: 'verified', reason: 'at most one cacheLife() call appears in the recommendation' };
+  }
+  for (let i = 0; i < calls.length - 1; i++) {
+    const between = text.slice(calls[i], calls[i + 1]);
+    if (/\b(?:if|else|switch|case)\b|[?:]/.test(between)) continue;
+    return {
+      disposition: 'failed',
+      reason: 'multiple cacheLife() calls appear on one recommended code path; only one should execute per function invocation',
+    };
+  }
+  return { disposition: 'verified', reason: 'multiple cacheLife() calls appear only in separate control-flow branches' };
+}
+
+async function verifyNextCacheLifetimeFreshnessSupported({ rec, files, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_lifetime_freshness_supported requires rec' };
+  const text = recText(rec);
+  if (!/\bcacheLife\s*\(/.test(text)) {
+    return { disposition: 'verified', reason: 'no cacheLife() lifetime change detected' };
+  }
+
+  const tags = dedupeCacheTags([
+    ...extractCacheTags(text),
+    ...await extractCacheTagsFromFiles(files, repoRoot, projectRootDirectory),
+  ]);
+  if (tags.length === 0) {
+    if (cacheLifeNeedsContentFreshnessProof(text)) {
+      return {
+        disposition: 'failed',
+        reason: 'cacheLife() lengthens content-derived data without cacheTag/revalidateTag evidence; add invalidation evidence or keep the finding out of the ready-to-apply list',
+      };
+    }
+    return { disposition: 'unverifiable', reason: 'cacheLife() rec has no cacheTag evidence to verify against invalidation' };
+  }
+
+  const recTextAsFile = [{ path: '<recommendation>', content: text }];
+  const invalidationFiles = [
+    ...recTextAsFile,
+    ...await readCacheInvalidationFiles(repoRoot, projectRootDirectory),
+  ];
+  const missing = tags.filter((tag) => !tagHasMatchingInvalidation(tag, invalidationFiles));
+  if (missing.length === 0) {
+    return { disposition: 'verified', reason: 'cacheLife() freshness change has matching cache tag invalidation evidence' };
+  }
+  return {
+    disposition: 'failed',
+    reason: `cacheLife() would lengthen tagged content without matching revalidateTag/updateTag evidence for: ${missing.map((t) => t.label).join(', ')}`,
+  };
+}
+
+async function verifyNextCacheComponentsRouteChainFile({ rec, framework, frameworkVersion, cacheComponents, signals }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_components_route_chain_file requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Cache Components route-chain check does not apply' };
+  }
+  if (cacheComponents !== true) {
+    return { disposition: 'verified', reason: 'Cache Components not detected as enabled' };
+  }
+  const targetRoute = routeFromCandidateRef(rec.candidateRef);
+  if (!targetRoute) {
+    return { disposition: 'unverifiable', reason: 'Cache Components layout recommendation has no route candidateRef' };
+  }
+  const routeRows = Array.isArray(signals?.codebase?.routes) ? signals.codebase.routes : [];
+  if (routeRows.length === 0) {
+    return { disposition: 'unverifiable', reason: 'codebase route map unavailable for layout route-chain check' };
+  }
+  const layoutFiles = recommendationFilesFromRec(rec)
+    .filter((file) => /(^|\/)layout\.(?:tsx?|jsx?)$/.test(String(file)));
+  if (layoutFiles.length === 0) {
+    return { disposition: 'verified', reason: 'no layout files named in recommendation' };
+  }
+  const layoutRoutes = routeRows.filter((route) =>
+    route?.type === 'layout' &&
+    route?.file &&
+    layoutFiles.some((file) => pathSuffixMatches(file, route.file))
+  );
+  if (layoutRoutes.length === 0) {
+    return {
+      disposition: 'failed',
+      reason: 'Cache Components recommendation cites a layout file that is not present in the scanned route map',
+    };
+  }
+  const target = normalizeRouteForLayoutMatch(targetRoute);
+  const matchingLayout = layoutRoutes.find((layout) =>
+    layoutAppliesToCandidateRoute(layout.routePath, target)
+  );
+  if (matchingLayout) {
+    return {
+      disposition: 'verified',
+      reason: `layout ${matchingLayout.file} is in the observed route chain for ${targetRoute}`,
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Cache Components recommendation cites a layout file outside the observed route chain for this candidate route',
+  };
+}
+
+async function verifyNextCacheLifeCdnHeaderSemantics({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_life_cdn_header_semantics requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 15) {
+    return { disposition: 'verified', reason: 'Cache Components cacheLife semantics do not apply to this Next.js version' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cacheLife() controls the Cache Components lifetime and defaults to the default profile when omitted; do not claim it emits CDN Cache-Control headers or that missing cacheLife alone makes a route run per request without production header evidence',
+  };
+}
+
+async function verifyImageResponseHeadersCitation({ rec, framework }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'image_response_headers_citation requires rec' };
+  if (framework && framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  if (/nextjs\.org\/docs\/app\/api-reference\/functions\/image-response/i.test(citations)) {
+    return { disposition: 'verified', reason: 'ImageResponse header option is backed by the ImageResponse API reference' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'ImageResponse header changes need the ImageResponse API reference citation',
+  };
+}
+
+async function verifyNextImagePriorityApiForVersion({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_image_priority_api_for_version requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'next/image priority deprecation does not apply before Next.js 16' };
+  }
+  const text = recText(rec);
+  if (/\b(?:preload|fetchPriority|loading\s*=\s*['"`]eager['"`]|loading:\s*['"`]eager['"`])\b/.test(text) &&
+      !/<Image\b[^>]*\bpriority(?:\s|=|>)/i.test(text)) {
+    return { disposition: 'verified', reason: 'Next.js 16 image preload guidance uses the replacement API' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Next.js 16 deprecates next/image priority; use preload, fetchPriority, or loading="eager" based on the image loading intent',
+  };
+}
+
+async function verifyNextCacheComponentsRouteSegmentConfig({ rec, framework, frameworkVersion, cacheComponents }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_components_route_segment_config requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Cache Components route segment config restriction does not apply' };
+  }
+  if (cacheComponents !== true) {
+    return { disposition: 'verified', reason: 'Cache Components not detected as enabled' };
+  }
+  const text = recText(rec);
+  if (/\broute segment config options?\b[^.\n]{0,120}\b(?:Route Handlers?|handlers?)\b[^.\n]{0,120}\b(?:no longer apply|do not apply|removed)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'Route Segment Config still has Route Handler options; with Cache Components only dynamic, revalidate, and fetchCache are removed',
+    };
+  }
+  const blocked = [
+    /\bdynamicParams\b/.test(text) ? 'dynamicParams' : null,
+    /\bfetchCache\b/.test(text) ? 'fetchCache' : null,
+    /\bexport\s+const\s+dynamic\b/.test(text) ? 'dynamic' : null,
+    /\bexport\s+const\s+revalidate\b/.test(text) ? 'revalidate' : null,
+  ].filter(Boolean);
+  if (blocked.length === 0) {
+    return { disposition: 'verified', reason: 'no removed route segment config option detected' };
+  }
+  return {
+    disposition: 'failed',
+    reason: `Next.js ${major} project has Cache Components enabled; route segment config option(s) ${blocked.join(', ')} are removed and must not be recommended`,
+  };
+}
+
+async function verifyNextRouteRevalidateStaticPrereq({ rec, framework, cacheComponents, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_route_revalidate_static_prereq requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  if (cacheComponents === true) {
+    return { disposition: 'verified', reason: 'Cache Components route-segment restrictions are handled separately' };
+  }
+  const files = recommendationFilesFromRec(rec)
+    .filter((file) => /(^|\/)app\/.+\/(?:page|layout|template)\.(?:tsx?|jsx?)$/.test(String(file)) ||
+      /(^|\/)(?:page|layout|template)\.(?:tsx?|jsx?)$/.test(String(file)));
+  if (files.length === 0) {
+    return { disposition: 'verified', reason: 'route-level revalidate recommendation does not target a page/layout/template file' };
+  }
+
+  const dynamicHits = [];
+  for (const file of files) {
+    const routeChain = await readNextRouteChainFiles(file, repoRoot, projectRootDirectory);
+    if (routeChain.length === 0) {
+      return { disposition: 'unverifiable', reason: `could not inspect route chain for ${file}` };
+    }
+    for (const entry of routeChain) {
+      const hit = firstDynamicRouteChainReason(entry.content);
+      if (hit) dynamicHits.push(`${entry.relative}:${hit}`);
+    }
+  }
+  if (dynamicHits.length > 0) {
+    return {
+      disposition: 'failed',
+      reason: `route-level revalidate can be defeated by request-time APIs or auth helpers in the route chain (${dynamicHits.slice(0, 3).join(', ')}); prove the route is ISR/static from next build output or move the dynamic read out before recommending revalidate`,
+    };
+  }
+  return { disposition: 'verified', reason: 'no request-time API or common auth helper detected in the recommended route chain' };
+}
+
+async function verifyNextCacheTagInvalidationSupported({ rec, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_tag_invalidation_supported requires rec' };
+  const tags = extractCacheTags(recText(rec));
+  if (tags.length === 0) {
+    return { disposition: 'unsupported', reason: 'cache invalidation claim did not include parseable cacheTag() values' };
+  }
+
+  let files;
+  try {
+    files = await readCacheInvalidationFiles(repoRoot, projectRootDirectory);
+  } catch {
+    return { disposition: 'unverifiable', reason: 'could not scan repo for matching revalidateTag/updateTag calls' };
+  }
+
+  const missing = [];
+  for (const tag of tags) {
+    if (!tagHasMatchingInvalidation(tag, files)) missing.push(tag.label);
+  }
+  if (missing.length === 0) {
+    return { disposition: 'verified', reason: 'every claimed cacheTag has a matching revalidateTag/updateTag path' };
+  }
+  return {
+    disposition: 'failed',
+    reason: `cache invalidation was claimed for tag(s) without matching revalidateTag/updateTag evidence: ${missing.join(', ')}`,
+  };
+}
+
+async function verifyCacheRecNotErrorDominatedOrAcknowledged({ rec, signals }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_rec_not_error_dominated_or_acknowledged requires rec' };
+  const route = routeFromCandidateRef(rec.candidateRef);
+  if (!route) return { disposition: 'unverifiable', reason: 'cache recommendation has no route candidateRef' };
+  const status = functionStatusForRoute(signals, route);
+  if (!status || status.total <= 0) {
+    return { disposition: 'unverifiable', reason: 'no function status metrics available for cache route' };
+  }
+  const errorRate = status.errors / status.total;
+  if (errorRate <= 0.2) {
+    return { disposition: 'verified', reason: `function 5xx rate is not dominant (${formatPct(errorRate)})` };
+  }
+  const text = recText(rec);
+  if (/\b(?:5xx|500|errors?|error-rate|non-error|successful|2xx|after\s+(?:fixing|resolving)\s+errors?)\b/i.test(text)) {
+    return { disposition: 'verified', reason: `cache recommendation acknowledges high 5xx share (${formatPct(errorRate)})` };
+  }
+  return {
+    disposition: 'failed',
+    reason: `route has high function 5xx share (${formatPct(errorRate)}); cache impact must exclude or acknowledge error traffic`,
+  };
+}
+
+async function verifyCacheControlHeaderSyntax({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_control_header_syntax requires rec' };
+  const values = [
+    ...extractHeaderValues(recText(rec), 'Cache-Control'),
+    ...extractHeaderValues(recText(rec), 'CDN-Cache-Control'),
+    ...extractHeaderValues(recText(rec), 'Vercel-CDN-Cache-Control'),
+  ];
+  if (values.length === 0) {
+    return { disposition: 'unverifiable', reason: 'no parseable Cache-Control header value in recommendation' };
+  }
+  const invalid = values.find((value) => hasEmptyCacheDirective(value));
+  if (invalid) {
+    return {
+      disposition: 'failed',
+      reason: `Cache-Control header contains an empty directive: ${invalid}`,
+    };
+  }
+  return { disposition: 'verified', reason: 'cache header directives are syntactically non-empty' };
+}
+
+async function verifyCacheControlHeadersCitation({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_control_headers_citation requires rec' };
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  if (/vercel\.com\/docs\/caching\/(?:cache-control-headers|cdn-cache)/i.test(citations)) {
+    return { disposition: 'verified', reason: 'Cache-Control change is backed by Vercel cache documentation' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Cache-Control header changes need Vercel cache documentation citation',
+  };
+}
+
+async function verifyCachePolicyPositiveOrNoReadyRec({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_policy_positive_or_no_ready_rec requires rec' };
+  const text = recText(rec);
+  const positivePolicy = /\b(?:s-maxage|stale-while-revalidate|CDN-Cache-Control|Vercel-CDN-Cache-Control|Cache-Control:\s*public|next:\s*\{\s*revalidate|revalidate\s*[:=]\s*\d|cacheLife\s*\(|cacheTag\s*\(|['"`]use cache(?::\s*remote)?['"`]|Runtime Cache|getCache\s*\(|force-cache)\b/i.test(text);
+  if (positivePolicy) {
+    return { disposition: 'verified', reason: 'cache recommendation names a positive cache policy' };
+  }
+  if (/\b(?:no-store|no-cache|cache:\s*['"`]no-store['"`])\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'cache candidates must not ship a no-store-only recommendation; if no-store is correct, report no change instead',
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cache candidate recommendation does not name a cache policy; specify CDN headers, framework cache, Runtime Cache, or report no change',
+  };
+}
+
+async function verifyCache404LongTtlSafety({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_404_long_ttl_safety requires rec' };
+  const text = recText(rec);
+  if (/\b(?:leave|keep|leaving|keeping)\b[^.\n]{0,120}\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b[^.\n]{0,120}\b(?:uncached|no-store|no-cache|short|separate)\b/i.test(text) ||
+      /\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b[^.\n]{0,120}\b(?:uncached|no-store|no-cache|short|separate)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'recommendation keeps 404/not-found caching separate or uncached' };
+  }
+  if (/\b(?:both|all)\b[^.\n]{0,120}\bResponse\b[^.\n]{0,120}\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b/i.test(text) ||
+      /\b(?:add|set|include)\b[^.\n]{0,160}\b(?:Cache-Control|s-maxage|stale-while-revalidate|CDN-Cache-Control|Vercel-CDN-Cache-Control)\b[^.\n]{0,220}\b(?:each|every|all|both|\d+|four)\b[^.\n]{0,120}\bResponse\b[^.\n]{0,160}\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b/i.test(text) ||
+      /\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b[^.\n]{0,160}\b(?:s-maxage|stale-while-revalidate|CDN-Cache-Control|Vercel-CDN-Cache-Control)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'long shared caching for 404/not-found branches needs explicit freshness evidence; leave those branches uncached or short-lived',
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cache recommendation mentions a 404/not-found branch without explicitly keeping that branch uncached or short-lived',
+  };
+}
+
+async function verifyRouteErrorNotFoundStatusAndScope({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'route_error_not_found_status_and_scope requires rec' };
+  const text = recText(rec);
+  const hasExplicit404 = /\bstatus\s*:\s*404\b/i.test(text);
+  if (!hasExplicit404) {
+    return {
+      disposition: 'failed',
+      reason: 'not-found error handling must set an explicit 404 status; a markdown/body-only Response defaults to 200',
+    };
+  }
+  if (routeErrorFixExplicitlyConvertsUnexpectedErrorsToNotFound(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'route-error 404 fixes must not convert unexpected exceptions into not-found responses; classify expected misses and preserve 5xx behavior for unknown errors',
+    };
+  }
+  const classifiesKnownMiss = /\b(?:known|expected|missing|not[- ]found|not found|ENOENT|NoSuchKey|content[- ]miss|file[- ]miss)\b[^.\n]{0,160}\b(?:only|separate|classif|branch|guard|case)\b/i.test(text) ||
+    /\b(?:only|separate|classif|branch|guard|case)\b[^.\n]{0,160}\b(?:known|expected|missing|not[- ]found|not found|ENOENT|NoSuchKey|content[- ]miss|file[- ]miss)\b/i.test(text);
+  const preservesUnknownErrors = /\b(?:unknown|unexpected|all other|other)\b[^.\n]{0,180}\b(?:rethrow|throw|500|5xx|surface|preserv|remain visible|do not convert)\b/i.test(text) ||
+    /\b(?:rethrow|throw|500|5xx|surface|preserv|remain visible|do not convert)\b[^.\n]{0,180}\b(?:unknown|unexpected|all other|other)\b/i.test(text);
+  if (classifiesKnownMiss && preservesUnknownErrors) {
+    return { disposition: 'verified', reason: 'catch path separates expected misses from unknown errors and sets status 404' };
+  }
+  if (routeErrorFixBroadlyCatchesNotFound(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'route-error 404 fixes must classify expected misses before returning not-found and must not turn generic catch blocks into 404 responses',
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'route-error 404 fixes must classify expected misses separately and preserve logging or 5xx behavior for unknown errors',
+  };
+}
+
+function routeErrorFixExplicitlyConvertsUnexpectedErrorsToNotFound(text) {
+  return /\bunexpected\s+exceptions?\b[^.\n]{0,180}\b(?:degrade|convert|return|become|map)\b[^.\n]{0,160}\b(?:404|not[- ]found|not found|notFound)\b/i.test(text) ||
+    /\b(?:404|not[- ]found|not found|notFound)\b[^.\n]{0,160}\b(?:for|on)\b[^.\n]{0,80}\b(?:any|all|unexpected|unknown)\b[^.\n]{0,80}\bexceptions?\b/i.test(text) ||
+    /\b(?:any|all|unexpected|unknown)\b[^.\n]{0,80}\bexceptions?\b[^.\n]{0,160}\b(?:404|not[- ]found|not found|notFound)\b/i.test(text);
+}
+
+function routeErrorFixBroadlyCatchesNotFound(text) {
+  return /\b(?:catch|catch\s*\([^)]*\))\b[^.\n]{0,220}\b(?:return|respond|degrade|convert)\b[^.\n]{0,160}\b(?:404|not[- ]found|not found|notFound)\b/i.test(text);
+}
+
+async function verifyImmutableDynamicRouteSafety({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'immutable_dynamic_route_safety requires rec' };
+  const text = recText(rec);
+  if (/\b(?:content[- ]hash(?:ed)?|hashed|fingerprint(?:ed)?|versioned\s+URL|URL\s+changes\s+when\s+bytes\s+change)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'immutable cache header is tied to a byte-versioned URL' };
+  }
+  if (/\bVercel-CDN-Cache-Control\b/i.test(text) && !/(?:^|[^A-Za-z-])Cache-Control\s*:\s*[^.\n]*\bimmutable\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'immutable directive is scoped away from browser Cache-Control' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'immutable browser caching on a dynamic route requires a content-hashed or otherwise byte-versioned URL',
+  };
+}
+
+async function verifyAuthGuardParallelizationSafety({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'auth_guard_parallelization_safety requires rec' };
+  const text = recText(rec);
+  if (/\b(?:query|lookup|fetch)\b[^.\n]{0,120}\b(?:constrained|scoped|filtered)\b[^.\n]{0,120}\b(?:email|user|owner|ownership|session|account|tenant|permission|auth)/i.test(text) ||
+      /\b(?:preserve|keep|retain)\b[^.\n]{0,120}\b(?:auth|authorization|ownership|permission|access)\s+(?:check|guard|gate)\b[^.\n]{0,120}\b(?:before|ahead of|prior to|sequential|not parallel)/i.test(text)) {
+    return { disposition: 'verified', reason: 'parallelization recommendation preserves the auth/ownership guard' };
+  }
+  if (/\bPromise\.all\s*\([\s\S]{0,500}(?:private|secret|token|registrant|ticket|payment|account|user)\w*[\s\S]{0,500}(?:owns|owner|ownership|authorize|auth|permission|access)\w*/i.test(text) ||
+      /\bPromise\.all\s*\([\s\S]{0,500}(?:owns|owner|ownership|authorize|auth|permission|access)\w*[\s\S]{0,500}(?:private|secret|token|registrant|ticket|payment|account|user)\w*/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'parallelization may fetch private data before the ownership/auth check has passed; combine the authorized query or keep the guard sequential',
+    };
+  }
+  return {
+    disposition: 'unverifiable',
+    reason: 'auth-sensitive parallelization needs explicit evidence that private data is not fetched before authorization',
+  };
+}
+
+async function verifyParallelizationImpactNotOverclaimed({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'parallelization_impact_not_overclaimed requires rec' };
+  const text = recText(rec);
+  if (/\b(?:measured|trace|span|profile|instrumented)\b[^.\n]{0,120}\b(?:duration|round[- ]trip|query|helper|await)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'parallelization impact claim cites measured helper/span duration' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'parallelization impact promises a helper/round-trip-sized drop without measured helper or span timing',
+  };
+}
+
+async function verifyParallelizationNotCpuBoundWork({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'parallelization_not_cpu_bound_work requires rec' };
+  const text = recText(rec);
+  if (/\b(?:measured|trace|span|profile|instrumented)\b[^.\n]{0,160}\b(?:wait|I\/O|io|network|fetch|database|query|CMS|API)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'parallelization target cites measured wait/I/O time' };
+  }
+  if (/\b(?:cpu\.p95|CPU p95|cpu p95|CPU-bound|compute-bound|in-process compute|compileMDX|MDX compilation|compilation|render compute)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'parallelization targets CPU/compile work without measured independent wait time; Promise.all is not a safe latency fix for CPU-bound work',
+    };
+  }
+  return { disposition: 'verified', reason: 'parallelization target is not described as CPU-bound work' };
+}
+
+async function verifyRuntimeErrorCauseSupported({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'runtime_error_cause_supported requires rec' };
+  const text = recText(rec);
+  const hasRuntimeStack = /\b(?:stack|logs?|trace)\b[\s\S]{0,220}\b(?:Error:|ENOENT|ETIMEDOUT|ECONNRESET|NEXT_|at\s+[\w./[\]()-]+(?::\d+)?)/i.test(text);
+  if (hasRuntimeStack) {
+    return { disposition: 'verified', reason: 'runtime error cause is backed by logs or stack evidence' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'runtime error root cause was claimed without runtime logs or stack evidence',
+  };
+}
+
+async function verifyVercelIgnoreCommandProjectState({ rec, signals }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'vercel_ignore_command_project_state requires rec' };
+  const project = signals?.project;
+  if (!project || typeof project !== 'object') {
+    return { disposition: 'unverifiable', reason: 'project configuration unavailable for Ignored Build Step check' };
+  }
+  const text = recText(rec);
+  if (typeof project.commandForIgnoringBuildStep === 'string' && project.commandForIgnoringBuildStep.trim() !== '') {
+    return {
+      disposition: 'failed',
+      reason: 'project already has an Ignored Build Step command configured; do not recommend adding another without evidence the current command is insufficient',
+    };
+  }
+  if (project.enableAffectedProjectsDeployments === true &&
+      /\b(?:Ignored Build Step|ignoreCommand|turbo-ignore|skip unaffected|unaffected projects?)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'project already has Vercel skip-unaffected deployments enabled; do not recommend another build-skipping change without evidence that automatic skipping is unavailable or insufficient',
+    };
+  }
+  return { disposition: 'verified', reason: 'project config does not contradict Ignored Build Step recommendation' };
+}
+
+async function verifyTurboBuildCacheSafety({ rec, files, repoRoot = '.', projectRootDirectory = null, framework }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'turbo_build_cache_safety requires rec' };
+  const candidateFiles = Array.isArray(files) ? files : [];
+  const turboFiles = candidateFiles.filter((file) => /(^|\/)turbo\.json$/.test(String(file)));
+  if (turboFiles.length === 0) {
+    return { disposition: 'unverifiable', reason: 'Turbo build-cache recommendation has no turbo.json file to inspect' };
+  }
+
+  const text = recText(rec);
+  for (const turboFile of turboFiles) {
+    let turbo;
+    try {
+      const { content } = await readClaimFile({ file: turboFile, repoRoot, projectRootDirectory });
+      turbo = parseJsonLike(content);
+    } catch {
+      return { disposition: 'unverifiable', reason: `cannot parse ${turboFile} for Turbo cache safety` };
+    }
+    const buildTask = turbo?.tasks?.build ?? turbo?.pipeline?.build ?? null;
+    const outputs = Array.isArray(buildTask?.outputs) ? buildTask.outputs.map(String) : [];
+    const pkgFile = siblingPackageJson(turboFile);
+    const pkg = await readOptionalJsonFile({ file: pkgFile, repoRoot, projectRootDirectory });
+    const buildScript = typeof pkg?.scripts?.build === 'string' ? pkg.scripts.build : '';
+    const hasNext = framework === 'next' || Boolean(pkg?.dependencies?.next || pkg?.devDependencies?.next);
+
+    if (buildScriptHasMigrationSideEffect(buildScript) && !recSeparatesTurboBuildSideEffects(text)) {
+      return {
+        disposition: 'failed',
+        reason: 'Turbo build caching is unsafe for this build task because the package build script runs migrations or other side effects; split those steps before caching the build output',
+      };
+    }
+
+    if (hasNext && outputs.length > 0 && !outputs.some((output) => /\.next(?:\/|\*\*)/.test(output))) {
+      return {
+        disposition: 'failed',
+        reason: 'Turbo build cache outputs do not include Next.js build output (`.next/**`); fix the output contract before enabling build caching',
+      };
+    }
+  }
+
+  return { disposition: 'verified', reason: 'Turbo build cache recommendation does not conflict with local build scripts or outputs' };
+}
+
+function siblingPackageJson(file) {
+  return join(dirname(String(file)), 'package.json');
+}
+
+async function readOptionalJsonFile(claim) {
+  try {
+    const { content } = await readClaimFile(claim);
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function parseJsonLike(content) {
+  return JSON.parse(
+    String(content)
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|[^:])\/\/.*$/gm, '$1')
+      .replace(/,\s*([}\]])/g, '$1')
+  );
+}
+
+function buildScriptHasMigrationSideEffect(script) {
+  return /\b(?:payload\s+migrate|prisma\s+migrate|knex\s+migrate|sequelize\s+db:migrate|db:migrate|migrate(?::|\s|$)|migration)\b/i.test(String(script));
+}
+
+function recSeparatesTurboBuildSideEffects(text) {
+  return /\b(?:split|separate|move|keep)\b[^.\n]{0,180}\b(?:migrations?|side effects?|payload migrate|prisma migrate)\b[^.\n]{0,180}\b(?:outside|before|uncached|separate)\b/i.test(text) ||
+    /\b(?:cache|enable caching for)\b[^.\n]{0,120}\b(?:buildonly|pure build|next build)\b[^.\n]{0,180}\b(?:not|without|after separating)\b[^.\n]{0,120}\b(?:migrations?|side effects?)\b/i.test(text);
+}
+
+function recText(rec) {
+  return [rec?.what, rec?.why, rec?.fix, rec?.currentBehavior, rec?.desiredBehavior, rec?.verify]
+    .filter(Boolean)
+    .join('\n');
+}
+
+function extractHeaderValues(text, header) {
+  const escaped = escapeRegExp(header);
+  const values = [];
+  const quotedKey = new RegExp(`['"\`]${escaped}['"\`]\\s*:\\s*['"\`]([^'"\`\\n]+)['"\`]`, 'gi');
+  for (const m of text.matchAll(quotedKey)) values.push(m[1].trim());
+  const bareKey = new RegExp(`\\b${escaped}\\b\\s*:\\s*['"\`]?([^'"\`\\n]+)['"\`]?`, 'gi');
+  for (const m of text.matchAll(bareKey)) values.push(cleanHeaderValue(m[1]));
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function hasHeaderValue(text, header, valuePattern) {
+  return extractHeaderValues(text, header).some((value) => valuePattern.test(value));
+}
+
+function cleanHeaderValue(value) {
+  return String(value)
+    .replace(/[).;]+$/g, '')
+    .replace(/\s+and\s+.*$/i, '')
+    .trim();
+}
+
+function hasEmptyCacheDirective(value) {
+  return String(value).split(',').some((part) => part.trim() === '');
+}
+
+function extractCacheTags(text) {
+  const tags = [];
+  const callRe = /\bcacheTag\s*\(([^)]*)\)/gs;
+  for (const call of text.matchAll(callRe)) {
+    const args = call[1] ?? '';
+    for (const m of args.matchAll(/['"]([^'"]+)['"]/g)) {
+      tags.push({ kind: 'exact', value: m[1], label: m[1] });
+    }
+    for (const m of args.matchAll(/`([^`]+)`/g)) {
+      const raw = m[1];
+      const prefix = raw.split('${')[0];
+      if (raw.includes('${') && prefix) {
+        tags.push({ kind: 'prefix', value: prefix, label: raw });
+      } else if (!raw.includes('${')) {
+        tags.push({ kind: 'exact', value: raw, label: raw });
+      }
+    }
+  }
+  const seen = new Set();
+  return tags.filter((tag) => {
+    const key = `${tag.kind}\u0000${tag.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+async function extractCacheTagsFromFiles(files, repoRoot, projectRootDirectory) {
+  const out = [];
+  if (!Array.isArray(files)) return out;
+  for (const file of files) {
+    try {
+      const { content } = await readClaimFile({ file, repoRoot, projectRootDirectory });
+      out.push(...extractCacheTags(content));
+    } catch {}
+  }
+  return out;
+}
+
+function dedupeCacheTags(tags) {
+  const seen = new Set();
+  return tags.filter((tag) => {
+    const key = `${tag.kind}\u0000${tag.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+async function readCacheInvalidationFiles(repoRoot, projectRootDirectory) {
+  const cacheKey = `${normalize(repoRoot || '.')}\u0000${normalizeProjectRootDirectory(projectRootDirectory) ?? ''}`;
+  if (cacheInvalidationFileCache.has(cacheKey)) return cacheInvalidationFileCache.get(cacheKey);
+  const baseRoot = normalize(repoRoot || '.');
+  const projectRoot = normalizeProjectRootDirectory(projectRootDirectory);
+  const root = projectRoot ? join(baseRoot, projectRoot) : baseRoot;
+  try {
+    await access(root);
+  } catch {
+    cacheInvalidationFileCache.set(cacheKey, []);
+    return [];
+  }
+  const rgFiles = await rgRelevantFiles(root);
+  if (Array.isArray(rgFiles)) {
+    const files = [];
+    for (const path of rgFiles.slice(0, 500)) {
+      try {
+        files.push({ path, content: await readFile(path, 'utf-8') });
+      } catch {}
+    }
+    cacheInvalidationFileCache.set(cacheKey, files);
+    return files;
+  }
+  const files = [];
+  for await (const path of walkFiles(root)) {
+    try {
+      const content = await readFile(path, 'utf-8');
+      if (!/\b(?:revalidateTag|updateTag)\s*\(|\btags\s*:/.test(content)) continue;
+      files.push({ path, content });
+    } catch {}
+  }
+  cacheInvalidationFileCache.set(cacheKey, files);
+  return files;
+}
+
+async function rgRelevantFiles(root) {
+  try {
+    const { stdout } = await execFileP('rg', [
+      '-l',
+      '--glob', '!node_modules/**',
+      '--glob', '!.next/**',
+      '--glob', '!.vercel/**',
+      '--glob', '!.turbo/**',
+      '--glob', '!dist/**',
+      '--glob', '!build/**',
+      '--glob', '!coverage/**',
+      '--glob', '!content/**',
+      '--glob', '!fixtures/**',
+      '--glob', '!migrations/**',
+      '--glob', '!public/**',
+      '--glob', '*.{ts,tsx,js,jsx,mjs,cjs}',
+      String.raw`\b(?:revalidateTag|updateTag)\s*\(|\btags\s*:`,
+      root,
+    ], { maxBuffer: 10 * 1024 * 1024 });
+    return stdout.split(/\r?\n/).filter(Boolean);
+  } catch (err) {
+    if (err?.code === 1) return [];
+    return null;
+  }
+}
+
+function tagHasMatchingInvalidation(tag, files) {
+  return files.some(({ content }) => {
+    if (hasLiteralInvalidation(content, tag)) return true;
+    return hasConfigDrivenInvalidation(content, tag, files);
+  });
+}
+
+function hasLiteralInvalidation(content, tag) {
+  if (tag.kind === 'exact') {
+    const escaped = escapeRegExp(tag.value);
+    return new RegExp(`\\b(?:revalidateTag|updateTag)\\s*\\(\\s*['"\`]${escaped}['"\`]`).test(content);
+  }
+  const escaped = escapeRegExp(tag.value);
+  return new RegExp(`\\b(?:revalidateTag|updateTag)\\s*\\(\\s*\`?${escaped}`).test(content);
+}
+
+function hasConfigDrivenInvalidation(content, tag, files) {
+  if (!/\brevalidateTag\s*\(\s*\w+/.test(content)) return false;
+  return files.some((file) => configContainsTag(file.content, tag));
+}
+
+function configContainsTag(content, tag) {
+  if (tag.kind === 'exact') {
+    const escaped = escapeRegExp(tag.value);
+    return new RegExp(`\\btags\\s*:\\s*\\[[^\\]]*['"\`]${escaped}['"\`]`, 's').test(content);
+  }
+  const escaped = escapeRegExp(tag.value);
+  return new RegExp(`\\btags\\s*:\\s*\\[[^\\]]*\`?${escaped}`, 's').test(content);
+}
+
+function routeFromCandidateRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const idx = ref.indexOf(':');
+  if (idx < 0) return null;
+  const route = ref.slice(idx + 1);
+  return route && route !== '<account>' && !route.startsWith('<account>#') ? route : null;
+}
+
+function functionStatusForRoute(signals, route) {
+  const rows = signals?.metrics?.fnStatusByRoute?.rows;
+  if (!Array.isArray(rows)) return null;
+  const target = canonicalizeRoute(route);
+  let total = 0;
+  let errors = 0;
+  for (const row of rows) {
+    const rowRoute = row?.route ?? row?.path;
+    if (!rowRoute || canonicalizeRoute(rowRoute) !== target) continue;
+    const value = numberValue(row?.value);
+    if (value == null) continue;
+    total += value;
+    if (/^5/.test(String(row?.http_status ?? ''))) errors += value;
+  }
+  return total > 0 ? { total, errors } : null;
+}
+
+function numberValue(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const n = Number(value.replace(/,/g, ''));
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function asArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+function formatPct(n) {
+  return `${(n * 100).toFixed(1)}%`;
+}
+
+function cacheLifeNeedsContentFreshnessProof(text) {
+  return /\bcacheLife\s*\(\s*['"`](?:hours|days|weeks|max)['"`]\s*\)/i.test(text) &&
+    /\b(?:CMS|Contentful|Payload|Sanity|WordPress|docs?|guides?|navigation|nav|content|article|blog|OpenAPI|metadata|get[A-Z][\w]*(?:By|For|From)?\w*)\b/.test(text);
+}
+
+function recommendationFilesFromRec(rec) {
+  return Array.from(new Set([
+    ...asArray(rec?.affectedFiles),
+    ...asArray(rec?.findingRefs).map((ref) => String(ref).match(/^(.+?):\d+$/)?.[1]).filter(Boolean),
+  ]));
+}
+
+async function readNextRouteChainFiles(file, repoRoot, projectRootDirectory) {
+  const normalized = normalizeProjectRootDirectory(file);
+  if (!normalized) return [];
+  const appIdx = normalized.split('/').lastIndexOf('app');
+  if (appIdx === -1) {
+    try {
+      const { path, content } = await readClaimFile({ file, repoRoot, projectRootDirectory });
+      return [{ path, relative: normalized, content }];
+    } catch {
+      return [];
+    }
+  }
+
+  const parts = normalized.split('/');
+  const appParts = parts.slice(0, appIdx + 1);
+  const routeDirs = parts.slice(appIdx + 1, -1);
+  const candidates = new Set([normalized]);
+  for (let depth = 0; depth <= routeDirs.length; depth++) {
+    const dir = [...appParts, ...routeDirs.slice(0, depth)].join('/');
+    for (const base of ['layout', 'template']) {
+      for (const ext of ['tsx', 'ts', 'jsx', 'js']) candidates.add(`${dir}/${base}.${ext}`);
+    }
+  }
+
+  const out = [];
+  for (const candidate of candidates) {
+    try {
+      const { path, content } = await readClaimFile({ file: candidate, repoRoot, projectRootDirectory });
+      out.push({ path, relative: candidate, content });
+    } catch {}
+  }
+  return out;
+}
+
+function firstDynamicRouteChainReason(content) {
+  const text = String(content ?? '');
+  const direct = text.match(/\b(cookies|headers|draftMode|connection)\s*\(/);
+  if (direct) return `${direct[1]}()`;
+  const helper = text.match(/\b(withAuth|getServerSession|auth|currentUser)\s*\(/);
+  if (helper) return `${helper[1]}()`;
+  if (/from\s+['"]next\/headers['"]/.test(text)) return 'next/headers import';
+  return null;
+}
+
+function pathSuffixMatches(candidateFile, routeFile) {
+  const candidate = normalizeProjectRootDirectory(candidateFile);
+  const route = normalizeProjectRootDirectory(routeFile);
+  if (!candidate || !route) return false;
+  return candidate === route || candidate.endsWith(`/${route}`) || route.endsWith(`/${candidate}`);
+}
+
+function normalizeRouteForLayoutMatch(route) {
+  const normalized = canonicalizeRoute(String(route ?? ''));
+  return normalized.startsWith('/') ? normalized : `/${normalized}`;
+}
+
+function layoutAppliesToCandidateRoute(layoutPath, targetRoute) {
+  if (typeof layoutPath !== 'string' || typeof targetRoute !== 'string') return false;
+  const layout = normalizeRouteForLayoutMatch(layoutPath);
+  const target = normalizeRouteForLayoutMatch(targetRoute);
+  if (layout === '/') return true;
+
+  let layoutTokens = layout.split('/').filter(Boolean);
+  const targetTokens = target.split('/').filter(Boolean);
+  if (layoutTokens.length > targetTokens.length && isDynamicPlaceholder(layoutTokens[0])) {
+    layoutTokens = layoutTokens.slice(1);
+  } else if (layoutTokens.length > 0 &&
+      targetTokens.length > 0 &&
+      isDynamicPlaceholder(layoutTokens[0]) &&
+      layoutTokens[1] === targetTokens[0]) {
+    layoutTokens = layoutTokens.slice(1);
+  }
+  if (layoutTokens.length === 0) return true;
+  if (layoutTokens.length > targetTokens.length) return false;
+
+  let literalMatches = 0;
+  for (let i = 0; i < layoutTokens.length; i++) {
+    const layoutToken = layoutTokens[i];
+    const targetToken = targetTokens[i];
+    if (isCatchAllPlaceholder(layoutToken)) return literalMatches > 0;
+    if (layoutToken === targetToken) {
+      literalMatches += 1;
+      continue;
+    }
+    if (isDynamicPlaceholder(layoutToken)) continue;
+    return false;
+  }
+  return literalMatches > 0;
+}
+
+function isDynamicPlaceholder(segment) {
+  return /^\[(?:\.{3})?.+\]$/.test(String(segment ?? ''));
+}
+
+function isCatchAllPlaceholder(segment) {
+  return /^\[\[?\.{3}.+\]?\]$/.test(String(segment ?? ''));
+}
+
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Supports `/pattern/flags` literal-regex form OR plain escaped string. Caller flags merge with embedded flags via Set dedup.
+function compilePattern(pattern, flags) {
+  const m = pattern.match(/^\/(.+)\/([gimsu]*)$/);
+  if (m) {
+    const mergedFlags = [...new Set(((m[2] || '') + (flags || '')).split(''))].join('');
+    return new RegExp(m[1], mergedFlags);
+  }
+  return new RegExp(pattern.replace(/[.+^${}()|[\]\\?*]/g, '\\$&'), flags);
+}
+
+async function readClaimFile(claim) {
+  const path = await firstAccessiblePath(claim);
+  return { path, content: await readFile(path, 'utf-8') };
+}
+
+async function firstAccessiblePath({ repoRoot = '.', file, projectRootDirectory = null }) {
+  let lastErr;
+  for (const p of repoPaths(repoRoot, file, projectRootDirectory)) {
+    try {
+      await access(p);
+      return p;
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw lastErr ?? new Error(`cannot access ${file}`);
+}
+
+function repoPaths(repoRoot, file, projectRootDirectory = null) {
+  if (!file) return [];
+  if (isAbsolute(file)) return [file];
+  const out = [join(repoRoot, file)];
+  const projectRoot = normalizeProjectRootDirectory(projectRootDirectory);
+  const normalizedFile = normalizeProjectRootDirectory(file);
+  if (projectRoot && normalizedFile && !normalizedFile.startsWith(`${projectRoot}/`)) {
+    out.push(join(repoRoot, projectRoot, file));
+  }
+  return Array.from(new Set(out.map((p) => normalize(p))));
+}
+
+function normalizeProjectRootDirectory(value) {
+  if (typeof value !== 'string' || value.trim() === '') return null;
+  return value.replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+}
+
+async function* walkFiles(root, skip = new Set([
+  'node_modules',
+  '.next',
+  '.vercel',
+  '.turbo',
+  'dist',
+  'build',
+  'coverage',
+  '.git',
+  'content',
+  'fixtures',
+  'migrations',
+  'public',
+])) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const path = join(root, e.name);
+    if (e.isDirectory()) {
+      if (skip.has(e.name)) continue;
+      yield* walkFiles(path, skip);
+      continue;
+    }
+    if (!e.isFile()) continue;
+    if (!/\.(tsx?|jsx?|mjs|cjs)$/.test(e.name)) continue;
+    yield path;
+  }
+}
+
+async function snippetFoundElsewhere(root, snippet, exceptFile) {
+  const norm = (s) => s.replace(/\s+/g, ' ').trim();
+  const target = norm(snippet);
+  if (target.length < 20) return null;
+  for await (const path of walkFiles(root)) {
+    if (path.endsWith(exceptFile)) continue;
+    try {
+      const content = await readFile(path, 'utf-8');
+      if (norm(content).includes(target)) return path;
+    } catch {}
+  }
+  return null;
+}
diff --git a/skills/vercel/vercel-optimize/lib/workspace-resolver.mjs b/skills/vercel/vercel-optimize/lib/workspace-resolver.mjs
new file mode 100644
index 0000000..4d5b767
--- /dev/null
+++ b/skills/vercel/vercel-optimize/lib/workspace-resolver.mjs
@@ -0,0 +1,521 @@
+// Resolve workspace-package imports to actual source files. Sub-agents need this when the route file is a thin shell that re-exports from a workspace package.
+//
+// Bounded expansion keeps the brief allowlist small: package export resolution, pure-barrel
+// traversal, and suffix fan-out for likely data-loading modules. This stays string-based
+// and falls through ("couldn't resolve") on shapes that need a full TS resolver.
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve as pathResolve } from 'node:path';
+
+const DEFAULT_RESOLVE_OPTIONS = {
+  pureBarrelDepth: 3,
+  suffixFanoutDepth: 2,
+  perSpecifierCap: 3,
+};
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const EXTENSIONS = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const INDEX_FILES = ['index.ts', 'index.tsx', 'index.js', 'index.jsx', 'index.mjs'];
+const SUFFIX_FANOUT_RE = /(^|\/)(content|data|loader|fetch|service|metadata|actions)\.tsx?$/;
+const EXPORT_FORWARD_RE = /export\s+(?:type\s+)?(?:\*|\*\s+as\s+[A-Za-z_$][\w$]*|\{[^}]*\})\s+from\s+['"][^'"\n]+['"]\s*;?/gs;
+
+export async function detectMonorepoRoot(startDir) {
+  let dir = pathResolve(startDir);
+  for (let depth = 0; depth < 15; depth++) {
+    if (await fileExists(join(dir, 'pnpm-workspace.yaml'))) return dir;
+    const pkg = await tryReadJson(join(dir, 'package.json'));
+    if (pkg && (Array.isArray(pkg.workspaces) || Array.isArray(pkg.workspaces?.packages))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+// Zero-dependency — pnpm-workspace.yaml shape is predictable; not pulling in js-yaml.
+export async function readWorkspaceGlobs(monorepoRoot) {
+  const pnpmPath = join(monorepoRoot, 'pnpm-workspace.yaml');
+  if (await fileExists(pnpmPath)) {
+    const text = await readFile(pnpmPath, 'utf-8');
+    return parsePnpmWorkspaceYaml(text);
+  }
+  const pkg = await tryReadJson(join(monorepoRoot, 'package.json'));
+  if (Array.isArray(pkg?.workspaces)) return pkg.workspaces;
+  if (Array.isArray(pkg?.workspaces?.packages)) return pkg.workspaces.packages;
+  return [];
+}
+
+// Handles `packages:` block with `- glob` entries. Not full YAML grammar.
+export function parsePnpmWorkspaceYaml(text) {
+  const out = [];
+  let inPackages = false;
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.replace(/#.*$/, '').trimEnd();
+    if (!line.trim()) continue;
+    if (/^packages\s*:/.test(line)) { inPackages = true; continue; }
+    if (!inPackages) continue;
+    if (!/^\s/.test(line)) { inPackages = false; continue; }
+    const m = line.match(/^\s*-\s+['"]?([^'"\s]+)['"]?\s*$/);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
+export async function listWorkspacePackages(monorepoRoot) {
+  const globs = await readWorkspaceGlobs(monorepoRoot);
+  const dirs = new Set();
+  for (const g of globs) {
+    const expanded = await expandWorkspaceGlob(monorepoRoot, g);
+    for (const d of expanded) dirs.add(d);
+  }
+  const out = [];
+  for (const dir of dirs) {
+    const pkg = await tryReadJson(join(dir, 'package.json'));
+    if (pkg?.name) out.push({ name: pkg.name, dir, pkg });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// Handles workspace-shape globs only. `**` collapses to one level — npm/pnpm don't document deep `**`.
+async function expandWorkspaceGlob(root, glob) {
+  const parts = glob.replace(/\\/g, '/').split('/');
+  return await expandParts(root, parts);
+}
+
+async function expandParts(currentDir, parts) {
+  if (parts.length === 0) return [currentDir];
+  const [head, ...rest] = parts;
+  if (head === '' || head === '.') return await expandParts(currentDir, rest);
+  if (head === '*' || head === '**') {
+    let entries = [];
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true });
+    } catch { return []; }
+    const childDirs = entries.filter((e) => e.isDirectory()).map((e) => join(currentDir, e.name));
+    const out = [];
+    for (const d of childDirs) {
+      const more = await expandParts(d, rest);
+      out.push(...more);
+    }
+    return out;
+  }
+  const next = join(currentDir, head);
+  try {
+    const s = await stat(next);
+    if (!s.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  return await expandParts(next, rest);
+}
+
+export function buildResolver(packages) {
+  const byName = new Map();
+  for (const p of packages) {
+    byName.set(p.name, buildPackageLookup(p));
+  }
+  return function resolveSpecifier(specifier) {
+    if (typeof specifier !== 'string' || !specifier.length) return null;
+    // Longest-name match first so `@vercel/foo-bar` wins over `@vercel/foo`.
+    const candidates = [...byName.keys()]
+      .filter((name) => specifier === name || specifier.startsWith(name + '/'))
+      .sort((a, b) => b.length - a.length);
+    if (candidates.length === 0) return null;
+    const pkgName = candidates[0];
+    const subpath = specifier === pkgName ? '.' : './' + specifier.slice(pkgName.length + 1);
+    const lookup = byName.get(pkgName);
+    return lookup.resolveSubpath(subpath);
+  };
+}
+
+// Node spec: pattern key has exactly one `*`; target may have one or zero.
+function buildPackageLookup(p) {
+  const exact = new Map();
+  const wildcards = [];
+  const exports = p.pkg.exports;
+  if (exports && typeof exports === 'object' && !Array.isArray(exports)) {
+    for (const [key, value] of Object.entries(exports)) {
+      const target = pickConditionalTarget(value);
+      if (typeof target !== 'string') continue;
+      if (key.includes('*')) {
+        const keyStarIdx = key.indexOf('*');
+        if (keyStarIdx !== key.lastIndexOf('*')) continue;
+        wildcards.push({
+          keyPrefix: key.slice(0, keyStarIdx),
+          keySuffix: key.slice(keyStarIdx + 1),
+          valueTemplate: target,
+        });
+      } else {
+        exact.set(key, target);
+      }
+    }
+  }
+  return {
+    resolveSubpath(subpath) {
+      const exactHit = exact.get(subpath);
+      if (exactHit) return joinPackagePath(p.dir, exactHit);
+      for (const w of wildcards) {
+        if (subpath.startsWith(w.keyPrefix) && subpath.endsWith(w.keySuffix)) {
+          const star = subpath.slice(w.keyPrefix.length, subpath.length - w.keySuffix.length);
+          if (!star) continue;
+          const target = w.valueTemplate.replace('*', star);
+          return joinPackagePath(p.dir, target);
+        }
+      }
+      // Unsafe to guess when no exports declared.
+      if (exact.size === 0 && wildcards.length === 0 && subpath !== '.') {
+        return null;
+      }
+      return null;
+    },
+  };
+}
+
+// Condition order matches what Next.js / Vite / esbuild would resolve.
+function pickConditionalTarget(value) {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const target = pickConditionalTarget(item);
+      if (typeof target === 'string') return target;
+    }
+    return null;
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  for (const cond of ['default', 'import', 'node', 'browser', 'require', 'types']) {
+    const v = value[cond];
+    if (typeof v === 'string') return v;
+  }
+  return null;
+}
+
+export async function resolveWorkspaceImports(sourceFilePath, resolver, options = {}) {
+  let text;
+  try {
+    text = await readFile(sourceFilePath, 'utf-8');
+  } catch {
+    return [];
+  }
+  const opts = { ...DEFAULT_RESOLVE_OPTIONS, ...options };
+  const refs = extractModuleReferences(text);
+  const out = [];
+  const seen = new Set();
+  for (const ref of refs) {
+    const resolved = await resolveModuleSpecifier(sourceFilePath, ref.specifier, resolver);
+    if (!resolved) continue;
+    const expanded = await expandResolvedSpecifier(resolved, ref.importedNames, resolver, opts);
+    for (const file of expanded) {
+      if (seen.has(file)) continue;
+      seen.add(file);
+      out.push(file);
+    }
+  }
+  return out;
+}
+
+// Skips CommonJS `require('foo')` and template-literal dynamic imports (statically unresolvable).
+export function extractImportSpecifiers(text) {
+  return [...new Set(extractModuleReferences(text).map((ref) => ref.specifier))];
+}
+
+function joinPackagePath(packageDir, relativeTarget) {
+  return join(packageDir, relativeTarget.replace(/^\.\//, ''));
+}
+
+async function expandResolvedSpecifier(startFile, importedNames, resolver, opts) {
+  const out = [];
+  const seen = new Set();
+  const barrelVisited = new Set();
+  const fanoutVisited = new Set();
+
+  const add = (file) => {
+    if (seen.has(file)) return false;
+    if (out.length > 0 && out.length - 1 >= opts.perSpecifierCap) return false;
+    seen.add(file);
+    out.push(file);
+    return true;
+  };
+
+  add(startFile);
+  await expandPureBarrel(startFile, importedNames, 0);
+  const fanoutSeeds = out.slice();
+  for (const file of fanoutSeeds) {
+    await expandSuffixFanout(file, 0);
+  }
+  return out;
+
+  async function expandPureBarrel(file, requestedNames, depth) {
+    if (depth >= opts.pureBarrelDepth) return;
+    if (barrelVisited.has(file)) return;
+    barrelVisited.add(file);
+    const text = await tryReadText(file);
+    if (text == null || !isPureBarrel(text)) return;
+    const refs = await selectRelevantForwards(file, extractExportForwardRefs(text), requestedNames, resolver);
+    for (const { ref, next } of refs) {
+      if (!add(next)) return;
+      await expandPureBarrel(next, requestedNamesForForward(ref, requestedNames), depth + 1);
+    }
+  }
+
+  async function expandSuffixFanout(file, depth) {
+    if (depth >= opts.suffixFanoutDepth) return;
+    if (!isSuffixFanoutFile(file)) return;
+    const visitKey = `${file}:${depth}`;
+    if (fanoutVisited.has(visitKey)) return;
+    fanoutVisited.add(visitKey);
+    const text = await tryReadText(file);
+    if (text == null) return;
+    for (const ref of extractModuleReferences(text)) {
+      const next = await resolveModuleSpecifier(file, ref.specifier, resolver);
+      if (!next) continue;
+      if (!add(next)) return;
+      if (isSuffixFanoutFile(next)) await expandSuffixFanout(next, depth + 1);
+    }
+  }
+}
+
+async function selectRelevantForwards(fromFile, refs, requestedNames, resolver) {
+  const resolved = [];
+  for (const [index, ref] of refs.entries()) {
+    const next = await resolveModuleSpecifier(fromFile, ref.specifier, resolver);
+    if (!next) continue;
+    let score = requestedNames && requestedNames.size > 0
+      ? forwardRelevanceScore(ref, requestedNames, refs.length)
+      : 1;
+    if (requestedNames && requestedNames.size > 0 && await fileExportsAnyName(next, requestedNames)) {
+      score = Math.max(score, 75);
+    }
+    resolved.push({ ref, next, index, score });
+  }
+  if (!requestedNames || requestedNames.size === 0) return resolved;
+  const ranked = resolved
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score || a.index - b.index);
+  return ranked.length > 0 ? ranked : resolved;
+}
+
+function forwardRelevanceScore(ref, requestedNames, siblingCount) {
+  if (!requestedNames || requestedNames.size === 0) return 1;
+  if (ref.exportedNames) {
+    for (const name of requestedNames) {
+      if (ref.exportedNames.has(name)) return 100;
+    }
+  }
+  if (specifierMatchesNames(ref.specifier, requestedNames)) return 50;
+  return siblingCount === 1 ? 1 : 0;
+}
+
+function requestedNamesForForward(ref, requestedNames) {
+  if (!requestedNames || requestedNames.size === 0) return null;
+  if (ref.star) return requestedNames;
+  const out = new Set();
+  for (const name of requestedNames) {
+    const source = ref.sourceNamesByExported?.get(name);
+    if (source) out.add(source);
+  }
+  return out.size > 0 ? out : requestedNames;
+}
+
+async function resolveModuleSpecifier(fromFile, specifier, resolver) {
+  const raw = specifier.startsWith('.')
+    ? join(dirname(fromFile), specifier)
+    : resolver(specifier);
+  if (!raw) return null;
+  return await resolveExistingPath(raw);
+}
+
+async function resolveExistingPath(basePath) {
+  for (const ext of EXTENSIONS) {
+    const candidate = ext === '' ? basePath : basePath + ext;
+    if (!isSourcePath(candidate)) continue;
+    if (await isFile(candidate)) return candidate;
+  }
+  for (const indexFile of INDEX_FILES) {
+    const candidate = join(basePath, indexFile);
+    if (await isFile(candidate)) return candidate;
+  }
+  return null;
+}
+
+function extractModuleReferences(text) {
+  return [
+    ...extractImportReferences(text),
+    ...extractExportForwardRefs(text).map((ref) => ({
+      specifier: ref.specifier,
+      importedNames: ref.star ? null : ref.exportedNames,
+    })),
+    ...extractDynamicImportReferences(text),
+  ];
+}
+
+function extractImportReferences(text) {
+  const out = [];
+  const fromRe = /import\s+(?:type\s+)?([\s\S]*?)\s+from\s+['"]([^'"\n]+)['"]/g;
+  let m;
+  while ((m = fromRe.exec(text)) !== null) {
+    out.push({ specifier: m[2], importedNames: parseImportNames(m[1]) });
+  }
+  const sideEffectRe = /import\s+['"]([^'"\n]+)['"]/g;
+  while ((m = sideEffectRe.exec(text)) !== null) {
+    out.push({ specifier: m[1], importedNames: null });
+  }
+  return out;
+}
+
+function extractDynamicImportReferences(text) {
+  const out = [];
+  const re = /import\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    out.push({ specifier: m[1], importedNames: null });
+  }
+  return out;
+}
+
+function extractExportForwardRefs(text) {
+  const out = [];
+  const re = /export\s+(?:type\s+)?(\*|\*\s+as\s+[A-Za-z_$][\w$]*|\{[^}]*\})\s+from\s+['"]([^'"\n]+)['"]\s*;?/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const clause = m[1].trim();
+    const star = clause.startsWith('*');
+    const names = star ? null : parseExportNames(clause);
+    out.push({
+      specifier: m[2],
+      star,
+      exportedNames: names?.exportedNames ?? null,
+      sourceNamesByExported: names?.sourceNamesByExported ?? null,
+    });
+  }
+  return out;
+}
+
+function parseImportNames(clause) {
+  const names = new Set();
+  const trimmed = clause.trim();
+  if (!trimmed) return null;
+  const named = /\{([^}]+)\}/s.exec(trimmed);
+  if (named) {
+    for (const part of splitImportList(named[1])) {
+      const cleaned = part.replace(/^type\s+/, '').trim();
+      if (!cleaned) continue;
+      const [source] = cleaned.split(/\s+as\s+/i);
+      if (source?.trim()) names.add(source.trim());
+    }
+  }
+  const withoutNamed = trimmed.replace(/\{[^}]*\}/s, '').replace(/,\s*$/, '').trim();
+  if (withoutNamed && !withoutNamed.startsWith('*')) names.add('default');
+  return names.size > 0 ? names : null;
+}
+
+function parseExportNames(clause) {
+  const body = clause.replace(/^\{|\}$/g, '');
+  const exportedNames = new Set();
+  const sourceNamesByExported = new Map();
+  for (const part of splitImportList(body)) {
+    const cleaned = part.replace(/^type\s+/, '').trim();
+    if (!cleaned) continue;
+    const [sourceRaw, exportedRaw] = cleaned.split(/\s+as\s+/i);
+    const source = sourceRaw.trim();
+    const exported = (exportedRaw ?? sourceRaw).trim();
+    if (!source || !exported) continue;
+    exportedNames.add(exported);
+    sourceNamesByExported.set(exported, source);
+  }
+  return { exportedNames, sourceNamesByExported };
+}
+
+function splitImportList(value) {
+  return value.split(',').map((part) => part.trim()).filter(Boolean);
+}
+
+function isPureBarrel(text) {
+  const refs = extractExportForwardRefs(text);
+  if (refs.length === 0) return false;
+  const withoutComments = text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '');
+  return withoutComments.replace(EXPORT_FORWARD_RE, '').trim() === '';
+}
+
+function specifierMatchesNames(specifier, names) {
+  const normalizedSpecifier = normalizeName(specifier.split('/').at(-1) ?? specifier);
+  for (const name of names) {
+    const normalizedName = normalizeName(name);
+    if (normalizedSpecifier === normalizedName || normalizedSpecifier.endsWith(normalizedName)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function normalizeName(value) {
+  return String(value ?? '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function isSuffixFanoutFile(file) {
+  return SUFFIX_FANOUT_RE.test(file.replace(/\\/g, '/'));
+}
+
+async function fileExportsAnyName(file, names) {
+  const text = await tryReadText(file);
+  if (text == null) return false;
+  for (const name of names) {
+    if (textExportsName(text, name)) return true;
+  }
+  return false;
+}
+
+function textExportsName(text, name) {
+  const escaped = escapeRegExp(name);
+  const declaration = new RegExp(`export\\s+(?:async\\s+)?(?:function|const|let|var|class|interface|type)\\s+${escaped}\\b`);
+  if (declaration.test(text)) return true;
+  const listRe = /export\s+\{([^}]+)\}(?!\s+from\b)/gs;
+  let m;
+  while ((m = listRe.exec(text)) !== null) {
+    const names = parseExportNames(`{${m[1]}}`).exportedNames;
+    if (names.has(name)) return true;
+  }
+  return false;
+}
+
+function isSourcePath(path) {
+  const match = /\.([A-Za-z0-9]+)$/.exec(path);
+  if (!match) return true;
+  return SOURCE_EXTENSIONS.has('.' + match[1]);
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function tryReadText(path) {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+async function fileExists(p) {
+  try { await stat(p); return true; } catch { return false; }
+}
+
+async function isFile(p) {
+  try {
+    const s = await stat(p);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function tryReadJson(path) {
+  try {
+    const text = await readFile(path, 'utf-8');
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
diff --git a/skills/vercel/vercel-optimize/metadata.json b/skills/vercel/vercel-optimize/metadata.json
new file mode 100644
index 0000000..8287bad
--- /dev/null
+++ b/skills/vercel/vercel-optimize/metadata.json
@@ -0,0 +1,14 @@
+{
+  "version": "1.2.0",
+  "organization": "Vercel Engineering",
+  "date": "May 2026",
+  "abstract": "Deep cost and performance optimization for supported Vercel projects. Pulls observability metrics, billing, and project config from the Vercel CLI, then investigates the codebase only where those metrics point. Produces ranked, verified recommendations with before/after code grounded in version-aware documentation citations. Avoids precise dollar projections (cost framed as order-of-magnitude) and avoids invented documentation URLs (curated allow-list).",
+  "references": [
+    "https://vercel.com/docs/cli/metrics",
+    "https://vercel.com/docs/cli/usage",
+    "https://vercel.com/docs/cli/api",
+    "https://vercel.com/docs/observability/observability-plus",
+    "https://nextjs.org/docs/app/building-your-application/caching",
+    "https://vercel.com/docs/frameworks/full-stack/sveltekit"
+  ]
+}
diff --git a/skills/vercel/vercel-optimize/references/candidates.md b/skills/vercel/vercel-optimize/references/candidates.md
new file mode 100644
index 0000000..9bcc87f
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/candidates.md
@@ -0,0 +1,176 @@
+<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->
+<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->
+<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->
+
+# Candidate gates
+
+The deterministic threshold expressions that turn observability signals into investigation candidates. Pure JS, no LLM. Thresholds live in `lib/gates/*.mjs`.
+
+Total gates: 15. Budget cap: `MAX_CODE_CANDIDATES = 6`. Gate version: `1.8.0`.
+
+## Gates
+
+### `build_minutes_fanout`
+
+- **Threshold**: `Build Minutes share > 0.15 OR turbo-force-bypass finding present`
+- **Billing dimension**: build
+- **Scope**: account
+- **Source citation**: `vercel-optimize gate threshold`
+
+Build Minutes line dominates the bill or Turborepo cache is bypassed. On monorepos, unchanged work should be skipped through Vercel skip-unaffected behavior, a verified Ignored Build Step, and a complete Turbo cache contract.
+
+---
+
+### `cold_start`
+
+- **Threshold**: `coldPct > 0.4 AND total >= 1000`
+- **Billing dimension**: function-duration
+- **Scope**: route
+- **Source citation**: `vercel-optimize gate threshold`
+
+Routes where > 40% of invocations are cold-start, at meaningful traffic (>=1,000 total invocations in window). Cold starts add 200-800ms per request and break the perceived latency budget on cache-miss paths. The 40% threshold is where cold-rate becomes a real signal vs Poisson noise on serverless. Sourced from vercel.function_invocation.count grouped by function_start_type.
+
+---
+
+### `cwv_poor`
+
+- **Threshold**: `LCP p75>2500 OR INP p75>200 OR CLS p75>0.1, AND speed_insights count > 50`
+- **Billing dimension**: speed-insights
+- **Scope**: route
+- **Source citation**: `https://web.dev/articles/vitals`
+
+Routes where Core Web Vitals fall into Google's "Poor" band on real-user traffic. LCP > 2500ms, INP > 200ms, or CLS > 0.1 each hurt SEO and conversion. Surfaces one candidate per (route, metric) pair to keep recommendations focused.
+
+---
+
+### `external_api_slow`
+
+- **Threshold**: `p75Ms > 2000 AND callCount >= 500`
+- **Billing dimension**: function-duration
+- **Scope**: route
+- **Source citation**: `vercel-optimize gate threshold`
+
+External API hostnames with p75 latency above 2 seconds AND at least 500 calls in the window. External API latency is a primary driver of function duration cost when the upstream is on a hot path; a single slow stale call isn't worth recommending against.
+
+---
+
+### `isr_overrevalidation`
+
+- **Threshold**: `writes/reads > 0.5 AND writes > 100`
+- **Billing dimension**: isr
+- **Scope**: route
+- **Source citation**: `https://vercel.com/docs/incremental-static-regeneration`
+
+ISR routes with > 1 write per 2 reads. The revalidate interval is too aggressive relative to read traffic — many reads pay to regenerate. Investigate whether the page can tolerate a longer revalidate window or on-demand revalidation via revalidateTag.
+
+---
+
+### `middleware_heavy`
+
+- **Threshold**: `middlewareInv/totalInv > 0.5 AND middlewareInv > 1000`
+- **Billing dimension**: edge-requests
+- **Scope**: account
+- **Source citation**: `https://nextjs.org/docs/app/building-your-application/routing/middleware`
+
+Middleware invocations cover > 50% of total requests at non-trivial volume. The matcher is probably broader than necessary; narrow it to the paths that actually need auth/rewrites/headers.
+
+---
+
+### `observability_events_attribution`
+
+- **Threshold**: `observabilityEventsShare > 0.20 (critical at > 0.30)`
+- **Billing dimension**: observability-events
+- **Scope**: account
+- **Source citation**: `vercel-optimize gate threshold`
+
+Observability Events line item exceeds 20% of total billed cost. High share usually traces to low cache hit rate, middleware-heavy traffic, or unconstrained custom-span cardinality. No sampling lever exists for Observability Plus; reduce upstream invocations instead.
+
+---
+
+### `platform_bot_protection`
+
+- **Threshold**: `botIdEnabled=false AND (botPct >= 0.05 OR edge_cost >= $25/window OR requests >= 14k/14d)`
+- **Billing dimension**: edge-requests
+- **Scope**: account
+- **Source citation**: `vercel-optimize gate threshold`
+
+When BotID is disabled AND there is evidence (observed bot bandwidth share, edge cost, or substantial request volume) that bot traffic is non-trivial. Bot traffic inflates edge request counts without delivering user value; staged bot protection can reduce waste on bot-heavy projects. Skipped on quiet projects with no bot evidence — the recommendation would be noise.
+
+---
+
+### `platform_fluid_compute`
+
+- **Threshold**: `fluid=false AND (any cold_start signal OR any route with p95>1000ms AND inv>1000)`
+- **Billing dimension**: function-duration
+- **Scope**: account
+- **Source citation**: `vercel-optimize gate threshold`
+
+When Fluid Compute is disabled on a project that shows cold-start pressure (high cold-start rate) or sustained slow function p95 on hot routes. Fluid Compute reduces cold starts via instance reuse — recommend turning it on at the project level rather than per-route.
+
+---
+
+### `region_misconfig`
+
+- **Threshold**: `single-region pin found AND routes.length > 20 (scanner-only branch)`
+- **Billing dimension**: function-duration
+- **Scope**: account
+- **Source citation**: `vercel-optimize gate threshold`
+
+A single function region is pinned in `vercel.json` or per-route `preferredRegion`. Without per-region TTFB data (data gap), the gate can't quantify the geographic latency cost — but a single-region pin on a project with 20+ routes is worth auditing against Speed Insights traffic geo.
+
+---
+
+### `route_errors`
+
+- **Threshold**: `count > 250 OR (totalRequests >= 1000 AND errorRate > 0.01)`
+- **Billing dimension**: function-duration
+- **Scope**: route
+- **Source citation**: `vercel-optimize gate threshold`
+
+Routes producing > 250 5xx errors over the window, or with > 1% error rate on at least 1,000 total requests. Errored function invocations still bill at full duration; high error rates also poison user experience.
+
+---
+
+### `scanner-driven`
+
+- **Threshold**: `per-kind: scanner matches.length >= threshold`
+- **Billing dimension**: mixed
+- **Scope**: mixed
+- **Source citation**: `vercel-optimize gate threshold`
+
+Configured kinds emitted from scanner output. Each requires a minimum match count to avoid noise. Findings on cold-path or unmappable files are dropped unless the underlying scanner is trafficIndependent.
+
+---
+
+### `slow_route`
+
+- **Threshold**: `(p95 > 500 AND inv >= 1400) OR (p95 > 1500 AND inv >= 250); disqualified when 5xx rate > 50%; Vercel Workflow runtime endpoints are hard-gated`
+- **Billing dimension**: function-duration
+- **Scope**: route
+- **Source citation**: `vercel-optimize gate threshold`
+
+Routes with p95 function duration above 500ms at meaningful traffic (>=1,400 invocations in window), OR catastrophically slow routes (>1500ms p95 at any volume >=250). High duration drives both function-duration cost and user-perceived latency. Investigate sequential awaits, slow external APIs, missing caching, N+1 patterns. Routes with >50% 5xx rate are disqualified — those are reliability problems, not performance tuning targets, and surface via route_errors instead. Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`) are hard-gated before launch because long-running step/flow requests are expected orchestration, not app-route bottlenecks.
+
+---
+
+### `uncached_route`
+
+- **Threshold**: `requests > 500 AND hitRate < 0.5 AND getShare > 0.2 (missing getShare is gated)`
+- **Billing dimension**: edge-requests
+- **Scope**: route
+- **Source citation**: `vercel-optimize gate threshold`
+
+Routes serving > 500 requests/period at < 50% cache hit AND at least 20% GET traffic. Each uncached GET request reaches the function, costing edge requests + function duration. Routes that are mostly POST/PUT/DELETE (Server Actions, mutations) are skipped — 0% cache is correct behavior there. Routes with missing method-share data are gated instead of launched. Auth-gated routes are disqualified separately.
+
+---
+
+### `usage_spike_triage`
+
+- **Threshold**: `any-day total > 2x mean OR any-day SKU > 3x SKU mean`
+- **Billing dimension**: mixed
+- **Scope**: account
+- **Source citation**: `vercel-optimize gate threshold`
+
+A single day in the billing window deviates sharply from the window baseline. Triage branches: bot or AI crawler spike, viral moment, pricing-model migration (legacy SKU → new), code regression. Without daily-granularity data, this gate stays dormant.
+
+---
diff --git a/skills/vercel/vercel-optimize/references/data-collection.md b/skills/vercel/vercel-optimize/references/data-collection.md
new file mode 100644
index 0000000..140c787
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/data-collection.md
@@ -0,0 +1,218 @@
+# Data collection
+
+What the skill collects in Step 1, where each signal comes from, and how it degrades when a capability is missing.
+
+All shapes here are covered by sanitized CLI fixtures in `packages/vercel-optimize-tests/test/fixtures/real-cli-output/`.
+
+## Table of contents
+
+- [The `signals.json` shape](#the-signalsjson-shape)
+- [Per-signal source matrix](#per-signal-source-matrix)
+- [Error states and fallbacks](#error-states-and-fallbacks)
+- [Real JSON shapes](#real-json-shapes)
+- [Why we avoid stderr grep](#why-we-avoid-stderr-grep)
+
+## The `signals.json` shape
+
+`node scripts/collect-signals.mjs` emits the Vercel-side signal document. `node scripts/scan-codebase.mjs <repo-root>` emits the local codebase scan. `node scripts/merge-signals.mjs vercel-signals.json codebase.json --out signals.json` combines them into the artifact consumed by the gate, deep-dive, verifier, and renderer. The merge step also annotates scanner findings with route-level observability, `COLD-PATH`, or `NO-ROUTE-MAPPING`; scanner gates reject non-traffic-independent findings that do not carry one of those deterministic annotations.
+
+The merged `signals.json` has this top-level shape:
+
+```json
+{
+  "schemaVersion": "1.2",
+  "collectedAt": "2026-05-12T20:48:44.123Z",
+  "timeWindow": "14d",
+  "projectId": "prj_xxx",
+  "orgId": "team_xxx",
+  "projectIdSource": "repo.json" | "project.json" | "arg" | "env" | "arg+repo.json" | "arg+project.json" | "env+repo.json" | "env+project.json",
+  "commandScope": {
+    "ok": true,
+    "cliScope": "team-slug-or-username",
+    "source": "team-api" | "whoami-current-team" | "whoami-user" | "linked-org-scope" | "missing-org-scope",
+    "required": true,
+    "detail": "..."
+  },
+  "frameworkSupport": {
+    "ok": true,
+    "status": "supported" | "limited" | "unsupported",
+    "blocker": null | "unsupported_framework",
+    "framework": "next",
+    "label": "Next.js",
+    "detail": "..."
+  },
+  "frameworkSupportBlocker": null | "unsupported_framework",
+  "frameworkSupportDetail": "...",
+  "observabilityPlus": true | false | null,
+  "observabilityPlusPreflight": { /* CLI/API configuration probe result */ },
+  "observabilityPlusUsable": true | false | null,
+  "observabilityPlusBlocker": null | "no_oplus_probe" | "project_disabled" | "payment_required" | "forbidden" | "daily_quota_exceeded" | "project_not_found" | "not_linked" | "all_failed_other" | "no_traffic",
+  "observabilityPlusBlockerDetail": "...",
+  "plan": { "plan": "hobby" | "pro" | "enterprise" | "uncertain", "reason": "..." },
+  "project": { /* /v9/projects/:id response; team-owned projects include ?teamId */ },
+  "contract": { "context": "...", "commitments": [], "totalCommitments": 0 },
+  "usage": { /* vercel usage --format json --breakdown daily, or null */ },
+  "usageError": null | "USAGE_UNAVAILABLE" | "USAGE_CONTEXT_MISMATCH" | "NOT_COLLECTED_OBSERVABILITY_BLOCKED" | "NOT_COLLECTED_UNSUPPORTED_FRAMEWORK" | "EXIT_<n>" | "UNKNOWN",
+  "stack": { /* framework + version + router + ORM + monorepo */ },
+  "codebase": { /* scan-codebase output: stack + routes + findings */ },
+  "metrics": { /* per-metric query results (only when observabilityPlus=true) */ },
+  "metricsSchema": [ /* array of {id, description} */ ]
+}
+```
+
+All metric queries use the same `timeWindow` constant (`14d`) — defined as `TIME_WINDOW` in [lib/queries.mjs](../lib/queries.mjs) and covered by the repo test suite. Mixing windows silently produces incompatible rollups; never pin a per-query `since`.
+
+All Vercel CLI commands that accept scope must use `commandScope.cliScope` (`--scope <team-slug-or-username>`). Linked project files often contain raw `team_...` or `usr_...` IDs, but several CLI subcommands silently fall back to the current team when `--scope` receives a raw account ID. `collect-signals.mjs` resolves raw team IDs to slugs and raw user IDs to usernames before running `vercel metrics`, `vercel usage`, or `vercel contract`; `deep-dive.mjs` reuses the same scope for follow-up metric queries. If the project link lacks an owner account or the CLI-safe scope cannot be resolved, stop and ask the user which Vercel project and team/personal scope they want audited. Do not infer scope from the current `vercel whoami` team.
+
+Downstream consumers reference `signals.<field>` paths verbatim. Bumping `schemaVersion` is required when any consumed path is renamed or removed.
+
+## Per-signal source matrix
+
+| Signal | CLI command | Required for | Fallback when missing |
+|---|---|---|---|
+| Auth | `vercel whoami` | Everything | Exit with "run `vercel login`" |
+| CLI version | `vercel --version` | Everything | Exit with "upgrade to v53+" — v53 is the skill's compatibility floor |
+| Project ID + Org ID | `.vercel/repo.json` (newer) or `.vercel/project.json` (legacy) → `VERCEL_PROJECT_ID` + `VERCEL_ORG_ID` → argv. When the user passes a project ID and multi-project `repo.json` contains exactly one matching entry, the collector uses that entry's owner account. | Everything | Exit with "run `vercel link` or pass projectId". Multi-project `repo.json` without an explicit matching project ID, or any project ID without owner account scope, is ambiguous; ask the user to clarify the intended project/account |
+| Framework support | local `package.json` via `detectStack()` + `classifyFrameworkSupport()` | Code-backed route recommendations | Stop before metric fan-out on unsupported frameworks unless the user chooses `--continue-unsupported-framework` |
+| CLI command scope | `vercel whoami --format json`, then `vercel api /v2/teams/:orgId` when a linked `team_...` ID must be converted to a slug | Keeps `vercel metrics`, `vercel usage`, and `vercel contract` on the linked project's account instead of the user's current/personal scope | `PROJECT_SCOPE_UNRESOLVED` or `SCOPE_UNRESOLVED`; stop and ask the user to clarify the intended project/account, then re-link under the intended team or personal account |
+| Project/scope verification | `vercel api /v9/projects/:id?teamId=<orgId>` for team-owned projects; omit `teamId` for `usr_...` user-owned projects | Proves the resolved account can read the resolved project before Observability Plus or billing conclusions | `PROJECT_SCOPE_MISMATCH`; stop and ask the user to confirm the exact project and team/personal scope. Do not report Observability Plus as missing until this check passes |
+| Observability Plus configuration | Vercel CLI/API probe plus one metric access check; user-owned projects skip the team configuration endpoint and rely on the scoped metrics probe | All `metrics.*` signals | Stop early when the account lacks Observability Plus or this project is disabled |
+| Observability Plus metrics access | One canary `vercel metrics vercel.request.count --since 14d --limit 1`, then full fan-out only if it succeeds | All `metrics.*` signals | Set `observabilityPlusUsable=false` with blocker detail; emit a blocker document after project/scope verification but before billing collection unless `--continue-without-observability` is passed |
+| Project config | Verified project API response from project/scope verification | Fluid Compute, BotID, Speed Insights, security flags | Stop on ownership mismatch; otherwise gates that need missing optional fields skip |
+| Plan tier | `vercel api /v2/teams/:orgId` (or `/v2/user` for user-owned projects) → `billing.plan`, then scoped `vercel contract --format json` fallback → `inferPlan()` | Cost-context framing only | `plan="uncertain"`; cost magnitudes still computed from `usage.services[].billedCost` |
+| Billing usage | Scoped `vercel usage --format json --from <14d> --to <today>` with best-effort project grouping when supported by the installed CLI | Cost magnitude framing, billing-driven candidates | `null` + `usageError` set when queried and unavailable; `NOT_COLLECTED_*` when a preflight stop happened before billing collection |
+| Stack | local `package.json` + dir scan | Version-aware citation filtering, scanner gating | "unknown" framework → all framework-specific citations filtered |
+| `metrics.fnDurationP95ByRoute` | `vercel metrics vercel.function_invocation.function_duration_ms -a p95 --group-by route --since 14d` | `slow_route`, `platform_fluid_compute` gates | `{ok:false}`; gate emits no candidates |
+| `metrics.requestsByRouteCache` | `vercel metrics vercel.request.count --group-by route --group-by cache_result --since 14d` | `uncached_route`, traffic-total computation | `{ok:false}` |
+| `metrics.fnStatusByRoute` | `vercel metrics vercel.function_invocation.count --group-by route --group-by http_status --since 14d` | Canonical function-level 5xx source for `route_errors` and `slow_route` error disqualification | `{ok:false}`; fall back to `requestsByRouteStatus` only for older fixtures |
+| `metrics.requestsByRouteStatus` | `vercel metrics vercel.request.count --group-by route --group-by http_status --since 14d` | Compatibility fallback for request-level status | `{ok:false}` |
+| `metrics.externalApiP75` | `vercel metrics vercel.external_api_request.request_duration_ms -a p75 --group-by origin_hostname --since 14d` | `external_api_slow` gate | `{ok:false}` |
+| `metrics.fnStartTypeByRoute` | `vercel metrics vercel.function_invocation.count -a sum --group-by route --group-by function_start_type --since 14d` | `cold_start`, `platform_fluid_compute` | `{ok:false}`; gate dormant. **`function_start_type` ∈ {cold,hot,prewarmed}** is the public way to read cold-start rate on CLI v53.4.0+ (replaces the old "not derivable" gap). |
+| `metrics.fnGbHrByRoute` | `vercel metrics vercel.function_invocation.function_duration_gbhr -a sum --group-by route --since 14d` | Cost ranking / report breakdown | `{ok:false}` |
+| `metrics.fnCpuMsByRoute` | `vercel metrics vercel.function_invocation.function_cpu_time_ms -a sum --group-by route --since 14d` | Active CPU ranking (Fluid Compute billing unit) | `{ok:false}` |
+| `metrics.fnPeakMemoryByRoute` | `vercel metrics vercel.function_invocation.peak_memory_mb -a max --group-by route --since 14d` | `oversized_memory` gate | `{ok:false}` |
+| `metrics.fnProvisionedMemoryByRoute` | `vercel metrics vercel.function_invocation.provisioned_memory_mb -a max --group-by route --since 14d` | `oversized_memory` gate | `{ok:false}` |
+| `metrics.fnTtfbP95ByRoute` | `vercel metrics vercel.function_invocation.ttfb_ms -a p95 --group-by route --since 14d` | TTFB cross-check for slow routes | `{ok:false}` |
+| `metrics.fdtByRoute` | `vercel metrics vercel.request.fdt_total_bytes -a sum --group-by route --since 14d` | Bandwidth-cost ranking | `{ok:false}` |
+| `metrics.fdtByBot` | `vercel metrics vercel.request.fdt_total_bytes -a sum --group-by bot_category --since 14d` | Strengthens `platform_bot_protection` with observed bot bandwidth share | `{ok:false}`; gate falls back to config-only signal |
+| `metrics.fdtByCache` | `vercel metrics vercel.request.fdt_total_bytes -a sum --group-by cache_result --since 14d` | Uncached-bandwidth narrative | `{ok:false}` |
+| `metrics.middlewareCount` | `vercel metrics vercel.middleware_invocation.count -a sum --group-by request_path --since 14d` | `middleware_heavy` gate | `{ok:false}`; gate dormant |
+| `metrics.middlewareDurationP95` | `vercel metrics vercel.middleware_invocation.duration_ms -a p95 --group-by request_path --since 14d` | Middleware latency narrative | `{ok:false}` |
+| `metrics.isrReadsByRoute` | `vercel metrics vercel.isr_operation.read_units -a sum --group-by route --since 14d` | `isr_overrevalidation` gate (denominator) | `{ok:false}` |
+| `metrics.isrWritesByRoute` | `vercel metrics vercel.isr_operation.write_units -a sum --group-by route --since 14d` | `isr_overrevalidation` gate (numerator) | `{ok:false}` |
+
+**ISR read:write ratio caveat.** `isrReadsByRoute` exposes the **origin-tier** read count only. CDN-tier reads (regional cache hits that never reach the ISR origin) are not separately surfaced today and can dominate total read volume. Before flagging "writes > reads" as inverted, the gate and report must (a) acknowledge CDN-tier reads aren't included, (b) corroborate with `requestsByRouteCache` `cache_result=HIT` share before alarming. A high origin-write rate alone does not imply pathological over-revalidation if the CDN is absorbing the steady-state read traffic.
+| `metrics.imageCount`, `imageByHost`, `imageSourceBytes` | `vercel metrics vercel.image_transformation.*` | Image-optimization narrative | `{ok:false}` |
+| `metrics.cwvLcpByRoute`, `cwvInpByRoute`, `cwvClsByRoute`, `cwvTtfbByRoute`, `cwvCount`, `cwvCountByRoute` | `vercel metrics vercel.speed_insights_metric.*` (`p75` for vitals, `sum` for counts) `--since 14d` | `cwv_poor` gate | Empty when no Speed Insights measurements are returned for the 14-day window — gate stays dormant; do not infer disabled vs no traffic unless another signal proves it |
+| `metrics.firewallByAction` | `vercel metrics vercel.firewall_action.count -a sum --group-by waf_action --since 14d` | Bot-protection narrative; shows existing managed rule activity | `{ok:false}` |
+| `metrics.botIdChecks` | `vercel metrics vercel.bot_id_check.count -a sum --since 14d` | Confirms whether BotID is actively running | `{ok:false}` |
+| `metrics.externalApiCount`, `externalApiBytes` | `vercel metrics vercel.external_api_request.*` grouped by `origin_hostname` | External-dependency cost narrative | `{ok:false}` |
+
+## Error states and fallbacks
+
+`lib/vercel.mjs`'s `runVercelJson()` parses stdout as JSON first (the most reliable signal — the CLI emits structured error payloads even when exit code is non-zero), and only falls back to stderr substring matching when JSON parsing fails:
+
+| Code | Meaning | Skill behavior |
+|---|---|---|
+| `unsupported_framework` | Detected framework cannot reliably map Vercel route metrics back to source files | Stop before metric fan-out; ask whether to continue with a limited platform/scanner audit |
+| `PROJECT_SCOPE_UNRESOLVED` | The project was found without an owner account, or `.vercel/repo.json` contains multiple linked projects and no explicit matching project ID was supplied | Stop before `vercel metrics`, `vercel usage`, or `vercel contract`; ask the user which Vercel project and team/personal scope to audit |
+| `SCOPE_UNRESOLVED` | The linked project belongs to a specific team/user, but the collector could not resolve a CLI-safe `--scope` value | Stop before `vercel metrics`, `vercel usage`, or `vercel contract`; ask the user to switch/re-link with the correct team |
+| `PROJECT_SCOPE_MISMATCH` | The resolved team/personal account cannot read the resolved project, or the project API returns a different owner/project | Stop before Observability Plus, metrics, usage, or contract checks; ask the user to confirm the exact Vercel project and team/personal scope |
+| `no_oplus_probe` | Observability Plus not enabled on team | Stop before full metric fan-out; ask whether to enable Observability Plus or run scanner-only |
+| `project_disabled` | Observability Plus enabled for team but disabled for project | Stop before full metric fan-out; ask the user to enable Observability Plus for this project or continue scanner-only |
+| `daily_quota_exceeded` | Observability Plus query quota is exhausted for the day | Stop before full metric fan-out; tell the user to retry after the next UTC midnight reset or ask whether to continue scanner-only |
+| `USAGE_UNAVAILABLE` | `vercel usage` returned no Costs payload after billing usage was actually queried | `usage=null`; cost-tier gates emit lower-priority candidates; billing section of the report shows the exact usage error |
+| `PROJECT_NOT_FOUND` | `vercel api /v9/projects/<id>` 404 (typically wrong scope) | `project={error}`; platform gates that depend on project config skip; report flags the data gap |
+| `invalid_filter_dimension` / `invalid_dimension` | Metric query used a dimension the metric doesn't support | Metric returns `{ok:false, code, allowedValues}`; consumer can introspect and adjust |
+| `NOT_LINKED` | The app directory is not linked in the way `vercel metrics` requires | Run `vercel link --yes --project <project-name-or-id> --cwd <app-dir>`; add `--team <team-id-or-slug>` when known. Passing only `VERCEL_PROJECT_ID` is not enough for route metrics if cwd is unlinked |
+| `NOT_AUTH` | Session expired | Caller exits with "run `vercel login`" |
+| `FORBIDDEN` | 403 — role lacks permission | Skip that endpoint; continue with degraded signal; surface in report |
+| `RATE_LIMIT` | 429 from API | Treat as "missing data" (no retry implemented yet) |
+| `EXIT_N` | Anything else | Treat as missing data; continue |
+
+The skill never crashes the entire collection on a single endpoint failure. Every catch-block uses `?? null` or `?? {}` so the JSON output is always well-shaped.
+
+## Real JSON shapes
+
+### `vercel metrics <id> --format json`
+
+```jsonc
+{
+  "query": {
+    "metric": "vercel.request.count",
+    "aggregation": "sum",
+    "groupBy": ["route"],
+    "startTime": "2026-04-13T04:00:00.000Z",
+    "endTime": "2026-05-13T08:00:00.000Z",
+    "granularity": { "hours": 4 }
+  },
+  "summary": [
+    { "route": "/dashboard/[sessionId]", "vercel_request_count_sum": 4923 },
+    { "route": "/sw.js",               "vercel_request_count_sum": 872 }
+  ],
+  "data": [
+    { "timestamp": "2026-04-13T04:00:00.000Z", "vercel_request_count_sum": 0, "route": "/dashboard/[sessionId]" }
+    /* ... */
+  ],
+  "statistics": { "bytesRead": 10267, "rowsRead": 947, "dbTimeSeconds": 0 }
+}
+```
+
+Field naming rule: the metric ID's dots become underscores, and the aggregation suffix is appended — `vercel.request.count` + `sum` → `vercel_request_count_sum`. `lib/vercel.mjs::normalizeSummary()` flattens `summary[]` into `[{<dim>: v, ..., value: <n>}]`.
+
+### `vercel metrics schema --format json`
+
+Array of `{id, description}` entries — NOT an object. Many metric IDs in earlier docs don't exist: there is no `vercel.function.cold_starts`, no `vercel.cache.hits`. Cache state is the `cache_result` dimension on `vercel.request.count`.
+
+### `vercel metrics <id> --filter "<bad>"`
+
+```jsonc
+{
+  "error": {
+    "code": "invalid_filter_dimension",
+    "message": "Filter uses invalid dimension \"status\" for metric \"vercel.request.count\".",
+    "allowedValues": [ "asn_id", ..., "http_status", ..., "route" ]
+  }
+}
+```
+
+Status filtering uses `http_status` (not `status`). Both `http_status eq '500'` and `http_status ge 500` work.
+
+### `vercel api /v9/projects/<id>` / `?teamId=<orgId>`
+
+Top-level keys relevant to the skill (real, verified):
+- `framework` (string, e.g. `"nextjs"`)
+- `resourceConfig.fluid` (boolean) — **Fluid Compute toggle**
+- `defaultResourceConfig.fluid` — template for new functions
+- `security.botIdEnabled` (boolean) — **BotID toggle**
+- `security.managedRules.bot_filter` (`{active, action}`) — firewall rule
+- `speedInsights` (`{id, hasData}`)
+- `webAnalytics` (`{id}`) — installed but `features.webAnalytics` says enabled state
+- `nodeVersion` (e.g. `"22.x"`)
+
+Calling without `?teamId=` returns 404 when the project belongs to a team other than the user's `currentTeam`. For user-owned projects (`orgId` starts with `usr_`), omit `teamId` and let the CLI use the authenticated user context.
+
+### `vercel contract --format json`
+
+```jsonc
+{ "context": "example-team", "commitments": [], "totalCommitments": 0 }
+```
+
+The direct account billing record is the primary plan signal: `billing.plan` from `vercel api /v2/teams/:orgId` or `vercel api /v2/user` is expected to be `hobby`, `pro`, or `enterprise`.
+
+`vercel contract` is only a fallback. `commitments[]` field names are not stable, so `inferPlan()` tries `category`, `commitmentCategory`, and `type`; category `Spend` means Pro and `Usage` means Enterprise. Empty commitments no longer imply Hobby by themselves.
+
+### `vercel usage --format json`
+
+May return `Error: Costs not found (404)`. Treat that queried error as `USAGE_UNAVAILABLE` and degrade — the skill can still produce a useful report from metrics + scanner. Do not use this explanation when `usageError` is `NOT_COLLECTED_OBSERVABILITY_BLOCKED` or another `NOT_COLLECTED_*` value; those mean the audit stopped before `vercel usage` ran.
+
+## Why we avoid stderr grep
+
+CLI error message strings are not stable contracts — they can change between versions. Detecting `OPLUS_REQUIRED` by greping `stderr.includes('Observability Plus')` will break the moment Vercel rewords the message.
+
+`runVercelJson()` therefore:
+1. Always tries to **parse stdout as JSON** first. Most failures emit a structured `{error:{code,message,allowedValues}}` payload that's deterministic.
+2. Only falls back to a lower-case stderr substring match when stdout was not parseable JSON.
+3. Categorizes anything unrecognized as `EXIT_N` and treats it as "missing data, continue."
+
+The skill is correct without precise category detection. The categories exist to give the user better error messages, not to drive control flow.
diff --git a/skills/vercel/vercel-optimize/references/docs-library.json b/skills/vercel/vercel-optimize/references/docs-library.json
new file mode 100644
index 0000000..ad4e330
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/docs-library.json
@@ -0,0 +1,683 @@
+{
+  "$schema": "Curated documentation allow-list for the vercel-optimize skill. Entries are version-aware via applicableFrameworks (semver). The recommender prompt receives only the subset valid for the user's stack. Citations outside this allow-list are stripped by the unknown-citation sanitizer.",
+  "version": "1.1.1",
+  "lastVerified": "2026-05-26",
+  "schemaVersion": "1.0",
+  "applicableFrameworksSyntax": "Semver-style. '*' = any framework. 'next@*' = any Next.js. 'next@14' = Next 14.x. 'next@>=15.0.0' = Next 15+. Multiple via '||': 'next@14 || next@>=15.0.0'.",
+  "urls": [
+    {
+      "url": "https://vercel.com/docs/caching/cdn-cache",
+      "topic": "Vercel CDN Cache — cacheable response criteria, static file caching, dynamic response caching, and cache limits",
+      "appliesTo": ["uncached_route", "cache_header_gap"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/headers/request-headers",
+      "topic": "Vercel request headers — documented geolocation header names including country, country-region, city, latitude, longitude, timezone, and postal code",
+      "appliesTo": ["uncached_route", "cache_header_gap"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/caching/cache-control-headers",
+      "topic": "Cache-Control headers on Vercel — s-maxage, CDN-Cache-Control, Vercel-CDN-Cache-Control, stale-while-revalidate",
+      "appliesTo": ["uncached_route", "cache_header_gap"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/caching/runtime-cache",
+      "topic": "Runtime Cache — reuse repeated API, database, and expensive computation results from Vercel Functions",
+      "appliesTo": ["slow_route", "external_api_slow"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/fluid-compute",
+      "topic": "Fluid Compute — reduced cold starts, active CPU pricing, function instance reuse, memory right-sizing",
+      "appliesTo": ["cold_start", "platform_fluid_compute", "slow_route", "oversized_memory"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/configuring-functions/memory",
+      "topic": "Function memory configuration — Standard 2GB / Performance 4GB tiers, when to upgrade Performance, account-level setting",
+      "appliesTo": ["platform_fluid_compute"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/speed-insights",
+      "topic": "Vercel Speed Insights — LCP, INP, CLS, TTFB, FCP, FID on real-user traffic",
+      "appliesTo": ["cwv_poor"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://web.dev/articles/vitals",
+      "topic": "Core Web Vitals — LCP < 2500ms, INP < 200ms, CLS < 0.1 thresholds",
+      "appliesTo": ["cwv_poor"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://web.dev/articles/optimize-lcp",
+      "topic": "Optimize LCP — preload critical images, defer non-critical CSS, reduce server response",
+      "appliesTo": ["cwv_poor"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://web.dev/articles/optimize-inp",
+      "topic": "Optimize INP — break up long tasks, defer non-essential JavaScript",
+      "appliesTo": ["cwv_poor"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://web.dev/articles/optimize-cls",
+      "topic": "Optimize CLS — reserve space for images, fonts, ads; avoid layout-affecting injections",
+      "appliesTo": ["cwv_poor"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/vercel-firewall/vercel-waf/managed-rulesets",
+      "topic": "Vercel WAF managed rulesets — managed bot and AI-bot actions by ruleset",
+      "appliesTo": ["platform_bot_protection", "uncached_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/vercel-firewall/vercel-waf/custom-rules",
+      "topic": "Vercel WAF custom rules — log, deny, challenge, bypass, redirect, and persistent actions",
+      "appliesTo": ["platform_bot_protection", "uncached_route", "middleware_heavy"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions",
+      "topic": "Vercel Functions lifecycle — regions, memory, max duration, runtimes",
+      "appliesTo": ["slow_route", "cold_start", "route_errors"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/debug-slow-functions",
+      "topic": "Debugging slow functions — isolate external latency, cold starts, bundle size, initialization, memory, and connection pooling",
+      "appliesTo": ["slow_route", "cold_start", "external_api_slow"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package",
+      "topic": "@vercel/functions helpers — waitUntil for post-response work and attachDatabasePool for pool lifecycle",
+      "appliesTo": ["slow_route", "cold_start", "external_api_slow", "route_errors"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/limitations",
+      "topic": "Vercel Functions limits — duration, payload, runtime, and invocation constraints",
+      "appliesTo": ["cold_start", "route_errors", "slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/runtimes",
+      "topic": "Runtime selection — node, python, ruby, go (edge runtime deprecated per 2026 platform notes)",
+      "appliesTo": ["cold_start", "slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/incremental-static-regeneration",
+      "topic": "Incremental Static Regeneration — reads vs writes, revalidate timing, on-demand revalidation",
+      "appliesTo": ["isr_overrevalidation", "uncached_route"],
+      "applicableFrameworks": ["next@*", "sveltekit@*", "astro@*", "nuxt@*"]
+    },
+    {
+      "url": "https://vercel.com/docs/image-optimization",
+      "topic": "Image Optimization on Vercel — supported formats, transformations, billing",
+      "appliesTo": ["image_optimization"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/image-optimization/managing-image-optimization-costs",
+      "topic": "Managing Image Optimization usage and costs — reduce unnecessary transformations and cache misses",
+      "appliesTo": ["image_optimization"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/image-optimization/limits-and-pricing",
+      "topic": "Image Optimization limits and pricing — source format, dimensions, transformed image size, and billing dimensions",
+      "appliesTo": ["image_optimization"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/observability/observability-plus",
+      "topic": "Observability Plus — path-level metrics, p75 sort, and retention",
+      "appliesTo": ["platform_fluid_compute", "observability_events_attribution"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/monorepos",
+      "topic": "Monorepos — skip unaffected projects and ignored build step tradeoffs",
+      "appliesTo": ["build_minutes_fanout"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/builds",
+      "topic": "Builds — build infrastructure, monorepo build controls, concurrency, and queues",
+      "appliesTo": ["build_minutes_fanout"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://turborepo.dev/docs/crafting-your-repository/caching",
+      "topic": "Turborepo caching — task-level cache config, force flags, remote cache",
+      "appliesTo": ["build_minutes_fanout"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/regions",
+      "topic": "Vercel Functions regions — single vs multi-region, defaults, latency tradeoffs",
+      "appliesTo": ["region_misconfig"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/configuring-functions/region",
+      "topic": "Configuring function region — vercel.json regions, segment-level preferredRegion",
+      "appliesTo": ["region_misconfig"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/alerts",
+      "topic": "Alerts — per-metric alerting on routes/status/usage with supported destinations",
+      "appliesTo": ["observability_events_attribution", "usage_spike_triage"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/spend-management",
+      "topic": "Spend Management — usage thresholds, notifications, and project pause behavior",
+      "appliesTo": ["usage_spike_triage"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/cli/metrics",
+      "topic": "vercel metrics CLI — schema, query construction, OData filters",
+      "appliesTo": [],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/cli/usage",
+      "topic": "vercel usage CLI — billing line items, breakdown, effectiveCost vs billedCost",
+      "appliesTo": [],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/cli/inspect",
+      "topic": "vercel inspect — view a deployment's build logs, region, runtime, commit, creator",
+      "appliesTo": ["route_errors"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/manage-cdn-usage",
+      "topic": "Vercel Edge Network bandwidth — Fast Data Transfer, included quotas, overage pricing",
+      "appliesTo": ["large_static_asset", "uncached_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/runtimes/edge-runtime",
+      "topic": "Vercel Edge Runtime — supported APIs, constraints, incompatible modules (node:* builtins, native deps)",
+      "appliesTo": ["edge_heavy_import", "cold_start"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/bot-management",
+      "topic": "Vercel Bot Protection — enabling, false-positive handling, billing implications",
+      "appliesTo": ["platform_bot_protection"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/botid",
+      "topic": "BotID — invisible challenge, Basic and Deep Analysis modes, checkBotId, observability, and billing",
+      "appliesTo": ["platform_bot_protection"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/functions/limitations",
+      "topic": "Platform limits — function payload size, max duration, regional caps",
+      "appliesTo": ["route_errors", "slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/project-configuration",
+      "topic": "vercel.json configuration — functions, crons, rewrites, redirects, headers, regions",
+      "appliesTo": ["uncached_route", "cache_header_gap"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/routing/",
+      "topic": "Vercel routing — firewall, bulk redirects, project routes, deployment routes, middleware, and filesystem order",
+      "appliesTo": ["uncached_route", "middleware_heavy", "cache_header_gap"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/redirects/bulk-redirects/",
+      "topic": "Bulk Redirects — framework-agnostic large redirect tables processed before project routes",
+      "appliesTo": ["uncached_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/routing-middleware",
+      "topic": "Vercel Routing Middleware — intercept requests before rendering and keep matcher scope intentional",
+      "appliesTo": ["middleware_heavy"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/workflow",
+      "topic": "Vercel Workflow — beta durable workflows, observability, Workflow Steps/Storage pricing, and compute billing caveats",
+      "appliesTo": ["route_errors", "slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://workflow-sdk.dev/docs/foundations/starting-workflows",
+      "topic": "Workflow SDK starting workflows — start() returns after enqueueing, returnValue waits for completion, streams/status can be read later",
+      "appliesTo": ["route_errors", "slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://workflow-sdk.dev/docs/foundations/workflows-and-steps",
+      "topic": "Workflow SDK workflows and steps — workflow orchestration, step execution, persisted results, retries, sleep, and suspension",
+      "appliesTo": ["route_errors", "slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://workflow-sdk.dev/docs/foundations/streaming",
+      "topic": "Workflow SDK streaming — durable streams, getReadable startIndex, getWritable, lock release, stream close, and retry caveats",
+      "appliesTo": ["slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://workflow-sdk.dev/docs/ai/resumable-streams",
+      "topic": "Workflow SDK resumable streams — reconnecting AI chat streams with run IDs, stream startIndex, and tail-index headers",
+      "appliesTo": ["slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/queues",
+      "topic": "Vercel Queues — asynchronous task queues for background work decoupled from the request path",
+      "appliesTo": ["route_errors"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://vercel.com/docs/concepts/edge-network/regions",
+      "topic": "Vercel function regions — single-region default, multi-region, db proximity",
+      "appliesTo": ["slow_route"],
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config",
+      "topic": "App Router route segment config — dynamic, revalidate, runtime, fetchCache, dynamicParams",
+      "appliesTo": ["uncached_route", "rendering_candidate", "force-dynamic"],
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/file-conventions/route",
+      "topic": "Route Handlers — GET handler caching defaults, route segment config, and request handling",
+      "appliesTo": ["uncached_route", "cache_header_gap"],
+      "applicableFrameworks": ["next@>=13.2.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/image-response",
+      "topic": "ImageResponse — dynamic OG image response options including status and headers",
+      "appliesTo": ["uncached_route", "cache_header_gap"],
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/generate-static-params",
+      "topic": "generateStaticParams — pre-render dynamic routes at build time",
+      "appliesTo": ["uncached_route", "rendering_candidate"],
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/fetch",
+      "topic": "Next.js fetch — server-side cache and next.revalidate semantics for App Router data requests",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "cache_header_gap"],
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/unstable_cache",
+      "topic": "unstable_cache — Next.js 14/15 cache primitive (replaced in 16 by 'use cache')",
+      "appliesTo": ["uncached_route", "function-duration"],
+      "applicableFrameworks": ["next@14 || next@15"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/directives/use-cache",
+      "topic": "'use cache' directive — opt-in persistent cache (15+)",
+      "appliesTo": ["uncached_route", "function-duration"],
+      "applicableFrameworks": ["next@>=15.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/directives/use-cache-remote",
+      "topic": "'use cache: remote' directive — remote cache storage for shared cached data with Cache Components",
+      "appliesTo": ["external_api_slow"],
+      "applicableFrameworks": ["next@>=16.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/cacheLife",
+      "topic": "cacheLife() — TTL annotation for 'use cache' segments",
+      "appliesTo": ["uncached_route", "isr_overrevalidation"],
+      "applicableFrameworks": ["next@>=15.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/cacheTag",
+      "topic": "cacheTag() — tag-based invalidation for 'use cache'",
+      "appliesTo": ["uncached_route", "isr_overrevalidation"],
+      "applicableFrameworks": ["next@>=15.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/revalidateTag",
+      "topic": "revalidateTag — on-demand invalidation by tag",
+      "appliesTo": ["isr_overrevalidation"],
+      "applicableFrameworks": ["next@>=13.4.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/revalidatePath",
+      "topic": "revalidatePath — on-demand invalidation by route",
+      "appliesTo": ["isr_overrevalidation"],
+      "applicableFrameworks": ["next@>=13.4.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/functions/after",
+      "topic": "after() — non-blocking work post-response (15+)",
+      "appliesTo": ["function-duration", "slow_route"],
+      "applicableFrameworks": ["next@>=15.0.0"]
+    },
+    {
+      "url": "https://react.dev/reference/react/cache",
+      "topic": "React cache() — per-request memoization in Server Components",
+      "appliesTo": ["function-duration", "slow_route"],
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/components/image",
+      "topic": "next/image component — formats, sizes, priority, lazy loading",
+      "appliesTo": ["image_optimization", "cwv_poor"],
+      "applicableFrameworks": ["next@*"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/components/font",
+      "topic": "next/font — self-hosted fonts, no CLS, build-time optimization",
+      "appliesTo": ["bundle_candidate", "cwv_poor"],
+      "applicableFrameworks": ["next@>=13.2.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/components/script",
+      "topic": "next/script component — loading strategies for third-party scripts and App Router worker caveats",
+      "appliesTo": ["cwv_poor"],
+      "applicableFrameworks": ["next@*"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/guides/lazy-loading",
+      "topic": "next/dynamic — lazy-load heavy client components, SSR opt-out",
+      "appliesTo": ["bundle_candidate", "slow_route", "cwv_poor"],
+      "applicableFrameworks": ["next@*"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/building-your-application/caching",
+      "topic": "Next.js App Router caching model — full-route cache, data cache, request memoization",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "function-duration"],
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents",
+      "topic": "cacheComponents flag — explicit caching model for App Router prerendering and data access",
+      "appliesTo": ["rendering_candidate", "uncached_route"],
+      "applicableFrameworks": ["next@>=16.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/getting-started/caching",
+      "topic": "Cache Components caching guide — static shell, cached dynamic content, runtime dynamic content",
+      "appliesTo": ["rendering_candidate", "uncached_route"],
+      "applicableFrameworks": ["next@>=16.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/guides/migrating-to-cache-components",
+      "topic": "Migrating to Cache Components — route segment config replacements and static shell migration",
+      "appliesTo": ["rendering_candidate", "uncached_route"],
+      "applicableFrameworks": ["next@>=16.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/building-your-application/routing/middleware",
+      "topic": "Next.js middleware — matcher config, runtime, request modification",
+      "appliesTo": ["middleware-broad-matcher", "platform_bot_protection", "middleware_heavy"],
+      "applicableFrameworks": ["next@>=12.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering",
+      "topic": "Partial Prerendering (PPR) — combine static shell + dynamic streaming (15+ experimental, stable later)",
+      "appliesTo": ["rendering_candidate", "slow_route"],
+      "applicableFrameworks": ["next@>=15.0.0"]
+    },
+    {
+      "url": "https://nextjs.org/docs/app/building-your-application/optimizing/bundle-analyzer",
+      "topic": "@next/bundle-analyzer — diagnose oversized client bundles",
+      "appliesTo": ["bundle_candidate"],
+      "applicableFrameworks": ["next@*"]
+    },
+    {
+      "url": "https://vercel.com/docs/frameworks/full-stack/sveltekit",
+      "topic": "SvelteKit on Vercel — adapter config, ISR, split function bundling, regions, and runtime settings",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "cold_start", "slow_route"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://svelte.dev/docs/kit/adapter-vercel",
+      "topic": "SvelteKit adapter-vercel — ISR, split, regions, max duration, and image config",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "cold_start", "slow_route"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://svelte.dev/docs/kit/page-options",
+      "topic": "SvelteKit page options — prerender, SSR, CSR, and server route prerendering",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "rendering_candidate"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/adapter-vercel",
+      "topic": "SvelteKit Vercel adapter — runtime, isr, split, regions, maxDuration config",
+      "appliesTo": ["slow_route", "cold_start", "uncached_route"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/page-options",
+      "topic": "SvelteKit page options — prerender, ssr, csr",
+      "appliesTo": ["rendering_candidate", "uncached_route"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/load",
+      "topic": "SvelteKit load functions — server-side data loading patterns, parallel loads",
+      "appliesTo": ["slow_route", "function-duration"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/routing",
+      "topic": "SvelteKit routing — +page.svelte, +page.server.ts, +server.ts route handlers, +layout.svelte",
+      "appliesTo": ["slow_route", "uncached_route", "rendering_candidate"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/hooks",
+      "topic": "SvelteKit hooks — handle (request middleware), handleFetch (per-fetch interception), handleError",
+      "appliesTo": ["middleware_heavy", "uncached_route", "route_errors"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/form-actions",
+      "topic": "SvelteKit form actions — server-side form handling without separate API endpoints",
+      "appliesTo": ["slow_route", "uncached_route"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/state-management",
+      "topic": "SvelteKit state management — request-scoped state, locals, avoiding cross-request leakage",
+      "appliesTo": ["slow_route", "route_errors"],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/cli",
+      "topic": "SvelteKit CLI — build, preview, sync. Use `vite build` for production output that adapter-vercel consumes.",
+      "appliesTo": [],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://kit.svelte.dev/docs/migrating",
+      "topic": "SvelteKit migration guides — for users on older majors who may not have ISR / per-route prerender",
+      "appliesTo": [],
+      "applicableFrameworks": ["sveltekit@*"]
+    },
+    {
+      "url": "https://docs.astro.build/en/guides/integrations-guide/vercel/",
+      "topic": "Astro Vercel adapter — ISR, image services, edge middleware, runtime config",
+      "appliesTo": ["slow_route", "cold_start", "uncached_route", "isr_overrevalidation", "rendering_candidate", "middleware_heavy"],
+      "applicableFrameworks": ["astro@*"]
+    },
+    {
+      "url": "https://vercel.com/docs/frameworks/frontend/astro",
+      "topic": "Astro on Vercel — output modes, ISR, edge middleware, and image optimization",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "rendering_candidate", "middleware_heavy", "image_optimization"],
+      "applicableFrameworks": ["astro@*"]
+    },
+    {
+      "url": "https://docs.astro.build/en/guides/on-demand-rendering/",
+      "topic": "Astro on-demand rendering — output server mode and per-route prerender controls",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "rendering_candidate"],
+      "applicableFrameworks": ["astro@*"]
+    },
+    {
+      "url": "https://docs.astro.build/en/reference/configuration-reference/",
+      "topic": "Astro configuration — output mode (static/server/hybrid), prerender, integrations",
+      "appliesTo": ["rendering_candidate", "uncached_route"],
+      "applicableFrameworks": ["astro@*"]
+    },
+    {
+      "url": "https://docs.astro.build/en/guides/server-side-rendering/",
+      "topic": "Astro SSR — hybrid mode, prerender export, dynamic routes",
+      "appliesTo": ["slow_route", "uncached_route", "rendering_candidate"],
+      "applicableFrameworks": ["astro@*"]
+    },
+    {
+      "url": "https://nuxt.com/docs/getting-started/deployment#vercel",
+      "topic": "Nuxt on Vercel — deployment, runtime configuration, ISR support",
+      "appliesTo": ["slow_route", "cold_start", "uncached_route"],
+      "applicableFrameworks": ["nuxt@*"]
+    },
+    {
+      "url": "https://vercel.com/docs/frameworks/full-stack/nuxt",
+      "topic": "Nuxt on Vercel — routeRules ISR, Vercel cache integration, deployment, and runtime configuration",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "slow_route", "cold_start"],
+      "applicableFrameworks": ["nuxt@>=3.0.0"]
+    },
+    {
+      "url": "https://nuxt.com/docs/api/composables/use-fetch",
+      "topic": "Nuxt useFetch / useAsyncData — automatic deduplication, parallel data loads, cache options",
+      "appliesTo": ["slow_route", "function-duration"],
+      "applicableFrameworks": ["nuxt@*"]
+    },
+    {
+      "url": "https://nuxt.com/docs/4.x/api/utils/define-route-rules",
+      "topic": "Nuxt defineRouteRules — per-route prerender, ISR, SWR, headers, and rendering controls",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "rendering_candidate"],
+      "applicableFrameworks": ["nuxt@>=3.0.0"]
+    },
+    {
+      "url": "https://nuxt.com/docs/4.x/guide/concepts/rendering",
+      "topic": "Nuxt rendering modes — universal rendering, routeRules, prerendering, and hybrid rendering",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "rendering_candidate"],
+      "applicableFrameworks": ["nuxt@>=3.0.0"]
+    },
+    {
+      "url": "https://nuxt.com/docs/api/utils/define-route-rules",
+      "topic": "Nuxt route rules — per-route SSR/SSG/ISR/swr/cache config in nuxt.config.ts",
+      "appliesTo": ["uncached_route", "isr_overrevalidation", "rendering_candidate"],
+      "applicableFrameworks": ["nuxt@*"]
+    },
+    {
+      "url": "https://docs.astro.build/en/guides/integrations-guide/vercel/",
+      "topic": "Astro Vercel adapter — SSR, ISR, image optimization on Vercel",
+      "appliesTo": ["slow_route", "image_optimization"],
+      "applicableFrameworks": ["astro@*"]
+    },
+    {
+      "url": "https://nuxt.com/docs/getting-started/deployment#vercel",
+      "topic": "Nuxt on Vercel — Nitro preset, ISR, caching headers",
+      "appliesTo": ["uncached_route", "rendering_candidate"],
+      "applicableFrameworks": ["nuxt@*"]
+    }
+  ],
+  "ruleSkillRefs": [
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "async-parallel",
+      "topic": "Promise.all for independent awaits",
+      "applicableFrameworks": ["next@*", "react@*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "async-suspense-boundaries",
+      "topic": "Suspense for streaming content",
+      "applicableFrameworks": ["next@>=13.0.0", "react@>=18.0.0"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "bundle-barrel-imports",
+      "topic": "Avoid barrel files, prefer direct imports",
+      "applicableFrameworks": ["next@*", "react@*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "bundle-dynamic-imports",
+      "topic": "next/dynamic for heavy components",
+      "applicableFrameworks": ["next@*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "bundle-defer-third-party",
+      "topic": "Defer analytics/logging scripts post-hydration",
+      "applicableFrameworks": ["next@*", "react@*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "server-cache-react",
+      "topic": "React.cache() for request deduplication",
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "server-cache-lru",
+      "topic": "LRU for cross-request caching",
+      "applicableFrameworks": ["next@*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "server-after-nonblocking",
+      "topic": "after() for non-blocking work post-response",
+      "applicableFrameworks": ["next@>=15.0.0"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "server-parallel-fetching",
+      "topic": "Restructure server components for parallel fetches",
+      "applicableFrameworks": ["next@>=13.0.0"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "server-hoist-static-io",
+      "topic": "Hoist static I/O (fonts, logos) to module level",
+      "applicableFrameworks": ["next@*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "client-swr-dedup",
+      "topic": "SWR for client-side request deduplication",
+      "applicableFrameworks": ["next@*", "react@*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "rendering-content-visibility",
+      "topic": "content-visibility for long lists",
+      "applicableFrameworks": ["*"]
+    },
+    {
+      "skill": "vercel-react-best-practices",
+      "rule": "rendering-resource-hints",
+      "topic": "React DOM resource hints for preloading",
+      "applicableFrameworks": ["next@*", "react@*"]
+    }
+  ]
+}
diff --git a/skills/vercel/vercel-optimize/references/doctrine.md b/skills/vercel/vercel-optimize/references/doctrine.md
new file mode 100644
index 0000000..91428a3
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/doctrine.md
@@ -0,0 +1,105 @@
+# Doctrine
+
+The four non-negotiable rules that shape every action this skill takes. If a future change conflicts with one of these, the change is wrong.
+
+## Rule 1: Observability before investigation
+
+The skill never reads a source file without an observability signal pointing at it. Step 1 (`node scripts/collect-signals.mjs`) is always first. Nothing reads source code until `signals.json` exists.
+
+**Why this fails when skipped:** without metrics, the skill defaults to "grep the repo for known anti-patterns and complain." That produces noisy, low-impact recs that aren't tied to traffic, cost, or user pain. Metrics-first investigation keeps the skill focused on observed traffic, cost, and reliability signals.
+
+### Four-check first-pass (Enterprise)
+
+When `plan === 'enterprise'`, the gate run must surface these four checks before code-level recommendations. Field engineers confirm these are the highest-leverage account-level levers across every renewal audit:
+
+1. **Observability Plus enabled?** From `signals.observabilityPlus`. If false, the whole audit degrades; surface as a top-of-report item.
+2. **Reverse proxy in front?** Heuristic from response headers / CNAME chain (when collected). A non-Vercel CDN over Vercel ISR is usually a "dumb pipe" — wasted spend.
+3. **WAF rules enabled?** From `signals.project.security`. BotID + managed rules absent on a project with bot evidence is the most common cost spike.
+4. **ISR read:write ratio.** From `metrics.isrReadsByRoute` + `metrics.isrWritesByRoute`. Include CDN-tier reads (see [data-collection.md](data-collection.md)) before flagging "writes > reads."
+
+These checks anchor the Enterprise-tier report's opening narrative; code-level recs follow.
+
+## Rule 2: Deterministic gate before every sub-agent investigation
+
+`node scripts/gate-investigations.mjs` is a pure-JS, LLM-free function. It reads `signals.json` and outputs `{toLaunch, platform, gated}`. Same input always produces byte-identical output (modulo `appliedAt`).
+
+Every kind of candidate (uncached route, slow route, errors, cold starts, scanner findings, platform-level recs) has its threshold expression encoded as a `gate(signals) → Candidate[]` function in `lib/gates/<kind>.mjs`.
+
+**Failed gates surface in the final report**, under "Not investigated in this run," with the exact reason they were held back. This is the user-facing trust mechanism: you see what we considered and chose to skip, and the reason.
+
+**Why this matters:** the agent never decides "should I look at this route?" via LLM judgment. The threshold is mechanical. This eliminates the entire failure mode where the agent investigates routes it shouldn't (cold-path) and recommends fixes for routes that don't need them.
+
+## Rule 3: Candidate-bound investigation scope
+
+When the gate emits a candidate with `files: ['src/app/api/products/route.ts']`, the agent reads ONLY that file (and its imports as the chain unfolds). It does NOT `grep -r` across the repo.
+
+If you find yourself wanting to grep the whole codebase, stop and re-read the current candidate's `question` field. If the question doesn't constrain the search, the candidate is malformed — log it as `gated` and skip. Do NOT compensate with a wider search.
+
+**Why this matters:** the agent's job is to verify and explain the metric anomaly the gate found, not to do a general code review. Wandering investigations produce drift, hallucination, and recommendations untied to the cost and performance data.
+
+### Scanner findings (the supplementary signal)
+
+Static AST-grep scanners run in parallel with the metric-driven investigations. Their output is annotated with the per-file observability signal (`function invocations: 1.2M; 95th percentile duration: 850ms; cache hit rate: 0%` if the file maps to a hot route, `COLD-PATH` if it maps to a route with no traffic, `NO-ROUTE-MAPPING` if the file doesn't map to any route).
+
+**Default rule:** scanner findings on `COLD-PATH` or `NO-ROUTE-MAPPING` files are dropped. They become recs only if the pattern is *traffic-independent*: build configuration, middleware matcher, source maps in production, raw script tags, React Compiler config. These don't care about traffic — they affect every request equally or affect the build itself.
+
+The traffic-independent allow-list lives in each scanner's `metadata.trafficIndependent: boolean` field. Set it to `true` only when you can defend the claim.
+
+## Rule 4: Doc-grounded, version-aware recommendations — no hallucinations
+
+Every recommendation must carry at least one citation from `references/docs-library.json`. Anything else is dropped at sanitizer time.
+
+The library has two parts:
+- **URLs** — Vercel docs, Next.js docs, SvelteKit docs, etc. Each declares `applicableFrameworks` (e.g., `["next@>=15.0.0"]`).
+- **Cross-skill rule references** — by name only (`vercel-react-best-practices:async-parallel`). The agent's host resolves these.
+
+Three sanitizers enforce this:
+- `missing-citation` — drops recs with empty `citations[]`.
+- `unknown-citation` — strips URLs not in the library, marks `needsReview=true`.
+- `version-mismatch` — strips URLs whose `applicableFrameworks` doesn't match the project's framework@version (parsed from `package.json`).
+
+Two verifier claim types check it: `citation_in_library` (URL ∈ allow-list) and `citation_applies_to_version` (semver match).
+
+**Why this matters:** LLMs cite plausible-looking URLs that 404, or recommend Next 15 features to Next 13 users. Both are trust-killers. The allow-list closes the first failure mode; the `applicableFrameworks` field closes the second.
+
+### Performance citations cite observed data
+
+Every performance claim cites the actual observability datum from `signals.json` — e.g., `functionRoutes[/api/products].p95Ms=850`. Estimated improvements are framed as ranges grounded in the observed baseline: `"Reduce /api/products 95th percentile duration from 850ms toward ~250-400ms based on similar cached routes."` Never an unanchored claim.
+
+### Cost framing is magnitude, never precise
+
+Cost claims like `$340/mo` are forbidden. The dollar noise floor on projections is too high to justify precision. The `impactMagnitude({currentCost, impactTier})` helper maps to phrases like `"hundreds of dollars per month at current traffic"` (computed against the user's actual `vercel usage` data).
+
+The `$-strip` sanitizer enforces this at output time — any `$N` literal in customer-facing fields is stripped.
+
+Performance numbers stay precise because they're observed, not extrapolated. We trust observed metrics; we don't trust dollar projections.
+
+## What good looks like
+
+A good run produces:
+- A small number (5-15) of recommendations.
+- Every rec ties to a specific route or file plus a specific metric signal.
+- Every rec carries before/after code and ≥1 citation matching the user's framework version.
+- Cost framing uses magnitude phrases. Performance framing uses precise observed numbers.
+- The "Not investigated in this run" section explains every other signal we saw and why we chose not to dig (cache hit rate was below threshold, 95th percentile duration was already healthy, etc.).
+- No `$N/mo` strings, no fabricated URLs, no Next.js 15 features recommended to a Next.js 13 user.
+
+## What bad looks like (anti-patterns we will not ship)
+
+- Recommendations from grepping the repo for known anti-patterns, without checking traffic.
+- "Enable Fluid Compute" without a cold-start signal.
+- "Add caching to /api/users" when the route has cookies() and is auth-gated.
+- "Reduce the duration of `/.well-known/workflow/v1/step`" because a Workflow step is long-running. Workflow runtime endpoints are generated orchestration routes; high wall-clock duration there is expected unless a separate reliability/error signal points elsewhere.
+- "Fix `/api/chat/[id]/stream` because it has high duration" without proving the stream does avoidable pre-first-byte work, high active CPU, duplicate invocations, or movable post-response work.
+- "Save $340/mo by doing X" — invented precision.
+- Citations to URLs that don't exist or that describe Next.js features the user's version doesn't have.
+- Long lists of recs the user can't act on; every rec needs an evidence chain.
+
+## Out of scope
+
+The skill is bounded to runtime cost and performance optimization on Vercel-hosted projects. The following are explicit non-goals; if signals or scanner findings surface in these areas, route them out:
+
+- **Deployment artifact size** in isolation. Bundle size matters only when it shows up as runtime cost (cold start, FDT) or performance (LCP, INP). If the only effect is "the .next directory is large," it's not in scope.
+- **Build-time issues without runtime impact.** Slow builds, build-cache misses, monorepo build fan-out — these only enter scope when they show up as Build Minutes billing pressure (then they go through the `build-minutes-fanout` gate). A 6-minute build that completes successfully and ships a small artifact is not a target.
+- **Security advisories and credential rotation.** RCE in `next-mdx-remote`, leaked env vars, OIDC vs explicit-key auth hygiene — refer to a security skill, not this one. Exception: when a security setting is also a documented cost lever (BotID = bot traffic = edge cost), it enters via the `platform_bot_protection` gate.
+- **Commercial / billing-process trivia.** Discount sliders, seat reconciliation, contract renewal mechanics. The skill can quantify which SKU is expensive; it does not negotiate.
diff --git a/skills/vercel/vercel-optimize/references/observability-plus.md b/skills/vercel/vercel-optimize/references/observability-plus.md
new file mode 100644
index 0000000..908ca8c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/observability-plus.md
@@ -0,0 +1,108 @@
+# Observability Plus Stop-And-Ask
+
+Use this file only when `signals.observabilityPlusBlocker` is set. Do not silently continue into scanner-only mode unless the user chooses that path.
+
+## Why This Check Exists
+
+This is a data dependency, not an upgrade pitch. The skill ranks work by observed route behavior so it can separate hot, expensive paths from code that only looks suspicious. These gates need per-route metrics:
+
+| Gate | Required signal |
+|---|---|
+| `slow_route` | Function duration and invocation count by route |
+| `uncached_route` | Cache result and request count by route |
+| `cold_start` | Function start type by route |
+| `route_errors` | Function status by route |
+| `isr_overrevalidation` | ISR reads and writes by route |
+| `middleware_heavy` | Middleware invocations and duration |
+| `cwv_poor` | Core Web Vitals by route |
+| `platform_bot_protection` | Fast Data Transfer by bot category |
+
+Scanner-only mode can still catch traffic-independent code issues, but it cannot rank the hottest routes or prove cost impact. Make that tradeoff explicit before continuing.
+
+## User Template
+
+Render this template first, then wait for the user's choice. Replace only `<detail>`. Do not add a preface; the heading is the opening line.
+
+```md
+**Per-route metrics are unavailable.**
+
+<detail>
+
+This audit needs route-level metrics to rank fixes by observed latency, cache hit rate, error rate, cold-start rate, and Incremental Static Regeneration reads and writes. Without them, I can run a scanner-only audit for traffic-independent code issues, but I cannot tell which routes matter most or prove cost impact.
+
+Docs: https://vercel.com/docs/observability/observability-plus
+
+Choose one:
+1. Enable Observability Plus, then re-run the metric-backed audit.
+2. Continue in scanner-only mode for a limited audit.
+```
+
+If the host supports a structured question tool, use this exact customer-facing copy. Do not rewrite it.
+
+```json
+{
+  "question": "Enable Observability Plus and re-run, or continue with a limited scanner-only audit?",
+  "header": "Observability Plus",
+  "options": [
+    {
+      "label": "Enable and re-run",
+      "description": "Use route-level metrics to rank the routes that matter most for cost and performance."
+    },
+    {
+      "label": "Run scanner-only",
+      "description": "Check traffic-independent code patterns without route ranking or proven cost impact."
+    }
+  ]
+}
+```
+
+Use the full product name in this question. Do not abbreviate product names or metrics in customer-facing blocker copy.
+
+## After The User Chooses
+
+If the user chooses **Enable and re-run**, stop after this short response:
+
+```md
+Enable Observability Plus from the Vercel dashboard's Observability tab, then tell me to rerun. I'll restart the metric-backed audit once route-level metrics are available.
+```
+
+Do not include raw team IDs, org IDs, project IDs, pricing language, dashboard screenshots, or extra persuasion. The docs link in the blocker message already covers availability and billing details.
+
+If the user chooses **Run scanner-only**, continue with the scanner-only steps below.
+
+## Blocker Copy
+
+| Blocker | Detail |
+|---|---|
+| `payment_required` | `Detected: route-level metrics were recognized for this team, but these metric queries are not usable.` |
+| `no_oplus_probe` | `Detected: this team does not expose the route-level metrics this audit needs.` |
+| `not_linked` | `Detected: this app directory is not linked to a Vercel project.` |
+| `forbidden` | `Detected: the Vercel CLI is authenticated to a team that cannot read this project.` |
+| `project_not_found` | `Detected: the project ID is not visible to the authenticated team.` |
+| `project_disabled` | `Detected: route-level metrics are enabled for the team but disabled for this project.` |
+| `all_failed_other` | `Detected: every per-route metric query failed. Error code: <code>.` |
+
+For `not_linked`, do not use the Observability Plus template. Link the app directory first:
+
+```bash
+vercel link --yes --project <project-name-or-id> --cwd <app-dir>
+```
+
+Add `--team <team-id-or-slug>` when the team is known. If the user supplied both app path and project name, run the link command instead of asking them what to do.
+
+For `forbidden` and `project_not_found`, ask the user to confirm the exact Vercel project and team/personal scope before presenting the Observability Plus choice.
+
+For `project_disabled`, do not present it as a team subscription problem. Ask the user to enable Observability Plus for this project, then re-run.
+
+For `no_traffic`, do not use this template. Tell the user the project has no meaningful traffic in the 14-day window, then ask whether to run scanner-only mode now or come back after traffic accumulates.
+
+## Scanner-Only Mode
+
+If the user picks scanner-only mode:
+
+1. Re-run `node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"` if the current `signals.json` stopped at the fast blocker (`usageError=NOT_COLLECTED_OBSERVABILITY_BLOCKED` or `project=null`).
+2. Run code scanners.
+3. Launch only traffic-independent findings.
+4. Render a clear data gap: per-route metric gates were skipped because Observability Plus data was unavailable.
+
+Do not imply the scanner-only report is a complete optimization audit.
diff --git a/skills/vercel/vercel-optimize/references/playbooks/README.md b/skills/vercel/vercel-optimize/references/playbooks/README.md
new file mode 100644
index 0000000..35e7d99
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/README.md
@@ -0,0 +1,53 @@
+# Playbooks
+
+Application-profile-specific advice that shapes how recommendations are phrased and ordered. Playbooks never invent claims — every rec still traces to a verified candidate or finding. They tell the recommender what to emphasize when a project matches a profile.
+
+## How a playbook gets applied
+
+1. Step 1 detects the project's stack + dependencies.
+2. The recommender heuristics infer an application profile (best guess from frameworks + dep signals).
+3. The matching playbook(s) are included in the recommender's context.
+4. Recommendations are shaped: ordering tilts toward the profile's priority list; phrasing nods to profile-specific concerns.
+
+## Profile detection (best-effort heuristics)
+
+| Signals → | Profile |
+|---|---|
+| `@vercel/sandbox`, `@ai-sdk/*`, `ai`, `openai`, `@anthropic-ai/sdk` deps OR AI Gateway / Sandbox SKU active in `usage.services` | `ai-application` |
+| `stripe`, `@shopify/*`, `react-stripe-js`, "cart"/"checkout" routes | `ecommerce` |
+| `next-auth`, `clerk`, dashboard routes, multi-tenant headers | `saas` |
+| Only `pages/api/**` or `app/api/**`, no UI routes | `api-service` |
+| Heavy MDX / markdown, mostly static routes | `content-site` |
+| Lots of `/(marketing)/` route groups, A/B test deps | `marketing` |
+
+`ai-application` is checked first — AI-shaped customers often share routes with SaaS/ecommerce surfaces, but the billing shape (AI Gateway dominant) and remediation set (provider failover, sandbox reuse, OIDC keyless) belong to this profile.
+
+When detection is uncertain, no playbook is applied. The recommender works fine without one — the playbook is a tilt, not a requirement.
+
+## Playbook schema
+
+Each playbook is a Markdown file with a fixed shape so the recommender can parse it reliably. Required sections:
+
+```markdown
+# {Profile name}
+
+## Typical billing shape
+(Which dimensions dominate — e.g., "Edge Requests > Function Duration > Image Optimization")
+
+## Priority patterns
+(Ordered list of patterns this profile particularly benefits from)
+
+## Frequent gotchas
+(Anti-patterns specific to this profile)
+
+## Cross-references
+(Rec IDs from recommendations.md or rule names from vercel-react-best-practices)
+```
+
+## Contributing a new playbook
+
+1. Identify a clear application profile and one or two representative project profiles that exemplify it.
+2. Create `references/playbooks/<profile>.md` matching the schema.
+3. Add detection signals to the table above (the heuristics live in the recommender code; document them here).
+4. Update the playbook selection matrix in `references/scoring.md`.
+5. Run `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs`. No tests directly cover playbooks (they're content), but the schema validator runs in CI.
diff --git a/skills/vercel/vercel-optimize/references/playbooks/ai-application.md b/skills/vercel/vercel-optimize/references/playbooks/ai-application.md
new file mode 100644
index 0000000..038bf09
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/ai-application.md
@@ -0,0 +1,32 @@
+# AI application
+
+LLM-backed apps, agents, code-sandbox tools, RAG pipelines. Cost shape is dominated by per-token AI Gateway spend and Sandbox active-compute time, not edge requests or function duration. Many AI customers also have a SaaS surface (auth, dashboards), but the cost lever lives upstream of the dashboard.
+
+## Typical billing shape
+
+AI Gateway > Sandbox Active Compute > Function Duration > Function Invocations. Edge Requests usually quiet; ISR rarely applies. Observability Events can climb fast if every tool-call span is captured at full fidelity.
+
+## Priority patterns
+
+1. **Provider failover.** Configure AI Gateway with an active-active fallback chain across providers (OpenAI + Anthropic, or model-family pairs). Critical-path agents must not be single-provider — a 429 from one provider becomes a user-visible outage otherwise. Field example: MELI runs homegrown active-active routing because retry-on-error against a single provider degraded their NLP-on-support flow.
+2. **OIDC keyless auth, not explicit API keys.** In production, use the AI Gateway OIDC binding so requests are signed by deployment identity. In local dev, `vercel env run -- <cmd>` rotates OIDC each run. An explicit `AI_GATEWAY_API_KEY` in repo env vars is a regression — it bypasses keyless and creates a long-lived secret.
+3. **Sandbox reuse over per-request `Sandbox.create`.** Each fresh sandbox costs at least 1 minute of billed compute (boot + teardown rounded up). When isolation isn't required (single-tenant agents, shared workspaces), pool sandboxes by name (`sandbox.get(name)`) — auto-snapshot on death + auto-resume on next get is the persistence model.
+4. **`after()` / `waitUntil()` for tool logging.** Tool-call telemetry, audit writes, and analytics should never block the user response. Use `after()` (Next 15+) or `waitUntil()` from `@vercel/functions` for any write that doesn't affect the streamed response.
+5. **Fluid Compute for JIT/process warmth.** Streaming LLM responses benefit from warm processes; the GraphQL/Apollo JIT cache + persisted-document plans only pay back when processes survive across requests. Fluid is the default; disabling it on AI workloads is almost always wrong.
+
+## Frequent gotchas
+
+- **Single-provider lock-in.** "We're using AI Gateway" doesn't imply failover — the provider list still has to be configured. A single-provider gateway is a thinner wrapper, not multi-provider resilience.
+- **Sandbox-per-request.** `new Sandbox(...)` inside a per-request handler with no `id` argument creates a fresh microVM each time. Cheaper to pool when isolation allows.
+- **BYOK fallback cost invisible.** AI Gateway with BYOK silently falls back to system credits on 429 / provider outage; cost migrates from "free BYOK" to "billed credits" without a separate signal unless tracked.
+- **Observability Events runaway.** Captured every tool call + every streamed delta at 100% sampling — events SKU climbs above 30% of bill. Cap span cardinality before scaling traffic.
+
+## Cross-references
+
+- [external-api-critical-path](../support-topics/external-api-critical-path.md) — sequential vs parallel calls; AI Gateway is one external API among others
+- [fluid-compute-caveats](../support-topics/fluid-compute-caveats.md) — module-state hazards and shared-instance caveats
+- [function-duration-io-and-after](../support-topics/function-duration-io-and-after.md) — `after()` for post-response tool logging
+- [observability-events-cost-attribution](../support-topics/observability-events-cost-attribution.md) — when Observability Events climb above 20% of bill
+- [use-cache-remote-shared-origin-data](../support-topics/use-cache-remote-shared-origin-data.md) — caching shared LLM context or embedding lookups
+- `https://vercel.com/docs/ai-gateway` — provider configuration, failover chain
+- `https://vercel.com/docs/vercel-sandbox` — `sandbox.get(name)` and active-compute billing
diff --git a/skills/vercel/vercel-optimize/references/playbooks/api-service.md b/skills/vercel/vercel-optimize/references/playbooks/api-service.md
new file mode 100644
index 0000000..7cac110
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/api-service.md
@@ -0,0 +1,30 @@
+# API service
+
+Headless API backend. No UI routes. Often consumed by mobile apps, partner integrations, or other Vercel projects via rewrites.
+
+## Typical billing shape
+
+Function Duration dominates (every request is a function invocation). Edge Requests scale with API traffic. External API costs matter when the service is a thin shim over third-party APIs (Stripe, Twilio, etc.).
+
+## Priority patterns
+
+1. **Cache GET responses at the edge.** Idempotent GET endpoints (catalog reads, status checks, public data) should ship with `Cache-Control: public, s-maxage=<seconds>, stale-while-revalidate=<longer>`. The CDN serves repeat callers without invoking the function.
+2. **Rate-limit at the edge, not the function.** Middleware with proper matcher scoping handles abusive clients before they hit your function-duration bill.
+3. **Parallel external API calls.** A "checkout-like" endpoint that calls Stripe + inventory + email-service sequentially is the most common slow_route in this profile. `Promise.all` is the obvious fix.
+4. **Background work post-response.** `after()` (Next 15+) for analytics, webhooks-to-self, and any write that doesn't affect the response.
+5. **Connection pooling.** Direct PG connections from serverless function instances exhaust the database. Use PgBouncer / Prisma Accelerate / Neon's pooler.
+
+## Frequent gotchas
+
+- **No `Cache-Control` on the public GETs.** This is the most common finding in this profile, and the easiest fix.
+- **Auth check serialized with data load.** `await checkAuth()` then `await loadData()` — these are often independent and can run in parallel if your auth path doesn't depend on the data.
+- **External API fan-out for one user.** A "build me a profile" endpoint that calls 5 third parties sequentially. Even small latency improvements multiplied by every user are huge.
+- **Long-running async operations on the request path.** Image generation, PDF rendering, big report computation. Move these to background queues or `after()`.
+
+## Cross-references
+
+- `https://vercel.com/docs/caching/cdn-cache` — the GET-handler Cache-Control fix
+- `vercel-react-best-practices:async-parallel` — parallelize external API calls
+- `vercel-react-best-practices:server-after-nonblocking` — `after()` for post-response work
+- `https://vercel.com/docs/fluid-compute` — when cold starts on infrequently-called endpoints hurt
+- `https://nextjs.org/docs/app/building-your-application/routing/middleware` — for rate-limit middleware
diff --git a/skills/vercel/vercel-optimize/references/playbooks/content-site.md b/skills/vercel/vercel-optimize/references/playbooks/content-site.md
new file mode 100644
index 0000000..d4c1f68
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/content-site.md
@@ -0,0 +1,30 @@
+# Content site
+
+Documentation, blogs, knowledge bases, marketing-adjacent content with mostly static pages. Authoring may be headless-CMS-driven or markdown-in-repo.
+
+## Typical billing shape
+
+Edge Requests dominate (every page view is an edge request; static assets even more). Image Optimization is often the #2 line item. Function Duration tends to be low — most pages should be static or ISR.
+
+## Priority patterns
+
+1. **Pre-render everything that can be pre-rendered.** Blog index, individual posts, docs pages, category pages. Use `generateStaticParams` for App Router or `getStaticPaths` for Pages Router. Anything CMS-driven should run on a webhook revalidation, not on every request.
+2. **ISR with a sensible cadence.** Pages that need fresh-ish content but don't need real-time accuracy go ISR. `revalidate: 3600` (hourly) is a good starting point for docs; `60s` for blog index pages.
+3. **`next/image` for every image asset.** Hero images, author photos, post inline images, OG images. Even thumbnail-only sites benefit from format negotiation (WebP/AVIF).
+4. **`next/font` for self-hosted fonts.** Eliminates FOIT/FOUT, eliminates the third-party request, prevents CLS.
+5. **Prefetch on hover.** `next/link` does this by default. For other frameworks, consider intersection-observer-based prefetch on the visible link set.
+
+## Frequent gotchas
+
+- **`force-dynamic` on the blog index.** Almost never necessary. The index can ISR or be fully static.
+- **Markdown rendering on every request.** If you're parsing MDX at request time, you're paying function-duration cost on what should be a static asset. Build-time MDX → static HTML.
+- **Search rebuilt on every request.** Site search backed by a function that queries a CMS on every keystroke. Move to a search index (Algolia, Pagefind, build-time generated) and serve from the CDN.
+- **CMS preview routes leaking into production traffic.** A `/preview/[slug]` route that's effectively another rendering path; sometimes called from production by mistake. Audit referrers.
+
+## Cross-references
+
+- `https://nextjs.org/docs/app/api-reference/functions/generate-static-params` — for pre-rendering
+- `https://vercel.com/docs/incremental-static-regeneration` — for the ISR fix
+- `https://nextjs.org/docs/app/api-reference/components/image` — image optimization
+- `https://nextjs.org/docs/app/api-reference/components/font` — self-hosted fonts
+- `vercel-react-best-practices:bundle-defer-third-party` — defer analytics/cookie banners
diff --git a/skills/vercel/vercel-optimize/references/playbooks/ecommerce.md b/skills/vercel/vercel-optimize/references/playbooks/ecommerce.md
new file mode 100644
index 0000000..0942a97
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/ecommerce.md
@@ -0,0 +1,30 @@
+# E-commerce
+
+Storefronts with cart, checkout, product catalogs. Often Stripe-integrated. Traffic skews toward catalog browsing (cacheable) and checkout (uncacheable).
+
+## Typical billing shape
+
+Edge Requests dominate (catalog browsing, image asset traffic) → Image Optimization (product images) → Function Duration (cart/checkout APIs). ISR Reads matter when product pages use ISR.
+
+## Priority patterns
+
+1. **Catalog pages: aggressive ISR + image optimization.** Product list and product detail pages should be ISR with a sensible `revalidate` (60s-3600s). Every image should go through `next/image` (or the framework equivalent). For Vercel-hosted storefronts, image cost can dominate everything else.
+2. **Checkout: keep dynamic, but parallelize external calls.** Cart/checkout/payment routes are correctly dynamic. The win is in reducing their function duration — `Promise.all` for independent calls to Stripe + inventory + tax services. Cite `vercel-react-best-practices:async-parallel`.
+3. **Cart drawer hydration: lift `'use client'` to the leaf.** Cart components are interactive, but the page wrapping them shouldn't be. Hoist server-rendered parts upward; only the buttons/forms are client.
+4. **Webhooks: separate, not on the user path.** Stripe/Shopify webhook handlers should live as their own routes with short duration limits. They don't share traffic patterns with the storefront.
+5. **Edge middleware for A/B + region routing only.** Catalog locale routing is a fine fit. Auth/cart state belongs in the dynamic page, not middleware.
+
+## Frequent gotchas
+
+- **Product images served raw.** `<img src={product.imageUrl}>` for hundreds of variants costs more than the rest of the bill combined. Always next/image.
+- **`force-dynamic` on the storefront homepage.** Often added during development to test cart-state behavior, never removed. Audit ruthlessly.
+- **Sequential Stripe calls.** "Create customer" → "create subscription" → "create invoice" is often three sequential awaits where two could run in parallel.
+- **Bot traffic on product search.** Marketing-driven traffic + bot traffic on search routes inflates edge request cost. Bot Protection often pays for itself within a month.
+
+## Cross-references
+
+- `vercel-react-best-practices:async-parallel` — parallelize Stripe/inventory/tax calls in checkout
+- `vercel-react-best-practices:async-suspense-boundaries` — stream the checkout shell, fill cart drawer later
+- `vercel-react-best-practices:bundle-defer-third-party` — defer analytics (GA, Mixpanel) post-hydration
+- `https://nextjs.org/docs/app/api-reference/components/image` — for the catalog image fix
+- `https://vercel.com/docs/bot-management` — for bot traffic on search/product routes
diff --git a/skills/vercel/vercel-optimize/references/playbooks/marketing.md b/skills/vercel/vercel-optimize/references/playbooks/marketing.md
new file mode 100644
index 0000000..b9f8b6d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/marketing.md
@@ -0,0 +1,30 @@
+# Marketing site
+
+Landing pages, lead-capture forms, A/B-tested variants, region-routed homepages. Traffic is bursty (campaigns drive spikes). Bot traffic can be substantial.
+
+## Typical billing shape
+
+Edge Requests dominate. Image Optimization is high (hero images, illustrations, product screenshots). Bandwidth matters for video content. Function Duration is usually low — most pages are static or ISR.
+
+## Priority patterns
+
+1. **Aggressive caching at the edge.** Marketing pages rarely change between campaign updates. `Cache-Control: public, s-maxage=86400, stale-while-revalidate=604800` keeps the CDN warm for 24h and stale-serves for a week.
+2. **Bot Protection.** Marketing campaigns attract competitor scrapers and bot traffic that inflates edge requests without delivering value. If edge cost is > $100/month and Bot Protection is disabled, this is almost always the top platform rec.
+3. **ISR for content-driven sections.** Customer logos, testimonials, "latest blog post" widgets, pricing tables — anything coming from a CMS. Revalidate hourly or on webhook.
+4. **A/B test logic at the edge, not in the page.** Edge Middleware for the variant assignment; cached static page per variant. Don't render the variant choice on every request.
+5. **Defer all third-party JS post-hydration.** Analytics, chat widgets, marketing pixels, cookie banners. None of them block the LCP. Cite `vercel-react-best-practices:bundle-defer-third-party`.
+
+## Frequent gotchas
+
+- **Hero images served at native resolution.** A 4MP hero image on every viewport, including mobile. `next/image` with `sizes` is mandatory.
+- **Cookie banner blocks first paint.** GDPR-compliant cookie banners often render synchronously in the head. Defer; render after hydration; persist consent state via a tiny inline script.
+- **Tracking pixel waterfalls.** Three different analytics services loaded in a chain. Load them after hydration in parallel; better yet, replace some with server-side tracking via webhook.
+- **`/api/contact` is the only function but runs hot.** Marketing sites are mostly static but the contact form gets bot-spammed. Rate limit at middleware; consider a queue for outgoing emails.
+
+## Cross-references
+
+- `https://vercel.com/docs/bot-management` — almost always the right platform rec
+- `https://vercel.com/docs/incremental-static-regeneration` — for CMS-driven sections
+- `https://nextjs.org/docs/app/api-reference/components/image` — hero/illustration optimization
+- `vercel-react-best-practices:bundle-defer-third-party` — defer analytics/pixels
+- `https://nextjs.org/docs/app/building-your-application/routing/middleware` — A/B variant routing at the edge
diff --git a/skills/vercel/vercel-optimize/references/playbooks/saas.md b/skills/vercel/vercel-optimize/references/playbooks/saas.md
new file mode 100644
index 0000000..6337377
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/saas.md
@@ -0,0 +1,31 @@
+# SaaS
+
+Multi-tenant applications with authenticated dashboards, settings, billing. Auth-gated by default. Traffic skews toward function duration (per-user data fetches) over edge requests.
+
+## Typical billing shape
+
+Function Duration dominates (every dashboard request runs the function fully — no edge caching for auth-gated content). Edge Requests grow with API surface. ISR rarely applies. Image Optimization rarely material.
+
+## Priority patterns
+
+1. **Per-request memoization with React.cache().** Server Components called from multiple places in the same request tree often re-query the database. `React.cache()` dedupes within the request. Cite `vercel-react-best-practices:server-cache-react`.
+2. **Parallel data loads in Server Components.** Dashboards typically load user + org + billing + recent-activity. Run all four in parallel via `Promise.all`. Cite `vercel-react-best-practices:async-parallel` and `:server-parallel-fetching`.
+3. **Fluid Compute.** Auth-gated routes have higher cold-start sensitivity (every cold start is a user waiting). If cold-start signal shows up in observability, Fluid Compute is usually the right account-level rec.
+4. **Async work after response.** Activity logs, audit trails, analytics events — anything that doesn't block the user — should run via `after()` (Next 15+) or `waitUntil()` from `@vercel/functions`. Cite `vercel-react-best-practices:server-after-nonblocking`.
+5. **Suspense boundaries around expensive widgets.** The dashboard shell renders fast; widgets stream in. This shifts perceived latency without changing the underlying queries.
+
+## Frequent gotchas
+
+- **N+1 ORM queries.** A list page that loops over results and fetches related records per-item. Especially common with Prisma's `.findUnique` inside a `.map`. Use `include` or batch via DataLoader.
+- **Sequential session+permission checks.** `await getSession()` then `await checkPermissions()` then `await loadData()` — these can often be parallelized when the permissions check doesn't depend on the data load.
+- **No connection pooling on serverless.** Prisma without a pooler exhausts the database under load. Connection pooling is mandatory.
+- **Polling for state from the client.** Every poll is a function invocation. Replace with SWR + on-demand revalidation, or with `revalidateTag` triggered by the mutation that actually changes state.
+
+## Cross-references
+
+- `vercel-react-best-practices:server-cache-react` — per-request dedup
+- `vercel-react-best-practices:server-parallel-fetching` — restructure for Promise.all
+- `vercel-react-best-practices:async-suspense-boundaries` — stream the dashboard shell
+- `vercel-react-best-practices:server-after-nonblocking` — defer audit/analytics writes (Next 15+)
+- `vercel-react-best-practices:client-swr-dedup` — replace polling with SWR
+- `https://vercel.com/docs/fluid-compute` — when cold starts hurt
diff --git a/skills/vercel/vercel-optimize/references/playbooks/sveltekit.md b/skills/vercel/vercel-optimize/references/playbooks/sveltekit.md
new file mode 100644
index 0000000..e7ea0ad
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/playbooks/sveltekit.md
@@ -0,0 +1,75 @@
+# SvelteKit
+
+Framework-specific playbook for SvelteKit projects on Vercel. Applies in
+addition to whichever application-profile playbook fits (saas, ecommerce,
+content-site, etc.). SvelteKit-on-Vercel ships through
+`@sveltejs/adapter-vercel`, so most platform-level recs map to adapter
+config rather than per-route framework APIs.
+
+## Typical billing shape
+
+Function Duration dominates server-rendered routes (every `+page.server.ts`
+`load` + `+server.ts` POST handler runs as a function). Edge Requests grow
+with API surface (`+server.ts` and form actions). ISR is supported via the
+adapter; when enabled, it converts to a cache_result HIT after first render.
+Image Optimization is rarely a SvelteKit-specific lever (it's the same
+Vercel image service Next.js uses).
+
+## Priority patterns
+
+1. **Adapter ISR for cacheable content.** Routes that don't depend on
+   per-request data are still served as functions by default. The
+   adapter accepts an `isr: { expiration: 60 }` option per route (set
+   in `+page.server.ts` via `export const config`). This converts
+   function invocations to cache hits. Cite
+   `https://kit.svelte.dev/docs/adapter-vercel` +
+   `https://vercel.com/docs/incremental-static-regeneration`.
+2. **Prerender what's static.** `export const prerender = true` in
+   `+page.server.ts` or `+page.ts` moves a route from function to CDN.
+   Cite `https://kit.svelte.dev/docs/page-options`.
+3. **Parallel `load` fetches.** A `load` function with multiple
+   sequential `await fetch(...)` calls leaves wall-clock time on the
+   table — wrap them in `Promise.all` (or return promises directly
+   from `load`, which SvelteKit streams). Cite
+   `https://kit.svelte.dev/docs/load`.
+4. **Move per-request work to `+server.ts` action handlers and run
+   them via `fetch` from the client.** Reduces SSR cost when only a
+   slice of the page actually needs server data on every request.
+5. **`hooks.server.ts` matcher hygiene.** Like Next.js middleware, the
+   `handle` hook intercepts every request unless filtered. Heavy
+   `handle` code multiplies cost by request volume. Move work into the
+   specific route's `load` when only that route needs it.
+6. **Adapter runtime + region config.** Single-region default; if the
+   project's users skew to a different region, set `regions: [...]` on
+   the adapter to reduce TTFB by 100-300ms.
+
+## Frequent gotchas
+
+- **Per-route SSR when prerender would do.** Marketing pages, docs,
+  blog posts often end up as functions because nobody added
+  `prerender = true`. The scanner flags these.
+- **`+layout.server.ts` data fetches blocking every child route.**
+  Auth-check + user-load in a layout makes EVERY function invocation
+  wait on those queries — even routes that don't read user. Push
+  user-load into the routes that need it.
+- **Adapter version drift.** `adapter-vercel@5` adds new options (ISR,
+  split). `adapter-vercel@3` doesn't. The recommender must check the
+  installed version before suggesting `isr: ...`.
+- **`fetch` calls in `load` to your own SvelteKit routes.** SvelteKit
+  optimizes these into direct module calls during SSR, but only if
+  the URL is relative. A hardcoded `https://your-domain.tld/api/...`
+  defeats this optimization.
+- **No connection pooling on serverless.** Same as Next.js — Postgres
+  without a pooler exhausts the database under load.
+
+## Cross-references
+
+- `https://kit.svelte.dev/docs/adapter-vercel` — adapter config (ISR, regions, runtime)
+- `https://kit.svelte.dev/docs/page-options` — prerender, ssr, csr
+- `https://kit.svelte.dev/docs/load` — parallel fetches in load
+- `https://kit.svelte.dev/docs/routing` — file conventions
+- `https://kit.svelte.dev/docs/hooks` — handle / handleFetch
+- `https://kit.svelte.dev/docs/form-actions` — server-side form handling
+- `https://kit.svelte.dev/docs/state-management` — request-scoped state
+- `https://vercel.com/docs/incremental-static-regeneration` — ISR on Vercel
+- `https://vercel.com/docs/fluid-compute` — Fluid Compute (framework-agnostic)
diff --git a/skills/vercel/vercel-optimize/references/recommendations.md b/skills/vercel/vercel-optimize/references/recommendations.md
new file mode 100644
index 0000000..cd1ae07
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/recommendations.md
@@ -0,0 +1,203 @@
+# Recommendations
+
+How recommendations are shaped, written, sanitized, and graded.
+
+## Table of contents
+
+- [Schema](#schema)
+- [Writing rules](#writing-rules)
+- [The 12 sanitizers](#the-12-sanitizers)
+- [Envelope-unwrap recovery](#envelope-unwrap-recovery)
+- [Grading rubric](#grading-rubric)
+- [Next.js version awareness](#nextjs-version-awareness)
+
+## Schema
+
+Every recommendation is a JSON object matching this TypeScript shape:
+
+```ts
+interface Recommendation {
+  // Customer-facing
+  what: string;              // 1 line, lead with impact. Max 80 chars when feasible.
+  why: string;               // 1-2 sentences. Root cause. Cites codebase findings + counts.
+  fix: string;               // Step-by-step. Includes before/after code fences. Specific enough to implement.
+  bucket: 'cost' | 'performance' | 'reliability';
+  effort: 'low' | 'medium' | 'high';
+  affectedFiles: string[];   // Verified file paths, from candidate.files
+  currentBehavior: string;   // What the code does now (with snippet)
+  desiredBehavior: string;   // Target state (with snippet)
+  risk?: string;             // Optional: e.g., "Removing force-dynamic may serve stale data on /admin"
+  verify: string;            // How to confirm the fix worked. e.g., "Re-run `vercel metrics …` and watch p95"
+
+  // Impact (computed from impact-magnitude.mjs in Step 4)
+  impactLabel: {
+    performance?: string;    // PRECISE: "Reduce /api/products p95 from 850ms toward ~250-400ms"
+    costMagnitude?: 'negligible' | 'small' | 'medium' | 'large' | 'very-large';
+    costPhrase?: string;     // "hundreds of dollars per month at current traffic"
+    billingDimension?: string;
+    fractionReduced?: number;
+  };
+  impactTier: 'high' | 'medium' | 'low';
+  billingDimension?: 'edge-requests' | 'function-duration' | 'image-optimization' | 'isr-reads' | 'isr-writes' | 'bandwidth' | 'data-cache-reads' | 'cron-invocations' | string;
+
+  // Grounding
+  citations: string[];       // From references/docs-library.json allow-list. Required: ≥1 entry.
+  candidateRef?: string;     // The gate candidate this rec traces to (e.g., "uncached_route:/api/products")
+  findingRefs?: string[];    // File:line markers from verifiedFindings.json
+  appliesAlsoTo?: Array<{     // Added by dedup when matching recs collapse into one customer-facing item.
+    candidateRef?: string;
+    affectedFiles?: string[];
+    o11ySignal?: string;
+    what?: string;
+  }>;
+  corroborationCount?: number; // Number of matching verified recs folded into this item, including itself.
+
+  // Verifier output (computed in Step 3.6)
+  verification?: {
+    passRate: number;
+    failed: Array<{ type: string; text: string; reason: string }>;
+  };
+
+  // Sanitizer audit trail (computed in Step 3.4)
+  sanitizerTrail?: string[]; // ["$-strip:2", "version-mismatch:next@15+:1", ...]
+  needsReview?: boolean;     // Set when a sanitizer caught a hazard
+
+  // Grading (Step 3.5)
+  quality: {
+    specificity: number;     // 0-1
+    actionability: number;
+    grounding: number;
+    evidence: number;
+    overall: number;
+    grade: 'Excellent' | 'Good' | 'Fair' | 'Poor';
+  };
+}
+```
+
+## Writing rules
+
+The recommender prompt explicitly tells the agent to follow these rules. Sanitizers enforce them after generation.
+
+**Voice and tone** are governed by [`references/voice.md`](./voice.md). Read it before writing recommendation prose; it keeps reports direct, metric-grounded, and free of internal process terms.
+
+### Lead with impact
+
+The `what` field opens with the verb + the change, not the framing. Compare:
+
+- ❌ "Consider enabling caching on the /api/products route" (filler before substance)
+- ✅ "Add Cache-Control with s-maxage to /api/products" (verb-first, scope-explicit)
+
+### Cite codebase findings with line numbers
+
+The `why` must reference a verified finding from `verifiedFindings.json`:
+
+- ❌ "The route is uncached" (could apply anywhere)
+- ✅ "src/app/api/products/route.ts:22 returns Response without Cache-Control; observability shows 0% cache hit on 1.2M invocations/mo"
+
+### No $ literals in customer fields
+
+The user-mandated rule. `what`/`why`/`fix`/`impact`/`currentBehavior`/`desiredBehavior` must not contain `$N` money literals. Use magnitude framing from `impact-magnitude.mjs`.
+
+- ❌ "Save $340/mo by adding s-maxage"
+- ✅ "Hundreds of dollars per month at current traffic"
+- ✅ (precise performance) "Move 1.2M monthly invocations to the CDN; expect p95 to drop from 850ms toward ~50ms on cache hits"
+
+The `$-strip` sanitizer enforces this at output time, but the prompt should also instruct the LLM not to emit dollar literals in the first place.
+
+### Before/after code fences required
+
+`currentBehavior` shows the offending snippet. `desiredBehavior` shows the target. Language-tagged code fences. Keep both under ~20 lines.
+
+### Cite at least one URL from the library
+
+`citations[]` must contain at least one entry from `references/docs-library.json`. The `missing-citation` sanitizer drops uncited recs. The `unknown-citation` and `version-mismatch` sanitizers strip invalid citations.
+
+### Match the user's framework version
+
+Don't recommend `'use cache'` (Next 15+) to a Next 13 user. The recommender prompt receives only the citation subset valid for the user's stack — but the LLM can still hallucinate. The `version-mismatch` sanitizer catches stragglers.
+
+## The 12 sanitizers
+
+Each sanitizer records its action in `rec.sanitizerTrail` when it mutates a field. Tag format: `tag:detail`. Tags are lexically stable — downstream consumers grep them.
+
+| # | Sanitizer | Trigger | Action | Trail tag |
+|---|---|---|---|---|
+| 1 | `$-strip` | Money-literal regex in customer field | Replace with "the billed cost" | `$-strip:N` |
+| 2 | `vercel-directive-strip` | `stale-if-error` / `proxy-revalidate` in cache-control | Strip directive (Vercel CDN doesn't honor) | `vercel-directive-strip:directive` |
+| 3 | `rate-limit` | Concurrency × delay > known provider rate limit | Prepend caveat, set needsReview | `rate-limit:provider:prescribed/limit` |
+| 4 | `pre-release` | Fix enables `-rc`/`-beta`/`-canary` feature | Append "requires pre-release version" caveat | `pre-release:pkg@version` |
+| 5 | `middleware-conflict` | Rec targets route covered by middleware matcher | Append "Middleware {matcher} may intercept" caveat | `middleware-conflict:matcher` |
+| 6 | `undeclared-dep` | Fix imports a package not in package.json | Prepend "Add dependency first: npm i {pkg}" | `undeclared-dep:pkg` |
+| 7 | `count-correct` | Cited count > verified count, ground-truth known | Rewrite to "~N" with verified count | `count-correct:token:cited→actual` |
+| 8 | `count-strip` | Cited count > verified count, no ground truth | Rewrite to "a number of" | `count-strip:token` |
+| 9 | `rendering-mode-mislabel` | Rec blames ISR/SSR on a static page | Append warning, set needsReview | `rendering-mode-mislabel` |
+| 10 | `unknown-citation` | URL not in `references/docs-library.json` | Strip URL, set needsReview if all stripped | `unknown-citation:url` |
+| 11 | `version-mismatch` | URL's `applicableFrameworks` doesn't match stack | Strip URL, set needsReview if all stripped | `version-mismatch:url` |
+| 12 | `missing-citation` | `citations.length === 0` after other sanitizers | DROP rec entirely | (rec not emitted; counted at end) |
+
+The sanitizer order matters: dollar-strip runs first (cheap, deterministic), then content sanitizers, then citation sanitizers last. This guarantees citation count is computed against the final state.
+
+The `recordSanitizer(rec, tag)` helper is the single entry point — sanitizers MUST call it before mutating fields. Otherwise the audit trail rots.
+
+### Provider rate limits
+
+Used by sanitizer #3. These provider limits are public contract values:
+
+| Provider | Limit | Doc URL |
+|---|---|---|
+| Notion | 3 rps | https://developers.notion.com/reference/request-limits |
+| OpenAI | 30 rps | https://platform.openai.com/docs/guides/rate-limits |
+| Stripe | 100 rps | https://docs.stripe.com/rate-limits |
+| Anthropic | 10 rps | https://docs.anthropic.com/en/api/rate-limits |
+
+Tiers/plans differ; these are first-tier defaults. The sanitizer prepends a caveat if the rec prescribes higher concurrency.
+
+## Envelope-unwrap recovery
+
+Not a sanitizer — a recovery step. LLMs occasionally wrap their JSON output in an envelope:
+
+```json
+{ "data": { "recommendations": [...] } }
+{ "result": { "recommendations": [...] } }
+{ "insights": { "recommendations": [...] } }
+```
+
+`attemptManualRecovery` peels one wrapping layer before schema validation. Increments `hygieneCounters.envelopeUnwraps`. Logs the unwrap to the run log.
+
+This is the only "creative" parsing the skill does. Anything else that fails schema validation is rejected.
+
+## Grading rubric
+
+Each rec is scored on four axes, 0-1 each. Average → grade:
+
+| Axis | What it measures | Strong (1.0) signal |
+|---|---|---|
+| Specificity | Concrete files, line numbers, code snippets | Triple-backtick code fence OR inline code ≥10 chars + verified file path |
+| Actionability | Clear "do this then that" steps | Numbered steps; verbs present in each step; no "consider"/"might" |
+| Grounding | Claims trace to findings or metric data | `sourceIndex` matches a finding OR rec has affectedFiles + code fences (presumed evidence) |
+| Evidence | Numeric, observed claims | Count words (errors, queries, invocations) + units (% / ms / s / K / M) |
+
+Grade thresholds:
+- `Excellent` ≥ 0.85
+- `Good` 0.70 – 0.85
+- `Fair` 0.55 – 0.70
+- `Poor` < 0.55 → dropped at quality floor in Step 4
+
+## Next.js version awareness
+
+The recommender's citation library is filtered by `signals.json.stack.framework@frameworkVersion`. The agent should still self-check the version when picking which APIs to recommend:
+
+| Feature | Available | Notes |
+|---|---|---|
+| App Router | Next ≥ 13.0 | Default since 14 |
+| `generateStaticParams` | Next ≥ 13.0 | Replaces getStaticPaths for App Router |
+| Fetch `next: { revalidate }` | Next ≥ 13.0 | Note: default fetch caching flipped in Next 15 |
+| `unstable_cache` | Next 14-15 | Replaced by 'use cache' in 16 |
+| `'use cache'` directive | Next ≥ 15.0 | Persistent cache primitive |
+| `cacheLife()`, `cacheTag()` | Next ≥ 15.0 | Pairs with 'use cache' |
+| `after()` | Next ≥ 15.0 | Non-blocking post-response work |
+| Partial Prerendering | Next ≥ 15.0 | Stable target later — verify per release |
+| `revalidateTag` / `revalidatePath` | Next ≥ 13.4 | Tag-based on-demand invalidation |
+| `cookies()` / `headers()` async | Next ≥ 15.0 | Async pattern in 15+ |
+
+The skill's curated citation library encodes these constraints via `applicableFrameworks`. If a contributor adds a new Next.js feature URL, they MUST set the right semver range in `references/docs-library.json`.
diff --git a/skills/vercel/vercel-optimize/references/scanner-patterns.md b/skills/vercel/vercel-optimize/references/scanner-patterns.md
new file mode 100644
index 0000000..26ae4d1
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/scanner-patterns.md
@@ -0,0 +1,251 @@
+<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->
+<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->
+<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->
+
+# Scanner patterns
+
+AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.
+
+Total scanners: 15.
+
+## Patterns
+
+### `cache-components-suspense-dedupe` — 'use cache' with multiple Suspense boundaries on the same data
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Default `'use cache'` does not dedupe identical calls across separate `<Suspense>` boundaries on the same render. Each boundary re-invokes the cached function, multiplying function-duration cost and inflating ISR write churn when the output is large.
+
+**Fix.** Hoist the promise to the page level (`const dataPromise = fetchData()` at the top, passed down to each Suspense child) OR move the shared fetch into a `'use cache: remote'` data-access layer so cross-request and cross-boundary dedupe applies.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/directives/use-cache`
+- `https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents`
+- `https://nextjs.org/docs/app/guides/migrating-to-cache-components`
+
+---
+
+### `edge-heavy-import` — Heavy / node-only import inside edge-runtime file
+
+- **Severity**: high
+- **Billing dimension**: function-duration
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Edge runtime is a constrained sandbox with no node: builtins and a much smaller cold-start budget than Node functions. Heavy SDKs (sharp, @aws-sdk/*, @prisma/client, pg, puppeteer) either fail at deploy or inflate cold-start latency. Move the import to a Node runtime function, or replace with an edge-compatible alternative (e.g., neon-driver instead of pg).
+
+**Fix.** Either (a) drop the `export const runtime = 'edge'` so the route runs on Node (default in 2026), or (b) replace the heavy import with an edge-compatible alternative. For DB: use @neondatabase/serverless or @planetscale/database instead of pg/mysql2. For image: do the work in a Node route handler. For auth signing: use jose (Web Crypto) instead of jsonwebtoken.
+
+**Citations:**
+- `https://vercel.com/docs/functions/runtimes/edge-runtime`
+- `https://vercel.com/docs/fluid-compute`
+
+---
+
+### `force-dynamic` — export const dynamic = 'force-dynamic'
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** force-dynamic disables static + ISR rendering. The route runs the function on every request. Sometimes necessary (cookies, headers, real-time data), often a habit that costs function-duration and edge-requests at scale.
+
+**Fix.** Audit the route. If dynamic behavior comes from cookies()/headers()/searchParams, force-dynamic may be redundant — Next infers dynamic automatically. Consider revalidate / 'use cache' / generateStaticParams if any portion can be pre-rendered.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config`
+
+---
+
+### `headers-in-page` — Dynamic API call forcing dynamic rendering
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** headers(), cookies(), and draftMode() are dynamic APIs. Reading them in a page/layout makes the entire segment dynamic — no ISR, no static generation, and a function invocation on every request.
+
+**Fix.** Move the dynamic API call into a child Server Component that lives inside a Suspense boundary. The parent can stay static; only the leaf re-renders dynamically.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config`
+- `https://nextjs.org/docs/app/building-your-application/caching`
+
+---
+
+### `large-static-asset` — Large file in public/
+
+- **Severity**: medium
+- **Billing dimension**: bandwidth
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Static assets in `public/` over 500 KB ship as-is from the CDN. Whether the cost is meaningful depends on traffic, but the candidate is binary — the file is either needed at that size or it can be optimized (compressed image, video transcode, or moved off the critical path).
+
+**Fix.** Verify the asset is reachable on the customer-facing hot path. Then choose: (a) compress (convert PNG → AVIF/WebP; transcode MP4 to lower bitrate); (b) host externally (Vercel Blob, S3, or a media CDN with per-asset signed URLs); (c) lazy-load (defer to client-side fetch instead of bundling into initial HTML).
+
+**Citations:**
+- `https://vercel.com/docs/manage-cdn-usage`
+- `https://vercel.com/docs/image-optimization`
+
+---
+
+### `max-age-without-s-maxage` — Cache-Control: max-age without s-maxage
+
+- **Severity**: medium
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** max-age caches in the browser; s-maxage caches at the CDN. Without s-maxage, every uncached visitor request invokes the function. Adding s-maxage often cuts function invocations by 80%+ on read-heavy routes.
+
+**Fix.** Add s-maxage to the Cache-Control header. Example: Cache-Control: public, max-age=60, s-maxage=600, stale-while-revalidate=86400. Pair with explicit cache-bust strategy if content can change.
+
+**Citations:**
+- `https://vercel.com/docs/caching/cdn-cache`
+- `https://vercel.com/docs/caching/cache-control-headers`
+
+---
+
+### `middleware-broad-matcher` — Middleware matcher missing or too broad
+
+- **Severity**: high
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** middleware.ts without a config.matcher (or matcher: ["/(.*)"]) runs on every request including _next/static, _next/image, favicon.ico, and image asset fetches. Edge-request cost scales accordingly.
+
+**Fix.** Scope the matcher to actual application paths. Example: matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"]
+
+**Citations:**
+- `https://nextjs.org/docs/app/building-your-application/routing/middleware`
+
+---
+
+### `missing-cache-headers` — Cacheable route or fetch with no caching (Cache-Control absent or no-store)
+
+- **Severity**: medium
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Two antipatterns: (a) GET handlers without explicit Cache-Control headers serve uncached; (b) fetch() calls with cache:"no-store" or next:{revalidate:0} opt out of caching even on cacheable upstream data. For non-auth routes / fetches, both are leaving cache hits on the floor.
+
+**Fix.** For GET handlers: return a Response with Cache-Control: public, s-maxage=<seconds>, stale-while-revalidate=<window>. For fetch(): drop cache:"no-store" (use { next: { revalidate: <seconds> } } in Next.js) so the response is cached by the framework + CDN.
+
+**Citations:**
+- `https://vercel.com/docs/caching/cdn-cache`
+- `https://vercel.com/docs/caching/cache-control-headers`
+- `https://nextjs.org/docs/app/building-your-application/caching`
+
+---
+
+### `prisma-include-tree-bloat` — Deep Prisma include tree (3+ levels)
+
+- **Severity**: high
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Nested .include({ x: { include: { y: { include: { z: ... } } } } }) makes Prisma issue a single huge join that scales O(N*M*K). Function duration explodes, memory spikes, often causes timeouts.
+
+**Fix.** Replace with explicit .findMany() calls or scoped .include() of only what the consumer reads. Consider Prisma.select() to project specific fields. For lists, batch with DataLoader patterns.
+
+**Citations:**
+- `vercel-react-best-practices:server-parallel-fetching`
+
+---
+
+### `region-pin-in-config` — Function region pinned in config
+
+- **Severity**: low
+- **Billing dimension**: function-duration
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** vercel.json `regions` or per-route `preferredRegion` is set. If the pinned region is far from the dominant user geo (or far from a data source) p95 TTFB suffers. This scanner provides the configured-region signal so the region-misconfig gate can recommend an audit.
+
+**Fix.** Audit the pinned region against traffic geography (Speed Insights or Web Analytics by country) and data-source location. Consider multi-region if data lives in a fixed location and users are global; consider relocating if users are concentrated in one geography.
+
+**Citations:**
+- `https://vercel.com/docs/functions/configuring-functions/region`
+- `https://vercel.com/docs/functions/configuring-functions/region`
+
+---
+
+### `source-maps-production` — Source maps enabled in production
+
+- **Severity**: low
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** productionBrowserSourceMaps: true ships .map files in the production bundle, increasing transfer size 30-100% per visitor. Useful for error reporting via Sentry; not useful for users.
+
+**Fix.** Keep source maps generation but exclude them from the public bundle. Upload to your error tracker via build-time CI step; do not serve them with the deployment.
+
+**Citations:**
+- `https://nextjs.org/docs/messages/improper-devtool`
+
+---
+
+### `sveltekit-prerender-missing` — SvelteKit page without explicit prerender / ISR config
+
+- **Severity**: low
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** SvelteKit page or +page.server.ts is missing an explicit `prerender`, `ssr`, or adapter `config.isr` declaration. Default is per-request function execution — investigate whether the route could be prerendered or ISR-cached.
+
+**Fix.** If the page is static (no per-user / per-request data), add `export const prerender = true` in +page.ts or +page.server.ts. If the data refreshes on a schedule, prefer adapter-vercel's ISR option via `export const config = { isr: { expiration: 60 } }`.
+
+**Citations:**
+- `https://kit.svelte.dev/docs/page-options`
+- `https://kit.svelte.dev/docs/adapter-vercel`
+- `https://vercel.com/docs/incremental-static-regeneration`
+
+---
+
+### `turbo-force-bypass` — Turborepo cache bypass on a monorepo
+
+- **Severity**: high
+- **Billing dimension**: build
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Turborepo's per-task cache can be bypassed by an explicit force flag, a `cache: false` config, or missing build-skip configuration. Every commit can rebuild unchanged work; Build Minutes climb with project count.
+
+**Fix.** Remove `TURBO_FORCE=true` from build env/scripts unless intentional. Set `tasks.build.cache: true` in `turbo.json` (or remove the override), and include generated outputs in Turbo's cache contract. Prefer Vercel's skip-unaffected monorepo behavior when available; use `ignoreCommand` only when that setting cannot cover the project.
+
+**Citations:**
+- `https://vercel.com/docs/monorepos`
+- `https://vercel.com/docs/builds`
+- `https://turborepo.dev/docs/crafting-your-repository/caching`
+
+---
+
+### `unoptimized-image` — Image optimization gap (raw <img>, global flag, missing sizes, or SVG mis-routed)
+
+- **Severity**: high
+- **Billing dimension**: image-optimization
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Four shapes of image-cost waste: raw <img> tags bypass the framework Image component; `images.unoptimized: true` disables Vercel image optimization globally; <Image fill> without `sizes` forces serving the largest source variant; <Image src=".svg"> without `unoptimized` routes vector data through the raster pipeline.
+
+**Fix.** For raw <img>: switch to next/image, enhanced-img (SvelteKit), <Image /> (Astro), or NuxtImg. For global unoptimized:true: remove the flag unless the project is hosted outside Vercel. For fill without sizes: add `sizes="(max-width: 768px) 100vw, 50vw"` or whatever matches your layout. For SVG: add `unoptimized` so the raw SVG ships instead of rastering it.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/components/image`
+- `https://vercel.com/docs/image-optimization`
+
+---
+
+### `use-cache-date-stamp` — new Date() / Date.now() / Math.random() inside a 'use cache' file
+
+- **Severity**: high
+- **Billing dimension**: isr
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** `'use cache'` memoizes by argument identity AND prerender output. A timestamp baked into the cached output (`new Date().getFullYear()` in a footer, `Date.now()` in a payload field) forces a fresh ISR write on every regeneration even when the underlying data is unchanged. Random values have the same failure mode.
+
+**Fix.** Replace module-scope `new Date()` with a build-time constant (`const buildYear = new Date().getFullYear()`) or move per-request timestamps into a client component inside `useEffect`. Do not pass dates as arguments to `'use cache'` functions — they invalidate the cache every call.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/directives/use-cache`
+- `https://nextjs.org/docs/app/api-reference/functions/cacheLife`
+
+---
diff --git a/skills/vercel/vercel-optimize/references/scoring.md b/skills/vercel/vercel-optimize/references/scoring.md
new file mode 100644
index 0000000..a988493
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/scoring.md
@@ -0,0 +1,205 @@
+## Step 4 — Score and report
+
+This reference covers everything that happens after recommendations are drafted: quality floor, impact framing, sort order, the customer-facing report template, and the playbook selection matrix.
+
+## Table of contents
+
+- [Quality floor and prune rules](#quality-floor-and-prune-rules)
+- [Impact framing — the magnitude rule](#impact-framing--the-magnitude-rule)
+- [`impactLabel` schema](#impactlabel-schema)
+- [Sort order and platform-rec cap](#sort-order-and-platform-rec-cap)
+- [The customer-facing report template](#the-customer-facing-report-template)
+- [Playbook selection matrix](#playbook-selection-matrix)
+
+## Quality floor and prune rules
+
+| Rule | Value | Why |
+|---|---|---|
+| Drop recommendations with `quality.overall < 0.55` | Hard cutoff (raised from 0.4 in May 2026 audit) | Bad-grade recs erode trust faster than they help. 0.55 matches the Poor/Fair grade boundary; recs below this are "Poor" and shouldn't ship. |
+| Prune cap on findings | 30% of input | Stops the pruner from wiping the report when LLM merit-grades are noisy |
+| Platform-rec cap | 3 | Account-level recs (Fluid, Bot Protection, Speed Insights) only have room for the top three |
+| Quick-wins definition | `effort === 'low' AND priority > 40` | Surfaces fixes the user can ship in a single PR |
+| Savings floor (internal ranking only) | $5/mo equivalent | Below this, even a "high" tier impact translates to "negligible" magnitude |
+
+## Impact framing — the magnitude rule
+
+**Performance: be precise.** Use observed numbers. Example:
+
+> "Reduce /api/products p95 from 850ms toward ~250-400ms; cache hit would lift from 0% toward ~60% based on similar cached routes."
+
+Performance numbers come from `signals.json.metrics.*` — they're observed, not extrapolated. Cite the exact route + metric value.
+
+**Dollar cost: never precise.** Use MAGNITUDE BUCKETS via `lib/impact-magnitude.mjs`'s `impactMagnitude({currentCost, impactTier})`:
+
+| Estimated reduction (USD) | Magnitude | Customer-facing phrase |
+|---|---|---|
+| < $5 | `negligible` | "small cost impact at current traffic" |
+| $5 – $50 | `small` | "low-tens of dollars per month at current traffic" |
+| $50 – $500 | `medium` | "hundreds of dollars per month at current traffic" |
+| $500 – $5,000 | `large` | "low-thousands of dollars per month at current traffic" |
+| > $5,000 | `very-large` | "thousands+ of dollars per month at current traffic" |
+
+Reduction is computed as `currentCost × fraction` where `fraction = {high: 0.4, medium: 0.2, low: 0.1}[impactTier]`. The fraction is intentionally conservative — we'd rather under-promise than mislead.
+
+### Discountable vs non-discountable SKUs
+
+When the project is on a Flex Commit and the report frames savings against contract burndown, segment spend before phrasing. Field doctrine (May 2026): the Flex discount slider applies only to a subset of SKUs.
+
+| Discountable (slider applies) | Non-discountable (raw rate) |
+|---|---|
+| Seats | Build CPU Minutes |
+| Edge Requests | Fluid Active CPU |
+| Fast Data Transfer | Fluid Provisioned Memory |
+| Fast Origin Transfer | Raw Flex top-up |
+| Image Optimization | |
+| ISR Reads / Writes | |
+| Observability Events | |
+
+A recommendation that targets a non-discountable SKU should never frame savings as a percentage of contract; frame as absolute magnitude only. Conversely, a discountable-SKU recommendation may surface "applies to contract burndown" in the magnitude phrase.
+
+**Why magnitudes:**
+
+- Traffic varies. A "20% reduction in edge requests" is exact at today's traffic and meaningless next quarter.
+- Pricing changes. Vercel's billing rates move; precise dollar projections rot.
+- The user is smart. They'd rather see "hundreds of dollars per month" with a real metric backing it than `$340/mo` with a hand-wave behind it.
+- The `$-strip` sanitizer enforces this at output time. Any `$N` literal that slips into customer-facing fields is replaced with "the billed cost" before rendering.
+
+## `impactLabel` schema
+
+```ts
+type ImpactLabel = {
+  // PRECISE: performance recs
+  performance?: string;
+  // MAGNITUDE: cost recs
+  costMagnitude?: 'negligible' | 'small' | 'medium' | 'large' | 'very-large';
+  costPhrase?: string;
+  billingDimension?: string;   // 'Edge Requests' | 'Function Duration' | ...
+  fractionReduced?: number;    // 0.2 = ~20% — internal only, NOT rendered
+};
+```
+
+Cost recs render `costPhrase`. Performance recs render `performance`. Reliability recs frame impact as observed error/timeout reduction (e.g., "Cuts 5xx rate from 0.4% to <0.1% based on current traffic").
+
+When a rec spans buckets — e.g., a caching fix that reduces both cost AND latency — render both lines.
+
+## Sort order and platform-rec cap
+
+Internal sort key (never rendered): `priority = currentDimensionCost × fractionReduced × confidence`.
+
+The list of recs the customer sees is sorted by this priority. The platform recommendations section is capped at 3, sorted the same way.
+
+## The customer-facing report template
+
+The agent renders this as the final output of Step 4. The shape is fixed; the content comes from the merged signals + verified recommendations + the `gated[]` list from Step 2.
+
+```markdown
+# Vercel Optimization Report — {projectName}
+
+**Stack**: {framework}@{frameworkVersion} | {router} | {orm}
+**Plan**: {plan.plan} ({plan.reason})
+**Period**: {usage.period.from} → {usage.period.to}
+**Observability**: {observability status}
+
+## Cost breakdown
+
+| Service | Usage | Billed Cost |
+|---|---|---|
+| (non-zero rows from usage.services, sorted by billedCost desc) |
+
+Total billed: {usage.totals.billedCost} (we render the precise current cost — we just don't project future precise savings)
+
+Omit zero-cost service rows from the table at the same cent precision shown to customers. If every row has `$0.00` billed cost but `effectiveCost` / USD `pricingQuantity` is non-zero, explain that net billed cost is `$0.00` after included credits or allotments and show the effective usage cost table instead. If both billed and effective costs are `$0.00`, replace the table with a concise note that `vercel usage` returned a billing payload but every reported service cost was `$0.00` for the window.
+
+If `vercel usage` was queried and unavailable, the cost breakdown is replaced by an observability-derived cost ranking from `metrics.fnGbHrByRoute` + `metrics.fnCpuMsByRoute` + `metrics.fdtByRoute` when those metrics exist. These don't translate directly to dollars — they show *which routes consume the billable units* so the user knows what to attack first. If `usageError` is `NOT_COLLECTED_OBSERVABILITY_BLOCKED` or another `NOT_COLLECTED_*` value, say usage was not collected; do not describe it as a billing-plan or Costs-feature finding.
+
+Render Observability status from the actual collection state:
+- `Observability Plus enabled — per-route metrics included` when `observabilityPlusUsable=true`.
+- `Per-route metrics unavailable — audit paused before metric-backed route ranking` when an Observability Plus blocker stopped the run before billing/scanner collection.
+- `Per-route metrics unavailable — analysis based on billing + scanner findings` when the user accepted a limited audit and billing/scanner signals were collected.
+- `Per-route metrics unavailable — limited analysis based on scanner findings` when the user accepted a limited audit but billing usage was queried and unavailable.
+- `Not checked — audit paused at unsupported-framework preflight` when framework support stopped the run before the Observability Plus check.
+- `Not enabled — analysis based on billing + scanner findings` only for legacy/limited reports where Observability Plus is known false and billing/scanner signals exist.
+
+## Highest-impact recommendations
+
+For each high-priority rec, in order:
+1. **{route or file}** — {o11ySignal}
+1. **{readable candidate label}** — {readable metric labels}
+   - **What to do**: {rec.what}
+   - **Impact**: {impactLabel.performance ?? impactLabel.costPhrase}
+   - **Effort**: {rec.effort}
+   - **Citations**: {rec.citations}
+
+## Recommendations
+
+### High impact
+
+| # | Bucket | What | Impact | Effort | Citations |
+|---|---|---|---|---|---|
+
+### Medium impact
+### Low impact
+
+## Platform recommendations
+
+(account-level recs from gate, capped at 3)
+
+## Observations from investigation
+
+Non-recommendation findings from reconciliation or investigation: deployment regressions, route-error storms, metric mismatches, and other real signals that should not become speculative performance recommendations.
+
+Observations must not contain implementation-grade actions. If the suggested action says to enable, add, wrap, apply, move, configure, challenge, deny, or otherwise change code or project settings, the renderer must hold it back until it passes the ready-to-apply recommendation evidence bar. Customer-visible observations can ask for narrower evidence collection: inspect logs, compare deployments, check headers, or confirm cacheability.
+
+## Investigated, no change recommended
+
+Candidates that were checked but did not produce a supported recommendation. Use plain reasons; do not use "abstain" in customer-facing copy.
+
+| Candidate | Why no recommendation shipped |
+|---|---|
+| Slow route on /docs | Detailed metrics did not support a code change |
+
+## Not investigated in this run
+
+This section earns the user's trust. For every metric signal we considered but didn't act on, group by candidate type and reason:
+
+| Candidate type | Why not investigated | Targets | Count |
+|---|---|---|---:|
+| Low cache-hit route | hitRate 0.65 above threshold | /api/orders | 1 |
+| Slow route | left for a larger run | /api/docs<br>/api/learn | 2 |
+
+## Strengths
+
+(what the project is doing right — caching is healthy on routes X/Y/Z; Fluid Compute is enabled; etc.)
+
+## Data gaps
+
+(what we couldn't measure — Observability Plus disabled means no per-route latency, etc.)
+```
+
+Common data gaps to call out when the underlying metric returned empty rows. If the metric query failed (`ok=false`), say the metric was not usable with the code; do not convert failed queries into "no measurements" or "not used" claims.
+
+- **Core Web Vitals empty.** The Speed Insights metric returned no measurements for the 14-day window. The `cwv_poor` gate stayed dormant; no claims about LCP/INP/CLS are made.
+- **ISR empty.** Project doesn't use Incremental Static Regeneration. The `isr_overrevalidation` gate stayed dormant.
+- **Middleware empty.** No `middleware.ts` (or matcher excludes all observed traffic). The `middleware_heavy` gate stayed dormant.
+- **Image transformations empty.** No `next/image` usage or no images served in the window.
+- **BotID checks empty.** BotID is disabled — see the `platform_bot_protection` recommendation for the toggle.
+- **Cold-start data near-zero.** Fluid Compute may already be enabled, or the project's traffic pattern keeps warm instances available; the `cold_start` gate evaluates the data but emits no candidate.
+
+The "Not investigated in this run" section is critical. It comes directly from `gate.json` produced by the gate. It tells the user we considered everything; we didn't just pick the easy targets.
+
+## Playbook selection matrix
+
+The recommender selects 0-2 playbooks based on the project's `stack.applicationProfile` (inferred from frameworks + deps) and the top billing dimensions.
+
+| Application profile | Likely top dimensions | Apply playbooks |
+|---|---|---|
+| `ai-application` (AI SDK, AI Gateway, Sandbox usage) | AI Gateway, Sandbox Active Compute, Function Duration | `playbooks/ai-application.md` |
+| `ecommerce` (Stripe, Shopify, cart components) | Edge Requests, Function Duration | `playbooks/ecommerce.md` |
+| `saas` (auth, dashboards, multi-tenant) | Function Duration, Bandwidth | `playbooks/saas.md` |
+| `api-service` (mostly API routes, no UI) | Function Duration, Edge Requests | `playbooks/api-service.md` |
+| `content-site` (blog, docs, mostly static) | Edge Requests, Image Optimization | `playbooks/content-site.md` |
+| `marketing` (landing pages, A/B tests) | Edge Requests, ISR Reads | `playbooks/marketing.md` |
+
+`ai-application` is checked first in `inferPlaybook()` — an AI-heavy SaaS or AI commerce app shares the AI playbook's billing shape (AI Gateway dominant) and gotchas, not the dashboard or cart-checkout patterns.
+
+Playbooks shape phrasing and ordering of recommendations. They never invent claims — every rec must still trace back to verified findings.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/README.md b/skills/vercel/vercel-optimize/references/support-topics/README.md
new file mode 100644
index 0000000..cfa8eeb
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/README.md
@@ -0,0 +1,46 @@
+# Support Topics
+
+Support topics are small, candidate-scoped investigation guardrails injected into sub-agent briefs.
+
+They are not recommendations, gates, scanners, or broad documentation. A topic tells the investigator what evidence to check, what false positives to avoid, and when to abstain for one class of candidate.
+
+## Add A Topic
+
+Add one file: `references/support-topics/<id>.md`.
+
+The filename must match the `id`. Frontmatter uses a strict subset of YAML: one `key: value` per line, arrays as JSON arrays.
+
+```md
+---
+id: cdn-cache-auth-safety
+title: CDN cache auth safety
+status: active
+candidateKinds: ["uncached_route", "cache_header_gap"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/caching/cdn-cache"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+...
+
+## Evidence To Check
+...
+
+## Do Not Recommend When
+...
+
+## Verification
+...
+```
+
+## Rules
+
+- Every active topic must cite only URLs or skill-rule refs already present in `references/docs-library.json`.
+- Use `candidateKinds` to keep the topic narrow. Use `"*"` only for workflow/protocol topics that truly apply to every candidate.
+- Use optional `metrics` only when a topic applies to a specific candidate metric, such as `["LCP"]`, `["INP"]`, or `["CLS"]` for Core Web Vitals.
+- Use optional `routePatterns` as JavaScript regex source strings when a topic should appear only for specific candidate routes, such as `["(^|/)404$"]`.
+- Keep the body below `maxBriefChars`; the brief renderer caps selected topics before they reach the sub-agent.
+- Put URLs in frontmatter only. Topic bodies should describe checks and guardrails, not cite new sources.
+- Do not include internal repository paths, service names, pricing tables, exact savings claims, or framework APIs without version gating.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/astro-edge-middleware-scope.md b/skills/vercel/vercel-optimize/references/support-topics/astro-edge-middleware-scope.md
new file mode 100644
index 0000000..967ca82
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/astro-edge-middleware-scope.md
@@ -0,0 +1,22 @@
+---
+id: astro-edge-middleware-scope
+title: Astro edge middleware scope
+status: active
+candidateKinds: ["middleware_heavy"]
+frameworks: ["astro@*"]
+priority: 88
+citations: ["https://vercel.com/docs/frameworks/frontend/astro", "https://docs.astro.build/en/guides/integrations-guide/vercel/"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+Astro middleware can run at the edge for broad request sets. If middleware volume is high, prove which paths actually need interception.
+
+## Evidence To Check
+Use middleware invocation share and top paths. Inspect adapter middleware mode, middleware source, auth/redirect logic, and whether static assets, prerendered pages, or public pages are being intercepted.
+
+## Do Not Recommend When
+Do not bypass required auth, locale, header, or routing logic. Do not move global middleware work into every page when the current scope is already minimal.
+
+## Verification
+Name the middleware share, dominant paths, current middleware mode, and exact source or config line to narrow.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/astro-output-mode-and-isr.md b/skills/vercel/vercel-optimize/references/support-topics/astro-output-mode-and-isr.md
new file mode 100644
index 0000000..b9d0e36
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/astro-output-mode-and-isr.md
@@ -0,0 +1,22 @@
+---
+id: astro-output-mode-and-isr
+title: Astro output mode and ISR
+status: active
+candidateKinds: ["uncached_route", "rendering_candidate"]
+frameworks: ["astro@*"]
+priority: 90
+citations: ["https://vercel.com/docs/frameworks/frontend/astro", "https://docs.astro.build/en/guides/on-demand-rendering/", "https://docs.astro.build/en/reference/configuration-reference/"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Astro defaults to static output; `server` output makes pages render on demand unless route-level prerendering changes that. First decide whether the hot route truly needs SSR.
+
+## Evidence To Check
+Inspect `astro.config`, adapter options, `output`, route-level `prerender`, dynamic params, middleware, and whether the content is shared across visitors. Compare route cache result and request volume.
+
+## Do Not Recommend When
+Do not prerender or cache personalized, preview, cart, checkout, or auth-gated pages. Do not change output mode for the whole app when one route-level flag is enough.
+
+## Verification
+Name the Astro output mode, route-level prerender state, observed route signal, and exact config or page line.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/auth-preserving-parallelization.md b/skills/vercel/vercel-optimize/references/support-topics/auth-preserving-parallelization.md
new file mode 100644
index 0000000..f6ea6d5
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/auth-preserving-parallelization.md
@@ -0,0 +1,22 @@
+---
+id: auth-preserving-parallelization
+title: Authorization-preserving parallelization
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["*"]
+priority: 90
+citations: ["vercel-react-best-practices:async-parallel", "vercel-react-best-practices:server-parallel-fetching"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Parallelizing awaits is safe only when it does not move private data access ahead of the auth, ownership, tenant, or permission check protecting that data.
+
+## Evidence To Check
+List every awaited operation being reordered. If a private lookup currently runs after `getSession()`, an ownership query, a tenant check, or a redirect guard, prove the lookup itself enforces the same predicate before recommending `Promise.all`.
+
+## Do Not Recommend When
+Do not parallelize a private record fetch with the ownership check that authorizes that fetch. Instead, recommend combining the guard and data lookup into one query constrained by the authenticated user, tenant, or ownership key.
+
+## Verification
+The fix must preserve the sequential guard or replace it with a single authorized query. Do not promise a latency drop equal to a helper unless that helper duration was measured.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/bot-protection-product-guardrails.md b/skills/vercel/vercel-optimize/references/support-topics/bot-protection-product-guardrails.md
new file mode 100644
index 0000000..658f2ec
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/bot-protection-product-guardrails.md
@@ -0,0 +1,22 @@
+---
+id: bot-protection-product-guardrails
+title: Bot Protection product guardrails
+status: active
+candidateKinds: ["platform_bot_protection"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/bot-management", "https://vercel.com/docs/vercel-firewall/vercel-waf/managed-rulesets", "https://vercel.com/docs/vercel-firewall/vercel-waf/custom-rules", "https://vercel.com/docs/botid"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+Bot Protection recommendations must be grounded in observed automated traffic or meaningful edge-request scale.
+
+## Evidence To Check
+Check bot bandwidth share, edge request volume, existing WAF managed rules, and whether BotID or Bot Protection is already enabled. Prefer a staged Log to Challenge or Deny path for rules whose false-positive risk is not proven.
+
+## Do Not Recommend When
+Do not recommend disabling Vercel security products to reduce cost. Do not recommend Bot Protection for quiet projects with no bot evidence.
+
+## Verification
+State the observed bot share or scale signal, current protection state, and any existing log, challenge, deny, or BotID check.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/build-minutes-monorepo-fanout.md b/skills/vercel/vercel-optimize/references/support-topics/build-minutes-monorepo-fanout.md
new file mode 100644
index 0000000..56f1ce2
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/build-minutes-monorepo-fanout.md
@@ -0,0 +1,23 @@
+---
+id: build-minutes-monorepo-fanout
+title: Build Minutes monorepo fanout
+status: active
+candidateKinds: ["build_minutes_fanout"]
+frameworks: ["*"]
+scannerPatterns: ["turbo-force-bypass"]
+priority: 90
+citations: ["https://vercel.com/docs/monorepos", "https://vercel.com/docs/builds", "https://turborepo.dev/docs/crafting-your-repository/caching"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Build Minutes climbs when commits rebuild unchanged work. Common causes: `TURBO_FORCE`, `cache: false`, missing outputs, or disabled build-skip settings.
+
+## Evidence To Check
+Confirm Build Minutes share and scanner subtype. Inspect `package.json`, `turbo.json`, outputs, `.gitignore`, `vercel.json`, and project settings. If `build` runs migrations, split them into an uncached step before recommending Turbo build caching.
+
+## Do Not Recommend When
+Skip under 5% bill share with no scanner finding. Skip single-project repos and intentional CI-only force flags. Do not recommend `ignoreCommand` from repo grep alone; dashboard-only skip-unaffected may be better.
+
+## Verification
+Name the offending file and pattern. Recommend only the verified fix: cache a pure build task, add generated `outputs`, enable skip-unaffected builds, or add `ignoreCommand` only when needed.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/cache-components-static-shell-boundaries.md b/skills/vercel/vercel-optimize/references/support-topics/cache-components-static-shell-boundaries.md
new file mode 100644
index 0000000..aee0a9a
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/cache-components-static-shell-boundaries.md
@@ -0,0 +1,22 @@
+---
+id: cache-components-static-shell-boundaries
+title: Cache Components static shell boundaries
+status: active
+candidateKinds: ["rendering_candidate"]
+frameworks: ["next@>=16.0.0"]
+priority: 94
+citations: ["https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents", "https://nextjs.org/docs/app/getting-started/caching", "https://nextjs.org/docs/app/guides/migrating-to-cache-components"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+On Next.js 16 with Cache Components, avoid older segment-config advice. The right question is whether the route can keep a static shell while dynamic data moves behind explicit cached or runtime boundaries.
+
+## Evidence To Check
+Check `cacheComponents`, `use cache`, `cacheLife`, request-time APIs, Suspense boundaries, and scanner evidence such as `force-dynamic` or `headers-in-page`.
+
+## Do Not Recommend When
+Do not suggest `dynamic`, `revalidate`, or `fetchCache` as the primary fix when Cache Components is enabled. Do not cache request-personalized content.
+
+## Verification
+Name the Next.js version, Cache Components state, dynamic trigger, and the exact boundary or directive that can change.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/cache-components-suspense-dedupe-pitfall.md b/skills/vercel/vercel-optimize/references/support-topics/cache-components-suspense-dedupe-pitfall.md
new file mode 100644
index 0000000..5aacb91
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/cache-components-suspense-dedupe-pitfall.md
@@ -0,0 +1,23 @@
+---
+id: cache-components-suspense-dedupe-pitfall
+title: Cache Components Suspense dedupe pitfall
+status: active
+candidateKinds: ["cache_components_suspense_dedupe"]
+frameworks: ["next@>=16.0.0"]
+scannerPatterns: ["cache-components-suspense-dedupe"]
+priority: 87
+citations: ["https://nextjs.org/docs/app/api-reference/directives/use-cache", "https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents", "https://nextjs.org/docs/app/guides/migrating-to-cache-components"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Default `'use cache'` does not dedupe identical calls across separate `<Suspense>` boundaries on the same render. Each boundary re-invokes the cached function, multiplying function-duration and ISR write churn.
+
+## Evidence To Check
+Confirm the scanner finding's repeated fetch URL or helper name. Verify the call sites are within the same route segment and inside distinct `<Suspense>` boundaries. Cross-reference `fnDurationP95ByRoute` and `isrWritesByRoute` for the owning route.
+
+## Do Not Recommend When
+Skip if the repeated call is intentional (different parameters, different intent). Skip if the duplicate is in a single component body where in-request memoization already applies.
+
+## Verification
+Name the duplicated call, count, and either: (a) the page-level promise to hoist or (b) the function to move to `'use cache: remote'`.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/cdn-cache-auth-safety.md b/skills/vercel/vercel-optimize/references/support-topics/cdn-cache-auth-safety.md
new file mode 100644
index 0000000..7ee59d1
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/cdn-cache-auth-safety.md
@@ -0,0 +1,22 @@
+---
+id: cdn-cache-auth-safety
+title: CDN cache auth safety
+status: active
+candidateKinds: ["uncached_route", "cache_header_gap"]
+frameworks: ["*"]
+priority: 100
+citations: ["https://vercel.com/docs/caching/cdn-cache", "https://vercel.com/docs/caching/cache-control-headers", "https://vercel.com/docs/project-configuration"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Treat edge caching as a safety question first. The route must be a public, cacheable GET path before a shared-cache recommendation is allowed.
+
+## Evidence To Check
+Use `methodDistribution`, `cacheBreakdown`, and headers. Before `s-maxage`, rule out cookies, sessions, authorization, draft state, and user-specific data.
+
+## Do Not Recommend When
+Do not cache mutations, dashboards, account data, request-personalized responses, or routes whose value changes per viewer. Do not mix `private` with shared-cache directives.
+
+## Verification
+Name GET share, cache mix, file line, and policy: mechanism, scope, TTL/freshness, and `Vary`. If the right policy is `no-store`, emit no-change/observation.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/cold-start-initialization-bundle.md b/skills/vercel/vercel-optimize/references/support-topics/cold-start-initialization-bundle.md
new file mode 100644
index 0000000..c99c495
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/cold-start-initialization-bundle.md
@@ -0,0 +1,22 @@
+---
+id: cold-start-initialization-bundle
+title: Cold-start initialization and bundle weight
+status: active
+candidateKinds: ["cold_start"]
+frameworks: ["*"]
+priority: 92
+citations: ["https://vercel.com/docs/functions/debug-slow-functions", "https://vercel.com/docs/functions/limitations", "https://vercel.com/docs/functions/runtimes"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Cold-start candidates need a code-path check, not only a project-setting check. First prove whether cold requests are paying for imports, module-scope setup, runtime choice, or dependency weight.
+
+## Evidence To Check
+Use `startTypeSplit`, `coldVsWarmLatencyP95`, and `coldByDeployment`. In source, inspect module-scope SDK setup, database/client construction, top-level network calls, heavy dependencies, runtime exports, and deployment-local changes.
+
+## Do Not Recommend When
+Do not blame cold starts when warm requests are similarly slow. Do not recommend keep-warm traffic or more memory before proving initialization or runtime pressure.
+
+## Verification
+Name the cold-start share, cold-vs-warm gap, and exact initialization, dependency, or runtime line that explains it.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/core-web-vitals-client-bottlenecks.md b/skills/vercel/vercel-optimize/references/support-topics/core-web-vitals-client-bottlenecks.md
new file mode 100644
index 0000000..470e313
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/core-web-vitals-client-bottlenecks.md
@@ -0,0 +1,22 @@
+---
+id: core-web-vitals-client-bottlenecks
+title: Core Web Vitals client bottlenecks
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/speed-insights", "https://web.dev/articles/vitals", "https://web.dev/articles/optimize-lcp", "https://web.dev/articles/optimize-inp", "https://web.dev/articles/optimize-cls"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Core Web Vitals candidates need metric-specific investigation. LCP, INP, and CLS usually have different causes and fixes.
+
+## Evidence To Check
+Use the poor metric in the deep dive first. For LCP, inspect server response and critical media. For INP, inspect heavy client JavaScript and interaction handlers. For CLS, inspect dimensions, fonts, and injected content.
+
+## Do Not Recommend When
+Do not emit a generic “improve Web Vitals” recommendation. Do not optimize a metric that is not poor for this route.
+
+## Verification
+Name the poor p75 metric, its value, and the exact source mechanism behind that metric.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/database-egress-pooling-region.md b/skills/vercel/vercel-optimize/references/support-topics/database-egress-pooling-region.md
new file mode 100644
index 0000000..431f3a1
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/database-egress-pooling-region.md
@@ -0,0 +1,22 @@
+---
+id: database-egress-pooling-region
+title: Database region and connection pressure
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["*"]
+priority: 60
+citations: ["https://vercel.com/docs/regions", "https://vercel.com/docs/functions", "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package", "https://vercel.com/docs/functions/limitations"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+Only recommend database or region changes when source and metrics both point to downstream I/O rather than in-process compute.
+
+## Evidence To Check
+Compare `cpu.p95` with `latency.p95`, then inspect database awaits, query fan-out, connection creation, pool lifecycle handling, and configured regions in project files.
+
+## Do Not Recommend When
+Do not name a database provider, pooling product, or region change unless the repo and project config prove it applies.
+
+## Verification
+Tie the finding to the observed wall-clock gap and the exact query, pool, or region configuration line.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/dynamic-rendering-traps.md b/skills/vercel/vercel-optimize/references/support-topics/dynamic-rendering-traps.md
new file mode 100644
index 0000000..cd9d62d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/dynamic-rendering-traps.md
@@ -0,0 +1,22 @@
+---
+id: dynamic-rendering-traps
+title: Dynamic rendering traps
+status: active
+candidateKinds: ["rendering_candidate"]
+frameworks: ["next@>=13.0.0"]
+priority: 90
+citations: ["https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config", "https://nextjs.org/docs/app/api-reference/functions/generate-static-params", "https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Rendering candidates are only actionable when the dynamic behavior is accidental. First prove that the route can be static, ISR, or partially static.
+
+## Evidence To Check
+Inspect `dynamic`, `revalidate`, `generateStaticParams`, route params, and dynamic APIs such as request headers or cookies. Check whether the dynamic call is in a layout, because that can affect a larger route tree.
+
+## Do Not Recommend When
+Do not remove dynamic rendering for auth, personalization, draft mode, per-request redirects, or request-specific data.
+
+## Verification
+The recommendation must cite the dynamic trigger and explain why the target route can tolerate static or ISR behavior.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path-platform.md b/skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path-platform.md
new file mode 100644
index 0000000..6f0d93d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path-platform.md
@@ -0,0 +1,22 @@
+---
+id: external-api-critical-path-platform
+title: Cross-framework external API critical path
+status: active
+candidateKinds: ["external_api_slow"]
+frameworks: ["*"]
+priority: 86
+citations: ["https://vercel.com/docs/functions/debug-slow-functions", "https://vercel.com/docs/caching/runtime-cache", "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+External API candidates are actionable only when the slow hostname is on a customer route's critical path. Prove the route waits on it before suggesting a cache, payload, or post-response change.
+
+## Evidence To Check
+Use hostname latency, caller routes, transfer bytes, and source awaits. Check sequential calls, overbroad payloads, repeated shared data, and side effects that can move after the response.
+
+## Do Not Recommend When
+Do not cache mutations, secrets, per-user responses, or unknown freshness contracts. Do not blame Vercel runtime when the upstream owns the latency.
+
+## Verification
+Name the hostname, caller route, observed p75/p95 or bytes, and exact await or fetch line that blocks the response.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path.md b/skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path.md
new file mode 100644
index 0000000..d7303f4
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/external-api-critical-path.md
@@ -0,0 +1,22 @@
+---
+id: external-api-critical-path
+title: External API critical path
+status: active
+candidateKinds: ["external_api_slow"]
+frameworks: ["next@>=13.0.0"]
+priority: 90
+citations: ["vercel-react-best-practices:async-parallel", "vercel-react-best-practices:server-parallel-fetching", "vercel-react-best-practices:server-cache-react"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For external API candidates, identify the customer route that waits on the slow hostname and whether the call is on the critical path.
+
+## Evidence To Check
+Use callers-by-route evidence, transfer size, and source awaits. Check whether the upstream call can run in parallel, be cached safely, be reduced in payload size, or move after response.
+
+## Do Not Recommend When
+Do not cache mutations, secrets, per-user responses, or upstream calls whose freshness requirement is unknown.
+
+## Verification
+Name the hostname, caller route, p75 or p95 latency, and the exact source line that waits on the call.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/fast-data-transfer-payloads.md b/skills/vercel/vercel-optimize/references/support-topics/fast-data-transfer-payloads.md
new file mode 100644
index 0000000..8a5e49b
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/fast-data-transfer-payloads.md
@@ -0,0 +1,22 @@
+---
+id: fast-data-transfer-payloads
+title: Fast Data Transfer payloads
+status: active
+candidateKinds: ["uncached_route"]
+frameworks: ["*"]
+priority: 65
+citations: ["https://vercel.com/docs/manage-cdn-usage", "https://vercel.com/docs/caching/cdn-cache"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+When uncached routes carry high bandwidth, check payload shape before recommending only cache headers. Fast Data Transfer includes the bytes transferred by requests and responses; compare compressed response sizes to the signal, not raw JSON.
+
+## Evidence To Check
+Use `bandwidthByCache`, response size, and source serialization. Look for unbounded JSON, large embedded objects, static files through functions, missing pagination.
+
+## Do Not Recommend When
+Do not shrink payloads without identifying fields or assets that are unnecessary for the route’s response.
+
+## Verification
+Tie the finding to observed bytes, cache result mix, and the exact response line. A "large payload" claim must reflect post-compression bytes — the unit FDT meters.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/fluid-compute-caveats.md b/skills/vercel/vercel-optimize/references/support-topics/fluid-compute-caveats.md
new file mode 100644
index 0000000..952b947
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/fluid-compute-caveats.md
@@ -0,0 +1,22 @@
+---
+id: fluid-compute-caveats
+title: Fluid compute caveats
+status: active
+candidateKinds: ["platform_fluid_compute", "cold_start"]
+frameworks: ["*"]
+priority: 80
+citations: ["https://vercel.com/docs/fluid-compute"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Fluid compute is a project-level lever. Use it when the setting is off and metrics show cold-start or warm-instance reuse pressure. Fluid can handle multiple invocations in one function instance; avoid per-request state in module scope.
+
+## Evidence To Check
+Check project facts, `startTypeSplit`, cold-vs-warm latency, and routes carrying the cold-start share. When enabling Fluid, audit module-state hazards Fluid surfaces (not creates): module-scoped mutable state, lazy singletons holding per-user data, globals keyed on per-request inputs.
+
+## Do Not Recommend When
+Do not recommend enabling fluid compute when project facts say it is already on. Do not frame as a file-level code fix.
+
+## Verification
+State project setting, cold-start rate or fallback slow-route signal, affected route concentration. If enabling, call out module-state audit as follow-up.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/function-duration-io-and-after.md b/skills/vercel/vercel-optimize/references/support-topics/function-duration-io-and-after.md
new file mode 100644
index 0000000..3e835dc
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/function-duration-io-and-after.md
@@ -0,0 +1,22 @@
+---
+id: function-duration-io-and-after
+title: Function duration, I/O, and post-response work
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["next@>=15.0.0"]
+priority: 75
+citations: ["https://nextjs.org/docs/app/api-reference/functions/after", "vercel-react-best-practices:async-parallel", "vercel-react-best-practices:server-after-nonblocking"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+When wall-clock latency is much higher than CPU time, check critical-path awaits before blaming rendering or compute.
+
+## Evidence To Check
+Compare `cpu.p95`, `ttfb.p95`, and `latency.p95`. In source, separate dependent awaits from independent awaits, and identify analytics, logging, or notification work that can run after the response.
+
+## Do Not Recommend When
+Do not wrap dependent operations in `Promise.all`. Do not replace `Promise.allSettled` when partial failure handling is intentional.
+
+## Verification
+Name the awaits that can move, the work that can run post-response, and the observed CPU-vs-wall-clock gap.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/function-invocation-reduction.md b/skills/vercel/vercel-optimize/references/support-topics/function-invocation-reduction.md
new file mode 100644
index 0000000..6e9f4da
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/function-invocation-reduction.md
@@ -0,0 +1,22 @@
+---
+id: function-invocation-reduction
+title: Function invocation reduction
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["next@>=13.0.0"]
+priority: 70
+citations: ["https://react.dev/reference/react/cache", "vercel-react-best-practices:server-parallel-fetching", "vercel-react-best-practices:server-cache-react"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For slow routes, prove duplicated in-request work in the listed files before recommending consolidation or memoization.
+
+## Evidence To Check
+Look for repeated awaits, duplicate fetches, same-app route handler calls, and helpers that run more than once per request.
+
+## Do Not Recommend When
+Do not collapse endpoints called independently by different clients. Do not persistently cache user-specific data. Do not recommend `Promise.all` for CPU-bound or compile-bound work unless trace/span evidence shows wait time to overlap. High `cpu.p95` near `latency.p95` is a warning sign, not proof of a latency win.
+
+## Verification
+Quote duplicated call sites with `latency.p95`, `cpu.p95`, or request-count evidence. If the fix overlaps awaits, cite measured helper/span timing or state the impact is unmeasured.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/function-region-misconfiguration-ttfb.md b/skills/vercel/vercel-optimize/references/support-topics/function-region-misconfiguration-ttfb.md
new file mode 100644
index 0000000..127fde4
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/function-region-misconfiguration-ttfb.md
@@ -0,0 +1,23 @@
+---
+id: function-region-misconfiguration-ttfb
+title: Function region misconfiguration (TTFB)
+status: active
+candidateKinds: ["region_misconfig"]
+frameworks: ["*"]
+scannerPatterns: ["region-pin-in-config"]
+priority: 85
+citations: ["https://vercel.com/docs/functions/configuring-functions/region", "https://vercel.com/docs/regions"]
+maxBriefChars: 950
+---
+
+## Investigation Brief
+A single function region is pinned. Per-region TTFB data is unavailable today (`evidence.dataGap`); treat as an audit prompt — validate the pinned region against user geo and data-source location before recommending changes.
+
+## Evidence To Check
+Scanner subtype (`vercel-json-single`, `segment-preferred`) and pinned regions. Cross-check Speed Insights TTFB and country analytics for traffic geo. Locate the data source — proximity to it often wins on cache-miss paths.
+
+## Do Not Recommend When
+Skip if TTFB is healthy across countries. Skip if pinned intentionally for data proximity. Skip on small projects (<20 routes). Do not propose multi-region without confirming the data layer is reachable without cross-region egress.
+
+## Verification
+Name pinned region(s), traffic geo, data-source location, and a specific call: relocate, expand, or keep with a TTFB monitor.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/image-optimization-cost-control.md b/skills/vercel/vercel-optimize/references/support-topics/image-optimization-cost-control.md
new file mode 100644
index 0000000..e2a683c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/image-optimization-cost-control.md
@@ -0,0 +1,22 @@
+---
+id: image-optimization-cost-control
+title: Image optimization cost control
+status: active
+candidateKinds: ["image_optimization"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/image-optimization", "https://vercel.com/docs/image-optimization/managing-image-optimization-costs", "https://vercel.com/docs/image-optimization/limits-and-pricing"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Image recommendations should distinguish real user-facing image work from wasteful transformations.
+
+## Evidence To Check
+Inspect the sampled files for raw image tags, dimensions, remote sources, repeated transforms, source image limits, icons, SVGs, GIFs, and existing framework image components.
+
+## Do Not Recommend When
+Do not route tiny icons, SVG UI assets, or animated GIFs through image optimization just because they are images. Do not change remote-source policy without checking the existing config.
+
+## Verification
+Name the image files or components, current rendering path, and the metric or scanner evidence that makes optimization material.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/isr-revalidation-static-generation.md b/skills/vercel/vercel-optimize/references/support-topics/isr-revalidation-static-generation.md
new file mode 100644
index 0000000..e0938c8
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/isr-revalidation-static-generation.md
@@ -0,0 +1,22 @@
+---
+id: isr-revalidation-static-generation
+title: ISR revalidation and static generation
+status: active
+candidateKinds: ["isr_overrevalidation"]
+frameworks: ["next@>=13.4.0"]
+priority: 95
+citations: ["https://vercel.com/docs/incremental-static-regeneration", "https://nextjs.org/docs/app/api-reference/functions/revalidateTag", "https://nextjs.org/docs/app/api-reference/functions/revalidatePath"]
+maxBriefChars: 1000
+---
+
+## Investigation Brief
+For ISR over-revalidation, the goal is to reduce unnecessary regeneration work without making content stale beyond the product’s tolerance.
+
+## Evidence To Check
+Compare ISR writes to reads, then inspect the route’s `revalidate`, `cacheLife()`, tag invalidation, and content update path. Look for very short timer revalidation on routes where updates are event-driven. If recommending `cacheLife()` or `cacheTag()` for tagged content, prove the exact tags are invalidated by `revalidateTag()` or `updateTag()`; near-matches do not count.
+
+## Do Not Recommend When
+Do not lengthen revalidation for inventory, pricing, auth, or other user-critical freshness without source evidence that stale content is acceptable. Do not claim existing CMS or webhook invalidation unless the matching invalidation call or config is in the allowed files.
+
+## Verification
+Tie the fix to the observed ISR writes per read and the line that controls revalidation or on-demand invalidation.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/middleware-proxy-edge-cost.md b/skills/vercel/vercel-optimize/references/support-topics/middleware-proxy-edge-cost.md
new file mode 100644
index 0000000..7cd2b3b
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/middleware-proxy-edge-cost.md
@@ -0,0 +1,22 @@
+---
+id: middleware-proxy-edge-cost
+title: Middleware edge cost
+status: active
+candidateKinds: ["middleware_heavy"]
+frameworks: ["next@>=12.0.0"]
+priority: 90
+citations: ["https://nextjs.org/docs/app/building-your-application/routing/middleware", "https://vercel.com/docs/routing-middleware"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Middleware recommendations should reduce unnecessary interception, not remove required request handling.
+
+## Evidence To Check
+Use `topMiddlewarePaths` and the matcher config. Confirm which paths need auth, rewrites, headers, or locale handling. Check whether static assets, images, or routes with no middleware need are being matched.
+
+## Do Not Recommend When
+Do not narrow the matcher in a way that bypasses required auth or routing behavior. Do not move middleware work into every route if the current matcher is already scoped.
+
+## Verification
+State the current middleware share, the dominant matched paths, and the exact matcher line to change.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/next-fetch-revalidate-floor.md b/skills/vercel/vercel-optimize/references/support-topics/next-fetch-revalidate-floor.md
new file mode 100644
index 0000000..352d548
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/next-fetch-revalidate-floor.md
@@ -0,0 +1,22 @@
+---
+id: next-fetch-revalidate-floor
+title: Next.js fetch revalidation floor
+status: active
+candidateKinds: ["uncached_route", "isr_overrevalidation"]
+frameworks: ["next@>=13.0.0"]
+priority: 88
+citations: ["https://nextjs.org/docs/app/api-reference/functions/fetch", "https://nextjs.org/docs/app/building-your-application/caching"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Next.js `fetch` options can set the route's effective cache floor. Low `revalidate`, `revalidate: 0`, or `cache: 'no-store'` can explain uncached traffic and excessive ISR work.
+
+## Evidence To Check
+Inspect route-tree `fetch` calls. Compare route revalidation with per-fetch `cache`, `next.revalidate`, tags, dynamic APIs, and duplicated URLs with conflicting options.
+
+## Do Not Recommend When
+Do not raise freshness windows for pricing, inventory, auth, draft, or user-specific data unless the source proves stale reads are acceptable.
+
+## Verification
+Name the observed cache or ISR signal, the lowest cache setting that controls the route, and the exact fetch line to change.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/next-font-cls-self-hosting.md b/skills/vercel/vercel-optimize/references/support-topics/next-font-cls-self-hosting.md
new file mode 100644
index 0000000..59e4fe2
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/next-font-cls-self-hosting.md
@@ -0,0 +1,23 @@
+---
+id: next-font-cls-self-hosting
+title: Next.js font CLS guardrail
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@>=13.2.0"]
+metrics: ["CLS"]
+priority: 86
+citations: ["https://nextjs.org/docs/app/api-reference/components/font", "https://web.dev/articles/optimize-cls"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+For poor CLS, check fonts only when the route actually loads external font CSS or swaps text after render.
+
+## Evidence To Check
+Inspect layouts and global styles for external font links, CSS imports, custom font-face rules, late-loading font classes, and whether `next/font` is already used.
+
+## Do Not Recommend When
+Do not migrate fonts when CLS is caused by images, ads, embeds, or injected UI. Do not suggest `next/font` for unsupported Next.js versions.
+
+## Verification
+Name the CLS value, font-loading mechanism, and the exact layout or stylesheet line to change.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/next-heavy-ui-lazy-load-boundaries.md b/skills/vercel/vercel-optimize/references/support-topics/next-heavy-ui-lazy-load-boundaries.md
new file mode 100644
index 0000000..470b010
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/next-heavy-ui-lazy-load-boundaries.md
@@ -0,0 +1,23 @@
+---
+id: next-heavy-ui-lazy-load-boundaries
+title: Next.js heavy UI lazy-load boundaries
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@*"]
+metrics: ["LCP", "INP"]
+priority: 82
+citations: ["https://nextjs.org/docs/app/guides/lazy-loading", "https://web.dev/articles/optimize-inp"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Heavy above-the-fold or rarely used UI can hurt LCP and INP when it ships too much JavaScript on first load. Look for concrete route-local UI, not generic bundle advice.
+
+## Evidence To Check
+Inspect client components, menus, search overlays, personalization widgets, maps, editors, and large imported libraries. Check whether they can load on interaction, viewport, or route entry with `next/dynamic` or dynamic import.
+
+## Do Not Recommend When
+Do not lazy-load essential above-the-fold content needed for initial meaning or accessibility. Do not use `ssr: false` from a Server Component.
+
+## Verification
+Name the poor metric, heavy UI boundary, imported library or component, and exact line to split.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/next-image-lcp-preload-sizes.md b/skills/vercel/vercel-optimize/references/support-topics/next-image-lcp-preload-sizes.md
new file mode 100644
index 0000000..7471ee6
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/next-image-lcp-preload-sizes.md
@@ -0,0 +1,23 @@
+---
+id: next-image-lcp-preload-sizes
+title: Next.js image LCP preload and sizes
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@*"]
+metrics: ["LCP"]
+priority: 86
+citations: ["https://nextjs.org/docs/app/api-reference/components/image", "https://web.dev/articles/optimize-lcp"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For poor LCP, identify whether the LCP element is an image before touching unrelated JavaScript. Hero images need correct sizing, priority behavior, and source-cache hygiene.
+
+## Evidence To Check
+Inspect above-the-fold media for `next/image`, `fill` without `sizes`, deprecated `priority` on Next.js 16, missing `preload` or `fetchPriority`, oversized dimensions, and remote-image TTL/source behavior.
+
+## Do Not Recommend When
+Do not preload multiple possible LCP images or route tiny icons/SVG UI assets through image optimization. Do not change quality or TTL without checking source-update semantics.
+
+## Verification
+Name the LCP value, image element or component, current props/config, and the exact line to change.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/next-route-handler-get-cache-defaults.md b/skills/vercel/vercel-optimize/references/support-topics/next-route-handler-get-cache-defaults.md
new file mode 100644
index 0000000..9d0f97c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/next-route-handler-get-cache-defaults.md
@@ -0,0 +1,22 @@
+---
+id: next-route-handler-get-cache-defaults
+title: Next.js Route Handler GET cache defaults
+status: active
+candidateKinds: ["uncached_route", "cache_header_gap"]
+frameworks: ["next@>=15.0.0"]
+priority: 91
+citations: ["https://nextjs.org/docs/app/api-reference/file-conventions/route", "https://vercel.com/docs/caching/cdn-cache"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+On Next.js 15+, GET Route Handlers are dynamic by default. For hot public GET handlers, verify whether uncached behavior is intentional before recommending cache headers or route config.
+
+## Evidence To Check
+Use method share, cache result, and source. Check `GET`, `revalidate`, `dynamic`, request headers, cookies, auth, query params, and response `Cache-Control`.
+
+## Do Not Recommend When
+Do not cache POST-style handlers, webhooks, per-user APIs, streaming responses, search requests with user-specific params, or handlers that read auth/cookies.
+
+## Verification
+Name the Next.js version, GET share, cache result mix, and the exact handler or header line that makes public caching safe.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/next-script-third-party-strategy.md b/skills/vercel/vercel-optimize/references/support-topics/next-script-third-party-strategy.md
new file mode 100644
index 0000000..75ac81a
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/next-script-third-party-strategy.md
@@ -0,0 +1,23 @@
+---
+id: next-script-third-party-strategy
+title: Next.js third-party script strategy
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@*"]
+metrics: ["LCP", "INP"]
+priority: 85
+citations: ["https://nextjs.org/docs/app/api-reference/components/script", "https://web.dev/articles/optimize-inp"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Third-party scripts are only actionable when they line up with the poor metric and route. For LCP or INP, prove a specific script blocks critical rendering, hydration, or interaction.
+
+## Evidence To Check
+Inspect `next/script`, raw `<script>`, tag managers, chat widgets, analytics, and consent code. Check `beforeInteractive`, `afterInteractive`, `lazyOnload`, and whether the script is route-local or global.
+
+## Do Not Recommend When
+Do not move required bot detection, consent, auth, or payment scripts later without product evidence. Do not recommend `worker` for App Router.
+
+## Verification
+Name the poor metric, script source, current strategy, and the exact route or layout line to change.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/nextjs-version-cache-semantics.md b/skills/vercel/vercel-optimize/references/support-topics/nextjs-version-cache-semantics.md
new file mode 100644
index 0000000..7f92975
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/nextjs-version-cache-semantics.md
@@ -0,0 +1,22 @@
+---
+id: nextjs-version-cache-semantics
+title: Next.js cache semantics by version
+status: active
+candidateKinds: ["uncached_route"]
+frameworks: ["next@>=15.0.0"]
+priority: 85
+citations: ["https://nextjs.org/docs/app/api-reference/directives/use-cache", "https://nextjs.org/docs/app/api-reference/functions/cacheLife", "https://nextjs.org/docs/app/building-your-application/caching"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+On Next.js 15+, match the fix to the cache primitive already in use.
+
+## Evidence To Check
+Check `'use cache'`, `cacheLife`, `cacheTag`, `fetch` cache options, route handlers, and dynamic APIs.
+
+## Do Not Recommend When
+Do not suggest APIs outside the detected Next.js version. Do not claim `cacheLife()` emits CDN `Cache-Control` headers or that missing `cacheLife()` alone makes a `'use cache'` route run per request. Omitted `cacheLife()` calls use the default profile.
+
+## Verification
+Name the detected Next.js version and exact cache primitive or route header.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/not-found-catchall-request-waste.md b/skills/vercel/vercel-optimize/references/support-topics/not-found-catchall-request-waste.md
new file mode 100644
index 0000000..babbae9
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/not-found-catchall-request-waste.md
@@ -0,0 +1,23 @@
+---
+id: not-found-catchall-request-waste
+title: Not-found and catch-all request waste
+status: active
+candidateKinds: ["uncached_route"]
+frameworks: ["*"]
+routePatterns: ["(^|/)404$", "not-found", "\\[\\.\\.\\."]
+priority: 92
+citations: ["https://vercel.com/docs/routing/", "https://vercel.com/docs/redirects/bulk-redirects/", "https://vercel.com/docs/vercel-firewall/vercel-waf/custom-rules", "https://vercel.com/docs/vercel-firewall/vercel-waf/managed-rulesets"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+High-volume 404 or catch-all traffic is often request waste. First determine whether the traffic is legacy URLs, bots, broken links, or a real product route.
+
+## Evidence To Check
+Use route volume, method share, cache result, bot share, and top request paths. Inspect redirects, rewrites, catch-all routes, sitemap/robots output, and any WAF rules already logging or blocking the pattern.
+
+## Do Not Recommend When
+Do not block or redirect legitimate product routes, search crawlers, or unknown traffic without a log-mode validation path. Do not replace a useful 404 page with a blanket rewrite.
+
+## Verification
+Name the dominant bad path pattern, observed request or bot volume, and the redirect, routing, or WAF rule that would stop the wasted function path.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/nuxt-route-rules-cache-isr.md b/skills/vercel/vercel-optimize/references/support-topics/nuxt-route-rules-cache-isr.md
new file mode 100644
index 0000000..822537d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/nuxt-route-rules-cache-isr.md
@@ -0,0 +1,22 @@
+---
+id: nuxt-route-rules-cache-isr
+title: Nuxt routeRules cache and ISR
+status: active
+candidateKinds: ["uncached_route", "isr_overrevalidation", "rendering_candidate"]
+frameworks: ["nuxt@>=3.0.0"]
+priority: 90
+citations: ["https://vercel.com/docs/frameworks/full-stack/nuxt", "https://nuxt.com/docs/4.x/api/utils/define-route-rules", "https://nuxt.com/docs/4.x/guide/concepts/rendering"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For Nuxt on Vercel, route-level caching usually belongs in `routeRules`. Match the lever to the route: prerender for static pages, ISR for shared content, and SSR for request-specific views.
+
+## Evidence To Check
+Inspect `nuxt.config`, inline route rules, server routes, pages, auth/session reads, and observed cache or ISR read/write patterns. Verify whether the route should be Vercel cache-backed ISR rather than generic SWR.
+
+## Do Not Recommend When
+Do not cache authenticated, cart, checkout, preview, or per-user routes. Do not add routeRules without proving the route is public and the freshness window is acceptable.
+
+## Verification
+Name the observed route signal, current routeRule or missing rule, chosen cache mode, and exact config line.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/observability-events-cost-attribution.md b/skills/vercel/vercel-optimize/references/support-topics/observability-events-cost-attribution.md
new file mode 100644
index 0000000..758c639
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/observability-events-cost-attribution.md
@@ -0,0 +1,22 @@
+---
+id: observability-events-cost-attribution
+title: Observability Events cost attribution
+status: active
+candidateKinds: ["observability_events_attribution"]
+frameworks: ["*"]
+priority: 92
+citations: ["https://vercel.com/docs/observability/observability-plus", "https://vercel.com/docs/alerts"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Observability Events is the metered SKU under Observability Plus. When the current bill shows a large Observability Events share, event volume is the lever. Reduce upstream: lift cache hit rate, narrow middleware matchers, and reduce unnecessary custom-span cardinality.
+
+## Evidence To Check
+Verify the share from `usage.services`. Cross-reference `requestsByRouteCache`, `middlewareCount`, external API span counts, and third-party tracing (`tracesSampleRate=1`).
+
+## Do Not Recommend When
+Skip below 15% share. Skip when cache hit rate is already >90% across hot routes — the lever is elsewhere. Do not propose sampling unless the specific metered signal has a documented sampling control.
+
+## Verification
+Name the share, upstream drivers, and concrete remediation per driver, not generic "reduce events".
diff --git a/skills/vercel/vercel-optimize/references/support-topics/post-response-work-waituntil.md b/skills/vercel/vercel-optimize/references/support-topics/post-response-work-waituntil.md
new file mode 100644
index 0000000..8760992
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/post-response-work-waituntil.md
@@ -0,0 +1,22 @@
+---
+id: post-response-work-waituntil
+title: Post-response work with waitUntil
+status: active
+candidateKinds: ["slow_route", "external_api_slow"]
+frameworks: ["next@<15.0.0", "sveltekit@*", "astro@*", "nuxt@*", "unknown@*"]
+priority: 78
+citations: ["https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+For stacks without Next.js `after()`, check whether non-critical work can run after the response instead of extending user-visible latency.
+
+## Evidence To Check
+Inspect the listed route for analytics, logging, notifications, cache warming, metrics, or webhook side effects that happen after the response data is ready.
+
+## Do Not Recommend When
+Do not move work that decides the response, must fail the request, changes visible state synchronously, or needs a durable retry guarantee.
+
+## Verification
+Name the blocking side effect, the observed latency or upstream signal, and the exact line that can move behind `waitUntil`.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/route-error-durable-offload.md b/skills/vercel/vercel-optimize/references/support-topics/route-error-durable-offload.md
new file mode 100644
index 0000000..1bb9395
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/route-error-durable-offload.md
@@ -0,0 +1,22 @@
+---
+id: route-error-durable-offload
+title: Durable offload for timeout-heavy routes
+status: active
+candidateKinds: ["route_errors"]
+frameworks: ["*"]
+priority: 84
+citations: ["https://vercel.com/docs/workflow", "https://workflow-sdk.dev/docs/foundations/starting-workflows", "https://workflow-sdk.dev/docs/foundations/workflows-and-steps", "https://vercel.com/docs/queues", "https://vercel.com/docs/functions/limitations"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Timeout-heavy routes often need a job boundary, not a higher limit. Workflow fits durable multi-step work that can continue after the response; return a run ID instead of waiting on `returnValue`.
+
+## Evidence To Check
+Use `errorStatusPattern`, `errorCodes`, and source flow. Look for fan-out, polling, batch work, AI jobs, uploads, sleeps, approval, multi-step side effects. If Workflow is already used, check whether the route waits or streams progress.
+
+## Do Not Recommend When
+Do not offload work that must finish before responding. Do not claim savings from offload alone: Workflow Steps/Storage bill separately, and invoked functions still use compute billing.
+
+## Verification
+Name the timeout/error class, long-running operation, post-enqueue response contract, and queue or workflow boundary that preserves semantics.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/route-error-runtime-limits.md b/skills/vercel/vercel-optimize/references/support-topics/route-error-runtime-limits.md
new file mode 100644
index 0000000..69b2544
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/route-error-runtime-limits.md
@@ -0,0 +1,22 @@
+---
+id: route-error-runtime-limits
+title: Route errors and runtime limits
+status: active
+candidateKinds: ["route_errors"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/functions", "https://vercel.com/docs/functions/limitations", "https://vercel.com/docs/cli/inspect"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Route error candidates are reliability findings with cost impact. Determine whether the failures are app exceptions, timeouts, payload limits, or deployment-specific regressions.
+
+## Evidence To Check
+Use `errorStatusPattern`, `errorCodes`, and `errorsByDeployment`. In source, inspect the path most likely to throw, time out, or exceed a platform limit.
+
+## Do Not Recommend When
+Do not frame high 5xx volume as a performance tuning issue. Do not suggest increasing limits before proving the route needs more headroom.
+
+## Verification
+Name the error class, deployment concentration if present, and the file line that triggers or fails to handle it.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/runtime-cache-reusable-data.md b/skills/vercel/vercel-optimize/references/support-topics/runtime-cache-reusable-data.md
new file mode 100644
index 0000000..fa54468
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/runtime-cache-reusable-data.md
@@ -0,0 +1,22 @@
+---
+id: runtime-cache-reusable-data
+title: Runtime Cache for reusable server data
+status: active
+candidateKinds: ["slow_route", "external_api_slow"]
+frameworks: ["*"]
+priority: 84
+citations: ["https://vercel.com/docs/caching/runtime-cache", "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Runtime Cache is only useful when the same server-side result is reused across requests. Treat it as a measured alternative when CDN response caching is unsafe or incomplete.
+
+## Evidence To Check
+Use p75/p95 latency, call count, caller routes, and transfer bytes. In source, identify database queries, external API calls, or expensive computations that return the same result for many viewers.
+
+## Do Not Recommend When
+Skip per-user data, mutations, secrets, one-off requests, or unknown freshness. Skip Runtime Cache when CDN caching solves the route. For Next with Cache Components, check `use cache: remote` first; use Runtime Cache only as a justified fallback.
+
+## Verification
+Name the reusable data, observed route or hostname pressure, required freshness window, and the exact call site to wrap.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/sveltekit-isr-prerender-safety.md b/skills/vercel/vercel-optimize/references/support-topics/sveltekit-isr-prerender-safety.md
new file mode 100644
index 0000000..787c447
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/sveltekit-isr-prerender-safety.md
@@ -0,0 +1,22 @@
+---
+id: sveltekit-isr-prerender-safety
+title: SvelteKit ISR and prerender safety
+status: active
+candidateKinds: ["uncached_route", "isr_overrevalidation"]
+frameworks: ["sveltekit@*"]
+priority: 90
+citations: ["https://vercel.com/docs/frameworks/full-stack/sveltekit", "https://svelte.dev/docs/kit/adapter-vercel", "https://svelte.dev/docs/kit/page-options"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For SvelteKit, the right lever is often `prerender` or adapter ISR on public consumer pages. First prove every visitor can safely see the same response for the configured interval.
+
+## Evidence To Check
+Inspect `+page`, `+page.server`, `+server`, layouts, `prerender`, `ssr`, and adapter `isr` config. Compare route cache results, ISR writes, and whether the route reads cookies, auth, or per-user locals.
+
+## Do Not Recommend When
+Do not use ISR for dashboards, carts, checkout, account data, drafts, or any route whose output varies per visitor. Do not add ISR when `prerender = true` already makes it irrelevant.
+
+## Verification
+Name the route, current SvelteKit page option or adapter config, observed cache or ISR signal, and the exact file line to change.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/sveltekit-split-cold-start-tradeoff.md b/skills/vercel/vercel-optimize/references/support-topics/sveltekit-split-cold-start-tradeoff.md
new file mode 100644
index 0000000..ff5c685
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/sveltekit-split-cold-start-tradeoff.md
@@ -0,0 +1,22 @@
+---
+id: sveltekit-split-cold-start-tradeoff
+title: SvelteKit split function cold-start tradeoff
+status: active
+candidateKinds: ["cold_start", "slow_route"]
+frameworks: ["sveltekit@*"]
+priority: 82
+citations: ["https://vercel.com/docs/frameworks/full-stack/sveltekit", "https://svelte.dev/docs/kit/adapter-vercel"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+SvelteKit bundles routes together by default to avoid excessive cold starts. Treat `split: true` as a targeted tradeoff, not a blanket optimization.
+
+## Evidence To Check
+Use cold-start share, cold-vs-warm latency, deployment concentration, and source bundle pressure. Check adapter options and whether a large dependency belongs to one route or the whole app.
+
+## Do Not Recommend When
+Do not split every route without evidence of function size pressure or route-local initialization cost. Do not split if cold starts are already the dominant problem.
+
+## Verification
+Name the cold-start signal, route or dependency that motivates the split, and the exact adapter config line.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/usage-spike-triage.md b/skills/vercel/vercel-optimize/references/support-topics/usage-spike-triage.md
new file mode 100644
index 0000000..b1b7a3f
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/usage-spike-triage.md
@@ -0,0 +1,22 @@
+---
+id: usage-spike-triage
+title: Usage spike triage
+status: active
+candidateKinds: ["usage_spike_triage"]
+frameworks: ["*"]
+priority: 95
+citations: ["https://vercel.com/docs/alerts", "https://vercel.com/docs/spend-management", "https://vercel.com/docs/bot-management"]
+maxBriefChars: 950
+---
+
+## Investigation Brief
+A single-day or single-SKU spike needs cause before fix. Branches: bot or AI crawler on a cacheable route, viral moment, pricing-model migration, or code regression.
+
+## Evidence To Check
+Confirm SKU and day from `usage.breakdown.data`. Cross-check firewall/bot data, traffic curve, SKU rename timing, and deploy log around the spike day. Spend Management and Alerts are monitoring tools; they do not replace finding the traffic or deploy cause.
+
+## Do Not Recommend When
+Do not propose a code fix until the branch is identified. Do not rate-limit a viral moment or revert a deploy for third-party crawler traffic.
+
+## Verification
+Name SKU, day, value, window mean, branch, and one supporting datum.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/use-cache-date-stamp-isr-write-amplifier.md b/skills/vercel/vercel-optimize/references/support-topics/use-cache-date-stamp-isr-write-amplifier.md
new file mode 100644
index 0000000..3cd709d
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/use-cache-date-stamp-isr-write-amplifier.md
@@ -0,0 +1,23 @@
+---
+id: use-cache-date-stamp-isr-write-amplifier
+title: "'use cache' date-stamp ISR write amplifier"
+status: active
+candidateKinds: ["use_cache_date_stamp"]
+frameworks: ["next@>=15.0.0"]
+scannerPatterns: ["use-cache-date-stamp"]
+priority: 88
+citations: ["https://nextjs.org/docs/app/api-reference/directives/use-cache", "https://nextjs.org/docs/app/api-reference/functions/cacheLife"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+`'use cache'` keys on argument identity and prerender output. A `new Date()`, `Date.now()`, or `Math.random()` baked into the cached output forces a fresh ISR write on every regeneration even when the data is unchanged.
+
+## Evidence To Check
+Check the scanner finding's `subtype`: `module-scope` (module-level date) or `in-cache-fn` (inside the cached body). Cross-reference `isrWritesByRoute` — a stable write rate against low reads is the symptom.
+
+## Do Not Recommend When
+Skip if the date is inside `useEffect`/`useCallback`/`useMemo`. Skip if `'use cache'` is only a comment. Skip if the date is the intended cache key.
+
+## Verification
+Name the file, the specific primitive call, and the replacement: build-time constant or client-side `useEffect`.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/use-cache-remote-shared-origin-data.md b/skills/vercel/vercel-optimize/references/support-topics/use-cache-remote-shared-origin-data.md
new file mode 100644
index 0000000..b4037ee
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/use-cache-remote-shared-origin-data.md
@@ -0,0 +1,22 @@
+---
+id: use-cache-remote-shared-origin-data
+title: Remote cache for shared origin data
+status: active
+candidateKinds: ["external_api_slow", "slow_route", "uncached_route"]
+frameworks: ["next@>=16.0.0"]
+priority: 87
+citations: ["https://vercel.com/docs/caching/runtime-cache", "https://nextjs.org/docs/app/api-reference/directives/use-cache-remote"]
+maxBriefChars: 950
+---
+
+## Investigation Brief
+For Next 16 candidates, check whether shared origin data or reusable route-handler work belongs in remote cache. Default `'use cache'` is not cross-request on Vercel. Use `'use cache: remote'` or `generateStaticParams`.
+
+## Evidence To Check
+Hostname p75, caller routes, call count, bytes. Verify data is shared and tolerates the freshness window. Confirm `'use cache: remote'`.
+
+## Do Not Recommend When
+Skip per-user, mutation, secret, or freshness-critical data. Skip when upstream is fast or rarely called. Avoid sub-ms reads (Edge Config) — overhead exceeds source latency.
+
+## Verification
+Name hostname, shared data, freshness window, and exact boundary. State `'use cache: remote'`.
diff --git a/skills/vercel/vercel-optimize/references/support-topics/workflow-resumable-stream-routes.md b/skills/vercel/vercel-optimize/references/support-topics/workflow-resumable-stream-routes.md
new file mode 100644
index 0000000..efb2993
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/support-topics/workflow-resumable-stream-routes.md
@@ -0,0 +1,23 @@
+---
+id: workflow-resumable-stream-routes
+title: Workflow resumable stream routes
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["*"]
+routePatterns: ["(^|/)api/.*/stream/?$", "(^|/)chat/.*/stream/?$", "\\[id\\].*/stream"]
+priority: 98
+citations: ["https://workflow-sdk.dev/docs/ai/resumable-streams", "https://workflow-sdk.dev/docs/foundations/streaming", "https://vercel.com/docs/workflow"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Stream-shaped routes may be Workflow SDK reconnection endpoints. Long wall-clock duration can be the live client connection.
+
+## Evidence To Check
+Look for `WorkflowChatTransport`, `getRun`, `run.getReadable`, `startIndex`, `x-workflow-run-id`, `x-workflow-stream-tail-index`, `getWritable`, or `createUIMessageStreamResponse`. Compare CPU, TTFB, wall-clock. Check full replay, missing tail-index, unreleased locks, or unclosed streams.
+
+## Do Not Recommend When
+Do not cache stream endpoints or remove resumability. Do not call high duration a bug when CPU is low, TTFB is healthy, and the route only holds a client connection.
+
+## Verification
+Name whether the route starts or reconnects a run, then cite the exact waste: replay, missing tail-index, lock leak, unclosed stream, high CPU, or avoidable pre-first-byte work.
diff --git a/skills/vercel/vercel-optimize/references/verification.md b/skills/vercel/vercel-optimize/references/verification.md
new file mode 100644
index 0000000..fbb5024
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/verification.md
@@ -0,0 +1,102 @@
+# Verification
+
+How claims in recommendations are mechanically verified, and when the recommender re-runs after a low pass rate.
+
+## Table of contents
+
+- [Why mechanical verification](#why-mechanical-verification)
+- [Claim types](#claim-types)
+- [Dispositions](#dispositions)
+- [Re-gen trigger and accept criteria](#re-gen-trigger-and-accept-criteria)
+- [Verifier implementation](#verifier-implementation)
+
+## Why mechanical verification
+
+The recommender is an LLM. LLMs hallucinate counts, miscount file occurrences, and confuse code snippets between similar-looking files. Mechanical verification — grep + filesystem reads + JSON checks against `signals.json` and `references/docs-library.json` — catches these failures before the customer sees them.
+
+The contract: every numeric claim, file reference, code snippet, citation URL, and contradiction-with-other-claims is verified. The LLM is not asked to judge whether its own output is correct.
+
+## Claim types
+
+The verifier extracts claims from `why`, `fix`, `currentBehavior`, `desiredBehavior`, and `verify` fields. Each matched claim runs through one of these handlers:
+
+| # | Claim type | Pattern in rec | Verification |
+|---|---|---|---|
+| 1 | `pattern_count` | "N fetch() calls in file X" | grep/ast-grep in X, exact count match |
+| 2 | `pattern_exists` | "uses JSON.parse(JSON.stringify())" | grep, boolean |
+| 3 | `pattern_absent` | "no Cache-Control header" | grep, verify absence (with guards — see below) |
+| 4 | `file_exists` | "app/not-found.tsx exists" | fs.access |
+| 5 | `finding_count` | "2 unoptimized images" | finding count vs `verifiedFindings.json` |
+| 6 | `contradiction` | Claim A vs Claim B | Substring conflict check |
+| 7 | `code_snippet` | Code fence labeled "Before:" | substring search in cited file |
+| 8 | `arithmetic` | "20% of 100K = 20K" | math check |
+| 9 | `repo_count` | "11 unstable_cache usages across 8 files" | grep repo, count distinct files |
+| 10 | `cited_count_literal` | "60+ icons in packages/ui/src/icons" | glob directory, count by extension |
+| 11 | `citation_in_library` | Any URL in `citations[]` | URL ∈ `references/docs-library.json` |
+| 12 | `citation_applies_to_version` | Any URL in `citations[]` | URL's `applicableFrameworks` matches `signals.json.stack.framework@frameworkVersion` |
+| 13 | `cache_vary_matches_dynamic_inputs` | CDN cache rec touches route files that read Vercel geolocation | Fails unless the rec varies by a coarse Vercel geolocation header such as `X-Vercel-IP-Country`, `X-Vercel-IP-Country-Region`, or `X-Vercel-IP-City` |
+| 13a | `cache_vary_cardinality_safe` | CDN cache rec sets `Vary` on request-specific geography | Fails on high-cardinality `X-Vercel-IP-Latitude` / `X-Vercel-IP-Longitude` / `X-Vercel-IP-Postal-Code` |
+| 14 | `next_cached_not_found_causal_support` | Rec claims `notFound()` inside `'use cache'` caused 5xx | Fails unless backed by Next-specific docs or runtime stack evidence |
+| 15 | `next_stable_cache_api_for_version` | Next.js 16 cache rec includes code examples | Fails on `unstable_cacheLife` / `unstable_cacheTag` or one-arg `revalidateTag()` |
+| 16 | `next_cache_components_runtime_cache_preference` | Next.js rec uses Runtime Cache APIs while `cacheComponents=true` | Fails unless `use cache: remote` is used or Runtime Cache is framed as a fallback |
+| 17 | `next_cache_components_route_segment_config` | Next.js 16 rec suggests removed route segment config while `cacheComponents=true` | Fails on `dynamicParams`, `dynamic`, `revalidate`, or `fetchCache` recommendations |
+| 17a | `next_route_revalidate_static_prereq` | Rec suggests route-level `export const revalidate` for a Next.js page/layout route | Fails when the route chain contains request-time APIs or common auth helpers that can force dynamic rendering |
+| 18 | `next_cache_lifetime_freshness_supported` | Rec lengthens a tagged Cache Components lifetime with `cacheLife()` | Fails unless every affected `cacheTag()` has matching `revalidateTag()` / `updateTag()` evidence |
+| 19 | `next_cache_life_cdn_header_semantics` | Rec claims `cacheLife()` emits CDN/Cache-Control headers or that missing `cacheLife()` alone makes a route run per request | Fails unless rewritten to the documented Cache Components lifetime behavior or backed by production header evidence |
+| 20 | `next_cache_tag_invalidation_supported` | Cache-lifetime rec claims existing tag invalidation | Fails unless every claimed `cacheTag()` has matching `revalidateTag()` / `updateTag()` evidence |
+| 21 | `cache_rec_not_error_dominated_or_acknowledged` | CDN cache rec targets a route with function 5xx metrics | Fails unless the rec excludes or acknowledges error traffic |
+| 22 | `cache_control_header_syntax` | CDN cache rec includes `Cache-Control`, `CDN-Cache-Control`, or `Vercel-CDN-Cache-Control` values | Fails on empty directives such as a trailing comma |
+| 23 | `cache_policy_positive_or_no_ready_rec` | Cache candidate emits a ready recommendation | Fails unless it names a positive cache policy; no-store-only belongs in no-change/observation output |
+| 24 | `cache_404_long_ttl_safety` | CDN cache rec mentions a 404 or not-found branch | Fails unless the rec keeps the 404/not-found branch uncached, short-lived, or explicitly separate |
+| 25 | `immutable_dynamic_route_safety` | Dynamic route rec uses browser `immutable` caching | Fails unless the URL is byte-versioned or the directive is scoped to Vercel's CDN |
+| 26 | `auth_guard_parallelization_safety` | Parallelization rec touches private/auth/ownership data | Fails if private data can be fetched before the auth or ownership guard |
+| 27 | `parallelization_impact_not_overclaimed` | Parallelization rec promises a helper-sized latency drop | Fails unless helper/span timing was measured |
+| 28 | `parallelization_not_cpu_bound_work` | Parallelization rec targets CPU or compile work | Fails unless measured wait/I/O time proves there is independent work to overlap |
+| 29 | `runtime_error_cause_supported` | Route-error rec names a runtime exception/root cause | Fails unless runtime logs or stack evidence support the cause |
+| 30 | `turbo_build_cache_safety` | Rec enables Turbo build caching | Fails when the package build script has migration side effects or Turbo outputs omit framework build output |
+
+Verifier guards:
+
+- **`snippet_in_wrong_file`**: code snippet found, but in a different file from the cited path → disposition `unsupported` (don't fail the rec; the LLM was close, but the source file claim is wrong).
+- **`line-number-as-count`**: "filename:42" matched against a `pattern_count` claim → skip; this is a line-number, not a count.
+- **`prose-of-absence`**: "no cache headers" without an explicit grep confirmation → `unsupported`; absence claims require evidence.
+- **`pattern_count` for abstracted DB calls**: `db.method()` in a file with DB imports + await helpers but literal count 0 → `unsupported` (import-chain resolution is out of scope).
+
+## Dispositions
+
+Each verified claim resolves to one of four states:
+
+| Disposition | Meaning | Counted toward `passRate`? |
+|---|---|---|
+| `verified` | Claim matches reality | yes (counts as pass) |
+| `failed` | Claim contradicts reality | yes (counts as fail) |
+| `unsupported` | Claim can't be checked mechanically (see guards above) | no |
+| `unverifiable` | Out of scope (e.g., external API behavior, runtime-only) | no |
+
+`passRate = verified / (verified + failed)`. Unsupported and unverifiable don't count either way.
+
+## Re-gen trigger and accept criteria
+
+After verification:
+
+| Condition | Action |
+|---|---|
+| `passRate < 0.8 AND verifiableClaimCount >= 2` | Re-run Step 3.3 (the recommender) with `topFailures` injected as feedback |
+| Project-config contradiction, cache-safety failure, or framework-semantic failure | Hard re-run. The customer report holds back the original rec until re-gen fixes it or abstains |
+| `passRate >= 0.8` OR `verifiableClaimCount < 2` | Accept the run, proceed to Step 4 |
+
+_(Floor lowered 5 → 2 in May 2026 audit: a rec with 1/1 failed claim is just as broken as 1/5, and the old floor let many small recs escape re-gen entirely.)_
+
+Re-gen accept criteria:
+
+- `regenPassRate >= originalPassRate` AND
+- Rec count not gutted (regen doesn't drop more than 50% of recs) AND
+- Findings still cited (no rec orphaning)
+
+If re-gen makes things worse, keep the original output unless the trigger was hard safety (`project_config_contradiction`, `cache_vary_safety`, or `semantic_safety`). Hard-safety failures must not ship to the customer report.
+
+## Verifier implementation
+
+`scripts/verify-and-regen.mjs` invokes `lib/extract-claims.mjs` and `lib/verify-claim.mjs` in-process for each verifiable claim. Pure functions, no network, no LLM — deterministic.
+
+For `citation_in_library` and `citation_applies_to_version`, the script uses `lib/citations.mjs`'s `isKnownUrl()` and `sanitizeCitations()` helpers (already tested). For everything else, it shells out to grep + ast-grep via execFile.
diff --git a/skills/vercel/vercel-optimize/references/voice.md b/skills/vercel/vercel-optimize/references/voice.md
new file mode 100644
index 0000000..aa927f0
--- /dev/null
+++ b/skills/vercel/vercel-optimize/references/voice.md
@@ -0,0 +1,76 @@
+# Voice
+
+Use Vercel's customer-facing voice: sharp teammate, clear, competent, no fluff.
+
+Write for a user deciding what to fix next. Lead with the observed signal, the specific change, and how to verify it. Do not explain the skill's internals unless the user asked for debug details.
+
+## Rules
+
+- Use plain words. Prefer "use" over "leverage," "reduce" over "optimize" when the action is specific.
+- Be direct. No apologetic preambles, no marketing language, no "For context" wrap-up paragraphs.
+- Keep every recommendation tied to a route, file, metric, or project setting.
+- Use observed numbers only. Never invent savings, traffic, latency, or percentages.
+- Use cost magnitude language, not precise savings: "hundreds of dollars per month at current traffic," not "$340/mo."
+- Use precise performance language when measured: "95th percentile duration is 1,240ms."
+- Frame prerequisites as engineering constraints, not upsells. Explain the decision impact: what the missing data prevents, what the limited fallback can still do, and what the user should choose next.
+- Use short bullets and tables. Avoid long paragraphs in reports and final chat messages.
+- Write full sentences with punctuation in reports.
+
+## Avoid
+
+- `seamlessly`, `effortlessly`, `powerful`, `robust`, `leverage`, `unleash`, `blazing`, `lightning-fast`, `turnkey`, `holistic`, `best-in-class`, `next-generation`, `cutting-edge`, `world-class`, `streamline`, `elevate`, `harness`, `crafted`, `myriad`, `plethora`, `empower`, `utilize`
+- Filler adverbs: `just`, `simply`, `actually`
+- Hedge starts: `Consider`, `You may want to`, `It is important to note`
+- Rhetorical reframes: `It's not X, it's Y`
+- Unicode arrows in prose: `->`, `→`, `⇒`
+- Internal process terms in customer output: `sub-agent`, `abstention`, `abstained`, `passRate`, `quality score`, `sanitizer`
+
+Use customer-facing replacements:
+
+| Internal | Customer-facing |
+|---|---|
+| `sub-agent` | `investigation` |
+| `abstained` | `found no supported change` |
+| `abstention` | `investigated, no change recommended` |
+| `passRate` | `verification result` |
+| `quality score` | `review result` |
+| `inv` | `function invocations` or `requests`, based on the metric |
+| `p95` | `95th percentile` |
+| `perf` | `performance` |
+| `CWV` | `Core Web Vitals` |
+
+## Product names
+
+Use these spellings:
+
+| Right | Wrong |
+|---|---|
+| `Observability Plus` | `OPlus`, `Oplus`, `O11y Plus`, `o11y+`, `obs+` |
+| `Vercel Functions` | `serverless functions` when referring to Vercel's product |
+| `fluid compute` mid-sentence | `Fluid Compute` mid-sentence |
+| `BotID` | `Bot ID`, `botID` |
+| `AI Gateway` | `Vercel AI Gateway`, `ai gateway` |
+| `AI SDK` | `Vercel AI SDK` |
+| `Edge Config` | `EdgeConfig` |
+| `Routing Middleware` | `Edge Middleware` |
+| `Web Analytics` | `Vercel Analytics` |
+| `Hobby`, `Pro`, `Enterprise` | `hobby`, `pro`, `enterprise` as plan names |
+
+Mirror billing names from the user's dashboard. If a dashboard still says `Edge Requests`, use `Edge Requests`; do not rename it.
+
+## Recommendation shape
+
+| Field | Pattern |
+|---|---|
+| `what` | Verb + change + scope. Example: `Add shared caching to /api/products`. |
+| `why` | State the metric and code evidence. Example: `The route handled 1,200,000 requests with a 0% cache hit rate; src/app/api/products/route.ts returns no Cache-Control header.` |
+| `fix` | Numbered steps. Start each step with a verb. |
+| `verify` | Tell the user exactly which metric or command to re-check. |
+
+Good:
+
+> Add `Cache-Control: s-maxage=300, stale-while-revalidate=86400` to `/api/products`. The route handled 1,200,000 GET requests with a 0% cache hit rate.
+
+Bad:
+
+> Consider leveraging a robust caching strategy to unlock better performance.
diff --git a/skills/vercel/vercel-optimize/scripts/budget-summary.mjs b/skills/vercel/vercel-optimize/scripts/budget-summary.mjs
new file mode 100644
index 0000000..9837e22
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/budget-summary.mjs
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Mid-flow checkpoint: should the orchestrator ask the user to raise the budget?
+// JSON output is the contract the orchestrator parses; markdown is human-only.
+
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { buildBudgetSummary, renderBudgetSummaryMarkdown } from '../lib/budget-summary.mjs';
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.gatePath) {
+    console.error('usage: node scripts/budget-summary.mjs <gate.json> [--format json|markdown] [--no-prompt]');
+    process.exit(1);
+  }
+  const gate = JSON.parse(await readFile(args.gatePath, 'utf-8'));
+  const summary = buildBudgetSummary(gate);
+  // --no-prompt: CI / non-interactive hosts collapse the checkpoint to a logging hop.
+  if (args.noPrompt) {
+    summary.shouldAsk = false;
+    summary.reason = 'forced false via --no-prompt (non-interactive host)';
+    summary.printContract = null;
+    summary.questionText = '';
+    summary.questionPayload = null;
+    summary.options = [];
+    summary.chatPreview = `Audit scope: no question needed — ${summary.reason}.`;
+    summary.exactChatMessage = {
+      body: summary.chatPreview,
+      lineCount: summary.chatPreview.split('\n').length,
+      sha256: createHash('sha256').update(summary.chatPreview).digest('hex'),
+    };
+    summary.printCheck = null;
+  }
+  if (args.format === 'markdown') {
+    process.stdout.write(renderBudgetSummaryMarkdown(summary) + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+  }
+}
+
+function parseArgs(argv) {
+  const out = { positional: [], format: 'json' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--format') out.format = argv[++i];
+    else if (a.startsWith('--format=')) out.format = a.slice('--format='.length);
+    else if (a === '--no-prompt') out.noPrompt = true;
+    else out.positional.push(a);
+  }
+  out.gatePath = out.positional[0];
+  return out;
+}
+
+main().catch((err) => {
+  console.error('[budget-summary] FAILED:', err.message);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/build-docs.mjs b/skills/vercel/vercel-optimize/scripts/build-docs.mjs
new file mode 100755
index 0000000..22c81c4
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/build-docs.mjs
@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Regenerates references/{scanner-patterns,candidates}.md from lib/{scanners,gates}/*
+// metadata. The .mjs files are the source of truth; check-docs-fresh.mjs blocks
+// PRs where the regenerated output diverges from what's checked in.
+
+import { writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { scanners } from '../lib/scanners/index.mjs';
+import { gates, MAX_CODE_CANDIDATES, GATE_VERSION } from '../lib/gates/index.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REFS = join(HERE, '..', 'references');
+
+const GENERATED_BANNER =
+  '<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->\n' +
+  '<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->\n' +
+  '<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->\n\n';
+
+async function main() {
+  await writeFile(join(REFS, 'scanner-patterns.md'), renderScanners());
+  await writeFile(join(REFS, 'candidates.md'), renderCandidates());
+  console.error('[build-docs] wrote scanner-patterns.md + candidates.md');
+}
+
+function renderScanners() {
+  const sorted = scanners.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Scanner patterns\n\n';
+  out += 'AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.\n\n';
+  out += `Total scanners: ${sorted.length}.\n\n`;
+  out += '## Patterns\n\n';
+  for (const s of sorted) {
+    const m = s.metadata;
+    out += `### \`${m.id}\` — ${m.title}\n\n`;
+    out += `- **Severity**: ${m.severity}\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Traffic-independent**: ${m.trafficIndependent ? 'yes (cold-path findings survive the doctrine drop)' : 'no (cold-path findings get dropped)'}\n\n`;
+    out += `**Description.** ${m.description}\n\n`;
+    out += `**Fix.** ${m.fix}\n\n`;
+    if (m.citations?.length) {
+      out += `**Citations:**\n${m.citations.map((c) => `- \`${c}\``).join('\n')}\n\n`;
+    }
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function renderCandidates() {
+  const sorted = gates.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Candidate gates\n\n';
+  out += 'The deterministic threshold expressions that turn observability signals into investigation candidates. Pure JS, no LLM. Thresholds live in `lib/gates/*.mjs`.\n\n';
+  out += `Total gates: ${sorted.length}. Budget cap: \`MAX_CODE_CANDIDATES = ${MAX_CODE_CANDIDATES}\`. Gate version: \`${GATE_VERSION}\`.\n\n`;
+  out += '## Gates\n\n';
+  for (const g of sorted) {
+    const m = g.metadata;
+    out += `### \`${m.id}\`\n\n`;
+    out += `- **Threshold**: \`${m.threshold}\`\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Scope**: ${m.scope}\n`;
+    out += `- **Source citation**: \`${m.sourceCitation}\`\n\n`;
+    out += `${m.description}\n\n`;
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function trimTrailingBlankLine(value) {
+  return value.replace(/\n{2,}$/, '\n');
+}
+
+main().catch((err) => {
+  console.error('[build-docs] FAILED:', err.message);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/check-citations.mjs b/skills/vercel/vercel-optimize/scripts/check-citations.mjs
new file mode 100644
index 0000000..2305d5c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/check-citations.mjs
@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Offline citation-library consistency checks. This intentionally does not
+// fetch URLs; it validates the local allow-list contract used by sanitizers.
+
+import { loadLibrary, matchesFrameworkVersion } from '../lib/citations.mjs';
+
+const URL_RE = /^https:\/\/[A-Za-z0-9.-]+\/\S*$/;
+const SKILL_REF_RE = /^[\w-]+:[\w-]+$/;
+const BANNED_STALE_URLS = new Set([
+  'https://nextjs.org/docs/app/api-reference/functions/cache-life',
+  'https://nextjs.org/docs/app/api-reference/functions/cache-tag',
+  'https://nextjs.org/docs/app/api-reference/functions/revalidate-tag',
+  'https://nextjs.org/docs/app/api-reference/functions/revalidate-path',
+  'https://nextjs.org/docs/app/api-reference/functions/cache',
+]);
+
+async function main() {
+  const lib = await loadLibrary();
+  const errors = [];
+
+  if (!Array.isArray(lib.urls)) errors.push('docs-library.urls must be an array');
+  if (!Array.isArray(lib.ruleSkillRefs)) errors.push('docs-library.ruleSkillRefs must be an array');
+
+  for (const [i, entry] of (lib.urls ?? []).entries()) {
+    const label = `urls[${i}]`;
+    if (!URL_RE.test(entry?.url ?? '')) errors.push(`${label}.url must be an https URL`);
+    if (BANNED_STALE_URLS.has(entry?.url)) {
+      errors.push(`${label}.url uses a stale Next.js docs path: ${entry.url}`);
+    }
+    if (typeof entry.topic !== 'string' || entry.topic.trim() === '') errors.push(`${label}.topic is required`);
+    if (!Array.isArray(entry.appliesTo)) errors.push(`${label}.appliesTo must be an array`);
+    validateFrameworks(entry.applicableFrameworks, `${label}.applicableFrameworks`, errors);
+  }
+
+  const seenRules = new Set();
+  for (const [i, entry] of (lib.ruleSkillRefs ?? []).entries()) {
+    const label = `ruleSkillRefs[${i}]`;
+    const ref = `${entry?.skill ?? ''}:${entry?.rule ?? ''}`;
+    if (!SKILL_REF_RE.test(ref)) errors.push(`${label} must contain skill + rule identifiers`);
+    if (seenRules.has(ref)) errors.push(`${label} duplicate: ${ref}`);
+    seenRules.add(ref);
+    if (typeof (entry.description ?? entry.topic) !== 'string' || (entry.description ?? entry.topic).trim() === '') {
+      errors.push(`${label}.topic or .description is required`);
+    }
+    validateFrameworks(entry.applicableFrameworks, `${label}.applicableFrameworks`, errors);
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`[check-citations] ${error}`);
+    process.exit(1);
+  }
+
+  console.error(`[check-citations] OK — ${lib.urls.length} URLs, ${lib.ruleSkillRefs.length} skill-rule refs`);
+}
+
+function validateFrameworks(patterns, label, errors) {
+  if (!Array.isArray(patterns) || patterns.length === 0) {
+    errors.push(`${label} must be a non-empty array`);
+    return;
+  }
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string' || pattern.trim() === '') {
+      errors.push(`${label} contains an empty pattern`);
+      continue;
+    }
+    if (pattern === '*') continue;
+    // Smoke-check parser coverage with a modern Next version. Unknown framework
+    // patterns are still valid as long as the syntax is recognizable.
+    if (!/^[\w-]+@(?:\*|\d+(?:\.\d+){0,2}|[<>]=?\s*\d+(?:\.\d+){0,2})(?:\s*\|\|\s*[\w-]+@(?:\*|\d+(?:\.\d+){0,2}|[<>]=?\s*\d+(?:\.\d+){0,2}))*$/.test(pattern)) {
+      errors.push(`${label} has unsupported pattern: ${pattern}`);
+      continue;
+    }
+    matchesFrameworkVersion(pattern, 'next', '16.0.0');
+  }
+}
+
+main().catch((err) => {
+  console.error('[check-citations] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/check-docs-fresh.mjs b/skills/vercel/vercel-optimize/scripts/check-docs-fresh.mjs
new file mode 100755
index 0000000..baf5720
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/check-docs-fresh.mjs
@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// CI gate: regenerate the reference docs in memory and diff against what's
+// checked in. Non-zero exit forces contributors to run build-docs.mjs.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { scanners } from '../lib/scanners/index.mjs';
+import { gates, MAX_CODE_CANDIDATES, GATE_VERSION } from '../lib/gates/index.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REFS = join(HERE, '..', 'references');
+
+const GENERATED_BANNER =
+  '<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->\n' +
+  '<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->\n' +
+  '<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->\n\n';
+
+async function main() {
+  const expected = {
+    'scanner-patterns.md': renderScanners(),
+    'candidates.md': renderCandidates(),
+  };
+
+  let stale = false;
+  for (const [name, content] of Object.entries(expected)) {
+    let actual;
+    try { actual = await readFile(join(REFS, name), 'utf-8'); }
+    catch {
+      console.error(`[check-docs-fresh] ${name} does not exist. Run \`node scripts/build-docs.mjs\`.`);
+      stale = true;
+      continue;
+    }
+    if (actual !== content) {
+      console.error(`[check-docs-fresh] ${name} is stale. Run \`node scripts/build-docs.mjs\` and commit.`);
+      stale = true;
+    }
+  }
+
+  if (stale) process.exit(1);
+  console.error('[check-docs-fresh] OK — generated docs match source');
+}
+
+// MUST stay byte-identical to build-docs.mjs renderers — duplication is the contract.
+function renderScanners() {
+  const sorted = scanners.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Scanner patterns\n\n';
+  out += 'AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.\n\n';
+  out += `Total scanners: ${sorted.length}.\n\n`;
+  out += '## Patterns\n\n';
+  for (const s of sorted) {
+    const m = s.metadata;
+    out += `### \`${m.id}\` — ${m.title}\n\n`;
+    out += `- **Severity**: ${m.severity}\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Traffic-independent**: ${m.trafficIndependent ? 'yes (cold-path findings survive the doctrine drop)' : 'no (cold-path findings get dropped)'}\n\n`;
+    out += `**Description.** ${m.description}\n\n`;
+    out += `**Fix.** ${m.fix}\n\n`;
+    if (m.citations?.length) {
+      out += `**Citations:**\n${m.citations.map((c) => `- \`${c}\``).join('\n')}\n\n`;
+    }
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function renderCandidates() {
+  const sorted = gates.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Candidate gates\n\n';
+  out += 'The deterministic threshold expressions that turn observability signals into investigation candidates. Pure JS, no LLM. Thresholds live in `lib/gates/*.mjs`.\n\n';
+  out += `Total gates: ${sorted.length}. Budget cap: \`MAX_CODE_CANDIDATES = ${MAX_CODE_CANDIDATES}\`. Gate version: \`${GATE_VERSION}\`.\n\n`;
+  out += '## Gates\n\n';
+  for (const g of sorted) {
+    const m = g.metadata;
+    out += `### \`${m.id}\`\n\n`;
+    out += `- **Threshold**: \`${m.threshold}\`\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Scope**: ${m.scope}\n`;
+    out += `- **Source citation**: \`${m.sourceCitation}\`\n\n`;
+    out += `${m.description}\n\n`;
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function trimTrailingBlankLine(value) {
+  return value.replace(/\n{2,}$/, '\n');
+}
+
+main().catch((err) => {
+  console.error('[check-docs-fresh] FAILED:', err.message);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/collect-signals.mjs b/skills/vercel/vercel-optimize/scripts/collect-signals.mjs
new file mode 100755
index 0000000..2831fb9
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/collect-signals.mjs
@@ -0,0 +1,576 @@
+#!/usr/bin/env node
+// Emits signals.json: Vercel CLI capability probe + project config + plan +
+// usage + codebase stack + metric queries. Status → stderr, JSON → stdout.
+// Degrades gracefully when capabilities are missing.
+
+import {
+  checkCliVersion,
+  checkAuth,
+  resolveProjectId,
+  resolveCommandScope,
+  hasObservabilityPlus,
+  checkObservabilityPlusConfiguration,
+  getMetricsSchema,
+  getProjectConfig,
+  getAccountPlan,
+  getContract,
+  getUsage,
+  filterUsageByProject,
+  inferPlan,
+  queryMetric,
+  detectStack,
+  redactSensitiveText,
+} from '../lib/vercel.mjs';
+import { classifyFrameworkSupport } from '../lib/framework-support.mjs';
+import { QUERIES, TIME_WINDOW, normalizerFor } from '../lib/queries.mjs';
+
+const SCHEMA_VERSION = '1.2';
+
+const log = (...args) => console.error('[collect-signals]', ...args);
+
+function parseArgs(argv) {
+  let explicitProjectId = null;
+  let continueWithoutObservability = process.env.VERCEL_OPTIMIZE_CONTINUE_WITHOUT_OBSERVABILITY === '1';
+  let continueUnsupportedFramework = process.env.VERCEL_OPTIMIZE_CONTINUE_UNSUPPORTED_FRAMEWORK === '1';
+
+  for (const arg of argv) {
+    if (arg === '--continue-without-observability') {
+      continueWithoutObservability = true;
+      continue;
+    }
+    if (arg === '--continue-unsupported-framework') {
+      continueUnsupportedFramework = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      throw new Error(`UNKNOWN_ARG: ${arg}`);
+    }
+    if (!explicitProjectId) {
+      explicitProjectId = arg;
+      continue;
+    }
+    throw new Error(`UNKNOWN_ARG: ${arg}`);
+  }
+
+  return { explicitProjectId, continueWithoutObservability, continueUnsupportedFramework };
+}
+
+async function main() {
+  const { explicitProjectId, continueWithoutObservability, continueUnsupportedFramework } = parseArgs(process.argv.slice(2));
+
+  log('checking Vercel CLI version…');
+  const cli = await checkCliVersion();
+  log(`vercel CLI v${cli.join('.')} OK`);
+
+  log('checking auth…');
+  await checkAuth();
+  log('auth OK');
+
+  log('resolving project id…');
+  const project = await resolveProjectId(explicitProjectId);
+  if (!project) {
+    throw new Error(
+      'NO_PROJECT_ID: pass one as argv, set VERCEL_PROJECT_ID, or run `vercel link` in this directory.'
+    );
+  }
+  log(`project link resolved (source=${project.source}; teamScope=${project.orgId ? 'yes' : 'no'})`);
+
+  if (!project.orgId) {
+    throw new Error('PROJECT_SCOPE_UNRESOLVED: the project was resolved without an owner account. Ask the user which Vercel team or personal scope owns the project, then rerun from a linked app directory or set VERCEL_PROJECT_ID with VERCEL_ORG_ID for that scope.');
+  }
+
+  log('checking framework support…');
+  const stack = await detectStack();
+  const frameworkSupport = classifyFrameworkSupport(stack);
+  log(`framework=${stack.framework}@${stack.frameworkVersion ?? '?'} support=${frameworkSupport.status}`);
+
+  if (!frameworkSupport.ok && !continueUnsupportedFramework) {
+    writeOutput({
+      schemaVersion: SCHEMA_VERSION,
+      collectedAt: new Date().toISOString(),
+      timeWindow: TIME_WINDOW,
+      projectId: project.projectId,
+      orgId: project.orgId,
+      projectIdSource: project.source,
+      commandScope: null,
+      frameworkSupport,
+      frameworkSupportBlocker: frameworkSupport.blocker,
+      frameworkSupportDetail: frameworkSupport.detail,
+      observabilityPlus: null,
+      observabilityPlusPreflight: null,
+      observabilityPlusUsable: null,
+      observabilityPlusBlocker: null,
+      observabilityPlusBlockerDetail: null,
+      plan: {
+        plan: 'uncertain',
+        reason: 'not collected before unsupported-framework confirmation',
+      },
+      project: null,
+      contract: null,
+      usage: null,
+      usageScope: null,
+      usageTeamTotal: null,
+      usageError: 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK',
+      stack,
+      metrics: {},
+      metricsSchema: null,
+    }, { usable: true, blocker: null, detail: 'Observability Plus was not checked.' }, frameworkSupport);
+    return;
+  }
+
+  if (!frameworkSupport.ok && continueUnsupportedFramework) {
+    log('continuing after unsupported framework blocker because --continue-unsupported-framework was set');
+  }
+
+  log('resolving Vercel CLI command scope…');
+  const commandScope = await resolveCommandScope(project);
+  if (!commandScope.ok) {
+    throw new Error(`SCOPE_UNRESOLVED: ${commandScope.detail} Run \`vercel switch <team>\` or re-link with \`vercel link --yes --project <project-name-or-id> --team <team-slug>\`.`);
+  }
+  const scope = commandScope.cliScope || undefined;
+  log(`command scope resolved (source=${commandScope.source}; scoped=${scope ? 'yes' : 'no'})`);
+
+  log('validating linked project belongs to the resolved scope…');
+  const projectCfg = await getProjectConfig(project.projectId, project.orgId);
+  const projectScope = validateProjectScope(projectCfg, project);
+  if (!projectScope.ok) {
+    throw new Error(`PROJECT_SCOPE_MISMATCH: ${projectScope.detail} Ask the user to confirm the exact Vercel project and team/personal scope, then rerun after \`vercel link --yes --project <project-name-or-id> --team <team-slug>\` or after setting both VERCEL_PROJECT_ID and VERCEL_ORG_ID for the intended scope.`);
+  }
+  log(`project scope verified (source=${projectScope.source})`);
+
+  log('checking Observability Plus configuration…');
+  const observabilityPlusConfig = await checkObservabilityPlusConfiguration({
+    orgId: project.orgId,
+    projectId: project.projectId,
+  });
+  log(`observabilityPlusPreflight=${observabilityPlusConfig.access === true ? 'enabled' : observabilityPlusConfig.blocker ?? 'unknown'} (${observabilityPlusConfig.source})`);
+
+  let oplus = observabilityPlusConfig.access === true;
+  if (observabilityPlusConfig.access == null) {
+    log('Observability Plus configuration preflight inconclusive; falling back to metrics schema probe…');
+    oplus = await hasObservabilityPlus(scope);
+  }
+  log(`observabilityPlus=${oplus}`);
+
+  const schema = oplus ? await getMetricsSchema(scope) : null;
+  if (oplus && schema) {
+    const count = Array.isArray(schema) ? schema.length : (schema.metrics?.length ?? 0);
+    log(`metric catalog: ${count} metrics available`);
+  }
+
+  // Check one cheap metric before pulling slower project context. If this fails,
+  // the orchestrator can ask the user immediately instead of waiting on billing.
+  let metrics = {};
+  let metricsCanaryOk = false;
+  if (oplus) {
+    log(`checking Observability Plus metrics access (window=${TIME_WINDOW})…`);
+    const t0 = Date.now();
+    const canary = await queryMetric('vercel.request.count', {
+      aggregation: 'sum',
+      since: TIME_WINDOW,
+      limit: 1,
+      scope,
+    });
+    metricsCanaryOk = !!canary?.ok;
+    if (!metricsCanaryOk) {
+      metrics = {
+        observabilityPlusCanary: {
+          ...canary,
+          metricId: 'vercel.request.count',
+          aggregation: 'sum',
+        },
+      };
+      log(`metrics access check failed: ${canary?.code ?? 'unknown'} — skipping full metrics fan-out`);
+    } else {
+      log(`metrics access check passed in ${Date.now() - t0}ms`);
+    }
+  } else {
+    log('skipping metric queries (Observability Plus preflight did not confirm access)');
+  }
+
+  let oplusDiag = observabilityPlusConfig.access === false
+    ? {
+        usable: false,
+        blocker: observabilityPlusConfig.blocker,
+        detail: observabilityPlusConfig.detail,
+      }
+    : (metricsCanaryOk
+        ? { usable: true, blocker: null, detail: 'Observability Plus metrics access check passed.' }
+        : diagnoseObservabilityPlus(metrics, oplus));
+
+  if (!oplusDiag.usable && !continueWithoutObservability) {
+    writeOutput({
+      schemaVersion: SCHEMA_VERSION,
+      collectedAt: new Date().toISOString(),
+      timeWindow: TIME_WINDOW,
+      projectId: project.projectId,
+      orgId: project.orgId,
+      projectIdSource: project.source,
+      commandScope,
+      observabilityPlus: oplus,
+      observabilityPlusPreflight: observabilityPlusConfig,
+      observabilityPlusUsable: oplusDiag.usable,
+      observabilityPlusBlocker: oplusDiag.blocker,
+      observabilityPlusBlockerDetail: oplusDiag.detail,
+      frameworkSupport,
+      frameworkSupportBlocker: frameworkSupport.blocker,
+      frameworkSupportDetail: frameworkSupport.detail,
+      plan: {
+        plan: 'uncertain',
+        reason: 'not collected before Observability Plus blocker confirmation',
+      },
+      project: projectCfg,
+      contract: null,
+      usage: null,
+      usageScope: null,
+      usageTeamTotal: null,
+      usageError: 'NOT_COLLECTED_OBSERVABILITY_BLOCKED',
+      stack: null,
+      metrics,
+      metricsSchema: schema,
+    }, oplusDiag);
+    return;
+  }
+
+  if (!oplusDiag.usable && continueWithoutObservability) {
+    log('continuing after Observability Plus blocker because --continue-without-observability was set');
+  }
+
+  log('pulling account plan + contract + usage in parallel…');
+  const [accountPlan, contract, usageResult] = await Promise.all([
+    getAccountPlan(project.orgId || scope),
+    getContract(scope),
+    getUsage({ days: 14, scope }),
+  ]);
+
+  let usage = null;
+  let usageContextMismatch = false;
+  let usageTotalCost = null;
+  let usageScope = 'team';
+  let usageTeamTotal = null;
+  if (usageResult?.ok) {
+    usage = usageResult.data;
+    const contractContext = contract?.context;
+    if (usage?.context && contractContext && usage.context !== contractContext) {
+      usageContextMismatch = true;
+      log(`usage: WARNING context mismatch — returned context=${usage.context} but project team=${contractContext}; treating usage as unavailable for this project`);
+      usage = null;
+    } else {
+      // Capture team total pre-filter so the report can label "this project vs team-wide" honestly.
+      usageTeamTotal = sumUsageCosts(usage);
+      const filterResult = filterUsageByProject(usage, project.projectId, projectCfg?.name);
+      if (filterResult.matched) {
+        usage = filterResult.filtered;
+        usageScope = 'project';
+        usageTotalCost = sumUsageCosts(usage);
+        log(`usage: filtered to project — ~$${usageTotalCost.toFixed(2)} (team-wide ~$${usageTeamTotal.toFixed(2)}; unattributed ~$${filterResult.unattributedTotal.toFixed(2)})`);
+      } else {
+        usageTotalCost = usageTeamTotal;
+        log(`usage: ~$${usageTotalCost.toFixed(2)} billed across services (team-wide — no per-project usage rows matched the linked project; report will label this team-wide)`);
+      }
+    }
+  } else {
+    log(`usage: unavailable (${usageResult?.code ?? 'unknown'}) — degrading to scanner+metrics-only mode`);
+  }
+
+  const planInfo = inferPlan(contract, { accountPlan, usageTotalCost });
+  log(`plan=${planInfo.plan} (${planInfo.reason})`);
+
+  if (projectCfg?.error) {
+    log(`project config: failed (${projectCfg.error}) — gates that need it will skip`);
+  }
+
+  log(`stack: ${stack.framework}@${stack.frameworkVersion ?? '?'} ${stack.hasAppRouter ? 'app-router' : ''}${stack.hasPagesRouter ? ' pages-router' : ''}${stack.orm !== 'none' ? ` orm=${stack.orm}` : ''}`);
+
+  // Each query is wrapped; one failure degrades only that metric.
+  if (oplus && metricsCanaryOk) {
+    log(`querying observability metrics (${QUERIES.length} metrics in parallel)…`);
+    const t0 = Date.now();
+    metrics = await collectMetrics(scope);
+    const wallMs = Date.now() - t0;
+    const counts = Object.fromEntries(
+      Object.entries(metrics).map(([k, v]) => {
+        if (!v) return [k, 'null'];
+        if (!v.ok) return [k, `err:${v.code}`];
+        const rows = Array.isArray(v.rows) ? v.rows.length : 0;
+        return [k, `${rows} rows`];
+      })
+    );
+    log(`metrics collected in ${wallMs}ms: ${JSON.stringify(counts)}`);
+  }
+
+  // The `vercel metrics schema` probe alone is NOT a reliable usability signal:
+  // it can return OK while per-route queries fail with payment_required (metrics
+  // unavailable for the team) or FORBIDDEN (auth-scope mismatch). Diagnose AFTER
+  // running queries by counting failure codes so the orchestrator can PAUSE and
+  // surface the choice before falling back to scanner-only mode.
+  oplusDiag = observabilityPlusConfig.access === false
+    ? {
+        usable: false,
+        blocker: observabilityPlusConfig.blocker,
+        detail: observabilityPlusConfig.detail,
+      }
+    : diagnoseObservabilityPlus(metrics, oplus);
+
+
+  const output = {
+    schemaVersion: SCHEMA_VERSION,
+    collectedAt: new Date().toISOString(),
+    timeWindow: TIME_WINDOW,
+    projectId: project.projectId,
+    orgId: project.orgId,
+    projectIdSource: project.source,
+    commandScope,
+    observabilityPlus: oplus,
+    observabilityPlusPreflight: observabilityPlusConfig,
+    observabilityPlusUsable: oplusDiag.usable,
+    observabilityPlusBlocker: oplusDiag.blocker,
+    observabilityPlusBlockerDetail: oplusDiag.detail,
+    frameworkSupport,
+    frameworkSupportBlocker: frameworkSupport.blocker,
+    frameworkSupportDetail: frameworkSupport.detail,
+    plan: planInfo,
+    project: projectCfg,
+    contract,
+    usage,
+    usageScope,
+    usageTeamTotal,
+    usageError: usageResult?.ok
+      ? (usageContextMismatch ? 'USAGE_CONTEXT_MISMATCH' : null)
+      : (usageResult?.code ?? 'UNKNOWN'),
+    stack,
+    metrics,
+    metricsSchema: schema,
+  };
+
+  writeOutput(output, oplusDiag);
+}
+
+function writeOutput(output, oplusDiag, frameworkSupport = output.frameworkSupport) {
+  if (frameworkSupport?.blocker) {
+    log(`⚠ Framework is not supported for metric-backed route-to-file optimization: ${frameworkSupport.detail}`);
+    log('   The orchestrator should PAUSE and ask whether to continue with a limited platform/scanner audit.');
+  }
+  if (!oplusDiag.usable) {
+    log(`⚠ Observability Plus is NOT usable on this project: blocker=${oplusDiag.blocker} (${oplusDiag.detail})`);
+    log('   The orchestrator should PAUSE and follow the blocker-specific remediation before proceeding.');
+  }
+
+  process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+  log('done');
+}
+
+function validateProjectScope(projectCfg, project) {
+  if (!projectCfg || projectCfg.error) {
+    return {
+      ok: false,
+      source: 'project-api',
+      detail: `The resolved account could not read the resolved project (project API error=${projectCfg?.error ?? 'unknown'}).`,
+    };
+  }
+
+  if (projectCfg.id && String(projectCfg.id) !== String(project.projectId)) {
+    return {
+      ok: false,
+      source: 'project-api',
+      detail: 'The project API returned a different project than the collector resolved from the link or environment.',
+    };
+  }
+
+  const ownerId = firstString(
+    projectCfg.accountId,
+    projectCfg.orgId,
+    projectCfg.ownerId,
+    projectCfg.teamId,
+    projectCfg.team?.id,
+    projectCfg.account?.id,
+    projectCfg.owner?.id,
+  );
+  if (ownerId && project.orgId && String(ownerId) !== String(project.orgId)) {
+    return {
+      ok: false,
+      source: 'project-api',
+      detail: 'The project API returned an owner account that differs from the collector-resolved account.',
+    };
+  }
+
+  return {
+    ok: true,
+    source: ownerId ? 'project-api-owner' : 'project-api-readable',
+  };
+}
+
+function firstString(...values) {
+  return values.find((value) => typeof value === 'string' && value.trim() !== '') ?? null;
+}
+
+async function collectMetrics(scope) {
+  const results = await Promise.all(
+    QUERIES.map(async (entry) => {
+      const r = await queryMetric(entry.metricId, {
+        aggregation: entry.aggregation,
+        groupBy: entry.groupBy,
+        filter: entry.filter,
+        since: TIME_WINDOW,
+        limit: entry.limit,
+        scope,
+      });
+      return [entry, r];
+    })
+  );
+
+  const out = {};
+  for (const [entry, result] of results) {
+    out[entry.id] = enrichEntry(entry, result);
+  }
+  return out;
+}
+
+function enrichEntry(entry, result) {
+  if (!result?.ok) {
+    return {
+      ...result,
+      metricId: entry.metricId,
+      aggregation: entry.aggregation,
+      groupBy: entry.groupBy,
+    };
+  }
+  const normalize = normalizerFor(entry);
+  const { rows } = normalize(result.data);
+  return {
+    ...result,
+    rows,
+    metricId: entry.metricId,
+    aggregation: entry.aggregation,
+    groupBy: entry.groupBy,
+  };
+}
+
+// `vercel usage --format json` shape is documented but not stable across CLI
+// versions; try several roots, return null if none match.
+function sumUsageCosts(usage) {
+  if (!usage) return null;
+  if (typeof usage.totalCost === 'number') return usage.totalCost;
+  if (typeof usage.totals?.billedCost === 'number') return usage.totals.billedCost;
+  if (Array.isArray(usage.services)) {
+    return usage.services.reduce((s, x) => s + (x.billedCost ?? x.cost ?? 0), 0);
+  }
+  if (Array.isArray(usage.breakdown?.data)) {
+    return usage.breakdown.data.reduce((s, d) => {
+      if (Array.isArray(d.services)) {
+        return s + d.services.reduce((ss, x) => ss + (x.billedCost ?? x.cost ?? 0), 0);
+      }
+      return s + (d.billedCost ?? d.cost ?? 0);
+    }, 0);
+  }
+  return null;
+}
+
+// Returns { usable, blocker, detail }. `blocker` enum:
+//   null | 'no_oplus_probe' | 'project_disabled' | 'payment_required' |
+//   'forbidden' | 'daily_quota_exceeded' | 'project_not_found' |
+//   'not_linked' | 'all_failed_other' | 'no_traffic'
+export function diagnoseObservabilityPlus(metrics, oplusProbe) {
+  if (!oplusProbe) {
+    return {
+      usable: false,
+      blocker: 'no_oplus_probe',
+      detail: 'vercel metrics schema returned non-OK; the team does not have Observability Plus enabled.',
+    };
+  }
+
+  const entries = Object.values(metrics);
+  if (entries.length === 0) {
+    return { usable: false, blocker: 'no_oplus_probe', detail: 'No metrics were attempted.' };
+  }
+
+  const failures = entries.filter((m) => m && m.ok === false);
+  const successes = entries.filter((m) => m && m.ok !== false);
+
+  if (successes.length === 0) {
+    const codeCounts = new Map();
+    for (const f of failures) {
+      const code = String(f.code ?? 'unknown').toLowerCase();
+      codeCounts.set(code, (codeCounts.get(code) ?? 0) + 1);
+    }
+    const top = [...codeCounts.entries()].sort((a, b) => b[1] - a[1])[0];
+    const topCode = top?.[0] ?? 'unknown';
+    if (/daily_quota_exceeded/.test(topCode)) {
+      return {
+        usable: false,
+        blocker: 'daily_quota_exceeded',
+        detail: `${top[1]}/${entries.length} metric queries hit the daily Observability query limit. Retry after the next UTC midnight reset.`,
+      };
+    }
+    if (/payment_required/.test(topCode)) {
+      const text = failures
+        .map((f) => `${f.message ?? ''}\n${f.stderr ?? ''}`)
+        .join('\n')
+        .toLowerCase();
+      if (
+        /subscription to observability plus[\s\S]{0,160}required/.test(text) ||
+        /observability plus[\s\S]{0,160}not enabled/.test(text)
+      ) {
+        return {
+          usable: false,
+          blocker: 'no_oplus_probe',
+          detail: `${top[1]}/${entries.length} metric queries need route-level Observability Plus data. Enable Observability Plus, then re-run the metric-backed audit.`,
+        };
+      }
+      return {
+        usable: false,
+        blocker: 'payment_required',
+        detail: `${top[1]}/${entries.length} metric queries returned payment_required. Route-level metrics were recognized for this team, but these queries are not usable. Check the team's Observability Plus subscription or event quota.`,
+      };
+    }
+    if (/forbidden|not_authorized|403/.test(topCode)) {
+      return {
+        usable: false,
+        blocker: 'forbidden',
+        detail: `${top[1]}/${entries.length} metric queries returned FORBIDDEN. Auth-scope mismatch — likely logged in to the wrong team (run \`vercel switch\`).`,
+      };
+    }
+    if (/project_not_found/.test(topCode)) {
+      return {
+        usable: false,
+        blocker: 'project_not_found',
+        detail: `Project ID not visible to the auth'd team. Run \`vercel switch\` or verify the project ID.`,
+      };
+    }
+    if (/not_linked/.test(topCode)) {
+      return {
+        usable: false,
+        blocker: 'not_linked',
+        detail: `${top[1]}/${entries.length} metric queries returned NOT_LINKED. Link the app directory first: \`vercel link --yes --project <project-name-or-id> --cwd <project-dir>\`; add \`--team <team-id-or-slug>\` when the team is known.`,
+      };
+    }
+    return {
+      usable: false,
+      blocker: 'all_failed_other',
+      detail: `Every metric query failed; top error code was \`${topCode}\` (${top?.[1]}/${entries.length}).`,
+    };
+  }
+
+  // Some queries succeeded; zero rows across the board = "no traffic in window",
+  // NOT an Observability Plus billing issue.
+  const totalRows = successes.reduce((s, m) => s + (Array.isArray(m.rows) ? m.rows.length : 0), 0);
+  if (totalRows === 0) {
+    return {
+      usable: true,
+      blocker: 'no_traffic',
+      detail: 'Observability Plus queries succeeded but every metric returned 0 rows. Either the project has no traffic in the 14-day window, or Observability Plus retention is limited (free tier = 1 day on Pro).',
+    };
+  }
+
+  return { usable: true, blocker: null, detail: 'Observability Plus is usable; queries returned data.' };
+}
+
+// Run main() only as a CLI; the test suite imports diagnoseObservabilityPlus directly.
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch((err) => {
+    console.error('[collect-signals] FAILED:', redactSensitiveText(err.message));
+    process.exit(1);
+  });
+}
diff --git a/skills/vercel/vercel-optimize/scripts/collect-sub-agent-outputs.mjs b/skills/vercel/vercel-optimize/scripts/collect-sub-agent-outputs.mjs
new file mode 100644
index 0000000..8699874
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/collect-sub-agent-outputs.mjs
@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// Collect raw sub-agent outputs into the recommendations.json array consumed by
+// verify-and-regen. Sub-agent hosts often wrap JSON in prose or markdown fences,
+// so extraction is permissive while candidateRef coverage stays strict.
+
+import { readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve, basename } from 'node:path';
+
+const log = (...a) => console.error('[collect-sub-agent-outputs]', ...a);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.inputs.length === 0 && !args.manifestPath) {
+    console.error('usage: node scripts/collect-sub-agent-outputs.mjs [--manifest briefs/manifest.json] <output-file-or-dir...> [--out recommendations.json] [--strict]');
+    process.exit(1);
+  }
+
+  const manifest = args.manifestPath
+    ? JSON.parse(await readFile(args.manifestPath, 'utf-8'))
+    : null;
+  const expected = manifest ? readExpectedBriefs(manifest) : [];
+  const preResolvedRecords = manifest ? readPreResolvedRecords(manifest) : [];
+  const files = args.inputs.length > 0 ? await collectInputFiles(args.inputs) : [];
+  const collected = [];
+  const summary = {
+    files: files.length,
+    kept: 0,
+    abstained: 0,
+    parseFailed: 0,
+    nonObject: 0,
+    missingCandidateRef: 0,
+  };
+  const errors = [];
+
+  for (const file of files) {
+    const raw = await readFile(file, 'utf-8');
+    const extracted = extractJsonValue(raw);
+    if (!extracted.ok) {
+      summary.parseFailed++;
+      const msg = `${file}: ${extracted.reason}`;
+      if (args.strict) errors.push(msg);
+      else log(`warn: ${msg}`);
+      continue;
+    }
+
+    const records = normalizeOutput(extracted.value);
+    if (records.length === 0) {
+      summary.nonObject++;
+      const msg = `${file}: JSON did not contain a recommendation or abstention object`;
+      if (args.strict) errors.push(msg);
+      else log(`warn: ${msg}`);
+      continue;
+    }
+
+    for (const record of records) {
+      const candidateRef = record.candidateRef ?? inferCandidateRefFromFile(file, expected, records.length);
+      if (!candidateRef) {
+        summary.missingCandidateRef++;
+        errors.push(`${file}: output is missing candidateRef`);
+        continue;
+      }
+      collected.push({
+        sourcePath: file,
+        record: record.candidateRef ? record : { ...record, candidateRef },
+      });
+    }
+  }
+
+  let ordered = collected;
+  if (expected.length > 0) {
+    const byRef = new Map();
+    for (const item of collected) {
+      const ref = item.record.candidateRef;
+      if (!expected.some((b) => b.candidateRef === ref)) {
+        errors.push(`${item.sourcePath}: unknown candidateRef ${ref}`);
+        continue;
+      }
+      if (byRef.has(ref)) {
+        errors.push(`${item.sourcePath}: duplicate output for candidateRef ${ref}`);
+        continue;
+      }
+      byRef.set(ref, item);
+    }
+    const missing = expected.filter((b) => !byRef.has(b.candidateRef));
+    for (const b of missing) errors.push(`missing output for candidateRef ${b.candidateRef}`);
+    ordered = expected.map((b) => byRef.get(b.candidateRef)).filter(Boolean);
+  } else {
+    ordered = collected.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
+  }
+
+  const records = [...preResolvedRecords, ...ordered.map((item) => item.record)];
+  summary.kept = records.filter((r) => r?.abstain !== true).length;
+  summary.abstained = records.filter((r) => r?.abstain === true).length;
+
+  if (errors.length > 0) {
+    for (const e of errors) log(`error: ${e}`);
+    process.exit(2);
+  }
+  if (records.length === 0) {
+    log('error: no recommendation or abstention records collected');
+    process.exit(2);
+  }
+
+  const serialized = JSON.stringify(records, null, 2) + '\n';
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeFile(args.outPath, serialized, 'utf-8');
+    log(`wrote ${serialized.length}B → ${args.outPath}`);
+  } else {
+    process.stdout.write(serialized);
+  }
+  log(`done: ${summary.files} files, ${summary.kept} recommendation draft(s), ${summary.abstained} found no supported change, ${summary.parseFailed} parse failed, ${summary.nonObject} invalid output(s)`);
+}
+
+function parseArgs(argv) {
+  const out = { inputs: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--manifest') out.manifestPath = resolve(argv[++i]);
+    else if (a.startsWith('--manifest=')) out.manifestPath = resolve(a.slice('--manifest='.length));
+    else if (a === '--out') out.outPath = resolve(argv[++i]);
+    else if (a.startsWith('--out=')) out.outPath = resolve(a.slice('--out='.length));
+    else if (a === '--strict') out.strict = true;
+    else out.inputs.push(resolve(a));
+  }
+  return out;
+}
+
+async function collectInputFiles(paths) {
+  const out = [];
+  for (const p of paths) {
+    const s = await stat(p);
+    if (s.isDirectory()) out.push(...await walkDir(p));
+    else if (s.isFile()) out.push(p);
+  }
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+async function walkDir(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.name.startsWith('.')) continue;
+    const p = resolve(dir, e.name);
+    if (e.isDirectory()) out.push(...await walkDir(p));
+    else if (e.isFile()) out.push(p);
+  }
+  return out;
+}
+
+function readExpectedBriefs(manifest) {
+  if (!manifest || typeof manifest !== 'object' || !Array.isArray(manifest.briefs)) {
+    throw new TypeError('manifest must contain a briefs array');
+  }
+  return manifest.briefs.map((b, i) => {
+    if (!b?.candidateRef) throw new TypeError(`manifest.briefs[${i}].candidateRef is required`);
+    return {
+      group: b.group ?? null,
+      index: b.index ?? i,
+      candidateRef: b.candidateRef,
+    };
+  });
+}
+
+function readPreResolvedRecords(manifest) {
+  if (!manifest || !Array.isArray(manifest.preResolvedRecords)) return [];
+  return manifest.preResolvedRecords.map((r, i) => {
+    if (!isRecordObject(r)) {
+      throw new TypeError(`manifest.preResolvedRecords[${i}] must be a recommendation or no-recommendation record`);
+    }
+    if (!r.candidateRef) {
+      throw new TypeError(`manifest.preResolvedRecords[${i}].candidateRef is required`);
+    }
+    return r;
+  });
+}
+
+function extractJsonValue(raw) {
+  for (const block of extractFenceBlocks(raw)) {
+    const parsed = tryParseJson(block);
+    if (parsed.ok) return parsed;
+  }
+  const full = tryParseJson(raw);
+  if (full.ok) return full;
+  for (const span of findBalancedJsonSpans(raw)) {
+    const parsed = tryParseJson(span);
+    if (parsed.ok) return parsed;
+  }
+  return { ok: false, reason: 'no valid JSON object or array found' };
+}
+
+function extractFenceBlocks(raw) {
+  const out = [];
+  const re = /```(?:json|JSON)?\s*\n([\s\S]*?)```/g;
+  let m;
+  while ((m = re.exec(raw)) !== null) out.push(m[1].trim());
+  return out;
+}
+
+function tryParseJson(raw) {
+  try {
+    return { ok: true, value: JSON.parse(raw.trim()) };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+function findBalancedJsonSpans(raw) {
+  const spans = [];
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch !== '{' && ch !== '[') continue;
+    const closeFor = ch === '{' ? '}' : ']';
+    const stack = [closeFor];
+    let inString = false;
+    let escape = false;
+    for (let j = i + 1; j < raw.length; j++) {
+      const c = raw[j];
+      if (inString) {
+        if (escape) escape = false;
+        else if (c === '\\') escape = true;
+        else if (c === '"') inString = false;
+        continue;
+      }
+      if (c === '"') {
+        inString = true;
+        continue;
+      }
+      if (c === '{') stack.push('}');
+      else if (c === '[') stack.push(']');
+      else if (c === '}' || c === ']') {
+        if (stack.at(-1) !== c) break;
+        stack.pop();
+        if (stack.length === 0) {
+          spans.push(raw.slice(i, j + 1));
+          i = j;
+          break;
+        }
+      }
+    }
+  }
+  return spans;
+}
+
+function normalizeOutput(value) {
+  const unwrapped = unwrapEnvelope(value);
+  if (Array.isArray(unwrapped)) return unwrapped.filter(isRecordObject);
+  if (isRecordObject(unwrapped)) return [unwrapped];
+  if (unwrapped && typeof unwrapped === 'object') {
+    if (isRecordObject(unwrapped.recommendation)) return [unwrapped.recommendation];
+    if (Array.isArray(unwrapped.recommendations)) return unwrapped.recommendations.filter(isRecordObject);
+  }
+  return [];
+}
+
+function unwrapEnvelope(value) {
+  let current = value;
+  for (let depth = 0; depth < 2; depth++) {
+    if (!current || typeof current !== 'object' || Array.isArray(current)) return current;
+    if (Array.isArray(current.recommendations) || current.recommendation) return current;
+    const keys = Object.keys(current);
+    const envelopeKey = ['data', 'result', 'insights'].find((k) => keys.length === 1 && k in current);
+    if (!envelopeKey) return current;
+    current = current[envelopeKey];
+  }
+  return current;
+}
+
+function isRecordObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  if (value.abstain === true) return true;
+  return ['what', 'why', 'fix', 'bucket', 'affectedFiles', 'citations'].some((k) => k in value);
+}
+
+function inferCandidateRefFromFile(file, expected, recordCount) {
+  if (recordCount !== 1 || expected.length === 0) return null;
+  if (expected.length === 1) return expected[0].candidateRef;
+  const name = basename(file);
+  const matches = expected.filter((b) => {
+    if (!b.group && b.index == null) return false;
+    const group = escapeRegExp(String(b.group ?? ''));
+    const index = escapeRegExp(String(b.index));
+    return new RegExp(`(?:^|[^A-Za-z0-9])${group}[-_.]?${index}(?:[^A-Za-z0-9]|$)`).test(name);
+  });
+  return matches.length === 1 ? matches[0].candidateRef : null;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+main().catch((err) => {
+  console.error('[collect-sub-agent-outputs] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/deep-dive.mjs b/skills/vercel/vercel-optimize/scripts/deep-dive.mjs
new file mode 100755
index 0000000..497d32a
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/deep-dive.mjs
@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// Runs AFTER gate-investigations.mjs and BEFORE any sub-agent reads source.
+// Attaches per-candidate evidence.deepDive to gate.toLaunch + gate.platform.
+// Byte-stable apart from totalWallMs; each CLI query is isolated.
+
+import { readFile } from 'node:fs/promises';
+import { queryMetric, readProjectJson, resolveCommandScope } from '../lib/vercel.mjs';
+import { specsForCandidate, mergeIntoEvidence, SCANNER_KINDS, TIME_WINDOW } from '../lib/deep-dive.mjs';
+
+const SCHEMA_VERSION = '1.0';
+const log = (...a) => console.error('[deep-dive]', ...a);
+
+async function main() {
+  // --cwd is load-bearing: the Vercel CLI resolves project/team from cwd's
+  // .vercel/project.json. Outside the project, metric queries silently hit the
+  // wrong team and look like "no traffic". We hard-fail on mismatch below.
+  const positional = [];
+  let explicitCwd = null;
+  for (let i = 2; i < process.argv.length; i++) {
+    const a = process.argv[i];
+    if (a === '--cwd' && i + 1 < process.argv.length) {
+      explicitCwd = process.argv[++i];
+    } else if (a.startsWith('--cwd=')) {
+      explicitCwd = a.slice('--cwd='.length);
+    } else {
+      positional.push(a);
+    }
+  }
+  const mergedPath = positional[0];
+  const gatePath = positional[1];
+  if (!mergedPath || !gatePath) {
+    console.error('usage: node scripts/deep-dive.mjs <merged.json> <gate.json> [--cwd <project-dir>]');
+    process.exit(1);
+  }
+
+  const [merged, gate] = await Promise.all([
+    readFile(mergedPath, 'utf-8').then(JSON.parse),
+    readFile(gatePath, 'utf-8').then(JSON.parse),
+  ]);
+
+  if (explicitCwd) {
+    process.chdir(explicitCwd);
+    log(`cwd: ${process.cwd()} (via --cwd)`);
+  }
+
+  const link = await readProjectJson(process.cwd());
+  if (!link) {
+    console.error(`[deep-dive] FATAL: cwd ${process.cwd()} has no .vercel/project.json or .vercel/repo.json.`);
+    console.error('         Re-run with --cwd <project-dir> pointing at the linked project, or cd into it first.');
+    console.error('         (The Vercel CLI resolves team/project from cwd; without a .vercel/ linkage every query returns empty rows for the wrong team.)');
+    process.exit(2);
+  }
+  if (merged.projectId && link.projectId !== merged.projectId) {
+    console.error('[deep-dive] FATAL: cwd .vercel/ links a different project than merged.json.');
+    console.error('         Re-run with --cwd <dir-linked-to-the-collected-project>.');
+    process.exit(2);
+  }
+  if (merged.orgId && link.orgId && link.orgId !== merged.orgId) {
+    console.error('[deep-dive] FATAL: cwd .vercel/ links the project to a different Vercel scope than signals.json.');
+    console.error('         Re-run with --cwd <dir-linked-to-the-collected-project>, or rerun collect-signals.mjs from the intended app directory.');
+    process.exit(2);
+  }
+  log(`cwd link OK (source ${link.source})`);
+
+  const commandScope = await resolveDeepDiveCommandScope(merged, link);
+  if (!commandScope.ok) {
+    console.error(`[deep-dive] FATAL: could not resolve a CLI-safe Vercel scope (${commandScope.detail ?? commandScope.error ?? 'unknown'}).`);
+    console.error('         Re-run collect-signals.mjs with the current skill, run `vercel switch <team>`, or re-link with `vercel link --yes --project <project> --team <team-slug>`.');
+    process.exit(2);
+  }
+  if (typeof commandScope.cliScope === 'string' && /^(team|usr)_/.test(commandScope.cliScope)) {
+    console.error('[deep-dive] FATAL: commandScope.cliScope is a raw account ID, not a CLI-safe scope.');
+    console.error('         Re-run collect-signals.mjs with the current skill so deep-dive queries use the same team as the broad pass.');
+    process.exit(2);
+  }
+  const commandAccountId = commandScope.teamId ?? commandScope.userId ?? null;
+  if (commandAccountId && link.orgId && link.orgId !== commandAccountId) {
+    console.error('[deep-dive] FATAL: cwd .vercel/ links the project to a different Vercel scope than commandScope.');
+    console.error('         Re-run with --cwd <dir-linked-to-the-collected-project>, or rerun collect-signals.mjs from the intended app directory.');
+    process.exit(2);
+  }
+  const scope = commandScope.cliScope || undefined;
+  log(`command scope resolved (source=${commandScope.source}; scoped=${scope ? 'yes' : 'no'})`);
+
+  const toLaunch = Array.isArray(gate.toLaunch) ? gate.toLaunch : [];
+  const platform = Array.isArray(gate.platform) ? gate.platform : [];
+
+  log(`enriching ${toLaunch.length} toLaunch + ${platform.length} platform candidate(s) (window=${TIME_WINDOW})`);
+
+  const t0 = Date.now();
+  const errors = [];
+
+  // Flatten {candidate, spec}, fire all CLI calls in one Promise.all, re-group.
+  // Avoids per-candidate sequentiality.
+  const allCandidates = [...toLaunch.map((c, i) => ({ c, group: 'toLaunch', i })),
+                        ...platform.map((c, i) => ({ c, group: 'platform', i }))];
+
+  const flatJobs = [];
+  const skipNotes = new Map();
+
+  for (const entry of allCandidates) {
+    const specs = specsForCandidate(entry.c);
+    if (specs.length === 0) {
+      if (SCANNER_KINDS.has(entry.c.kind)) {
+        skipNotes.set(`${entry.group}:${entry.i}`, 'scanner-driven (no deep-dive needed)');
+      } else if (entry.c.kind === 'platform_fluid_compute') {
+        skipNotes.set(`${entry.group}:${entry.i}`, 'reused from broad pass (fnStartTypeByRoute)');
+      } else {
+        skipNotes.set(`${entry.group}:${entry.i}`, `no deep-dive spec for kind=${entry.c.kind}`);
+      }
+      continue;
+    }
+    for (const spec of specs) {
+      flatJobs.push({ entry, spec });
+    }
+  }
+
+  // Cut CLI calls two ways: (1) extract per-route slices already collected in
+  // the broad pass; (2) dedupe identical queries across candidates (same route
+  // can fire multiple gates wanting the same metric).
+  let extractedFromBroadPass = 0;
+  let dedupedQueryHits = 0;
+  const broadPassResults = [];
+  const remainingJobs = [];
+  for (const job of flatJobs) {
+    const extracted = tryExtractFromBroadPass(job.spec, merged);
+    if (extracted) {
+      broadPassResults.push({ entry: job.entry, spec: job.spec, ok: true, ...extracted });
+      extractedFromBroadPass++;
+    } else {
+      remainingJobs.push(job);
+    }
+  }
+
+  // One CLI call per unique dedup key; jobs sharing a key share the result.
+  const queryGroups = new Map();
+  for (const job of remainingJobs) {
+    const key = queryKey(job.spec, scope);
+    if (!queryGroups.has(key)) {
+      queryGroups.set(key, { spec: job.spec, jobs: [] });
+    }
+    queryGroups.get(key).jobs.push(job);
+  }
+  dedupedQueryHits = remainingJobs.length - queryGroups.size;
+
+  const totalCliQueries = queryGroups.size;
+  log(`${flatJobs.length} specs total: ${extractedFromBroadPass} extracted from broad-pass, ${dedupedQueryHits} deduped, ${totalCliQueries} CLI queries to run`);
+
+  const groupResults = await Promise.all([...queryGroups.values()].map(async ({ spec, jobs }) => {
+    const r = await queryMetric(spec.metricId, {
+      aggregation: spec.aggregation,
+      groupBy: spec.groupBy,
+      filter: spec.filter,
+      since: spec.since,
+      limit: spec.limit,
+      scope,
+    });
+    return { spec, jobs, response: r };
+  }));
+
+  const cliResults = [];
+  for (const { spec, jobs, response: r } of groupResults) {
+    if (!r.ok) {
+      for (const job of jobs) {
+        errors.push({
+          candidateGroup: job.entry.group,
+          candidateIndex: job.entry.i,
+          kind: job.entry.c.kind,
+          route: job.entry.c.route ?? job.entry.c.hostname ?? null,
+          specId: spec.id,
+          code: r.code,
+        });
+        cliResults.push({ entry: job.entry, spec, ok: false, error: r.code });
+      }
+      continue;
+    }
+    const norm = normalizeResponse(r.data, spec);
+    for (const job of jobs) {
+      cliResults.push({ entry: job.entry, spec, ok: true, ...norm });
+    }
+  }
+  const results = [...broadPassResults, ...cliResults];
+
+  const wallMs = Date.now() - t0;
+  log(`done in ${wallMs}ms (${totalCliQueries} CLI queries, ${extractedFromBroadPass} extracted from broad-pass, ${dedupedQueryHits} deduped, ${errors.length} errors)`);
+
+  const byCandidate = new Map();
+  for (const res of results) {
+    const k = `${res.entry.group}:${res.entry.i}`;
+    if (!byCandidate.has(k)) byCandidate.set(k, []);
+    byCandidate.get(k).push(res);
+  }
+
+  function enrich(c, group, i) {
+    const k = `${group}:${i}`;
+    const note = skipNotes.get(k);
+    if (note) {
+      return {
+        ...c,
+        evidence: {
+          ...(c.evidence ?? {}),
+          deepDive: { note },
+        },
+      };
+    }
+    const list = byCandidate.get(k) ?? [];
+    const merged = mergeIntoEvidence(list);
+    return {
+      ...c,
+      evidence: {
+        ...(c.evidence ?? {}),
+        deepDive: merged,
+      },
+    };
+  }
+
+  const enrichedToLaunch = toLaunch.map((c, i) => enrich(c, 'toLaunch', i));
+  const enrichedPlatform = platform.map((c, i) => enrich(c, 'platform', i));
+
+  const out = {
+    schemaVersion: SCHEMA_VERSION,
+    appliedAt: new Date().toISOString(),
+    candidatesEnriched: toLaunch.length + platform.length,
+    specsTotal: flatJobs.length,
+    queriesRun: totalCliQueries,
+    extractedFromBroadPass,
+    dedupedQueryHits,
+    totalWallMs: wallMs,
+    errors,
+    toLaunch: enrichedToLaunch,
+    platform: enrichedPlatform,
+  };
+
+  process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+}
+
+async function resolveDeepDiveCommandScope(merged, link) {
+  const linkedOrgId = merged.orgId ?? link.orgId ?? null;
+  if (merged.commandScope?.ok && (merged.commandScope.cliScope || !linkedOrgId)) {
+    return merged.commandScope;
+  }
+  if (merged.commandScope && merged.commandScope.ok === false) return merged.commandScope;
+
+  return await resolveCommandScope({
+    projectId: merged.projectId ?? link.projectId ?? null,
+    orgId: merged.orgId ?? link.orgId ?? null,
+  });
+}
+
+// Reduce CLI response to {value} or {rows:[{value,...dims}]}. The per-metric
+// underscore field (e.g. vercel_function_invocation_count_sum) gets renamed
+// to `value` for compactness.
+function normalizeResponse(data, spec) {
+  if (!data || !Array.isArray(data.summary)) return { value: null };
+  const field = `${spec.metricId.replace(/\./g, '_')}_${spec.aggregation}`;
+  if (spec.groupBy.length === 0) {
+    const first = data.summary[0];
+    if (!first) return { value: null };
+    const v = first[field];
+    return { value: typeof v === 'number' ? round4(v) : null };
+  }
+  const rows = data.summary.map((row) => {
+    const out = { value: typeof row[field] === 'number' ? round4(row[field]) : null };
+    for (const dim of spec.groupBy) {
+      if (row[dim] !== undefined) out[dim] = row[dim];
+    }
+    return out;
+  });
+  return { rows };
+}
+
+function round4(n) {
+  if (!Number.isFinite(n)) return n;
+  return Math.round(n * 10000) / 10000;
+}
+
+// Skip the CLI call when broad-pass already collected the same metric grouped
+// by [route, dim]. Returns {rows} on hit, null on miss. Cuts rate-limit pressure
+// for per-route slice specs (startTypeSplit, cacheBreakdown, methodDistribution).
+function tryExtractFromBroadPass(spec, merged) {
+  const eq = spec.broadPassEquivalent;
+  if (!eq) return null;
+  const broadRows = merged?.metrics?.[eq.key]?.rows;
+  if (!Array.isArray(broadRows)) return null;
+  const rows = [];
+  for (const row of broadRows) {
+    if (row.route !== eq.routeFilter) continue;
+    const out = { value: typeof row.value === 'number' ? row.value : null };
+    for (const dim of (eq.projectDims ?? [])) {
+      if (row[dim] !== undefined) out[dim] = row[dim];
+    }
+    rows.push(out);
+  }
+  // Zero rows ≠ "no data" — broad-pass row limit may have truncated the route.
+  // Fall through to CLI so the caller gets a definitive answer.
+  if (rows.length === 0) return null;
+  return { rows };
+}
+
+// Two specs sharing this key answer the same question — one CLI call serves both.
+// Must include everything that affects the CLI's arg list.
+function queryKey(spec, scope) {
+  const groupBy = [...(spec.groupBy ?? [])].sort();
+  return JSON.stringify({
+    metricId: spec.metricId,
+    aggregation: spec.aggregation,
+    groupBy,
+    filter: spec.filter ?? null,
+    since: spec.since ?? null,
+    limit: spec.limit ?? null,
+    scope: scope ?? null,
+  });
+}
+
+main().catch((err) => {
+  console.error('[deep-dive] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/gate-investigations.mjs b/skills/vercel/vercel-optimize/scripts/gate-investigations.mjs
new file mode 100755
index 0000000..936060e
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/gate-investigations.mjs
@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Pure-JS deterministic gate. Reads merged signals.json, emits
+// {toLaunch, platform, gated}. Same input → byte-identical output (modulo
+// appliedAt). Sort keys are stable and explicit — never change without
+// a co-located golden-output test update.
+
+import { readFile } from 'node:fs/promises';
+import { gates, DEFAULT_MAX_CODE_CANDIDATES, GATE_VERSION } from '../lib/gates/index.mjs';
+import { applyAuthDisqualifier } from '../lib/auth-route.mjs';
+import { dedupeCandidates } from '../lib/route-normalize.mjs';
+import { validateCandidates } from '../lib/gates/contract.mjs';
+import { applyHardGates } from '../lib/gates/hard-gates.mjs';
+import { selectLaunchCandidates } from '../lib/gates/select-candidates.mjs';
+import { routePathMatchScore } from '../lib/investigation-brief.mjs';
+
+const SCHEMA_VERSION = '1.1';
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.signalsPath) {
+    console.error('usage: node scripts/gate-investigations.mjs <signals.json> [--max-candidates N|all]');
+    console.error('       VERCEL_OPTIMIZE_MAX_CANDIDATES env var supported (same values)');
+    process.exit(1);
+  }
+  const budget = resolveBudget(args);
+  const signals = JSON.parse(await readFile(args.signalsPath, 'utf-8'));
+
+  const allSeeds = gates.flatMap((g) => {
+    try {
+      return g.gate(signals) ?? [];
+    } catch (err) {
+      console.error(`[gate-investigations] gate ${g.metadata?.id} threw: ${err.message}`);
+      return [];
+    }
+  });
+
+  const validSeeds = validateCandidates(allSeeds, { source: 'gate-output' });
+  const annotated = validSeeds.map(applyAuthDisqualifier);
+  const sorted = annotated.slice().sort(stableCompare);
+
+  // Next.js 16 segment-tree metric paths surface the same source file under
+  // many encoded labels (city variants, _tree/_index siblings, base64 flag
+  // prefixes). Without dedup the budget gets shredded ~4-10x per page.
+  const { deduped, dropped } = dedupeCandidates(sorted);
+  const displayAnnotated = deduped.map((candidate) => attachDisplayRoute(candidate, signals));
+  const hardGateResult = applyHardGates(displayAnnotated, signals);
+  const gateable = hardGateResult.allowed;
+
+  // Account-scope candidates don't compete with code-scope for the budget.
+  const codeScoped = gateable.filter((c) => !c.disqualified && c.scope !== 'account');
+  const platformScoped = gateable.filter((c) => !c.disqualified && c.scope === 'account');
+
+  const selection = selectLaunchCandidates(codeScoped, budget, {
+    diversify: args.budgetSource === 'default',
+  });
+  const toLaunch = selection.selected;
+  const skippedByBudget = selection.skipped;
+  const budgetLabel = budget === Infinity ? 'unlimited (all)' : String(budget);
+  const gated = [
+    ...gateable
+      .filter((c) => c.disqualified)
+      .map((c) => ({ ...c, gatedReason: c.disqualifyReason ?? 'disqualified' })),
+    ...hardGateResult.gated,
+    ...skippedByBudget.map((c) => ({
+      ...c,
+      gatedReason: `skippedByBudget (max-candidates=${budgetLabel}; raise with --max-candidates N or =all)`,
+    })),
+    ...dropped.map((d) => ({
+      ...d.candidate,
+      gatedReason: `coveredBy (${d.mergedInto}) — ${d.reason}`,
+    })),
+  ];
+
+  process.stdout.write(JSON.stringify({
+    schemaVersion: SCHEMA_VERSION,
+    gateVersion: GATE_VERSION,
+    appliedAt: new Date().toISOString(),
+    budget: {
+      maxCandidates: budget === Infinity ? 'all' : budget,
+      source: args.budgetSource,
+      selection: selection.selectionMode,
+    },
+    toLaunch,
+    platform: platformScoped,
+    gated,
+    gateMetadata: gates.map((g) => ({
+      id: g.metadata?.id,
+      threshold: g.metadata?.threshold,
+      billingDimension: g.metadata?.billingDimension,
+      sourceCitation: g.metadata?.sourceCitation,
+    })),
+  }, null, 2) + '\n');
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--max-candidates') out.maxCandidatesArg = argv[++i];
+    else if (a.startsWith('--max-candidates=')) out.maxCandidatesArg = a.slice('--max-candidates='.length);
+    else out.positional.push(a);
+  }
+  out.signalsPath = out.positional[0];
+  return out;
+}
+
+function resolveBudget(args) {
+  const raw = args.maxCandidatesArg ?? process.env.VERCEL_OPTIMIZE_MAX_CANDIDATES;
+  if (raw == null || raw === '') {
+    args.budgetSource = 'default';
+    return DEFAULT_MAX_CODE_CANDIDATES;
+  }
+  const trimmed = String(raw).trim().toLowerCase();
+  if (trimmed === 'all' || trimmed === 'unlimited' || trimmed === '-1') {
+    args.budgetSource = args.maxCandidatesArg != null ? 'flag' : 'env';
+    return Infinity;
+  }
+  const n = Number(trimmed);
+  if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+    console.error(`[gate-investigations] bad budget value '${raw}'; expected positive integer or 'all'`);
+    process.exit(2);
+  }
+  args.budgetSource = args.maxCandidatesArg != null ? 'flag' : 'env';
+  return n;
+}
+
+// Total ordering: priority desc, kind asc, route asc. Underpins byte-identical output.
+function stableCompare(a, b) {
+  const pa = a.priority ?? 0;
+  const pb = b.priority ?? 0;
+  if (pa !== pb) return pb - pa;
+  const ka = String(a.kind ?? '');
+  const kb = String(b.kind ?? '');
+  if (ka !== kb) return ka.localeCompare(kb);
+  const ra = String(a.route ?? a.hostname ?? '');
+  const rb = String(b.route ?? b.hostname ?? '');
+  return ra.localeCompare(rb);
+}
+
+function attachDisplayRoute(candidate, signals) {
+  if (!candidate || candidate.scope !== 'route' || typeof candidate.route !== 'string') return candidate;
+  if (!candidate.route.includes('[*]')) return candidate;
+
+  const routes = (signals.codebase?.routes ?? [])
+    .map((route) => route?.routePath)
+    .filter((routePath) => typeof routePath === 'string' && routePath.length > 0);
+  if (routes.length === 0) return candidate;
+
+  let bestRoute = null;
+  let bestScore = 0;
+  for (const routePath of routes) {
+    const score = routePathMatchScore(routePath, candidate.route);
+    if (score > bestScore) {
+      bestRoute = routePath;
+      bestScore = score;
+    }
+  }
+
+  if (!bestRoute || bestScore <= 0 || bestRoute === candidate.route) return candidate;
+  return { ...candidate, displayRoute: bestRoute };
+}
+
+main().catch((err) => {
+  console.error('[gate-investigations] FAILED:', err.message);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/merge-signals.mjs b/skills/vercel/vercel-optimize/scripts/merge-signals.mjs
new file mode 100644
index 0000000..06e305c
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/merge-signals.mjs
@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// Deterministically combines Vercel metric collection with the local codebase
+// scan. Keeps the merged artifact shape stable: collect-signals output at the
+// top level, scan-codebase output under `codebase`.
+
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { routePathMatchScore } from '../lib/investigation-brief.mjs';
+import { canonicalizeRoute } from '../lib/route-normalize.mjs';
+
+const log = (...args) => console.error('[merge-signals]', ...args);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.signalsPath || !args.codebasePath) {
+    console.error('usage: node scripts/merge-signals.mjs <signals.json> <codebase.json> [--out merged.json] [--force]');
+    process.exit(1);
+  }
+
+  const [signals, codebase] = await Promise.all([
+    readJson(args.signalsPath, 'signals'),
+    readJson(args.codebasePath, 'codebase scan'),
+  ]);
+
+  const merged = mergeSignals(signals, codebase);
+  const body = JSON.stringify(merged, null, 2) + '\n';
+  if (args.outPath) {
+    await writeOutput(args.outPath, body, { force: args.force });
+    log(`wrote ${args.outPath}`);
+  } else {
+    process.stdout.write(body);
+  }
+}
+
+export function mergeSignals(signals, codebase) {
+  assertObject(signals, 'signals');
+  assertObject(codebase, 'codebase scan');
+
+  if (!signals.schemaVersion) {
+    throw new Error('signals.json is missing schemaVersion; pass collect-signals output as the first file.');
+  }
+  if (!Array.isArray(codebase.routes) || !Array.isArray(codebase.findings) || !codebase.stack) {
+    throw new Error('codebase.json must be scan-codebase output with stack, routes[], and findings[].');
+  }
+
+  return {
+    ...signals,
+    codebase: annotateCodebaseScan(signals, codebase),
+  };
+}
+
+export function annotateCodebaseScan(signals, codebase) {
+  const index = buildRouteMetricIndex(signals);
+  return {
+    ...codebase,
+    findings: (codebase.findings ?? []).map((finding) => annotateFinding(finding, index)),
+  };
+}
+
+function annotateFinding(finding, index) {
+  if (!finding || typeof finding !== 'object') return finding;
+  if (finding.trafficIndependent) return finding;
+  if (!finding.route) return { ...finding, o11ySignal: 'NO-ROUTE-MAPPING' };
+
+  const summary = bestRouteSummary(finding.route, index);
+  if (!summary || !hasTraffic(summary)) return { ...finding, o11ySignal: 'COLD-PATH' };
+  return { ...finding, o11ySignal: formatRouteSignal(summary) };
+}
+
+function buildRouteMetricIndex(signals) {
+  const out = new Map();
+  const ensure = (route) => {
+    const canonical = canonicalizeRoute(route);
+    const existing = out.get(canonical) ?? { route: canonical };
+    out.set(canonical, existing);
+    return existing;
+  };
+
+  for (const row of rows(signals, 'fnStatusByRoute')) {
+    if (!row.route) continue;
+    const summary = ensure(row.route);
+    summary.functionRuns = (summary.functionRuns ?? 0) + numeric(row.value);
+  }
+  for (const row of rows(signals, 'fnDurationP95ByRoute')) {
+    if (!row.route) continue;
+    ensure(row.route).p95Ms = numeric(row.value);
+  }
+  for (const row of rows(signals, 'requestsByRouteCache')) {
+    if (!row.route) continue;
+    const summary = ensure(row.route);
+    const count = numeric(row.value);
+    summary.requests = (summary.requests ?? 0) + count;
+    if (String(row.cache_result).toUpperCase() === 'HIT') {
+      summary.cacheHits = (summary.cacheHits ?? 0) + count;
+    }
+  }
+  return out;
+}
+
+function rows(signals, metricId) {
+  const rows = signals?.metrics?.[metricId]?.rows;
+  return Array.isArray(rows) ? rows : [];
+}
+
+function numeric(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function bestRouteSummary(route, index) {
+  const canonical = canonicalizeRoute(route);
+  const exact = index.get(canonical);
+  if (exact) return exact;
+
+  let best = null;
+  for (const summary of index.values()) {
+    const score = routePathMatchScore(canonical, summary.route);
+    if (score <= 0) continue;
+    if (!best || score > best.score) best = { score, summary };
+  }
+  return best?.summary ?? null;
+}
+
+function hasTraffic(summary) {
+  return (summary.functionRuns ?? 0) > 0 || (summary.requests ?? 0) > 0;
+}
+
+function formatRouteSignal(summary) {
+  const parts = [];
+  if ((summary.functionRuns ?? 0) > 0) parts.push(`inv=${Math.round(summary.functionRuns)}`);
+  else if ((summary.requests ?? 0) > 0) parts.push(`requests=${Math.round(summary.requests)}`);
+  if ((summary.p95Ms ?? 0) > 0) parts.push(`p95=${Math.round(summary.p95Ms)}ms`);
+  if ((summary.requests ?? 0) > 0 && summary.cacheHits != null) {
+    const hitRate = Math.round((summary.cacheHits / summary.requests) * 100);
+    parts.push(`cache=${hitRate}%`);
+  }
+  return parts.join(',') || 'COLD-PATH';
+}
+
+function parseArgs(argv) {
+  const out = { positional: [], force: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--out') out.outPath = argv[++i];
+    else if (a.startsWith('--out=')) out.outPath = a.slice('--out='.length);
+    else if (a === '--force') out.force = true;
+    else out.positional.push(a);
+  }
+  out.signalsPath = out.positional[0];
+  out.codebasePath = out.positional[1];
+  return out;
+}
+
+async function readJson(path, label) {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Could not read ${label} JSON at ${path}: ${err.message}`);
+  }
+}
+
+function assertObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+}
+
+async function writeOutput(path, body, { force }) {
+  if (!force && await exists(path)) {
+    throw new Error(`output file already exists: ${path}. Use a fresh run directory or pass --force to overwrite.`);
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, body);
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch((err) => {
+    console.error('[merge-signals] FAILED:', err.message);
+    process.exit(1);
+  });
+}
diff --git a/skills/vercel/vercel-optimize/scripts/prepare-investigation-brief.mjs b/skills/vercel/vercel-optimize/scripts/prepare-investigation-brief.mjs
new file mode 100644
index 0000000..3e49476
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/prepare-investigation-brief.mjs
@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// Emits the ENTIRE prompt a sub-agent sees for one candidate (candidate +
+// deep-dive evidence + filtered citations + playbook + protocol + output
+// schema). --list emits a manifest the orchestrator uses to decide fan-out
+// vs serial. Brief → stdout, status → stderr.
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import {
+  buildBrief,
+  inferPlaybook,
+  inferFrameworkPlaybook,
+  resolveFiles,
+  citationSubset,
+} from '../lib/investigation-brief.mjs';
+import { supportTopicSubset } from '../lib/support-topics.mjs';
+import { candidateRefFor } from '../lib/reconcile-candidates.mjs';
+import { formatCandidateLabel } from '../lib/display-labels.mjs';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PLAYBOOKS_DIR = join(HERE, '..', 'references', 'playbooks');
+
+const log = (...a) => console.error('[prepare-brief]', ...a);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.mergedPath || !args.investigationPath) {
+    console.error('usage: node scripts/prepare-investigation-brief.mjs <merged.json> <investigation.json> [--index N] [--group toLaunch|platform] [--out FILE]');
+    console.error('   or: node scripts/prepare-investigation-brief.mjs <merged.json> <investigation.json> --list');
+    process.exit(1);
+  }
+
+  const [merged, investigation] = await Promise.all([
+    readFile(args.mergedPath, 'utf-8').then(JSON.parse),
+    readFile(args.investigationPath, 'utf-8').then(JSON.parse),
+  ]);
+
+  if (args.list) {
+    const manifest = buildManifest(merged, investigation);
+    process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
+    return;
+  }
+
+  const group = args.group ?? 'toLaunch';
+  const index = args.index ?? 0;
+  const pool = Array.isArray(investigation[group]) ? investigation[group] : [];
+  if (index < 0 || index >= pool.length) {
+    console.error(`[prepare-brief] FATAL: ${group}[${index}] out of range (${group} has ${pool.length} entries)`);
+    process.exit(2);
+  }
+  let candidate = pool[index];
+
+  // Scan output may live at merged.codebase (older shape) or merged.signals.codebase
+  // (current shape, after the jq merge nests it under signals). Resolve either.
+  const codebase = pickCodebase(merged);
+  const signals = {
+    ...merged,
+    codebase,
+  };
+  const files = resolveFiles(candidate, signals);
+  candidate = {
+    ...candidate,
+    candidateRef: candidate.candidateRef ?? candidateRefFor(candidate, files),
+  };
+  const playbookId = inferPlaybook(signals);
+  const playbookBody = playbookId ? await tryReadPlaybook(playbookId) : null;
+  const frameworkPlaybookId = inferFrameworkPlaybook(signals);
+  const frameworkPlaybookBody = frameworkPlaybookId ? await tryReadPlaybook(frameworkPlaybookId) : null;
+
+  const stack = signals.stack ?? signals.codebase?.stack ?? {};
+  const framework = stack.framework ?? 'unknown';
+  const version = stack.frameworkVersion ?? 'unknown';
+  const citations = await citationSubset(candidate.kind, framework, version);
+  const supportTopics = await supportTopicSubset({
+    candidate,
+    signals,
+    framework,
+    version,
+    profile: playbookId,
+    frameworkPlaybookId,
+  });
+
+  const brief = buildBrief({
+    candidate,
+    candidateIndex: index,
+    candidateGroup: group,
+    files,
+    signals,
+    citations,
+    playbookId,
+    playbookBody,
+    frameworkPlaybookId,
+    frameworkPlaybookBody,
+    supportTopics,
+    generatedAt: args.deterministic ? null : new Date().toISOString(),
+  });
+
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeBriefFile(args.outPath, brief, { force: args.force });
+    log(`wrote ${brief.length}B → ${args.outPath}`);
+  } else {
+    process.stdout.write(brief + '\n');
+  }
+}
+
+function buildManifest(merged, investigation) {
+  const out = [];
+  const groups = ['toLaunch', 'platform'];
+  for (const group of groups) {
+    const pool = Array.isArray(investigation[group]) ? investigation[group] : [];
+    pool.forEach((c, i) => {
+      const files = resolveFiles(c, { ...merged, codebase: pickCodebase(merged) });
+      const candidateRef = c.candidateRef ?? candidateRefFor(c, files);
+      out.push({
+        group,
+        index: i,
+        kind: c.kind,
+        route: c.route ?? c.hostname ?? null,
+        scope: c.scope ?? null,
+        priority: c.priority ?? null,
+        confidence: c.confidence ?? null,
+        o11ySignal: c.o11ySignal ?? null,
+        files,
+        candidateRef,
+        label: formatCandidateLabel({ ...c, files }),
+      });
+    });
+  }
+  return {
+    schemaVersion: '1.0',
+    totalBriefs: out.length,
+    toLaunchCount: out.filter((b) => b.group === 'toLaunch').length,
+    platformCount: out.filter((b) => b.group === 'platform').length,
+    preResolvedRecords: Array.isArray(investigation.preResolvedRecords)
+      ? investigation.preResolvedRecords
+      : [],
+    fanoutPlan: buildFanoutPlan(out),
+    briefs: out,
+  };
+}
+
+function buildFanoutPlan(briefs) {
+  const groups = new Map();
+  for (const brief of briefs) {
+    const key = candidateFamilyKey(brief);
+    const existing = groups.get(key) ?? {
+      familyKey: key,
+      label: brief.label,
+      kind: brief.kind,
+      primaryBrief: { group: brief.group, index: brief.index, candidateRef: brief.candidateRef },
+      relatedBriefs: [],
+    };
+    if (existing.primaryBrief.candidateRef !== brief.candidateRef) {
+      existing.relatedBriefs.push({ group: brief.group, index: brief.index, candidateRef: brief.candidateRef });
+    }
+    groups.set(key, existing);
+  }
+  return {
+    totalFamilies: groups.size,
+    families: [...groups.values()].map((g) => ({
+      ...g,
+      totalBriefs: 1 + g.relatedBriefs.length,
+    })),
+  };
+}
+
+function candidateFamilyKey(brief) {
+  const file = Array.isArray(brief.files) && brief.files.length > 0 ? brief.files[0] : null;
+  const target = file ?? brief.route ?? brief.scope ?? '<account>';
+  return `${brief.kind ?? 'unknown'}:${target}`;
+}
+
+// Prefer merged.codebase, fall back to merged.signals.codebase, then empty.
+// Also accepts a fully-shaped scan doc directly (used in tests).
+function pickCodebase(merged) {
+  if (!merged || typeof merged !== 'object') return {};
+  if (merged.codebase && typeof merged.codebase === 'object' && (merged.codebase.routes || merged.codebase.findings)) {
+    return merged.codebase;
+  }
+  if (merged.signals?.codebase && typeof merged.signals.codebase === 'object') {
+    return merged.signals.codebase;
+  }
+  return {};
+}
+
+async function tryReadPlaybook(id) {
+  try {
+    return await readFile(join(PLAYBOOKS_DIR, `${id}.md`), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--index') out.index = Number(argv[++i]);
+    else if (a.startsWith('--index=')) out.index = Number(a.slice('--index='.length));
+    else if (a === '--group') out.group = argv[++i];
+    else if (a.startsWith('--group=')) out.group = a.slice('--group='.length);
+    else if (a === '--out') out.outPath = resolve(argv[++i]);
+    else if (a.startsWith('--out=')) out.outPath = resolve(a.slice('--out='.length));
+    else if (a === '--list') out.list = true;
+    else if (a === '--deterministic') out.deterministic = true;
+    else if (a === '--force') out.force = true;
+    else out.positional.push(a);
+  }
+  out.mergedPath = out.positional[0];
+  out.investigationPath = out.positional[1];
+  return out;
+}
+
+async function writeBriefFile(outPath, brief, { force = false } = {}) {
+  try {
+    await writeFile(outPath, brief + '\n', { encoding: 'utf-8', flag: force ? 'w' : 'wx' });
+  } catch (err) {
+    if (err?.code === 'EEXIST') {
+      throw new Error(`output file already exists: ${outPath}. Use a fresh run directory or pass --force to overwrite.`);
+    }
+    throw err;
+  }
+}
+
+main().catch((err) => {
+  console.error('[prepare-brief] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/reconcile-candidates.mjs b/skills/vercel/vercel-optimize/scripts/reconcile-candidates.mjs
new file mode 100644
index 0000000..1f80104
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/reconcile-candidates.mjs
@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Deterministic reconciliation between deep-dive and investigator fan-out.
+// Reads investigation-evidence.json, removes candidates whose follow-up metric
+// evidence already disproves/reframes the gate hypothesis, and emits the same
+// shape with preResolvedRecords for the final report.
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { reconcileInvestigation } from '../lib/reconcile-candidates.mjs';
+
+const log = (...a) => console.error('[reconcile-candidates]', ...a);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.investigationPath) {
+    console.error('usage: node scripts/reconcile-candidates.mjs <investigation-evidence.json> [--gate gate.json] [--out reconciled-investigation.json]');
+    process.exit(1);
+  }
+
+  const [investigation, gate] = await Promise.all([
+    readFile(args.investigationPath, 'utf-8').then(JSON.parse),
+    args.gatePath ? readFile(args.gatePath, 'utf-8').then(JSON.parse) : null,
+  ]);
+
+  const reconciled = reconcileInvestigation(investigation, { gate });
+  const serialized = JSON.stringify({
+    ...reconciled,
+    reconciledAt: args.noTimestamp ? null : new Date().toISOString(),
+  }, null, 2) + '\n';
+
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeFile(args.outPath, serialized, 'utf-8');
+    log(`wrote ${serialized.length}B -> ${args.outPath}`);
+  } else {
+    process.stdout.write(serialized);
+  }
+
+  const dropped = reconciled.reconciliation?.droppedBeforeInvestigation ?? 0;
+  if (dropped > 0) log(`dropped ${dropped} candidate(s) before investigation`);
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--gate') out.gatePath = resolve(argv[++i]);
+    else if (a.startsWith('--gate=')) out.gatePath = resolve(a.slice('--gate='.length));
+    else if (a === '--out') out.outPath = resolve(argv[++i]);
+    else if (a.startsWith('--out=')) out.outPath = resolve(a.slice('--out='.length));
+    else if (a === '--no-timestamp') out.noTimestamp = true;
+    else out.positional.push(a);
+  }
+  out.investigationPath = out.positional[0] ? resolve(out.positional[0]) : null;
+  return out;
+}
+
+main().catch((err) => {
+  console.error('[reconcile-candidates] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/render-report.mjs b/skills/vercel/vercel-optimize/scripts/render-report.mjs
new file mode 100644
index 0000000..542a992
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/render-report.mjs
@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+// Final pipeline step. Emits customer-facing markdown from
+// recommendations.json + gate.json + signals.json.
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { buildFinalReportMessage, renderReport } from '../lib/render-report.mjs';
+import { dedupeRecommendations } from '../lib/dedup-recs.mjs';
+import { canonicalizeRoute } from '../lib/route-normalize.mjs';
+import { hasUnsupportedCacheLifeCdnText, splitCustomerSafeObservations } from '../lib/observation-safety.mjs';
+
+const log = (...a) => console.error('[render-report]', ...a);
+const HARD_REGEN_TRIGGERS = new Set([
+  'project_config_contradiction',
+  'cache_vary_safety',
+  'semantic_safety',
+]);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.recsPath || !args.gatePath || !args.signalsPath) {
+    console.error('usage: node scripts/render-report.mjs <recommendations.json> <gate.json> <signals.json> [--project NAME] [--out FILE] [--message-out FILE] [--no-timestamp] [--debug-out FILE]');
+    process.exit(1);
+  }
+
+  const [recsRaw, gateRaw, signalsRaw] = await Promise.all([
+    readFile(args.recsPath, 'utf-8').then(JSON.parse),
+    readFile(args.gatePath, 'utf-8').then(JSON.parse),
+    readFile(args.signalsPath, 'utf-8').then(JSON.parse),
+  ]);
+
+  // Accept either a raw rec array OR the verify-and-regen wrapper
+  // {recsGraded, qualityDropped, ...}. Stale-rec defense: when verify-and-regen
+  // flagged a hard-safety issue but the orchestrator skipped re-spawn, the
+  // original rec is still in recsGraded. Filter it here so it can't ship; it
+  // surfaces in "Investigated, no change recommended" instead.
+  const hardRegenRefs = new Set(
+    Array.isArray(recsRaw.regenPlan)
+      ? recsRaw.regenPlan
+          .filter((p) => HARD_REGEN_TRIGGERS.has(p.regenTrigger))
+          .map((p) => p.candidateRef)
+          .filter(Boolean)
+      : []
+  );
+  const activeCandidates = [
+    ...(Array.isArray(gateRaw.toLaunch) ? gateRaw.toLaunch : []),
+    ...(Array.isArray(gateRaw.platform) ? gateRaw.platform : []),
+  ];
+  const enforceCurrentGate = !Array.isArray(recsRaw) && activeCandidates.length > 0;
+  const staleRecommendationDrops = [];
+  const wrapperRecommendations = Array.isArray(recsRaw.renderableRecommendations)
+    ? recsRaw.renderableRecommendations
+    : (recsRaw.recsGraded ?? []);
+  const needsReviewDrops = [];
+  const candidateRecommendations = Array.isArray(recsRaw)
+    ? recsRaw.filter((r) => r?.abstain !== true)
+    : wrapperRecommendations
+        .filter((r, i) => (r.quality?.overall ?? 0) >= 0.55)
+        .filter((r) => !hardRegenRefs.has(r.candidateRef));
+  const recommendationsRaw = candidateRecommendations
+        .filter((r) => {
+          if (r?.abstain === true || r?.needsReview !== true) return true;
+          needsReviewDrops.push({
+            candidateRef: r.candidateRef ?? null,
+            reason: 'This recommendation needs a manual safety review before it is ready to apply.',
+          });
+          return false;
+        })
+        .filter((r) => {
+          if (!enforceCurrentGate) return true;
+          if (recommendationMatchesActiveCandidate(r, activeCandidates)) return true;
+          staleRecommendationDrops.push({
+            candidateRef: r.candidateRef ?? null,
+            reason: 'This recommendation came from a candidate that is not in the current run output. Re-run from a clean run directory before applying it.',
+          });
+          return false;
+        });
+  const recommendations = dedupeRecommendations(recommendationsRaw);
+  const readyTargets = new Set(
+    recommendations
+      .map((r) => candidateTarget(r?.candidateRef))
+      .filter(Boolean)
+  );
+  const droppedContradictions = !Array.isArray(recsRaw)
+    ? (recsRaw.recsGraded ?? [])
+        .map((r, i) => ({ r, i }))
+        .filter(({ r }) => hardRegenRefs.has(r.candidateRef))
+        .map(({ r, i }) => ({
+          candidateRef: r.candidateRef ?? null,
+          reason: publicHardRegenReason(recsRaw.regenPlan?.find((p) => p.index === i || p.candidateRef === r.candidateRef)),
+        }))
+    : [];
+
+  const gated = Array.isArray(gateRaw.gated) ? gateRaw.gated : [];
+
+  // No-change findings are first-class investigation outputs ("the hypothesis didn't hold").
+  // Contradiction-dropped recs ride alongside them so customers see WHY a rec
+  // was held back instead of it silently disappearing.
+  const baseAbstentions = Array.isArray(recsRaw)
+    ? recsRaw.filter((r) => r?.abstain === true).map((r) => ({
+        candidateRef: r.candidateRef ?? null,
+        reason: publicNoChangeReason(r.reason ?? '(no reason recorded)'),
+      }))
+    : (recsRaw.abstentions ?? []).map((r) => ({
+        ...r,
+        reason: publicNoChangeReason(r.reason ?? '(no reason recorded)'),
+      }));
+  const publicBaseAbstentions = baseAbstentions.filter((r) => !readyTargets.has(candidateTarget(r?.candidateRef)));
+  // Observations: no-change findings carrying a structured non-perf finding
+  // (deployment regression, error storm, etc.).
+  const flattenedObservations = Array.isArray(recsRaw)
+    ? flattenObservations(recsRaw.filter((r) => r?.abstain === true))
+    : flattenObservations([
+        ...(Array.isArray(recsRaw.observations) ? recsRaw.observations : []),
+        ...(Array.isArray(recsRaw.abstentions) ? recsRaw.abstentions : []),
+      ]);
+  const { observations: safeObservations, heldBackObservations } = splitCustomerSafeObservations(flattenedObservations, baseAbstentions, signalsRaw);
+  const observations = suppressReadyCoveredObservations(safeObservations, recommendations);
+
+  const abstentions = [
+    ...publicBaseAbstentions,
+    ...droppedContradictions,
+    ...staleRecommendationDrops,
+    ...needsReviewDrops,
+    ...(Array.isArray(recsRaw.withheldRecommendations) ? recsRaw.withheldRecommendations.map((d) => ({
+      candidateRef: d.candidateRef ?? null,
+      reason: publicWithheldReason(d),
+      needsEvidence: true,
+    })) : []),
+    ...(Array.isArray(recsRaw.sanitizerDropped) ? recsRaw.sanitizerDropped.map((d) => ({
+      candidateRef: d.candidateRef ?? null,
+      reason: `This needs a closer review before it is safe to apply: ${d.reason ?? 'review required'}.`,
+      needsEvidence: true,
+    })) : []),
+    ...(Array.isArray(recsRaw.heldBackObservations) ? recsRaw.heldBackObservations.map((d) => ({
+      ...d,
+      needsEvidence: true,
+    })) : []),
+    ...heldBackObservations,
+  ];
+
+  // Full catalog lets the renderer recover o11ySignal + aliasRoutes that recs
+  // didn't propagate, and canonicalize segment-tree candidateRefs.
+  const allCandidates = [
+    ...activeCandidates,
+    ...gated,
+  ];
+
+  const md = renderReport({
+    recommendations,
+    gated,
+    abstentions,
+    observations,
+    signals: signalsRaw,
+    candidates: allCandidates,
+    opts: {
+      projectName: args.projectName,
+      generatedAt: args.noTimestamp ? null : new Date().toISOString(),
+      heldBackCount: (Number.isInteger(recsRaw.summary?.withheldRecommendations)
+          ? recsRaw.summary.withheldRecommendations
+          : (Array.isArray(recsRaw.regenPlan) ? recsRaw.regenPlan.length : 0) +
+            (Array.isArray(recsRaw.qualityDropped) ? recsRaw.qualityDropped.length : 0)) +
+        (Array.isArray(recsRaw.sanitizerDropped) ? recsRaw.sanitizerDropped.length : 0) +
+        (Array.isArray(recsRaw.heldBackObservations) ? recsRaw.heldBackObservations.length : 0) +
+        heldBackObservations.length,
+      noChangeCount: Number.isInteger(recsRaw.summary?.abstentions)
+        ? Math.min(recsRaw.summary.abstentions, publicBaseAbstentions.length)
+        : publicBaseAbstentions.length,
+    },
+  });
+
+  if (args.debugOutPath) {
+    const debugArtifact = buildDebugArtifact({
+      recsRaw,
+      recommendationsRaw,
+      recommendations,
+      gateRaw,
+      abstentions,
+      observations,
+      heldBackObservations,
+      staleRecommendationDrops,
+      droppedContradictions,
+    });
+    const serializedDebug = JSON.stringify(debugArtifact, null, 2) + '\n';
+    await mkdir(dirname(args.debugOutPath), { recursive: true });
+    await writeFile(args.debugOutPath, serializedDebug, 'utf-8');
+    log(`wrote debug ${serializedDebug.length}B → ${args.debugOutPath}`);
+  }
+
+  if (args.messageOutPath) {
+    const messageArtifact = buildFinalReportMessage({
+      reportPath: args.outPath ?? '(stdout)',
+      markdown: md,
+      recommendations,
+      signals: signalsRaw,
+    });
+    const serializedMessage = JSON.stringify(messageArtifact, null, 2) + '\n';
+    await mkdir(dirname(args.messageOutPath), { recursive: true });
+    await writeFile(args.messageOutPath, serializedMessage, 'utf-8');
+    log(`wrote final message ${serializedMessage.length}B → ${args.messageOutPath}`);
+  }
+
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeFile(args.outPath, md + '\n', 'utf-8');
+    log(`wrote ${md.length}B → ${args.outPath}`);
+  } else {
+    process.stdout.write(md + '\n');
+  }
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') out.projectName = argv[++i];
+    else if (a.startsWith('--project=')) out.projectName = a.slice('--project='.length);
+    else if (a === '--out') out.outPath = resolve(argv[++i]);
+    else if (a.startsWith('--out=')) out.outPath = resolve(a.slice('--out='.length));
+    else if (a === '--message-out') out.messageOutPath = resolve(argv[++i]);
+    else if (a.startsWith('--message-out=')) out.messageOutPath = resolve(a.slice('--message-out='.length));
+    else if (a === '--no-timestamp') out.noTimestamp = true;
+    else if (a === '--debug-out') out.debugOutPath = resolve(argv[++i]);
+    else if (a.startsWith('--debug-out=')) out.debugOutPath = resolve(a.slice('--debug-out='.length));
+    else if (a === '--debug') {
+      console.error('[render-report] --debug no longer writes internal details into customer markdown; use --debug-out FILE');
+    }
+    else out.positional.push(a);
+  }
+  out.recsPath = out.positional[0];
+  out.gatePath = out.positional[1];
+  out.signalsPath = out.positional[2];
+  return out;
+}
+
+function publicWithheldReason(record) {
+  switch (record?.reason) {
+    case 'needs_review':
+      return 'Automated checks added a safety caveat, so this run kept the recommendation out of the ready-to-apply list.';
+    case 'quality_floor':
+      return 'The recommendation did not meet the evidence bar for this report.';
+    case 'project_config_contradiction':
+    case 'cache_vary_safety':
+    case 'semantic_safety':
+      return publicHardRegenReason({ regenTrigger: record.reason });
+    default:
+      return 'This recommendation needs stronger evidence before it is safe to apply.';
+  }
+}
+
+function publicHardRegenReason(plan) {
+  switch (plan?.regenTrigger) {
+    case 'project_config_contradiction':
+      return 'The recommendation tried to turn on a project setting that is already enabled. Re-run the investigation with refreshed project-config evidence.';
+    case 'cache_vary_safety':
+      return 'The recommendation added shared CDN caching to output that varies by request geography without the required Vary header. Re-run the investigation with the cache-safety failure in scope.';
+    case 'semantic_safety':
+      return 'This recommendation needs stronger framework evidence before it is safe to apply. Re-run the investigation with that evidence in scope.';
+    default:
+      return 'This recommendation needs stronger evidence before it is safe to apply. Re-run the investigation with those checks in scope.';
+  }
+}
+
+function recommendationMatchesActiveCandidate(rec, candidates) {
+  const ref = parseCandidateRef(rec?.candidateRef);
+  if (!ref) return true;
+  return candidates.some((candidate) => candidateMatchesRef(candidate, ref));
+}
+
+function parseCandidateRef(ref) {
+  if (typeof ref !== 'string' || ref.length === 0) return null;
+  const [kind, ...targetParts] = ref.split(':');
+  if (!kind) return null;
+  return { kind, target: targetParts.join(':') };
+}
+
+function candidateMatchesRef(candidate, ref) {
+  if (!candidate || candidate.kind !== ref.kind) return false;
+  if (candidate.scope === 'account' || ref.target === '<account>') return true;
+
+  const candidateTarget = candidate.route ?? candidate.hostname ?? candidate.file ?? candidate.target ?? null;
+  if (!candidateTarget || !ref.target) return false;
+
+  const a = String(candidateTarget);
+  const b = String(ref.target);
+  return a === b || canonicalizeRoute(a) === canonicalizeRoute(b);
+}
+
+function suppressReadyCoveredObservations(observations, recommendations = []) {
+  if (!Array.isArray(observations) || observations.length === 0) return [];
+  const readyFamiliesByTarget = new Map();
+  for (const rec of recommendations) {
+    const parsed = parseCandidateRef(rec?.candidateRef);
+    const target = candidateTarget(rec?.candidateRef);
+    const family = candidateFamily(parsed?.kind);
+    if (!target || !family) continue;
+    const set = readyFamiliesByTarget.get(target) ?? new Set();
+    set.add(family);
+    readyFamiliesByTarget.set(target, set);
+  }
+
+  return observations.filter((observation) => {
+    const parsed = parseCandidateRef(observation?.candidateRef);
+    const target = candidateTarget(observation?.candidateRef);
+    const family = candidateFamily(parsed?.kind);
+    if (!target || !family) return true;
+    return !readyFamiliesByTarget.get(target)?.has(family);
+  });
+}
+
+function candidateFamily(kind) {
+  switch (kind) {
+    case 'uncached_route':
+    case 'cache_header_gap':
+    case 'missing_cache_headers':
+    case 'max_age_without_s_maxage':
+      return 'cache';
+    case 'slow_route':
+    case 'cold_start':
+    case 'external_api_slow':
+    case 'cwv_poor':
+      return 'performance';
+    case 'route_errors':
+      return 'reliability';
+    case 'isr_overrevalidation':
+      return 'isr';
+    case 'middleware_heavy':
+      return 'middleware';
+    case 'build_minutes_fanout':
+      return 'build';
+    default:
+      return kind || null;
+  }
+}
+
+function candidateTarget(ref) {
+  if (typeof ref !== 'string') return null;
+  const idx = ref.indexOf(':');
+  if (idx === -1) return null;
+  return ref.slice(idx + 1);
+}
+
+function publicNoChangeReason(reason) {
+  if (hasUnsupportedCacheLifeCdnText(reason)) {
+    return 'This candidate overlapped a cache-lifetime draft that did not meet the framework evidence bar. No supported change shipped from this run.';
+  }
+  return reason;
+}
+
+function buildDebugArtifact({
+  recsRaw,
+  recommendationsRaw,
+  recommendations,
+  gateRaw,
+  abstentions = [],
+  observations = [],
+  heldBackObservations = [],
+  staleRecommendationDrops = [],
+  droppedContradictions = [],
+}) {
+  const wrapper = Array.isArray(recsRaw) ? null : recsRaw;
+  const sourceRecords = Array.isArray(recsRaw)
+    ? recsRaw
+    : (recsRaw.recsGraded ?? []);
+  const summary = wrapper?.summary
+    ? {
+        ...wrapper.summary,
+        rawRecommendationCount: recommendationsRaw.length,
+        renderedRecommendationCount: recommendations.length,
+      }
+    : null;
+  return {
+    schemaVersion: '1.0',
+    summary,
+    regenPlan: wrapper?.regenPlan ?? [],
+    qualityDropped: wrapper?.qualityDropped ?? [],
+    withheldRecommendations: wrapper?.withheldRecommendations ?? [],
+    abstentions,
+    observations,
+    heldBackObservations,
+    staleRecommendationDrops,
+    droppedContradictions,
+    sanitizerDropped: wrapper?.sanitizerDropped ?? [],
+    renderedRecommendationCount: recommendations.length,
+    rawRecommendationCount: recommendationsRaw.length,
+    gateBudget: gateRaw?.budget ?? null,
+    recommendations: sourceRecords
+      .filter((record) => record && record.abstain !== true)
+      .map((record) => ({
+        candidateRef: record.candidateRef ?? null,
+        what: record.what ?? null,
+        verification: record.verification ?? null,
+        quality: record.quality ?? null,
+        passRate: record.passRate ?? record.verification?.passRate ?? null,
+        avgQuality: record.avgQuality ?? null,
+        needsReview: record.needsReview === true,
+        sanitizerTrail: Array.isArray(record.sanitizerTrail) ? record.sanitizerTrail : [],
+      })),
+  };
+}
+
+function flattenObservations(records) {
+  const out = [];
+  for (const record of records) {
+    if (!record || typeof record !== 'object') continue;
+    if (record.observation && typeof record.observation === 'object') {
+      out.push({
+        candidateRef: record.candidateRef ?? null,
+        summary: coerceOptionalString(record.observation.summary),
+        evidence: record.observation.evidence ?? null,
+        suggestedAction: record.observation.suggestedAction ?? null,
+        kind: record.observation.kind ?? 'other',
+      });
+      continue;
+    }
+    if ('summary' in record || 'evidence' in record || 'suggestedAction' in record || 'kind' in record) {
+      out.push({
+        candidateRef: record.candidateRef ?? null,
+        summary: coerceOptionalString(record.summary),
+        evidence: record.evidence ?? null,
+        suggestedAction: record.suggestedAction ?? null,
+        kind: record.kind ?? 'other',
+      });
+    }
+  }
+  return out;
+}
+
+function coerceOptionalString(value) {
+  return value == null ? value : String(value);
+}
+
+main().catch((err) => {
+  console.error('[render-report] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/scan-codebase.mjs b/skills/vercel/vercel-optimize/scripts/scan-codebase.mjs
new file mode 100755
index 0000000..9d416b5
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/scan-codebase.mjs
@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+// Walks the repo, runs every scanner in lib/scanners/, emits findings + routes
+// + stack as JSON. Output is merged into signals.codebase.*. New scanners drop
+// into lib/scanners/ + the barrel; this file is closed for modification.
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { scanners } from '../lib/scanners/index.mjs';
+import { detectStack } from '../lib/vercel.mjs';
+import {
+  detectMonorepoRoot,
+  listWorkspacePackages,
+  buildResolver,
+  resolveWorkspaceImports,
+} from '../lib/workspace-resolver.mjs';
+
+const SCHEMA_VERSION = '1.0';
+const SKIP_DIRS = new Set(['node_modules', '.next', '.vercel', 'dist', 'build', '.git', 'coverage', '.turbo', '__tests__', 'cypress']);
+const SKIP_FILE_PATTERNS = [/\.test\./, /\.spec\./, /\.d\.ts$/];
+
+async function main() {
+  const rootDir = process.argv[2] || process.cwd();
+  process.stderr.write(`[scan-codebase] scanning ${rootDir}\n`);
+
+  const [stack, files, routes] = await Promise.all([
+    detectStack(rootDir),
+    collectFiles(rootDir),
+    enumerateRoutes(rootDir),
+  ]);
+
+  // In a monorepo, route files often re-export from workspace packages. Without
+  // resolving those, sub-agents abstain because the workspace path is outside
+  // their read scope.
+  const monorepoRoot = await detectMonorepoRoot(rootDir);
+  let workspacePackages = [];
+  let resolver = () => null;
+  if (monorepoRoot) {
+    workspacePackages = await listWorkspacePackages(monorepoRoot);
+    resolver = buildResolver(workspacePackages);
+    process.stderr.write(`[scan-codebase] monorepo root: ${monorepoRoot} (${workspacePackages.length} workspace packages)\n`);
+  }
+  await enrichRoutesWithWorkspaceImports(routes, rootDir, resolver, monorepoRoot);
+
+  process.stderr.write(`[scan-codebase] ${files.length} files, ${routes.length} routes, ${scanners.length} scanners\n`);
+
+  const findings = [];
+  for (const scanner of scanners) {
+    try {
+      const applicable = filterApplicable(files, scanner.metadata);
+      // Scanners may be sync or async (large-static-asset does fs.stat walks).
+      const found = await scanner.scan({ files: applicable, rootDir, routes, stack });
+      for (const f of (found ?? [])) {
+        findings.push({
+          ...f,
+          route: mapFileToRoute(f.file, routes),
+        });
+      }
+    } catch (err) {
+      process.stderr.write(`[scan-codebase] scanner ${scanner.metadata?.id} threw: ${err.message}\n`);
+    }
+  }
+
+  findings.sort((a, b) =>
+    a.file.localeCompare(b.file)
+    || (a.line ?? 0) - (b.line ?? 0)
+    || a.pattern.localeCompare(b.pattern)
+  );
+
+  process.stdout.write(JSON.stringify({
+    schemaVersion: SCHEMA_VERSION,
+    scannedAt: new Date().toISOString(),
+    rootDir,
+    monorepoRoot: monorepoRoot ?? null,
+    workspacePackages: workspacePackages.map((p) => ({ name: p.name, dir: relative(monorepoRoot ?? rootDir, p.dir) })),
+    stack,
+    routes,
+    findings,
+    scannerMetadata: scanners.map((s) => ({
+      id: s.metadata.id,
+      title: s.metadata.title,
+      severity: s.metadata.severity,
+      billingDimension: s.metadata.billingDimension,
+      trafficIndependent: s.metadata.trafficIndependent,
+    })),
+  }, null, 2) + '\n');
+
+  process.stderr.write(`[scan-codebase] ${findings.length} finding(s)\n`);
+}
+
+// Record workspace-package imports per route so the brief allowlists them and
+// sub-agents can investigate the real source rather than abstaining on a thin
+// re-export shell. Capped to keep the brief focused (source order ≈ import order,
+// so the primary view component usually leads).
+const WORKSPACE_IMPORT_LIMIT_PER_ROUTE = 12;
+async function enrichRoutesWithWorkspaceImports(routes, scanRootDir, resolver, monorepoRoot) {
+  if (!monorepoRoot) return;
+  for (const r of routes) {
+    if (!r?.file) continue;
+    const abs = join(scanRootDir, r.file);
+    const resolved = await resolveWorkspaceImports(abs, resolver, {
+      pureBarrelDepth: 3,
+      suffixFanoutDepth: 2,
+      perSpecifierCap: 3,
+    });
+    if (resolved.length === 0) continue;
+    // Paths must be relative to the monorepo root so they align between signals + verifier.
+    r.workspaceImports = resolved
+      .slice(0, WORKSPACE_IMPORT_LIMIT_PER_ROUTE)
+      .map((abs) => relative(monorepoRoot, abs));
+  }
+}
+
+async function collectFiles(root) {
+  const entries = await readdir(root, { recursive: true, withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const segments = (e.parentPath ?? e.path ?? root).split('/');
+    if (segments.some((s) => SKIP_DIRS.has(s))) continue;
+    if (SKIP_FILE_PATTERNS.some((re) => re.test(e.name))) continue;
+    if (!/\.(tsx?|jsx?|mjs|cjs|html|svelte|astro|vue|json)$/.test(e.name)) continue;
+
+    const full = join(e.parentPath ?? e.path ?? root, e.name);
+    try {
+      const content = await readFile(full, 'utf-8');
+      if (content.length > 500_000) continue;
+      out.push({ path: relative(root, full), content });
+    } catch {}
+  }
+  return out;
+}
+
+function filterApplicable(files, meta) {
+  const incl = meta.includeGlobs ?? ['**/*'];
+  return files.filter((f) => incl.some((g) => globMatch(g, f.path)));
+}
+
+// Tiny glob → regex. Supports **, *, and {a,b} alternation.
+function globMatch(pattern, path) {
+  const re = new RegExp(
+    '^' +
+    pattern
+      .replace(/[.+^$()|[\]\\]/g, '\\$&')
+      .replace(/\{([^}]+)\}/g, (_, inner) => '(' + inner.split(',').join('|') + ')')
+      .replace(/\*\*/g, '__GLOBSTAR__')
+      .replace(/\*/g, '[^/]*')
+      .replace(/__GLOBSTAR__/g, '.*')
+    + '$'
+  );
+  return re.test(path);
+}
+
+async function enumerateRoutes(root) {
+  const entries = await readdir(root, { recursive: true, withFileTypes: true });
+  const routes = [];
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const segments = (e.parentPath ?? e.path ?? root).split('/');
+    if (segments.some((s) => SKIP_DIRS.has(s))) continue;
+
+    const full = join(e.parentPath ?? e.path ?? root, e.name);
+    const rel = relative(root, full);
+
+    // App Router: route groups ((name)), parallel routes (@slot), private folders
+    // (_name), and the top-level page.tsx (no path segment) all need explicit handling.
+    let m = rel.match(/^(?:src\/)?app\/(.*)\/(page|route|layout)\.(tsx?|jsx?)$/);
+    if (!m) {
+      const top = rel.match(/^(?:src\/)?app\/(page|route|layout)\.(tsx?|jsx?)$/);
+      if (top) {
+        routes.push({
+          routePath: '/',
+          file: rel,
+          type: routeEntryType(top[1]),
+        });
+        continue;
+      }
+    }
+    if (m) {
+      const stripped = m[1]
+        .split('/')
+        .filter((seg) => !/^\([^)]+\)$/.test(seg) && !/^@/.test(seg) && !/^_/.test(seg))
+        .join('/')
+        .replace(/^\/+|\/+$/g, '');
+      const routePath = stripped === '' ? '/' : `/${stripped}`;
+      routes.push({
+        routePath,
+        file: rel,
+        type: routeEntryType(m[2]),
+      });
+      continue;
+    }
+
+    // Astro endpoint filenames commonly include the response extension
+    // (`feed.xml.ts`, `robots.txt.ts`). Handle these before the generic
+    // `src/pages` rule, which otherwise treats them as page components.
+    m = rel.match(/^src\/pages\/(.*\.(?:xml|json|txt|rss|atom|svg|png|jpg|jpeg|webp))\.(tsx?|jsx?|mjs|cjs)$/);
+    if (m) {
+      const name = normalizeRouteFileStem(m[1]);
+      routes.push({
+        routePath: name === '' ? '/' : '/' + name,
+        file: rel,
+        type: 'route',
+      });
+      continue;
+    }
+
+    m = rel.match(/^(?:src\/)?pages\/(.*)\.(tsx?|jsx?)$/);
+    if (m) {
+      const name = m[1].replace(/\/index$/, '').replace(/^index$/, '');
+      const isApi = /^api\//.test(name);
+      routes.push({
+        routePath: name === '' ? '/' : '/' + name,
+        file: rel,
+        type: isApi ? 'route' : 'page',
+      });
+      continue;
+    }
+
+    // Nuxt 3/4 pages. Dynamic segments use the same bracket shape as metrics
+    // (`[id]`, `[...slug]`), so keep them intact for route matching.
+    m = rel.match(/^(?:app\/)?pages\/(.*)\.vue$/);
+    if (m) {
+      const name = normalizeRouteFileStem(m[1]);
+      routes.push({
+        routePath: name === '' ? '/' : '/' + name,
+        file: rel,
+        type: 'page',
+      });
+      continue;
+    }
+
+    // Nuxt server routes: server/api/foo.get.ts -> /api/foo,
+    // server/routes/rss.xml.ts -> /rss.xml.
+    m = rel.match(/^server\/(api|routes)\/(.*)\.(tsx?|jsx?|mjs|cjs)$/);
+    if (m) {
+      const base = m[1] === 'api' ? 'api/' : '';
+      const name = normalizeRouteFileStem(`${base}${m[2]}`);
+      routes.push({
+        routePath: name === '' ? '/' : '/' + name,
+        file: rel,
+        type: 'route',
+      });
+      continue;
+    }
+
+    // Astro pages and endpoints. This is limited framework support, but route
+    // mapping still improves reports when Vercel metrics use user-facing paths.
+    m = rel.match(/^src\/pages\/(.*)\.(astro|tsx?|jsx?|mjs|cjs)$/);
+    if (m) {
+      const name = normalizeRouteFileStem(m[1]);
+      routes.push({
+        routePath: name === '' ? '/' : '/' + name,
+        file: rel,
+        type: m[2] === 'astro' ? 'page' : 'route',
+      });
+      continue;
+    }
+
+    // SvelteKit: +page.svelte = page, +page.server.{ts,js} pairs with it (treat
+    // as page), +server.{ts,js} = API route, +layout.* = ancestor layout context.
+    // Route groups (auth) stripped like Next; dynamic segments [slug]/[...rest]/[[opt]] preserved.
+    m = rel.match(/^src\/routes\/(.*)\/\+(page\.svelte|page\.server\.(?:ts|js)|server\.(?:ts|js)|layout\.svelte|layout\.server\.(?:ts|js))$/);
+    if (m || /^src\/routes\/\+(page\.svelte|page\.server\.(?:ts|js)|server\.(?:ts|js)|layout\.svelte|layout\.server\.(?:ts|js))$/.test(rel)) {
+      const fileTypeMatch = rel.match(/\+(page\.svelte|page\.server\.(?:ts|js)|server\.(?:ts|js)|layout\.svelte|layout\.server\.(?:ts|js))$/);
+      const fileType = fileTypeMatch?.[1] ?? '';
+      const segs = (m?.[1] ?? '').split('/').filter(Boolean)
+        .filter((seg) => !/^\([^)]+\)$/.test(seg));
+      const routePath = segs.length === 0 ? '/' : '/' + segs.join('/');
+      const type = fileType.startsWith('server') ? 'route' : fileType.startsWith('layout') ? 'layout' : 'page';
+      // When +page.svelte AND +page.server.ts both exist, +page.svelte wins ownership.
+      const existing = type === 'layout' ? null : routes.find((r) => r.routePath === routePath && r.type !== 'layout');
+      if (existing) {
+        if (fileType === 'page.svelte' && existing.type === 'page') {
+          existing.file = rel;
+        }
+        continue;
+      }
+      routes.push({ routePath, file: rel, type });
+      continue;
+    }
+  }
+  return routes.sort((a, b) =>
+    a.routePath.localeCompare(b.routePath)
+    || routeTypeOrder(a.type) - routeTypeOrder(b.type)
+    || a.file.localeCompare(b.file)
+  );
+}
+
+function routeEntryType(name) {
+  return name === 'route' ? 'route' : name === 'layout' ? 'layout' : 'page';
+}
+
+function normalizeRouteFileStem(stem) {
+  return String(stem ?? '')
+    .replace(/\/index$/, '')
+    .replace(/^index$/, '')
+    .replace(/\.(?:get|post|put|patch|delete|options|head)$/, '')
+    .replace(/^\/+|\/+$/g, '');
+}
+
+function routeTypeOrder(type) {
+  return type === 'page' ? 0 : type === 'route' ? 1 : type === 'layout' ? 2 : 3;
+}
+
+function mapFileToRoute(filePath, routes) {
+  const r = routes.find((rt) => rt.file === filePath);
+  return r?.routePath ?? null;
+}
+
+main().catch((err) => {
+  process.stderr.write(`[scan-codebase] FAILED: ${err.message}\n`);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/verify-and-regen.mjs b/skills/vercel/vercel-optimize/scripts/verify-and-regen.mjs
new file mode 100644
index 0000000..45973c3
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/verify-and-regen.mjs
@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+// Verify → grade → emit regenPlan. Does NOT spawn sub-agents — the
+// orchestrator reads regenPlan, re-spawns one sub-agent per targeted candidate
+// with topFailures injected, then re-runs this script. Thresholds are tuned
+// below (REGEN_*, QUALITY_FLOOR) — read those constants for the live values.
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { verifyClaim } from '../lib/verify-claim.mjs';
+import { extractClaims, summarizeClaimResults } from '../lib/extract-claims.mjs';
+import { gradeRecommendation, applyQualityFloor } from '../lib/grade-recommendation.mjs';
+import { deriveProjectFacts } from '../lib/project-facts.mjs';
+import { resolveRepoRoot } from '../lib/repo-root.mjs';
+import { applySanitizers } from '../lib/sanitizers/index.mjs';
+
+const SCHEMA_VERSION = '1.0';
+const REGEN_PASS_RATE_THRESHOLD = 0.8;
+// 1/1 failed is as broken as 1/5; below 2 claims is below the noise floor.
+const REGEN_MIN_CLAIMS = 2;
+// The Poor/Fair grade boundary — Poor recs erode trust faster than recall helps.
+const QUALITY_FLOOR = 0.55;
+
+const log = (...a) => console.error('[verify-and-regen]', ...a);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.recsPath) {
+    console.error('usage: node scripts/verify-and-regen.mjs <recommendations.json> [--signals merged.json] [--repo-root DIR] [--out FILE]');
+    process.exit(1);
+  }
+
+  const recs = JSON.parse(await readFile(args.recsPath, 'utf-8'));
+  if (!Array.isArray(recs)) {
+    console.error('[verify-and-regen] FATAL: recommendations.json must be an array of rec objects');
+    process.exit(2);
+  }
+
+  let framework, version, cacheComponents, knownFindings = [], projectFacts = [], signals = null;
+  if (args.signalsPath) {
+    signals = JSON.parse(await readFile(args.signalsPath, 'utf-8'));
+    const stack = signals.stack ?? signals.codebase?.stack ?? {};
+    framework = stack.framework;
+    version = stack.frameworkVersion;
+    cacheComponents = stack.cacheComponents;
+    knownFindings = (signals.codebase?.findings ?? signals.findings ?? [])
+      .filter((f) => f.file && (f.line != null))
+      .map((f) => ({ file: f.file, line: f.line }));
+    projectFacts = deriveProjectFacts(signals);
+    if (projectFacts.length > 0) {
+      log(`project facts in play: ${projectFacts.map((f) => f.id).join(', ')}`);
+    }
+  }
+
+  // Repo-root priority: (1) signals.project.rootDirectory from Vercel API
+  // (authoritative — returns "apps/<name>" so cwd can be back-mapped without
+  // filesystem probing), (2) supplied --repo-root, (3) walk-up from cwd.
+  const rootResult = await resolveRepoRoot(recs, args.repoRoot, process.cwd(), signals);
+  const repoRoot = rootResult.root;
+  if (rootResult.source === 'api') {
+    log(`repo-root from Vercel API: '${repoRoot}' (rootDirectory='${rootResult.apiOffset}')`);
+  } else if (rootResult.source === 'auto-detected') {
+    log(`repo-root auto-detected: '${repoRoot}' (probe: ${rootResult.probe})`);
+  } else if (rootResult.source === 'corrected') {
+    log(`repo-root auto-corrected: '${args.repoRoot}' → '${repoRoot}' (sub-agent paths resolve there)`);
+  }
+  log(`verifying ${recs.length} rec(s) — framework=${framework ?? '?'}@${version ?? '?'} repoRoot=${repoRoot}`);
+
+  // knownFindings MUST combine scanner findings + sub-agent's verified
+  // findingRefs — scanner-only grounding would miss every metric-gate rec.
+  // Abstentions are first-class outputs ({abstain:true, candidateRef, reason})
+  // and MUST NOT be graded; the abstention IS the answer.
+  const recsGraded = [];
+  const abstentions = [];
+  const observations = [];
+  const sanitizerDropped = [];
+  for (let i = 0; i < recs.length; i++) {
+    const rec = recs[i];
+
+    if (rec?.abstain === true) {
+      abstentions.push({
+        index: i,
+        candidateRef: rec.candidateRef ?? null,
+        reason: rec.reason ?? '(no reason recorded)',
+      });
+      // Observation: real non-perf signal worth surfacing (regression, error storm).
+      if (rec.observation && typeof rec.observation === 'object' && rec.observation.summary) {
+        observations.push({
+          index: i,
+          candidateRef: rec.candidateRef ?? null,
+          summary: String(rec.observation.summary),
+          evidence: rec.observation.evidence ?? null,
+          suggestedAction: rec.observation.suggestedAction ?? null,
+          kind: rec.observation.kind ?? 'other',
+        });
+      }
+      continue;
+    }
+
+    const baseClaimCtx = {
+      framework,
+      version,
+      repoRoot,
+      projectFacts,
+      projectRootDirectory: signals?.project?.rootDirectory ?? null,
+      cacheComponents,
+      signals,
+    };
+    const initialClaims = extractClaims(rec, baseClaimCtx);
+    const initialVerifyResults = await Promise.all(initialClaims.map((c) => verifyClaim(c)));
+    const initialClaimsWithResults = initialVerifyResults.map((r, j) => ({
+      ...r,
+      type: initialClaims[j]?.type,
+      claimType: initialClaims[j]?.type,
+      claim: initialClaims[j],
+    }));
+    const sanitizerResult = await applySanitizers(rec, {
+      framework,
+      version,
+      signals,
+      verifyResults: initialClaimsWithResults,
+    });
+    if (!sanitizerResult.kept) {
+      sanitizerDropped.push({
+        index: i,
+        candidateRef: rec.candidateRef ?? null,
+        what: rec.what ?? null,
+        reason: sanitizerResult.dropReason ?? 'automated-check',
+      });
+      continue;
+    }
+
+    const sanitizedRec = sanitizerResult.rec;
+    const claims = extractClaims(sanitizedRec, baseClaimCtx);
+    const verifyResults = await Promise.all(claims.map((c) => verifyClaim(c)));
+    const verification = summarizeClaimResults(verifyResults);
+
+    // A findingRef whose file_exists claim verified counts as grounding evidence.
+    const verifiedRefs = [];
+    for (let j = 0; j < claims.length; j++) {
+      const c = claims[j];
+      const r = verifyResults[j];
+      if (r?.disposition !== 'verified') continue;
+      if (c.sourceField === 'findingRefs' && c.type === 'file_exists') {
+        const ref = (rec.findingRefs ?? []).find((x) => String(x).startsWith(c.file + ':'));
+        if (ref) {
+          const m = String(ref).match(/^(.+?):(\d+)$/);
+          if (m) verifiedRefs.push({ file: m[1], line: Number(m[2]) });
+        }
+      }
+    }
+    const recKnownFindings = [...knownFindings, ...verifiedRefs];
+    const quality = gradeRecommendation(sanitizedRec, { knownFindings: recKnownFindings });
+
+    recsGraded.push({
+      index: i,
+      rec: { ...sanitizedRec, verification, verifyResults, quality },
+      claims,
+      verifyResults,
+      verification,
+      quality,
+    });
+  }
+
+  // Project-config contradictions are a HARD trigger: a "turn on Fluid" rec on
+  // a project where Fluid is already on passes 8/9 claims but is the wrong rec.
+  // passRate alone won't catch this.
+  const regenPlan = [];
+  for (const g of recsGraded) {
+    const { passRate, verifiable } = g.verification;
+    const claimsWithResults = g.verifyResults.map((r, j) => ({ ...r, claim: g.claims[j] }));
+    const contradictions = claimsWithResults.filter(
+      (r) => r.disposition === 'failed' && r.claim?.type === 'does_not_contradict_project_config'
+    );
+    const triggeredByPassRate = verifiable >= REGEN_MIN_CLAIMS && passRate < REGEN_PASS_RATE_THRESHOLD;
+    const cacheSafetyFailures = claimsWithResults.filter(
+      (r) => r.disposition === 'failed' && (
+        r.claim?.type === 'cache_vary_matches_dynamic_inputs' ||
+        r.claim?.type === 'cache_vary_cardinality_safe'
+      )
+    );
+    const semanticSafetyFailures = claimsWithResults.filter(
+      (r) => r.disposition === 'failed' && (
+        r.claim?.type === 'next_cached_not_found_causal_support' ||
+        r.claim?.type === 'next_stable_cache_api_for_version' ||
+        r.claim?.type === 'next_runtime_cache_api_for_version' ||
+        r.claim?.type === 'next_cache_life_single_execution' ||
+        r.claim?.type === 'next_cache_lifetime_freshness_supported' ||
+        r.claim?.type === 'next_cache_components_route_chain_file' ||
+        r.claim?.type === 'next_cache_life_cdn_header_semantics' ||
+        r.claim?.type === 'image_response_headers_citation' ||
+        r.claim?.type === 'next_image_priority_api_for_version' ||
+        r.claim?.type === 'next_cache_components_route_segment_config' ||
+        r.claim?.type === 'next_route_revalidate_static_prereq' ||
+        r.claim?.type === 'next_cache_tag_invalidation_supported' ||
+        r.claim?.type === 'cache_rec_not_error_dominated_or_acknowledged' ||
+        r.claim?.type === 'cache_control_header_syntax' ||
+        r.claim?.type === 'cache_control_headers_citation' ||
+        r.claim?.type === 'cache_404_long_ttl_safety' ||
+        r.claim?.type === 'route_error_not_found_status_and_scope' ||
+        r.claim?.type === 'immutable_dynamic_route_safety' ||
+        r.claim?.type === 'auth_guard_parallelization_safety' ||
+        r.claim?.type === 'parallelization_impact_not_overclaimed' ||
+        r.claim?.type === 'parallelization_not_cpu_bound_work' ||
+        r.claim?.type === 'runtime_error_cause_supported' ||
+        r.claim?.type === 'vercel_ignore_command_project_state'
+      )
+    );
+    const triggeredByContradiction = contradictions.length > 0;
+    const triggeredByCacheSafety = cacheSafetyFailures.length > 0;
+    const triggeredBySemanticSafety = semanticSafetyFailures.length > 0;
+    if (!triggeredByPassRate && !triggeredByContradiction && !triggeredByCacheSafety && !triggeredBySemanticSafety) continue;
+
+    const failures = claimsWithResults
+      .filter((r) => r.disposition === 'failed')
+      .slice(0, 5);
+    regenPlan.push({
+      index: g.index,
+      candidateRef: g.rec.candidateRef ?? null,
+      what: g.rec.what ?? null,
+      verifiableClaimCount: verifiable,
+      passRate,
+      regenTrigger: triggeredByContradiction
+        ? 'project_config_contradiction'
+        : triggeredByCacheSafety
+          ? 'cache_vary_safety'
+          : triggeredBySemanticSafety
+            ? 'semantic_safety'
+        : 'pass_rate_below_threshold',
+      topFailures: failures.map((f) => ({
+        claimType: f.claim?.type,
+        field: f.claim?.sourceField,
+        url: f.claim?.url,
+        file: f.claim?.file,
+        pattern: f.claim?.pattern,
+        reason: f.reason,
+      })),
+      regenBriefHint: triggeredByContradiction
+        ? 'Sub-agent recommended toggling on a project setting that is already enabled. Re-spawn with the project-config Strengths block highlighted; the rec must drop the contradictory step and keep only the actionable parts.'
+        : triggeredByCacheSafety
+          ? 'Sub-agent recommended CDN caching with unsafe or missing Vary behavior. Re-spawn with the cache safety failure highlighted; the rec must use a low-cardinality Vary header that matches the dynamic inputs, or abstain.'
+          : triggeredBySemanticSafety
+            ? 'Sub-agent made a framework-semantic claim that failed deterministic checks. Re-spawn with the failure highlighted; the rec must either add version-correct code/citations/runtime evidence or abstain.'
+        : 'Re-spawn the sub-agent with this rec\'s topFailures injected as feedback. Re-emit the rec only if regenPassRate >= originalPassRate AND citation count not gutted.',
+    });
+  }
+
+  const qualityCheck = applyQualityFloor(recsGraded.map((g) => g.rec), QUALITY_FLOOR);
+  const hardRegenIndexes = new Set(regenPlan.map((p) => p.index));
+  const qualityDroppedIndexes = new Set(
+    qualityCheck.dropped
+      .map((d) => recsGraded.findIndex((g) => g.rec === d.rec))
+      .filter((i) => i >= 0)
+  );
+  const needsReviewIndexes = new Set(
+    recsGraded
+      .filter((g) => g.rec.needsReview === true)
+      .map((g) => g.index)
+  );
+  const verifiedRecommendations = recsGraded
+    .filter((g) => !hardRegenIndexes.has(g.index) && !qualityDroppedIndexes.has(g.index) && !needsReviewIndexes.has(g.index))
+    .map((g) => g.rec);
+  const withheldRecommendations = recsGraded
+    .filter((g) => hardRegenIndexes.has(g.index) || qualityDroppedIndexes.has(g.index) || needsReviewIndexes.has(g.index))
+    .map((g) => ({
+      index: g.index,
+      candidateRef: g.rec.candidateRef ?? null,
+      what: g.rec.what ?? null,
+      reason: hardRegenIndexes.has(g.index)
+        ? (regenPlan.find((p) => p.index === g.index)?.regenTrigger ?? 'verification')
+        : qualityDroppedIndexes.has(g.index)
+          ? 'quality_floor'
+          : 'needs_review',
+    }));
+
+  const summary = {
+    totalRecs: recs.length,
+    abstentions: abstentions.length,
+    observations: observations.length,
+    sanitizerDropped: sanitizerDropped.length,
+    needsRegen: regenPlan.length,
+    qualityDropped: qualityCheck.dropped.length,
+    needsReview: needsReviewIndexes.size,
+    verifiedRecommendations: verifiedRecommendations.length,
+    withheldRecommendations: withheldRecommendations.length,
+    averagePassRate: recsGraded.length > 0
+      ? round4(recsGraded.reduce((s, g) => s + g.verification.passRate, 0) / recsGraded.length)
+      : null,
+    averageQuality: recsGraded.length > 0
+      ? round4(recsGraded.reduce((s, g) => s + g.quality.overall, 0) / recsGraded.length)
+      : null,
+  };
+
+  const output = {
+    schemaVersion: SCHEMA_VERSION,
+    summary,
+    recsGraded: recsGraded.map((g) => g.rec),
+    verifiedRecommendations,
+    renderableRecommendations: verifiedRecommendations,
+    withheldRecommendations,
+    abstentions,
+    observations,
+    sanitizerDropped,
+    regenPlan,
+    qualityDropped: qualityCheck.dropped.map((d) => ({
+      index: recsGraded.findIndex((g) => g.rec === d.rec),
+      candidateRef: d.rec.candidateRef ?? null,
+      quality: d.rec.quality,
+      reason: d.reason,
+    })),
+  };
+
+  const serialized = JSON.stringify(output, null, 2) + '\n';
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeFile(args.outPath, serialized, 'utf-8');
+    log(`wrote ${serialized.length}B → ${args.outPath}`);
+  } else {
+    process.stdout.write(serialized);
+  }
+  log(`done: ${summary.totalRecs} records checked; ${summary.verifiedRecommendations} ready, ${summary.withheldRecommendations} held back, ${summary.abstentions} found no supported change, ${summary.sanitizerDropped} dropped by safety checks`);
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--signals') out.signalsPath = argv[++i];
+    else if (a.startsWith('--signals=')) out.signalsPath = a.slice('--signals='.length);
+    else if (a === '--repo-root') out.repoRoot = argv[++i];
+    else if (a.startsWith('--repo-root=')) out.repoRoot = a.slice('--repo-root='.length);
+    else if (a === '--out') out.outPath = resolve(argv[++i]);
+    else if (a.startsWith('--out=')) out.outPath = resolve(a.slice('--out='.length));
+    else out.positional.push(a);
+  }
+  out.recsPath = out.positional[0];
+  return out;
+}
+
+function round4(n) { return Math.round(n * 10000) / 10000; }
+
+main().catch((err) => {
+  console.error('[verify-and-regen] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});
diff --git a/skills/vercel/vercel-optimize/scripts/verify-finding.mjs b/skills/vercel/vercel-optimize/scripts/verify-finding.mjs
new file mode 100755
index 0000000..4e7fedc
--- /dev/null
+++ b/skills/vercel/vercel-optimize/scripts/verify-finding.mjs
@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// CLI shell around lib/verify-claim.mjs. argv[2] = JSON claim, stdout = result.
+// Claim `type` enum: pattern_count | pattern_exists | pattern_absent | file_exists |
+// code_snippet | repo_count | citation_in_library | citation_applies_to_version.
+
+import { verifyClaim } from '../lib/verify-claim.mjs';
+
+const SCHEMA_VERSION = '1.0';
+
+async function main() {
+  const claim = JSON.parse(process.argv[2] || '{}');
+  const result = await verifyClaim(claim);
+  process.stdout.write(JSON.stringify({ schemaVersion: SCHEMA_VERSION, ...result }, null, 2) + '\n');
+}
+
+main().catch((err) => {
+  process.stderr.write(`[verify-finding] FAILED: ${err.message}\n`);
+  process.exit(1);
+});
diff --git a/skills/vercel/web-design-guidelines/SKILL.md b/skills/vercel/web-design-guidelines/SKILL.md
new file mode 100644
index 0000000..ceae92a
--- /dev/null
+++ b/skills/vercel/web-design-guidelines/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
diff --git a/skills/vercel/writing-guidelines/SKILL.md b/skills/vercel/writing-guidelines/SKILL.md
new file mode 100644
index 0000000..63facf3
--- /dev/null
+++ b/skills/vercel/writing-guidelines/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: writing-guidelines
+description: Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Writing Guidelines
+
+Review files for compliance with Writing Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.