docs(tailwindcss-patch): clarify v9 upgrade flow

Author: sonofmagic

packages/tailwindcss-patch/MIGRATION.md

@@ -79,6 +79,41 @@ Migration mapping:
 
 If you still have legacy fields, run `tw-patch migrate --dry-run` first, then apply the rewritten config before upgrading.
 
+### Quick config diff
+
+```ts
+// before
+export default defineConfig({
+  registry: {
+    output: {
+      file: '.tw-patch/tw-class-list.json',
+    },
+    tailwind: {
+      package: 'tailwindcss',
+      classic: {
+        cwd: 'apps/web',
+      },
+    },
+  },
+})
+
+// after
+export default defineConfig({
+  registry: {
+    extract: {
+      file: '.tw-patch/tw-class-list.json',
+    },
+    tailwindcss: {
+      version: 4,
+      packageName: 'tailwindcss',
+      v3: {
+        cwd: 'apps/web',
+      },
+    },
+  },
+})
+```
+
 ## 3. CLI changes
 
 - `tw-patch install` still applies the runtime patch, but logging and error handling were refreshed.
@@ -104,7 +139,7 @@ If you still have legacy fields, run `tw-patch migrate --dry-run` first, then ap
 - The affected-shards template supports repo-level shard config via `.tw-patch/ci-shards.json` (example: `packages/tailwindcss-patch/examples/github-actions/ci-shards.example.json`).
 - README/README-cn now include a CI copy checklist and troubleshooting notes for local action wiring and common failure modes.
 - Migration report tooling now has public exports from package entry (`migrateConfigFiles`, `restoreConfigFiles`, report constants/types) and published JSON schema subpaths: `tailwindcss-patch/migration-report.schema.json`, `tailwindcss-patch/restore-result.schema.json`, `tailwindcss-patch/validate-result.schema.json`.
-- Commands resolve configuration from `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Existing configuration files continue to work without changes.
+- Commands resolve configuration from `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Upgrade configs to the modern `registry` shape before moving to v9.
 
 ## 4. Cache handling
 
@@ -125,7 +160,7 @@ Starting from the cache governance update, the on-disk cache also moved to **sch
 - Legacy array files are still readable, but treated as cache-miss and lazily rebuilt.
 - `TailwindcssPatcher#clearCache()` can clear current-context (default) or all contexts.
 
-This keeps public APIs backward compatible while preventing cross-project cache pollution in monorepos.
+This preserves cache-file compatibility while preventing cross-project cache pollution in monorepos.
 
 ## 5. Exported helpers
 
@@ -153,11 +188,13 @@ Update imports accordingly when consuming these helpers directly.
 
 ## 9. Checklist for upgrading projects
 
-1. Update the dependency to the latest version of `tailwindcss-patch`.
-2. Review custom imports from `tailwindcss-patch/core/*` and switch to the new module paths.
-3. If you instantiate the patcher manually, adopt the new options object.
-4. Refresh CLI usage in scripts (e.g. add `--output` or `--no-write` where appropriate).
-5. For Tailwind v4 projects, configure `tailwindcss.v4.cssEntries` and `sources` so that `extract()` can discover candidates.
-6. Run your extraction workflow and ensure the generated class list matches expectations.
+1. Run `tw-patch migrate --dry-run` and inspect every reported config rewrite.
+2. Rewrite or migrate all config files to modern `registry.extract`, `registry.apply`, and `registry.tailwindcss` fields.
+3. Set `registry.tailwindcss.version` explicitly in every project config.
+4. Update custom imports from `tailwindcss-patch/core/*` to the new module paths.
+5. If you instantiate the patcher manually, switch to the modern constructor shape.
+6. Refresh CLI usage in scripts and rerun `tw-patch install`.
+7. For Tailwind v4 projects, configure `tailwindcss.v4.cssEntries` and `sources` so `extract()` can discover candidates.
+8. Run extraction in each project and compare the generated class list with the pre-upgrade output.
 
 For any regressions or gaps discovered during migration, please open an issue with reproduction details so we can iterate quickly.

packages/tailwindcss-patch/README-cn.md

