feat: add Agent Skill for S1 to S2 migration

packages/dev/codemods/src/s1-to-s2/README.md

@@ -9,6 +9,9 @@ Run `npx @react-spectrum/codemods s1-to-s2` from the directory you want to upgra
 ### Options
 
 - `-c, --components <components>`: Comma separated list of components to upgrade (ex: `Button,TableView`). If not specified, all available components will be upgraded.
+- `--path <path>`: The path to the directory to run the codemod in. Defaults to the current directory (`.`).
+- `-d, --dry`: Run the codemod without writing any changes to disk. Use this to preview migrations before applying.
+- `--agent`: Run in non-interactive mode. Skips interactive prompts, package installation, and macro setup. Required when running in CI or from an agent tool. Note: `@react-spectrum/s2` must still be installed and resolvable.
 
 ## How it works
 

packages/dev/codemods/src/s1-to-s2/UPGRADE.md

@@ -265,7 +265,7 @@ Example:
 
 ### Border width
 
-Affected style props: `borderWidth`, `borderStartWidth`, `borderEndWidth`, `borderTopWidth`, `orderBottomWidth`, `borderXWidth`, `borderYWidth`.
+Affected style props: `borderWidth`, `borderStartWidth`, `borderEndWidth`, `borderTopWidth`, `borderBottomWidth`, `borderXWidth`, `borderYWidth`.
 
 Example:
 

packages/dev/s2-docs/migration-references/focused-app-setup.md

@@ -0,0 +1,25 @@
+# App setup and style macro
+
+## Full-page apps
+
+- Import `@react-spectrum/s2/page.css` in the app entrypoint so the page background and color scheme are applied before JavaScript runs.
+- Do not carry over a v3 root `Provider theme={defaultTheme}` wrapper just to make the app render. S2 does not require that pattern.
+- Do not assume there is only one app root. Standalone pages, alternate entrypoints, utility apps, embedded sub-apps, and test-only render targets may each need their own `page.css` or Provider cleanup.
+
+## Embedded sections
+
+- If S2 renders as part of a larger page instead of owning the whole document, keep the S2 subtree inside `<Provider background="...">` rather than importing `page.css` globally.
+
+## Provider decisions
+
+- Use S2 `Provider` when you need locale overrides, router integration, explicit color-scheme/background control, or SSR with `elementType="html"`.
+- Remove `theme={defaultTheme}` and other v3 theme props. They do not carry forward to S2.
+- Preserve surrounding app-shell providers such as routing, Redux/store, analytics, i18n/intl, and product-framework host providers. Replace only the React Spectrum-specific wrapper instead of flattening the whole provider stack.
+- For tests, wrap only the cases that actually need S2 context such as locale or background. Do not recreate a full v3 theme wrapper by default.
+
+## Bundlers
+
+- Detect the bundler at the migration target level, especially in monorepos. The workspace root may include Storybook, Vite, or other tooling that does not represent the runtime bundler for the package being migrated.
+- Parcel v2.12.0+ already supports S2 macros. Most Parcel repos only need the package install and the right entrypoint CSS import.
+- Non-Parcel bundlers need `unplugin-parcel-macros` and the appropriate framework setup. Keep plugin ordering correct so macros run before the rest of the toolchain.
+- If the repo already has a framework-specific S2 setup, preserve it instead of layering a second macro configuration on top.

packages/dev/s2-docs/migration-references/focused-manual-fixes.md

@@ -0,0 +1,37 @@
+# Manual fixes after the codemod
+
+## Known gaps to handle explicitly
+
+- `@react-spectrum/toast` imports are not automatically migrated. Move them to S2, then re-check `ToastContainer` mounts and `ToastQueue` usages.
+- v3 `Provider` and `defaultTheme` wrappers in apps and tests need human review. S2 does not use the v3 theme object model.
+
+## Imports and packages
+
+- Collapse v3 component imports onto `@react-spectrum/s2`.
+- Keep using `@spectrum-icons/*` only when there is no S2 icon or illustration equivalent. Prefer `@react-spectrum/s2/icons/*` and `@react-spectrum/s2/illustrations` when possible.
+- If the codemod leaves `TODO(S2-upgrade)` next to an icon or illustration import, pick the nearest S2 replacement manually.
+
+## App and Provider setup
+
+- Full-page apps usually add `import '@react-spectrum/s2/page.css';` at the entrypoint and no longer need a mandatory root Provider just to supply `theme={defaultTheme}`.
+- Embedded sections still use S2 `Provider` with an explicit `background`.
+- Keep or add S2 `Provider` only when locale, router integration, color-scheme/background overrides, or SSR `elementType="html"` behavior are needed.
+- Preserve unrelated wrappers such as routing, store, analytics, i18n, and host-framework providers. Replace or remove only the React Spectrum-specific layer.
+
+## Style and layout follow-ups
+
+- Convert v3 style props and `UNSAFE_style` cases to the S2 style macro when possible.
+- `Flex` and `Grid` often become `div` elements styled with the macro.
+- Review `ClearSlots` and other direct `@react-spectrum/utils` imports manually. These are not part of the common S2 app surface.
+
+## Dialogs and collections
+
+- `DialogContainer` and `useDialogContainer` still exist in S2, but the import path changes and dismiss logic may need to move between `Dialog`, `DialogTrigger`, and `DialogContainer`.
+- When `Item` survives the codemod, rename it based on its parent: `MenuItem`, `PickerItem`, `ComboBoxItem`, `ListBoxItem`, `Tab`, `TabPanel`, `Tag`, `Breadcrumb`, and similar.
+- Preserve React `key` when mapping arrays, but ensure collection data items expose `id` when S2 expects it.
+- Table and ListView migrations often need manual review for row headers, nested columns, and explicit item ids.
+
+## Tests
+
+- Replace v3 Provider/defaultTheme test wrappers with the minimal S2 `Provider` props the test actually needs, or remove the wrapper entirely if no S2 context is required.
+- Update toast mocks and assertions that still reference `@react-spectrum/toast` or old dialog markup.