@@ -60,6 +60,48 @@ pnpm dlx tw-patch validate --report-file .tw-patch/migrate-report.json --json
 
 CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`。v9 仅接受现代 `registry` 结构；如果项目里仍有旧字段，请先执行 `tw-patch migrate`，详情见 [迁移指南](./MIGRATION.md)。
 
+### v9 升级步骤
+
+1. 先执行 `pnpm dlx tw-patch migrate --dry-run`，确认有哪些配置需要改写。
+2. 应用迁移结果，或者手动把配置改成现代 `registry` 字段。
+3. 确认所有配置都显式设置了 `registry.tailwindcss.version`。
+4. 升级到 v9 后，重新执行项目里的 `tw-patch install` / `tw-patch extract`。
+
+legacy 到 v9 的对照示例：
+
+```ts
+// before
+export default defineConfig({
+  registry: {
+    output: {
+      file: '.tw-patch/tw-class-list.json',
+    },
+    tailwind: {
+      package: 'tailwindcss',
+      classic: {
+        cwd: 'apps/web',
+      },
+    },
+  },
+})
+
+// after
+export default defineConfig({
+  registry: {
+    extract: {
+      file: '.tw-patch/tw-class-list.json',
+    },
+    tailwindcss: {
+      version: 4,
+      packageName: 'tailwindcss',
+      v3: {
+        cwd: 'apps/web',
+      },
+    },
+  },
+})
+```
+
 ### `migrate` 常用参数
 
 | 参数                   | 说明                                             |
@@ -239,9 +281,9 @@ console.log(groupedTokens['src/button.tsx'][0].rawCandidate)
 // await patcher.collectContentTokensByFile({ key: 'absolute', stripAbsolutePaths: false })
 ```
 
-构造函数既可以接收上述新版对象，也可以传入旧结构；内部会自动完成兼容转换。
+构造函数在 v9 中只接受上述新版对象。
 
-已标记弃用（下一个大版本移除）的旧字段：`cwd`、`overwrite`、`tailwind`、`features`、`output`。
+以下旧字段在 v9 中会直接报错：`cwd`、`overwrite`、`tailwind`、`features`、`output`。
 
 字段迁移关系：
 
@@ -251,7 +293,7 @@ console.log(groupedTokens['src/button.tsx'][0].rawCandidate)
 - `features` -> `apply`
 - `output` -> `extract`
 
-当运行时检测到这些旧字段时，`normalizeOptions` 会输出一次性告警，帮助你逐步迁移。
+如果项目里还存在这些字段，请先运行 `tw-patch migrate --dry-run` 预览改写结果。
 
 当遇到文件权限受限等情况时，可通过 cache.driver 切换为默认的文件缓存、内存缓存（memory）或无操作模式（noop）。
 

packages/tailwindcss-patch/README.md

@@ -117,6 +117,48 @@ Skip `next()` to fully replace a command (e.g. custom `init` or cache clearing b
 
 The CLI loads `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. v9 expects the modern `registry` shape; use `tw-patch migrate` before upgrading if your config still uses deprecated keys.
 
+### v9 upgrade flow
+
+1. Run `pnpm dlx tw-patch migrate --dry-run` to preview required config rewrites.
+2. Apply the migration, or rewrite the config manually to modern `registry` fields.
+3. Confirm every config sets `registry.tailwindcss.version` explicitly.
+4. Upgrade to v9 and rerun `tw-patch install` / `tw-patch extract` in your project.
+
+Legacy to v9 example:
+
+```ts
+// before
+export default defineConfig({
+  registry: {
+    output: {
+      file: '.tw-patch/tw-class-list.json',
+    },
+    tailwind: {
+      package: 'tailwindcss',
+      classic: {
+        cwd: 'apps/web',
+      },
+    },
+  },
+})
+
+// after
+export default defineConfig({
+  registry: {
+    extract: {
+      file: '.tw-patch/tw-class-list.json',
+    },
+    tailwindcss: {
+      version: 4,
+      packageName: 'tailwindcss',
+      v3: {
+        cwd: 'apps/web',
+      },
+    },
+  },
+})
+```
+
 ### Migrate options
 
 | Flag                   | Description                                                           |
@@ -298,8 +340,6 @@ console.log(patchStatus.entries)
 
 The constructor accepts the modern object shown above only in v9.
 
-Deprecated fields kept temporarily (to be removed in the next major): `cwd`, `overwrite`, `tailwind`, `features`, `output`.
-
 Migration mapping:
 
 - `cwd` -> `projectRoot`