packages/dev/s2-docs/migration-references/focused-toast.md

@@ -0,0 +1,22 @@
+# Toast migration
+
+## Import changes
+
+- Move `ToastContainer` and `ToastQueue` imports from `@react-spectrum/toast` to `@react-spectrum/s2`.
+- Keep a shared `ToastContainer` mounted near the app root or test harness, then update all queue calls to use the S2 import path.
+
+## Queue methods
+
+- S2 supports `ToastQueue.neutral`, `positive`, `negative`, and `info`.
+- Re-check options such as `timeout`, `actionLabel`, `onAction`, `shouldCloseOnAction`, and `onClose` after the import move.
+- The queue methods still return a close function. Keep programmatic dismissal logic when the existing UX depends on it.
+
+## Common post-codemod blind spots
+
+- Search for every `ToastContainer` mount and every `ToastQueue` usage after moving imports. Shared app roots, secondary entrypoints, and test harnesses are easy to miss.
+
+## Tests and mocks
+
+- Update every toast mock to point at `@react-spectrum/s2`.
+- If a test mounted `ToastContainer` from the old package, swap it to the S2 import as part of the same change.
+- Re-run the affected tests after the import move. Toast helpers are often mocked in many files and are easy to miss.

packages/dev/s2-docs/migration-references/focused-workflow.md

@@ -0,0 +1,45 @@
+# Codemod-first workflow
+
+## Inspect before editing
+
+- Search package manifests and source for `@adobe/react-spectrum`, `@react-spectrum/*`, and `@spectrum-icons/*`.
+- In monorepos or mixed-tooling repos, inspect the target package or app first instead of assuming the root manifest, Storybook config, or workspace tooling represents the runtime target being migrated.
+- Determine the package manager from the relevant lockfile or workspace setup, then choose the codemod runner that matches that repo or package.
+- Detect the bundler at the migration target level before touching setup files. Parcel v2.12.0+ already supports S2 style macros. Vite, webpack, Next.js, Rollup, ESBuild, and similar toolchains need explicit macro-plugin setup.
+- Find app entrypoints, standalone pages, alternate entrypoints, embedded sub-apps, utility apps, test-only render targets, root providers, shared test wrappers, toast setup, and any direct `defaultTheme` usage before the codemod changes imports.
+- Search for `ToastContainer`, `ToastQueue`, `DialogContainer`, `useDialogContainer`, `ClearSlots`, style props, and `UNSAFE_style`. These are common follow-up areas after the codemod.
+
+## Run the codemod first
+
+Prefer the repo-native non-interactive command so the upgrade stays deterministic:
+
+```bash
+npx @react-spectrum/codemods s1-to-s2 --agent
+yarn dlx @react-spectrum/codemods s1-to-s2 --agent
+pnpm dlx @react-spectrum/codemods s1-to-s2 --agent
+```
+
+Use `npx` for npm and Yarn 1 repos, `yarn dlx` for Yarn Berry or Yarn PnP repos, and `pnpm dlx` for pnpm repos. Use the equivalent workspace-native runner if the repo uses another package manager.
+Use `--path <dir>` for monorepos or when only one package should migrate first. In a monorepo, run the codemod against the target subtree first instead of the whole workspace.
+Use `--components A,B` when the user explicitly wants an incremental rollout by component family.
+Use `--dry` when you need to preview scope before editing.
+
+## Resolve follow-up work in order
+
+1. Install or verify `@react-spectrum/s2` and clean up imports.
+2. Add S2 app setup such as `@react-spectrum/s2/page.css` or `Provider` changes.
+3. Search for `TODO(S2-upgrade)` and fix every remaining comment.
+4. Resolve style prop, layout, and dialog/collection follow-ups.
+5. Migrate icons, illustrations, and toast imports.
+6. Update tests, mocks, and validation commands.
+
+## Validate with repo-native commands
+
+Prefer the narrowest existing scripts from `package.json`:
+
+- dependency install if manifests changed
+- typecheck or compile
+- focused tests for touched areas
+- build
+
+For monorepos, validate the affected package or subtree first with its own scripts before escalating to workspace-wide checks.

packages/dev/s2-docs/package.json

@@ -49,6 +49,8 @@
     "json5": "^2.2.3",
     "lz-string": "^1.5.0",
     "markdown-to-jsx": "^6.11.0",
+    "mdast-util-mdx": "^1.0.0",
+    "mdast-util-to-markdown": "^1.0.0",
     "react": "^19.2.0",
     "react-aria": "^3.40.0",
     "react-aria-components": "^1.7.1",