diff --git a/plugins/agent-browser/.agents/skills/agent-browser/SKILL.md b/plugins/agent-browser/.agents/skills/agent-browser/SKILL.md
index bdd73cc6..8485a1f4 100644
--- a/plugins/agent-browser/.agents/skills/agent-browser/SKILL.md
+++ b/plugins/agent-browser/.agents/skills/agent-browser/SKILL.md
@@ -30,6 +30,7 @@ Load a specialized skill when the task falls outside browser web pages:
 agent-browser skills get electron          # Electron desktop apps (VS Code, Slack, Discord, Figma, ...)
 agent-browser skills get slack             # Slack workspace automation
 agent-browser skills get dogfood           # Exploratory testing / QA / bug hunts
+agent-browser skills get derive-client     # Record a HAR, derive a standalone API client for a site
 agent-browser skills get vercel-sandbox    # agent-browser inside Vercel Sandbox microVMs
 agent-browser skills get agentcore         # AWS Bedrock AgentCore cloud browsers
 ```
diff --git a/plugins/agent-browser/.claude/skills/agent-browser b/plugins/agent-browser/.claude/skills/agent-browser
new file mode 120000
index 00000000..e298b7be
--- /dev/null
+++ b/plugins/agent-browser/.claude/skills/agent-browser
@@ -0,0 +1 @@
+../../.agents/skills/agent-browser
\ No newline at end of file
diff --git a/plugins/agent-browser/agent/skills/agent-browser/SKILL.md b/plugins/agent-browser/agent/skills/agent-browser/SKILL.md
index baf88bcd..7a423df7 100644
--- a/plugins/agent-browser/agent/skills/agent-browser/SKILL.md
+++ b/plugins/agent-browser/agent/skills/agent-browser/SKILL.md
@@ -26,6 +26,7 @@ Load a specialized skill when the task falls outside browser web pages:
 agent-browser skills get electron          # Electron desktop apps (VS Code, Slack, Discord, Figma, ...)
 agent-browser skills get slack             # Slack workspace automation
 agent-browser skills get dogfood           # Exploratory testing / QA / bug hunts
+agent-browser skills get derive-client     # Record a HAR, derive a standalone API client for a site
 agent-browser skills get vercel-sandbox    # agent-browser inside Vercel Sandbox microVMs
 agent-browser skills get agentcore         # AWS Bedrock AgentCore cloud browsers
 ```
diff --git a/plugins/agent-browser/skills-lock.json b/plugins/agent-browser/skills-lock.json
index d7858725..7b474434 100644
--- a/plugins/agent-browser/skills-lock.json
+++ b/plugins/agent-browser/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel-labs/agent-browser",
       "sourceType": "github",
       "skillPath": "skills/agent-browser/SKILL.md",
-      "computedHash": "ecc7641aea05f85ca3b11e7759d32aaf52fe05946ab4b63739c7bf78a41237a2"
+      "computedHash": "a674b7d81066e3cc471a7512ddb4ae724418cbfefa75cbb050b0dc430e4d57a0"
     },
     "dogfood": {
       "source": "vercel-labs/agent-browser",
diff --git a/plugins/ai-sdk/.claude/skills/ai-sdk b/plugins/ai-sdk/.claude/skills/ai-sdk
new file mode 120000
index 00000000..ec2935fb
--- /dev/null
+++ b/plugins/ai-sdk/.claude/skills/ai-sdk
@@ -0,0 +1 @@
+../../.agents/skills/ai-sdk
\ No newline at end of file
diff --git a/plugins/antfu/.claude/skills/antfu b/plugins/antfu/.claude/skills/antfu
new file mode 120000
index 00000000..4fc00718
--- /dev/null
+++ b/plugins/antfu/.claude/skills/antfu
@@ -0,0 +1 @@
+../../.agents/skills/antfu
\ No newline at end of file
diff --git a/plugins/ast-grep/.claude/skills/ast-grep b/plugins/ast-grep/.claude/skills/ast-grep
new file mode 120000
index 00000000..00582958
--- /dev/null
+++ b/plugins/ast-grep/.claude/skills/ast-grep
@@ -0,0 +1 @@
+../../.agents/skills/ast-grep
\ No newline at end of file
diff --git a/plugins/axi/.agents/skills/axi/SKILL.md b/plugins/axi/.agents/skills/axi/SKILL.md
index b7c59803..b6e0819a 100644
--- a/plugins/axi/.agents/skills/axi/SKILL.md
+++ b/plugins/axi/.agents/skills/axi/SKILL.md
@@ -245,3 +245,29 @@ description: Manage project tasks in the current workspace
 ```
 
 Every subcommand should support `--help` with a concise, complete reference: available flags with defaults, required arguments, and 2-3 usage examples. Keep it focused on the requested subcommand — don't dump the entire CLI's manual.
+
+### Identify yourself instantly: the `--version` fast path
+
+`-v`, `-V`, and `--version` must all print the bare version and exit 0. Agents and their harnesses probe `--version` constantly - to confirm a tool is installed, to check whether a fix has shipped, to decide whether to suggest `update`. That makes latency an ergonomics property, not just a perf tweak: a probe that takes 80 ms is 80 ms of every session start, paid before any useful work happens.
+
+The trap is ESM static imports. If `bin/<tool>.js` statically imports the module that builds the command graph, every dependency in that graph is fully evaluated _before_ the version check runs. One heavy import anywhere in the tree - an SDK, a server framework - is then paid on every `--version`.
+
+Answer the version before the graph loads: keep the version in a leaf module that imports only node builtins, and defer the real CLI to a dynamic `import()`.
+
+```js
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js"; // leaf module - node builtins only
+
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+  const { main } = await import("../src/cli.js"); // heavy graph loads only here
+  await main();
+}
+```
+
+`axi-sdk-js/fast-path` is a dedicated subpath export that imports nothing at all, so pulling it in never drags in `runAxiCli` or its dependencies. `tryFastPath` handles only a bare, single-argument version flag and returns `false` for everything else, so all other argv - including version flags in trailing positions - falls through to `runAxiCli`, which stays the single owner of the general case. Its accepted flags and output are identical to the SDK's own version handling, so adopting it changes nothing an agent can observe except the latency.
+
+Two things keep this honest:
+
+- The version must come from a **leaf** module. If `VERSION` is defined inside `cli.ts`, importing it re-pulls the whole graph and the fast path buys nothing.
+- Guard it with a test that measures the version path against the `node -e "console.log(1)"` floor measured in the same process, rather than an absolute millisecond budget that goes flaky across machines.
diff --git a/plugins/axi/.claude/skills/axi b/plugins/axi/.claude/skills/axi
new file mode 120000
index 00000000..51a5e828
--- /dev/null
+++ b/plugins/axi/.claude/skills/axi
@@ -0,0 +1 @@
+../../.agents/skills/axi
\ No newline at end of file
diff --git a/plugins/axi/agent/skills/axi/SKILL.md b/plugins/axi/agent/skills/axi/SKILL.md
index f83de045..adbb4949 100644
--- a/plugins/axi/agent/skills/axi/SKILL.md
+++ b/plugins/axi/agent/skills/axi/SKILL.md
@@ -241,3 +241,29 @@ description: Manage project tasks in the current workspace
 ```
 
 Every subcommand should support `--help` with a concise, complete reference: available flags with defaults, required arguments, and 2-3 usage examples. Keep it focused on the requested subcommand — don't dump the entire CLI's manual.
+
+### Identify yourself instantly: the `--version` fast path
+
+`-v`, `-V`, and `--version` must all print the bare version and exit 0. Agents and their harnesses probe `--version` constantly - to confirm a tool is installed, to check whether a fix has shipped, to decide whether to suggest `update`. That makes latency an ergonomics property, not just a perf tweak: a probe that takes 80 ms is 80 ms of every session start, paid before any useful work happens.
+
+The trap is ESM static imports. If `bin/<tool>.js` statically imports the module that builds the command graph, every dependency in that graph is fully evaluated _before_ the version check runs. One heavy import anywhere in the tree - an SDK, a server framework - is then paid on every `--version`.
+
+Answer the version before the graph loads: keep the version in a leaf module that imports only node builtins, and defer the real CLI to a dynamic `import()`.
+
+```js
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js"; // leaf module - node builtins only
+
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+  const { main } = await import("../src/cli.js"); // heavy graph loads only here
+  await main();
+}
+```
+
+`axi-sdk-js/fast-path` is a dedicated subpath export that imports nothing at all, so pulling it in never drags in `runAxiCli` or its dependencies. `tryFastPath` handles only a bare, single-argument version flag and returns `false` for everything else, so all other argv - including version flags in trailing positions - falls through to `runAxiCli`, which stays the single owner of the general case. Its accepted flags and output are identical to the SDK's own version handling, so adopting it changes nothing an agent can observe except the latency.
+
+Two things keep this honest:
+
+- The version must come from a **leaf** module. If `VERSION` is defined inside `cli.ts`, importing it re-pulls the whole graph and the fast path buys nothing.
+- Guard it with a test that measures the version path against the `node -e "console.log(1)"` floor measured in the same process, rather than an absolute millisecond budget that goes flaky across machines.
diff --git a/plugins/axi/skills-lock.json b/plugins/axi/skills-lock.json
index cf1e86d4..2f235a5d 100644
--- a/plugins/axi/skills-lock.json
+++ b/plugins/axi/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "kunchenguid/axi",
       "sourceType": "github",
       "skillPath": ".agents/skills/axi/SKILL.md",
-      "computedHash": "07a1364ca8cea05e5d264ee90c669531618e381a82d6976b17108095fcf90366"
+      "computedHash": "7de23a6b8171a06b7885712f3dd971e64d9301543d1b8c46f21660494303df95"
     }
   }
 }
diff --git a/plugins/better-auth/.agents/skills/better-auth-best-practices/SKILL.md b/plugins/better-auth/.agents/skills/better-auth-best-practices/SKILL.md
index 3e6a4e19..ddeedc81 100644
--- a/plugins/better-auth/.agents/skills/better-auth-best-practices/SKILL.md
+++ b/plugins/better-auth/.agents/skills/better-auth-best-practices/SKILL.md
@@ -15,7 +15,10 @@ description: Configure Better Auth server and client, set up database adapters,
 2. Set env vars: `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`
 3. Create `auth.ts` with database + config
 4. Create route handler for your framework
-5. Run `npx @better-auth/cli@latest migrate`
+5. Run migrations:
+   - **Built-in adapter:** `npx @better-auth/cli@latest migrate`
+   - **Drizzle:** `npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
+   - **Prisma:** `npx @better-auth/cli@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
 6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`
 
 ---
@@ -59,10 +62,12 @@ CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--c
 
 ## Database
 
-**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance.
+**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance. For Postgres, also supports `postgres` (postgres.js) and `@neondatabase/serverless`.
 
 **ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`.
 
+**Drizzle provider values:** `"pg"` (PostgreSQL), `"mysql"` (MySQL), `"sqlite"` (SQLite). Must match the driver used.
+
 **Critical:** Better Auth uses adapter model names, NOT underlying table names. If Prisma model is `User` mapping to table `users`, use `modelName: "user"` (Prisma reference), not `"users"`.
 
 ---
@@ -163,6 +168,8 @@ For separate client/server projects: `createAuthClient<typeof auth>()`.
 4. **Cookie cache** - Custom session fields NOT cached, always re-fetched
 5. **Stateless mode** - No DB = session in cookie only, logout on cache expiry
 6. **Change email flow** - Sends to current email first, then new email
+7. **Drizzle: db not initialized** - `drizzleAdapter(db, ...)` requires a `db` instance from `drizzle()`. See `create-auth` skill for setup examples (node-postgres, postgres.js, Neon).
+8. **Drizzle: missing drizzle.config.ts** - `drizzle-kit` commands require a `drizzle.config.ts` pointing to the generated schema file and DB credentials.
 
 ---
 
diff --git a/plugins/better-auth/.agents/skills/organization-best-practices/SKILL.md b/plugins/better-auth/.agents/skills/organization-best-practices/SKILL.md
index 0e84a844..6f2f6447 100644
--- a/plugins/better-auth/.agents/skills/organization-best-practices/SKILL.md
+++ b/plugins/better-auth/.agents/skills/organization-best-practices/SKILL.md
@@ -7,7 +7,7 @@ description: Configure multi-tenant organizations, manage members and invitation
 
 1. Add `organization()` plugin to server config
 2. Add `organizationClient()` plugin to client config
-3. Run `npx @better-auth/cli migrate`
+3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
 4. Verify: check that organization, member, invitation tables exist in your database
 
 ```ts
diff --git a/plugins/better-auth/.agents/skills/two-factor-authentication-best-practices/SKILL.md b/plugins/better-auth/.agents/skills/two-factor-authentication-best-practices/SKILL.md
index cf9c30bf..74acac84 100644
--- a/plugins/better-auth/.agents/skills/two-factor-authentication-best-practices/SKILL.md
+++ b/plugins/better-auth/.agents/skills/two-factor-authentication-best-practices/SKILL.md
@@ -7,7 +7,7 @@ description: Configure TOTP authenticator apps, send OTP codes via email/SMS, ma
 
 1. Add `twoFactor()` plugin to server config with `issuer`
 2. Add `twoFactorClient()` plugin to client config
-3. Run `npx @better-auth/cli migrate`
+3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
 4. Verify: check that `twoFactorSecret` column exists on user table
 
 ```ts
diff --git a/plugins/better-auth/.claude/skills/better-auth-best-practices b/plugins/better-auth/.claude/skills/better-auth-best-practices
new file mode 120000
index 00000000..d28d6bd7
--- /dev/null
+++ b/plugins/better-auth/.claude/skills/better-auth-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/better-auth-best-practices
\ No newline at end of file
diff --git a/plugins/better-auth/.claude/skills/email-and-password-best-practices b/plugins/better-auth/.claude/skills/email-and-password-best-practices
new file mode 120000
index 00000000..e78bcf65
--- /dev/null
+++ b/plugins/better-auth/.claude/skills/email-and-password-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/email-and-password-best-practices
\ No newline at end of file
diff --git a/plugins/better-auth/.claude/skills/organization-best-practices b/plugins/better-auth/.claude/skills/organization-best-practices
new file mode 120000
index 00000000..d43ca82a
--- /dev/null
+++ b/plugins/better-auth/.claude/skills/organization-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/organization-best-practices
\ No newline at end of file
diff --git a/plugins/better-auth/.claude/skills/two-factor-authentication-best-practices b/plugins/better-auth/.claude/skills/two-factor-authentication-best-practices
new file mode 120000
index 00000000..0defcaa0
--- /dev/null
+++ b/plugins/better-auth/.claude/skills/two-factor-authentication-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/two-factor-authentication-best-practices
\ No newline at end of file
diff --git a/plugins/better-auth/agent/skills/better-auth-best-practices/SKILL.md b/plugins/better-auth/agent/skills/better-auth-best-practices/SKILL.md
index b380767c..3a77bc34 100644
--- a/plugins/better-auth/agent/skills/better-auth-best-practices/SKILL.md
+++ b/plugins/better-auth/agent/skills/better-auth-best-practices/SKILL.md
@@ -13,7 +13,10 @@ description: "Configure Better Auth server and client, set up database adapters,
 2. Set env vars: `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`
 3. Create `auth.ts` with database + config
 4. Create route handler for your framework
-5. Run `npx @better-auth/cli@latest migrate`
+5. Run migrations:
+   - **Built-in adapter:** `npx @better-auth/cli@latest migrate`
+   - **Drizzle:** `npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
+   - **Prisma:** `npx @better-auth/cli@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
 6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`
 
 ---
@@ -57,10 +60,12 @@ CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--c
 
 ## Database
 
-**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance.
+**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance. For Postgres, also supports `postgres` (postgres.js) and `@neondatabase/serverless`.
 
 **ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`.
 
+**Drizzle provider values:** `"pg"` (PostgreSQL), `"mysql"` (MySQL), `"sqlite"` (SQLite). Must match the driver used.
+
 **Critical:** Better Auth uses adapter model names, NOT underlying table names. If Prisma model is `User` mapping to table `users`, use `modelName: "user"` (Prisma reference), not `"users"`.
 
 ---
@@ -161,6 +166,8 @@ For separate client/server projects: `createAuthClient<typeof auth>()`.
 4. **Cookie cache** - Custom session fields NOT cached, always re-fetched
 5. **Stateless mode** - No DB = session in cookie only, logout on cache expiry
 6. **Change email flow** - Sends to current email first, then new email
+7. **Drizzle: db not initialized** - `drizzleAdapter(db, ...)` requires a `db` instance from `drizzle()`. See `create-auth` skill for setup examples (node-postgres, postgres.js, Neon).
+8. **Drizzle: missing drizzle.config.ts** - `drizzle-kit` commands require a `drizzle.config.ts` pointing to the generated schema file and DB credentials.
 
 ---
 
diff --git a/plugins/better-auth/agent/skills/organization-best-practices/SKILL.md b/plugins/better-auth/agent/skills/organization-best-practices/SKILL.md
index 4e07fbbd..819089a9 100644
--- a/plugins/better-auth/agent/skills/organization-best-practices/SKILL.md
+++ b/plugins/better-auth/agent/skills/organization-best-practices/SKILL.md
@@ -5,7 +5,7 @@ description: "Configure multi-tenant organizations, manage members and invitatio
 
 1. Add `organization()` plugin to server config
 2. Add `organizationClient()` plugin to client config
-3. Run `npx @better-auth/cli migrate`
+3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
 4. Verify: check that organization, member, invitation tables exist in your database
 
 ```ts
diff --git a/plugins/better-auth/agent/skills/two-factor-authentication-best-practices/SKILL.md b/plugins/better-auth/agent/skills/two-factor-authentication-best-practices/SKILL.md
index c5bdf15a..6f366f3c 100644
--- a/plugins/better-auth/agent/skills/two-factor-authentication-best-practices/SKILL.md
+++ b/plugins/better-auth/agent/skills/two-factor-authentication-best-practices/SKILL.md
@@ -5,7 +5,7 @@ description: "Configure TOTP authenticator apps, send OTP codes via email/SMS, m
 
 1. Add `twoFactor()` plugin to server config with `issuer`
 2. Add `twoFactorClient()` plugin to client config
-3. Run `npx @better-auth/cli migrate`
+3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
 4. Verify: check that `twoFactorSecret` column exists on user table
 
 ```ts
diff --git a/plugins/better-auth/skills-lock.json b/plugins/better-auth/skills-lock.json
index 11f6218b..052584f7 100644
--- a/plugins/better-auth/skills-lock.json
+++ b/plugins/better-auth/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "better-auth/skills",
       "sourceType": "github",
       "skillPath": "better-auth/best-practices/SKILL.md",
-      "computedHash": "a4c830509e85557b59339d8d93a4e243e9e59c686e7678854d39230e12c2a6dc"
+      "computedHash": "61ba0ef64ed2e7c424401cc848ca33dd6d790a720c44727717dc0c5cba5fc122"
     },
     "create-auth-skill": {
       "source": "better-auth/skills",
@@ -23,13 +23,13 @@
       "source": "better-auth/skills",
       "sourceType": "github",
       "skillPath": "better-auth/organization/SKILL.md",
-      "computedHash": "79a5a85b43d10e9fe37582b3506b051a33a991817b938f349099baa5ddba21aa"
+      "computedHash": "27627eb3a13bd44eff3a5d890f96e7db052b623db90e01684f759abe3e7fe56b"
     },
     "two-factor-authentication-best-practices": {
       "source": "better-auth/skills",
       "sourceType": "github",
       "skillPath": "better-auth/twoFactor/SKILL.md",
-      "computedHash": "7e297aaf887e11fdc03e52bdbf44974e161e8f7c393170ced7dc66cace4f6d46"
+      "computedHash": "a6f720042e5a090909e0d519a6a50a7eb8179553cd5315f0bbad852a6d20dac8"
     }
   }
 }
diff --git a/plugins/chat-sdk/.claude/skills/chat-sdk b/plugins/chat-sdk/.claude/skills/chat-sdk
new file mode 120000
index 00000000..77d22f1b
--- /dev/null
+++ b/plugins/chat-sdk/.claude/skills/chat-sdk
@@ -0,0 +1 @@
+../../.agents/skills/chat-sdk
\ No newline at end of file
diff --git a/plugins/dev3000/.agents/skills/d3k/PUBLISH.md b/plugins/dev3000/.agents/skills/d3k/PUBLISH.md
index 254bb3dd..512c50ee 100644
--- a/plugins/dev3000/.agents/skills/d3k/PUBLISH.md
+++ b/plugins/dev3000/.agents/skills/d3k/PUBLISH.md
@@ -13,15 +13,15 @@
 
 ### Short description
 
-`Bootstraps d3k runtime for standalone AI apps`
+`Agent-owned local web debugging with a managed browser`
 
 ### Long description
 
-`Installs/initializes dev3000 (d3k) for standalone agent shells (Codex, Cursor, Claude Code), starts d3k as the default runtime, and uses unified logs plus CDP browser control instead of raw npm/bun dev.`
+`Starts or reuses d3k in a retained background agent session, opens the project-stable managed browser, and uses unified browser/server evidence instead of raw dev servers or separate automation browsers.`
 
 ### Default prompt
 
-`Use $d3k to initialize d3k, start the correct runtime, and drive debugging with unified logs and CDP browser controls.`
+`Use $d3k to let me test this project in its monitored browser, then inspect the captured evidence after I reproduce the issue.`
 
 ## Source URL
 
diff --git a/plugins/dev3000/.agents/skills/d3k/SKILL.md b/plugins/dev3000/.agents/skills/d3k/SKILL.md
index 7ae3c655..1439e9ad 100644
--- a/plugins/dev3000/.agents/skills/d3k/SKILL.md
+++ b/plugins/dev3000/.agents/skills/d3k/SKILL.md
@@ -1,199 +1,128 @@
 ---
 name: "d3k"
-description: "Bootstrap d3k in standalone AI apps (Codex, Cursor, Claude Code): detect/install dev3000, start d3k as the runtime, and use unified logs plus d3k-owned browser/session control instead of running npm/bun dev directly."
+description: "Use when the user asks to use d3k, run/dev/test/debug a web project with d3k, or reproduce a browser issue. Own the runtime: reuse or background-start d3k non-interactively, wait for readiness, use its project-stable managed Chrome profile, and inspect unified browser/server evidence."
 ---
 
-# d3k Standalone Bootstrap
+# d3k Agent Runtime
 
-Use this skill when working in a standalone AI app and you need reliable local web debugging with browser + server context.
+d3k is the local web runtime for this task. It starts the dev server behind a stable Portless URL, owns a project-stable Chrome profile, and records server logs, browser console output, network activity, interactions, and screenshots in one timeline.
 
-## Why d3k-first
+When this skill triggers, operate d3k. Do not merely tell the user how to run it.
 
-- `d3k` captures server logs, browser console, network events, and screenshots in one timeline.
-- `d3k` owns the browser session so the agent can control the same browser being monitored.
-- Running `npm run dev` or `bun run dev` directly omits this unified telemetry and usually leads to weaker diagnoses.
+## Interpret the Request
 
-## Auth-Sensitive Browser Rule
+- "Let me test/dev my project with d3k": prepare the runtime and headed browser, confirm it is ready, then hand control to the user. Wait for them to reproduce the issue before inspecting evidence.
+- "Test/debug/fix this with d3k": prepare the runtime, then drive the managed browser and investigate autonomously.
+- If ambiguous, start the runtime and browser first. That action is safe and useful for either path.
 
-For Google OAuth, Supabase auth, and any other auth-sensitive debugging, d3k must own browser startup. Start d3k normally so it launches the app and browser together, including `--app-url` when the target URL is known.
+## Start or Reuse d3k
 
-Do not use `d3k agent-browser --profile ... --headed open ...`, raw Chrome, Playwright, browser MCP sessions, manual CDP attachment, or any other separate automation browser for auth debugging unless the user explicitly asks for that path. Agent-browser-created/custom Chrome profiles can be rejected by Google with `This browser or app may not be secure`.
+Run from the project root.
+
+1. Check for an existing project runtime:
 
-After d3k has launched the browser, use the safe managed-browser path:
 ```bash
-d3k agent-browser --require-d3k-browser open "<url>"
-d3k agent-browser snapshot -i
-d3k agent-browser click @e1
-d3k errors --context
+d3k status --json
 ```
 
-If this fails because no d3k-managed browser exists, restart d3k cleanly with its normal browser-owning flow. Do not fall back to creating a new agent-browser Chrome for auth.
+If it reports `"running": true`, reuse it. Do not start a second dev server or browser.
 
-## Bootstrap Workflow
-
-1. Confirm whether `d3k` is installed:
-```bash
-command -v d3k >/dev/null && d3k --version
-```
+2. If d3k is not installed, install it:
 
-2. If `d3k` is missing, install dev3000 globally (prefer Bun):
 ```bash
 bun install -g dev3000
 ```
-Fallback if Bun is unavailable:
-```bash
-npm install -g dev3000
-```
 
-3. Start d3k as the runtime and let d3k own browser startup. When the app command, port, and target URL are known, use the normal app-debugging shape:
-```bash
-d3k --no-agent --command "<dev command>" --port <port> --startup-timeout <seconds> --no-tui --app-url "<url>"
-```
+Use `npm install -g dev3000` only when Bun is unavailable.
 
-   For a repo-default shell with no target URL yet:
-```bash
-d3k --no-agent --no-tui -t
-```
-
-4. Keep d3k running while editing code. Do not start a second dev server with `npm/bun dev`.
+3. Start d3k with the agent's shell/process tool as a retained background or yielded session:
 
-5. Drive the page through d3k's active browser session:
 ```bash
-d3k agent-browser snapshot -i
-d3k agent-browser click @e1
-d3k errors --context
+d3k --no-agent --no-tui -t
 ```
 
-## Required Browser/Session Default
-
-When a user asks to start or debug an app with d3k, prefer d3k's normal browser-owning flow, including `--app-url` when a target URL is known.
+Do not wait for this long-running command to exit. Keep its process/session handle so you can monitor or stop it later. Prefer the execution tool's background/session support over shelling with `&`.
 
-Do not launch a separate raw Chrome, Playwright browser, browser MCP session, or manually attach to CDP unless the user explicitly asks for that path. Separate automation-only browser profiles can break OAuth flows, especially Google sign-in with `This browser or app may not be secure`.
+If the target URL is already known, pass it so the managed browser opens there:
 
-After d3k is running, drive the page through `d3k agent-browser ...` commands so interactions target d3k's active browser session.
-
-If profile or daemon state seems stale, first run:
 ```bash
-d3k agent-browser close --all
+d3k --no-agent --no-tui -t --app-url "<url>"
 ```
 
-Then restart d3k cleanly with the normal browser-owning flow.
+Let d3k auto-detect the package manager, dev command, and port. Add `--command`, `--script`, or `--port` only when detection is wrong or the user specified them.
+
+4. Poll until the runtime is ready:
 
-For a normal app-debugging session, use:
 ```bash
-d3k --no-agent --command "<dev command>" --port <port> --startup-timeout <seconds> --no-tui --app-url "<url>"
-d3k agent-browser --require-d3k-browser open "<url>"
-d3k agent-browser snapshot -i
-d3k agent-browser click @e1
-d3k errors --context
+d3k status --json
 ```
 
-## Non-Auth Fresh Browser/Profile Startup
-
-Use this special-case workflow only for non-auth debugging when the user explicitly asks Codex to start d3k with a fresh browser/profile. Do not use this workflow for Google OAuth, Supabase auth, or any sign-in flow that may reject automation browsers. The default app-debugging workflow is to let d3k own browser startup and then interact through `d3k agent-browser`.
+A successful status response is the readiness boundary. Prefer the reported Portless `appUrl`; the underlying app port may change between runs. If startup fails, inspect the retained process output and `d3k logs --type server`; do not launch a separate dev server.
 
-1. Close any stale `agent-browser` daemon before launching with `--profile`. Otherwise `agent-browser` will reuse the existing daemon and print `--profile ignored`.
-   ```bash
-   d3k agent-browser close --all
-   ```
+## User-Driven Testing
 
-2. Start the app through d3k in `servers-only` mode and keep that command running. In Codex, this is more reliable than asking d3k to launch the browser itself when a fresh profile is required.
-   ```bash
-   d3k --no-agent --no-skills --servers-only --command "npm run dev -- -H 127.0.0.1 -p 3000" --port 3000 --startup-timeout 90 --no-tui
-   ```
+When the user says "let me test":
 
-   Adjust the package-manager command and port for the project. Prefer `--command` over `--script` when passing framework flags. For npm scripts, put flags after `--`; otherwise tools like Next.js can interpret the port as a project directory.
-
-3. Verify the server before opening more browser windows:
-   ```bash
-   curl -I http://127.0.0.1:3000
-   ```
-
-4. Open the fresh profile as a separate browser step:
-   ```bash
-   d3k agent-browser --allow-new-browser --profile /tmp/d3k-fresh-profile --headed open http://127.0.0.1:3000
-   ```
-
-5. Sanity-check the opened page:
-   ```bash
-   d3k agent-browser get title
-   d3k agent-browser snapshot -i
-   d3k errors
-   ```
-
-Practical rules:
-
-- Prefer `127.0.0.1` for this workflow. If `localhost` hangs or flips between IPv4/IPv6 behavior, do not keep retrying browser launches.
-- If `curl -I` hangs, the server is wedged even if the port appears occupied; restart the d3k server process before opening a browser.
-- In `servers-only` mode there is no d3k-managed browser. Use `--allow-new-browser` only for the explicit non-auth fresh-profile open step; do not use `d3k cdp-port`.
-- In sandboxed agent environments, rerun local-network checks and `agent-browser` opens outside the sandbox when sandbox networking blocks access to `127.0.0.1`.
-
-## Debugging Commands
-
-Use these first before ad-hoc log scraping:
+1. Confirm the status response includes the app URL and `"browserConnected": true`.
+2. Tell the user the monitored browser is ready.
+3. Keep the d3k process running and wait for the user to reproduce the behavior.
+4. When they report that it happened, begin with:
 
 ```bash
 d3k errors --context
 d3k logs -n 200
-d3k logs --type browser
-d3k logs --type server
 ```
 
-## Browser Interaction
+Do not replace the headed browser with automation while the user is testing.
+
+## Agent-Driven Testing
 
-Use the already-monitored d3k browser session instead of launching a separate automation browser.
+Drive the exact browser d3k is monitoring:
 
 ```bash
-d3k agent-browser --require-d3k-browser open http://localhost:3000
 d3k agent-browser snapshot -i
 d3k agent-browser click @e2
-d3k agent-browser screenshot /tmp/d3k-current.png
+d3k agent-browser fill @e3 "text"
+d3k errors --context
 ```
 
-`d3k agent-browser` auto-connects to the active d3k session's browser. `--require-d3k-browser` fails instead of creating a new browser when no d3k-managed browser exists. Manual CDP attachment, `d3k agent-browser connect <port>`, and `--allow-new-browser` are explicit opt-in paths for targeting or creating a different browser, not the default.
+Use `--require-d3k-browser` when opening a URL so failure cannot silently create another browser:
 
-## Browser Tool Choice
+```bash
+d3k agent-browser --require-d3k-browser open "<url>"
+```
+
+After every reproduction or code change, replay the relevant interaction and check `d3k errors --context` again.
 
-Use the browser tool that matches the task instead of treating them as interchangeable:
+## Evidence Commands
 
-- `agent-browser`
-  - Default choice.
-  - Best for generic web apps and for driving the exact headed browser session that d3k is already monitoring.
-  - Use it when you need `snapshot`, ref-based `click`, `fill`, or to reproduce what the user sees in the monitored tab.
-- `next-browser`
-  - Next.js-specific tool.
-  - Best for React/Next introspection: `tree`, `errors`, `logs`, `routes`, `project`, PPR inspection, and related Next dev-server signals.
-  - It is not a drop-in replacement for `agent-browser`: no accessibility `snapshot`, no ref-based `click`, and no `fill`.
-  - It launches its own daemon/browser flow and does not use d3k's active browser session.
+Prefer these over ad-hoc log scraping:
 
-Practical rule:
+```bash
+d3k status --json
+d3k errors --context
+d3k logs -n 200
+d3k logs --type browser
+d3k logs --type server
+```
 
-- Need to drive the same browser d3k is monitoring: use `agent-browser`.
-- Need Next.js component tree or Next-specific diagnostics: use `next-browser`.
+Artifacts live under `~/.d3k/<project>/`, including `session.json`, logs, screenshots, and the Chrome profile.
 
-Examples:
+## Browser and Auth Safety
 
-```bash
-# Same monitored browser session
-d3k agent-browser snapshot -i
-d3k agent-browser click @e2
+d3k must own browser startup by default. Its per-project Chrome profile preserves login state, cookies, and local storage.
 
-# Next.js-specific inspection
-d3k next-browser open http://localhost:3000
-d3k next-browser tree
-d3k next-browser errors
-d3k next-browser logs
-```
+For Google OAuth, Supabase auth, and other auth-sensitive flows, never substitute raw Chrome, Playwright, a browser MCP session, manual CDP attachment, or `agent-browser --profile`. Those paths use a different browser/profile and can trigger "This browser or app may not be secure."
 
-## Artifacts to Read
+If the managed browser is unavailable, stop or interrupt the retained d3k process and restart d3k cleanly. Do not work around it by creating another browser.
 
-- `~/.d3k/{project}/d3k.log`
-- `~/.d3k/{project}/logs/`
-- `~/.d3k/{project}/screenshots/`
-- `~/.d3k/{project}/session.json`
+Use `--headless` only for CI or when explicitly requested. Use `--servers-only` only when browser monitoring is intentionally unwanted.
 
 ## Operating Rules
 
-- Prefer headed mode for interactive debugging.
-- Use `--headless` only for CI or when explicitly requested.
-- Use `--servers-only` only when browser monitoring is intentionally disabled, and not for auth-sensitive debugging.
+- Do not run `npm run dev`, `bun run dev`, or another dev server alongside d3k.
+- Do not start a second d3k when `d3k status --json` reports an active one.
+- Keep d3k alive across edits and retests.
+- Preserve the project-stable Chrome profile unless the user explicitly asks for a fresh profile.
+- Leave the runtime running when handing a headed browser to the user; stop it only when asked or when the task requires a clean restart.
+- Portless routing is the default. Use `--no-portless` or `PORTLESS=0` only when direct localhost routing is explicitly required.
diff --git a/plugins/dev3000/.claude/skills/d3k b/plugins/dev3000/.claude/skills/d3k
new file mode 120000
index 00000000..be13baf4
--- /dev/null
+++ b/plugins/dev3000/.claude/skills/d3k
@@ -0,0 +1 @@
+../../.agents/skills/d3k
\ No newline at end of file
diff --git a/plugins/dev3000/agent/skills/d3k/PUBLISH.md b/plugins/dev3000/agent/skills/d3k/PUBLISH.md
index 254bb3dd..512c50ee 100644
--- a/plugins/dev3000/agent/skills/d3k/PUBLISH.md
+++ b/plugins/dev3000/agent/skills/d3k/PUBLISH.md
@@ -13,15 +13,15 @@
 
 ### Short description
 
-`Bootstraps d3k runtime for standalone AI apps`
+`Agent-owned local web debugging with a managed browser`
 
 ### Long description
 
-`Installs/initializes dev3000 (d3k) for standalone agent shells (Codex, Cursor, Claude Code), starts d3k as the default runtime, and uses unified logs plus CDP browser control instead of raw npm/bun dev.`
+`Starts or reuses d3k in a retained background agent session, opens the project-stable managed browser, and uses unified browser/server evidence instead of raw dev servers or separate automation browsers.`
 
 ### Default prompt
 
-`Use $d3k to initialize d3k, start the correct runtime, and drive debugging with unified logs and CDP browser controls.`
+`Use $d3k to let me test this project in its monitored browser, then inspect the captured evidence after I reproduce the issue.`
 
 ## Source URL
 
diff --git a/plugins/dev3000/agent/skills/d3k/SKILL.md b/plugins/dev3000/agent/skills/d3k/SKILL.md
index 9f6260fc..511c3ec0 100644
--- a/plugins/dev3000/agent/skills/d3k/SKILL.md
+++ b/plugins/dev3000/agent/skills/d3k/SKILL.md
@@ -1,197 +1,126 @@
 ---
-description: "Bootstrap d3k in standalone AI apps (Codex, Cursor, Claude Code): detect/install dev3000, start d3k as the runtime, and use unified logs plus d3k-owned browser/session control instead of running npm/bun dev directly."
+description: "Use when the user asks to use d3k, run/dev/test/debug a web project with d3k, or reproduce a browser issue. Own the runtime: reuse or background-start d3k non-interactively, wait for readiness, use its project-stable managed Chrome profile, and inspect unified browser/server evidence."
 ---
-# d3k Standalone Bootstrap
+# d3k Agent Runtime
 
-Use this skill when working in a standalone AI app and you need reliable local web debugging with browser + server context.
+d3k is the local web runtime for this task. It starts the dev server behind a stable Portless URL, owns a project-stable Chrome profile, and records server logs, browser console output, network activity, interactions, and screenshots in one timeline.
 
-## Why d3k-first
+When this skill triggers, operate d3k. Do not merely tell the user how to run it.
 
-- `d3k` captures server logs, browser console, network events, and screenshots in one timeline.
-- `d3k` owns the browser session so the agent can control the same browser being monitored.
-- Running `npm run dev` or `bun run dev` directly omits this unified telemetry and usually leads to weaker diagnoses.
+## Interpret the Request
 
-## Auth-Sensitive Browser Rule
+- "Let me test/dev my project with d3k": prepare the runtime and headed browser, confirm it is ready, then hand control to the user. Wait for them to reproduce the issue before inspecting evidence.
+- "Test/debug/fix this with d3k": prepare the runtime, then drive the managed browser and investigate autonomously.
+- If ambiguous, start the runtime and browser first. That action is safe and useful for either path.
 
-For Google OAuth, Supabase auth, and any other auth-sensitive debugging, d3k must own browser startup. Start d3k normally so it launches the app and browser together, including `--app-url` when the target URL is known.
+## Start or Reuse d3k
 
-Do not use `d3k agent-browser --profile ... --headed open ...`, raw Chrome, Playwright, browser MCP sessions, manual CDP attachment, or any other separate automation browser for auth debugging unless the user explicitly asks for that path. Agent-browser-created/custom Chrome profiles can be rejected by Google with `This browser or app may not be secure`.
+Run from the project root.
+
+1. Check for an existing project runtime:
 
-After d3k has launched the browser, use the safe managed-browser path:
 ```bash
-d3k agent-browser --require-d3k-browser open "<url>"
-d3k agent-browser snapshot -i
-d3k agent-browser click @e1
-d3k errors --context
+d3k status --json
 ```
 
-If this fails because no d3k-managed browser exists, restart d3k cleanly with its normal browser-owning flow. Do not fall back to creating a new agent-browser Chrome for auth.
+If it reports `"running": true`, reuse it. Do not start a second dev server or browser.
 
-## Bootstrap Workflow
-
-1. Confirm whether `d3k` is installed:
-```bash
-command -v d3k >/dev/null && d3k --version
-```
+2. If d3k is not installed, install it:
 
-2. If `d3k` is missing, install dev3000 globally (prefer Bun):
 ```bash
 bun install -g dev3000
 ```
-Fallback if Bun is unavailable:
-```bash
-npm install -g dev3000
-```
 
-3. Start d3k as the runtime and let d3k own browser startup. When the app command, port, and target URL are known, use the normal app-debugging shape:
-```bash
-d3k --no-agent --command "<dev command>" --port <port> --startup-timeout <seconds> --no-tui --app-url "<url>"
-```
+Use `npm install -g dev3000` only when Bun is unavailable.
 
-   For a repo-default shell with no target URL yet:
-```bash
-d3k --no-agent --no-tui -t
-```
-
-4. Keep d3k running while editing code. Do not start a second dev server with `npm/bun dev`.
+3. Start d3k with the agent's shell/process tool as a retained background or yielded session:
 
-5. Drive the page through d3k's active browser session:
 ```bash
-d3k agent-browser snapshot -i
-d3k agent-browser click @e1
-d3k errors --context
+d3k --no-agent --no-tui -t
 ```
 
-## Required Browser/Session Default
-
-When a user asks to start or debug an app with d3k, prefer d3k's normal browser-owning flow, including `--app-url` when a target URL is known.
+Do not wait for this long-running command to exit. Keep its process/session handle so you can monitor or stop it later. Prefer the execution tool's background/session support over shelling with `&`.
 
-Do not launch a separate raw Chrome, Playwright browser, browser MCP session, or manually attach to CDP unless the user explicitly asks for that path. Separate automation-only browser profiles can break OAuth flows, especially Google sign-in with `This browser or app may not be secure`.
+If the target URL is already known, pass it so the managed browser opens there:
 
-After d3k is running, drive the page through `d3k agent-browser ...` commands so interactions target d3k's active browser session.
-
-If profile or daemon state seems stale, first run:
 ```bash
-d3k agent-browser close --all
+d3k --no-agent --no-tui -t --app-url "<url>"
 ```
 
-Then restart d3k cleanly with the normal browser-owning flow.
+Let d3k auto-detect the package manager, dev command, and port. Add `--command`, `--script`, or `--port` only when detection is wrong or the user specified them.
+
+4. Poll until the runtime is ready:
 
-For a normal app-debugging session, use:
 ```bash
-d3k --no-agent --command "<dev command>" --port <port> --startup-timeout <seconds> --no-tui --app-url "<url>"
-d3k agent-browser --require-d3k-browser open "<url>"
-d3k agent-browser snapshot -i
-d3k agent-browser click @e1
-d3k errors --context
+d3k status --json
 ```
 
-## Non-Auth Fresh Browser/Profile Startup
-
-Use this special-case workflow only for non-auth debugging when the user explicitly asks Codex to start d3k with a fresh browser/profile. Do not use this workflow for Google OAuth, Supabase auth, or any sign-in flow that may reject automation browsers. The default app-debugging workflow is to let d3k own browser startup and then interact through `d3k agent-browser`.
+A successful status response is the readiness boundary. Prefer the reported Portless `appUrl`; the underlying app port may change between runs. If startup fails, inspect the retained process output and `d3k logs --type server`; do not launch a separate dev server.
 
-1. Close any stale `agent-browser` daemon before launching with `--profile`. Otherwise `agent-browser` will reuse the existing daemon and print `--profile ignored`.
-   ```bash
-   d3k agent-browser close --all
-   ```
+## User-Driven Testing
 
-2. Start the app through d3k in `servers-only` mode and keep that command running. In Codex, this is more reliable than asking d3k to launch the browser itself when a fresh profile is required.
-   ```bash
-   d3k --no-agent --no-skills --servers-only --command "npm run dev -- -H 127.0.0.1 -p 3000" --port 3000 --startup-timeout 90 --no-tui
-   ```
+When the user says "let me test":
 
-   Adjust the package-manager command and port for the project. Prefer `--command` over `--script` when passing framework flags. For npm scripts, put flags after `--`; otherwise tools like Next.js can interpret the port as a project directory.
-
-3. Verify the server before opening more browser windows:
-   ```bash
-   curl -I http://127.0.0.1:3000
-   ```
-
-4. Open the fresh profile as a separate browser step:
-   ```bash
-   d3k agent-browser --allow-new-browser --profile /tmp/d3k-fresh-profile --headed open http://127.0.0.1:3000
-   ```
-
-5. Sanity-check the opened page:
-   ```bash
-   d3k agent-browser get title
-   d3k agent-browser snapshot -i
-   d3k errors
-   ```
-
-Practical rules:
-
-- Prefer `127.0.0.1` for this workflow. If `localhost` hangs or flips between IPv4/IPv6 behavior, do not keep retrying browser launches.
-- If `curl -I` hangs, the server is wedged even if the port appears occupied; restart the d3k server process before opening a browser.
-- In `servers-only` mode there is no d3k-managed browser. Use `--allow-new-browser` only for the explicit non-auth fresh-profile open step; do not use `d3k cdp-port`.
-- In sandboxed agent environments, rerun local-network checks and `agent-browser` opens outside the sandbox when sandbox networking blocks access to `127.0.0.1`.
-
-## Debugging Commands
-
-Use these first before ad-hoc log scraping:
+1. Confirm the status response includes the app URL and `"browserConnected": true`.
+2. Tell the user the monitored browser is ready.
+3. Keep the d3k process running and wait for the user to reproduce the behavior.
+4. When they report that it happened, begin with:
 
 ```bash
 d3k errors --context
 d3k logs -n 200
-d3k logs --type browser
-d3k logs --type server
 ```
 
-## Browser Interaction
+Do not replace the headed browser with automation while the user is testing.
+
+## Agent-Driven Testing
 
-Use the already-monitored d3k browser session instead of launching a separate automation browser.
+Drive the exact browser d3k is monitoring:
 
 ```bash
-d3k agent-browser --require-d3k-browser open http://localhost:3000
 d3k agent-browser snapshot -i
 d3k agent-browser click @e2
-d3k agent-browser screenshot /tmp/d3k-current.png
+d3k agent-browser fill @e3 "text"
+d3k errors --context
 ```
 
-`d3k agent-browser` auto-connects to the active d3k session's browser. `--require-d3k-browser` fails instead of creating a new browser when no d3k-managed browser exists. Manual CDP attachment, `d3k agent-browser connect <port>`, and `--allow-new-browser` are explicit opt-in paths for targeting or creating a different browser, not the default.
+Use `--require-d3k-browser` when opening a URL so failure cannot silently create another browser:
 
-## Browser Tool Choice
+```bash
+d3k agent-browser --require-d3k-browser open "<url>"
+```
+
+After every reproduction or code change, replay the relevant interaction and check `d3k errors --context` again.
 
-Use the browser tool that matches the task instead of treating them as interchangeable:
+## Evidence Commands
 
-- `agent-browser`
-  - Default choice.
-  - Best for generic web apps and for driving the exact headed browser session that d3k is already monitoring.
-  - Use it when you need `snapshot`, ref-based `click`, `fill`, or to reproduce what the user sees in the monitored tab.
-- `next-browser`
-  - Next.js-specific tool.
-  - Best for React/Next introspection: `tree`, `errors`, `logs`, `routes`, `project`, PPR inspection, and related Next dev-server signals.
-  - It is not a drop-in replacement for `agent-browser`: no accessibility `snapshot`, no ref-based `click`, and no `fill`.
-  - It launches its own daemon/browser flow and does not use d3k's active browser session.
+Prefer these over ad-hoc log scraping:
 
-Practical rule:
+```bash
+d3k status --json
+d3k errors --context
+d3k logs -n 200
+d3k logs --type browser
+d3k logs --type server
+```
 
-- Need to drive the same browser d3k is monitoring: use `agent-browser`.
-- Need Next.js component tree or Next-specific diagnostics: use `next-browser`.
+Artifacts live under `~/.d3k/<project>/`, including `session.json`, logs, screenshots, and the Chrome profile.
 
-Examples:
+## Browser and Auth Safety
 
-```bash
-# Same monitored browser session
-d3k agent-browser snapshot -i
-d3k agent-browser click @e2
+d3k must own browser startup by default. Its per-project Chrome profile preserves login state, cookies, and local storage.
 
-# Next.js-specific inspection
-d3k next-browser open http://localhost:3000
-d3k next-browser tree
-d3k next-browser errors
-d3k next-browser logs
-```
+For Google OAuth, Supabase auth, and other auth-sensitive flows, never substitute raw Chrome, Playwright, a browser MCP session, manual CDP attachment, or `agent-browser --profile`. Those paths use a different browser/profile and can trigger "This browser or app may not be secure."
 
-## Artifacts to Read
+If the managed browser is unavailable, stop or interrupt the retained d3k process and restart d3k cleanly. Do not work around it by creating another browser.
 
-- `~/.d3k/{project}/d3k.log`
-- `~/.d3k/{project}/logs/`
-- `~/.d3k/{project}/screenshots/`
-- `~/.d3k/{project}/session.json`
+Use `--headless` only for CI or when explicitly requested. Use `--servers-only` only when browser monitoring is intentionally unwanted.
 
 ## Operating Rules
 
-- Prefer headed mode for interactive debugging.
-- Use `--headless` only for CI or when explicitly requested.
-- Use `--servers-only` only when browser monitoring is intentionally disabled, and not for auth-sensitive debugging.
+- Do not run `npm run dev`, `bun run dev`, or another dev server alongside d3k.
+- Do not start a second d3k when `d3k status --json` reports an active one.
+- Keep d3k alive across edits and retests.
+- Preserve the project-stable Chrome profile unless the user explicitly asks for a fresh profile.
+- Leave the runtime running when handing a headed browser to the user; stop it only when asked or when the task requires a clean restart.
+- Portless routing is the default. Use `--no-portless` or `PORTLESS=0` only when direct localhost routing is explicitly required.
diff --git a/plugins/dev3000/skills-lock.json b/plugins/dev3000/skills-lock.json
index dbcced14..f7d3f718 100644
--- a/plugins/dev3000/skills-lock.json
+++ b/plugins/dev3000/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel-labs/dev3000",
       "sourceType": "github",
       "skillPath": "skills/d3k/SKILL.md",
-      "computedHash": "13d37628042043672f4331264634ac19956f6e1fc9d97e320af12be5243343aa"
+      "computedHash": "6462ff3b28aaec3ba02f8419e4a6faace3ccb69165bf0da8f55a7da93393e2d3"
     }
   }
 }
diff --git a/plugins/docus/.claude/skills/create-docs b/plugins/docus/.claude/skills/create-docs
new file mode 120000
index 00000000..dac07543
--- /dev/null
+++ b/plugins/docus/.claude/skills/create-docs
@@ -0,0 +1 @@
+../../.agents/skills/create-docs
\ No newline at end of file
diff --git a/plugins/docus/.claude/skills/review-docs b/plugins/docus/.claude/skills/review-docs
new file mode 120000
index 00000000..8d8fe1a9
--- /dev/null
+++ b/plugins/docus/.claude/skills/review-docs
@@ -0,0 +1 @@
+../../.agents/skills/review-docs
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/apple b/plugins/emulate/.claude/skills/apple
new file mode 120000
index 00000000..9a130dbc
--- /dev/null
+++ b/plugins/emulate/.claude/skills/apple
@@ -0,0 +1 @@
+../../.agents/skills/apple
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/aws b/plugins/emulate/.claude/skills/aws
new file mode 120000
index 00000000..8a8a0cc6
--- /dev/null
+++ b/plugins/emulate/.claude/skills/aws
@@ -0,0 +1 @@
+../../.agents/skills/aws
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/emulate b/plugins/emulate/.claude/skills/emulate
new file mode 120000
index 00000000..810be77e
--- /dev/null
+++ b/plugins/emulate/.claude/skills/emulate
@@ -0,0 +1 @@
+../../.agents/skills/emulate
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/github b/plugins/emulate/.claude/skills/github
new file mode 120000
index 00000000..af893bfd
--- /dev/null
+++ b/plugins/emulate/.claude/skills/github
@@ -0,0 +1 @@
+../../.agents/skills/github
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/google b/plugins/emulate/.claude/skills/google
new file mode 120000
index 00000000..50f5353d
--- /dev/null
+++ b/plugins/emulate/.claude/skills/google
@@ -0,0 +1 @@
+../../.agents/skills/google
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/linear b/plugins/emulate/.claude/skills/linear
new file mode 120000
index 00000000..647ab93b
--- /dev/null
+++ b/plugins/emulate/.claude/skills/linear
@@ -0,0 +1 @@
+../../.agents/skills/linear
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/microsoft b/plugins/emulate/.claude/skills/microsoft
new file mode 120000
index 00000000..18651efb
--- /dev/null
+++ b/plugins/emulate/.claude/skills/microsoft
@@ -0,0 +1 @@
+../../.agents/skills/microsoft
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/next b/plugins/emulate/.claude/skills/next
new file mode 120000
index 00000000..55113dc1
--- /dev/null
+++ b/plugins/emulate/.claude/skills/next
@@ -0,0 +1 @@
+../../.agents/skills/next
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/resend b/plugins/emulate/.claude/skills/resend
new file mode 120000
index 00000000..eddaea0b
--- /dev/null
+++ b/plugins/emulate/.claude/skills/resend
@@ -0,0 +1 @@
+../../.agents/skills/resend
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/slack b/plugins/emulate/.claude/skills/slack
new file mode 120000
index 00000000..1cf3af3f
--- /dev/null
+++ b/plugins/emulate/.claude/skills/slack
@@ -0,0 +1 @@
+../../.agents/skills/slack
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/stripe b/plugins/emulate/.claude/skills/stripe
new file mode 120000
index 00000000..7eb1ba12
--- /dev/null
+++ b/plugins/emulate/.claude/skills/stripe
@@ -0,0 +1 @@
+../../.agents/skills/stripe
\ No newline at end of file
diff --git a/plugins/emulate/.claude/skills/vercel b/plugins/emulate/.claude/skills/vercel
new file mode 120000
index 00000000..5e1b3ce3
--- /dev/null
+++ b/plugins/emulate/.claude/skills/vercel
@@ -0,0 +1 @@
+../../.agents/skills/vercel
\ No newline at end of file
diff --git a/plugins/git-ai/.claude/skills/ask b/plugins/git-ai/.claude/skills/ask
new file mode 120000
index 00000000..2db68559
--- /dev/null
+++ b/plugins/git-ai/.claude/skills/ask
@@ -0,0 +1 @@
+../../.agents/skills/ask
\ No newline at end of file
diff --git a/plugins/git-ai/.claude/skills/git-ai-search b/plugins/git-ai/.claude/skills/git-ai-search
new file mode 120000
index 00000000..1635d65a
--- /dev/null
+++ b/plugins/git-ai/.claude/skills/git-ai-search
@@ -0,0 +1 @@
+../../.agents/skills/git-ai-search
\ No newline at end of file
diff --git a/plugins/git-ai/.claude/skills/prompt-analysis b/plugins/git-ai/.claude/skills/prompt-analysis
new file mode 120000
index 00000000..3b8bc272
--- /dev/null
+++ b/plugins/git-ai/.claude/skills/prompt-analysis
@@ -0,0 +1 @@
+../../.agents/skills/prompt-analysis
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-admin-reports b/plugins/google-workspace/.claude/skills/gws-admin-reports
new file mode 120000
index 00000000..a0cbdf73
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-admin-reports
@@ -0,0 +1 @@
+../../.agents/skills/gws-admin-reports
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-calendar b/plugins/google-workspace/.claude/skills/gws-calendar
new file mode 120000
index 00000000..3dbc8165
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-calendar
@@ -0,0 +1 @@
+../../.agents/skills/gws-calendar
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-calendar-agenda b/plugins/google-workspace/.claude/skills/gws-calendar-agenda
new file mode 120000
index 00000000..5309b10e
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-calendar-agenda
@@ -0,0 +1 @@
+../../.agents/skills/gws-calendar-agenda
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-calendar-insert b/plugins/google-workspace/.claude/skills/gws-calendar-insert
new file mode 120000
index 00000000..9c87ae80
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-calendar-insert
@@ -0,0 +1 @@
+../../.agents/skills/gws-calendar-insert
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-chat b/plugins/google-workspace/.claude/skills/gws-chat
new file mode 120000
index 00000000..706de078
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-chat
@@ -0,0 +1 @@
+../../.agents/skills/gws-chat
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-chat-send b/plugins/google-workspace/.claude/skills/gws-chat-send
new file mode 120000
index 00000000..8d31876c
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-chat-send
@@ -0,0 +1 @@
+../../.agents/skills/gws-chat-send
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-classroom b/plugins/google-workspace/.claude/skills/gws-classroom
new file mode 120000
index 00000000..b9a8293a
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-classroom
@@ -0,0 +1 @@
+../../.agents/skills/gws-classroom
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-docs b/plugins/google-workspace/.claude/skills/gws-docs
new file mode 120000
index 00000000..7e0b2bd7
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-docs
@@ -0,0 +1 @@
+../../.agents/skills/gws-docs
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-docs-write b/plugins/google-workspace/.claude/skills/gws-docs-write
new file mode 120000
index 00000000..9ec51409
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-docs-write
@@ -0,0 +1 @@
+../../.agents/skills/gws-docs-write
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-drive b/plugins/google-workspace/.claude/skills/gws-drive
new file mode 120000
index 00000000..ed118107
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-drive
@@ -0,0 +1 @@
+../../.agents/skills/gws-drive
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-drive-upload b/plugins/google-workspace/.claude/skills/gws-drive-upload
new file mode 120000
index 00000000..7b3256cc
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-drive-upload
@@ -0,0 +1 @@
+../../.agents/skills/gws-drive-upload
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-events b/plugins/google-workspace/.claude/skills/gws-events
new file mode 120000
index 00000000..849df899
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-events
@@ -0,0 +1 @@
+../../.agents/skills/gws-events
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-events-renew b/plugins/google-workspace/.claude/skills/gws-events-renew
new file mode 120000
index 00000000..cbaff727
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-events-renew
@@ -0,0 +1 @@
+../../.agents/skills/gws-events-renew
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-events-subscribe b/plugins/google-workspace/.claude/skills/gws-events-subscribe
new file mode 120000
index 00000000..bb8df6e1
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-events-subscribe
@@ -0,0 +1 @@
+../../.agents/skills/gws-events-subscribe
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-forms b/plugins/google-workspace/.claude/skills/gws-forms
new file mode 120000
index 00000000..cbaf837f
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-forms
@@ -0,0 +1 @@
+../../.agents/skills/gws-forms
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail b/plugins/google-workspace/.claude/skills/gws-gmail
new file mode 120000
index 00000000..539fd358
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail-forward b/plugins/google-workspace/.claude/skills/gws-gmail-forward
new file mode 120000
index 00000000..cfbf67c3
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail-forward
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail-forward
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail-read b/plugins/google-workspace/.claude/skills/gws-gmail-read
new file mode 120000
index 00000000..c5b6c147
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail-read
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail-read
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail-reply b/plugins/google-workspace/.claude/skills/gws-gmail-reply
new file mode 120000
index 00000000..bf46a8b6
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail-reply
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail-reply
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail-reply-all b/plugins/google-workspace/.claude/skills/gws-gmail-reply-all
new file mode 120000
index 00000000..a91ece4a
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail-reply-all
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail-reply-all
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail-send b/plugins/google-workspace/.claude/skills/gws-gmail-send
new file mode 120000
index 00000000..8cfd6b73
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail-send
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail-send
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail-triage b/plugins/google-workspace/.claude/skills/gws-gmail-triage
new file mode 120000
index 00000000..6275cd8d
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail-triage
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail-triage
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-gmail-watch b/plugins/google-workspace/.claude/skills/gws-gmail-watch
new file mode 120000
index 00000000..42ff1bc9
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-gmail-watch
@@ -0,0 +1 @@
+../../.agents/skills/gws-gmail-watch
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-keep b/plugins/google-workspace/.claude/skills/gws-keep
new file mode 120000
index 00000000..9c985289
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-keep
@@ -0,0 +1 @@
+../../.agents/skills/gws-keep
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-meet b/plugins/google-workspace/.claude/skills/gws-meet
new file mode 120000
index 00000000..275f80c4
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-meet
@@ -0,0 +1 @@
+../../.agents/skills/gws-meet
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-modelarmor b/plugins/google-workspace/.claude/skills/gws-modelarmor
new file mode 120000
index 00000000..e0d87302
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-modelarmor
@@ -0,0 +1 @@
+../../.agents/skills/gws-modelarmor
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-modelarmor-create-template b/plugins/google-workspace/.claude/skills/gws-modelarmor-create-template
new file mode 120000
index 00000000..7beb6f26
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-modelarmor-create-template
@@ -0,0 +1 @@
+../../.agents/skills/gws-modelarmor-create-template
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-modelarmor-sanitize-prompt b/plugins/google-workspace/.claude/skills/gws-modelarmor-sanitize-prompt
new file mode 120000
index 00000000..2c2e075a
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-modelarmor-sanitize-prompt
@@ -0,0 +1 @@
+../../.agents/skills/gws-modelarmor-sanitize-prompt
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-modelarmor-sanitize-response b/plugins/google-workspace/.claude/skills/gws-modelarmor-sanitize-response
new file mode 120000
index 00000000..6ef3a328
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-modelarmor-sanitize-response
@@ -0,0 +1 @@
+../../.agents/skills/gws-modelarmor-sanitize-response
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-people b/plugins/google-workspace/.claude/skills/gws-people
new file mode 120000
index 00000000..1c1d6bef
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-people
@@ -0,0 +1 @@
+../../.agents/skills/gws-people
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-script b/plugins/google-workspace/.claude/skills/gws-script
new file mode 120000
index 00000000..571c9498
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-script
@@ -0,0 +1 @@
+../../.agents/skills/gws-script
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-script-push b/plugins/google-workspace/.claude/skills/gws-script-push
new file mode 120000
index 00000000..a690bf67
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-script-push
@@ -0,0 +1 @@
+../../.agents/skills/gws-script-push
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-shared b/plugins/google-workspace/.claude/skills/gws-shared
new file mode 120000
index 00000000..55b3ceda
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-shared
@@ -0,0 +1 @@
+../../.agents/skills/gws-shared
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-sheets b/plugins/google-workspace/.claude/skills/gws-sheets
new file mode 120000
index 00000000..89c52b60
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-sheets
@@ -0,0 +1 @@
+../../.agents/skills/gws-sheets
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-sheets-append b/plugins/google-workspace/.claude/skills/gws-sheets-append
new file mode 120000
index 00000000..63e73807
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-sheets-append
@@ -0,0 +1 @@
+../../.agents/skills/gws-sheets-append
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-sheets-read b/plugins/google-workspace/.claude/skills/gws-sheets-read
new file mode 120000
index 00000000..d652ba4b
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-sheets-read
@@ -0,0 +1 @@
+../../.agents/skills/gws-sheets-read
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-slides b/plugins/google-workspace/.claude/skills/gws-slides
new file mode 120000
index 00000000..6bdd6344
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-slides
@@ -0,0 +1 @@
+../../.agents/skills/gws-slides
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-tasks b/plugins/google-workspace/.claude/skills/gws-tasks
new file mode 120000
index 00000000..ce75ec88
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-tasks
@@ -0,0 +1 @@
+../../.agents/skills/gws-tasks
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-workflow b/plugins/google-workspace/.claude/skills/gws-workflow
new file mode 120000
index 00000000..44ee741e
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-workflow
@@ -0,0 +1 @@
+../../.agents/skills/gws-workflow
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-workflow-email-to-task b/plugins/google-workspace/.claude/skills/gws-workflow-email-to-task
new file mode 120000
index 00000000..a48618f9
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-workflow-email-to-task
@@ -0,0 +1 @@
+../../.agents/skills/gws-workflow-email-to-task
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-workflow-file-announce b/plugins/google-workspace/.claude/skills/gws-workflow-file-announce
new file mode 120000
index 00000000..7b32e249
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-workflow-file-announce
@@ -0,0 +1 @@
+../../.agents/skills/gws-workflow-file-announce
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-workflow-meeting-prep b/plugins/google-workspace/.claude/skills/gws-workflow-meeting-prep
new file mode 120000
index 00000000..e58774cd
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-workflow-meeting-prep
@@ -0,0 +1 @@
+../../.agents/skills/gws-workflow-meeting-prep
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-workflow-standup-report b/plugins/google-workspace/.claude/skills/gws-workflow-standup-report
new file mode 120000
index 00000000..89398327
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-workflow-standup-report
@@ -0,0 +1 @@
+../../.agents/skills/gws-workflow-standup-report
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/gws-workflow-weekly-digest b/plugins/google-workspace/.claude/skills/gws-workflow-weekly-digest
new file mode 120000
index 00000000..62bf9d0c
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/gws-workflow-weekly-digest
@@ -0,0 +1 @@
+../../.agents/skills/gws-workflow-weekly-digest
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-content-creator b/plugins/google-workspace/.claude/skills/persona-content-creator
new file mode 120000
index 00000000..75d3653f
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-content-creator
@@ -0,0 +1 @@
+../../.agents/skills/persona-content-creator
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-customer-support b/plugins/google-workspace/.claude/skills/persona-customer-support
new file mode 120000
index 00000000..7046bd1e
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-customer-support
@@ -0,0 +1 @@
+../../.agents/skills/persona-customer-support
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-event-coordinator b/plugins/google-workspace/.claude/skills/persona-event-coordinator
new file mode 120000
index 00000000..796a032f
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-event-coordinator
@@ -0,0 +1 @@
+../../.agents/skills/persona-event-coordinator
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-exec-assistant b/plugins/google-workspace/.claude/skills/persona-exec-assistant
new file mode 120000
index 00000000..b6fa265f
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-exec-assistant
@@ -0,0 +1 @@
+../../.agents/skills/persona-exec-assistant
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-hr-coordinator b/plugins/google-workspace/.claude/skills/persona-hr-coordinator
new file mode 120000
index 00000000..67b4f8d1
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-hr-coordinator
@@ -0,0 +1 @@
+../../.agents/skills/persona-hr-coordinator
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-it-admin b/plugins/google-workspace/.claude/skills/persona-it-admin
new file mode 120000
index 00000000..7c227ef4
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-it-admin
@@ -0,0 +1 @@
+../../.agents/skills/persona-it-admin
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-project-manager b/plugins/google-workspace/.claude/skills/persona-project-manager
new file mode 120000
index 00000000..40533673
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-project-manager
@@ -0,0 +1 @@
+../../.agents/skills/persona-project-manager
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-researcher b/plugins/google-workspace/.claude/skills/persona-researcher
new file mode 120000
index 00000000..037318f2
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-researcher
@@ -0,0 +1 @@
+../../.agents/skills/persona-researcher
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-sales-ops b/plugins/google-workspace/.claude/skills/persona-sales-ops
new file mode 120000
index 00000000..dab84f62
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-sales-ops
@@ -0,0 +1 @@
+../../.agents/skills/persona-sales-ops
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/persona-team-lead b/plugins/google-workspace/.claude/skills/persona-team-lead
new file mode 120000
index 00000000..ba21e938
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/persona-team-lead
@@ -0,0 +1 @@
+../../.agents/skills/persona-team-lead
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-backup-sheet-as-csv b/plugins/google-workspace/.claude/skills/recipe-backup-sheet-as-csv
new file mode 120000
index 00000000..d2cfc075
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-backup-sheet-as-csv
@@ -0,0 +1 @@
+../../.agents/skills/recipe-backup-sheet-as-csv
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-batch-invite-to-event b/plugins/google-workspace/.claude/skills/recipe-batch-invite-to-event
new file mode 120000
index 00000000..17a380bc
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-batch-invite-to-event
@@ -0,0 +1 @@
+../../.agents/skills/recipe-batch-invite-to-event
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-block-focus-time b/plugins/google-workspace/.claude/skills/recipe-block-focus-time
new file mode 120000
index 00000000..9e23d515
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-block-focus-time
@@ -0,0 +1 @@
+../../.agents/skills/recipe-block-focus-time
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-bulk-download-folder b/plugins/google-workspace/.claude/skills/recipe-bulk-download-folder
new file mode 120000
index 00000000..e046300e
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-bulk-download-folder
@@ -0,0 +1 @@
+../../.agents/skills/recipe-bulk-download-folder
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-collect-form-responses b/plugins/google-workspace/.claude/skills/recipe-collect-form-responses
new file mode 120000
index 00000000..cbe6307a
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-collect-form-responses
@@ -0,0 +1 @@
+../../.agents/skills/recipe-collect-form-responses
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-compare-sheet-tabs b/plugins/google-workspace/.claude/skills/recipe-compare-sheet-tabs
new file mode 120000
index 00000000..2d8dc0ad
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-compare-sheet-tabs
@@ -0,0 +1 @@
+../../.agents/skills/recipe-compare-sheet-tabs
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-copy-sheet-for-new-month b/plugins/google-workspace/.claude/skills/recipe-copy-sheet-for-new-month
new file mode 120000
index 00000000..41226253
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-copy-sheet-for-new-month
@@ -0,0 +1 @@
+../../.agents/skills/recipe-copy-sheet-for-new-month
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-classroom-course b/plugins/google-workspace/.claude/skills/recipe-create-classroom-course
new file mode 120000
index 00000000..5899da45
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-classroom-course
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-classroom-course
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-doc-from-template b/plugins/google-workspace/.claude/skills/recipe-create-doc-from-template
new file mode 120000
index 00000000..78d8afd7
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-doc-from-template
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-doc-from-template
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-events-from-sheet b/plugins/google-workspace/.claude/skills/recipe-create-events-from-sheet
new file mode 120000
index 00000000..b6422472
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-events-from-sheet
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-events-from-sheet
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-expense-tracker b/plugins/google-workspace/.claude/skills/recipe-create-expense-tracker
new file mode 120000
index 00000000..dc100069
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-expense-tracker
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-expense-tracker
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-feedback-form b/plugins/google-workspace/.claude/skills/recipe-create-feedback-form
new file mode 120000
index 00000000..0264f187
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-feedback-form
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-feedback-form
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-gmail-filter b/plugins/google-workspace/.claude/skills/recipe-create-gmail-filter
new file mode 120000
index 00000000..aae6809d
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-gmail-filter
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-gmail-filter
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-meet-space b/plugins/google-workspace/.claude/skills/recipe-create-meet-space
new file mode 120000
index 00000000..8118cff1
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-meet-space
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-meet-space
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-presentation b/plugins/google-workspace/.claude/skills/recipe-create-presentation
new file mode 120000
index 00000000..479e35ae
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-presentation
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-presentation
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-shared-drive b/plugins/google-workspace/.claude/skills/recipe-create-shared-drive
new file mode 120000
index 00000000..7e1aa709
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-shared-drive
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-shared-drive
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-task-list b/plugins/google-workspace/.claude/skills/recipe-create-task-list
new file mode 120000
index 00000000..1b5455cb
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-task-list
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-task-list
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-create-vacation-responder b/plugins/google-workspace/.claude/skills/recipe-create-vacation-responder
new file mode 120000
index 00000000..6f714712
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-create-vacation-responder
@@ -0,0 +1 @@
+../../.agents/skills/recipe-create-vacation-responder
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-draft-email-from-doc b/plugins/google-workspace/.claude/skills/recipe-draft-email-from-doc
new file mode 120000
index 00000000..18bcfce2
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-draft-email-from-doc
@@ -0,0 +1 @@
+../../.agents/skills/recipe-draft-email-from-doc
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-email-drive-link b/plugins/google-workspace/.claude/skills/recipe-email-drive-link
new file mode 120000
index 00000000..ee653c46
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-email-drive-link
@@ -0,0 +1 @@
+../../.agents/skills/recipe-email-drive-link
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-find-free-time b/plugins/google-workspace/.claude/skills/recipe-find-free-time
new file mode 120000
index 00000000..3e27bf1e
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-find-free-time
@@ -0,0 +1 @@
+../../.agents/skills/recipe-find-free-time
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-find-large-files b/plugins/google-workspace/.claude/skills/recipe-find-large-files
new file mode 120000
index 00000000..2a83c5d7
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-find-large-files
@@ -0,0 +1 @@
+../../.agents/skills/recipe-find-large-files
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-forward-labeled-emails b/plugins/google-workspace/.claude/skills/recipe-forward-labeled-emails
new file mode 120000
index 00000000..cb1302fb
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-forward-labeled-emails
@@ -0,0 +1 @@
+../../.agents/skills/recipe-forward-labeled-emails
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-generate-report-from-sheet b/plugins/google-workspace/.claude/skills/recipe-generate-report-from-sheet
new file mode 120000
index 00000000..475eab4e
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-generate-report-from-sheet
@@ -0,0 +1 @@
+../../.agents/skills/recipe-generate-report-from-sheet
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-label-and-archive-emails b/plugins/google-workspace/.claude/skills/recipe-label-and-archive-emails
new file mode 120000
index 00000000..628ba559
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-label-and-archive-emails
@@ -0,0 +1 @@
+../../.agents/skills/recipe-label-and-archive-emails
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-log-deal-update b/plugins/google-workspace/.claude/skills/recipe-log-deal-update
new file mode 120000
index 00000000..47f06c92
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-log-deal-update
@@ -0,0 +1 @@
+../../.agents/skills/recipe-log-deal-update
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-organize-drive-folder b/plugins/google-workspace/.claude/skills/recipe-organize-drive-folder
new file mode 120000
index 00000000..26628af1
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-organize-drive-folder
@@ -0,0 +1 @@
+../../.agents/skills/recipe-organize-drive-folder
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-plan-weekly-schedule b/plugins/google-workspace/.claude/skills/recipe-plan-weekly-schedule
new file mode 120000
index 00000000..37095348
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-plan-weekly-schedule
@@ -0,0 +1 @@
+../../.agents/skills/recipe-plan-weekly-schedule
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-post-mortem-setup b/plugins/google-workspace/.claude/skills/recipe-post-mortem-setup
new file mode 120000
index 00000000..661eb6f8
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-post-mortem-setup
@@ -0,0 +1 @@
+../../.agents/skills/recipe-post-mortem-setup
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-reschedule-meeting b/plugins/google-workspace/.claude/skills/recipe-reschedule-meeting
new file mode 120000
index 00000000..db48b554
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-reschedule-meeting
@@ -0,0 +1 @@
+../../.agents/skills/recipe-reschedule-meeting
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-review-meet-participants b/plugins/google-workspace/.claude/skills/recipe-review-meet-participants
new file mode 120000
index 00000000..61b3124c
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-review-meet-participants
@@ -0,0 +1 @@
+../../.agents/skills/recipe-review-meet-participants
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-review-overdue-tasks b/plugins/google-workspace/.claude/skills/recipe-review-overdue-tasks
new file mode 120000
index 00000000..dde6965c
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-review-overdue-tasks
@@ -0,0 +1 @@
+../../.agents/skills/recipe-review-overdue-tasks
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-save-email-attachments b/plugins/google-workspace/.claude/skills/recipe-save-email-attachments
new file mode 120000
index 00000000..72f9ba75
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-save-email-attachments
@@ -0,0 +1 @@
+../../.agents/skills/recipe-save-email-attachments
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-save-email-to-doc b/plugins/google-workspace/.claude/skills/recipe-save-email-to-doc
new file mode 120000
index 00000000..00568e8d
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-save-email-to-doc
@@ -0,0 +1 @@
+../../.agents/skills/recipe-save-email-to-doc
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-schedule-recurring-event b/plugins/google-workspace/.claude/skills/recipe-schedule-recurring-event
new file mode 120000
index 00000000..ea6ead0d
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-schedule-recurring-event
@@ -0,0 +1 @@
+../../.agents/skills/recipe-schedule-recurring-event
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-send-team-announcement b/plugins/google-workspace/.claude/skills/recipe-send-team-announcement
new file mode 120000
index 00000000..e59007b4
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-send-team-announcement
@@ -0,0 +1 @@
+../../.agents/skills/recipe-send-team-announcement
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-share-doc-and-notify b/plugins/google-workspace/.claude/skills/recipe-share-doc-and-notify
new file mode 120000
index 00000000..625ac380
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-share-doc-and-notify
@@ -0,0 +1 @@
+../../.agents/skills/recipe-share-doc-and-notify
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-share-event-materials b/plugins/google-workspace/.claude/skills/recipe-share-event-materials
new file mode 120000
index 00000000..696b79ad
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-share-event-materials
@@ -0,0 +1 @@
+../../.agents/skills/recipe-share-event-materials
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-share-folder-with-team b/plugins/google-workspace/.claude/skills/recipe-share-folder-with-team
new file mode 120000
index 00000000..d7691960
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-share-folder-with-team
@@ -0,0 +1 @@
+../../.agents/skills/recipe-share-folder-with-team
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-sync-contacts-to-sheet b/plugins/google-workspace/.claude/skills/recipe-sync-contacts-to-sheet
new file mode 120000
index 00000000..43f300f9
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-sync-contacts-to-sheet
@@ -0,0 +1 @@
+../../.agents/skills/recipe-sync-contacts-to-sheet
\ No newline at end of file
diff --git a/plugins/google-workspace/.claude/skills/recipe-watch-drive-changes b/plugins/google-workspace/.claude/skills/recipe-watch-drive-changes
new file mode 120000
index 00000000..b3fa5bdb
--- /dev/null
+++ b/plugins/google-workspace/.claude/skills/recipe-watch-drive-changes
@@ -0,0 +1 @@
+../../.agents/skills/recipe-watch-drive-changes
\ No newline at end of file
diff --git a/plugins/greptile/.agents/skills/greploop/SKILL.md b/plugins/greptile/.agents/skills/greploop/SKILL.md
index 43ddb608..43a91fd6 100644
--- a/plugins/greptile/.agents/skills/greploop/SKILL.md
+++ b/plugins/greptile/.agents/skills/greploop/SKILL.md
@@ -116,14 +116,23 @@ Then poll for the Greptile check run to complete:
 
 ```bash
 HEAD_SHA=$(gh pr view <PR_NUMBER> --json headRefOid -q .headRefOid)
+ATTEMPTS=0
+MAX_ATTEMPTS=60
+POLL_INTERVAL_SECONDS=10
 
 while true; do
+  ATTEMPTS=$((ATTEMPTS + 1))
+  if [ "$ATTEMPTS" -gt "$MAX_ATTEMPTS" ]; then
+    echo "Timed out waiting for the Greptile check run after approximately 10 minutes." >&2
+    exit 1
+  fi
+
   GREPTILE_CHECK=$(gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs" \
     --jq '.check_runs[] | select(.name | test("greptile"; "i"))' 2>/dev/null)
   
   if [ -z "$GREPTILE_CHECK" ]; then
     echo "Waiting for Greptile check to appear..."
-    sleep 5
+    sleep "$POLL_INTERVAL_SECONDS"
     continue
   fi
   
@@ -140,10 +149,12 @@ while true; do
   fi
   
   echo "Waiting for Greptile... (status: $STATUS)"
-  sleep 10
+  sleep "$POLL_INTERVAL_SECONDS"
 done
 ```
 
+If polling times out, stop the greploop workflow and report the timeout. Do not continue with stale or missing review results.
+
 **GitLab** — check if Greptile is already running before posting a trigger comment:
 
 ```bash
@@ -165,8 +176,17 @@ Then poll for the Greptile pipeline job to complete (see [GitLab API reference](
 
 ```bash
 HEAD_SHA=$(glab mr view <MR_IID> --output json | jq -r '.sha')
+ATTEMPTS=0
+MAX_ATTEMPTS=60
+POLL_INTERVAL_SECONDS=10
 
 while true; do
+  ATTEMPTS=$((ATTEMPTS + 1))
+  if [ "$ATTEMPTS" -gt "$MAX_ATTEMPTS" ]; then
+    echo "Timed out waiting for the Greptile pipeline job after approximately 10 minutes." >&2
+    exit 1
+  fi
+
   PIPELINES=$(glab api "projects/:fullpath/merge_requests/<MR_IID>/pipelines")
   # Find the most recent pipeline for this SHA
   PIPELINE_ID=$(echo "$PIPELINES" | jq -r --arg sha "$HEAD_SHA" \
@@ -174,7 +194,7 @@ while true; do
 
   if [ -z "$PIPELINE_ID" ]; then
     echo "Waiting for Greptile pipeline to appear..."
-    sleep 5
+    sleep "$POLL_INTERVAL_SECONDS"
     continue
   fi
 
@@ -183,7 +203,7 @@ while true; do
 
   if [ -z "$GREPTILE_JOB" ]; then
     echo "Waiting for Greptile job to appear..."
-    sleep 5
+    sleep "$POLL_INTERVAL_SECONDS"
     continue
   fi
 
@@ -195,10 +215,12 @@ while true; do
   fi
 
   echo "Waiting for Greptile... (status: $JOB_STATUS)"
-  sleep 10
+  sleep "$POLL_INTERVAL_SECONDS"
 done
 ```
 
+If polling times out, stop the greploop workflow and report the timeout. Do not continue with stale or missing review results.
+
 #### B. Fetch Greptile review results
 
 Greptile may surface its score in several places — check **all** of the relevant sources:
diff --git a/plugins/greptile/.claude/skills/check-pr b/plugins/greptile/.claude/skills/check-pr
new file mode 120000
index 00000000..b5085f31
--- /dev/null
+++ b/plugins/greptile/.claude/skills/check-pr
@@ -0,0 +1 @@
+../../.agents/skills/check-pr
\ No newline at end of file
diff --git a/plugins/greptile/.claude/skills/cli-review b/plugins/greptile/.claude/skills/cli-review
new file mode 120000
index 00000000..f7f9386b
--- /dev/null
+++ b/plugins/greptile/.claude/skills/cli-review
@@ -0,0 +1 @@
+../../.agents/skills/cli-review
\ No newline at end of file
diff --git a/plugins/greptile/.claude/skills/greploop b/plugins/greptile/.claude/skills/greploop
new file mode 120000
index 00000000..f7b25640
--- /dev/null
+++ b/plugins/greptile/.claude/skills/greploop
@@ -0,0 +1 @@
+../../.agents/skills/greploop
\ No newline at end of file
diff --git a/plugins/greptile/agent/skills/greploop/SKILL.md b/plugins/greptile/agent/skills/greploop/SKILL.md
index dbbb2261..ac6a3870 100644
--- a/plugins/greptile/agent/skills/greploop/SKILL.md
+++ b/plugins/greptile/agent/skills/greploop/SKILL.md
@@ -106,14 +106,23 @@ Then poll for the Greptile check run to complete:
 
 ```bash
 HEAD_SHA=$(gh pr view <PR_NUMBER> --json headRefOid -q .headRefOid)
+ATTEMPTS=0
+MAX_ATTEMPTS=60
+POLL_INTERVAL_SECONDS=10
 
 while true; do
+  ATTEMPTS=$((ATTEMPTS + 1))
+  if [ "$ATTEMPTS" -gt "$MAX_ATTEMPTS" ]; then
+    echo "Timed out waiting for the Greptile check run after approximately 10 minutes." >&2
+    exit 1
+  fi
+
   GREPTILE_CHECK=$(gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs" \
     --jq '.check_runs[] | select(.name | test("greptile"; "i"))' 2>/dev/null)
   
   if [ -z "$GREPTILE_CHECK" ]; then
     echo "Waiting for Greptile check to appear..."
-    sleep 5
+    sleep "$POLL_INTERVAL_SECONDS"
     continue
   fi
   
@@ -130,10 +139,12 @@ while true; do
   fi
   
   echo "Waiting for Greptile... (status: $STATUS)"
-  sleep 10
+  sleep "$POLL_INTERVAL_SECONDS"
 done
 ```
 
+If polling times out, stop the greploop workflow and report the timeout. Do not continue with stale or missing review results.
+
 **GitLab** — check if Greptile is already running before posting a trigger comment:
 
 ```bash
@@ -155,8 +166,17 @@ Then poll for the Greptile pipeline job to complete (see [GitLab API reference](
 
 ```bash
 HEAD_SHA=$(glab mr view <MR_IID> --output json | jq -r '.sha')
+ATTEMPTS=0
+MAX_ATTEMPTS=60
+POLL_INTERVAL_SECONDS=10
 
 while true; do
+  ATTEMPTS=$((ATTEMPTS + 1))
+  if [ "$ATTEMPTS" -gt "$MAX_ATTEMPTS" ]; then
+    echo "Timed out waiting for the Greptile pipeline job after approximately 10 minutes." >&2
+    exit 1
+  fi
+
   PIPELINES=$(glab api "projects/:fullpath/merge_requests/<MR_IID>/pipelines")
   # Find the most recent pipeline for this SHA
   PIPELINE_ID=$(echo "$PIPELINES" | jq -r --arg sha "$HEAD_SHA" \
@@ -164,7 +184,7 @@ while true; do
 
   if [ -z "$PIPELINE_ID" ]; then
     echo "Waiting for Greptile pipeline to appear..."
-    sleep 5
+    sleep "$POLL_INTERVAL_SECONDS"
     continue
   fi
 
@@ -173,7 +193,7 @@ while true; do
 
   if [ -z "$GREPTILE_JOB" ]; then
     echo "Waiting for Greptile job to appear..."
-    sleep 5
+    sleep "$POLL_INTERVAL_SECONDS"
     continue
   fi
 
@@ -185,10 +205,12 @@ while true; do
   fi
 
   echo "Waiting for Greptile... (status: $JOB_STATUS)"
-  sleep 10
+  sleep "$POLL_INTERVAL_SECONDS"
 done
 ```
 
+If polling times out, stop the greploop workflow and report the timeout. Do not continue with stale or missing review results.
+
 #### B. Fetch Greptile review results
 
 Greptile may surface its score in several places — check **all** of the relevant sources:
diff --git a/plugins/greptile/skills-lock.json b/plugins/greptile/skills-lock.json
index 9127be01..00e4fe07 100644
--- a/plugins/greptile/skills-lock.json
+++ b/plugins/greptile/skills-lock.json
@@ -17,7 +17,7 @@
       "source": "greptileai/skills",
       "sourceType": "github",
       "skillPath": "greploop/SKILL.md",
-      "computedHash": "13849c1cfc853dd4ebdef9caa05e73ea322355dcee6114df64879fdf37ad6f19"
+      "computedHash": "d37000d0e461ccf46116abdf371ad9b0beaaf7d2ed7365fb91f10903bc51cd85"
     }
   }
 }
diff --git a/plugins/lavish/.agents/skills/lavish/SKILL.md b/plugins/lavish/.agents/skills/lavish/SKILL.md
index fac4ab56..fa5eef9c 100644
--- a/plugins/lavish/.agents/skills/lavish/SKILL.md
+++ b/plugins/lavish/.agents/skills/lavish/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: lavish
 description: Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.
-argument-hint: <what the artifact should show>
-author: Kun Chen (kunchenguid)
+license: MIT
 metadata:
-  hermes:
-    tags: [html, review, artifacts, visualization]
-    category: productivity
+  author: Kun Chen (kunchenguid)
+  argument-hint: <what the artifact should show>
+  hermes-tags: html, review, artifacts, visualization
+  hermes-category: productivity
 ---
 
 # Lavish Editor
@@ -15,6 +15,7 @@ Lavish Editor helps agents turn rich HTML artifacts into collaborative human rev
 
 You do not need lavish-axi installed globally - invoke it with `npx -y lavish-axi <html-file>`.
 If lavish-axi output shows a follow-up command starting with `lavish-axi`, run it as `npx -y lavish-axi ...` instead.
+In restricted subprocess sandboxes, CI, or agent harnesses where `npx -y` exits opaquely (for example with status 216), use an already-installed copy directly: `node "$(npm root)/lavish-axi/dist/cli.mjs" <html-file>` for a local install, `node "$(npm root -g)/lavish-axi/dist/cli.mjs" <html-file>` for a global install, or the bare `lavish-axi <html-file>` bin after installing once.
 
 ## Request
 
@@ -31,13 +32,22 @@ Use lavish-axi when the user asks for a visual artifact, HTML explainer, interac
 
 1. Create the HTML artifact (default location `.lavish/<name>.html` in the working directory).
 2. Run `npx -y lavish-axi <html-file>` to open or resume a review session in the browser.
-3. Run `npx -y lavish-axi poll <html-file>` to long-poll for the user's annotations, queued prompts, and browser-reported `layout_warnings`.
-   The poll stays silent until the user acts or the real browser reports fresh layout warnings - leave it running, never kill it.
-   If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost.
-4. If poll returns `layout_warnings`, follow the returned `next_step`: fix and re-check fresh error-severity findings, but proceed with a note instead of looping when every current warning is persistent or low-severity.
-5. Apply human feedback, then poll again with `--agent-reply "<message>"` to reply in the browser and keep the loop going.
+   If the output carries a `self_paint_warning`, fix the unpainted page surface and save before polling - Lavish live-reloads the artifact.
+3. Run `npx -y lavish-axi poll <html-file>` to long-poll for the user's annotations and queued prompts.
+   On the first poll, prefer `--agent-reply "<one-line summary of what you built and what to review first>"` so the conversation panel opens with context.
+   Browser-detected layout issues are filed passively in the user's Layout issues inbox and arrive as an ordinary `layout-warnings` prompt only when the user selects and queues them. Never edit an issue the user has not queued. The only response that arrives without user action is `artifact_failures`, when the review surface itself is unusable.
+   The poll stays silent until the user acts or a fatal artifact failure makes the review surface unusable - leave it running, never kill it.
+   Cosmetic, intentional, transient, tiny, and uncertain observations remain silent.
+   Keep the poll in the foreground by default and let it return the feedback directly to the agent.
+   A background poll is allowed only through a harness-native tracked background-job facility whose completion result is guaranteed to resume or notify the same agent.
+   Never use `nohup`, shell `&`, `disown`, redirected fire-and-forget processes, or a detached terminal without an explicit verified callback merely to keep polling alive.
+   If the harness has no completion-aware background facility, use the foreground poll or first wire a verified wake callback into the surrounding supervisor.
+   Do not tell the user the artifact is being monitored until that wake path is live.
+   If the poll gets killed or times out anyway, just re-run it - queued feedback is never lost.
+4. If poll returns feedback, apply the user's prompts. A `layout-warnings` prompt is an explicit repair request; apply every listed fix in one pass before saving, and let Lavish re-check it after a newer artifact load.
+5. Apply human feedback, then poll again with `--agent-reply "<message>"` to reply in the browser and keep the loop going under the same foreground-or-verified-wake-path rule.
 6. Run `npx -y lavish-axi end <html-file>` when the review is finished.
-7. If the user ends the session from the browser instead, `npx -y lavish-axi <html-file>` refuses to reopen it and says so - only pass `--reopen` when the user asks for further review or something genuinely important needs their visual attention. Otherwise deliver remaining updates directly in this conversation.
+7. `Send & End` ends the session. Its final feedback is still delivered once. After that response, polling stops, and the agent must not reopen the session uninvited. Deliver any remaining updates directly in this conversation.
 
 ## Visual guidance
 
@@ -51,7 +61,7 @@ Use lavish-axi when the user asks for a visual artifact, HTML explainer, interac
 
 Run `npx -y lavish-axi playbook <id>` for focused, detailed guidance on any of these.
 One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so MUST open each matching playbook before writing HTML.
-For flows, architecture, state, or sequence diagrams, do not hand-build boxes-and-arrows from div/flexbox; open the diagram playbook and use Mermaid unless SVG is needed for richly annotated nodes.
+For flows, architecture, state, or sequence diagrams, do not hand-build boxes-and-arrows from div/flexbox; open the diagram playbook and use the theme-aware Mermaid snippet from `npx -y lavish-axi design` unless SVG is needed for richly annotated nodes.
 
 - `diagram` - Map relationships, flows, state, and architecture
 - `table` - Turn dense records into scan-friendly review surfaces
@@ -66,11 +76,12 @@ For flows, architecture, state, or sequence diagrams, do not hand-build boxes-an
 - Run `npx -y lavish-axi <html-file>` to open or resume a Lavish Editor session. If the user explicitly ended the session from the browser, this refuses to reopen it and explains why instead of reopening uninvited - pass `--reopen` only when the user asks for further review or something important needs their visual attention
 - Unless the user specifies another location, create HTML artifacts in the current working directory under `.lavish/`
 - Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work
-- Run `npx -y lavish-axi poll <html-file>` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost. When it reports the session ended, stop polling and do not reopen it uninvited - deliver remaining updates in this conversation instead
+- Run `npx -y lavish-axi poll <html-file>` to wait for user feedback. It long-polls and stays silent until the user sends feedback or ends the session, so leave it running - never kill it. Detected layout issues never return this poll: the browser files them in the user's Layout issues inbox in the Lavish top bar, and they arrive as an ordinary tag "layout-warnings" prompt only when the user selects them and queues the fixes. Never edit the artifact to chase a layout issue the user has not queued. The only exception is a fatal artifact_failures response, which means the review surface itself could not be used. Keep the poll in the foreground by default and let it return the feedback directly to the agent. A background poll is allowed only through a harness-native tracked background-job facility whose completion result is guaranteed to resume or notify the same agent. Never use `nohup`, shell `&`, `disown`, redirected fire-and-forget processes, or a detached terminal without an explicit verified callback merely to keep polling alive. If the harness has no completion-aware background facility, use the foreground poll or first wire a verified wake callback into the surrounding supervisor. Do not tell the user the artifact is being monitored until that wake path is live. If the poll gets killed or times out anyway, just re-run it - queued feedback is never lost. `Send & End` ends the session. Its final feedback is still delivered once. After that response, polling stops, and the agent must not reopen the session uninvited.
+- Rendered Mermaid diagrams in `.mermaid` containers become embedded, editable Excalidraw whiteboards in the browser (click a diagram to unlock editing; a Fullscreen action opens it over the whole viewport) - flowchart, sequence, class, ER, and state diagrams convert to editable shapes; other types embed as an image to draw on. Scenes autosave locally; when a reload detects a changed Mermaid source, the reviewer explicitly chooses to re-convert and discard saved edits or keep editing the saved scene. Standalone and exported copies still render plain Mermaid. Queue feedback adds a prompt to the Conversation panel; when the user sends it, poll returns a tag "whiteboard" prompt carrying a bounded edit summary plus local scenePath (.excalidraw JSON) and previewPath (PNG) files - read the summary first, open the files only when needed, then apply the edits by updating the Mermaid source in the artifact (never try to write the scene back)
 - Run `npx -y lavish-axi end <html-file>` to end a session as the agent - ending it this way still allows a plain reopen later. When the user ends it from the browser instead, a later `npx -y lavish-axi <html-file>` refuses to reopen it without `--reopen`
 - Run `npx -y lavish-axi export <html-file> [--out <path>]` to write a portable copy of the artifact - one HTML file with its LOCAL assets inlined - so it opens with no Lavish server and no sibling files. Remote CDN/font references are left as links, so it needs network to render those. Users can also export from the browser chrome's overflow menu
 - Run `npx -y lavish-axi share <html-file> [--password <pw>] [--token <t>]` to publish the artifact on ht-ml.app (https://ht-ml.app), a third-party hosting service not part of Lavish, and get back a visitable URL. Shares are PUBLIC by default, so anyone with the link can open them. Pass --password to publish a PRIVATE password-protected page; viewers must supply the password to view. Local assets are inlined; remote refs load over the network. It returns the url plus a secret update_key for managing the page later. Use --token or LAVISH_AXI_HTML_APP_TOKEN only when you have an optional bearer token; it is never required. Users can also publish from the browser chrome's overflow menu
 - Run `npx -y lavish-axi stop` to shut down the background server (it also self-stops when idle or after the last session ends with nothing connected)
 - Run `npx -y lavish-axi playbook <playbook_id>` for focused artifact guidance. One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so MUST open each matching playbook before writing HTML.
-- Lavish does not auto-inject any design system - artifacts stay portable so they render identically when opened directly without lavish-axi running. Before writing any HTML, decide the design direction in this strict priority order, and only move to the next step when the current one truly yields nothing: (1) if the user asked for a specific look or named design system, use that; (2) otherwise you must first inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's design system: Tailwind or theme config, shared CSS variables or design tokens, component library, brand assets, or existing styled pages. If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo; (3) only when both steps come up empty, use the Lavish-recommended Tailwind CSS browser runtime v4 + DaisyUI v5, available via CDN - run `npx -y lavish-axi design` for a content-to-playbook router, a copy-pasteable CDN snippet, a Mermaid CDN snippet/init for diagrams, and the DaisyUI component reference, and prefer the Tailwind/DaisyUI CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. When you deliver the artifact, state which of the three design sources you used and why.
+- Lavish does not auto-inject any design system - artifacts stay portable so they render identically when opened directly without lavish-axi running. Before writing any HTML: Decide the design direction in this strict priority order, and only move to the next step when the current one truly yields nothing: (1) if the user asked for a specific look or named design system, use that; (2) otherwise you must first inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's design system: Tailwind or theme config, shared CSS variables or design tokens, component library, brand assets, or existing styled pages. If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo; (3) only when both steps come up empty, use the Lavish-recommended Tailwind CSS browser runtime v4 + DaisyUI v5, available via CDN, and prefer that CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. Run `npx -y lavish-axi design` for a content-to-playbook router, a copy-pasteable CDN snippet, a Mermaid CDN snippet/init for diagrams, and the DaisyUI component reference. When you deliver the artifact, state which of the three design sources you used and why.
 - Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop
diff --git a/plugins/lavish/.claude/skills/lavish b/plugins/lavish/.claude/skills/lavish
new file mode 120000
index 00000000..0fa00290
--- /dev/null
+++ b/plugins/lavish/.claude/skills/lavish
@@ -0,0 +1 @@
+../../.agents/skills/lavish
\ No newline at end of file
diff --git a/plugins/lavish/agent/skills/lavish/SKILL.md b/plugins/lavish/agent/skills/lavish/SKILL.md
index 256f3495..06a399ce 100644
--- a/plugins/lavish/agent/skills/lavish/SKILL.md
+++ b/plugins/lavish/agent/skills/lavish/SKILL.md
@@ -1,5 +1,7 @@
 ---
 description: "Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose."
+license: "MIT"
+metadata: {"author":"Kun Chen (kunchenguid)","argument-hint":"<what the artifact should show>","hermes-tags":"html, review, artifacts, visualization","hermes-category":"productivity"}
 ---
 # Lavish Editor
 
@@ -7,6 +9,7 @@ Lavish Editor helps agents turn rich HTML artifacts into collaborative human rev
 
 You do not need lavish-axi installed globally - invoke it with `npx -y lavish-axi <html-file>`.
 If lavish-axi output shows a follow-up command starting with `lavish-axi`, run it as `npx -y lavish-axi ...` instead.
+In restricted subprocess sandboxes, CI, or agent harnesses where `npx -y` exits opaquely (for example with status 216), use an already-installed copy directly: `node "$(npm root)/lavish-axi/dist/cli.mjs" <html-file>` for a local install, `node "$(npm root -g)/lavish-axi/dist/cli.mjs" <html-file>` for a global install, or the bare `lavish-axi <html-file>` bin after installing once.
 
 ## Request
 
@@ -23,13 +26,22 @@ Use lavish-axi when the user asks for a visual artifact, HTML explainer, interac
 
 1. Create the HTML artifact (default location `.lavish/<name>.html` in the working directory).
 2. Run `npx -y lavish-axi <html-file>` to open or resume a review session in the browser.
-3. Run `npx -y lavish-axi poll <html-file>` to long-poll for the user's annotations, queued prompts, and browser-reported `layout_warnings`.
-   The poll stays silent until the user acts or the real browser reports fresh layout warnings - leave it running, never kill it.
-   If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost.
-4. If poll returns `layout_warnings`, follow the returned `next_step`: fix and re-check fresh error-severity findings, but proceed with a note instead of looping when every current warning is persistent or low-severity.
-5. Apply human feedback, then poll again with `--agent-reply "<message>"` to reply in the browser and keep the loop going.
+   If the output carries a `self_paint_warning`, fix the unpainted page surface and save before polling - Lavish live-reloads the artifact.
+3. Run `npx -y lavish-axi poll <html-file>` to long-poll for the user's annotations and queued prompts.
+   On the first poll, prefer `--agent-reply "<one-line summary of what you built and what to review first>"` so the conversation panel opens with context.
+   Browser-detected layout issues are filed passively in the user's Layout issues inbox and arrive as an ordinary `layout-warnings` prompt only when the user selects and queues them. Never edit an issue the user has not queued. The only response that arrives without user action is `artifact_failures`, when the review surface itself is unusable.
+   The poll stays silent until the user acts or a fatal artifact failure makes the review surface unusable - leave it running, never kill it.
+   Cosmetic, intentional, transient, tiny, and uncertain observations remain silent.
+   Keep the poll in the foreground by default and let it return the feedback directly to the agent.
+   A background poll is allowed only through a harness-native tracked background-job facility whose completion result is guaranteed to resume or notify the same agent.
+   Never use `nohup`, shell `&`, `disown`, redirected fire-and-forget processes, or a detached terminal without an explicit verified callback merely to keep polling alive.
+   If the harness has no completion-aware background facility, use the foreground poll or first wire a verified wake callback into the surrounding supervisor.
+   Do not tell the user the artifact is being monitored until that wake path is live.
+   If the poll gets killed or times out anyway, just re-run it - queued feedback is never lost.
+4. If poll returns feedback, apply the user's prompts. A `layout-warnings` prompt is an explicit repair request; apply every listed fix in one pass before saving, and let Lavish re-check it after a newer artifact load.
+5. Apply human feedback, then poll again with `--agent-reply "<message>"` to reply in the browser and keep the loop going under the same foreground-or-verified-wake-path rule.
 6. Run `npx -y lavish-axi end <html-file>` when the review is finished.
-7. If the user ends the session from the browser instead, `npx -y lavish-axi <html-file>` refuses to reopen it and says so - only pass `--reopen` when the user asks for further review or something genuinely important needs their visual attention. Otherwise deliver remaining updates directly in this conversation.
+7. `Send & End` ends the session. Its final feedback is still delivered once. After that response, polling stops, and the agent must not reopen the session uninvited. Deliver any remaining updates directly in this conversation.
 
 ## Visual guidance
 
@@ -43,7 +55,7 @@ Use lavish-axi when the user asks for a visual artifact, HTML explainer, interac
 
 Run `npx -y lavish-axi playbook <id>` for focused, detailed guidance on any of these.
 One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so MUST open each matching playbook before writing HTML.
-For flows, architecture, state, or sequence diagrams, do not hand-build boxes-and-arrows from div/flexbox; open the diagram playbook and use Mermaid unless SVG is needed for richly annotated nodes.
+For flows, architecture, state, or sequence diagrams, do not hand-build boxes-and-arrows from div/flexbox; open the diagram playbook and use the theme-aware Mermaid snippet from `npx -y lavish-axi design` unless SVG is needed for richly annotated nodes.
 
 - `diagram` - Map relationships, flows, state, and architecture
 - `table` - Turn dense records into scan-friendly review surfaces
@@ -58,11 +70,12 @@ For flows, architecture, state, or sequence diagrams, do not hand-build boxes-an
 - Run `npx -y lavish-axi <html-file>` to open or resume a Lavish Editor session. If the user explicitly ended the session from the browser, this refuses to reopen it and explains why instead of reopening uninvited - pass `--reopen` only when the user asks for further review or something important needs their visual attention
 - Unless the user specifies another location, create HTML artifacts in the current working directory under `.lavish/`
 - Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work
-- Run `npx -y lavish-axi poll <html-file>` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost. When it reports the session ended, stop polling and do not reopen it uninvited - deliver remaining updates in this conversation instead
+- Run `npx -y lavish-axi poll <html-file>` to wait for user feedback. It long-polls and stays silent until the user sends feedback or ends the session, so leave it running - never kill it. Detected layout issues never return this poll: the browser files them in the user's Layout issues inbox in the Lavish top bar, and they arrive as an ordinary tag "layout-warnings" prompt only when the user selects them and queues the fixes. Never edit the artifact to chase a layout issue the user has not queued. The only exception is a fatal artifact_failures response, which means the review surface itself could not be used. Keep the poll in the foreground by default and let it return the feedback directly to the agent. A background poll is allowed only through a harness-native tracked background-job facility whose completion result is guaranteed to resume or notify the same agent. Never use `nohup`, shell `&`, `disown`, redirected fire-and-forget processes, or a detached terminal without an explicit verified callback merely to keep polling alive. If the harness has no completion-aware background facility, use the foreground poll or first wire a verified wake callback into the surrounding supervisor. Do not tell the user the artifact is being monitored until that wake path is live. If the poll gets killed or times out anyway, just re-run it - queued feedback is never lost. `Send & End` ends the session. Its final feedback is still delivered once. After that response, polling stops, and the agent must not reopen the session uninvited.
+- Rendered Mermaid diagrams in `.mermaid` containers become embedded, editable Excalidraw whiteboards in the browser (click a diagram to unlock editing; a Fullscreen action opens it over the whole viewport) - flowchart, sequence, class, ER, and state diagrams convert to editable shapes; other types embed as an image to draw on. Scenes autosave locally; when a reload detects a changed Mermaid source, the reviewer explicitly chooses to re-convert and discard saved edits or keep editing the saved scene. Standalone and exported copies still render plain Mermaid. Queue feedback adds a prompt to the Conversation panel; when the user sends it, poll returns a tag "whiteboard" prompt carrying a bounded edit summary plus local scenePath (.excalidraw JSON) and previewPath (PNG) files - read the summary first, open the files only when needed, then apply the edits by updating the Mermaid source in the artifact (never try to write the scene back)
 - Run `npx -y lavish-axi end <html-file>` to end a session as the agent - ending it this way still allows a plain reopen later. When the user ends it from the browser instead, a later `npx -y lavish-axi <html-file>` refuses to reopen it without `--reopen`
 - Run `npx -y lavish-axi export <html-file> [--out <path>]` to write a portable copy of the artifact - one HTML file with its LOCAL assets inlined - so it opens with no Lavish server and no sibling files. Remote CDN/font references are left as links, so it needs network to render those. Users can also export from the browser chrome's overflow menu
 - Run `npx -y lavish-axi share <html-file> [--password <pw>] [--token <t>]` to publish the artifact on ht-ml.app (https://ht-ml.app), a third-party hosting service not part of Lavish, and get back a visitable URL. Shares are PUBLIC by default, so anyone with the link can open them. Pass --password to publish a PRIVATE password-protected page; viewers must supply the password to view. Local assets are inlined; remote refs load over the network. It returns the url plus a secret update_key for managing the page later. Use --token or LAVISH_AXI_HTML_APP_TOKEN only when you have an optional bearer token; it is never required. Users can also publish from the browser chrome's overflow menu
 - Run `npx -y lavish-axi stop` to shut down the background server (it also self-stops when idle or after the last session ends with nothing connected)
 - Run `npx -y lavish-axi playbook <playbook_id>` for focused artifact guidance. One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so MUST open each matching playbook before writing HTML.
-- Lavish does not auto-inject any design system - artifacts stay portable so they render identically when opened directly without lavish-axi running. Before writing any HTML, decide the design direction in this strict priority order, and only move to the next step when the current one truly yields nothing: (1) if the user asked for a specific look or named design system, use that; (2) otherwise you must first inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's design system: Tailwind or theme config, shared CSS variables or design tokens, component library, brand assets, or existing styled pages. If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo; (3) only when both steps come up empty, use the Lavish-recommended Tailwind CSS browser runtime v4 + DaisyUI v5, available via CDN - run `npx -y lavish-axi design` for a content-to-playbook router, a copy-pasteable CDN snippet, a Mermaid CDN snippet/init for diagrams, and the DaisyUI component reference, and prefer the Tailwind/DaisyUI CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. When you deliver the artifact, state which of the three design sources you used and why.
+- Lavish does not auto-inject any design system - artifacts stay portable so they render identically when opened directly without lavish-axi running. Before writing any HTML: Decide the design direction in this strict priority order, and only move to the next step when the current one truly yields nothing: (1) if the user asked for a specific look or named design system, use that; (2) otherwise you must first inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's design system: Tailwind or theme config, shared CSS variables or design tokens, component library, brand assets, or existing styled pages. If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo; (3) only when both steps come up empty, use the Lavish-recommended Tailwind CSS browser runtime v4 + DaisyUI v5, available via CDN, and prefer that CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. Run `npx -y lavish-axi design` for a content-to-playbook router, a copy-pasteable CDN snippet, a Mermaid CDN snippet/init for diagrams, and the DaisyUI component reference. When you deliver the artifact, state which of the three design sources you used and why.
 - Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop
diff --git a/plugins/lavish/skills-lock.json b/plugins/lavish/skills-lock.json
index 0f5b5295..c259f312 100644
--- a/plugins/lavish/skills-lock.json
+++ b/plugins/lavish/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "kunchenguid/lavish-axi",
       "sourceType": "github",
       "skillPath": "skills/lavish/SKILL.md",
-      "computedHash": "c3a0299d820bc3b30613d7740718b194511201319047fa9d3075e0ab1e596bde"
+      "computedHash": "1516c3ea2b973555b7cc052118102996266366ee27020ce9ec40d93bab6f7ab8"
     }
   }
 }
diff --git a/plugins/mastra/.agents/skills/mastra/SKILL.md b/plugins/mastra/.agents/skills/mastra/SKILL.md
index e66994dc..eac88bf1 100644
--- a/plugins/mastra/.agents/skills/mastra/SKILL.md
+++ b/plugins/mastra/.agents/skills/mastra/SKILL.md
@@ -1,10 +1,10 @@
 ---
 name: mastra
-description: "Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for documentation lookup, API verification, TypeScript setup, common errors, migrations, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, or remote servers."
+description: "Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for documentation lookup, API verification, TypeScript setup, common errors, migrations, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, Trace Intelligence, or remote servers."
 license: Apache-2.0
 metadata:
   author: Mastra
-  version: "2.0.0"
+  version: "2.1.0"
   repository: https://github.com/mastra-ai/skills
 ---
 
@@ -43,6 +43,7 @@ ls node_modules/@mastra/
 | I'm getting an error...           | [`references/common-errors.md`](references/common-errors.md)     | Common errors and solutions                    |
 | Upgrade from v0.x to v1.x         | [`references/migration-guide.md`](references/migration-guide.md) | Version upgrade workflows                      |
 | Inspect/call server resources via CLI | [`references/mastra-api.md`](references/mastra-api.md)       | `mastra api` CLI for local, Mastra platform, or remote servers |
+| Investigate agent health, recurring failures, or improvement opportunities | [`references/trace-intelligence.md`](references/trace-intelligence.md) | Start with aggregate Trace Intelligence themes, then inspect trace/log evidence |
 
 ### Scripts
 
@@ -87,6 +88,10 @@ Then open `http://localhost:4111` in a browser to show Mastra Studio to your hum
 
 Use `mastra api` to inspect or call resources on local dev servers, Mastra platform deployments, or remote Mastra endpoints. It is useful for agent-readable state, execution, traces, logs, scores, threads, and workflow operations. See [`references/mastra-api.md`](references/mastra-api.md) for usage patterns.
 
+## Trace Intelligence
+
+Trace Intelligence (private beta on the Mastra platform) clusters completed agent traces into recurring themes across four trace signals: goal, outcome, behavior, and sentiment. Use it first for aggregate agent-health questions: what users ask for, where outcomes fail or get blocked, which behaviors recur, how sentiment shifts, and where the agent can improve. Then use `mastra api trace`, `log`, `metric`, and `score` commands for concrete execution evidence from specific traces. Query Trace Intelligence with `mastra api learning` CLI commands, or over HTTP via the local dev server proxy or the platform endpoint. See [`references/trace-intelligence.md`](references/trace-intelligence.md) for the investigation workflow, CLI commands, and route reference.
+
 ## Critical requirements
 
 ### TypeScript config
diff --git a/plugins/mastra/.agents/skills/mastra/references/trace-intelligence.md b/plugins/mastra/.agents/skills/mastra/references/trace-intelligence.md
new file mode 100644
index 00000000..d79dc919
--- /dev/null
+++ b/plugins/mastra/.agents/skills/mastra/references/trace-intelligence.md
@@ -0,0 +1,220 @@
+# Trace Intelligence Reference
+
+How to query Trace Intelligence (private beta) from the Mastra platform. Trace Intelligence analyzes completed agent traces and groups them into recurring themes across four trace signals: `goal`, `outcome`, `behavior`, and `sentiment`.
+
+Use this reference when the user asks to investigate agent health, find recurring failures or behavior issues, identify ways to improve an agent, understand what users ask for, inspect recurring goal/outcome/behavior/sentiment themes, or query Trace Intelligence data programmatically.
+
+## Concepts
+
+- **Trace signal**: one-sentence description generated per completed trace, per dimension (`goal`, `outcome`, `behavior`, `sentiment`).
+- **Theme**: durable cluster of similar trace signals for one dimension, with a label and description. Theme IDs are stable across snapshots for one signal.
+- **Snapshot**: a moving analysis window over recent traces. Identified by an opaque `snapshotId`.
+- **Noise**: traces in a snapshot that did not cluster into any theme. Window-local, no durable identity.
+
+## Prerequisites
+
+- The project uses Mastra platform Observability and has completed traces.
+- The project is enrolled in the Trace Intelligence private beta. Non-enrolled projects get `403` from direct project reads.
+
+Analysis is asynchronous: a project generally needs 100+ completed traces before themes exist. Empty responses usually mean not enough analyzed data yet, not an error.
+
+## Access paths
+
+All Trace Intelligence routes are read-only `GET` requests under `/api/learning/`.
+
+1. **`mastra api learning` CLI** (preferred): use the same credential model as hosted observability commands. No `--url` or `--header` is required if `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` are set, or if `.mastra-project.json` is present. The CLI also resolves `X-Mastra-Organization-Id` from `MASTRA_ORGANIZATION_ID` or `.mastra-project.json`.
+
+```bash
+mastra api learning entities '{"entityType":"agent"}'
+```
+
+Pass `--url` and `--header` only when overriding the hosted Trace Intelligence target or credentials.
+
+2. **Local dev server proxy**: `mastra dev` proxies `GET http://localhost:4111/api/learning/*` to the platform using its normal platform credentials. Loopback only.
+
+```bash
+curl -fsS "http://localhost:4111/api/learning/entities?entityType=agent" | jq
+```
+
+3. **Direct platform endpoint** (no CLI or dev server needed): call `https://output.signals.mastra.ai` with explicit auth, project, and organization headers.
+
+```bash
+BASE="https://output.signals.mastra.ai"
+AUTH=(
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN"
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID"
+  -H "X-Mastra-Organization-Id: $MASTRA_ORGANIZATION_ID"
+)
+
+curl -fsS "${AUTH[@]}" "$BASE/api/learning/entities?entityType=agent" | jq
+```
+
+The curl examples below use `$BASE` and `"${AUTH[@]}"`; for the local proxy, replace `$BASE` with `http://localhost:4111` and drop the headers.
+
+## CLI commands
+
+Every route has a CLI command. Positional args carry `entityId`/`themeId`; the JSON input carries the query params from the [route summary](#route-summary). Pass `--schema` to any command to print its input schema, and `--pretty` for readable output.
+
+| Command | Route |
+| --- | --- |
+| `mastra api learning entities '{"entityType":"agent"}'` | `/api/learning/entities` |
+| `mastra api learning snapshots <entityId> <input>` | `.../theme-snapshots` |
+| `mastra api learning flow <entityId> <input>` | `.../theme-flow` |
+| `mastra api learning paths <entityId> <input>` | `.../theme-paths` |
+| `mastra api learning theme list <entityId> <input>` | `.../themes` |
+| `mastra api learning theme get <entityId> <themeId> <input>` | `.../themes/:themeId` |
+| `mastra api learning theme examples <entityId> <themeId> <input>` | `.../themes/:themeId/examples` |
+| `mastra api learning theme history <entityId> <themeId> <input>` | `.../themes/:themeId/history` |
+| `mastra api learning noise get <entityId> <input>` | `.../noise` |
+| `mastra api learning noise examples <entityId> <input>` | `.../noise/examples` |
+
+Same workflow as the curl steps below:
+
+```bash
+# 1. Discover entities and their available signals
+mastra api learning entities '{"entityType":"agent"}'
+
+# 2. List snapshots (signalNames is ordered, comma-separated)
+mastra api learning snapshots my-agent \
+  '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}'
+
+# 3. Themes for one signal in one snapshot (snapshotId from step 2)
+mastra api learning theme list my-agent \
+  '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
+
+# 4. Drill into one theme (numeric themeId from step 3)
+mastra api learning theme examples my-agent 42 \
+  '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
+mastra api learning theme history my-agent 42 \
+  '{"entityType":"agent","signalName":"goal"}'
+```
+
+## Investigation workflow
+
+For broad agent-health or improvement questions, start with Trace Intelligence to find recurring patterns, then use trace/log/metric/score APIs for concrete evidence from specific runs. For a specific failed run or error, start with `mastra api trace` or `mastra api log`, then use Trace Intelligence to check whether the issue is recurring.
+
+Follow this order for aggregate Trace Intelligence analysis. Later calls need values returned by earlier calls.
+
+### 1. Discover entities
+
+Lists entities (agents) that have theme output, with which signals are available:
+
+```bash
+curl -fsS "${AUTH[@]}" "$BASE/api/learning/entities?entityType=agent" \
+  | jq '.entities[] | {entityId, availableSignals, latestWindow}'
+```
+
+Only request `signalNames` that appear in `availableSignals` in later calls.
+
+### 2. List snapshots
+
+`signalNames` is an ordered, comma-separated list (1-4 unique values). A snapshot is returned only when every requested signal has usable output for the window:
+
+```bash
+ENTITY="my-agent" # TODO: entityId from step 1
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/theme-snapshots?entityType=agent&signalNames=goal,outcome,behavior,sentiment&limit=10" \
+  | jq '.snapshots[] | {snapshotId, ordinal, total, startedAt, endedAt, traceCount}'
+```
+
+Optional `from`/`to` (ISO timestamps with offset) bound the snapshot cutoffs; `cursor` paginates newest-first via `nextCursor`.
+
+### 3. Read themes or the cross-signal flow
+
+Use each trace signal for a different diagnostic angle:
+
+- `goal`: what users are trying to do.
+- `outcome`: what completes, fails, gets blocked, or remains unresolved.
+- `behavior`: how the agent behaves, including tool use, loops, refusals, recovery, or drift.
+- `sentiment`: how user emotion changes across interactions.
+
+Themes for one signal in one snapshot:
+
+```bash
+SNAPSHOT="..." # TODO: snapshotId from step 2
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT" \
+  | jq '{themes: [.themes[] | {themeId, label, state, traceCount, coverage, trend}], noise}'
+```
+
+Cross-signal flow (Sankey-style stages and links; counts are distinct traces):
+
+```bash
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/theme-flow?entityType=agent&signalNames=goal,outcome&snapshotId=$SNAPSHOT" \
+  | jq '{stages: [.stages[] | {signalName, nodes: [.nodes[] | {label, kind, traceCount, stageShare}]}], links}'
+```
+
+### 4. Drill into one theme
+
+Use examples to move from aggregate themes to concrete traces. After identifying a suspicious theme, inspect its examples, then use the returned `traceId` with `mastra api trace`, logs, metrics, or scores when you need execution-level evidence.
+
+Detail, examples (raw trace signal texts), and history:
+
+```bash
+THEME="42" # TODO: numeric themeId from step 3
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes/$THEME?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT" | jq '.theme'
+
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes/$THEME/examples?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT&limit=10" \
+  | jq '.examples[] | {traceId, signalText}'
+
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes/$THEME/history?entityType=agent&signalName=goal" \
+  | jq '{points: [.points[] | {state, traceCount, coverage}], relationships}'
+```
+
+History does not take `snapshotId`; it returns the theme's lifecycle (`birth`, `continue`, `split`, `merge`, `death`, `resurrection`) across snapshots, plus split/merge relationships.
+
+### 5. Noise and per-trace paths
+
+Noise bucket and its examples (same query shape as themes, using `/noise` and `/noise/examples`):
+
+```bash
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/noise?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT" | jq '.noise'
+```
+
+Per-trace assignments across the ordered signals (trace-level companion to `theme-flow`; paginate with `limit`/`offset` until `nextOffset` is absent):
+
+```bash
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/theme-paths?entityType=agent&signalNames=goal,outcome&snapshotId=$SNAPSHOT&limit=100" \
+  | jq '{themes, paths: .paths[:5]}'
+```
+
+`paths[].assignments` maps each signal to a theme key (resolved in the `themes` dictionary) or `"noise"`. Use this to join themes back to concrete `traceId` values, then inspect those traces with `mastra api trace` (see [`mastra-api.md`](mastra-api.md)).
+
+## Route summary
+
+| Route | Required query params | Optional |
+| --- | --- | --- |
+| `GET /api/learning/entities` | `entityType` | `limit` |
+| `GET .../:entityId/theme-snapshots` | `entityType`, `signalNames` | `limit`, `cursor`, `from`, `to` |
+| `GET .../:entityId/theme-flow` | `entityType`, `signalNames`, `snapshotId` | `themeLimitPerStage` |
+| `GET .../:entityId/theme-paths` | `entityType`, `signalNames`, `snapshotId` | `limit`, `offset` |
+| `GET .../:entityId/themes` | `entityType`, `signalName`, `snapshotId` | — |
+| `GET .../:entityId/themes/:themeId` | `entityType`, `signalName`, `snapshotId` | — |
+| `GET .../:entityId/themes/:themeId/examples` | `entityType`, `signalName`, `snapshotId` | `limit`, `offset` |
+| `GET .../:entityId/themes/:themeId/history` | `entityType`, `signalName` | `limit`, `cursor` |
+| `GET .../:entityId/noise` | `entityType`, `signalName`, `snapshotId` | — |
+| `GET .../:entityId/noise/examples` | `entityType`, `signalName`, `snapshotId` | `limit`, `offset` |
+
+`:themeId` is numeric. Flow/paths/snapshots take plural ordered `signalNames`; theme/noise routes take singular `signalName`.
+
+## Rules and caveats
+
+- **`snapshotId` is opaque.** Send it back unchanged, with the same entity and signal selection it came from. It is rejected for a different project, entity, or signal set. Never construct or reuse snapshot IDs across scopes.
+- **Counts are distinct traces**, not assignment rows. `coverage`, `stageShare`, `sourceShare`, `targetShare` are fractions of the deduplicated counts.
+- **`other` nodes in `theme-flow`** are lower-volume themes collapsed per stage. They have no `themeId` and cannot be drilled into; raise `themeLimitPerStage` to expand them.
+- **Noise is window-local.** It has no durable ID, label, or trend, and differs between snapshots.
+- **Results are AI-generated summaries.** Verify conclusions against theme examples and the underlying traces before acting on them.
+
+## Errors
+
+- `401`: bad or missing bearer token. Check `MASTRA_PLATFORM_ACCESS_TOKEN`.
+- `403` mentioning `X-Mastra-Organization-Id`: the organization header is missing. Set `MASTRA_ORGANIZATION_ID` (direct curl) or run from a directory containing `.mastra-project.json` (CLI).
+- `403`: project not enrolled in the private beta, or the local proxy was called from a non-loopback host.
+- `503` from the local proxy: `MASTRA_PLATFORM_ACCESS_TOKEN` / `MASTRA_PROJECT_ID` missing from the dev server environment.
+- Empty `entities` or `snapshots`: not enough analyzed traces yet, or the requested `signalNames` are not all available. Re-check `availableSignals` from the entities call.
diff --git a/plugins/mastra/.claude/skills/mastra b/plugins/mastra/.claude/skills/mastra
new file mode 120000
index 00000000..2d4ffc16
--- /dev/null
+++ b/plugins/mastra/.claude/skills/mastra
@@ -0,0 +1 @@
+../../.agents/skills/mastra
\ No newline at end of file
diff --git a/plugins/mastra/agent/skills/mastra/SKILL.md b/plugins/mastra/agent/skills/mastra/SKILL.md
index 0188b009..a313495f 100644
--- a/plugins/mastra/agent/skills/mastra/SKILL.md
+++ b/plugins/mastra/agent/skills/mastra/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for documentation lookup, API verification, TypeScript setup, common errors, migrations, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, or remote servers."
+description: "Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for documentation lookup, API verification, TypeScript setup, common errors, migrations, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, Trace Intelligence, or remote servers."
 license: "Apache-2.0"
-metadata: {"author":"Mastra","version":"2.0.0","repository":"https://github.com/mastra-ai/skills"}
+metadata: {"author":"Mastra","version":"2.1.0","repository":"https://github.com/mastra-ai/skills"}
 ---
 # Mastra Framework Guide
 
@@ -38,6 +38,7 @@ ls node_modules/@mastra/
 | I'm getting an error...           | [`references/common-errors.md`](references/common-errors.md)     | Common errors and solutions                    |
 | Upgrade from v0.x to v1.x         | [`references/migration-guide.md`](references/migration-guide.md) | Version upgrade workflows                      |
 | Inspect/call server resources via CLI | [`references/mastra-api.md`](references/mastra-api.md)       | `mastra api` CLI for local, Mastra platform, or remote servers |
+| Investigate agent health, recurring failures, or improvement opportunities | [`references/trace-intelligence.md`](references/trace-intelligence.md) | Start with aggregate Trace Intelligence themes, then inspect trace/log evidence |
 
 ### Scripts
 
@@ -82,6 +83,10 @@ Then open `http://localhost:4111` in a browser to show Mastra Studio to your hum
 
 Use `mastra api` to inspect or call resources on local dev servers, Mastra platform deployments, or remote Mastra endpoints. It is useful for agent-readable state, execution, traces, logs, scores, threads, and workflow operations. See [`references/mastra-api.md`](references/mastra-api.md) for usage patterns.
 
+## Trace Intelligence
+
+Trace Intelligence (private beta on the Mastra platform) clusters completed agent traces into recurring themes across four trace signals: goal, outcome, behavior, and sentiment. Use it first for aggregate agent-health questions: what users ask for, where outcomes fail or get blocked, which behaviors recur, how sentiment shifts, and where the agent can improve. Then use `mastra api trace`, `log`, `metric`, and `score` commands for concrete execution evidence from specific traces. Query Trace Intelligence with `mastra api learning` CLI commands, or over HTTP via the local dev server proxy or the platform endpoint. See [`references/trace-intelligence.md`](references/trace-intelligence.md) for the investigation workflow, CLI commands, and route reference.
+
 ## Critical requirements
 
 ### TypeScript config
diff --git a/plugins/mastra/agent/skills/mastra/references/trace-intelligence.md b/plugins/mastra/agent/skills/mastra/references/trace-intelligence.md
new file mode 100644
index 00000000..d79dc919
--- /dev/null
+++ b/plugins/mastra/agent/skills/mastra/references/trace-intelligence.md
@@ -0,0 +1,220 @@
+# Trace Intelligence Reference
+
+How to query Trace Intelligence (private beta) from the Mastra platform. Trace Intelligence analyzes completed agent traces and groups them into recurring themes across four trace signals: `goal`, `outcome`, `behavior`, and `sentiment`.
+
+Use this reference when the user asks to investigate agent health, find recurring failures or behavior issues, identify ways to improve an agent, understand what users ask for, inspect recurring goal/outcome/behavior/sentiment themes, or query Trace Intelligence data programmatically.
+
+## Concepts
+
+- **Trace signal**: one-sentence description generated per completed trace, per dimension (`goal`, `outcome`, `behavior`, `sentiment`).
+- **Theme**: durable cluster of similar trace signals for one dimension, with a label and description. Theme IDs are stable across snapshots for one signal.
+- **Snapshot**: a moving analysis window over recent traces. Identified by an opaque `snapshotId`.
+- **Noise**: traces in a snapshot that did not cluster into any theme. Window-local, no durable identity.
+
+## Prerequisites
+
+- The project uses Mastra platform Observability and has completed traces.
+- The project is enrolled in the Trace Intelligence private beta. Non-enrolled projects get `403` from direct project reads.
+
+Analysis is asynchronous: a project generally needs 100+ completed traces before themes exist. Empty responses usually mean not enough analyzed data yet, not an error.
+
+## Access paths
+
+All Trace Intelligence routes are read-only `GET` requests under `/api/learning/`.
+
+1. **`mastra api learning` CLI** (preferred): use the same credential model as hosted observability commands. No `--url` or `--header` is required if `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` are set, or if `.mastra-project.json` is present. The CLI also resolves `X-Mastra-Organization-Id` from `MASTRA_ORGANIZATION_ID` or `.mastra-project.json`.
+
+```bash
+mastra api learning entities '{"entityType":"agent"}'
+```
+
+Pass `--url` and `--header` only when overriding the hosted Trace Intelligence target or credentials.
+
+2. **Local dev server proxy**: `mastra dev` proxies `GET http://localhost:4111/api/learning/*` to the platform using its normal platform credentials. Loopback only.
+
+```bash
+curl -fsS "http://localhost:4111/api/learning/entities?entityType=agent" | jq
+```
+
+3. **Direct platform endpoint** (no CLI or dev server needed): call `https://output.signals.mastra.ai` with explicit auth, project, and organization headers.
+
+```bash
+BASE="https://output.signals.mastra.ai"
+AUTH=(
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN"
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID"
+  -H "X-Mastra-Organization-Id: $MASTRA_ORGANIZATION_ID"
+)
+
+curl -fsS "${AUTH[@]}" "$BASE/api/learning/entities?entityType=agent" | jq
+```
+
+The curl examples below use `$BASE` and `"${AUTH[@]}"`; for the local proxy, replace `$BASE` with `http://localhost:4111` and drop the headers.
+
+## CLI commands
+
+Every route has a CLI command. Positional args carry `entityId`/`themeId`; the JSON input carries the query params from the [route summary](#route-summary). Pass `--schema` to any command to print its input schema, and `--pretty` for readable output.
+
+| Command | Route |
+| --- | --- |
+| `mastra api learning entities '{"entityType":"agent"}'` | `/api/learning/entities` |
+| `mastra api learning snapshots <entityId> <input>` | `.../theme-snapshots` |
+| `mastra api learning flow <entityId> <input>` | `.../theme-flow` |
+| `mastra api learning paths <entityId> <input>` | `.../theme-paths` |
+| `mastra api learning theme list <entityId> <input>` | `.../themes` |
+| `mastra api learning theme get <entityId> <themeId> <input>` | `.../themes/:themeId` |
+| `mastra api learning theme examples <entityId> <themeId> <input>` | `.../themes/:themeId/examples` |
+| `mastra api learning theme history <entityId> <themeId> <input>` | `.../themes/:themeId/history` |
+| `mastra api learning noise get <entityId> <input>` | `.../noise` |
+| `mastra api learning noise examples <entityId> <input>` | `.../noise/examples` |
+
+Same workflow as the curl steps below:
+
+```bash
+# 1. Discover entities and their available signals
+mastra api learning entities '{"entityType":"agent"}'
+
+# 2. List snapshots (signalNames is ordered, comma-separated)
+mastra api learning snapshots my-agent \
+  '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}'
+
+# 3. Themes for one signal in one snapshot (snapshotId from step 2)
+mastra api learning theme list my-agent \
+  '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
+
+# 4. Drill into one theme (numeric themeId from step 3)
+mastra api learning theme examples my-agent 42 \
+  '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
+mastra api learning theme history my-agent 42 \
+  '{"entityType":"agent","signalName":"goal"}'
+```
+
+## Investigation workflow
+
+For broad agent-health or improvement questions, start with Trace Intelligence to find recurring patterns, then use trace/log/metric/score APIs for concrete evidence from specific runs. For a specific failed run or error, start with `mastra api trace` or `mastra api log`, then use Trace Intelligence to check whether the issue is recurring.
+
+Follow this order for aggregate Trace Intelligence analysis. Later calls need values returned by earlier calls.
+
+### 1. Discover entities
+
+Lists entities (agents) that have theme output, with which signals are available:
+
+```bash
+curl -fsS "${AUTH[@]}" "$BASE/api/learning/entities?entityType=agent" \
+  | jq '.entities[] | {entityId, availableSignals, latestWindow}'
+```
+
+Only request `signalNames` that appear in `availableSignals` in later calls.
+
+### 2. List snapshots
+
+`signalNames` is an ordered, comma-separated list (1-4 unique values). A snapshot is returned only when every requested signal has usable output for the window:
+
+```bash
+ENTITY="my-agent" # TODO: entityId from step 1
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/theme-snapshots?entityType=agent&signalNames=goal,outcome,behavior,sentiment&limit=10" \
+  | jq '.snapshots[] | {snapshotId, ordinal, total, startedAt, endedAt, traceCount}'
+```
+
+Optional `from`/`to` (ISO timestamps with offset) bound the snapshot cutoffs; `cursor` paginates newest-first via `nextCursor`.
+
+### 3. Read themes or the cross-signal flow
+
+Use each trace signal for a different diagnostic angle:
+
+- `goal`: what users are trying to do.
+- `outcome`: what completes, fails, gets blocked, or remains unresolved.
+- `behavior`: how the agent behaves, including tool use, loops, refusals, recovery, or drift.
+- `sentiment`: how user emotion changes across interactions.
+
+Themes for one signal in one snapshot:
+
+```bash
+SNAPSHOT="..." # TODO: snapshotId from step 2
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT" \
+  | jq '{themes: [.themes[] | {themeId, label, state, traceCount, coverage, trend}], noise}'
+```
+
+Cross-signal flow (Sankey-style stages and links; counts are distinct traces):
+
+```bash
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/theme-flow?entityType=agent&signalNames=goal,outcome&snapshotId=$SNAPSHOT" \
+  | jq '{stages: [.stages[] | {signalName, nodes: [.nodes[] | {label, kind, traceCount, stageShare}]}], links}'
+```
+
+### 4. Drill into one theme
+
+Use examples to move from aggregate themes to concrete traces. After identifying a suspicious theme, inspect its examples, then use the returned `traceId` with `mastra api trace`, logs, metrics, or scores when you need execution-level evidence.
+
+Detail, examples (raw trace signal texts), and history:
+
+```bash
+THEME="42" # TODO: numeric themeId from step 3
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes/$THEME?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT" | jq '.theme'
+
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes/$THEME/examples?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT&limit=10" \
+  | jq '.examples[] | {traceId, signalText}'
+
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/themes/$THEME/history?entityType=agent&signalName=goal" \
+  | jq '{points: [.points[] | {state, traceCount, coverage}], relationships}'
+```
+
+History does not take `snapshotId`; it returns the theme's lifecycle (`birth`, `continue`, `split`, `merge`, `death`, `resurrection`) across snapshots, plus split/merge relationships.
+
+### 5. Noise and per-trace paths
+
+Noise bucket and its examples (same query shape as themes, using `/noise` and `/noise/examples`):
+
+```bash
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/noise?entityType=agent&signalName=goal&snapshotId=$SNAPSHOT" | jq '.noise'
+```
+
+Per-trace assignments across the ordered signals (trace-level companion to `theme-flow`; paginate with `limit`/`offset` until `nextOffset` is absent):
+
+```bash
+curl -fsS "${AUTH[@]}" \
+  "$BASE/api/learning/entities/$ENTITY/theme-paths?entityType=agent&signalNames=goal,outcome&snapshotId=$SNAPSHOT&limit=100" \
+  | jq '{themes, paths: .paths[:5]}'
+```
+
+`paths[].assignments` maps each signal to a theme key (resolved in the `themes` dictionary) or `"noise"`. Use this to join themes back to concrete `traceId` values, then inspect those traces with `mastra api trace` (see [`mastra-api.md`](mastra-api.md)).
+
+## Route summary
+
+| Route | Required query params | Optional |
+| --- | --- | --- |
+| `GET /api/learning/entities` | `entityType` | `limit` |
+| `GET .../:entityId/theme-snapshots` | `entityType`, `signalNames` | `limit`, `cursor`, `from`, `to` |
+| `GET .../:entityId/theme-flow` | `entityType`, `signalNames`, `snapshotId` | `themeLimitPerStage` |
+| `GET .../:entityId/theme-paths` | `entityType`, `signalNames`, `snapshotId` | `limit`, `offset` |
+| `GET .../:entityId/themes` | `entityType`, `signalName`, `snapshotId` | — |
+| `GET .../:entityId/themes/:themeId` | `entityType`, `signalName`, `snapshotId` | — |
+| `GET .../:entityId/themes/:themeId/examples` | `entityType`, `signalName`, `snapshotId` | `limit`, `offset` |
+| `GET .../:entityId/themes/:themeId/history` | `entityType`, `signalName` | `limit`, `cursor` |
+| `GET .../:entityId/noise` | `entityType`, `signalName`, `snapshotId` | — |
+| `GET .../:entityId/noise/examples` | `entityType`, `signalName`, `snapshotId` | `limit`, `offset` |
+
+`:themeId` is numeric. Flow/paths/snapshots take plural ordered `signalNames`; theme/noise routes take singular `signalName`.
+
+## Rules and caveats
+
+- **`snapshotId` is opaque.** Send it back unchanged, with the same entity and signal selection it came from. It is rejected for a different project, entity, or signal set. Never construct or reuse snapshot IDs across scopes.
+- **Counts are distinct traces**, not assignment rows. `coverage`, `stageShare`, `sourceShare`, `targetShare` are fractions of the deduplicated counts.
+- **`other` nodes in `theme-flow`** are lower-volume themes collapsed per stage. They have no `themeId` and cannot be drilled into; raise `themeLimitPerStage` to expand them.
+- **Noise is window-local.** It has no durable ID, label, or trend, and differs between snapshots.
+- **Results are AI-generated summaries.** Verify conclusions against theme examples and the underlying traces before acting on them.
+
+## Errors
+
+- `401`: bad or missing bearer token. Check `MASTRA_PLATFORM_ACCESS_TOKEN`.
+- `403` mentioning `X-Mastra-Organization-Id`: the organization header is missing. Set `MASTRA_ORGANIZATION_ID` (direct curl) or run from a directory containing `.mastra-project.json` (CLI).
+- `403`: project not enrolled in the private beta, or the local proxy was called from a non-loopback host.
+- `503` from the local proxy: `MASTRA_PLATFORM_ACCESS_TOKEN` / `MASTRA_PROJECT_ID` missing from the dev server environment.
+- Empty `entities` or `snapshots`: not enough analyzed traces yet, or the requested `signalNames` are not all available. Re-check `availableSignals` from the entities call.
diff --git a/plugins/mastra/skills-lock.json b/plugins/mastra/skills-lock.json
index a77ed31f..940dd7a9 100644
--- a/plugins/mastra/skills-lock.json
+++ b/plugins/mastra/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "mastra-ai/skills",
       "sourceType": "github",
       "skillPath": "skills/mastra/SKILL.md",
-      "computedHash": "f0ca76d36d67a345064f471a9577e752beb2b20ab46acdf154ed223905e1d3a4"
+      "computedHash": "6482dad39fb72d1fe9d02078c15c3ee708774fd026a8557b4c7dc37fb554977a"
     }
   }
 }
diff --git a/plugins/nostics/.agents/skills/nostics/SKILL.md b/plugins/nostics/.agents/skills/nostics/SKILL.md
index c9c1b46e..23269443 100644
--- a/plugins/nostics/.agents/skills/nostics/SKILL.md
+++ b/plugins/nostics/.agents/skills/nostics/SKILL.md
@@ -142,7 +142,7 @@ export const diagnostics =
       })
 ```
 
-The accessed code becomes the `message`, `docs` still derives from `docsBase`, no `why`/`fix` text ships. No `reporters` by default (so a surviving `throw` doesn't also log and then resurface as the uncaught error); pass `reporters` to keep prod telemetry. `nosticsStrip` tracks this ternary like a direct catalog export.
+The accessed code becomes the instance `name`, `docs` still derives from `docsBase`, `why` points to the docs URL when one exists (empty otherwise), no `why`/`fix` text ships. No `reporters` by default (so a surviving `throw` doesn't also log and then resurface as the uncaught error); pass `reporters` to keep prod telemetry. `nosticsStrip` tracks this ternary like a direct catalog export.
 
 ## Conventions
 
diff --git a/plugins/nostics/.claude/skills/add-diagnostic b/plugins/nostics/.claude/skills/add-diagnostic
new file mode 120000
index 00000000..232e310b
--- /dev/null
+++ b/plugins/nostics/.claude/skills/add-diagnostic
@@ -0,0 +1 @@
+../../.agents/skills/add-diagnostic
\ No newline at end of file
diff --git a/plugins/nostics/.claude/skills/nostics b/plugins/nostics/.claude/skills/nostics
new file mode 120000
index 00000000..9f76d555
--- /dev/null
+++ b/plugins/nostics/.claude/skills/nostics
@@ -0,0 +1 @@
+../../.agents/skills/nostics
\ No newline at end of file
diff --git a/plugins/nostics/agent/skills/nostics/SKILL.md b/plugins/nostics/agent/skills/nostics/SKILL.md
index d2daaee6..76179399 100644
--- a/plugins/nostics/agent/skills/nostics/SKILL.md
+++ b/plugins/nostics/agent/skills/nostics/SKILL.md
@@ -140,7 +140,7 @@ export const diagnostics =
       })
 ```
 
-The accessed code becomes the `message`, `docs` still derives from `docsBase`, no `why`/`fix` text ships. No `reporters` by default (so a surviving `throw` doesn't also log and then resurface as the uncaught error); pass `reporters` to keep prod telemetry. `nosticsStrip` tracks this ternary like a direct catalog export.
+The accessed code becomes the instance `name`, `docs` still derives from `docsBase`, `why` points to the docs URL when one exists (empty otherwise), no `why`/`fix` text ships. No `reporters` by default (so a surviving `throw` doesn't also log and then resurface as the uncaught error); pass `reporters` to keep prod telemetry. `nosticsStrip` tracks this ternary like a direct catalog export.
 
 ## Conventions
 
diff --git a/plugins/nostics/skills-lock.json b/plugins/nostics/skills-lock.json
index e8f71ee1..797422a3 100644
--- a/plugins/nostics/skills-lock.json
+++ b/plugins/nostics/skills-lock.json
@@ -5,13 +5,13 @@
       "source": "vercel-labs/nostics",
       "sourceType": "github",
       "skillPath": "skills/add-diagnostic/SKILL.md",
-      "computedHash": "bffe858a73515c6dcd391644a6c5ac494f0ef56454fa713156f093f7241544f6"
+      "computedHash": "c7b8e4657722027d0ec9099406e05941d33103cc76b4915859e3cd60f94617a0"
     },
     "nostics": {
       "source": "vercel-labs/nostics",
       "sourceType": "github",
       "skillPath": "skills/nostics/SKILL.md",
-      "computedHash": "e44672950987d49b46bc53be17bd11ed7e4270eb031c837417239cb34f2c95f8"
+      "computedHash": "7a39ad8833dd28e1209b7c269564b6a864a859cf86fb3b64a87790bf3b47c5cc"
     }
   }
 }
diff --git a/plugins/nuxt-seo/.claude/skills/nuxt-seo b/plugins/nuxt-seo/.claude/skills/nuxt-seo
new file mode 120000
index 00000000..fb7f6572
--- /dev/null
+++ b/plugins/nuxt-seo/.claude/skills/nuxt-seo
@@ -0,0 +1 @@
+../../.agents/skills/nuxt-seo
\ No newline at end of file
diff --git a/plugins/nuxt-ui/.claude/skills/nuxt-ui b/plugins/nuxt-ui/.claude/skills/nuxt-ui
new file mode 120000
index 00000000..f7d99193
--- /dev/null
+++ b/plugins/nuxt-ui/.claude/skills/nuxt-ui
@@ -0,0 +1 @@
+../../.agents/skills/nuxt-ui
\ No newline at end of file
diff --git a/plugins/nuxt/.claude/skills/nuxt b/plugins/nuxt/.claude/skills/nuxt
new file mode 120000
index 00000000..7bf43bbc
--- /dev/null
+++ b/plugins/nuxt/.claude/skills/nuxt
@@ -0,0 +1 @@
+../../.agents/skills/nuxt
\ No newline at end of file
diff --git a/plugins/pinia/.claude/skills/pinia b/plugins/pinia/.claude/skills/pinia
new file mode 120000
index 00000000..b29e1ea3
--- /dev/null
+++ b/plugins/pinia/.claude/skills/pinia
@@ -0,0 +1 @@
+../../.agents/skills/pinia
\ No newline at end of file
diff --git a/plugins/playwright-cli/.claude/skills/playwright-cli b/plugins/playwright-cli/.claude/skills/playwright-cli
new file mode 120000
index 00000000..a5bb5229
--- /dev/null
+++ b/plugins/playwright-cli/.claude/skills/playwright-cli
@@ -0,0 +1 @@
+../../.agents/skills/playwright-cli
\ No newline at end of file
diff --git a/plugins/pnpm/.claude/skills/pnpm b/plugins/pnpm/.claude/skills/pnpm
new file mode 120000
index 00000000..c3181c55
--- /dev/null
+++ b/plugins/pnpm/.claude/skills/pnpm
@@ -0,0 +1 @@
+../../.agents/skills/pnpm
\ No newline at end of file
diff --git a/plugins/portless/.agents/skills/portless/SKILL.md b/plugins/portless/.agents/skills/portless/SKILL.md
index c810a582..d386f2ff 100644
--- a/plugins/portless/.agents/skills/portless/SKILL.md
+++ b/plugins/portless/.agents/skills/portless/SKILL.md
@@ -161,37 +161,41 @@ PORTLESS=0 pnpm dev   # Bypasses proxy, uses default port
 2. `portless <name> <cmd>` assigns a random free port (4000-4999) via the `PORT` env var and registers the app with the proxy
 3. The browser hits `https://<name>.localhost`; the proxy forwards to the app's assigned port
 
+Outside LAN mode, the proxy and its HTTP redirect listener bind only to the IPv4 and IPv6 loopback addresses, `127.0.0.1` and `::1`. They do not accept connections through LAN, VPN, or other network interfaces.
+
 `.localhost` domains resolve to `127.0.0.1` natively in Chrome, Firefox, and Edge. Safari relies on the system DNS resolver, which may not handle `.localhost` subdomains on all configurations. Run `portless hosts sync` to add entries to `/etc/hosts` if needed.
 
-Use `portless proxy start --tld localhost --tld test` to serve the same app names under multiple TLDs from one proxy. `PORTLESS_URL` uses the first configured TLD. `PORTLESS_TLD` accepts the same comma separated list format, e.g. `PORTLESS_TLD=localhost,test`.
+Use `portless proxy start --tld localhost --tld test` to serve the same app names under multiple TLDs from one proxy. `PORTLESS_URL` uses the first configured TLD. When configured TLDs overlap (e.g. `example.com` and `dev.example.com`), hostnames are matched against the longest TLD first, regardless of configuration order. `PORTLESS_TLD` accepts the same comma separated list format, e.g. `PORTLESS_TLD=localhost,test`.
+
+TLDs can be multi-segment DNS names such as `dev.example.com`, so local URLs can mirror production structure (`myapp.dev.example.com`). Each label follows DNS rules: lowercase letters, digits, interior hyphens, 63 characters per label, 253 total. Strict OAuth providers that reject `.localhost` redirect URIs accept a real domain like `https://myapp.dev.example.com/api/auth/callback/google`.
 
 Most frameworks (Next.js, Express, Nuxt, etc.) respect the `PORT` env var automatically. For frameworks that ignore `PORT` (Vite, VitePlus, Astro, React Router, Angular, Expo, React Native), portless auto-injects the correct `--port` flag and, when needed, a matching `--host` CLI flag.
 
 ### State directory
 
-Portless stores its state (routes, PID file, port file) in `~/.portless`. Override with the `PORTLESS_STATE_DIR` environment variable.
+Portless stores its state (routes, PID file, port file) in `~/.portless`. When the proxy runs under sudo, this remains the invoking user's home directory so unprivileged apps and the proxy share route registrations. Override with the `PORTLESS_STATE_DIR` environment variable.
 
 ### Environment variables
 
-| Variable              | Description                                                                 |
-| --------------------- | --------------------------------------------------------------------------- |
-| `PORTLESS_PORT`       | Override the default proxy port (default: 443 with HTTPS, 80 without)       |
-| `PORTLESS_APP_PORT`   | Use a fixed port for the app (skip auto-assignment)                         |
-| `PORTLESS_HTTPS`      | HTTPS on by default; set to `0` to disable (same as `--no-tls`)             |
-| `PORTLESS_LAN`        | Set to `1` to always enable LAN mode (auto-detects LAN IP)                  |
-| `PORTLESS_LAN_IP`     | Pin a specific LAN IP for LAN mode                                          |
-| `PORTLESS_TLD`        | Use one or more TLDs (e.g. localhost,test)                                  |
-| `PORTLESS_WILDCARD`   | Set to `1` to allow unregistered subdomains to fall back to parent          |
-| `PORTLESS_SYNC_HOSTS` | Set to `0` to disable auto-sync of /etc/hosts (on by default)               |
-| `PORTLESS_TAILSCALE`  | Set to `1` to share apps on your Tailscale network (same as `--tailscale`)  |
-| `PORTLESS_FUNNEL`     | Set to `1` to share apps publicly via Tailscale Funnel (same as `--funnel`) |
-| `PORTLESS_NGROK`      | Set to `1` to share apps publicly via ngrok (same as `--ngrok`)             |
-| `PORTLESS_STATE_DIR`  | Override the state directory                                                |
-| `PORTLESS=0`          | Bypass the proxy, run the command directly                                  |
+| Variable              | Description                                                                    |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `PORTLESS_PORT`       | Override the default proxy port (default: 443 with HTTPS, 80 without)          |
+| `PORTLESS_APP_PORT`   | Use a fixed port for the app (skip auto-assignment)                            |
+| `PORTLESS_HTTPS`      | HTTPS on by default; set to `0` to disable (same as `--no-tls`)                |
+| `PORTLESS_LAN`        | Set to `1` to always enable LAN mode (auto-detects LAN IP)                     |
+| `PORTLESS_LAN_IP`     | Pin a specific LAN IP for LAN mode                                             |
+| `PORTLESS_TLD`        | Use one or more TLDs, single or multi-segment (e.g. localhost,dev.example.com) |
+| `PORTLESS_WILDCARD`   | Set to `1` to allow unregistered subdomains to fall back to parent             |
+| `PORTLESS_SYNC_HOSTS` | Set to `0` to disable auto-sync of /etc/hosts (on by default)                  |
+| `PORTLESS_TAILSCALE`  | Set to `1` to share apps on your Tailscale network (same as `--tailscale`)     |
+| `PORTLESS_FUNNEL`     | Set to `1` to share apps publicly via Tailscale Funnel (same as `--funnel`)    |
+| `PORTLESS_NGROK`      | Set to `1` to share apps publicly via ngrok (same as `--ngrok`)                |
+| `PORTLESS_STATE_DIR`  | Override the state directory                                                   |
+| `PORTLESS=0`          | Bypass the proxy, run the command directly                                     |
 
 ### HTTP/2 + HTTPS
 
-HTTPS with HTTP/2 is enabled by default (faster page loads for dev servers with many files). First run generates a local CA and adds it to the system trust store. After that, no prompts and no browser warnings.
+HTTPS with HTTP/2 is enabled by default (faster page loads for dev servers with many files). WebSockets work over both HTTP/1.1 (Upgrade) and HTTP/2 (RFC 8441 extended CONNECT), so dev server HMR works through the proxy. First run generates a local CA and adds it to the system trust store. After that, no prompts and no browser warnings.
 
 ```bash
 portless proxy start --cert ./c.pem --key ./k.pem  # Use custom certs
@@ -199,7 +203,7 @@ portless proxy start --no-tls                       # Disable HTTPS (plain HTTP)
 portless trust                                      # Add CA to trust store later
 ```
 
-On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). On Windows, it uses `certutil` to add the CA to the system trust store.
+On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). On Windows, it uses `certutil` to add the CA to the system trust store. On WSL, it updates both the Linux trust store and the Windows current-user Root store so Windows browsers trust portless HTTPS certificates.
 
 ### LAN mode
 
@@ -209,7 +213,7 @@ portless proxy start --lan --https
 portless proxy start --lan --ip 192.168.1.42
 ```
 
-`--lan` advertises `<name>.local` hostnames over mDNS so any device on the same Wi-Fi can reach your apps. Portless auto-detects your LAN IP and follows network changes automatically, but you can pin a specific address with `--ip <address>` or the `PORTLESS_LAN_IP` environment variable. Set `PORTLESS_LAN=1` to default to LAN mode every time the proxy starts.
+`--lan` explicitly binds the proxy to the IPv4 and IPv6 unspecified addresses, `0.0.0.0` and `::`, and advertises `<name>.local` hostnames over mDNS so devices on the same Wi-Fi can reach your apps. Portless auto-detects your LAN IP and follows network changes automatically, but you can pin a specific address with `--ip <address>` or the `PORTLESS_LAN_IP` environment variable. Set `PORTLESS_LAN=1` to default to LAN mode every time the proxy starts.
 
 Portless remembers LAN mode via `proxy.lan`, so if you stop a LAN proxy and start again, it stays in LAN mode. All proxy settings (port, TLS, TLDs, LAN) are persisted and reused on auto-start unless overridden by explicit flags or env vars. Use `PORTLESS_LAN=0` for one start to switch back to `.localhost` mode. If a proxy is already running with different explicit LAN/TLS/TLD settings, portless warns and asks you to stop it first.
 
@@ -297,6 +301,7 @@ The chosen service configuration is written into launchd, systemd, or Task Sched
 | `portless proxy start -p <number>`                | Start the proxy on a custom port                               |
 | `portless proxy start --tld test`                 | Use .test instead of .localhost                                |
 | `portless proxy start --tld localhost --tld test` | Serve both TLDs from one proxy                                 |
+| `portless proxy start --tld dev.example.com`      | Use a multi-segment TLD for production-parity URLs             |
 | `portless proxy start --foreground`               | Start the proxy in foreground (for debugging)                  |
 | `portless proxy start --wildcard`                 | Allow unregistered subdomains to fall back to parent route     |
 | `portless proxy stop`                             | Stop the proxy                                                 |
@@ -424,7 +429,7 @@ This adds the portless local CA to your system trust store. After that, restart
 portless clean
 ```
 
-Stops the proxy if needed, removes the portless CA from the trust store (when portless added it), deletes known files under state directories, and removes the portless `/etc/hosts` block. May require `sudo` on macOS/Linux.
+Stops the proxy if needed, removes the portless CA from the trust store (when portless added it), deletes known files under state directories, and removes the portless `/etc/hosts` block. May require `sudo` on macOS/Linux. If trust-store removal fails, portless retains its CA certificate and key so a later `portless clean` can safely retry.
 
 ### Proxy loop (508 Loop Detected)
 
diff --git a/plugins/portless/.claude/skills/portless b/plugins/portless/.claude/skills/portless
new file mode 120000
index 00000000..240f102d
--- /dev/null
+++ b/plugins/portless/.claude/skills/portless
@@ -0,0 +1 @@
+../../.agents/skills/portless
\ No newline at end of file
diff --git a/plugins/portless/agent/skills/portless/SKILL.md b/plugins/portless/agent/skills/portless/SKILL.md
index 0f5df541..3b9f2302 100644
--- a/plugins/portless/agent/skills/portless/SKILL.md
+++ b/plugins/portless/agent/skills/portless/SKILL.md
@@ -159,37 +159,41 @@ PORTLESS=0 pnpm dev   # Bypasses proxy, uses default port
 2. `portless <name> <cmd>` assigns a random free port (4000-4999) via the `PORT` env var and registers the app with the proxy
 3. The browser hits `https://<name>.localhost`; the proxy forwards to the app's assigned port
 
+Outside LAN mode, the proxy and its HTTP redirect listener bind only to the IPv4 and IPv6 loopback addresses, `127.0.0.1` and `::1`. They do not accept connections through LAN, VPN, or other network interfaces.
+
 `.localhost` domains resolve to `127.0.0.1` natively in Chrome, Firefox, and Edge. Safari relies on the system DNS resolver, which may not handle `.localhost` subdomains on all configurations. Run `portless hosts sync` to add entries to `/etc/hosts` if needed.
 
-Use `portless proxy start --tld localhost --tld test` to serve the same app names under multiple TLDs from one proxy. `PORTLESS_URL` uses the first configured TLD. `PORTLESS_TLD` accepts the same comma separated list format, e.g. `PORTLESS_TLD=localhost,test`.
+Use `portless proxy start --tld localhost --tld test` to serve the same app names under multiple TLDs from one proxy. `PORTLESS_URL` uses the first configured TLD. When configured TLDs overlap (e.g. `example.com` and `dev.example.com`), hostnames are matched against the longest TLD first, regardless of configuration order. `PORTLESS_TLD` accepts the same comma separated list format, e.g. `PORTLESS_TLD=localhost,test`.
+
+TLDs can be multi-segment DNS names such as `dev.example.com`, so local URLs can mirror production structure (`myapp.dev.example.com`). Each label follows DNS rules: lowercase letters, digits, interior hyphens, 63 characters per label, 253 total. Strict OAuth providers that reject `.localhost` redirect URIs accept a real domain like `https://myapp.dev.example.com/api/auth/callback/google`.
 
 Most frameworks (Next.js, Express, Nuxt, etc.) respect the `PORT` env var automatically. For frameworks that ignore `PORT` (Vite, VitePlus, Astro, React Router, Angular, Expo, React Native), portless auto-injects the correct `--port` flag and, when needed, a matching `--host` CLI flag.
 
 ### State directory
 
-Portless stores its state (routes, PID file, port file) in `~/.portless`. Override with the `PORTLESS_STATE_DIR` environment variable.
+Portless stores its state (routes, PID file, port file) in `~/.portless`. When the proxy runs under sudo, this remains the invoking user's home directory so unprivileged apps and the proxy share route registrations. Override with the `PORTLESS_STATE_DIR` environment variable.
 
 ### Environment variables
 
-| Variable              | Description                                                                 |
-| --------------------- | --------------------------------------------------------------------------- |
-| `PORTLESS_PORT`       | Override the default proxy port (default: 443 with HTTPS, 80 without)       |
-| `PORTLESS_APP_PORT`   | Use a fixed port for the app (skip auto-assignment)                         |
-| `PORTLESS_HTTPS`      | HTTPS on by default; set to `0` to disable (same as `--no-tls`)             |
-| `PORTLESS_LAN`        | Set to `1` to always enable LAN mode (auto-detects LAN IP)                  |
-| `PORTLESS_LAN_IP`     | Pin a specific LAN IP for LAN mode                                          |
-| `PORTLESS_TLD`        | Use one or more TLDs (e.g. localhost,test)                                  |
-| `PORTLESS_WILDCARD`   | Set to `1` to allow unregistered subdomains to fall back to parent          |
-| `PORTLESS_SYNC_HOSTS` | Set to `0` to disable auto-sync of /etc/hosts (on by default)               |
-| `PORTLESS_TAILSCALE`  | Set to `1` to share apps on your Tailscale network (same as `--tailscale`)  |
-| `PORTLESS_FUNNEL`     | Set to `1` to share apps publicly via Tailscale Funnel (same as `--funnel`) |
-| `PORTLESS_NGROK`      | Set to `1` to share apps publicly via ngrok (same as `--ngrok`)             |
-| `PORTLESS_STATE_DIR`  | Override the state directory                                                |
-| `PORTLESS=0`          | Bypass the proxy, run the command directly                                  |
+| Variable              | Description                                                                    |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `PORTLESS_PORT`       | Override the default proxy port (default: 443 with HTTPS, 80 without)          |
+| `PORTLESS_APP_PORT`   | Use a fixed port for the app (skip auto-assignment)                            |
+| `PORTLESS_HTTPS`      | HTTPS on by default; set to `0` to disable (same as `--no-tls`)                |
+| `PORTLESS_LAN`        | Set to `1` to always enable LAN mode (auto-detects LAN IP)                     |
+| `PORTLESS_LAN_IP`     | Pin a specific LAN IP for LAN mode                                             |
+| `PORTLESS_TLD`        | Use one or more TLDs, single or multi-segment (e.g. localhost,dev.example.com) |
+| `PORTLESS_WILDCARD`   | Set to `1` to allow unregistered subdomains to fall back to parent             |
+| `PORTLESS_SYNC_HOSTS` | Set to `0` to disable auto-sync of /etc/hosts (on by default)                  |
+| `PORTLESS_TAILSCALE`  | Set to `1` to share apps on your Tailscale network (same as `--tailscale`)     |
+| `PORTLESS_FUNNEL`     | Set to `1` to share apps publicly via Tailscale Funnel (same as `--funnel`)    |
+| `PORTLESS_NGROK`      | Set to `1` to share apps publicly via ngrok (same as `--ngrok`)                |
+| `PORTLESS_STATE_DIR`  | Override the state directory                                                   |
+| `PORTLESS=0`          | Bypass the proxy, run the command directly                                     |
 
 ### HTTP/2 + HTTPS
 
-HTTPS with HTTP/2 is enabled by default (faster page loads for dev servers with many files). First run generates a local CA and adds it to the system trust store. After that, no prompts and no browser warnings.
+HTTPS with HTTP/2 is enabled by default (faster page loads for dev servers with many files). WebSockets work over both HTTP/1.1 (Upgrade) and HTTP/2 (RFC 8441 extended CONNECT), so dev server HMR works through the proxy. First run generates a local CA and adds it to the system trust store. After that, no prompts and no browser warnings.
 
 ```bash
 portless proxy start --cert ./c.pem --key ./k.pem  # Use custom certs
@@ -197,7 +201,7 @@ portless proxy start --no-tls                       # Disable HTTPS (plain HTTP)
 portless trust                                      # Add CA to trust store later
 ```
 
-On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). On Windows, it uses `certutil` to add the CA to the system trust store.
+On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). On Windows, it uses `certutil` to add the CA to the system trust store. On WSL, it updates both the Linux trust store and the Windows current-user Root store so Windows browsers trust portless HTTPS certificates.
 
 ### LAN mode
 
@@ -207,7 +211,7 @@ portless proxy start --lan --https
 portless proxy start --lan --ip 192.168.1.42
 ```
 
-`--lan` advertises `<name>.local` hostnames over mDNS so any device on the same Wi-Fi can reach your apps. Portless auto-detects your LAN IP and follows network changes automatically, but you can pin a specific address with `--ip <address>` or the `PORTLESS_LAN_IP` environment variable. Set `PORTLESS_LAN=1` to default to LAN mode every time the proxy starts.
+`--lan` explicitly binds the proxy to the IPv4 and IPv6 unspecified addresses, `0.0.0.0` and `::`, and advertises `<name>.local` hostnames over mDNS so devices on the same Wi-Fi can reach your apps. Portless auto-detects your LAN IP and follows network changes automatically, but you can pin a specific address with `--ip <address>` or the `PORTLESS_LAN_IP` environment variable. Set `PORTLESS_LAN=1` to default to LAN mode every time the proxy starts.
 
 Portless remembers LAN mode via `proxy.lan`, so if you stop a LAN proxy and start again, it stays in LAN mode. All proxy settings (port, TLS, TLDs, LAN) are persisted and reused on auto-start unless overridden by explicit flags or env vars. Use `PORTLESS_LAN=0` for one start to switch back to `.localhost` mode. If a proxy is already running with different explicit LAN/TLS/TLD settings, portless warns and asks you to stop it first.
 
@@ -295,6 +299,7 @@ The chosen service configuration is written into launchd, systemd, or Task Sched
 | `portless proxy start -p <number>`                | Start the proxy on a custom port                               |
 | `portless proxy start --tld test`                 | Use .test instead of .localhost                                |
 | `portless proxy start --tld localhost --tld test` | Serve both TLDs from one proxy                                 |
+| `portless proxy start --tld dev.example.com`      | Use a multi-segment TLD for production-parity URLs             |
 | `portless proxy start --foreground`               | Start the proxy in foreground (for debugging)                  |
 | `portless proxy start --wildcard`                 | Allow unregistered subdomains to fall back to parent route     |
 | `portless proxy stop`                             | Stop the proxy                                                 |
@@ -422,7 +427,7 @@ This adds the portless local CA to your system trust store. After that, restart
 portless clean
 ```
 
-Stops the proxy if needed, removes the portless CA from the trust store (when portless added it), deletes known files under state directories, and removes the portless `/etc/hosts` block. May require `sudo` on macOS/Linux.
+Stops the proxy if needed, removes the portless CA from the trust store (when portless added it), deletes known files under state directories, and removes the portless `/etc/hosts` block. May require `sudo` on macOS/Linux. If trust-store removal fails, portless retains its CA certificate and key so a later `portless clean` can safely retry.
 
 ### Proxy loop (508 Loop Detected)
 
diff --git a/plugins/portless/skills-lock.json b/plugins/portless/skills-lock.json
index 8a58bfcf..583f677b 100644
--- a/plugins/portless/skills-lock.json
+++ b/plugins/portless/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel-labs/portless",
       "sourceType": "github",
       "skillPath": "skills/portless/SKILL.md",
-      "computedHash": "5f707167fa4e23761d1c74dc176649fbb2169dea0890c035e8ad72cbfdc0d56b"
+      "computedHash": "5b758ea66233a1ebd494554904db55d902f5ea8832c353188d771f5c6fed9d2b"
     }
   }
 }
diff --git a/plugins/prisma/.agents/skills/prisma-cli/SKILL.md b/plugins/prisma/.agents/skills/prisma-cli/SKILL.md
index 17595be1..b2b770ef 100644
--- a/plugins/prisma/.agents/skills/prisma-cli/SKILL.md
+++ b/plugins/prisma/.agents/skills/prisma-cli/SKILL.md
@@ -1,19 +1,19 @@
 ---
 name: prisma-cli
-description: Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, studio, validate, format, debug, and mcp. Use for ORM/database CLI workflows, not Prisma Compute app deployment. For Prisma Compute, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, apps, deployments, logs, or domains, use the `prisma-compute` skill instead. Triggers on "prisma init", "prisma generate", "prisma migrate", "prisma db", "prisma studio", "prisma mcp".
+description: Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, complete, studio, validate, format, debug, and mcp. Use for ORM/database CLI workflows, not the Prisma Platform CLI. Triggers on "prisma init", "prisma generate", "prisma migrate", "prisma db", "prisma complete", "prisma studio", "prisma mcp".
 license: MIT
 metadata:
   author: prisma
-  version: "7.6.0"
+  version: "7.9.1"
 ---
 
 # Prisma CLI Reference
 
 Reference for Prisma ORM CLI commands. This skill provides guidance on command usage, options, and best practices for current Prisma ORM releases.
 
-## Boundary: Compute
+## Boundary: Platform and Compute
 
-Do not use this skill for Prisma Compute app deployment. Use `prisma-compute` for `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, Compute apps, deployments, logs, domains, and framework deploy readiness.
+Do not confuse the stable ORM command (`prisma`) with the public-beta Platform package (`@prisma/cli`, binary `prisma-cli`). Use `prisma-compute` for Compute apps and workspace auth, and `prisma-postgres` for Platform projects and databases.
 
 ## When to Apply
 
@@ -24,6 +24,7 @@ Reference this skill when:
 - Managing database state (`prisma db push/pull`)
 - Using local development database (`prisma dev`)
 - Debugging Prisma issues (`prisma debug`)
+- Generating shell completions (`prisma complete`)
 
 ## Rule Categories by Priority
 
@@ -34,19 +35,19 @@ Reference this skill when:
 | 3 | Development | HIGH | `dev` |
 | 4 | Database | HIGH | `db-` |
 | 5 | Migrations | CRITICAL | `migrate-` |
-| 6 | Utility | MEDIUM | `studio`, `validate`, `format`, `debug`, `mcp` |
+| 6 | Utility | MEDIUM | `complete`, `studio`, `validate`, `format`, `debug`, `mcp` |
 
 ## Command Categories
 
 | Category | Commands | Purpose |
 |----------|----------|---------|
-| Setup | `init` | Bootstrap new Prisma project |
+| Setup | `init` | Initialize a Prisma project |
 | Generation | `generate` | Generate Prisma Client |
 | Validation | `validate`, `format` | Schema validation and formatting |
 | Development | `dev` | Local Prisma Postgres for development |
 | Database | `db pull`, `db push`, `db seed`, `db execute` | Direct database operations |
 | Migrations | `migrate dev`, `migrate deploy`, `migrate reset`, `migrate status`, `migrate diff`, `migrate resolve` | Schema migrations |
-| Utility | `studio`, `mcp`, `version`, `debug` | Development and AI tooling |
+| Utility | `complete`, `studio`, `mcp`, `version`, `debug` | Shell, development, and AI tooling |
 
 ## Quick Reference
 
@@ -66,6 +67,7 @@ prisma init --db
 
 # Initialize with an example model
 prisma init --with-model
+
 ```
 
 ### Client Generation
@@ -178,8 +180,22 @@ prisma validate
 
 # Format schema
 prisma format
+
+# Generate shell completion code
+prisma complete zsh
 ```
 
+## AI Safety Checkpoint
+
+Prisma blocks destructive commands when it detects an AI agent until the agent has obtained explicit user consent. This covers `migrate reset`, `db push --force-reset`, and `db push --accept-data-loss`.
+
+- Explain the exact data-loss impact and ask for consent immediately before running the command.
+- Do not infer consent from earlier or unrelated messages.
+- If automation needs the consent variable, set `PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION` to the user's exact consent message. Do not invent the text.
+- The Prisma MCP server deliberately has no `migrate-reset` tool.
+
+Read `references/agent-safety.md` before any destructive Prisma command.
+
 ## Current Prisma CLI Setup
 
 ### New Configuration File
@@ -237,6 +253,8 @@ references/migrate-resolve.md - Migration resolution
 references/migrate-diff.md   - Schema diffing
 references/studio.md         - Database GUI
 references/mcp.md            - Prisma MCP server
+references/complete.md       - Shell completion generation
+references/agent-safety.md   - AI consent checkpoint for destructive commands
 references/validate.md       - Schema validation
 references/format.md         - Schema formatting
 references/debug.md          - Debug info
diff --git a/plugins/prisma/.agents/skills/prisma-cli/references/agent-safety.md b/plugins/prisma/.agents/skills/prisma-cli/references/agent-safety.md
new file mode 100644
index 00000000..651c6c34
--- /dev/null
+++ b/plugins/prisma/.agents/skills/prisma-cli/references/agent-safety.md
@@ -0,0 +1,27 @@
+# AI safety checkpoint for destructive commands
+
+Prisma detects common AI-agent environments and blocks these commands until the user gives explicit consent:
+
+- `prisma migrate reset`
+- `prisma db push --force-reset`
+- `prisma db push --accept-data-loss`
+
+## Required workflow
+
+1. Inspect the target database/config and explain exactly what can be deleted or reset.
+2. Ask the user for explicit consent immediately before the action.
+3. Run the command only after that consent.
+
+For an agent-run subprocess, Prisma accepts the exact consent text through:
+
+```bash
+PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION='<exact user consent message>' prisma migrate reset --force
+```
+
+The value must match the user's message exactly and must not contain added quotes or newlines. Never fabricate consent, reuse an old unrelated approval, or bypass the checkpoint by hiding agent-detection environment variables.
+
+The MCP server has no `migrate-reset` tool. Use the shell command only after consent.
+
+## Reference
+
+- [Prisma ORM 7.9.0 release](https://github.com/prisma/prisma/releases/tag/7.9.0)
diff --git a/plugins/prisma/.agents/skills/prisma-cli/references/complete.md b/plugins/prisma/.agents/skills/prisma-cli/references/complete.md
new file mode 100644
index 00000000..73324407
--- /dev/null
+++ b/plugins/prisma/.agents/skills/prisma-cli/references/complete.md
@@ -0,0 +1,22 @@
+# prisma complete
+
+Prints a shell completion script.
+
+```bash
+prisma complete zsh
+prisma complete bash
+prisma complete fish
+prisma complete powershell
+```
+
+For a direct global CLI installation, load the output using the shell's normal startup mechanism. For example, in zsh:
+
+```bash
+source <(prisma complete zsh)
+```
+
+Prisma also integrates with supported package-manager completion flows. `npx` and `bunx` do not themselves provide completion; invoke the installed binary or the package manager's supported execution form such as `npm exec` or `bun x`.
+
+## Reference
+
+- [Prisma ORM 7.9.0 release](https://github.com/prisma/prisma/releases/tag/7.9.0)
diff --git a/plugins/prisma/.agents/skills/prisma-cli/references/db-push.md b/plugins/prisma/.agents/skills/prisma-cli/references/db-push.md
index 51acdbb2..74da0cf4 100644
--- a/plugins/prisma/.agents/skills/prisma-cli/references/db-push.md
+++ b/plugins/prisma/.agents/skills/prisma-cli/references/db-push.md
@@ -25,6 +25,8 @@ prisma db push [options]
 | `--config` | Custom path to your Prisma config file |
 | `--url` | Override the datasource URL from the Prisma config file |
 
+When Prisma detects an AI agent, `--force-reset` and `--accept-data-loss` require explicit user consent. Follow `agent-safety.md`; never infer or fabricate the consent text.
+
 ### Follow-up Command
 
 - Run `prisma generate` explicitly when you need refreshed client output
diff --git a/plugins/prisma/.agents/skills/prisma-cli/references/init.md b/plugins/prisma/.agents/skills/prisma-cli/references/init.md
index a255c7b5..c4390ed8 100644
--- a/plugins/prisma/.agents/skills/prisma-cli/references/init.md
+++ b/plugins/prisma/.agents/skills/prisma-cli/references/init.md
@@ -34,6 +34,9 @@ bunx --bun prisma init
 | `--output` | Define Prisma Client generator output path to use | - |
 | `--preview-feature` | Define a preview feature to use | - |
 | `--with-model` | Add example model to created schema file | - |
+| `--no-skills` | Skip the best-effort installation of Prisma agent skills | - |
+
+`prisma init` attempts to install `prisma/skills` for detected agents. This is best-effort and does not make project initialization fail. Use `--no-skills` in minimal or controlled environments.
 
 ## Examples
 
diff --git a/plugins/prisma/.agents/skills/prisma-cli/references/mcp.md b/plugins/prisma/.agents/skills/prisma-cli/references/mcp.md
index 26cb963f..284130fa 100644
--- a/plugins/prisma/.agents/skills/prisma-cli/references/mcp.md
+++ b/plugins/prisma/.agents/skills/prisma-cli/references/mcp.md
@@ -30,7 +30,8 @@ prisma mcp
 
 - Run this from the project that contains your Prisma schema and `prisma.config.ts`
 - The command is separate from Prisma Studio and does not open a browser UI
-- The MCP server wraps Prisma CLI commands. For exact behavior of commands like `migrate dev` or `migrate reset`, follow the underlying CLI command docs rather than relying only on the MCP tool descriptions.
+- The MCP server exposes `migrate-status`, `migrate-dev`, and Prisma Studio tooling. It does not expose the destructive `migrate-reset` tool; do not claim it is available or try to bypass that safety boundary.
+- For destructive shell commands, follow `agent-safety.md` and obtain explicit user consent.
 
 ## References
 
diff --git a/plugins/prisma/.agents/skills/prisma-cli/references/migrate-dev.md b/plugins/prisma/.agents/skills/prisma-cli/references/migrate-dev.md
index 6b6352b4..48643b64 100644
--- a/plugins/prisma/.agents/skills/prisma-cli/references/migrate-dev.md
+++ b/plugins/prisma/.agents/skills/prisma-cli/references/migrate-dev.md
@@ -31,7 +31,7 @@ prisma migrate dev [options]
 - Run `prisma generate` explicitly when you need refreshed client output
 - Run `prisma db seed` explicitly when you need seed data
 
-Note: Prisma CLI help for `7.6.0` still says `migrate dev` "trigger[s] generators", but local verification in a temp Prisma 7.6.0 project did not emit generated client files. Treat `prisma generate` as an explicit follow-up step when you need generated artifacts on disk.
+Run `prisma generate` as an explicit follow-up when you need refreshed generated artifacts. Do not rely on historical CLI help that described generators as part of `migrate dev`.
 
 ## Examples
 
diff --git a/plugins/prisma/.agents/skills/prisma-cli/references/migrate-reset.md b/plugins/prisma/.agents/skills/prisma-cli/references/migrate-reset.md
index 38d6fbdc..900e2885 100644
--- a/plugins/prisma/.agents/skills/prisma-cli/references/migrate-reset.md
+++ b/plugins/prisma/.agents/skills/prisma-cli/references/migrate-reset.md
@@ -17,6 +17,8 @@ prisma migrate reset [options]
 
 **Warning: All data will be lost.**
 
+When Prisma detects an AI agent, this command is blocked until the user gives explicit consent. Follow `agent-safety.md`; `--force` skips the ordinary prompt but does not constitute user consent for an agent.
+
 ## Options
 
 | Option | Description |
diff --git a/plugins/prisma/.agents/skills/prisma-client-api/SKILL.md b/plugins/prisma/.agents/skills/prisma-client-api/SKILL.md
index 8325eeac..57aa8a52 100644
--- a/plugins/prisma/.agents/skills/prisma-client-api/SKILL.md
+++ b/plugins/prisma/.agents/skills/prisma-client-api/SKILL.md
@@ -4,7 +4,7 @@ description: Prisma Client API reference covering model queries, filters, operat
 license: MIT
 metadata:
   author: prisma
-  version: "7.6.0"
+  version: "7.9.1"
 ---
 
 # Prisma Client API Reference
diff --git a/plugins/prisma/.agents/skills/prisma-client-api/references/constructor.md b/plugins/prisma/.agents/skills/prisma-client-api/references/constructor.md
index 7c7825f3..a9fb5e8f 100644
--- a/plugins/prisma/.agents/skills/prisma-client-api/references/constructor.md
+++ b/plugins/prisma/.agents/skills/prisma-client-api/references/constructor.md
@@ -127,6 +127,19 @@ const prisma = new PrismaClient({
 })
 ```
 
+### queryPlanCacheMaxSize
+
+Use `queryPlanCacheMaxSize` to limit the in-memory query-plan cache:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  queryPlanCacheMaxSize: 2_000,
+})
+```
+
+The value must be a non-negative integer. Set it to `0` to disable query-plan caching; omit it to use Prisma's default. Treat this as a process-local memory/performance control, not a database prepared-statement setting.
+
 ## Singleton Pattern
 
 Prevent multiple client instances in development:
diff --git a/plugins/prisma/.agents/skills/prisma-client-api/references/raw-queries.md b/plugins/prisma/.agents/skills/prisma-client-api/references/raw-queries.md
index 5d3a220b..e444ce2f 100644
--- a/plugins/prisma/.agents/skills/prisma-client-api/references/raw-queries.md
+++ b/plugins/prisma/.agents/skills/prisma-client-api/references/raw-queries.md
@@ -192,3 +192,7 @@ const users = await prisma.$queryRaw<Result[]>`
 `
 // createdAt is already a Date object
 ```
+
+Invalid JavaScript `Date` values passed to raw queries fail validation instead of being silently serialized as `null`. Validate date input at the application boundary; do not rely on `new Date(badValue)` reaching the database.
+
+When a driver adapter returns an unmapped database-specific error, Prisma surfaces `P2039` with the adapter's preserved original code/message. If those details are missing, fix the adapter mapping rather than parsing rendered error text.
diff --git a/plugins/prisma/.agents/skills/prisma-database-setup/SKILL.md b/plugins/prisma/.agents/skills/prisma-database-setup/SKILL.md
index 1de91a64..51643e74 100644
--- a/plugins/prisma/.agents/skills/prisma-database-setup/SKILL.md
+++ b/plugins/prisma/.agents/skills/prisma-database-setup/SKILL.md
@@ -170,7 +170,7 @@ generator client {
 }
 ```
 
-For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup.
+For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup. If a MongoDB project asks about upgrading Prisma versions, route to the `prisma-mongodb-upgrade` skill (stay-on-v6 vs Prisma Next is the real decision; Prisma 7 is not an option).
 
 ## Rule Files
 
diff --git a/plugins/prisma/.agents/skills/prisma-driver-adapter-implementation/SKILL.md b/plugins/prisma/.agents/skills/prisma-driver-adapter-implementation/SKILL.md
index 12d3dae5..4bf3479c 100644
--- a/plugins/prisma/.agents/skills/prisma-driver-adapter-implementation/SKILL.md
+++ b/plugins/prisma/.agents/skills/prisma-driver-adapter-implementation/SKILL.md
@@ -1,638 +1,270 @@
 ---
 name: prisma-driver-adapter-implementation
-description: Required reference for Prisma v7 driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter/Transaction interfaces. Contains critical contract details not inferable from code examples — including the transaction lifecycle protocol, error mapping requirements, and verification checklist. Existing implementations do not replace this skill.
+description: Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.
 license: MIT
 metadata:
-  author: Tyler Benfield
-  version: "7.6.0"
+  author: prisma
+  version: "7.9.1"
 ---
 
-# Prisma 7 Driver Adapter Implementation Guide
+# Prisma SQL Driver Adapter Implementation
 
-This skill provides everything needed to implement a Prisma ORM v7 driver adapter for any database.
+Use this guide with the exact `@prisma/driver-adapter-utils` version installed by the target Prisma release. Driver adapters are a protocol boundary: type-compatible code can still corrupt values, leak connections, or break transactions.
 
-## Architecture Overview
+## When to Apply
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         PrismaClient                            │
-│                    (requires adapter factory)                   │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│            SqlMigrationAwareDriverAdapterFactory                │
-│   ┌─────────────────────┐    ┌─────────────────────────────┐    │
-│   │ connect()           │    │ connectToShadowDb()         │    │
-│   │ → SqlDriverAdapter  │    │ → SqlDriverAdapter          │    │
-│   └─────────────────────┘    └─────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                      SqlDriverAdapter                           │
-│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
-│  │ queryRaw()   │ │ executeRaw() │ │ startTransaction()       │ │
-│  │ → ResultSet  │ │ → number     │ │ → Transaction            │ │
-│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
-│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
-│  │executeScript │ │ dispose()    │ │ getConnectionInfo()      │ │
-│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                        Transaction                              │
-│  Extends SqlQueryable + commit() + rollback() + options         │
-│  (lifecycle hooks only — Prisma sends SQL via executeRaw)       │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Required Interfaces
+- Implementing `SqlDriverAdapterFactory`, `SqlMigrationAwareDriverAdapterFactory`, `SqlDriverAdapter`, or `Transaction`
+- Adding nested-transaction/savepoint support
+- Mapping driver values, column metadata, bind arguments, or database errors
+- Debugging `P2039`, transaction leaks, shadow-database failures, or adapter-specific query behavior
 
-Import from `@prisma/driver-adapter-utils`:
+## Contract snapshot
 
 ```typescript
-import type {
-  ColumnType,
-  IsolationLevel,
-  SqlDriverAdapter,
-  SqlMigrationAwareDriverAdapterFactory,
-  SqlQuery,
-  SqlQueryable,
-  SqlResultSet,
-  Transaction,
-  TransactionOptions,
-  ArgType,
-  ConnectionInfo,
-  MappedError,
-} from "@prisma/driver-adapter-utils";
-import {
-  ColumnTypeEnum,
-  DriverAdapterError,
-} from "@prisma/driver-adapter-utils";
-```
-
-## Interface Definitions
-
-### SqlQuery (input to queryRaw/executeRaw)
-
-```typescript
-type SqlQuery = {
-  sql: string; // Parameterized SQL with placeholders
-  args: Array<unknown>; // Bound parameter values
-  argTypes: Array<ArgType>; // Type hints for each argument
-};
-
-type ArgType = {
-  scalarType: ArgScalarType; // 'string' | 'int' | 'bigint' | 'float' | 'decimal' | 'boolean' | 'enum' | 'uuid' | 'json' | 'datetime' | 'bytes' | 'unknown'
-  dbType?: string;
-  arity: "scalar" | "list";
-};
-```
-
-### SqlResultSet (output from queryRaw)
-
-```typescript
-interface SqlResultSet {
-  columnNames: Array<string>; // Column names in order
-  columnTypes: Array<ColumnType>; // Column types matching columnNames
-  rows: Array<Array<unknown>>; // Row data as arrays
-  lastInsertId?: string; // For INSERT without RETURNING
+interface SqlDriverAdapterFactory extends AdapterInfo {
+  connect(): Promise<SqlDriverAdapter>
 }
-```
-
-### ColumnTypeEnum values
-
-```typescript
-const ColumnTypeEnum = {
-  Int32: 0,
-  Int64: 1,
-  Float: 2,
-  Double: 3,
-  Numeric: 4,
-  Boolean: 5,
-  Character: 6,
-  Text: 7,
-  Date: 8,
-  Time: 9,
-  DateTime: 10,
-  Json: 11,
-  Enum: 12,
-  Bytes: 13,
-  Set: 14,
-  Uuid: 15,
-  Int32Array: 64,
-  Int64Array: 65,
-  FloatArray: 66,
-  DoubleArray: 67,
-  NumericArray: 68,
-  BooleanArray: 69,
-  CharacterArray: 70,
-  TextArray: 71,
-  DateArray: 72,
-  TimeArray: 73,
-  DateTimeArray: 74,
-  JsonArray: 75,
-  EnumArray: 76,
-  BytesArray: 77,
-  UuidArray: 78,
-  UnknownNumber: 128,
-} as const;
-```
-
-### SqlDriverAdapter
 
-```typescript
-interface SqlDriverAdapter extends SqlQueryable {
-  executeScript(script: string): Promise<void>;
-  startTransaction(isolationLevel?: IsolationLevel): Promise<Transaction>;
-  getConnectionInfo?(): ConnectionInfo;
-  dispose(): Promise<void>;
+interface SqlMigrationAwareDriverAdapterFactory extends SqlDriverAdapterFactory {
+  connectToShadowDb(): Promise<SqlDriverAdapter>
 }
-```
 
-### Transaction
-
-```typescript
-interface Transaction extends SqlQueryable {
-  readonly options: TransactionOptions;
-  commit(): Promise<void>;
-  rollback(): Promise<void>;
+interface SqlDriverAdapter extends AdapterInfo {
+  queryRaw(query: SqlQuery): Promise<SqlResultSet>
+  executeRaw(query: SqlQuery): Promise<number>
+  executeScript(script: string): Promise<void>
+  startTransaction(isolationLevel?: IsolationLevel): Promise<Transaction>
+  getConnectionInfo?(): ConnectionInfo
+  dispose(): Promise<void>
 }
 
-type TransactionOptions = { usePhantomQuery: boolean };
+interface Transaction extends AdapterInfo {
+  readonly options: { usePhantomQuery: boolean }
+  queryRaw(query: SqlQuery): Promise<SqlResultSet>
+  executeRaw(query: SqlQuery): Promise<number>
+  commit(): Promise<void>
+  rollback(): Promise<void>
+  createSavepoint?(name: string): Promise<void>
+  rollbackToSavepoint?(name: string): Promise<void>
+  releaseSavepoint?(name: string): Promise<void>
+}
 ```
 
-### SqlMigrationAwareDriverAdapterFactory
+`IsolationLevel` currently includes `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SNAPSHOT`, and `SERIALIZABLE`; validate what the concrete database supports.
 
-```typescript
-interface SqlMigrationAwareDriverAdapterFactory {
-  readonly provider: "mysql" | "postgres" | "sqlite" | "sqlserver";
-  readonly adapterName: string;
-  connect(): Promise<SqlDriverAdapter>;
-  connectToShadowDb(): Promise<SqlDriverAdapter>;
-}
-```
+## Priority rules
 
-## Implementation Steps
+| Priority | Rule | Impact |
+|----------|------|--------|
+| CRITICAL | One dedicated connection per transaction | Prevents interleaving and leaks |
+| CRITICAL | `commit`/`rollback` are lifecycle cleanup hooks | Prevents duplicate COMMIT/ROLLBACK |
+| CRITICAL | Savepoints live on `Transaction`, not adapter-global depth | Makes nested scopes connection-local |
+| CRITICAL | Preserve original database error code/message | Enables useful `P2039` fallback |
+| HIGH | Map arguments and result metadata exactly | Prevents silent value corruption |
+| HIGH | Shadow databases are isolated and always cleaned up | Makes Migrate safe |
+| HIGH | Dispose only resources the adapter owns | Prevents shutting down caller-owned pools |
 
-### Step 1: Create the Queryable base class
+## Query implementation
+
+`SqlQuery` contains `sql`, `args`, and parallel `argTypes`. Map each argument using both value and `ArgType`; do not discard type/arity information. Execute in the driver's array/tuple row mode so column order is stable.
 
 ```typescript
-class MyQueryable<TClient> implements SqlQueryable {
-  readonly provider = "postgres" as const; // or 'sqlite' | 'mysql' | 'sqlserver'
-  readonly adapterName = "@my-org/adapter-mydb" as const;
+class ExampleQueryable {
+  readonly provider = 'postgres' as const
+  readonly adapterName = '@acme/adapter-example'
 
-  constructor(protected readonly client: TClient) {}
+  constructor(protected readonly connection: DriverConnection) {}
 
   async queryRaw(query: SqlQuery): Promise<SqlResultSet> {
     try {
-      const args = query.args.map((arg, i) =>
-        mapArg(arg, query.argTypes[i] ?? { scalarType: "unknown", arity: "scalar" })
-      );
-
-      // Execute query with your driver
-      const result = await this.client.query(query.sql, args);
+      const result = await this.connection.query({
+        text: query.sql,
+        values: query.args.map((value, index) =>
+          mapArg(value, query.argTypes[index]),
+        ),
+        rowMode: 'array',
+      })
 
-      // Extract column metadata
-      const columnNames = /* get from result */;
-      const columnTypes = /* map to ColumnTypeEnum */;
-
-      // Map rows to ResultValue arrays
-      const rows = result.map(row => mapRow(row, columnTypes));
-
-      return { columnNames, columnTypes, rows };
-    } catch (e) {
-      this.onError(e);
+      return {
+        columnNames: result.fields.map((field) => field.name),
+        columnTypes: result.fields.map(mapColumnType),
+        rows: result.rows,
+      }
+    } catch (error) {
+      throwAdapterError(error)
     }
   }
 
   async executeRaw(query: SqlQuery): Promise<number> {
     try {
-      const args = query.args.map((arg, i) =>
-        mapArg(arg, query.argTypes[i] ?? { scalarType: "unknown", arity: "scalar" })
-      );
-      const result = await this.client.query(query.sql, args);
-      return result.affectedRows ?? 0;
-    } catch (e) {
-      this.onError(e);
+      const result = await this.connection.execute(
+        query.sql,
+        query.args.map((value, index) => mapArg(value, query.argTypes[index])),
+      )
+      return result.rowsAffected ?? 0
+    } catch (error) {
+      throwAdapterError(error)
     }
   }
-
-  protected onError(error: unknown): never {
-    throw new DriverAdapterError(convertDriverError(error));
-  }
 }
 ```
 
-### Step 2: Create the Transaction class
+### Result mapping
 
-**Critical**: `commit()` and `rollback()` are **lifecycle hooks only**. They must NOT issue SQL. Prisma sends `COMMIT`/`ROLLBACK` via `executeRaw` on the transaction object.
+Return `columnNames`, `columnTypes`, and `rows` with identical lengths/order. Map driver metadata to `ColumnTypeEnum` deliberately:
 
-```typescript
-class MyTransaction extends MyQueryable<TClient> implements Transaction {
-  readonly options: TransactionOptions;
-  readonly #release: () => void;
-
-  constructor(
-    client: TClient,
-    options: TransactionOptions,
-    release: () => void,
-  ) {
-    super(client);
-    this.options = options;
-    this.#release = release;
-  }
+- signed integer widths to `Int32`/`Int64`; preserve 64-bit values without JS number truncation
+- decimal/numeric to `Numeric` using the representation expected by Prisma
+- binary to `Uint8Array`/`Bytes`
+- date-only, time-only, and timestamp to `Date`, `Time`, and `DateTime`
+- UUID, JSON, enum, arrays, and provider-specific unknown values to their explicit types
+- unsupported native types to `DriverAdapterError({ kind: 'UnsupportedNativeDataType', type })`
 
-  commit(): Promise<void> {
-    // DO NOT issue COMMIT SQL here — Prisma does it via executeRaw
-    this.#release(); // Release connection/resources
-    return Promise.resolve();
-  }
+Test `null`, empty arrays, array element types, big integers, decimals, byte arrays, JSON, dates, and user-defined/unknown native types.
 
-  rollback(): Promise<void> {
-    // DO NOT issue ROLLBACK SQL here — Prisma does it via executeRaw
-    this.#release();
-    return Promise.resolve();
-  }
-}
-```
+### Script execution
 
-### Step 3: Create the Adapter class
+`executeScript` must execute a migration script as the provider expects. Prefer the driver's native multi-statement/script facility or a real SQL parser. Naively splitting on `;` breaks functions, triggers, quoted strings, and dialect-specific blocks.
 
-```typescript
-class MyAdapter extends MyQueryable<TClient> implements SqlDriverAdapter {
-  #transactionDepth = 0;
+## Transaction protocol
 
-  constructor(client: TClient) {
-    super(client);
-  }
+`startTransaction` must acquire one dedicated connection, start the database transaction, apply the requested isolation level, and return a `Transaction` bound to that same connection. If setup fails, release it immediately.
 
-  async executeScript(script: string): Promise<void> {
-    // For SQLite: split on ';' and run each statement
-    // For Postgres: use multi-statement execution
-    try {
-      // Implementation depends on driver capabilities
-    } catch (e) {
-      this.onError(e);
+```typescript
+async startTransaction(level?: IsolationLevel): Promise<Transaction> {
+  const connection = await this.pool.acquire()
+  try {
+    const tx = new ExampleTransaction(connection, () => connection.release())
+    await tx.executeRaw({ sql: 'BEGIN', args: [], argTypes: [] })
+    if (level) {
+      await tx.executeRaw({
+        sql: `SET TRANSACTION ISOLATION LEVEL ${validateLevel(level)}`,
+        args: [],
+        argTypes: [],
+      })
     }
+    return tx
+  } catch (error) {
+    connection.release(error)
+    throwAdapterError(error)
   }
+}
+```
 
-  async startTransaction(
-    isolationLevel?: IsolationLevel,
-  ): Promise<Transaction> {
-    // Validate isolation level for your database
-    const validLevels = new Set<IsolationLevel>([
-      "READ UNCOMMITTED",
-      "READ COMMITTED",
-      "REPEATABLE READ",
-      "SERIALIZABLE",
-    ]);
-
-    if (isolationLevel !== undefined && !validLevels.has(isolationLevel)) {
-      throw new DriverAdapterError({
-        kind: "InvalidIsolationLevel",
-        level: isolationLevel,
-      });
-    }
-
-    const options: TransactionOptions = { usePhantomQuery: false };
+### Commit and rollback
 
-    this.#transactionDepth += 1;
-    const depth = this.#transactionDepth;
+Prisma coordinates the SQL `COMMIT`/`ROLLBACK` through `executeRaw`. The transaction object's `commit()` and `rollback()` methods are lifecycle hooks: detach listeners and release the dedicated connection exactly once. They must not issue a second SQL commit/rollback.
 
-    try {
-      if (depth === 1) {
-        // Issue BEGIN (with isolation level if specified)
-        const beginSql = isolationLevel
-          ? `BEGIN ISOLATION LEVEL ${isolationLevel}`
-          : "BEGIN";
-        await this.client.query(beginSql);
-      } else {
-        // Nested: use savepoints
-        await this.client.query(`SAVEPOINT sp_${depth}`);
-      }
-    } catch (e) {
-      this.#transactionDepth -= 1;
-      this.onError(e);
-    }
+```typescript
+class ExampleTransaction extends ExampleQueryable implements Transaction {
+  readonly options = { usePhantomQuery: false }
+  #closed = false
 
-    const release = () => {
-      this.#transactionDepth -= 1;
-    };
-    return new MyTransaction(this.client, options, release);
+  constructor(connection: DriverConnection, private readonly release: () => void) {
+    super(connection)
   }
 
-  getConnectionInfo(): ConnectionInfo {
-    return { supportsRelationJoins: true };
-  }
+  async commit() { this.finish() }
+  async rollback() { this.finish() }
 
-  async dispose(): Promise<void> {
-    await this.client.close();
+  private finish() {
+    if (this.#closed) return
+    this.#closed = true
+    this.release()
   }
-}
-```
-
-### Step 4: Create the Factory class
-
-```typescript
-export type MyAdapterConfig = {
-  url: string;
-};
-
-export type MyAdapterOptions = {
-  shadowDatabaseUrl?: string;
-};
 
-export class MyAdapterFactory implements SqlMigrationAwareDriverAdapterFactory {
-  readonly provider = "postgres" as const;
-  readonly adapterName = "@my-org/adapter-mydb" as const;
+  async createSavepoint(name: string) {
+    await this.control(`SAVEPOINT ${safeSavepoint(name)}`)
+  }
 
-  constructor(
-    private readonly config: MyAdapterConfig,
-    private readonly options?: MyAdapterOptions,
-  ) {}
+  async rollbackToSavepoint(name: string) {
+    await this.control(`ROLLBACK TO SAVEPOINT ${safeSavepoint(name)}`)
+  }
 
-  connect(): Promise<SqlDriverAdapter> {
-    return Promise.resolve(new MyAdapter(openConnection(this.config.url)));
+  async releaseSavepoint(name: string) {
+    await this.control(`RELEASE SAVEPOINT ${safeSavepoint(name)}`)
   }
 
-  connectToShadowDb(): Promise<SqlDriverAdapter> {
-    const url = this.options?.shadowDatabaseUrl ?? this.config.url;
-    return Promise.resolve(new MyAdapter(openConnection(url)));
+  private async control(sql: string) {
+    await this.executeRaw({ sql, args: [], argTypes: [] })
   }
 }
 ```
 
-## Conversion Helpers
-
-### Argument Mapping (input)
-
-Convert Prisma argument values to driver-native types:
-
-```typescript
-function mapArg(arg: unknown, argType: ArgType): unknown {
-  if (arg === null || arg === undefined) return null;
+Implement the optional savepoint methods only where the provider supports them. Validate/quote savepoint identifiers. For providers whose savepoints are intentionally no-ops, document and test that limitation.
 
-  // String → number for int columns
-  if (typeof arg === "string" && argType.scalarType === "int")
-    return Number.parseInt(arg, 10);
+Never keep transaction depth on the shared adapter. Parallel transactions make adapter-global depth incorrect; nested state belongs to the returned transaction connection and Prisma's savepoint calls.
 
-  // String → number for float columns
-  if (typeof arg === "string" && argType.scalarType === "float")
-    return Number.parseFloat(arg);
+## Error mapping
 
-  // String → BigInt for bigint columns
-  if (typeof arg === "string" && argType.scalarType === "bigint")
-    return BigInt(arg);
+Wrap recognized driver failures in `DriverAdapterError`. Map known conditions to `MappedError` kinds such as constraint violations, authentication/reachability, missing table/column/database, timeouts, closed transactions, invalid input, value range, and write conflicts.
 
-  // Base64 string → Buffer for bytes columns
-  if (typeof arg === "string" && argType.scalarType === "bytes")
-    return Buffer.from(arg, "base64");
-
-  // Boolean → 0/1 for SQLite
-  if (typeof arg === "boolean" && /* SQLite */)
-    return arg ? 1 : 0;
-
-  return arg;
-}
-```
-
-### Row Mapping (output)
-
-Convert driver result values to Prisma-expected types:
+For database errors, preserve `originalCode` and `originalMessage` even when falling back to the provider-specific raw variant:
 
 ```typescript
-function mapRow(row: unknown[], columnTypes: ColumnType[]): ResultValue[] {
-  const result: ResultValue[] = [];
-
-  for (let i = 0; i < row.length; i++) {
-    const value = row[i] ?? null;
-    const colType = columnTypes[i];
-
-    if (value === null) {
-      result.push(null);
-      continue;
-    }
-
-    // bigint → string for Int64 (JSON-safe)
-    if (typeof value === "bigint") {
-      result.push(value.toString());
-      continue;
-    }
-
-    // Date → ISO 8601 string for DateTime
-    if (value instanceof Date) {
-      result.push(value.toISOString());
-      continue;
-    }
-
-    // JSON objects → stringified
-    if (colType === ColumnTypeEnum.Json && typeof value === "object") {
-      result.push(JSON.stringify(value));
-      continue;
-    }
-
-    result.push(value as ResultValue);
+import {
+  DriverAdapterError,
+  type Error as DriverAdapterErrorObject,
+  type MappedError,
+} from '@prisma/driver-adapter-utils'
+
+function convertDriverError(error: DatabaseError): DriverAdapterErrorObject {
+  return {
+    originalCode: String(error.code),
+    originalMessage: error.message,
+    ...mapKnownOrRaw(error),
   }
-
-  return result;
-}
-```
-
-### Column Type Inference
-
-When the driver doesn't provide type metadata, infer from JS values:
-
-```typescript
-function inferColumnType(value: NonNullable<unknown>): ColumnType {
-  if (typeof value === "boolean") return ColumnTypeEnum.Boolean;
-  if (typeof value === "bigint") return ColumnTypeEnum.Int64;
-  if (value instanceof Uint8Array) return ColumnTypeEnum.Bytes;
-  if (value instanceof Date) return ColumnTypeEnum.DateTime;
-  if (Array.isArray(value)) return ColumnTypeEnum.Text; // fallback
-  if (typeof value === "object") return ColumnTypeEnum.Json;
-  if (typeof value === "number") return ColumnTypeEnum.UnknownNumber;
-  return ColumnTypeEnum.Text;
 }
-```
-
-## Error Handling
-
-Map driver errors to `MappedError` for Prisma to handle correctly:
-
-```typescript
-function convertDriverError(error: unknown): MappedError {
-  if (error instanceof Error) {
-    // Database-specific error mapping
-    const dbError = error as Error & { code?: string; errno?: number };
-
-    // PostgreSQL example
-    if (dbError.code === "23505") {
-      return { kind: "UniqueConstraintViolation" };
-    }
-    if (dbError.code === "23502") {
-      return { kind: "NullConstraintViolation" };
-    }
-    if (dbError.code === "23503") {
-      return { kind: "ForeignKeyConstraintViolation" };
-    }
-    if (dbError.code === "42P01") {
-      return { kind: "TableDoesNotExist" };
-    }
 
-    // SQLite example
-    if (error.name === "SQLiteError") {
-      return {
-        kind: "sqlite",
-        extendedCode: dbError.errno ?? 1,
-        message: error.message,
-      };
-    }
-
-    // PostgreSQL raw error
-    if (dbError.code) {
-      return {
-        kind: "postgres",
-        code: dbError.code,
-        severity: "ERROR",
-        message: error.message,
-        detail: undefined,
-        column: undefined,
-        hint: undefined,
-      };
-    }
+function mapKnownOrRaw(error: DatabaseError): MappedError {
+  if (error.code === '23505') {
+    return { kind: 'UniqueConstraintViolation', constraint: parsedConstraint(error) }
+  }
+  return {
+    kind: 'postgres',
+    code: String(error.code ?? 'N/A'),
+    severity: error.severity ?? 'N/A',
+    message: error.message,
+    detail: error.detail,
+    column: error.column,
+    hint: error.hint,
   }
-
-  return { kind: "GenericJs", id: 0 };
 }
-```
-
-## Database-Specific Notes
-
-### SQLite
-
-- Set `safeIntegers: true` when opening the database to get `bigint` for large integers
-- Only `SERIALIZABLE` isolation level is valid
-- `executeScript`: split on `;` and run each statement individually
-- Boolean values: store as 0/1, return as boolean
-
-### PostgreSQL
-
-- All standard isolation levels are valid
-- For connection pooling (PgBouncer), use `prepare: false`
-- Transactions require a dedicated connection (`reserve()` pattern)
-- `executeScript`: use multi-statement execution (`.simple()` in some drivers)
-- `int8` columns may return as string (already stringified by driver)
-- `numeric` columns return as string to preserve precision
-
-### MySQL/MariaDB
-
-- Supports `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SERIALIZABLE`
-- Use `?` placeholders for parameters
-- Handle `BIGINT` as string for large values
-
-## Testing Strategy
 
-### Unit Tests (no PrismaClient)
-
-Test the adapter directly with the raw database driver:
-
-```typescript
-describe("queryRaw", () => {
-  test("returns column names and types", async () => {
-    const adapter = new MyAdapter(createTestConnection());
-    const result = await adapter.queryRaw({
-      sql: "SELECT id, name FROM users",
-      args: [],
-      argTypes: [],
-    });
-    expect(result.columnNames).toEqual(["id", "name"]);
-    expect(result.columnTypes[0]).toBe(ColumnTypeEnum.Int32);
-  });
-});
-
-describe("startTransaction", () => {
-  test("commit persists changes", async () => {
-    const adapter = new MyAdapter(createTestConnection());
-    const tx = await adapter.startTransaction();
-    await tx.executeRaw({
-      sql: "INSERT INTO users (name) VALUES (?)",
-      args: ["Alice"],
-      argTypes: [],
-    });
-    // Prisma sends COMMIT via executeRaw
-    await tx.executeRaw({ sql: "COMMIT", args: [], argTypes: [] });
-    await tx.commit(); // lifecycle hook only
-    // Verify data persisted
-  });
-});
-```
-
-### E2E Tests (with PrismaClient)
-
-Test the full integration:
-
-```typescript
-describe("E2E", () => {
-  let prisma: PrismaClient;
-
-  beforeEach(async () => {
-    const factory = new MyAdapterFactory({ url: TEST_DB_URL });
-    prisma = new PrismaClient({ adapter: factory });
-  });
-
-  test("CRUD operations", async () => {
-    const user = await prisma.user.create({ data: { name: "Alice" } });
-    expect(user.id).toBeGreaterThan(0);
-
-    const found = await prisma.user.findUnique({ where: { id: user.id } });
-    expect(found?.name).toBe("Alice");
-  });
-
-  test("transactions roll back on error", async () => {
-    await expect(
-      prisma.$transaction(async (tx) => {
-        await tx.user.create({ data: { name: "Bob" } });
-        throw new Error("Rollback!");
-      }),
-    ).rejects.toThrow();
-
-    expect(await prisma.user.count()).toBe(0);
-  });
-});
-```
-
-## Usage Example
-
-```typescript
-import { PrismaClient } from "./generated/prisma/client";
-import { MyAdapterFactory } from "@my-org/adapter-mydb";
-
-const factory = new MyAdapterFactory({
-  url: process.env.DATABASE_URL!,
-});
-
-const prisma = new PrismaClient({ adapter: factory });
-
-// Use prisma normally
-const users = await prisma.user.findMany();
+function throwAdapterError(error: unknown): never {
+  if (!isDatabaseError(error)) throw error
+  throw new DriverAdapterError(convertDriverError(error))
+}
 ```
 
-## Checklist
-
-Before considering the adapter complete:
-
-- [ ] `SqlMigrationAwareDriverAdapterFactory` implemented with `connect()` and `connectToShadowDb()`
-- [ ] `SqlDriverAdapter` implements `queryRaw`, `executeRaw`, `executeScript`, `startTransaction`, `dispose`
-- [ ] `Transaction` implements `queryRaw`, `executeRaw`, `commit`, `rollback` with `options: { usePhantomQuery: false }`
-- [ ] `commit()` and `rollback()` are lifecycle hooks only (no SQL issued)
-- [ ] `startTransaction` issues `BEGIN` (depth 1) or `SAVEPOINT sp_N` (nested)
-- [ ] Argument mapping handles: string→int, string→bigint, string→float, base64→bytes
-- [ ] Row mapping handles: bigint→string, Date→ISO string, JSON→string
-- [ ] Column types correctly mapped to `ColumnTypeEnum`
-- [ ] Errors wrapped in `DriverAdapterError` with proper `MappedError` kind
-- [ ] Isolation level validation for the target database
-- [ ] Unit tests pass for queryRaw, executeRaw, executeScript, transactions
-- [ ] E2E tests pass with real PrismaClient
+Prisma uses preserved original details when an unmapped driver error becomes `P2039`. Do not replace every unknown exception with a fabricated `GenericJs` id; rethrow genuinely unexpected non-driver errors so programming bugs remain visible.
+
+## Factory, ownership, and shadow database
+
+- `connect()` returns a fresh usable adapter connection/pool wrapper.
+- Track whether the factory created the pool. `dispose()` closes owned pools and only detaches listeners from caller-owned pools unless an explicit option transfers ownership.
+- Implement `SqlMigrationAwareDriverAdapterFactory` only when `connectToShadowDb()` can create an isolated shadow database, connect to it, and drop it during disposal/failure cleanup.
+- Never point the shadow adapter at the primary database. Quote generated identifiers and use cryptographically unique names.
+- `getConnectionInfo()` should accurately report `schemaName`, `maxBindValues` when applicable, and `supportsRelationJoins`.
+
+## Verification checklist
+
+- [ ] Typecheck against the exact target `@prisma/driver-adapter-utils` version
+- [ ] `queryRaw` preserves column order, types, nulls, and precision
+- [ ] `executeRaw` reports affected rows correctly
+- [ ] `executeScript` handles provider-specific multi-statement syntax
+- [ ] Concurrent interactive transactions use distinct dedicated connections
+- [ ] Success commits and releases once; failure rolls back and releases once
+- [ ] Nested transaction tests exercise create/rollback/release savepoint hooks
+- [ ] Unsupported isolation levels fail as `InvalidIsolationLevel`
+- [ ] Known constraints map to structured errors
+- [ ] Unmapped database errors retain original code/message and surface useful `P2039`
+- [ ] Dispose ownership is tested for internal and external pools
+- [ ] Shadow database creation, use, failure cleanup, and disposal are isolated
+- [ ] Run Prisma Client integration/E2E tests, not only adapter unit tests
+
+## Source references
+
+- [Driver adapter interfaces](https://github.com/prisma/prisma/blob/v7/packages/driver-adapter-utils/src/types.ts)
+- [PostgreSQL adapter transaction implementation](https://github.com/prisma/prisma/blob/v7/packages/adapter-pg/src/pg.ts)
+- [PostgreSQL adapter error mapping](https://github.com/prisma/prisma/blob/v7/packages/adapter-pg/src/errors.ts)
diff --git a/plugins/prisma/.agents/skills/prisma-postgres/SKILL.md b/plugins/prisma/.agents/skills/prisma-postgres/SKILL.md
index 86024dd2..568543fb 100644
--- a/plugins/prisma/.agents/skills/prisma-postgres/SKILL.md
+++ b/plugins/prisma/.agents/skills/prisma-postgres/SKILL.md
@@ -4,7 +4,7 @@ description: Prisma Postgres setup and operations guidance across Console, creat
 license: MIT
 metadata:
   author: prisma
-  version: "7.6.0"
+  version: "7.9.1"
 ---
 
 # Prisma Postgres
@@ -67,6 +67,22 @@ For app integrations, you can also use the programmatic API (`create()` / `regio
 
 Temporary databases auto-delete after ~24 hours unless claimed.
 
+### 2b. Persistent databases with the Platform CLI
+
+For databases that belong to a Project (not throwaway `create-db` databases), use `@prisma/cli`:
+
+```bash
+npx -y @prisma/cli@latest database create --help
+npx -y @prisma/cli@latest database list --json
+npx -y @prisma/cli@latest database connection create db_123
+npx -y @prisma/cli@latest database usage db_123
+npx -y @prisma/cli@latest database backup list db_123
+```
+
+`database create` and `database connection create` print a one-time connection URL; store it immediately. Destructive commands (`remove`, `restore`) require exact `--confirm <id>`.
+
+For automation, prefer `--json --no-interactive`, resolve ids before mutations, and verify the installed command's help because this CLI is beta.
+
 ### 3. Link an existing local project
 
 Use `prisma postgres link` when the database already exists and you want to wire a local project to it:
@@ -111,6 +127,8 @@ npm install @prisma/management-api-sdk
 
 Use `createManagementApiClient` for existing tokens, or `createManagementApiSdk` for OAuth + token refresh.
 
+The SDK exposes typed workspace service-token list, create, and revoke routes. A newly created token value is returned exactly once. Let the installed SDK types or OpenAPI document settle exact beta endpoint shapes.
+
 ## Rule Files
 
 Detailed guidance lives in:
diff --git a/plugins/prisma/.agents/skills/prisma-postgres/references/console-and-connections.md b/plugins/prisma/.agents/skills/prisma-postgres/references/console-and-connections.md
index c6e30f9a..4025d12b 100644
--- a/plugins/prisma/.agents/skills/prisma-postgres/references/console-and-connections.md
+++ b/plugins/prisma/.agents/skills/prisma-postgres/references/console-and-connections.md
@@ -55,6 +55,8 @@ Typical direct TCP format:
 DATABASE_URL="postgres://identifier:key@db.prisma.io:5432/postgres?sslmode=require"
 ```
 
+Management API connection responses expose both `endpoints.direct` (`db.prisma.io:5432`) and `endpoints.pooled` (`pooled.db.prisma.io:5432`); prefer those fields over the deprecated flat `connectionString`. Connection secrets are shown once at creation (one-time view); store them immediately.
+
 ## Adapter choices
 
 - Standard Node.js apps: prefer `@prisma/adapter-pg` with the direct TCP URL above.
diff --git a/plugins/prisma/.agents/skills/prisma-postgres/references/management-api-sdk.md b/plugins/prisma/.agents/skills/prisma-postgres/references/management-api-sdk.md
index d4ad6bb0..026aa5f8 100644
--- a/plugins/prisma/.agents/skills/prisma-postgres/references/management-api-sdk.md
+++ b/plugins/prisma/.agents/skills/prisma-postgres/references/management-api-sdk.md
@@ -2,6 +2,8 @@
 
 Use `@prisma/management-api-sdk` for typed API integration with optional OAuth and token refresh.
 
+The Platform API evolves independently from Prisma ORM. Inspect the installed package's generated `api.d.ts` for exact paths and request/response shapes.
+
 ## Priority
 
 HIGH
@@ -25,6 +27,18 @@ const client = createManagementApiClient({ token: process.env.PRISMA_SERVICE_TOK
 const { data: workspaces } = await client.GET('/v1/workspaces')
 ```
 
+Check the generated client result before using `data`; typed clients surface HTTP failures separately. Never log a full response from connection/key creation because it may contain one-time credentials.
+
+## Workspace service tokens
+
+The typed client exposes routes to list, create, and revoke workspace service tokens:
+
+- `GET /v1/workspaces/{workspaceId}/service-tokens`
+- `POST /v1/workspaces/{workspaceId}/service-tokens`
+- `DELETE /v1/workspaces/{workspaceId}/service-tokens/{serviceTokenId}`
+
+Creation accepts a display `name`. The response's `data.value` is the complete token and is returned exactly once; transfer it directly to the intended secret store without logging the response. Later list calls return metadata and `valueHint`, not the token value. Treat revocation as destructive and resolve both ids explicitly.
+
 ## Full SDK (OAuth + refresh)
 
 ```typescript
diff --git a/plugins/prisma/.agents/skills/prisma-postgres/references/management-api.md b/plugins/prisma/.agents/skills/prisma-postgres/references/management-api.md
index ff37c39e..4e4e76f9 100644
--- a/plugins/prisma/.agents/skills/prisma-postgres/references/management-api.md
+++ b/plugins/prisma/.agents/skills/prisma-postgres/references/management-api.md
@@ -42,17 +42,35 @@ Authorization: Bearer $TOKEN
 3. Exchange code at `https://auth.prisma.io/token`.
 4. Use returned access token in Management API requests.
 
-## Common endpoints
+## Resource model
 
-- `GET /workspaces`
-- `GET /projects`
-- `POST /projects`
-- Database management endpoints under project/database paths
+Workspace -> Project -> Branch -> Database. Branches are a first-class resource: databases attach to a Branch, and branch-scoped env/databases are how preview isolation works.
+
+## Current resource inventory
+
+The 1.55 OpenAPI surface includes:
+
+- workspaces, subscriptions, workspace integrations, workspace service tokens, and current-user metadata
+- projects, transfers, project databases, and project/branch environment variables
+- branches under a project plus branch get/update/delete operations
+- databases, usage, backups, restore, connections, and connection rotation
+- apps, deployments, promotion/rollback, runtime logs, domains, and build logs
+- buckets and bucket keys
+- source repositories, SCM installations/install intents, and repositories
+- integrations and regions
+
+App/deployment, branch mutation, SCM, and bucket routes include experimental surfaces. Read the installed SDK types or live OpenAPI before building durable automation around them.
+
+Connection create/rotate responses reveal credentials once. Later reads redact or omit the secret, so store the URL immediately. Use the structured direct/pooled endpoint returned by the concrete operation; do not assume a historical flat response shape.
+
+Workspace service-token creation also returns the complete token value exactly once. List calls expose only metadata and a `valueHint`; delete revokes the token. Keep workspace and token ids opaque, and never log a create response.
+
+Database create supports explicit project, region, branch, and source context. A source may be empty, a backup, or another database. Backup records are incremental; rely on current fields and documented units rather than old full-backup examples.
 
 ## Notes
 
-- Management API responses may include direct connection credentials for databases.
-- Build PostgreSQL `DATABASE_URL` from direct connection values when needed.
+- Management API mutation responses may include direct connection credentials; treat the entire response as secret until redacted.
+- Prefer an API-provided connection string over manually assembling one from fields.
 
 ## References
 
diff --git a/plugins/prisma/.agents/skills/prisma-upgrade-v7/SKILL.md b/plugins/prisma/.agents/skills/prisma-upgrade-v7/SKILL.md
index 1ac08b97..23d4956a 100644
--- a/plugins/prisma/.agents/skills/prisma-upgrade-v7/SKILL.md
+++ b/plugins/prisma/.agents/skills/prisma-upgrade-v7/SKILL.md
@@ -41,9 +41,15 @@ Reference this skill when:
 - `removed-features` - removed middleware, metrics, and legacy CLI behavior
 - `accelerate-users` - migration notes for Accelerate users
 
+## Using MongoDB? This guide does not apply
+
+Prisma 7 has no MongoDB connector. Do not apply any step in this guide to a project with
+`provider = "mongodb"` — see the `prisma-mongodb-upgrade` skill for the actual decision
+(stay on v6 deliberately vs migrate to Prisma Next).
+
 ## Important Notes
 
-- **MongoDB projects should stay on Prisma 6.x** - do not migrate MongoDB apps to Prisma 7's SQL client path
+- **MongoDB projects should stay on Prisma 6.x or migrate to Prisma Next** - do not migrate MongoDB apps to Prisma 7's SQL client path (see `prisma-mongodb-upgrade`)
 - **Node.js 20.19.0+** required
 - **TypeScript 5.4.0+** required
 - **Latest stable Prisma ORM version**: `7.6.0`
diff --git a/plugins/prisma/.claude/skills/prisma-cli b/plugins/prisma/.claude/skills/prisma-cli
new file mode 120000
index 00000000..bc38a65a
--- /dev/null
+++ b/plugins/prisma/.claude/skills/prisma-cli
@@ -0,0 +1 @@
+../../.agents/skills/prisma-cli
\ No newline at end of file
diff --git a/plugins/prisma/.claude/skills/prisma-client-api b/plugins/prisma/.claude/skills/prisma-client-api
new file mode 120000
index 00000000..25a84415
--- /dev/null
+++ b/plugins/prisma/.claude/skills/prisma-client-api
@@ -0,0 +1 @@
+../../.agents/skills/prisma-client-api
\ No newline at end of file
diff --git a/plugins/prisma/.claude/skills/prisma-database-setup b/plugins/prisma/.claude/skills/prisma-database-setup
new file mode 120000
index 00000000..f188a790
--- /dev/null
+++ b/plugins/prisma/.claude/skills/prisma-database-setup
@@ -0,0 +1 @@
+../../.agents/skills/prisma-database-setup
\ No newline at end of file
diff --git a/plugins/prisma/.claude/skills/prisma-driver-adapter-implementation b/plugins/prisma/.claude/skills/prisma-driver-adapter-implementation
new file mode 120000
index 00000000..c4bd907d
--- /dev/null
+++ b/plugins/prisma/.claude/skills/prisma-driver-adapter-implementation
@@ -0,0 +1 @@
+../../.agents/skills/prisma-driver-adapter-implementation
\ No newline at end of file
diff --git a/plugins/prisma/.claude/skills/prisma-postgres b/plugins/prisma/.claude/skills/prisma-postgres
new file mode 120000
index 00000000..e195028e
--- /dev/null
+++ b/plugins/prisma/.claude/skills/prisma-postgres
@@ -0,0 +1 @@
+../../.agents/skills/prisma-postgres
\ No newline at end of file
diff --git a/plugins/prisma/.claude/skills/prisma-upgrade-v7 b/plugins/prisma/.claude/skills/prisma-upgrade-v7
new file mode 120000
index 00000000..95a4d863
--- /dev/null
+++ b/plugins/prisma/.claude/skills/prisma-upgrade-v7
@@ -0,0 +1 @@
+../../.agents/skills/prisma-upgrade-v7
\ No newline at end of file
diff --git a/plugins/prisma/agent/skills/prisma-cli/SKILL.md b/plugins/prisma/agent/skills/prisma-cli/SKILL.md
index 38e72c8f..da55af3f 100644
--- a/plugins/prisma/agent/skills/prisma-cli/SKILL.md
+++ b/plugins/prisma/agent/skills/prisma-cli/SKILL.md
@@ -1,15 +1,15 @@
 ---
-description: "Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, studio, validate, format, debug, and mcp. Use for ORM/database CLI workflows, not Prisma Compute app deployment. For Prisma Compute, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, apps, deployments, logs, or domains, use the `prisma-compute` skill instead. Triggers on \"prisma init\", \"prisma generate\", \"prisma migrate\", \"prisma db\", \"prisma studio\", \"prisma mcp\"."
+description: "Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, complete, studio, validate, format, debug, and mcp. Use for ORM/database CLI workflows, not the Prisma Platform CLI. Triggers on \"prisma init\", \"prisma generate\", \"prisma migrate\", \"prisma db\", \"prisma complete\", \"prisma studio\", \"prisma mcp\"."
 license: "MIT"
-metadata: {"author":"prisma","version":"7.6.0"}
+metadata: {"author":"prisma","version":"7.9.1"}
 ---
 # Prisma CLI Reference
 
 Reference for Prisma ORM CLI commands. This skill provides guidance on command usage, options, and best practices for current Prisma ORM releases.
 
-## Boundary: Compute
+## Boundary: Platform and Compute
 
-Do not use this skill for Prisma Compute app deployment. Use `prisma-compute` for `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, Compute apps, deployments, logs, domains, and framework deploy readiness.
+Do not confuse the stable ORM command (`prisma`) with the public-beta Platform package (`@prisma/cli`, binary `prisma-cli`). Use `prisma-compute` for Compute apps and workspace auth, and `prisma-postgres` for Platform projects and databases.
 
 ## When to Apply
 
@@ -20,6 +20,7 @@ Reference this skill when:
 - Managing database state (`prisma db push/pull`)
 - Using local development database (`prisma dev`)
 - Debugging Prisma issues (`prisma debug`)
+- Generating shell completions (`prisma complete`)
 
 ## Rule Categories by Priority
 
@@ -30,19 +31,19 @@ Reference this skill when:
 | 3 | Development | HIGH | `dev` |
 | 4 | Database | HIGH | `db-` |
 | 5 | Migrations | CRITICAL | `migrate-` |
-| 6 | Utility | MEDIUM | `studio`, `validate`, `format`, `debug`, `mcp` |
+| 6 | Utility | MEDIUM | `complete`, `studio`, `validate`, `format`, `debug`, `mcp` |
 
 ## Command Categories
 
 | Category | Commands | Purpose |
 |----------|----------|---------|
-| Setup | `init` | Bootstrap new Prisma project |
+| Setup | `init` | Initialize a Prisma project |
 | Generation | `generate` | Generate Prisma Client |
 | Validation | `validate`, `format` | Schema validation and formatting |
 | Development | `dev` | Local Prisma Postgres for development |
 | Database | `db pull`, `db push`, `db seed`, `db execute` | Direct database operations |
 | Migrations | `migrate dev`, `migrate deploy`, `migrate reset`, `migrate status`, `migrate diff`, `migrate resolve` | Schema migrations |
-| Utility | `studio`, `mcp`, `version`, `debug` | Development and AI tooling |
+| Utility | `complete`, `studio`, `mcp`, `version`, `debug` | Shell, development, and AI tooling |
 
 ## Quick Reference
 
@@ -62,6 +63,7 @@ prisma init --db
 
 # Initialize with an example model
 prisma init --with-model
+
 ```
 
 ### Client Generation
@@ -174,8 +176,22 @@ prisma validate
 
 # Format schema
 prisma format
+
+# Generate shell completion code
+prisma complete zsh
 ```
 
+## AI Safety Checkpoint
+
+Prisma blocks destructive commands when it detects an AI agent until the agent has obtained explicit user consent. This covers `migrate reset`, `db push --force-reset`, and `db push --accept-data-loss`.
+
+- Explain the exact data-loss impact and ask for consent immediately before running the command.
+- Do not infer consent from earlier or unrelated messages.
+- If automation needs the consent variable, set `PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION` to the user's exact consent message. Do not invent the text.
+- The Prisma MCP server deliberately has no `migrate-reset` tool.
+
+Read `references/agent-safety.md` before any destructive Prisma command.
+
 ## Current Prisma CLI Setup
 
 ### New Configuration File
@@ -233,6 +249,8 @@ references/migrate-resolve.md - Migration resolution
 references/migrate-diff.md   - Schema diffing
 references/studio.md         - Database GUI
 references/mcp.md            - Prisma MCP server
+references/complete.md       - Shell completion generation
+references/agent-safety.md   - AI consent checkpoint for destructive commands
 references/validate.md       - Schema validation
 references/format.md         - Schema formatting
 references/debug.md          - Debug info
diff --git a/plugins/prisma/agent/skills/prisma-cli/references/agent-safety.md b/plugins/prisma/agent/skills/prisma-cli/references/agent-safety.md
new file mode 100644
index 00000000..651c6c34
--- /dev/null
+++ b/plugins/prisma/agent/skills/prisma-cli/references/agent-safety.md
@@ -0,0 +1,27 @@
+# AI safety checkpoint for destructive commands
+
+Prisma detects common AI-agent environments and blocks these commands until the user gives explicit consent:
+
+- `prisma migrate reset`
+- `prisma db push --force-reset`
+- `prisma db push --accept-data-loss`
+
+## Required workflow
+
+1. Inspect the target database/config and explain exactly what can be deleted or reset.
+2. Ask the user for explicit consent immediately before the action.
+3. Run the command only after that consent.
+
+For an agent-run subprocess, Prisma accepts the exact consent text through:
+
+```bash
+PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION='<exact user consent message>' prisma migrate reset --force
+```
+
+The value must match the user's message exactly and must not contain added quotes or newlines. Never fabricate consent, reuse an old unrelated approval, or bypass the checkpoint by hiding agent-detection environment variables.
+
+The MCP server has no `migrate-reset` tool. Use the shell command only after consent.
+
+## Reference
+
+- [Prisma ORM 7.9.0 release](https://github.com/prisma/prisma/releases/tag/7.9.0)
diff --git a/plugins/prisma/agent/skills/prisma-cli/references/complete.md b/plugins/prisma/agent/skills/prisma-cli/references/complete.md
new file mode 100644
index 00000000..73324407
--- /dev/null
+++ b/plugins/prisma/agent/skills/prisma-cli/references/complete.md
@@ -0,0 +1,22 @@
+# prisma complete
+
+Prints a shell completion script.
+
+```bash
+prisma complete zsh
+prisma complete bash
+prisma complete fish
+prisma complete powershell
+```
+
+For a direct global CLI installation, load the output using the shell's normal startup mechanism. For example, in zsh:
+
+```bash
+source <(prisma complete zsh)
+```
+
+Prisma also integrates with supported package-manager completion flows. `npx` and `bunx` do not themselves provide completion; invoke the installed binary or the package manager's supported execution form such as `npm exec` or `bun x`.
+
+## Reference
+
+- [Prisma ORM 7.9.0 release](https://github.com/prisma/prisma/releases/tag/7.9.0)
diff --git a/plugins/prisma/agent/skills/prisma-cli/references/db-push.md b/plugins/prisma/agent/skills/prisma-cli/references/db-push.md
index 51acdbb2..74da0cf4 100644
--- a/plugins/prisma/agent/skills/prisma-cli/references/db-push.md
+++ b/plugins/prisma/agent/skills/prisma-cli/references/db-push.md
@@ -25,6 +25,8 @@ prisma db push [options]
 | `--config` | Custom path to your Prisma config file |
 | `--url` | Override the datasource URL from the Prisma config file |
 
+When Prisma detects an AI agent, `--force-reset` and `--accept-data-loss` require explicit user consent. Follow `agent-safety.md`; never infer or fabricate the consent text.
+
 ### Follow-up Command
 
 - Run `prisma generate` explicitly when you need refreshed client output
diff --git a/plugins/prisma/agent/skills/prisma-cli/references/init.md b/plugins/prisma/agent/skills/prisma-cli/references/init.md
index a255c7b5..c4390ed8 100644
--- a/plugins/prisma/agent/skills/prisma-cli/references/init.md
+++ b/plugins/prisma/agent/skills/prisma-cli/references/init.md
@@ -34,6 +34,9 @@ bunx --bun prisma init
 | `--output` | Define Prisma Client generator output path to use | - |
 | `--preview-feature` | Define a preview feature to use | - |
 | `--with-model` | Add example model to created schema file | - |
+| `--no-skills` | Skip the best-effort installation of Prisma agent skills | - |
+
+`prisma init` attempts to install `prisma/skills` for detected agents. This is best-effort and does not make project initialization fail. Use `--no-skills` in minimal or controlled environments.
 
 ## Examples
 
diff --git a/plugins/prisma/agent/skills/prisma-cli/references/mcp.md b/plugins/prisma/agent/skills/prisma-cli/references/mcp.md
index 26cb963f..284130fa 100644
--- a/plugins/prisma/agent/skills/prisma-cli/references/mcp.md
+++ b/plugins/prisma/agent/skills/prisma-cli/references/mcp.md
@@ -30,7 +30,8 @@ prisma mcp
 
 - Run this from the project that contains your Prisma schema and `prisma.config.ts`
 - The command is separate from Prisma Studio and does not open a browser UI
-- The MCP server wraps Prisma CLI commands. For exact behavior of commands like `migrate dev` or `migrate reset`, follow the underlying CLI command docs rather than relying only on the MCP tool descriptions.
+- The MCP server exposes `migrate-status`, `migrate-dev`, and Prisma Studio tooling. It does not expose the destructive `migrate-reset` tool; do not claim it is available or try to bypass that safety boundary.
+- For destructive shell commands, follow `agent-safety.md` and obtain explicit user consent.
 
 ## References
 
diff --git a/plugins/prisma/agent/skills/prisma-cli/references/migrate-dev.md b/plugins/prisma/agent/skills/prisma-cli/references/migrate-dev.md
index 6b6352b4..48643b64 100644
--- a/plugins/prisma/agent/skills/prisma-cli/references/migrate-dev.md
+++ b/plugins/prisma/agent/skills/prisma-cli/references/migrate-dev.md
@@ -31,7 +31,7 @@ prisma migrate dev [options]
 - Run `prisma generate` explicitly when you need refreshed client output
 - Run `prisma db seed` explicitly when you need seed data
 
-Note: Prisma CLI help for `7.6.0` still says `migrate dev` "trigger[s] generators", but local verification in a temp Prisma 7.6.0 project did not emit generated client files. Treat `prisma generate` as an explicit follow-up step when you need generated artifacts on disk.
+Run `prisma generate` as an explicit follow-up when you need refreshed generated artifacts. Do not rely on historical CLI help that described generators as part of `migrate dev`.
 
 ## Examples
 
diff --git a/plugins/prisma/agent/skills/prisma-cli/references/migrate-reset.md b/plugins/prisma/agent/skills/prisma-cli/references/migrate-reset.md
index 38d6fbdc..900e2885 100644
--- a/plugins/prisma/agent/skills/prisma-cli/references/migrate-reset.md
+++ b/plugins/prisma/agent/skills/prisma-cli/references/migrate-reset.md
@@ -17,6 +17,8 @@ prisma migrate reset [options]
 
 **Warning: All data will be lost.**
 
+When Prisma detects an AI agent, this command is blocked until the user gives explicit consent. Follow `agent-safety.md`; `--force` skips the ordinary prompt but does not constitute user consent for an agent.
+
 ## Options
 
 | Option | Description |
diff --git a/plugins/prisma/agent/skills/prisma-client-api/SKILL.md b/plugins/prisma/agent/skills/prisma-client-api/SKILL.md
index efce8029..b1cc41f4 100644
--- a/plugins/prisma/agent/skills/prisma-client-api/SKILL.md
+++ b/plugins/prisma/agent/skills/prisma-client-api/SKILL.md
@@ -1,7 +1,7 @@
 ---
 description: "Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on \"prisma query\", \"findMany\", \"create\", \"update\", \"delete\", \"$transaction\"."
 license: "MIT"
-metadata: {"author":"prisma","version":"7.6.0"}
+metadata: {"author":"prisma","version":"7.9.1"}
 ---
 # Prisma Client API Reference
 
diff --git a/plugins/prisma/agent/skills/prisma-client-api/references/constructor.md b/plugins/prisma/agent/skills/prisma-client-api/references/constructor.md
index 7c7825f3..a9fb5e8f 100644
--- a/plugins/prisma/agent/skills/prisma-client-api/references/constructor.md
+++ b/plugins/prisma/agent/skills/prisma-client-api/references/constructor.md
@@ -127,6 +127,19 @@ const prisma = new PrismaClient({
 })
 ```
 
+### queryPlanCacheMaxSize
+
+Use `queryPlanCacheMaxSize` to limit the in-memory query-plan cache:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  queryPlanCacheMaxSize: 2_000,
+})
+```
+
+The value must be a non-negative integer. Set it to `0` to disable query-plan caching; omit it to use Prisma's default. Treat this as a process-local memory/performance control, not a database prepared-statement setting.
+
 ## Singleton Pattern
 
 Prevent multiple client instances in development:
diff --git a/plugins/prisma/agent/skills/prisma-client-api/references/raw-queries.md b/plugins/prisma/agent/skills/prisma-client-api/references/raw-queries.md
index 5d3a220b..e444ce2f 100644
--- a/plugins/prisma/agent/skills/prisma-client-api/references/raw-queries.md
+++ b/plugins/prisma/agent/skills/prisma-client-api/references/raw-queries.md
@@ -192,3 +192,7 @@ const users = await prisma.$queryRaw<Result[]>`
 `
 // createdAt is already a Date object
 ```
+
+Invalid JavaScript `Date` values passed to raw queries fail validation instead of being silently serialized as `null`. Validate date input at the application boundary; do not rely on `new Date(badValue)` reaching the database.
+
+When a driver adapter returns an unmapped database-specific error, Prisma surfaces `P2039` with the adapter's preserved original code/message. If those details are missing, fix the adapter mapping rather than parsing rendered error text.
diff --git a/plugins/prisma/agent/skills/prisma-database-setup/SKILL.md b/plugins/prisma/agent/skills/prisma-database-setup/SKILL.md
index accd1c1c..56e92f46 100644
--- a/plugins/prisma/agent/skills/prisma-database-setup/SKILL.md
+++ b/plugins/prisma/agent/skills/prisma-database-setup/SKILL.md
@@ -166,7 +166,7 @@ generator client {
 }
 ```
 
-For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup.
+For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup. If a MongoDB project asks about upgrading Prisma versions, route to the `prisma-mongodb-upgrade` skill (stay-on-v6 vs Prisma Next is the real decision; Prisma 7 is not an option).
 
 ## Rule Files
 
diff --git a/plugins/prisma/agent/skills/prisma-driver-adapter-implementation/SKILL.md b/plugins/prisma/agent/skills/prisma-driver-adapter-implementation/SKILL.md
index 780ae665..136b6cfd 100644
--- a/plugins/prisma/agent/skills/prisma-driver-adapter-implementation/SKILL.md
+++ b/plugins/prisma/agent/skills/prisma-driver-adapter-implementation/SKILL.md
@@ -1,634 +1,266 @@
 ---
-description: "Required reference for Prisma v7 driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter/Transaction interfaces. Contains critical contract details not inferable from code examples — including the transaction lifecycle protocol, error mapping requirements, and verification checklist. Existing implementations do not replace this skill."
+description: "Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification."
 license: "MIT"
-metadata: {"author":"Tyler Benfield","version":"7.6.0"}
+metadata: {"author":"prisma","version":"7.9.1"}
 ---
-# Prisma 7 Driver Adapter Implementation Guide
+# Prisma SQL Driver Adapter Implementation
 
-This skill provides everything needed to implement a Prisma ORM v7 driver adapter for any database.
+Use this guide with the exact `@prisma/driver-adapter-utils` version installed by the target Prisma release. Driver adapters are a protocol boundary: type-compatible code can still corrupt values, leak connections, or break transactions.
 
-## Architecture Overview
+## When to Apply
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         PrismaClient                            │
-│                    (requires adapter factory)                   │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│            SqlMigrationAwareDriverAdapterFactory                │
-│   ┌─────────────────────┐    ┌─────────────────────────────┐    │
-│   │ connect()           │    │ connectToShadowDb()         │    │
-│   │ → SqlDriverAdapter  │    │ → SqlDriverAdapter          │    │
-│   └─────────────────────┘    └─────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                      SqlDriverAdapter                           │
-│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
-│  │ queryRaw()   │ │ executeRaw() │ │ startTransaction()       │ │
-│  │ → ResultSet  │ │ → number     │ │ → Transaction            │ │
-│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
-│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
-│  │executeScript │ │ dispose()    │ │ getConnectionInfo()      │ │
-│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                        Transaction                              │
-│  Extends SqlQueryable + commit() + rollback() + options         │
-│  (lifecycle hooks only — Prisma sends SQL via executeRaw)       │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Required Interfaces
+- Implementing `SqlDriverAdapterFactory`, `SqlMigrationAwareDriverAdapterFactory`, `SqlDriverAdapter`, or `Transaction`
+- Adding nested-transaction/savepoint support
+- Mapping driver values, column metadata, bind arguments, or database errors
+- Debugging `P2039`, transaction leaks, shadow-database failures, or adapter-specific query behavior
 
-Import from `@prisma/driver-adapter-utils`:
+## Contract snapshot
 
 ```typescript
-import type {
-  ColumnType,
-  IsolationLevel,
-  SqlDriverAdapter,
-  SqlMigrationAwareDriverAdapterFactory,
-  SqlQuery,
-  SqlQueryable,
-  SqlResultSet,
-  Transaction,
-  TransactionOptions,
-  ArgType,
-  ConnectionInfo,
-  MappedError,
-} from "@prisma/driver-adapter-utils";
-import {
-  ColumnTypeEnum,
-  DriverAdapterError,
-} from "@prisma/driver-adapter-utils";
-```
-
-## Interface Definitions
-
-### SqlQuery (input to queryRaw/executeRaw)
-
-```typescript
-type SqlQuery = {
-  sql: string; // Parameterized SQL with placeholders
-  args: Array<unknown>; // Bound parameter values
-  argTypes: Array<ArgType>; // Type hints for each argument
-};
-
-type ArgType = {
-  scalarType: ArgScalarType; // 'string' | 'int' | 'bigint' | 'float' | 'decimal' | 'boolean' | 'enum' | 'uuid' | 'json' | 'datetime' | 'bytes' | 'unknown'
-  dbType?: string;
-  arity: "scalar" | "list";
-};
-```
-
-### SqlResultSet (output from queryRaw)
-
-```typescript
-interface SqlResultSet {
-  columnNames: Array<string>; // Column names in order
-  columnTypes: Array<ColumnType>; // Column types matching columnNames
-  rows: Array<Array<unknown>>; // Row data as arrays
-  lastInsertId?: string; // For INSERT without RETURNING
+interface SqlDriverAdapterFactory extends AdapterInfo {
+  connect(): Promise<SqlDriverAdapter>
 }
-```
-
-### ColumnTypeEnum values
-
-```typescript
-const ColumnTypeEnum = {
-  Int32: 0,
-  Int64: 1,
-  Float: 2,
-  Double: 3,
-  Numeric: 4,
-  Boolean: 5,
-  Character: 6,
-  Text: 7,
-  Date: 8,
-  Time: 9,
-  DateTime: 10,
-  Json: 11,
-  Enum: 12,
-  Bytes: 13,
-  Set: 14,
-  Uuid: 15,
-  Int32Array: 64,
-  Int64Array: 65,
-  FloatArray: 66,
-  DoubleArray: 67,
-  NumericArray: 68,
-  BooleanArray: 69,
-  CharacterArray: 70,
-  TextArray: 71,
-  DateArray: 72,
-  TimeArray: 73,
-  DateTimeArray: 74,
-  JsonArray: 75,
-  EnumArray: 76,
-  BytesArray: 77,
-  UuidArray: 78,
-  UnknownNumber: 128,
-} as const;
-```
-
-### SqlDriverAdapter
 
-```typescript
-interface SqlDriverAdapter extends SqlQueryable {
-  executeScript(script: string): Promise<void>;
-  startTransaction(isolationLevel?: IsolationLevel): Promise<Transaction>;
-  getConnectionInfo?(): ConnectionInfo;
-  dispose(): Promise<void>;
+interface SqlMigrationAwareDriverAdapterFactory extends SqlDriverAdapterFactory {
+  connectToShadowDb(): Promise<SqlDriverAdapter>
 }
-```
 
-### Transaction
-
-```typescript
-interface Transaction extends SqlQueryable {
-  readonly options: TransactionOptions;
-  commit(): Promise<void>;
-  rollback(): Promise<void>;
+interface SqlDriverAdapter extends AdapterInfo {
+  queryRaw(query: SqlQuery): Promise<SqlResultSet>
+  executeRaw(query: SqlQuery): Promise<number>
+  executeScript(script: string): Promise<void>
+  startTransaction(isolationLevel?: IsolationLevel): Promise<Transaction>
+  getConnectionInfo?(): ConnectionInfo
+  dispose(): Promise<void>
 }
 
-type TransactionOptions = { usePhantomQuery: boolean };
+interface Transaction extends AdapterInfo {
+  readonly options: { usePhantomQuery: boolean }
+  queryRaw(query: SqlQuery): Promise<SqlResultSet>
+  executeRaw(query: SqlQuery): Promise<number>
+  commit(): Promise<void>
+  rollback(): Promise<void>
+  createSavepoint?(name: string): Promise<void>
+  rollbackToSavepoint?(name: string): Promise<void>
+  releaseSavepoint?(name: string): Promise<void>
+}
 ```
 
-### SqlMigrationAwareDriverAdapterFactory
+`IsolationLevel` currently includes `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SNAPSHOT`, and `SERIALIZABLE`; validate what the concrete database supports.
 
-```typescript
-interface SqlMigrationAwareDriverAdapterFactory {
-  readonly provider: "mysql" | "postgres" | "sqlite" | "sqlserver";
-  readonly adapterName: string;
-  connect(): Promise<SqlDriverAdapter>;
-  connectToShadowDb(): Promise<SqlDriverAdapter>;
-}
-```
+## Priority rules
 
-## Implementation Steps
+| Priority | Rule | Impact |
+|----------|------|--------|
+| CRITICAL | One dedicated connection per transaction | Prevents interleaving and leaks |
+| CRITICAL | `commit`/`rollback` are lifecycle cleanup hooks | Prevents duplicate COMMIT/ROLLBACK |
+| CRITICAL | Savepoints live on `Transaction`, not adapter-global depth | Makes nested scopes connection-local |
+| CRITICAL | Preserve original database error code/message | Enables useful `P2039` fallback |
+| HIGH | Map arguments and result metadata exactly | Prevents silent value corruption |
+| HIGH | Shadow databases are isolated and always cleaned up | Makes Migrate safe |
+| HIGH | Dispose only resources the adapter owns | Prevents shutting down caller-owned pools |
 
-### Step 1: Create the Queryable base class
+## Query implementation
+
+`SqlQuery` contains `sql`, `args`, and parallel `argTypes`. Map each argument using both value and `ArgType`; do not discard type/arity information. Execute in the driver's array/tuple row mode so column order is stable.
 
 ```typescript
-class MyQueryable<TClient> implements SqlQueryable {
-  readonly provider = "postgres" as const; // or 'sqlite' | 'mysql' | 'sqlserver'
-  readonly adapterName = "@my-org/adapter-mydb" as const;
+class ExampleQueryable {
+  readonly provider = 'postgres' as const
+  readonly adapterName = '@acme/adapter-example'
 
-  constructor(protected readonly client: TClient) {}
+  constructor(protected readonly connection: DriverConnection) {}
 
   async queryRaw(query: SqlQuery): Promise<SqlResultSet> {
     try {
-      const args = query.args.map((arg, i) =>
-        mapArg(arg, query.argTypes[i] ?? { scalarType: "unknown", arity: "scalar" })
-      );
-
-      // Execute query with your driver
-      const result = await this.client.query(query.sql, args);
+      const result = await this.connection.query({
+        text: query.sql,
+        values: query.args.map((value, index) =>
+          mapArg(value, query.argTypes[index]),
+        ),
+        rowMode: 'array',
+      })
 
-      // Extract column metadata
-      const columnNames = /* get from result */;
-      const columnTypes = /* map to ColumnTypeEnum */;
-
-      // Map rows to ResultValue arrays
-      const rows = result.map(row => mapRow(row, columnTypes));
-
-      return { columnNames, columnTypes, rows };
-    } catch (e) {
-      this.onError(e);
+      return {
+        columnNames: result.fields.map((field) => field.name),
+        columnTypes: result.fields.map(mapColumnType),
+        rows: result.rows,
+      }
+    } catch (error) {
+      throwAdapterError(error)
     }
   }
 
   async executeRaw(query: SqlQuery): Promise<number> {
     try {
-      const args = query.args.map((arg, i) =>
-        mapArg(arg, query.argTypes[i] ?? { scalarType: "unknown", arity: "scalar" })
-      );
-      const result = await this.client.query(query.sql, args);
-      return result.affectedRows ?? 0;
-    } catch (e) {
-      this.onError(e);
+      const result = await this.connection.execute(
+        query.sql,
+        query.args.map((value, index) => mapArg(value, query.argTypes[index])),
+      )
+      return result.rowsAffected ?? 0
+    } catch (error) {
+      throwAdapterError(error)
     }
   }
-
-  protected onError(error: unknown): never {
-    throw new DriverAdapterError(convertDriverError(error));
-  }
 }
 ```
 
-### Step 2: Create the Transaction class
+### Result mapping
 
-**Critical**: `commit()` and `rollback()` are **lifecycle hooks only**. They must NOT issue SQL. Prisma sends `COMMIT`/`ROLLBACK` via `executeRaw` on the transaction object.
+Return `columnNames`, `columnTypes`, and `rows` with identical lengths/order. Map driver metadata to `ColumnTypeEnum` deliberately:
 
-```typescript
-class MyTransaction extends MyQueryable<TClient> implements Transaction {
-  readonly options: TransactionOptions;
-  readonly #release: () => void;
-
-  constructor(
-    client: TClient,
-    options: TransactionOptions,
-    release: () => void,
-  ) {
-    super(client);
-    this.options = options;
-    this.#release = release;
-  }
+- signed integer widths to `Int32`/`Int64`; preserve 64-bit values without JS number truncation
+- decimal/numeric to `Numeric` using the representation expected by Prisma
+- binary to `Uint8Array`/`Bytes`
+- date-only, time-only, and timestamp to `Date`, `Time`, and `DateTime`
+- UUID, JSON, enum, arrays, and provider-specific unknown values to their explicit types
+- unsupported native types to `DriverAdapterError({ kind: 'UnsupportedNativeDataType', type })`
 
-  commit(): Promise<void> {
-    // DO NOT issue COMMIT SQL here — Prisma does it via executeRaw
-    this.#release(); // Release connection/resources
-    return Promise.resolve();
-  }
+Test `null`, empty arrays, array element types, big integers, decimals, byte arrays, JSON, dates, and user-defined/unknown native types.
 
-  rollback(): Promise<void> {
-    // DO NOT issue ROLLBACK SQL here — Prisma does it via executeRaw
-    this.#release();
-    return Promise.resolve();
-  }
-}
-```
+### Script execution
 
-### Step 3: Create the Adapter class
+`executeScript` must execute a migration script as the provider expects. Prefer the driver's native multi-statement/script facility or a real SQL parser. Naively splitting on `;` breaks functions, triggers, quoted strings, and dialect-specific blocks.
 
-```typescript
-class MyAdapter extends MyQueryable<TClient> implements SqlDriverAdapter {
-  #transactionDepth = 0;
+## Transaction protocol
 
-  constructor(client: TClient) {
-    super(client);
-  }
+`startTransaction` must acquire one dedicated connection, start the database transaction, apply the requested isolation level, and return a `Transaction` bound to that same connection. If setup fails, release it immediately.
 
-  async executeScript(script: string): Promise<void> {
-    // For SQLite: split on ';' and run each statement
-    // For Postgres: use multi-statement execution
-    try {
-      // Implementation depends on driver capabilities
-    } catch (e) {
-      this.onError(e);
+```typescript
+async startTransaction(level?: IsolationLevel): Promise<Transaction> {
+  const connection = await this.pool.acquire()
+  try {
+    const tx = new ExampleTransaction(connection, () => connection.release())
+    await tx.executeRaw({ sql: 'BEGIN', args: [], argTypes: [] })
+    if (level) {
+      await tx.executeRaw({
+        sql: `SET TRANSACTION ISOLATION LEVEL ${validateLevel(level)}`,
+        args: [],
+        argTypes: [],
+      })
     }
+    return tx
+  } catch (error) {
+    connection.release(error)
+    throwAdapterError(error)
   }
+}
+```
 
-  async startTransaction(
-    isolationLevel?: IsolationLevel,
-  ): Promise<Transaction> {
-    // Validate isolation level for your database
-    const validLevels = new Set<IsolationLevel>([
-      "READ UNCOMMITTED",
-      "READ COMMITTED",
-      "REPEATABLE READ",
-      "SERIALIZABLE",
-    ]);
-
-    if (isolationLevel !== undefined && !validLevels.has(isolationLevel)) {
-      throw new DriverAdapterError({
-        kind: "InvalidIsolationLevel",
-        level: isolationLevel,
-      });
-    }
-
-    const options: TransactionOptions = { usePhantomQuery: false };
+### Commit and rollback
 
-    this.#transactionDepth += 1;
-    const depth = this.#transactionDepth;
+Prisma coordinates the SQL `COMMIT`/`ROLLBACK` through `executeRaw`. The transaction object's `commit()` and `rollback()` methods are lifecycle hooks: detach listeners and release the dedicated connection exactly once. They must not issue a second SQL commit/rollback.
 
-    try {
-      if (depth === 1) {
-        // Issue BEGIN (with isolation level if specified)
-        const beginSql = isolationLevel
-          ? `BEGIN ISOLATION LEVEL ${isolationLevel}`
-          : "BEGIN";
-        await this.client.query(beginSql);
-      } else {
-        // Nested: use savepoints
-        await this.client.query(`SAVEPOINT sp_${depth}`);
-      }
-    } catch (e) {
-      this.#transactionDepth -= 1;
-      this.onError(e);
-    }
+```typescript
+class ExampleTransaction extends ExampleQueryable implements Transaction {
+  readonly options = { usePhantomQuery: false }
+  #closed = false
 
-    const release = () => {
-      this.#transactionDepth -= 1;
-    };
-    return new MyTransaction(this.client, options, release);
+  constructor(connection: DriverConnection, private readonly release: () => void) {
+    super(connection)
   }
 
-  getConnectionInfo(): ConnectionInfo {
-    return { supportsRelationJoins: true };
-  }
+  async commit() { this.finish() }
+  async rollback() { this.finish() }
 
-  async dispose(): Promise<void> {
-    await this.client.close();
+  private finish() {
+    if (this.#closed) return
+    this.#closed = true
+    this.release()
   }
-}
-```
-
-### Step 4: Create the Factory class
-
-```typescript
-export type MyAdapterConfig = {
-  url: string;
-};
-
-export type MyAdapterOptions = {
-  shadowDatabaseUrl?: string;
-};
 
-export class MyAdapterFactory implements SqlMigrationAwareDriverAdapterFactory {
-  readonly provider = "postgres" as const;
-  readonly adapterName = "@my-org/adapter-mydb" as const;
+  async createSavepoint(name: string) {
+    await this.control(`SAVEPOINT ${safeSavepoint(name)}`)
+  }
 
-  constructor(
-    private readonly config: MyAdapterConfig,
-    private readonly options?: MyAdapterOptions,
-  ) {}
+  async rollbackToSavepoint(name: string) {
+    await this.control(`ROLLBACK TO SAVEPOINT ${safeSavepoint(name)}`)
+  }
 
-  connect(): Promise<SqlDriverAdapter> {
-    return Promise.resolve(new MyAdapter(openConnection(this.config.url)));
+  async releaseSavepoint(name: string) {
+    await this.control(`RELEASE SAVEPOINT ${safeSavepoint(name)}`)
   }
 
-  connectToShadowDb(): Promise<SqlDriverAdapter> {
-    const url = this.options?.shadowDatabaseUrl ?? this.config.url;
-    return Promise.resolve(new MyAdapter(openConnection(url)));
+  private async control(sql: string) {
+    await this.executeRaw({ sql, args: [], argTypes: [] })
   }
 }
 ```
 
-## Conversion Helpers
-
-### Argument Mapping (input)
-
-Convert Prisma argument values to driver-native types:
-
-```typescript
-function mapArg(arg: unknown, argType: ArgType): unknown {
-  if (arg === null || arg === undefined) return null;
+Implement the optional savepoint methods only where the provider supports them. Validate/quote savepoint identifiers. For providers whose savepoints are intentionally no-ops, document and test that limitation.
 
-  // String → number for int columns
-  if (typeof arg === "string" && argType.scalarType === "int")
-    return Number.parseInt(arg, 10);
+Never keep transaction depth on the shared adapter. Parallel transactions make adapter-global depth incorrect; nested state belongs to the returned transaction connection and Prisma's savepoint calls.
 
-  // String → number for float columns
-  if (typeof arg === "string" && argType.scalarType === "float")
-    return Number.parseFloat(arg);
+## Error mapping
 
-  // String → BigInt for bigint columns
-  if (typeof arg === "string" && argType.scalarType === "bigint")
-    return BigInt(arg);
+Wrap recognized driver failures in `DriverAdapterError`. Map known conditions to `MappedError` kinds such as constraint violations, authentication/reachability, missing table/column/database, timeouts, closed transactions, invalid input, value range, and write conflicts.
 
-  // Base64 string → Buffer for bytes columns
-  if (typeof arg === "string" && argType.scalarType === "bytes")
-    return Buffer.from(arg, "base64");
-
-  // Boolean → 0/1 for SQLite
-  if (typeof arg === "boolean" && /* SQLite */)
-    return arg ? 1 : 0;
-
-  return arg;
-}
-```
-
-### Row Mapping (output)
-
-Convert driver result values to Prisma-expected types:
+For database errors, preserve `originalCode` and `originalMessage` even when falling back to the provider-specific raw variant:
 
 ```typescript
-function mapRow(row: unknown[], columnTypes: ColumnType[]): ResultValue[] {
-  const result: ResultValue[] = [];
-
-  for (let i = 0; i < row.length; i++) {
-    const value = row[i] ?? null;
-    const colType = columnTypes[i];
-
-    if (value === null) {
-      result.push(null);
-      continue;
-    }
-
-    // bigint → string for Int64 (JSON-safe)
-    if (typeof value === "bigint") {
-      result.push(value.toString());
-      continue;
-    }
-
-    // Date → ISO 8601 string for DateTime
-    if (value instanceof Date) {
-      result.push(value.toISOString());
-      continue;
-    }
-
-    // JSON objects → stringified
-    if (colType === ColumnTypeEnum.Json && typeof value === "object") {
-      result.push(JSON.stringify(value));
-      continue;
-    }
-
-    result.push(value as ResultValue);
+import {
+  DriverAdapterError,
+  type Error as DriverAdapterErrorObject,
+  type MappedError,
+} from '@prisma/driver-adapter-utils'
+
+function convertDriverError(error: DatabaseError): DriverAdapterErrorObject {
+  return {
+    originalCode: String(error.code),
+    originalMessage: error.message,
+    ...mapKnownOrRaw(error),
   }
-
-  return result;
-}
-```
-
-### Column Type Inference
-
-When the driver doesn't provide type metadata, infer from JS values:
-
-```typescript
-function inferColumnType(value: NonNullable<unknown>): ColumnType {
-  if (typeof value === "boolean") return ColumnTypeEnum.Boolean;
-  if (typeof value === "bigint") return ColumnTypeEnum.Int64;
-  if (value instanceof Uint8Array) return ColumnTypeEnum.Bytes;
-  if (value instanceof Date) return ColumnTypeEnum.DateTime;
-  if (Array.isArray(value)) return ColumnTypeEnum.Text; // fallback
-  if (typeof value === "object") return ColumnTypeEnum.Json;
-  if (typeof value === "number") return ColumnTypeEnum.UnknownNumber;
-  return ColumnTypeEnum.Text;
 }
-```
-
-## Error Handling
-
-Map driver errors to `MappedError` for Prisma to handle correctly:
-
-```typescript
-function convertDriverError(error: unknown): MappedError {
-  if (error instanceof Error) {
-    // Database-specific error mapping
-    const dbError = error as Error & { code?: string; errno?: number };
-
-    // PostgreSQL example
-    if (dbError.code === "23505") {
-      return { kind: "UniqueConstraintViolation" };
-    }
-    if (dbError.code === "23502") {
-      return { kind: "NullConstraintViolation" };
-    }
-    if (dbError.code === "23503") {
-      return { kind: "ForeignKeyConstraintViolation" };
-    }
-    if (dbError.code === "42P01") {
-      return { kind: "TableDoesNotExist" };
-    }
 
-    // SQLite example
-    if (error.name === "SQLiteError") {
-      return {
-        kind: "sqlite",
-        extendedCode: dbError.errno ?? 1,
-        message: error.message,
-      };
-    }
-
-    // PostgreSQL raw error
-    if (dbError.code) {
-      return {
-        kind: "postgres",
-        code: dbError.code,
-        severity: "ERROR",
-        message: error.message,
-        detail: undefined,
-        column: undefined,
-        hint: undefined,
-      };
-    }
+function mapKnownOrRaw(error: DatabaseError): MappedError {
+  if (error.code === '23505') {
+    return { kind: 'UniqueConstraintViolation', constraint: parsedConstraint(error) }
+  }
+  return {
+    kind: 'postgres',
+    code: String(error.code ?? 'N/A'),
+    severity: error.severity ?? 'N/A',
+    message: error.message,
+    detail: error.detail,
+    column: error.column,
+    hint: error.hint,
   }
-
-  return { kind: "GenericJs", id: 0 };
 }
-```
-
-## Database-Specific Notes
-
-### SQLite
-
-- Set `safeIntegers: true` when opening the database to get `bigint` for large integers
-- Only `SERIALIZABLE` isolation level is valid
-- `executeScript`: split on `;` and run each statement individually
-- Boolean values: store as 0/1, return as boolean
-
-### PostgreSQL
-
-- All standard isolation levels are valid
-- For connection pooling (PgBouncer), use `prepare: false`
-- Transactions require a dedicated connection (`reserve()` pattern)
-- `executeScript`: use multi-statement execution (`.simple()` in some drivers)
-- `int8` columns may return as string (already stringified by driver)
-- `numeric` columns return as string to preserve precision
-
-### MySQL/MariaDB
-
-- Supports `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SERIALIZABLE`
-- Use `?` placeholders for parameters
-- Handle `BIGINT` as string for large values
-
-## Testing Strategy
 
-### Unit Tests (no PrismaClient)
-
-Test the adapter directly with the raw database driver:
-
-```typescript
-describe("queryRaw", () => {
-  test("returns column names and types", async () => {
-    const adapter = new MyAdapter(createTestConnection());
-    const result = await adapter.queryRaw({
-      sql: "SELECT id, name FROM users",
-      args: [],
-      argTypes: [],
-    });
-    expect(result.columnNames).toEqual(["id", "name"]);
-    expect(result.columnTypes[0]).toBe(ColumnTypeEnum.Int32);
-  });
-});
-
-describe("startTransaction", () => {
-  test("commit persists changes", async () => {
-    const adapter = new MyAdapter(createTestConnection());
-    const tx = await adapter.startTransaction();
-    await tx.executeRaw({
-      sql: "INSERT INTO users (name) VALUES (?)",
-      args: ["Alice"],
-      argTypes: [],
-    });
-    // Prisma sends COMMIT via executeRaw
-    await tx.executeRaw({ sql: "COMMIT", args: [], argTypes: [] });
-    await tx.commit(); // lifecycle hook only
-    // Verify data persisted
-  });
-});
-```
-
-### E2E Tests (with PrismaClient)
-
-Test the full integration:
-
-```typescript
-describe("E2E", () => {
-  let prisma: PrismaClient;
-
-  beforeEach(async () => {
-    const factory = new MyAdapterFactory({ url: TEST_DB_URL });
-    prisma = new PrismaClient({ adapter: factory });
-  });
-
-  test("CRUD operations", async () => {
-    const user = await prisma.user.create({ data: { name: "Alice" } });
-    expect(user.id).toBeGreaterThan(0);
-
-    const found = await prisma.user.findUnique({ where: { id: user.id } });
-    expect(found?.name).toBe("Alice");
-  });
-
-  test("transactions roll back on error", async () => {
-    await expect(
-      prisma.$transaction(async (tx) => {
-        await tx.user.create({ data: { name: "Bob" } });
-        throw new Error("Rollback!");
-      }),
-    ).rejects.toThrow();
-
-    expect(await prisma.user.count()).toBe(0);
-  });
-});
-```
-
-## Usage Example
-
-```typescript
-import { PrismaClient } from "./generated/prisma/client";
-import { MyAdapterFactory } from "@my-org/adapter-mydb";
-
-const factory = new MyAdapterFactory({
-  url: process.env.DATABASE_URL!,
-});
-
-const prisma = new PrismaClient({ adapter: factory });
-
-// Use prisma normally
-const users = await prisma.user.findMany();
+function throwAdapterError(error: unknown): never {
+  if (!isDatabaseError(error)) throw error
+  throw new DriverAdapterError(convertDriverError(error))
+}
 ```
 
-## Checklist
-
-Before considering the adapter complete:
-
-- [ ] `SqlMigrationAwareDriverAdapterFactory` implemented with `connect()` and `connectToShadowDb()`
-- [ ] `SqlDriverAdapter` implements `queryRaw`, `executeRaw`, `executeScript`, `startTransaction`, `dispose`
-- [ ] `Transaction` implements `queryRaw`, `executeRaw`, `commit`, `rollback` with `options: { usePhantomQuery: false }`
-- [ ] `commit()` and `rollback()` are lifecycle hooks only (no SQL issued)
-- [ ] `startTransaction` issues `BEGIN` (depth 1) or `SAVEPOINT sp_N` (nested)
-- [ ] Argument mapping handles: string→int, string→bigint, string→float, base64→bytes
-- [ ] Row mapping handles: bigint→string, Date→ISO string, JSON→string
-- [ ] Column types correctly mapped to `ColumnTypeEnum`
-- [ ] Errors wrapped in `DriverAdapterError` with proper `MappedError` kind
-- [ ] Isolation level validation for the target database
-- [ ] Unit tests pass for queryRaw, executeRaw, executeScript, transactions
-- [ ] E2E tests pass with real PrismaClient
+Prisma uses preserved original details when an unmapped driver error becomes `P2039`. Do not replace every unknown exception with a fabricated `GenericJs` id; rethrow genuinely unexpected non-driver errors so programming bugs remain visible.
+
+## Factory, ownership, and shadow database
+
+- `connect()` returns a fresh usable adapter connection/pool wrapper.
+- Track whether the factory created the pool. `dispose()` closes owned pools and only detaches listeners from caller-owned pools unless an explicit option transfers ownership.
+- Implement `SqlMigrationAwareDriverAdapterFactory` only when `connectToShadowDb()` can create an isolated shadow database, connect to it, and drop it during disposal/failure cleanup.
+- Never point the shadow adapter at the primary database. Quote generated identifiers and use cryptographically unique names.
+- `getConnectionInfo()` should accurately report `schemaName`, `maxBindValues` when applicable, and `supportsRelationJoins`.
+
+## Verification checklist
+
+- [ ] Typecheck against the exact target `@prisma/driver-adapter-utils` version
+- [ ] `queryRaw` preserves column order, types, nulls, and precision
+- [ ] `executeRaw` reports affected rows correctly
+- [ ] `executeScript` handles provider-specific multi-statement syntax
+- [ ] Concurrent interactive transactions use distinct dedicated connections
+- [ ] Success commits and releases once; failure rolls back and releases once
+- [ ] Nested transaction tests exercise create/rollback/release savepoint hooks
+- [ ] Unsupported isolation levels fail as `InvalidIsolationLevel`
+- [ ] Known constraints map to structured errors
+- [ ] Unmapped database errors retain original code/message and surface useful `P2039`
+- [ ] Dispose ownership is tested for internal and external pools
+- [ ] Shadow database creation, use, failure cleanup, and disposal are isolated
+- [ ] Run Prisma Client integration/E2E tests, not only adapter unit tests
+
+## Source references
+
+- [Driver adapter interfaces](https://github.com/prisma/prisma/blob/v7/packages/driver-adapter-utils/src/types.ts)
+- [PostgreSQL adapter transaction implementation](https://github.com/prisma/prisma/blob/v7/packages/adapter-pg/src/pg.ts)
+- [PostgreSQL adapter error mapping](https://github.com/prisma/prisma/blob/v7/packages/adapter-pg/src/errors.ts)
diff --git a/plugins/prisma/agent/skills/prisma-postgres/SKILL.md b/plugins/prisma/agent/skills/prisma-postgres/SKILL.md
index d49d0e83..bb8f9140 100644
--- a/plugins/prisma/agent/skills/prisma-postgres/SKILL.md
+++ b/plugins/prisma/agent/skills/prisma-postgres/SKILL.md
@@ -1,7 +1,7 @@
 ---
 description: "Prisma Postgres setup and operations guidance across Console, create-db CLI, Management API, and Management API SDK. Use when creating Prisma Postgres databases, working in Prisma Console, provisioning with create-db/create-pg/create-postgres, or integrating programmatic provisioning with service tokens or OAuth."
 license: "MIT"
-metadata: {"author":"prisma","version":"7.6.0"}
+metadata: {"author":"prisma","version":"7.9.1"}
 ---
 # Prisma Postgres
 
@@ -63,6 +63,22 @@ For app integrations, you can also use the programmatic API (`create()` / `regio
 
 Temporary databases auto-delete after ~24 hours unless claimed.
 
+### 2b. Persistent databases with the Platform CLI
+
+For databases that belong to a Project (not throwaway `create-db` databases), use `@prisma/cli`:
+
+```bash
+npx -y @prisma/cli@latest database create --help
+npx -y @prisma/cli@latest database list --json
+npx -y @prisma/cli@latest database connection create db_123
+npx -y @prisma/cli@latest database usage db_123
+npx -y @prisma/cli@latest database backup list db_123
+```
+
+`database create` and `database connection create` print a one-time connection URL; store it immediately. Destructive commands (`remove`, `restore`) require exact `--confirm <id>`.
+
+For automation, prefer `--json --no-interactive`, resolve ids before mutations, and verify the installed command's help because this CLI is beta.
+
 ### 3. Link an existing local project
 
 Use `prisma postgres link` when the database already exists and you want to wire a local project to it:
@@ -107,6 +123,8 @@ npm install @prisma/management-api-sdk
 
 Use `createManagementApiClient` for existing tokens, or `createManagementApiSdk` for OAuth + token refresh.
 
+The SDK exposes typed workspace service-token list, create, and revoke routes. A newly created token value is returned exactly once. Let the installed SDK types or OpenAPI document settle exact beta endpoint shapes.
+
 ## Rule Files
 
 Detailed guidance lives in:
diff --git a/plugins/prisma/agent/skills/prisma-postgres/references/console-and-connections.md b/plugins/prisma/agent/skills/prisma-postgres/references/console-and-connections.md
index c6e30f9a..4025d12b 100644
--- a/plugins/prisma/agent/skills/prisma-postgres/references/console-and-connections.md
+++ b/plugins/prisma/agent/skills/prisma-postgres/references/console-and-connections.md
@@ -55,6 +55,8 @@ Typical direct TCP format:
 DATABASE_URL="postgres://identifier:key@db.prisma.io:5432/postgres?sslmode=require"
 ```
 
+Management API connection responses expose both `endpoints.direct` (`db.prisma.io:5432`) and `endpoints.pooled` (`pooled.db.prisma.io:5432`); prefer those fields over the deprecated flat `connectionString`. Connection secrets are shown once at creation (one-time view); store them immediately.
+
 ## Adapter choices
 
 - Standard Node.js apps: prefer `@prisma/adapter-pg` with the direct TCP URL above.
diff --git a/plugins/prisma/agent/skills/prisma-postgres/references/management-api-sdk.md b/plugins/prisma/agent/skills/prisma-postgres/references/management-api-sdk.md
index d4ad6bb0..026aa5f8 100644
--- a/plugins/prisma/agent/skills/prisma-postgres/references/management-api-sdk.md
+++ b/plugins/prisma/agent/skills/prisma-postgres/references/management-api-sdk.md
@@ -2,6 +2,8 @@
 
 Use `@prisma/management-api-sdk` for typed API integration with optional OAuth and token refresh.
 
+The Platform API evolves independently from Prisma ORM. Inspect the installed package's generated `api.d.ts` for exact paths and request/response shapes.
+
 ## Priority
 
 HIGH
@@ -25,6 +27,18 @@ const client = createManagementApiClient({ token: process.env.PRISMA_SERVICE_TOK
 const { data: workspaces } = await client.GET('/v1/workspaces')
 ```
 
+Check the generated client result before using `data`; typed clients surface HTTP failures separately. Never log a full response from connection/key creation because it may contain one-time credentials.
+
+## Workspace service tokens
+
+The typed client exposes routes to list, create, and revoke workspace service tokens:
+
+- `GET /v1/workspaces/{workspaceId}/service-tokens`
+- `POST /v1/workspaces/{workspaceId}/service-tokens`
+- `DELETE /v1/workspaces/{workspaceId}/service-tokens/{serviceTokenId}`
+
+Creation accepts a display `name`. The response's `data.value` is the complete token and is returned exactly once; transfer it directly to the intended secret store without logging the response. Later list calls return metadata and `valueHint`, not the token value. Treat revocation as destructive and resolve both ids explicitly.
+
 ## Full SDK (OAuth + refresh)
 
 ```typescript
diff --git a/plugins/prisma/agent/skills/prisma-postgres/references/management-api.md b/plugins/prisma/agent/skills/prisma-postgres/references/management-api.md
index ff37c39e..4e4e76f9 100644
--- a/plugins/prisma/agent/skills/prisma-postgres/references/management-api.md
+++ b/plugins/prisma/agent/skills/prisma-postgres/references/management-api.md
@@ -42,17 +42,35 @@ Authorization: Bearer $TOKEN
 3. Exchange code at `https://auth.prisma.io/token`.
 4. Use returned access token in Management API requests.
 
-## Common endpoints
+## Resource model
 
-- `GET /workspaces`
-- `GET /projects`
-- `POST /projects`
-- Database management endpoints under project/database paths
+Workspace -> Project -> Branch -> Database. Branches are a first-class resource: databases attach to a Branch, and branch-scoped env/databases are how preview isolation works.
+
+## Current resource inventory
+
+The 1.55 OpenAPI surface includes:
+
+- workspaces, subscriptions, workspace integrations, workspace service tokens, and current-user metadata
+- projects, transfers, project databases, and project/branch environment variables
+- branches under a project plus branch get/update/delete operations
+- databases, usage, backups, restore, connections, and connection rotation
+- apps, deployments, promotion/rollback, runtime logs, domains, and build logs
+- buckets and bucket keys
+- source repositories, SCM installations/install intents, and repositories
+- integrations and regions
+
+App/deployment, branch mutation, SCM, and bucket routes include experimental surfaces. Read the installed SDK types or live OpenAPI before building durable automation around them.
+
+Connection create/rotate responses reveal credentials once. Later reads redact or omit the secret, so store the URL immediately. Use the structured direct/pooled endpoint returned by the concrete operation; do not assume a historical flat response shape.
+
+Workspace service-token creation also returns the complete token value exactly once. List calls expose only metadata and a `valueHint`; delete revokes the token. Keep workspace and token ids opaque, and never log a create response.
+
+Database create supports explicit project, region, branch, and source context. A source may be empty, a backup, or another database. Backup records are incremental; rely on current fields and documented units rather than old full-backup examples.
 
 ## Notes
 
-- Management API responses may include direct connection credentials for databases.
-- Build PostgreSQL `DATABASE_URL` from direct connection values when needed.
+- Management API mutation responses may include direct connection credentials; treat the entire response as secret until redacted.
+- Prefer an API-provided connection string over manually assembling one from fields.
 
 ## References
 
diff --git a/plugins/prisma/agent/skills/prisma-upgrade-v7/SKILL.md b/plugins/prisma/agent/skills/prisma-upgrade-v7/SKILL.md
index 047773ae..3bbc4096 100644
--- a/plugins/prisma/agent/skills/prisma-upgrade-v7/SKILL.md
+++ b/plugins/prisma/agent/skills/prisma-upgrade-v7/SKILL.md
@@ -37,9 +37,15 @@ Reference this skill when:
 - `removed-features` - removed middleware, metrics, and legacy CLI behavior
 - `accelerate-users` - migration notes for Accelerate users
 
+## Using MongoDB? This guide does not apply
+
+Prisma 7 has no MongoDB connector. Do not apply any step in this guide to a project with
+`provider = "mongodb"` — see the `prisma-mongodb-upgrade` skill for the actual decision
+(stay on v6 deliberately vs migrate to Prisma Next).
+
 ## Important Notes
 
-- **MongoDB projects should stay on Prisma 6.x** - do not migrate MongoDB apps to Prisma 7's SQL client path
+- **MongoDB projects should stay on Prisma 6.x or migrate to Prisma Next** - do not migrate MongoDB apps to Prisma 7's SQL client path (see `prisma-mongodb-upgrade`)
 - **Node.js 20.19.0+** required
 - **TypeScript 5.4.0+** required
 - **Latest stable Prisma ORM version**: `7.6.0`
diff --git a/plugins/prisma/skills-lock.json b/plugins/prisma/skills-lock.json
index 0396f7c1..add2ed45 100644
--- a/plugins/prisma/skills-lock.json
+++ b/plugins/prisma/skills-lock.json
@@ -5,37 +5,37 @@
       "source": "prisma/skills",
       "sourceType": "github",
       "skillPath": "prisma-cli/SKILL.md",
-      "computedHash": "1cfdc0011df8699a2ece587f229a1e892df2a9a3eec40b5407492cb4c6570e95"
+      "computedHash": "129e77cba93984b88d66cf0f66d5788f5487431f17f189a1ab2d839976874e3b"
     },
     "prisma-client-api": {
       "source": "prisma/skills",
       "sourceType": "github",
       "skillPath": "prisma-client-api/SKILL.md",
-      "computedHash": "0434410e48fb796bbdc3ad0050654bfc9cf72c89b30dbad098ee5c9f655b7f85"
+      "computedHash": "cbbabff961c8e16b2d59f8c1ffb4e7e20be52154e778ab95121e0211d6d09969"
     },
     "prisma-database-setup": {
       "source": "prisma/skills",
       "sourceType": "github",
       "skillPath": "prisma-database-setup/SKILL.md",
-      "computedHash": "46d2dc2f9c968722376bbb6a1a1389c82bd7cceb5973ac1486c54890514b8959"
+      "computedHash": "6a991a2530a6da7131e3fc71c353e8278702d0146b8b6e1d2fdfc2d3d0a21bd2"
     },
     "prisma-driver-adapter-implementation": {
       "source": "prisma/skills",
       "sourceType": "github",
       "skillPath": "prisma-driver-adapter-implementation/SKILL.md",
-      "computedHash": "2e00b0d05f0da23796f6d44684e19219b74cf993f8a2df6e5b044812f375bbc6"
+      "computedHash": "cc487f1bf36f616ddb3a9478b3527d288dd706d77a9e5dbee9af52dca1eee8e4"
     },
     "prisma-postgres": {
       "source": "prisma/skills",
       "sourceType": "github",
       "skillPath": "prisma-postgres/SKILL.md",
-      "computedHash": "d090d1206fb6a2dd9f7b9f658d851ccd653132512c53c6e0a164110d9ee80005"
+      "computedHash": "0422727e18019add9208b86ce862964025acc011ff31fba1d59a01b836bd6272"
     },
     "prisma-upgrade-v7": {
       "source": "prisma/skills",
       "sourceType": "github",
       "skillPath": "prisma-upgrade-v7/SKILL.md",
-      "computedHash": "2e4d54a4c7a0fc2476e81686718a765f5eb2cacfb2fb0822f3109c76bf4a9bb0"
+      "computedHash": "0e07dc2831f86cf27627df914db43d862b0fc75d72c1f9070434aab7940bad7c"
     }
   }
 }
diff --git a/plugins/react-native/.agents/skills/vercel-react-native-skills/metadata.json b/plugins/react-native/.agents/skills/vercel-react-native-skills/metadata.json
new file mode 100644
index 00000000..600eb5bc
--- /dev/null
+++ b/plugins/react-native/.agents/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/plugins/react-native/.claude/skills/vercel-react-native-skills b/plugins/react-native/.claude/skills/vercel-react-native-skills
new file mode 120000
index 00000000..8c988434
--- /dev/null
+++ b/plugins/react-native/.claude/skills/vercel-react-native-skills
@@ -0,0 +1 @@
+../../.agents/skills/vercel-react-native-skills
\ No newline at end of file
diff --git a/plugins/react-native/agent/skills/vercel-react-native-skills/metadata.json b/plugins/react-native/agent/skills/vercel-react-native-skills/metadata.json
new file mode 100644
index 00000000..600eb5bc
--- /dev/null
+++ b/plugins/react-native/agent/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/plugins/react-native/skills-lock.json b/plugins/react-native/skills-lock.json
index 8545c572..14674bd4 100644
--- a/plugins/react-native/skills-lock.json
+++ b/plugins/react-native/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel-labs/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/react-native-skills/SKILL.md",
-      "computedHash": "2e9088a7333666d8c2833b8ff58bd51b955501c42b4c7244f72b4cbf22dafcc4"
+      "computedHash": "41d24eafa7c3d82e270439808f7cfbc4d51aeb2d14f2809a2267c16275784d06"
     }
   }
 }
diff --git a/plugins/react/.agents/skills/vercel-composition-patterns/metadata.json b/plugins/react/.agents/skills/vercel-composition-patterns/metadata.json
new file mode 100644
index 00000000..3470b744
--- /dev/null
+++ b/plugins/react/.agents/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/plugins/react/.agents/skills/vercel-react-best-practices/metadata.json b/plugins/react/.agents/skills/vercel-react-best-practices/metadata.json
new file mode 100644
index 00000000..3bec38b1
--- /dev/null
+++ b/plugins/react/.agents/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/plugins/react/.agents/skills/vercel-react-view-transitions/metadata.json b/plugins/react/.agents/skills/vercel-react-view-transitions/metadata.json
new file mode 100644
index 00000000..aabe3e14
--- /dev/null
+++ b/plugins/react/.agents/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/plugins/react/.claude/skills/vercel-composition-patterns b/plugins/react/.claude/skills/vercel-composition-patterns
new file mode 120000
index 00000000..55a19e8f
--- /dev/null
+++ b/plugins/react/.claude/skills/vercel-composition-patterns
@@ -0,0 +1 @@
+../../.agents/skills/vercel-composition-patterns
\ No newline at end of file
diff --git a/plugins/react/.claude/skills/vercel-react-best-practices b/plugins/react/.claude/skills/vercel-react-best-practices
new file mode 120000
index 00000000..e567923b
--- /dev/null
+++ b/plugins/react/.claude/skills/vercel-react-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/vercel-react-best-practices
\ No newline at end of file
diff --git a/plugins/react/.claude/skills/vercel-react-view-transitions b/plugins/react/.claude/skills/vercel-react-view-transitions
new file mode 120000
index 00000000..78a32226
--- /dev/null
+++ b/plugins/react/.claude/skills/vercel-react-view-transitions
@@ -0,0 +1 @@
+../../.agents/skills/vercel-react-view-transitions
\ No newline at end of file
diff --git a/plugins/react/agent/skills/vercel-composition-patterns/metadata.json b/plugins/react/agent/skills/vercel-composition-patterns/metadata.json
new file mode 100644
index 00000000..3470b744
--- /dev/null
+++ b/plugins/react/agent/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/plugins/react/agent/skills/vercel-react-best-practices/metadata.json b/plugins/react/agent/skills/vercel-react-best-practices/metadata.json
new file mode 100644
index 00000000..3bec38b1
--- /dev/null
+++ b/plugins/react/agent/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/plugins/react/agent/skills/vercel-react-view-transitions/metadata.json b/plugins/react/agent/skills/vercel-react-view-transitions/metadata.json
new file mode 100644
index 00000000..aabe3e14
--- /dev/null
+++ b/plugins/react/agent/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/plugins/react/skills-lock.json b/plugins/react/skills-lock.json
index 90bc6dcb..82fa09e5 100644
--- a/plugins/react/skills-lock.json
+++ b/plugins/react/skills-lock.json
@@ -5,19 +5,19 @@
       "source": "vercel-labs/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/composition-patterns/SKILL.md",
-      "computedHash": "f98931159fa9c7fed043bcd18a891a46dcf89ababa38df13a4c5b7b30dc0ce07"
+      "computedHash": "575757e3e25761c8c562d6e395d29f0b76c98b1273c0bd72d88e6ab1bc9c7d42"
     },
     "vercel-react-best-practices": {
       "source": "vercel-labs/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/react-best-practices/SKILL.md",
-      "computedHash": "3219a1944e404ffc14d1d9d6aef6dd2e3855b81387ee0a044ccbfe14d34c2357"
+      "computedHash": "ca7b0c0c6e5f2750043f7f0cd72d16ac4e2abc48f9b5500d047a4b77a2506212"
     },
     "vercel-react-view-transitions": {
       "source": "vercel-labs/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/react-view-transitions/SKILL.md",
-      "computedHash": "4fea9144f604256d0a21faaea904b7e205e7676e316721ba5fdd68c2600c7d42"
+      "computedHash": "c8952fc9127fa0564d0cb71dccb4215a5608ac933b5831104f09173a97a46f85"
     }
   }
 }
diff --git a/plugins/shadcn-ui/.agents/skills/shadcn/SKILL.md b/plugins/shadcn-ui/.agents/skills/shadcn/SKILL.md
index 8c01af92..1b4c414c 100644
--- a/plugins/shadcn-ui/.agents/skills/shadcn/SKILL.md
+++ b/plugins/shadcn-ui/.agents/skills/shadcn/SKILL.md
@@ -64,7 +64,9 @@ These rules are **always enforced**. Each links to a file with Incorrect/Correct
 - **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
 - **Callouts use `Alert`.** Don't build custom styled divs.
 - **Empty states use `Empty`.** Don't build custom empty state markup.
-- **Toast via `sonner`.** Use `toast()` from `sonner`.
+- **Toast follows the project base.** Use `toast` from the `toast` component for
+  Base UI projects. Use `toast()` from `sonner` for Radix and React Aria
+  projects.
 - **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
 - **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
 - **Use `Badge`** instead of custom styled spans.
@@ -135,7 +137,7 @@ These are the most common patterns that differentiate correct shadcn/ui code. Fo
 | Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
 | Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
 | Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
-| Feedback                   | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner`                                        |
+| Feedback                   | `toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`                 |
 | Command palette            | `Command` inside `Dialog`                                                                           |
 | Charts                     | `Chart` (wraps Recharts)                                                                            |
 | Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
diff --git a/plugins/shadcn-ui/.agents/skills/shadcn/rules/composition.md b/plugins/shadcn-ui/.agents/skills/shadcn/rules/composition.md
index 0654245a..a8aa4274 100644
--- a/plugins/shadcn-ui/.agents/skills/shadcn/rules/composition.md
+++ b/plugins/shadcn-ui/.agents/skills/shadcn/rules/composition.md
@@ -5,7 +5,7 @@
 - Items always inside their Group component
 - Callouts use Alert
 - Empty states use Empty component
-- Toast notifications use sonner
+- Toast notifications follow the project base
 - Choosing between overlay components
 - Dialog, Sheet, and Drawer always need a Title
 - Card structure
@@ -88,7 +88,19 @@ Chat components nest in a fixed order (`MessageScrollerProvider` → `MessageScr
 
 ---
 
-## Toast notifications use sonner
+## Toast notifications follow the project base
+
+For Base UI projects, use the `toast` component:
+
+```tsx
+import { toast } from "@/components/ui/toast"
+
+toast.add({
+  title: "Changes saved.",
+})
+```
+
+For Radix and React Aria projects, use Sonner:
 
 ```tsx
 import { toast } from "sonner"
diff --git a/plugins/shadcn-ui/.claude/skills/migrate-radix-to-base b/plugins/shadcn-ui/.claude/skills/migrate-radix-to-base
new file mode 120000
index 00000000..1ee49446
--- /dev/null
+++ b/plugins/shadcn-ui/.claude/skills/migrate-radix-to-base
@@ -0,0 +1 @@
+../../.agents/skills/migrate-radix-to-base
\ No newline at end of file
diff --git a/plugins/shadcn-ui/.claude/skills/shadcn b/plugins/shadcn-ui/.claude/skills/shadcn
new file mode 120000
index 00000000..8d5af6f6
--- /dev/null
+++ b/plugins/shadcn-ui/.claude/skills/shadcn
@@ -0,0 +1 @@
+../../.agents/skills/shadcn
\ No newline at end of file
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/SKILL.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/SKILL.md
new file mode 100644
index 00000000..005e00b3
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/SKILL.md
@@ -0,0 +1,171 @@
+---
+description: "Migrates React projects and components from Radix UI to Base UI. Use when asked to migrate from radix, move to base-ui, convert radix primitives, or switch a shadcn project's base library. Handles single components (\"migrate accordion\") and whole projects."
+---
+# Radix UI -> Base UI migration
+
+You migrate shadcn wrappers, hand-rolled radix compositions, and their
+consumers to `@base-ui/react`, keeping the project buildable at every step.
+Be precise; never guess a mapping. When a prop or part is not in these
+reference files, check `node_modules/@base-ui/react/**/*.d.ts` before
+transforming, and record gaps in the report.
+
+## Preflight (always)
+
+1. `npx shadcn@latest info --json` (or the project's runner): gives the
+   current base, STYLE (e.g. `radix-lyra`), tailwind version, aliases,
+   installed components, and package manager. Trust it over inference.
+2. Detect the package manager (packageManager field / lockfile:
+   pnpm-lock.yaml, bun.lock, yarn.lock, package-lock.json) and use IT for
+   every install. Never leave a stale lockfile.
+3. Require a clean git tree; work on a branch; one commit per component.
+4. Baseline check BEFORE touching dependencies: run the project's
+   typecheck/build so pre-existing failures are never attributed to you.
+5. Install `@base-ui/react` alongside radix. Radix packages are removed only
+   after the LAST component is migrated (both coexist fine).
+
+## Strategy: golden pair first, transformation engine second
+
+- **Golden pair via the CLI (preferred).** If the project is shadcn with a
+  known style (`radix-<style>`), the shadcn CLI itself is the golden-pair
+  executor:
+  1. Classify each ui wrapper FIRST: diff the user's file against its stock
+     origin, using the components.json style VERBATIM in the URL
+     (`https://ui.shadcn.com/r/styles/<style>/<component>.json`,
+     files[0].content). This works for prefixed styles (radix-nova) AND
+     legacy unprefixed ones (new-york, new-york-v4, default), which are all
+     still served.
+  2. WHOLE-PROJECT mode: flip `components.json` style `radix-<style>` ->
+     `base-<style>` now. PROGRESSIVE mode: do NOT flip yet (the project is
+     still mostly radix; the flip happens once, after the last component);
+     fetch base variants directly by URL instead
+     (`https://ui.shadcn.com/r/styles/base-<style>/<component>.json`).
+  3. PRISTINE wrappers, whole-project mode: `shadcn add <component>
+     --overwrite` delivers the base variant with the project's exact
+     icon/font/preset resolution. Never bulk `--all --overwrite`; go
+     component by component, or you drown in unrelated registry version
+     drift. PROGRESSIVE mode: never use `--overwrite` (it destroys the
+     original that consumers still import); write the fetched base variant
+     content to `<component>-base.tsx` instead.
+  4. CUSTOMIZED wrappers: fetch the base variant and replay the user's diff
+     onto it (their customizations must SURVIVE; `--overwrite` would destroy
+     them). Mechanical implementation that works at scale:
+     `git merge-file user.tsx radix-golden.tsx base-golden.tsx` (three-way
+     merge, radix golden as ancestor) auto-resolves most files; hand-resolve
+     conflicts with the reference tables.
+  5. MANDATORY leftover sweep on EVERY golden-pair file, including ones that
+     merged "clean": `grep -n "radix-ui\|@radix-ui\|IconPlaceholder"` per
+     file. The registry sometimes reorders functions between variants, which
+     makes three-way merges report zero conflicts while leaving stale radix
+     hunks in place. A clean merge is NOT proof of a clean file.
+  This is more reliable than reconstructing transforms; use it whenever the
+  pair exists. Consumer/app code has no CLI mechanism: always hand-migrate it
+  against `consumer-props.md`.
+- **Legacy styles (new-york, new-york-v4, default): classification only, no
+  replay.** These have no base counterpart (there is no base-new-york), and
+  retargeting onto a base-<style> variant would restyle the user's app. Use
+  the radix golden ONLY to detect customizations, then run the transformation
+  engine on the user's OWN file: rewire primitives, keep their exact classes,
+  apply class-mapping renames. Their look stays theirs. At the end of a
+  legacy whole-project migration, FLAG (do not fix): the style name still
+  reads as radix to the CLI, so future `shadcn add` will deliver radix
+  variants; the user decides whether to switch style or add manually.
+- **Transformation engine (fallback).** Hand-rolled radix code, non-shadcn
+  projects, unknown styles: transform using `universal-patterns.md` (imports
+  in BOTH forms: `radix-ui` and `@radix-ui/react-*`; asChild->render with the
+  worked example; Portal>Positioner>Popup; the positioner FORWARD rule; part
+  renames), the per-family props tables (`overlays.md`, `menus.md`,
+  `form-controls.md`, `disclosure.md`, `display-misc.md`), `class-mapping.md`
+  for data-attribute/CSS-var rewrites, and `wrapper-shapes.md` for exact
+  target shapes (tooltip arrow, SubContent defaults, select anatomy).
+
+## Modes
+
+**Progressive (default).** "Migrate accordion" = one component, strangler-fig:
+1. Detect in-progress state first: an existing `<component>-base.tsx`,
+   consumers split between old/new imports. The files ARE the state; resume,
+   never restart.
+2. If the component imports other ui wrappers still on radix (select ->
+   button), STOP and recommend migrating those first, bottom-up.
+3. Write the migrated version to `<component>-base.tsx` (original untouched;
+   golden-pair content fetched by URL, or transformed by hand, per the
+   strategy above); typecheck. Repoint consumers ONE AT A TIME (imports + the
+   call-site props in `consumer-props.md`); typecheck each. When no consumer
+   imports the original: delete it, rename `-base` -> original, flip imports
+   back, final check, commit. When the LAST radix wrapper in the project is
+   finalized, flip `components.json` to `base-<style>` and remove radix deps.
+
+**Whole project** (only when explicitly asked): same per-component work in
+dependency order (leaf/shared wrappers like button and label first). After
+wrappers, sweep ALL app code against `consumer-props.md` — the call-site
+break surface is much larger than asChild. Then remove radix deps, install,
+full build.
+
+## Hard rules
+
+- NEVER touch non-radix libraries or their wrappers: cmdk (command), vaul
+  (drawer), sonner, input-otp, react-day-picker (calendar), recharts (chart).
+  Report them as intentionally untouched.
+- No Base UI counterpart: AspectRatio -> CSS aspect-ratio div; Label ->
+  native `<label>`; VisuallyHidden -> `sr-only`; Direction -> Direction
+  Provider (`direction` prop, not `dir`). Popover Anchor and NavigationMenu
+  Indicator have no equivalent: inert passthrough + flag.
+- `button.tsx` migrates to the REAL `@base-ui/react/button` primitive, never
+  a hand-rolled useRender wrapper.
+- Behavior deltas are FLAGGED, never silently patched (tabs manual
+  activation, menu items not closing on click, nav-menu 50ms delay). The
+  target is idiomatic Base UI matching the shadcn base registry.
+- Honest reporting: skipped/reverted files are listed as flagged, never as
+  migrated. Pre-existing failures are named as pre-existing.
+
+## Verify and report
+
+Typecheck per file, build per batch, full build at the end vs the baseline.
+
+Reports live in a `.migration/` directory at the project root, ONE FILE PER
+COMPONENT: `.migration/<component>.md` (e.g. `.migration/accordion.md`).
+Rules:
+- Each run writes (or fully overwrites) the file for each component it
+  migrated. Re-running a component replaces its report; never touch other
+  components' files.
+- A multi-component run ("migrate alert-dialog and dropdown-menu") writes one
+  file per component, each self-contained; shared consumer-sweep notes are
+  repeated in every affected file.
+- Whole-project mode writes the per-component files plus
+  `.migration/project.md` (dependency swap, app-code sweep summary, final
+  build result).
+- There is NO index file. Migration status is derived from disk, not
+  maintained: scan the project's ui directory (the `ui` alias from shadcn
+  info, e.g. components/ui or src/components/ui) for remaining radix imports
+  when asked "what's left". End every run's summary with that derived count
+  ("N wrappers remain on Radix").
+
+Each `.migration/<component>.md` uses EXACTLY this structure (it is
+documented publicly; reports must match it):
+
+```md
+# <component>
+
+<date, strategy used (golden pair via CLI / merge / engine), one-line verdict>
+
+## Changed
+
+<every file touched, with what changed and why; include file:line for
+anything notable. Confirm the leftover scan is clean:
+grep -n "radix-ui\|@radix-ui" on this component's files>
+
+## Left alone
+
+<files that look related but were intentionally not touched, with the reason
+(cmdk/vaul/sonner are not radix; unrelated drift; etc.)>
+
+## Behavior changes
+
+<differences that compile fine but act differently; flagged, never patched
+(tabs activation, menu close-on-click, delays...). Empty section if none>
+
+## Verify by hand
+
+<short manual QA checklist for this primitive family: focus return on
+dialogs, keyboard nav + typeahead on menus/select, tooltip delay feel,
+slider commit events. Concrete steps, one minute of clicking>
+```
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/class-mapping.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/class-mapping.md
new file mode 100644
index 00000000..e6130b70
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/class-mapping.md
@@ -0,0 +1,62 @@
+# Class-string rewrites (layer 2)
+
+Apply these across ALL class strings (className, cva definitions, cn calls),
+including app code. They are safe, mechanical rewrites.
+
+## Data-attribute selectors
+
+| Radix pattern | Base UI pattern |
+|---|---|
+| `data-[state=open]:` | `data-open:` |
+| `data-[state=closed]:` | `data-closed:` |
+| `data-[state=checked]:` | `data-checked:` |
+| `data-[state=unchecked]:` | `data-unchecked:` |
+| `data-[state=active]:` (tabs) | `data-active:` |
+| `data-[state=on]:` (toggle) | `data-pressed:` |
+| `data-[highlighted]:` | `data-highlighted:` (unchanged) |
+| `data-[disabled]:` | `data-disabled:` (unchanged) |
+| `data-[side=...]:` | `data-[side=...]:` (unchanged, still parameterized) |
+| `group-data-[state=open]` / `peer-data-[state=open]` | `group-data-open` / `peer-data-open` |
+| submenu trigger open marker `data-[state=open]:` | `data-popup-open:` |
+
+## Animation idiom
+
+Radix (tw-animate/keyframes):
+`data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=closed]:fade-out-0`
+
+Base UI (transition + starting/ending styles):
+`transition-[opacity,transform] data-starting-style:opacity-0 data-ending-style:opacity-0` (plus translate/scale equivalents).
+
+Do not translate animate-in/out utilities 1:1; restate the intent with
+`data-starting-style:` / `data-ending-style:` transitions. When the original
+uses per-side slide classes, keep the `data-[side=...]` or
+`data-[swipe-direction=...]` parameterization.
+
+## CSS variables
+
+| Radix var | Base UI var |
+|---|---|
+| `--radix-<comp>-content-transform-origin` | `--transform-origin` |
+| `--radix-<comp>-content-available-height` | `--available-height` |
+| `--radix-<comp>-content-available-width` | `--available-width` |
+| `--radix-<comp>-trigger-width` | `--anchor-width` |
+| `--radix-<comp>-trigger-height` | `--anchor-height` |
+| `--radix-accordion-content-height` | `--accordion-panel-height` |
+| `--radix-collapsible-content-height` | `--collapsible-panel-height` |
+| `--radix-navigation-menu-viewport-height/width` | `--positioner-height` / `--positioner-width` |
+
+## Element changes kill pseudo-class variants
+
+When a part's rendered element changes from a form control to a generic
+element (checkbox/switch/radio Roots render `<span>` in Base UI), `disabled:`
+and `:disabled` Tailwind variants become dead code. Replace them with
+`data-disabled:` equivalents. (Note: the shadcn base registry's checkbox
+still carries the dead `disabled:*` classes; treat that as an upstream quirk,
+not a pattern to copy.)
+
+## Disabled-state hooks
+
+Some Base UI triggers surface disabled state as `aria-disabled` rather than
+the `disabled` attribute (accordion trigger, tabs tab). Where the radix code
+used `disabled:opacity-50`, add or substitute `aria-disabled:opacity-50`
+according to the wrapper's reference file.
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/consumer-props.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/consumer-props.md
new file mode 100644
index 00000000..92e1d90d
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/consumer-props.md
@@ -0,0 +1,58 @@
+# Consumer-side prop changes (call sites, not wrappers)
+
+The shadcn wrapper NAMES survive a radix -> base-ui migration, but these props
+change or disappear at CALL SITES in app code. Sweep every consumer for this
+list after migrating the wrappers. All entries verified against
+@base-ui/react@1.6.0 type definitions during real migrations; when in doubt,
+check node_modules/@base-ui/react/**/*.d.ts, never guess.
+
+## Universal
+
+| Radix | Base UI | Call-site action |
+|---|---|---|
+| `asChild` (any wrapper) | `render` prop | `<Trigger asChild><Button/></Trigger>` -> `<Trigger render={<Button/>}>...` |
+
+## Per component
+
+| Component | Radix prop | Base UI fate | Call-site action |
+|---|---|---|---|
+| Accordion | `type="single"\|"multiple"` + `collapsible` | dropped; `value`/`defaultValue` are ALWAYS arrays; multiple-open via `multiple` | `type="single" collapsible` -> remove both; wrap values in arrays; `type="multiple"` -> `multiple` |
+| Tabs | `activationMode="manual"` | dropped; Base UI defaults to MANUAL activation | remove prop; near-equivalent opt-in is `Tabs.List activateOnFocus` (behavior delta: flag, do not auto-add) |
+| Select | `position="popper"\|"item-aligned"` | `alignItemWithTrigger` boolean (on Positioner; wrappers expose it) | `position="popper"` -> `alignItemWithTrigger={false}`; `item-aligned` -> `alignItemWithTrigger` (default) |
+| TooltipProvider | `delayDuration`, `skipDelayDuration` | `delay`; skip-delay concept dropped | rename / remove |
+| Tooltip | `disableHoverableContent` | NO equivalent | remove; FLAG the behavior change in the report |
+| Avatar.Image | `delayMs` | `delay` | rename |
+| ScrollArea | `type="always"\|"scroll"\|...` | dropped | remove |
+| Separator | `decorative` | dropped | remove |
+| Checkbox | `checked="indeterminate"` | `indeterminate` is a SEPARATE boolean prop | `checked="indeterminate"` -> `indeterminate` + boolean `checked` |
+| Slider | `onValueChange(value)` | signature gains event details; also `inverted` REMOVED | check handler arity; remove `inverted` (flag vertical-inverted usage) |
+| Select | `onValueChange(value: string)` | widens to `(value: Value \| null, eventDetails)` | `useState<string>` + `onValueChange={setState}` breaks: widen state to `string \| null` or wrap the setter |
+| Slider | `onValueCommit` | `onValueCommitted` | rename |
+| ToggleGroup | `type="single"\|"multiple"` | `multiple` boolean; value shape arrays | same treatment as Accordion |
+| ToggleGroup / Toolbar | `rovingFocus={false}` | dropped (roving focus always on); `loop` -> `loopFocus` | remove / rename |
+| Menubar | `value`/`onValueChange` (active menu) | dropped; control per Menu.Root `open` | restructure if used; usually unused |
+| Menubar | `loop` | `loopFocus` | rename |
+| ContextMenu.Root | `modal` | REMOVED | remove |
+| ContextMenu.Trigger | `disabled` | REMOVED | remove; gate the trigger yourself |
+| DropdownMenu/ContextMenu items | (Radix closed menu on select) | `closeOnClick` defaults FALSE on CheckboxItem/RadioItem | behavior delta: flag; add `closeOnClick` only if the user asks |
+| NavigationMenu | `delayDuration`(200), `skipDelayDuration`, `viewport` | `delay`(50) + `closeDelay`; viewport prop gone (Positioner handles it) | rename/remove; flag the 200->50 hover-delay feel change |
+| Popover / HoverCard | `openDelay`/`closeDelay` on Root | move to TRIGGER as `delay`/`closeDelay` | relocate props Root -> Trigger |
+| Dialog / AlertDialog | `onOpenAutoFocus` | `initialFocus` (element/ref-based, not event-based) | restructure: pass target instead of preventDefault handler |
+| Dialog / AlertDialog | `onCloseAutoFocus` | `finalFocus` | same restructure |
+| Dialog family | `onEscapeKeyDown`, `onPointerDownOutside`, `onInteractOutside` | consolidated; see the overlays reference for exact per-part signatures | consult overlays.md; do not guess |
+| DirectionProvider | `dir` | `direction` | rename |
+
+## Callback signature rule
+
+Base UI callbacks commonly gain an event-details argument:
+`onOpenChange(open, eventDetails)`, `onValueChange(value, eventDetails)`.
+Passing an existing single-arg handler stays type-safe; handlers that USED
+Radix's event parameter need review against the family reference file.
+
+## Sweep procedure
+
+1. grep app code (outside components/ui) for each LHS token above plus
+   `asChild`.
+2. Fix call sites file by file; typecheck after each file.
+3. Anything on this list marked FLAG goes into the migration report as a
+   behavior delta, never silently patched.
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/disclosure.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/disclosure.md
new file mode 100644
index 00000000..2d40cdcd
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/disclosure.md
@@ -0,0 +1,353 @@
+# Radix → Base UI props mapping: disclosure + toggle family
+
+Scope: accordion, collapsible, tabs, toggle, toggle-group, toolbar.
+Sources: radix-ui.com primitives docs + base-ui.com `.md` docs, cross-checked against installed `@base-ui/react@1.6.0` `.d.ts` files (the published docs page for accordion lagged; types are authoritative here).
+
+Conventions that apply to every component below:
+
+- `asChild` (boolean, default `false`) → `render` (`ReactElement | (props: HTMLProps, state) => ReactElement`). Signature changed: instead of a lone child element, pass the element to `render`; Base UI merges props onto it. Button-rendering parts additionally accept `nativeButton` (default `true`), set it to `false` when `render` produces a non-`<button>` element.
+- Base UI `className` and `style` also accept a `(state) => value` function form.
+- Radix `data-[state=...]` value attributes become Base UI presence attributes (`data-open`, `data-closed`, `data-pressed`, `data-active`).
+- Base UI change callbacks all gained a second `eventDetails` argument (`{ reason, event, cancel(), ... }`).
+- Radix `dir` props are dropped everywhere; Base UI reads direction from the DOM `dir` attribute / `DirectionProvider`.
+
+---
+
+# accordion
+
+Part mapping: `Root → Root`, `Item → Item`, `Header → Header`, `Trigger → Trigger`, `Content → Panel`.
+
+## Accordion.Root → Accordion.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. Pass element to `render` instead of wrapping a child. |
+| `type` (required) | `"single" \| "multiple"` / — | `multiple` | Signature changed. `type="multiple"` → `multiple` (boolean, default `false`); `type="single"` → omit. |
+| `value` | `string` (single) or `string[]` (multiple) / — | `value` | Signature changed. Base UI is ALWAYS an array (`Value[]`, `Value = any`), even in single mode: `value="a"` → `value={["a"]}`. |
+| `defaultValue` | `string` or `string[]` / — | `defaultValue` | Same array caveat as `value`. |
+| `onValueChange` | `(value: string) => void` or `(value: string[]) => void` / — | `onValueChange` | Signature changed: `(value: Value[], eventDetails: Accordion.Root.ChangeEventDetails) => void`. Always receives an array; unwrap `value[0]` for single mode. |
+| `collapsible` | `boolean` / `false` | — dropped | Base UI single mode is always collapsible. To forbid closing the last open item (Radix `collapsible={false}` default), control `value` and ignore updates where the array is empty, or call `eventDetails.cancel()` when `value.length === 0`. |
+| `disabled` | `boolean` / `false` | `disabled` (default `false`) | Same. |
+| `dir` | `"ltr" \| "rtl"` / `"ltr"` | — dropped | Use DOM `dir` attribute / `DirectionProvider`. |
+| `orientation` | `"vertical" \| "horizontal"` / `"vertical"` | — dropped (prop exists but deprecated no-op) | Base UI removed roving arrow-key focus per the APG guidance update, so `orientation` (and `loopFocus`) no longer affect keyboard behavior. Do not carry it over. |
+
+## Accordion.Item → Accordion.Item
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `value` (required) | `string` / — | `value` | Renamed constraint: Base UI `value` is `any` and OPTIONAL (auto-generated from index when omitted). Keep passing strings for parity. |
+| `disabled` | `boolean` / `false` | `disabled` (default `false`) | Same. |
+
+## Accordion.Header → Accordion.Header
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. Both render `<h3>` by default. |
+
+## Accordion.Trigger → Accordion.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+
+## Accordion.Content → Accordion.Panel
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `forceMount` | `true \| undefined` / — | `keepMounted` (boolean, default `false`) | Renamed. `forceMount` → `keepMounted` (closed panel stays in DOM, hidden). Also available on `Root` to apply to all panels. |
+
+## Base UI only props worth knowing
+
+- `Root.hiddenUntilFound` / `Panel.hiddenUntilFound` (default `false`): uses `hidden="until-found"` so browser find-in-page can expand panels; overrides `keepMounted`. No Radix equivalent.
+- `Root.keepMounted`: root-level version of the per-panel prop.
+- `Item.onOpenChange`: `(open: boolean, eventDetails: Accordion.Item.ChangeEventDetails) => void`, per-item open callback. No Radix equivalent.
+- `Trigger.nativeButton` (default `true`).
+- `className` / `style` state-function forms on every part.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Item/Header/Content [data-state="open" \| "closed"]` | `Item`, `Header`: `data-open` (presence); `Panel`: `data-open` (presence) | No `data-closed` on accordion parts (unlike collapsible); style closed state as the absence of `data-open`. |
+| `Trigger [data-state="open"]` | `Trigger [data-panel-open]` | Renamed. Trigger specifically uses `data-panel-open`, NOT `data-open`. |
+| `[data-disabled]` | `[data-disabled]` | Same (Root, Item, Header, Trigger, Panel). |
+| `[data-orientation]` (all parts) | `Root`, `Panel`: `data-orientation` | Deprecated along with orientation; avoid relying on it. |
+| — | `Item/Header/Panel [data-index]` | Base UI only: numeric item index. |
+| — | `Panel [data-starting-style]`, `[data-ending-style]` | Base UI only: CSS-transition animation hooks (replace Radix mount/unmount animation pattern). |
+
+## CSS var mapping
+
+| Radix | Base UI |
+|---|---|
+| `--radix-accordion-content-height` | `--accordion-panel-height` |
+| `--radix-accordion-content-width` | `--accordion-panel-width` |
+
+---
+
+# collapsible
+
+Part mapping: `Root → Root`, `Trigger → Trigger`, `Content → Panel`.
+
+## Collapsible.Root → Collapsible.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `defaultOpen` | `boolean` / — | `defaultOpen` (default `false`) | Same. |
+| `open` | `boolean` / — | `open` | Same. |
+| `onOpenChange` | `(open: boolean) => void` / — | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: Collapsible.Root.ChangeEventDetails) => void`. |
+| `disabled` | `boolean` / — | `disabled` (default `false`) | Same. |
+
+## Collapsible.Trigger → Collapsible.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+
+## Collapsible.Content → Collapsible.Panel
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `forceMount` | `true \| undefined` / — | `keepMounted` (boolean, default `false`) | Renamed. |
+
+## Base UI only props worth knowing
+
+- `Panel.hiddenUntilFound` (default `false`): find-in-page support via `hidden="until-found"`; overrides `keepMounted`.
+- `Trigger.nativeButton` (default `true`).
+- `className` / `style` state-function forms.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Root/Content [data-state="open" \| "closed"]` | `Panel [data-open]` / `[data-closed]` | Renamed to presence attributes. Base UI Root renders a plain `<div>`; state attrs live on Panel/Trigger. |
+| `Trigger [data-state="open"]` | `Trigger [data-panel-open]` | Renamed; trigger-specific name. |
+| `[data-disabled]` | — (not emitted on collapsible parts) | Gate styles on the `disabled` prop / `:disabled` on the trigger instead. |
+| — | `Panel [data-starting-style]`, `[data-ending-style]` | Base UI only: animation hooks. |
+
+## CSS var mapping
+
+| Radix | Base UI |
+|---|---|
+| `--radix-collapsible-content-height` | `--collapsible-panel-height` |
+| `--radix-collapsible-content-width` | `--collapsible-panel-width` |
+
+---
+
+# tabs
+
+Part mapping: `Root → Root`, `List → List`, `Trigger → Tab`, `Content → Panel`. Base UI adds an `Indicator` part with no Radix equivalent.
+
+## Tabs.Root → Tabs.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `defaultValue` | `string` / — | `defaultValue` | Signature changed: Base UI value type is `Tabs.Tab.Value` (`any`), default `0` (first tab active by default; Radix has no default active tab). Strings still work unchanged. |
+| `value` | `string` / — | `value` | Same shape for string values; type widened to `any`. |
+| `onValueChange` | `(value: string) => void` / — | `onValueChange` | Signature changed: `(value: Tabs.Tab.Value, eventDetails: Tabs.Root.ChangeEventDetails) => void`. |
+| `orientation` | `"horizontal" \| "vertical"` / `"horizontal"` | `orientation` (default `'horizontal'`) | Same. |
+| `dir` | `"ltr" \| "rtl"` / — | — dropped | Use DOM `dir` / `DirectionProvider`. |
+| `activationMode` | `"automatic" \| "manual"` / `"automatic"` | moved + renamed: `List.activateOnFocus` (boolean, default `false`) | Moved from Root to List and inverted DEFAULT: Radix defaults to automatic, Base UI 1.6.0 defaults to `false` (manual). To preserve Radix default behavior set `<Tabs.List activateOnFocus>`; `activationMode="manual"` → omit. |
+
+## Tabs.List → Tabs.List
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `loop` | `boolean` / `true` | `loopFocus` (default `true`) | Renamed. |
+
+## Tabs.Trigger → Tabs.Tab
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+| `value` (required) | `string` / — | `value` (required) | Type widened to `Tabs.Tab.Value` (`any`); strings unchanged. |
+| `disabled` | `boolean` / `false` | `disabled` | Same. |
+
+## Tabs.Content → Tabs.Panel
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `value` (required) | `string` / — | `value` (required) | Type widened; strings unchanged. |
+| `forceMount` | `true \| undefined` / — | `keepMounted` (boolean, default `false`) | Renamed. Hidden panels stay in DOM with `data-hidden`. |
+
+## Base UI only props worth knowing
+
+- `Tabs.Indicator`: new part, a `<span>` that tracks the active tab for sliding-highlight UIs; `renderBeforeHydration` (default `false`) for SSR-flash avoidance. Exposes the `--active-tab-*` CSS vars below.
+- `List.activateOnFocus` (see above).
+- `Tab.nativeButton`, state-function `className`/`style` on all parts.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Trigger [data-state="active" \| "inactive"]` | `Tab [data-active]` (presence) | Renamed. Inactive = absence of `data-active`. |
+| `Content [data-state="active" \| "inactive"]` | `Panel [data-hidden]` (presence when hidden) | Inverted polarity: Radix marks the active state, Base UI marks the hidden state. |
+| `[data-orientation]` (all parts) | `[data-orientation]` (Root, List, Tab, Panel, Indicator) | Same. |
+| `Trigger [data-disabled]` | `Tab [data-disabled]` | Same. |
+| — | `[data-activation-direction]` (`'left' \| 'right' \| 'up' \| 'down' \| 'none'`, all parts) | Base UI only: direction of the last tab change, useful for directional animations. |
+| — | `Panel [data-index]`, `[data-starting-style]`, `[data-ending-style]` | Base UI only. |
+
+## CSS var mapping
+
+Radix Tabs exposes no CSS variables. Base UI only (on `Indicator`): `--active-tab-left`, `--active-tab-right`, `--active-tab-top`, `--active-tab-bottom`, `--active-tab-width`, `--active-tab-height`.
+
+---
+
+# toggle
+
+Part mapping: `Toggle.Root → Toggle` (single-part; Base UI export is directly callable, no `.Root`).
+
+## Toggle.Root → Toggle
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+| `defaultPressed` | `boolean` / — | `defaultPressed` (default `false`) | Same. |
+| `pressed` | `boolean` / — | `pressed` | Same. |
+| `onPressedChange` | `(pressed: boolean) => void` / — | `onPressedChange` | Signature changed: `(pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void`. |
+| `disabled` | `boolean` / — | `disabled` (default `false`) | Same. |
+
+## Base UI only props worth knowing
+
+- `value?: string`: identifies the toggle inside a Base UI `ToggleGroup` (this replaces Radix `ToggleGroup.Item`'s `value`, see toggle-group below).
+- `nativeButton` (default `true`), state-function `className`/`style`.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `[data-state="on" \| "off"]` | `[data-pressed]` (presence) | Renamed. Off = absence of `data-pressed`. |
+| `[data-disabled]` | `[data-disabled]` | Same. |
+
+## CSS var mapping
+
+None on either side.
+
+---
+
+# toggle-group
+
+Part mapping: `ToggleGroup.Root → ToggleGroup` (callable single export), `ToggleGroup.Item → Toggle` (Base UI reuses the Toggle primitive as group items).
+
+## ToggleGroup.Root → ToggleGroup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `type` (required) | `"single" \| "multiple"` / — | `multiple` (boolean, default `false`) | Signature changed, same pattern as accordion. |
+| `value` | `string` (single) or `string[]` (multiple) / — | `value` | Signature changed: always `readonly Value[]` (array), even single mode. `value="bold"` → `value={["bold"]}`. |
+| `defaultValue` | `string` or `string[]` / — | `defaultValue` | Same array caveat. |
+| `onValueChange` | `(value: string) => void` or `(value: string[]) => void` / — | `onValueChange` | Signature changed: `(groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void`. Always an array; single mode with nothing pressed = `[]` (Radix single mode signals this as `""`). |
+| `disabled` | `boolean` / `false` | `disabled` (default `false`) | Same. |
+| `rovingFocus` | `boolean` / `true` | — dropped | Roving focus is always on in Base UI; no opt-out. If you relied on `rovingFocus={false}` (every item tabbable), there is no direct workaround. |
+| `orientation` | `"horizontal" \| "vertical"` / `undefined` | `orientation` (default `'horizontal'`) | Same name; Base UI has an explicit default. |
+| `dir` | `"ltr" \| "rtl"` / — | — dropped | Use DOM `dir` / `DirectionProvider`. |
+| `loop` | `boolean` / `true` | `loopFocus` (default `true`) | Renamed. |
+
+## ToggleGroup.Item → Toggle
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+| `value` (required) | `string` / — | `value` | Same meaning; on Base UI's `Toggle` it is optional in the type but required in practice for group membership. |
+| `disabled` | `boolean` / — | `disabled` (default `false`) | Same. |
+
+Note: the item also gains the full standalone `Toggle` API (`pressed`, `defaultPressed`, `onPressedChange` with `eventDetails`) since it IS the Toggle primitive; inside a group the group value normally drives pressed state.
+
+## Base UI only props worth knowing
+
+- `multiple` (covered above) and the always-array value model.
+- Items are plain `Toggle`s, so per-item `onPressedChange` is available.
+- State-function `className`/`style`.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Item [data-state="on" \| "off"]` | `Toggle [data-pressed]` (presence) | Renamed. |
+| `Item [data-disabled]` | `Toggle [data-disabled]` | Same. |
+| `Root/Item [data-orientation]` | `ToggleGroup [data-orientation]` | On the group only; items (Toggles) do not emit it. |
+| — | `ToggleGroup [data-disabled]`, `[data-multiple]` | Base UI only. |
+
+## CSS var mapping
+
+None on either side.
+
+---
+
+# toolbar
+
+Part mapping: `Root → Root`, `Button → Button`, `Link → Link`, `Separator → Separator`. `Toolbar.ToggleGroup`/`Toolbar.ToggleItem` are DROPPED as dedicated parts: compose the standalone `ToggleGroup` with `<Toolbar.Button render={<Toggle />} value="...">` as items (Base UI docs pattern). Base UI adds `Group` and `Input` parts with no Radix equivalent.
+
+## Toolbar.Root → Toolbar.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `orientation` | `"horizontal" \| "vertical"` / `"horizontal"` | `orientation` (default `'horizontal'`) | Same. |
+| `dir` | `"ltr" \| "rtl"` / — | — dropped | Use DOM `dir` / `DirectionProvider`. |
+| `loop` | `boolean` / `true` | `loopFocus` (default `true`) | Renamed. |
+
+## Toolbar.Button → Toolbar.Button
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+
+## Toolbar.Link → Toolbar.Link
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. Both render `<a>`. |
+
+## Toolbar.ToggleGroup → ToggleGroup (standalone, composed)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `type` (required) | `"single" \| "multiple"` / — | `multiple` (boolean, default `false`) | Moved: use the standalone `ToggleGroup` component inside `Toolbar.Root`; same mapping as toggle-group above. |
+| `value` / `defaultValue` | `string` or `string[]` / — | `value` / `defaultValue` on `ToggleGroup` | Always an array (see toggle-group). |
+| `onValueChange` | `(value: string \| string[]) => void` / — | `onValueChange` on `ToggleGroup` | `(groupValue: Value[], eventDetails) => void`. |
+| `disabled` | `boolean` / `false` | `disabled` on `ToggleGroup` | Same. |
+
+## Toolbar.ToggleItem → Toolbar.Button render={<Toggle />}
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | — | Moved: the composition IS the render prop: `<Toolbar.Button render={<Toggle />} value="bold" />`. Toolbar.Button supplies toolbar focus behavior, Toggle supplies pressed state. |
+| `value` (required) | `string` / — | `value` (on the composed element) | Same. |
+| `disabled` | `boolean` / — | `disabled` (on `Toolbar.Button`, default `false`) | Same; note `focusableWhenDisabled` defaults to `true` (disabled items stay focusable, Radix disabled items are not). |
+
+## Toolbar.Separator → Toolbar.Separator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| — | — | `orientation` | Base UI only: defaults to the OPPOSITE of the toolbar's orientation (horizontal toolbar → vertical separator), which matches Radix's automatic behavior; usually omit. |
+
+## Base UI only props worth knowing
+
+- `Root.disabled`: disables the entire toolbar (no Radix equivalent).
+- `Toolbar.Group` (new part): groups related items, with a group-level `disabled` (default `false`).
+- `Toolbar.Input` (new part): `<input>` wired into toolbar arrow-key navigation; `defaultValue`, `disabled` (default `false`), `focusableWhenDisabled` (default `true`).
+- `Button.disabled` (default `false`) + `Button.focusableWhenDisabled` (default `true`): disabled buttons remain focusable for discoverability; set `focusableWhenDisabled={false}` for Radix-like behavior.
+- `Button.nativeButton` (default `true`), state-function `className`/`style` on all parts.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `[data-orientation]` (Root, Button, ToggleGroup, ToggleItem, Separator) | `[data-orientation]` (Root, Button, Link, Input, Group, Separator) | Same; Separator's value is perpendicular to the toolbar. |
+| `ToggleItem [data-state="on" \| "off"]` | `[data-pressed]` (presence, from the composed `Toggle`) | Renamed. |
+| `ToggleItem [data-disabled]` | `[data-disabled]` (Root, Button, Input, Group) | Same. |
+| — | `Button/Input [data-focusable]` | Base UI only: present when focusable-while-disabled. |
+
+## CSS var mapping
+
+None on either side.
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/display-misc.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/display-misc.md
new file mode 100644
index 00000000..9623e44c
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/display-misc.md
@@ -0,0 +1,410 @@
+# Radix UI → Base UI props mapping: progress, scroll-area, separator, avatar, toast, form
+
+Sources: radix-ui/website `data/primitives/docs/components/*.mdx` (full inline prop tables) and base-ui.com `/react/components/{progress,scroll-area,separator,avatar,toast,form,field,fieldset}.md` (fetched 2026-07-02, `@base-ui/react`, formerly `@base-ui-components/react`).
+
+Universal conventions (apply to every part below, not repeated per table):
+
+- `asChild` (boolean) → `render` (`ReactElement | ((props: HTMLProps, state) => ReactElement)`). Signature changed: `<Part asChild><a/></Part>` → `<Part render={<a/>} />`.
+- Base UI `className` and `style` also accept a function of the part's `State` object.
+- Every Base part exposes `Part.Props` and `Part.State` types (e.g. `Progress.Root.Props`).
+
+---
+
+# progress
+
+Part mapping: `Progress.Root` → `Progress.Root`, `Progress.Indicator` → `Progress.Indicator` (now MUST be nested in the new `Progress.Track`). Base UI adds `Track`, `Label`, `Value` parts. The primitive computes the Indicator fill width itself (inline style), so the Radix pattern `style={{ transform: translateX(-(100 - value)%) }}` on Indicator is deleted, not ported.
+
+## Progress.Root → Progress.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed (see header). |
+| `value` | `number \| null` / - | `value` | Same. Required in Base UI (default `null`). `null` = indeterminate in both. |
+| `max` | `number` / - | `max` | Same. Base UI default `100`; Base UI also adds `min` (default `0`). |
+| `getValueLabel` | `(value: number, max: number) => string` / - | `getAriaValueText` | Renamed + signature changed: Base UI is `(formattedValue: string \| null, value: number \| null) => string`. Percent math is gone; use `format`/`locale` for formatting instead. |
+
+## Progress.Indicator → Progress.Indicator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Only prop. Nest inside `Progress.Track`; width is set by the primitive. |
+
+### Base UI only props worth knowing
+
+- Root: `min` (`0`), `format` (`Intl.NumberFormatOptions`), `locale` (`Intl.LocalesArgument`), `aria-valuetext`.
+- New parts: `Progress.Track` (contains Indicator), `Progress.Label` (accessible label, `<span>`), `Progress.Value` (formatted value text, `<span>`, `children` render fn `(formattedValue, value) => ReactNode`).
+
+### Data attributes
+
+| Radix | Base UI |
+| --- | --- |
+| `[data-state="loading"]` | `[data-progressing]` (boolean-presence attrs replace the enum) |
+| `[data-state="complete"]` | `[data-complete]` |
+| `[data-state="indeterminate"]` | `[data-indeterminate]` |
+| `[data-value]`, `[data-max]` | Dropped. Read `value` in a `className`/`style` state function or set your own attribute. |
+
+All Base attrs are present on Root, Track, Indicator, Label, and Value alike. State type: `{ status: 'indeterminate' | 'progressing' | 'complete' }`.
+
+### CSS variables
+
+None on either side.
+
+---
+
+# scroll-area
+
+Part mapping: `ScrollArea.Root` → `ScrollArea.Root`, `ScrollArea.Viewport` → `ScrollArea.Viewport`, `ScrollAreaScrollbar` → `ScrollArea.Scrollbar`, `ScrollAreaThumb` → `ScrollArea.Thumb`, `ScrollArea.Corner` → `ScrollArea.Corner`. Base UI adds `ScrollArea.Content` (wraps content inside Viewport, needed for horizontal overflow measurement).
+
+## ScrollArea.Root → ScrollArea.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `type` | `"auto" \| "always" \| "scroll" \| "hover"` / `"hover"` | Dropped | Visibility is CSS-driven: style Scrollbar `opacity` against `[data-hovering]`/`[data-scrolling]` (hover/scroll behavior), or always-visible CSS for `"always"` (+ `keepMounted` on Scrollbar). `"auto"` is the default mount behavior (scrollbar only mounts when scrollable). |
+| `scrollHideDelay` | `number` / `600` | Dropped | Reproduce with a CSS `transition-delay` on the scrollbar's opacity transition. |
+| `dir` | `"ltr" \| "rtl"` / - | Dropped | Base UI reads direction from the DOM (`dir` attribute) / its DirectionProvider utility; no per-component prop. |
+| `nonce` | `string` / - | Dropped | No documented CSP nonce equivalent. |
+
+## ScrollArea.Viewport → ScrollArea.Viewport
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Same part role (the scrollable container). Wrap children in `ScrollArea.Content` when horizontal scrolling matters. |
+
+## ScrollAreaScrollbar → ScrollArea.Scrollbar
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `forceMount` | `boolean` / - | `keepMounted` | Renamed; `boolean`, default `false`. Keeps the element in the DOM when the viewport is not scrollable. |
+| `orientation` | `"horizontal" \| "vertical"` / `"vertical"` | `orientation` | Same, same default. |
+
+## ScrollAreaThumb → ScrollArea.Thumb
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Only prop on both sides. |
+
+## ScrollArea.Corner → ScrollArea.Corner
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Only prop on both sides. |
+
+### Base UI only props worth knowing
+
+- Root: `overflowEdgeThreshold` (`number | Partial<{ xStart; xEnd; yStart; yEnd }>`, default `0`), threshold before the overflow edge attributes flip.
+- New part: `ScrollArea.Content` (div inside Viewport; same overflow data attributes as Root).
+
+### Data attributes
+
+| Radix | Base UI |
+| --- | --- |
+| Scrollbar `[data-state="visible" \| "hidden"]` | Dropped. Use `[data-hovering]`, `[data-scrolling]`, and `[data-has-overflow-x/y]` on Scrollbar to drive visibility styles. |
+| Scrollbar/Thumb `[data-orientation]` | Same (`data-orientation` on Scrollbar and Thumb). |
+| - | New, on Root/Content/Viewport/Scrollbar: `data-has-overflow-x`, `data-has-overflow-y`, `data-overflow-x-start/end`, `data-overflow-y-start/end`, `data-scrolling`; Scrollbar also `data-hovering`. |
+
+### CSS variables
+
+Radix's scroll-area docs list no CSS variables (its implementation ships undocumented `--radix-scroll-area-thumb-*`/`corner-*` vars). Base UI documents:
+
+| Base UI variable | Where |
+| --- | --- |
+| `--scroll-area-corner-width`, `--scroll-area-corner-height` | Root |
+| `--scroll-area-thumb-width`, `--scroll-area-thumb-height` | Scrollbar |
+| `--scroll-area-overflow-x-start/end`, `--scroll-area-overflow-y-start/end` | Viewport (pixel distance from each edge, great for scroll fades) |
+
+---
+
+# separator
+
+Part mapping: `Separator.Root` → `Separator` (callable single part, no `.Root`).
+
+## Separator.Root → Separator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `orientation` | `"horizontal" \| "vertical"` / `"horizontal"` | `orientation` | Same, same default (`Orientation` type). |
+| `decorative` | `boolean` / - | Dropped | Base UI's separator is always semantic (`role="separator"`). For a purely visual rule, render a plain `<div aria-hidden="true">` or use a CSS border instead. |
+
+### Base UI only props worth knowing
+
+None beyond the universal `className`/`style`/`render`. Renders a `<div>`.
+
+### Data attributes
+
+`[data-orientation]` with values `horizontal | vertical`: identical on both sides.
+
+### CSS variables
+
+None on either side.
+
+---
+
+# avatar
+
+Part mapping: `Avatar.Root` → `Avatar.Root`, `Avatar.Image` → `Avatar.Image`, `Avatar.Fallback` → `Avatar.Fallback`. Same anatomy. Base Root renders `<span>`, Image `<img>`, Fallback `<span>`.
+
+## Avatar.Root → Avatar.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Only prop on both sides. Base Root can also take plain children (e.g. initials) with no Image/Fallback. |
+
+## Avatar.Image → Avatar.Image
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `onLoadingStatusChange` | `(status: "idle" \| "loading" \| "loaded" \| "error") => void` / - | `onLoadingStatusChange` | Same name, same `ImageLoadingStatus` union. |
+
+## Avatar.Fallback → Avatar.Fallback
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `delayMs` | `number` / - | `delay` | Renamed, same meaning (ms to wait before showing the fallback). |
+
+### Base UI only props worth knowing
+
+Nothing beyond the universal trio. Part `State` exposes `imageLoadingStatus` (and `transitionStatus` on Image) for `className`/`style` functions.
+
+### Data attributes
+
+Radix documents none. Base UI Image adds `data-starting-style` / `data-ending-style` for enter/exit transitions.
+
+### CSS variables
+
+None on either side.
+
+---
+
+# toast
+
+The mental model changes completely: Radix toast is declarative (you render `<Toast.Root open>` yourself), Base UI toast is manager-driven. Toasts are created imperatively via `Toast.useToastManager().add({ title, description, ... })` (or a global `Toast.createToastManager()` passed to `Provider toastManager`), and you render `useToastManager().toasts.map((toast) => <Toast.Root key={toast.id} toast={toast} />)` inside the Viewport.
+
+Part mapping:
+
+| Radix part | Base UI part |
+| --- | --- |
+| `Toast.Provider` | `Toast.Provider` (props differ heavily) |
+| `Toast.Viewport` | `Toast.Portal` + `Toast.Viewport` (Portal is new; appends to `<body>` by default) |
+| `Toast.Root` | `Toast.Root` (requires `toast` object; typically wraps new `Toast.Content`) |
+| `Toast.Title` | `Toast.Title` (renders `<h2>`) |
+| `Toast.Description` | `Toast.Description` (renders `<p>`) |
+| `Toast.Action` | `Toast.Action` (rendered per-toast; props can come from `toast.actionProps`) |
+| `Toast.Close` | `Toast.Close` |
+| - | New: `Toast.Content`, `Toast.Positioner` + `Toast.Arrow` (anchored toasts), `Toast.createToastManager`, `Toast.useToastManager` |
+
+## Toast.Provider → Toast.Provider
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `duration` | `number` / `5000` | `timeout` | Renamed. Same default (`5000`, `0` disables auto-dismiss). Per-toast override moved to `add({ timeout })`. |
+| `label` (required) | `string` / `"Notification"` | Dropped | Base UI handles screen reader announcements internally; per-toast urgency via `priority: 'low' \| 'high'` in `add()`. |
+| `swipeDirection` | `"right" \| "left" \| "up" \| "down"` / `"right"` | Moved | Now `swipeDirection` on `Toast.Root`; accepts a single value or an array, default `['down', 'right']`. |
+| `swipeThreshold` | `number` / `50` | Dropped | Not configurable. Opt elements out of swipe with the `data-base-ui-swipe-ignore` attribute. |
+| `announcerContainer` | `Element \| DocumentFragment` / `document.body` | Dropped | Closest analog is `Toast.Portal container` for where the viewport renders. |
+
+## Toast.Viewport → Toast.Portal + Toast.Viewport
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | On both Portal and Viewport. |
+| `hotkey` | `string[]` / `["F8"]` | Dropped | Base UI hard-wires F6 to focus the viewport landmark; not configurable. |
+| `label` | `string` / `"Notifications ({hotkey})"` | Dropped | Landmark labelling handled internally. |
+
+Base UI only: `Portal.container` (`HTMLElement | ShadowRoot | ref | null`).
+
+## Toast.Root → Toast.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `type` | `"foreground" \| "background"` / `"foreground"` | `priority` in `add()` options | Moved + renamed: `foreground` ≈ `priority: 'high'` (announced urgently), `background` ≈ `'low'` (default). Careful: Base UI's `toast.type` is a different concept (a free-form styling category like `'success'`, surfaced as `data-type`). |
+| `duration` | `number` / - | `timeout` in `add()` options | Moved + renamed; per-toast override of Provider `timeout`. |
+| `defaultOpen` | `boolean` / `true` | Dropped | Open state lives in the manager. Create with `add()`, remove with `close(id)`. |
+| `open` | `boolean` / - | Dropped | Same as above; there is no controlled-open mode. `add({ id })` upserts an existing toast in place. |
+| `onOpenChange` | `(open: boolean) => void` / - | Dropped (workaround) | Use `onClose` / `onRemove` callbacks in the toast object (`add()` options). |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` / - | Dropped | Esc-to-close still works when focus is in the viewport, but is not interceptable. |
+| `onPause` / `onResume` | `() => void` / - | Dropped | Timers still pause on hover, focus, and window blur automatically, but there are no callbacks. |
+| `onSwipeStart` / `onSwipeMove` / `onSwipeEnd` / `onSwipeCancel` | `(event: SwipeEvent) => void` / - | Dropped (workaround) | Swiping is styled, not scripted: `[data-swiping]`, `[data-swipe-direction]` and `--toast-swipe-movement-x/y` replace the event hooks. |
+| `forceMount` | `boolean` / - | Dropped | Roots render from the `toasts` array; exit animations get `data-ending-style` + `toast.transitionStatus: 'ending'` before removal (`onRemove` fires after). |
+
+Base UI only on Root: `toast` (required `Toast.Root.ToastObject`: `id`, `title`, `description`, `type`, `timeout`, `priority`, `updateKey`, `limited`, `height`, `onClose`, `onRemove`, `actionProps`, `positionerProps`, `data`), `swipeDirection` (single or array).
+
+## Toast.Title → Toast.Title
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Only prop. Base renders `<h2>` (Radix rendered `<div>`); pass `render={<div />}` to keep a div. Content usually comes from `toast.title`. |
+
+## Toast.Description → Toast.Description
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Only prop. Base renders `<p>`. Content usually comes from `toast.description`. |
+
+## Toast.Action → Toast.Action
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `altText` (required) | `string` / - | Dropped | No equivalent prop. When creating toasts via the manager, pass the button's props (including handlers and aria attributes) through `add({ actionProps })`. |
+
+Base UI only: `nativeButton` (`boolean`, default `true`, set `false` when `render` is not a button).
+
+## Toast.Close → Toast.Close
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+
+Base UI only: `nativeButton` (as on Action).
+
+### Base UI only props worth knowing
+
+- Provider: `limit` (`number`, default `3`; overflowing toasts get `data-limited` + `inert` instead of being removed), `toastManager` (from `Toast.createToastManager()` for use outside React).
+- Manager API (`useToastManager()` return / `createToastManager()`): `toasts`, `add(options) => id`, `close(id?)`, `update(id, options)`, `promise(promise, { loading, success, error })`.
+- New parts: `Toast.Content` (clips overflow while the stack is collapsed; `data-behind`, `data-expanded`), `Toast.Positioner`/`Toast.Arrow` for anchored toasts (full popup positioning surface: `anchor`, `side` default `'top'`, `align`, `sideOffset`, `alignOffset`, `collisionAvoidance`, `collisionBoundary`, `collisionPadding`, `arrowPadding`, `sticky`, `positionMethod`, `disableAnchorTracking`).
+
+### Data attributes
+
+| Radix | Base UI |
+| --- | --- |
+| Root `[data-state="open" \| "closed"]` | `data-starting-style` / `data-ending-style` (CSS transition hooks) |
+| Root `[data-swipe="start" \| "move" \| "cancel" \| "end"]` | `[data-swiping]` while swiping; `"end"` ≈ `[data-ending-style][data-swipe-direction=...]` |
+| Root `[data-swipe-direction]` (`up/down/left/right`) | Same name and values |
+| - | New: Root `data-expanded`, `data-limited`, `data-type`; Viewport `data-expanded`; Content `data-behind`, `data-expanded`; Title/Description/Close/Action `data-type`; Positioner/Arrow `data-side`, `data-align`, `data-anchor-hidden`/`data-uncentered` |
+
+### CSS variables
+
+| Radix | Base UI |
+| --- | --- |
+| `--radix-toast-swipe-move-x` / `--radix-toast-swipe-move-y` | `--toast-swipe-movement-x` / `--toast-swipe-movement-y` |
+| `--radix-toast-swipe-end-x` / `--radix-toast-swipe-end-y` | Dropped; animate dismissal from `[data-ending-style][data-swipe-direction=...]` using the movement vars |
+| - | New on Root: `--toast-index`, `--toast-offset-y`, `--toast-height`; Viewport: `--toast-frontmost-height`; Positioner: `--anchor-width/height`, `--available-width/height`, `--transform-origin` |
+
+---
+
+# form
+
+Base UI splits Radix Form across three components: `Form` (`@base-ui/react/form`, a callable single part rendering `<form>`), `Field` (`@base-ui/react/field`: `Root`, `Label`, `Control`, `Error`, `Description`, `Validity`, `Item`), and `Fieldset` (`@base-ui/react/fieldset`: `Root`, `Legend`).
+
+Part mapping:
+
+| Radix part | Base UI part |
+| --- | --- |
+| `Form.Root` | `Form` (callable, no `.Root`) |
+| `Form.Field` | `Field.Root` |
+| `Form.Label` | `Field.Label` |
+| `Form.Control` | `Field.Control` (or any Base UI input component: Input, Checkbox, Select, ... work inside Field out of the box) |
+| `Form.Message` | `Field.Error` (validation errors); `Field.Description` for plain hint text |
+| `Form.ValidityState` | `Field.Validity` |
+| `Form.Submit` | Dropped; use a plain `<button type="submit">` |
+| - | New: `Fieldset.Root` + `Fieldset.Legend`, `Field.Item` (per-item wrapper in checkbox/radio groups) |
+
+## Form.Root → Form
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `onClearServerErrors` | `() => void` / - | Dropped (workaround) | The server-error model changed: pass an `errors` object (keys = `Field.Root` `name`, values = message(s)) to `Form`; clear your own error state in `onFormSubmit` (Base calls `preventDefault()` for you) or in `onValueChange` per field. |
+
+Base UI only on Form: `errors` (`Errors`), `onFormSubmit` (`(formValues, eventDetails) => void`), `validationMode` (`'onSubmit' | 'onBlur' | 'onChange'`, default `'onSubmit'`), `actionsRef` (`{ validate(fieldName?) }`).
+
+## Form.Field → Field.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `name` (required) | `string` / - | `name` | Same purpose (submission identity + matching `Form errors` keys); optional in Base UI and takes precedence over `name` on `Field.Control`. |
+| `serverInvalid` | `boolean` / - | Dropped (workaround) | Either supply the message via `Form errors={{ [name]: message }}` (field becomes invalid and `Field.Error` shows it), or force state with the `invalid` boolean prop on `Field.Root`. |
+
+Base UI only on Field.Root: `validate` (`(value, formValues) => string | string[] | Promise<...> | null`, the custom-validation replacement for Radix function `match`), `validationMode`, `validationDebounceTime` (`0`), `disabled`, `invalid`, `dirty`, `touched`, `actionsRef` (`{ validate() }`).
+
+## Form.Label → Field.Label
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. Auto-association with the control is preserved. |
+
+Base UI only: `nativeLabel` (`boolean`, default `true`; set `false` when `render` swaps in a non-label element, e.g. a `<div>` labelling a `<Select.Trigger>` button).
+
+## Form.Control → Field.Control
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. For composite widgets, skip Control entirely: Base UI inputs (Input, Checkbox, Select, ...) wire into `Field.Root` directly, which Radix Form could not do. |
+
+Base UI only: `defaultValue` (`string | number | string[]`), `onValueChange` (`(value, eventDetails) => void`).
+
+## Form.Message → Field.Error
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `match` | `'badInput' \| 'patternMismatch' \| 'rangeOverflow' \| 'rangeUnderflow' \| 'stepMismatch' \| 'tooLong' \| 'tooShort' \| 'typeMismatch' \| 'valid' \| 'valueMissing' \| ((value, formData) => boolean \| Promise<boolean>)` / - | `match` | Signature changed: Base UI is `boolean \| 'valid' \| 'badInput' \| 'customError' \| 'patternMismatch' \| 'rangeOverflow' \| 'rangeUnderflow' \| 'stepMismatch' \| 'tooLong' \| 'tooShort' \| 'typeMismatch' \| 'valueMissing'`. The function form is gone: move custom rules to `validate` on `Field.Root` (returns error string(s)); an Error without `match` then displays them. `'customError'` matches `validate` failures. |
+| `forceMatch` | `boolean` / `false` | `match={true}` | Renamed/absorbed: `match` accepting `true` always shows the message (the documented hook for external libraries and server errors). |
+| `name` | `string` / - | Dropped | `Field.Error` cannot target a field from outside; it must be nested in the owning `Field.Root`. |
+
+Note: Radix rendered default English messages per `match` when `children` were omitted; Base UI renders the error string coming from `validate`/`Form errors`, otherwise provide `children`. `Field.Description` (className/style/render only) is the new home for non-error helper text. Error renders a `<div>`, Description a `<p>`.
+
+## Form.ValidityState → Field.Validity
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `children` | `(validity: ValidityState \| undefined) => React.ReactNode` / - | `children` (required) | Signature changed: `(state: Field.Validity.State) => React.ReactNode` where the native flags live at `state.validity.*` (plus `state.errors`, `state.error`, `state.value`, `state.initialValue`). |
+| `name` | `string` / - | Dropped | Must be nested inside `Field.Root`. |
+
+## Form.Submit → (none)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | Dropped | No submit part; render a plain `<button type="submit">` (or the styled Button component). |
+
+## (new) Fieldset.Root and Fieldset.Legend
+
+No Radix counterpart. `Fieldset.Root` renders a native `<fieldset>` (props: `className`/`style`/`render`; state `{ disabled }`, `data-disabled`). `Fieldset.Legend` renders a `<div>` automatically associated as the accessible legend. Use to group related fields under one label.
+
+### Base UI only props worth knowing (form-wide)
+
+- Validation timing is configurable (`validationMode` on Form or per Field, `validationDebounceTime`).
+- `actionsRef` imperative `validate()` on both Form and Field.Root.
+- `Field.Item` groups a single checkbox/radio inside a group with its own label/description (`disabled` prop).
+- Focus is moved to the first invalid field on submit, matching Radix behavior.
+
+### Data attributes
+
+| Radix (Field/Label/Control/Message) | Base UI (all Field parts: Root, Item, Label, Control, Description, Error) |
+| --- | --- |
+| `[data-valid]` | `[data-valid]` (same) |
+| `[data-invalid]` | `[data-invalid]` (same) |
+| - | New: `data-dirty`, `data-touched`, `data-filled`, `data-focused`, `data-disabled`; Error also gets `data-starting-style`/`data-ending-style`. |
+
+### CSS variables
+
+None on either side.
+
+---
+
+# No Base UI counterpart
+
+Radix utilities with no Base UI equivalent, and the recommended plain replacements:
+
+## Label (radix `Label.Root`: `asChild`, `htmlFor`)
+
+Use a native `<label htmlFor="...">`, or `Field.Label` when inside a `Field.Root` (which auto-wires the association, no `htmlFor` needed). Radix's only behavioral extra (preventing text selection on double click) is one line of CSS: `select-none` / `user-select: none`.
+
+## AspectRatio (radix `AspectRatio.Root`: `asChild`, `ratio` default `1`)
+
+Use the CSS `aspect-ratio` property, which is what the prop mapped to: `ratio={16 / 9}` → `aspect-video` or `aspect-[16/9]` (`aspect-ratio: 16 / 9`), plus `w-full` and `object-cover` on the media child.
+
+## VisuallyHidden (radix `VisuallyHidden.Root`: `asChild`)
+
+Use Tailwind's `sr-only` class on a `<span>` (the standard clip-rect pattern). Note: some Base UI popup components in other files still need hidden titles for a11y; `<span className="sr-only">` covers that too.
+
+## AccessibleIcon (radix `AccessibleIcon.Root`: `label` required)
+
+It was only VisuallyHidden + `aria-hidden` composed: render the icon with `aria-hidden="true"` (or `focusable="false"`) and add `<span className="sr-only">{label}</span>` next to it, or put `aria-label={label}` on the interactive parent (button/link) instead.
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/form-controls.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/form-controls.md
new file mode 100644
index 00000000..829de397
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/form-controls.md
@@ -0,0 +1,390 @@
+# Radix UI to Base UI props mapping: form controls
+
+Scope: select, checkbox, radio-group, switch, slider.
+Sources: radix-ui.com primitives docs and base-ui.com `/react/components/*.md` (fetched 2026-07-02).
+
+Global conventions that apply to every part below:
+
+- `asChild` (Radix, `boolean`, default `false`) -> `render` (Base UI, `ReactElement | ((props, state) => ReactElement)`). Every Base UI part accepts `render`, plus `className`/`style` as either plain values or state callbacks (`(state) => ...`).
+- Base UI parts that render interactive elements accept `nativeButton` (tells Base UI whether the `render` target is a native `<button>`), which has no Radix equivalent.
+- Callbacks fire with a second `eventDetails` argument (`{ reason, event, cancel(), allowPropagation(), isCanceled, isPropagationAllowed, trigger }`). `eventDetails.cancel()` replaces Radix's `event.preventDefault()` pattern for preventing default component behavior.
+- Radix `data-state="x"` tokens become presence attributes in Base UI (`data-checked`, `data-unchecked`, `data-open`, ...). Base UI adds Field-integration attributes everywhere (`data-valid`, `data-invalid`, `data-dirty`, `data-touched`, `data-filled`, `data-focused`) and animation attributes (`data-starting-style`, `data-ending-style`).
+- Radix `dir` props have no Base UI per-component equivalent, direction comes from `DirectionProvider` (or the `dir` HTML attribute).
+
+---
+
+# select
+
+Part mapping: `Root -> Root`, `Trigger -> Trigger`, `Value -> Value`, `Icon -> Icon`, `Portal -> Portal`, `Content -> Portal > Positioner > Popup` (split into three parts), `Viewport -> List`, `Item -> Item`, `ItemText -> ItemText`, `ItemIndicator -> ItemIndicator`, `ScrollUpButton -> ScrollUpArrow`, `ScrollDownButton -> ScrollDownArrow`, `Group -> Group`, `Label -> GroupLabel` (Base UI's `Select.Label` is a NEW part that labels the trigger, not groups), `Separator -> Separator`, `Arrow -> Arrow`.
+
+## Select.Root → Select.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultValue` | `string`, no default | `defaultValue: Value[] \| Value \| null` | Same name, widened type. Values can be any type (objects supported), arrays for `multiple`. |
+| `value` | `string`, no default | `value: Value[] \| Value \| null` | Same name, widened type. `null` means "no value" (placeholder shown). |
+| `onValueChange` | `(value: string) => void` | `onValueChange: (value: Value[] \| Value \| null, eventDetails: Select.Root.ChangeEventDetails) => void` | Signature changed: second `eventDetails` arg with `reason` (`'trigger-press' \| 'outside-press' \| 'escape-key' \| 'window-resize' \| 'item-press' \| 'focus-out' \| 'list-navigation' \| 'cancel-open' \| 'none'`) and `cancel()`. |
+| `defaultOpen` | `boolean`, no default | `defaultOpen: boolean`, default `false` | Same. |
+| `open` | `boolean`, no default | `open: boolean` | Same. |
+| `onOpenChange` | `(open: boolean) => void` | `onOpenChange: (open: boolean, eventDetails: Select.Root.ChangeEventDetails) => void` | Signature changed: added `eventDetails` (same reason union as above). Radix Content's `onEscapeKeyDown`/`onPointerDownOutside` interception moves here (check `eventDetails.reason === 'escape-key'` / `'outside-press'`, call `eventDetails.cancel()` to keep open). |
+| `dir` | `"ltr" \| "rtl"`, no default | dropped | Use Base UI `DirectionProvider` or the `dir` attribute on an ancestor. |
+| `name` | `string`, no default | `name: string` | Same (Base UI renders a hidden `<input>`). |
+| `disabled` | `boolean`, no default | `disabled: boolean`, default `false` | Same. |
+| `required` | `boolean`, no default | `required: boolean`, default `false` | Same. |
+
+Base UI `Select.Root` renders no HTML element (Radix Root doesn't either).
+
+## Select.Trigger → Select.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | See global conventions. Base UI Trigger renders `<button>` by default; `nativeButton` defaults to `true` here, set it to `false` when rendering a non-button via `render`. |
+| (none) | - | `disabled: boolean` | Base UI allows disabling just the trigger. |
+
+## Select.Value → Select.Value
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| `placeholder` | `ReactNode`, no default | `placeholder: React.ReactNode` | Same name. Behavior change: Radix `Value` renders the selected Item's `ItemText` content; Base UI renders the raw value string unless you pass `items` on Root or a `children` function (`(value) => ReactNode`). If your item labels differ from values, supply `items` on Root or format via `children`. |
+
+## Select.Icon → Select.Icon
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. Base UI Icon exposes `data-popup-open` for rotate-when-open styling. |
+
+## Select.Portal → Select.Portal
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `container` | `HTMLElement`, default `document.body` | `container: HTMLElement \| ShadowRoot \| React.RefObject<...> \| null` | Same concept, type widened (accepts refs and ShadowRoot). Base UI Portal renders a `<div>` and accepts `className`/`style`/`render`. |
+
+## Select.Content → Select.Portal > Select.Positioner > Select.Popup (moved/split)
+
+Radix `Content` handled positioning, collision, and the panel in one part. In Base UI, positioning props live on `Positioner`, panel/focus props live on `Popup`, dismiss interception lives on `Root.onOpenChange` eventDetails.
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` (on Positioner and/or Popup) | Same pattern. |
+| `position` | `"item-aligned" \| "popper"`, default `"item-aligned"` | `alignItemWithTrigger: boolean` on Positioner, default `true` | Signature changed: enum becomes boolean. `"item-aligned"` -> `alignItemWithTrigger` (true, the default), `"popper"` -> `alignItemWithTrigger={false}`. Base UI auto-disables it when space is insufficient or on touch input. |
+| `side` | `"top" \| "right" \| "bottom" \| "left"`, default `"bottom"` | `side: Side` on Positioner, default `'bottom'` | Moved. Base UI adds `'inline-start' \| 'inline-end'` logical values. Only applies when `alignItemWithTrigger` is off (as with Radix popper mode). |
+| `sideOffset` | `number`, default `0` | `sideOffset: number \| OffsetFunction` on Positioner, default `0` | Moved, type widened (accepts a function of `{ side, align, anchor, positioner }`). |
+| `align` | `"start" \| "center" \| "end"`, default `"start"` | `align: Align` on Positioner, default `'center'` | Moved. Default differs: Radix `"start"` vs Base UI `'center'`. Pass `align="start"` explicitly to preserve Radix behavior. |
+| `alignOffset` | `number`, default `0` | `alignOffset: number \| OffsetFunction` on Positioner, default `0` | Moved, type widened. |
+| `avoidCollisions` | `boolean`, default `true` | `collisionAvoidance: CollisionAvoidance` on Positioner | Signature changed: boolean becomes a config object `{ side: 'flip' \| 'shift' \| 'none', align: 'flip' \| 'shift' \| 'none', fallbackAxisSide: 'start' \| 'end' \| 'none' }`. `avoidCollisions={false}` ~ `collisionAvoidance={{ side: 'none', align: 'none', fallbackAxisSide: 'none' }}`. |
+| `collisionBoundary` | `Boundary`, default `[]` | `collisionBoundary: Boundary` on Positioner, default `'clipping-ancestors'` | Moved, default differs (Radix default is the viewport, Base UI defaults to clipping ancestors). |
+| `collisionPadding` | `number \| Padding`, default `10` | `collisionPadding: Padding` on Positioner, default `5` | Moved, default differs (10 -> 5). |
+| `arrowPadding` | `number`, default `0` | `arrowPadding: number` on Positioner, default `5` | Moved, default differs (0 -> 5). |
+| `sticky` | `"partial" \| "always"`, default `"partial"` | `sticky: boolean` on Positioner, default `false` | Signature changed and semantics differ: Base UI `sticky` keeps the popup in the viewport after the anchor scrolls out of view. There is no `"always"` equivalent. |
+| `hideWhenDetached` | `boolean`, default `false` | dropped (workaround) | No prop. Style on `data-anchor-hidden` (present on Positioner when the anchor is hidden), e.g. `[data-anchor-hidden] { visibility: hidden }`. |
+| `onCloseAutoFocus` | `(event: Event) => void` | `finalFocus` on Popup | Signature changed: instead of preventing default in an event handler, pass `finalFocus` as `boolean \| RefObject \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`. `false` = don't move focus (the `preventDefault()` equivalent), a ref/element = focus that. |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | moved to `Root.onOpenChange` | Check `eventDetails.reason === 'escape-key'`; call `eventDetails.cancel()` to prevent close. |
+| `onPointerDownOutside` | `(event: PointerEvent) => void` | moved to `Root.onOpenChange` | Check `eventDetails.reason === 'outside-press'`; call `eventDetails.cancel()` to prevent close. |
+
+## Select.Viewport → Select.List (renamed)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Renamed part, no other props on either side. Radix required `<ScrollUpButton>`/`<Viewport>`/`<ScrollDownButton>` as siblings inside Content; in Base UI, `List` and the scroll arrows are children of `Popup`. |
+
+## Select.Item → Select.Item
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. Also `nativeButton` (default `false`, Base UI Item renders a `<div>`). |
+| `value` | `string`, required | `value: any`, default `null` | Same name, widened type (objects allowed, see Root `isItemEqualToValue` / `itemToString*`). `null` value marks the placeholder item. |
+| `disabled` | `boolean`, no default | `disabled: boolean`, default `false` | Same. |
+| `textValue` | `string`, no default | `label: string` | Renamed. Both drive typeahead text matching, defaulting to the item's text content. |
+
+## Select.ItemText → Select.ItemText
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. Note element change: Radix renders `<span>`, Base UI renders `<div>`. |
+
+## Select.ItemIndicator → Select.ItemIndicator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| (implicit conditional mount) | - | `keepMounted: boolean` | Base UI unmounts when unselected by default, same as Radix. `keepMounted` keeps it in the DOM (Radix had no `forceMount` on select's ItemIndicator). |
+
+## Select.ScrollUpButton / ScrollDownButton → Select.ScrollUpArrow / ScrollDownArrow (renamed)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Renamed parts. Base UI adds `keepMounted: boolean` (default `false`) to keep the arrow in the DOM while the popup is not scrollable. Base UI arrows do not render on touch input. |
+
+## Select.Group → Select.Group
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same. |
+
+## Select.Label → Select.GroupLabel (renamed)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Renamed. Do NOT map to Base UI `Select.Label`, which is a new part that labels the select trigger itself (rendered outside the popup). |
+
+## Select.Separator → Select.Separator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same. Base UI adds `orientation: Orientation`, default `'horizontal'`. |
+
+## Select.Arrow → Select.Arrow
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| `width` | `number`, default `10` | dropped | Size the arrow with CSS; Base UI Arrow renders a `<div>` you fill with your own SVG. |
+| `height` | `number`, default `5` | dropped | Same as above. |
+
+## Base UI only props worth knowing (select)
+
+- `Root.multiple: boolean` (default `false`): multi-select with `Value[]` values, no Radix equivalent.
+- `Root.items`: `Record<string, ReactNode> | { label, value }[] | Group[]`, lets `Select.Value` render labels instead of raw values.
+- `Root.isItemEqualToValue`, `Root.itemToStringLabel`, `Root.itemToStringValue`: object-value support.
+- `Root.modal: boolean` (default `true`): scroll lock + outside pointer blocking; Radix select was always modal-ish, set `modal={false}` for non-modal behavior.
+- `Root.readOnly`, `Root.autoComplete`, `Root.form`, `Root.inputRef`, `Root.id`, `Root.onOpenChangeComplete`, `Root.actionsRef` (`{ unmount() }` for externally controlled exit animations), `Root.highlightItemOnHover` (default `true`).
+- New parts: `Select.Backdrop` (overlay under the popup), `Select.Label` (trigger label), `Popup.finalFocus`.
+- `Positioner.anchor`, `Positioner.positionMethod` (`'absolute' | 'fixed'`), `Positioner.disableAnchorTracking`.
+
+## Data-attribute mapping (select)
+
+| Radix | Base UI |
+| --- | --- |
+| Trigger `data-state="open" \| "closed"` | Trigger `data-popup-open` (presence), plus `data-pressed`, `data-popup-side` |
+| Trigger `data-placeholder` | Trigger/Value `data-placeholder` (same) |
+| Trigger `data-disabled` | Trigger `data-disabled` (same), plus `data-readonly`, `data-required`, Field attrs |
+| Content `data-state="open" \| "closed"` | Positioner/Popup `data-open` / `data-closed` (presence) |
+| Content `data-side` (`left/right/bottom/top`) | Positioner/Popup `data-side` (`none/top/bottom/left/right/inline-start/inline-end`) |
+| Content `data-align` | Positioner/Popup `data-align` (same values) |
+| Item `data-state="checked" \| "unchecked"` | Item `data-selected` (presence, no unchecked token) |
+| Item `data-highlighted` | Item `data-highlighted` (same) |
+| Item `data-disabled` | Item `data-disabled` (same) |
+| (none) | Popup/Backdrop/ItemIndicator/ScrollArrows `data-starting-style` / `data-ending-style` (animation hooks) |
+| (none) | Positioner `data-anchor-hidden`, ScrollArrows `data-direction` / `data-visible` |
+
+## CSS variable mapping (select)
+
+All Base UI vars are set on `Select.Positioner` (Radix set them on Content, popper mode only):
+
+| Radix | Base UI |
+| --- | --- |
+| `--radix-select-trigger-width` | `--anchor-width` |
+| `--radix-select-trigger-height` | `--anchor-height` |
+| `--radix-select-content-available-width` | `--available-width` |
+| `--radix-select-content-available-height` | `--available-height` |
+| `--radix-select-content-transform-origin` | `--transform-origin` |
+
+---
+
+# checkbox
+
+Part mapping: `Root -> Root`, `Indicator -> Indicator`. Element change: Radix Root renders a `<button>` plus hidden input inside a form; Base UI Root renders a `<span>` plus hidden `<input>` always (use `nativeButton` + `render` to render a real button).
+
+## Checkbox.Root → Checkbox.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | See global conventions, pair with `nativeButton` when rendering a `<button>`. |
+| `defaultChecked` | `boolean \| 'indeterminate'`, no default | `defaultChecked: boolean`, default `false` | Signature changed: `'indeterminate'` is no longer a checked value. Use the separate `indeterminate: boolean` prop. |
+| `checked` | `boolean \| 'indeterminate'`, no default | `checked: boolean` + `indeterminate: boolean` | Signature changed: split into two props. Radix `checked="indeterminate"` -> Base UI `indeterminate` (a checkbox can be indeterminate and unchecked/checked independently). |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | `onCheckedChange: (checked: boolean, eventDetails: Checkbox.Root.ChangeEventDetails) => void` | Signature changed: `checked` is always boolean, `eventDetails` added (`reason: 'none'`). Indeterminate transitions are managed by you via the `indeterminate` prop (or `parent` in a CheckboxGroup). |
+| `disabled` | `boolean`, no default | `disabled: boolean`, default `false` | Same. |
+| `required` | `boolean`, no default | `required: boolean`, default `false` | Same. |
+| `name` | `string`, no default | `name: string` | Same. |
+| `value` | `string`, default `"on"` | `value: string` | Same name. Radix documents the default as `"on"`; Base UI docs list no default but hidden-input submission matches native checkbox behavior (`"on"` when unset). |
+
+## Checkbox.Indicator → Checkbox.Indicator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| `forceMount` | `boolean`, no default | `keepMounted: boolean`, default `false` | Renamed. Both keep the element in the DOM when unchecked (for animation). Base UI also renders the indicator when `indeterminate`. |
+
+## Base UI only props worth knowing (checkbox)
+
+- `Root.indeterminate: boolean` (default `false`): the mixed state, decoupled from `checked`.
+- `Root.parent: boolean` + `CheckboxGroup` (new component, `base-ui.com/react/components/checkbox-group`): `<CheckboxGroup value/defaultValue/onValueChange(string[], eventDetails)/allValues/disabled>` provides shared state for a set of checkboxes and enables a parent "select all" checkbox. No Radix equivalent, new capability.
+- `Root.readOnly: boolean`, `Root.uncheckedValue: string` (value submitted when unchecked), `Root.form: string`, `Root.inputRef`, `Root.id`, `Root.nativeButton`.
+
+## Data-attribute mapping (checkbox)
+
+| Radix | Base UI |
+| --- | --- |
+| `data-state="checked"` | `data-checked` |
+| `data-state="unchecked"` | `data-unchecked` |
+| `data-state="indeterminate"` | `data-indeterminate` |
+| `data-disabled` | `data-disabled` (same) |
+| (none) | `data-readonly`, `data-required`, `data-valid`, `data-invalid`, `data-dirty`, `data-touched`, `data-filled`, `data-focused` (Field integration) |
+| (none) | Indicator `data-starting-style` / `data-ending-style` |
+
+No CSS variables on either side.
+
+---
+
+# radio-group
+
+Part mapping: Radix ships one `RadioGroup` namespace; Base UI splits it into `RadioGroup` (a single component, no sub-parts) and `Radio` (`Radio.Root`, `Radio.Indicator`). `RadioGroup.Root -> RadioGroup`, `RadioGroup.Item -> Radio.Root`, `RadioGroup.Indicator -> Radio.Indicator`. Element change: Radix Item renders `<button>`; Base UI `Radio.Root` renders `<span>` plus hidden `<input>` (use `nativeButton` + `render` for a real button).
+
+## RadioGroup.Root → RadioGroup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| `defaultValue` | `string`, no default | `defaultValue: Value` | Same name, widened type (any value type). |
+| `value` | `string`, no default | `value: Value` | Same name, widened type. |
+| `onValueChange` | `(value: string) => void` | `onValueChange: (value: Value, eventDetails: RadioGroup.ChangeEventDetails) => void` | Signature changed: added `eventDetails` (`reason: 'none'`). |
+| `disabled` | `boolean`, no default | `disabled: boolean`, default `false` | Same. |
+| `name` | `string`, no default | `name: string` | Same. |
+| `required` | `boolean`, no default | `required: boolean`, default `false` | Same. |
+| `orientation` | `enum`, default `undefined` | dropped | Base UI arrow-key navigation handles both axes automatically; there is no orientation prop (set `aria-orientation` yourself if needed for AT). |
+| `dir` | `"ltr" \| "rtl"`, no default | dropped | Use `DirectionProvider`. |
+| `loop` | `boolean`, default `true` | dropped | Focus wrapping is built in and not configurable. |
+
+## RadioGroup.Item → Radio.Root (moved to Radio namespace)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern, plus `nativeButton` (default `false`). |
+| `value` | `string`, required | `value: Value`, required | Same name, widened type. |
+| `disabled` | `boolean`, no default | `disabled: boolean` | Same. |
+| `required` | `boolean`, no default | `required: boolean` | Same. |
+
+## RadioGroup.Indicator → Radio.Indicator (moved to Radio namespace)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| `forceMount` | `boolean`, no default | `keepMounted: boolean`, default `false` | Renamed. |
+
+## Base UI only props worth knowing (radio-group)
+
+- `RadioGroup.readOnly`, `RadioGroup.form`, `RadioGroup.inputRef` (the group owns one hidden input).
+- `Radio.Root.readOnly`, `Radio.Root.inputRef`, `Radio.Root.nativeButton`.
+
+## Data-attribute mapping (radio-group)
+
+| Radix | Base UI |
+| --- | --- |
+| Root `data-disabled` | RadioGroup `data-disabled` (same) |
+| Item/Indicator `data-state="checked"` | Radio.Root/Indicator `data-checked` |
+| Item/Indicator `data-state="unchecked"` | Radio.Root/Indicator `data-unchecked` |
+| Item/Indicator `data-disabled` | `data-disabled` (same) |
+| (none) | `data-readonly`, `data-required`, Field attrs (`data-valid`, `data-invalid`, `data-dirty`, `data-touched`, `data-filled`, `data-focused`) |
+| (none) | Indicator `data-starting-style` / `data-ending-style` |
+
+No CSS variables on either side.
+
+---
+
+# switch
+
+Part mapping: `Root -> Root`, `Thumb -> Thumb`. Element change: Radix Root renders `<button>` + hidden input in forms; Base UI Root renders `<span>` plus hidden `<input>` always (use `nativeButton` + `render` for a real button).
+
+## Switch.Root → Switch.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern, pair with `nativeButton`. |
+| `defaultChecked` | `boolean`, no default | `defaultChecked: boolean`, default `false` | Same. |
+| `checked` | `boolean`, no default | `checked: boolean` | Same. |
+| `onCheckedChange` | `(checked: boolean) => void` | `onCheckedChange: (checked: boolean, eventDetails: Switch.Root.ChangeEventDetails) => void` | Signature changed: added `eventDetails` (`reason: 'none'`). |
+| `disabled` | `boolean`, no default | `disabled: boolean`, default `false` | Same. |
+| `required` | `boolean`, no default | `required: boolean`, default `false` | Same. |
+| `name` | `string`, no default | `name: string` | Same. |
+| `value` | `string`, default `"on"` | `value: string` | Same name. Base UI submits `"on"` by default, matching native checkbox behavior. |
+
+## Switch.Thumb → Switch.Thumb
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern, only prop on either side. |
+
+## Base UI only props worth knowing (switch)
+
+- `Root.readOnly: boolean`, `Root.uncheckedValue: string`, `Root.form: string`, `Root.inputRef`, `Root.id`, `Root.nativeButton` (default `false`).
+
+## Data-attribute mapping (switch)
+
+| Radix | Base UI |
+| --- | --- |
+| Root/Thumb `data-state="checked"` | `data-checked` |
+| Root/Thumb `data-state="unchecked"` | `data-unchecked` |
+| Root/Thumb `data-disabled` | `data-disabled` (same) |
+| (none) | `data-readonly`, `data-required`, Field attrs (`data-valid`, `data-invalid`, `data-dirty`, `data-touched`, `data-filled`, `data-focused`) |
+
+No CSS variables on either side.
+
+---
+
+# slider
+
+Part mapping: `Root -> Root`, `Track -> Track`, `Range -> Indicator` (renamed), `Thumb -> Thumb`, plus a NEW required `Control` part: Base UI anatomy is `Root > Control > Track > (Indicator, Thumb)`. `Control` is the clickable/draggable surface (Radix Root handled pointer interaction itself). Base UI also adds `Value` and `Label` parts. Element change: Radix Thumb renders a plain element wrapped by an invisible span with a hidden input in forms; Base UI Thumb renders a `<div>` with a nested `<input type="range">`.
+
+## Slider.Root → Slider.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| `defaultValue` | `number[]`, no default | `defaultValue: number \| number[]` | Same name, widened: a single `number` gives a single-thumb slider (no array wrapper needed). |
+| `value` | `number[]`, no default | `value: number \| number[]` | Same, widened. Ranged sliders still take an array. |
+| `onValueChange` | `(value: number[]) => void` | `onValueChange: (value: number \| number[], eventDetails: Slider.Root.ChangeEventDetails) => void` | Signature changed: value matches the shape you pass in (number for single), `eventDetails` added with `reason: 'input-change' \| 'track-press' \| 'drag' \| 'keyboard' \| 'none'` and `activeThumbIndex: number`. |
+| `onValueCommit` | `(value: number[]) => void` | `onValueCommitted: (value: number \| number[], eventDetails: Slider.Root.CommitEventDetails) => void` | Renamed (`Commit` -> `Committed`) and signature changed (same shape/eventDetails notes as above). Base UI does not fire it if the value did not change. |
+| `name` | `string`, no default | `name: string` | Same. |
+| `disabled` | `boolean`, default `false` | `disabled: boolean`, default `false` | Same. |
+| `orientation` | `"horizontal" \| "vertical"`, default `"horizontal"` | `orientation: Orientation`, default `'horizontal'` | Same. |
+| `dir` | `"ltr" \| "rtl"`, no default | dropped | Use `DirectionProvider`. |
+| `inverted` | `boolean`, default `false` | dropped (workaround) | No equivalent. For horizontal sliders, wrap in `DirectionProvider dir="rtl"` (direction-based inversion); there is no built-in way to invert a vertical slider. |
+| `min` | `number`, default `0` | `min: number`, default `0` | Same. |
+| `max` | `number`, default `100` | `max: number`, default `100` | Same. |
+| `step` | `number`, default `1` | `step: number`, default `1` | Same. |
+| `minStepsBetweenThumbs` | `number`, default `0` | `minStepsBetweenValues: number`, default `0` | Renamed (`Thumbs` -> `Values`). |
+| `form` | `string`, no default | `form: string` | Same. |
+
+## Slider.Track → Slider.Track (moved inside Control)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. Structural move: Track must now be nested in the new `Slider.Control` part, and `Thumb` moves inside `Track` (Radix had Thumb as a sibling of Track under Root). |
+
+## Slider.Range → Slider.Indicator (renamed)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Renamed part, same role (visualizes the filled portion), still a child of Track. |
+
+## Slider.Thumb → Slider.Thumb
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean`, `false` | `render` | Same pattern. |
+| (per-thumb accessibility via aria props) | - | `index: number`, `getAriaLabel(index)`, `getAriaValueText(formattedValue, value, index)`, `aria-valuetext` | Base UI thumbs take `index` (required for SSR of multi-thumb range sliders) and a11y formatters. Also `disabled`, `inputRef`, `tabIndex`, `onFocus`/`onBlur`/`onKeyDown` forwarded to the nested `<input type="range">`. |
+
+## (new part) Slider.Control
+
+No Radix equivalent. The interactive surface that receives pointer events; wrap `Track` with it. Props: `className`/`style`/`render` only.
+
+## Base UI only props worth knowing (slider)
+
+- `Root.thumbAlignment: 'center' | 'edge' | 'edge-client-only'` (default `'center'`): whether the thumb center or edge aligns with the control edge at min/max. Radix always behaved like `'edge'`-ish via CSS; Base UI defaults to `'center'`, set `thumbAlignment="edge"` to keep the thumb inside the track bounds.
+- `Root.thumbCollisionBehavior: 'push' | 'swap' | 'none'` (default `'push'`): range-slider thumb collision handling (Radix behavior was closest to `'none'`).
+- `Root.largeStep: number` (default `10`): Page Up/Down and Shift+Arrow increment.
+- `Root.format: Intl.NumberFormatOptions` and `Root.locale: Intl.LocalesArgument`: value formatting for `Slider.Value` and `aria-valuetext`.
+- New parts: `Slider.Value` (renders `<output>`, `children: (formattedValues: string[], values: number[]) => ReactNode`), `Slider.Label` (auto-associated label).
+
+## Data-attribute mapping (slider)
+
+| Radix | Base UI |
+| --- | --- |
+| `data-disabled` (all parts) | `data-disabled` (same, all parts) |
+| `data-orientation` (`horizontal/vertical`, all parts) | `data-orientation` (same values, all parts) |
+| (none) | `data-dragging` (present on all parts while dragging) |
+| (none) | Thumb `data-index` (thumb index in range sliders) |
+| (none) | Field attrs on all parts (`data-valid`, `data-invalid`, `data-dirty`, `data-touched`, `data-focused`) |
+
+No CSS variables on either side (Radix slider positions thumbs via inline styles; Base UI does the same).
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/menus.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/menus.md
new file mode 100644
index 00000000..128e13d7
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/menus.md
@@ -0,0 +1,409 @@
+# Radix → Base UI props mapping: menu family
+
+Sources: radix-ui.com primitives docs (dropdown-menu, context-menu, menubar, navigation-menu) and base-ui.com `/react/components/{menu,context-menu,menubar,navigation-menu}.md`, fetched 2026-07-02.
+
+Part-mapping ground truth (from our wrappers): `Content` → `Portal > Positioner > Popup` (side/sideOffset/align/alignOffset live on `Positioner`); `Label` → `GroupLabel`; `ItemIndicator` → `CheckboxItemIndicator`/`RadioItemIndicator`; `Sub` → `SubmenuRoot`; `SubTrigger` → `SubmenuTrigger`; navigation-menu `Viewport` → `Positioner > Popup > Viewport`, `Indicator` → `Icon`; `asChild` → `render`.
+
+Cross-cutting rules (apply to every part below):
+
+| Radix pattern | Base UI equivalent |
+| --- | --- |
+| `asChild` (`boolean`, `false`) | `render` (`ReactElement \| ((props: HTMLProps, state) => ReactElement)`). No merge-onto-child boolean; pass the element or a function. |
+| `dir` (`"ltr" \| "rtl"`) on roots | Dropped everywhere. Base UI reads direction from `<DirectionProvider>` (`@base-ui-components/react/direction-provider`) or the DOM `dir` attribute. |
+| `forceMount` (`boolean`) | `keepMounted` (`boolean`, `false`) on `Portal` / indicator parts. Same use case (animation/SEO), presence is CSS-driven via `data-starting-style` / `data-ending-style` instead of Radix `data-state` + forced mount. |
+| `onEscapeKeyDown` / `onPointerDownOutside` / `onFocusOutside` / `onInteractOutside` (content parts) | Dropped as separate props. Use `onOpenChange(open, eventDetails)` on the Root and branch on `eventDetails.reason` (`'escape-key'`, `'outside-press'`, `'focus-out'`, ...). Call `eventDetails.cancel()` to prevent the close (replaces `event.preventDefault()`). |
+| `onSelect` on items (`(event: Event) => void`; `event.preventDefault()` keeps menu open) | `onClick` (`(event: BaseUIEvent<React.MouseEvent<HTMLDivElement>>) => void`) plus `closeOnClick` (`boolean`) to control whether the menu closes. |
+| `textValue` on items (`string`, typeahead) | `label` (`string`). |
+| Controlled callbacks `(value) => void` | All Base UI change callbacks take a second `eventDetails` argument (`{ reason, event, cancel(), allowPropagation(), isCanceled, isPropagationAllowed, trigger }`). |
+
+---
+
+# dropdown-menu (Radix `DropdownMenu` → Base UI `Menu`)
+
+## Root → Menu.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` / – | `defaultOpen` (`boolean`, `false`) | Same. |
+| `open` | `boolean` / – | `open` (`boolean`) | Same. |
+| `onOpenChange` | `(open: boolean) => void` / – | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: Menu.Root.ChangeEventDetails) => void`. `eventDetails.reason` is one of `'trigger-hover' \| 'trigger-focus' \| 'trigger-press' \| 'outside-press' \| 'focus-out' \| 'list-navigation' \| 'escape-key' \| 'item-press' \| 'close-press' \| 'sibling-open' \| 'cancel-open' \| 'imperative-action' \| 'none'`; `eventDetails.cancel()` blocks the state change. |
+| `modal` | `boolean` / `true` | `modal` (`boolean`, `true`) | Same. |
+| `dir` | `"ltr" \| "rtl"` / – | – | Dropped. Use `DirectionProvider`. |
+
+## Trigger → Menu.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | See cross-cutting rules. When rendering a non-button, also set `nativeButton={false}`. |
+
+## Portal → Menu.Portal
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` / – | `keepMounted` (`boolean`, `false`) | Renamed; keeps portal in DOM while hidden. |
+| `container` | `HTMLElement` / `document.body` | `container` (`HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`) | Same, wider type (accepts refs and ShadowRoot). |
+
+## Content → Menu.Portal > Menu.Positioner > Menu.Popup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` on `Popup` | See cross-cutting rules. |
+| `loop` | `boolean` / `false` | `loopFocus` on **Root** (`boolean`, `true`) | Moved + renamed. Default flips: Base UI loops by default. |
+| `onCloseAutoFocus` | `(event: Event) => void` / – | `finalFocus` on **Popup** | Signature changed: `boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` where `InteractionType = 'mouse' \| 'touch' \| 'pen' \| 'keyboard'`. Return `false` to replicate `event.preventDefault()`; return an element to redirect focus. |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` / – | – | Dropped → `onOpenChange` with `reason === 'escape-key'`. |
+| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` / – | – | Dropped → `onOpenChange` with `reason === 'outside-press'`. |
+| `onFocusOutside` | `(event: FocusOutsideEvent) => void` / – | – | Dropped → `onOpenChange` with `reason === 'focus-out'`. |
+| `onInteractOutside` | `(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void` / – | – | Dropped → `onOpenChange` with `reason === 'outside-press' \|\| 'focus-out'`. |
+| `forceMount` | `boolean` / – | `keepMounted` on **Portal** | Moved; animate with `data-starting-style`/`data-ending-style`. |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` / `"bottom"` | `side` on **Positioner** (`Side`, `'bottom'`) | Moved. Base adds logical values: `Side = 'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'`. |
+| `sideOffset` | `number` / `0` | `sideOffset` on **Positioner** (`number \| OffsetFunction`, `0`) | Moved; also accepts `(data: { side, align, anchor: {width,height}, positioner: {width,height} }) => number`. |
+| `align` | `"start" \| "center" \| "end"` / `"center"` | `align` on **Positioner** (`Align`, `'center'`) | Moved, same values/default. |
+| `alignOffset` | `number` / `0` | `alignOffset` on **Positioner** (`number \| OffsetFunction`, `0`) | Moved; also accepts function form. |
+| `avoidCollisions` | `boolean` / `true` | `collisionAvoidance` on **Positioner** (`CollisionAvoidance`) | Signature changed: object `{ side?: 'flip' \| 'shift' \| 'none'; align?: 'flip' \| 'shift' \| 'none'; fallbackAxisSide?: 'start' \| 'end' \| 'none' }`. `avoidCollisions={false}` → `collisionAvoidance={{ side: 'none', align: 'none', fallbackAxisSide: 'none' }}`. |
+| `collisionBoundary` | `Element \| null \| Array<Element \| null>` / `[]` | `collisionBoundary` on **Positioner** (`Boundary`, `'clipping-ancestors'`) | Default changes: Radix `[]` means viewport/clipping ancestors; Base default `'clipping-ancestors'` is equivalent. Also accepts an element or rect. |
+| `collisionPadding` | `number \| Padding` / `0` | `collisionPadding` on **Positioner** (`Padding`, `5`) | Same shape; default changes 0 → 5. |
+| `arrowPadding` | `number` / `0` | `arrowPadding` on **Positioner** (`number`, `5`) | Same; default changes 0 → 5. |
+| `sticky` | `"partial" \| "always"` / `"partial"` | – (see note) | Different concept. Radix `sticky` controls align-axis sticking; closest Base knob is `collisionAvoidance.align` (`'shift'` ≈ partial). Base UI's own `sticky` (`boolean`, `false`) instead keeps the popup in the viewport after the anchor scrolls away, which has no Radix equivalent. |
+| `hideWhenDetached` | `boolean` / `false` | – | Dropped as behavior prop. Base always exposes `data-anchor-hidden` on Positioner/Popup; hide via CSS: `[data-anchor-hidden] { visibility: hidden }`. |
+
+## Arrow → Menu.Arrow
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base Arrow renders a `<div>` you fill with an SVG (Radix renders the svg itself). Place inside `Popup`. |
+| `width` | `number` / `10` | – | Dropped; size the child SVG/element with CSS. |
+| `height` | `number` / `5` | – | Dropped; size with CSS. |
+
+## Item → Menu.Item
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | For links use `Menu.LinkItem` (renders `<a>`) instead of `render`. |
+| `disabled` | `boolean` / – | `disabled` (`boolean`, `false`) | Same. |
+| `onSelect` | `(event: Event) => void` / – | `onClick` (`(event: BaseUIEvent<React.MouseEvent<HTMLDivElement>>) => void`) | Renamed + signature changed. `event.preventDefault()` in `onSelect` (keep open) → `closeOnClick={false}` (`boolean`, default `true` on Item). |
+| `textValue` | `string` / – | `label` (`string`) | Renamed. |
+
+## Group → Menu.Group
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Same otherwise. |
+
+## Label → Menu.GroupLabel
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Part renamed. Base GroupLabel must be inside a `Group` (it wires `aria-labelledby`); Radix Label could float freely. |
+
+## CheckboxItem → Menu.CheckboxItem
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | – |
+| `checked` | `boolean \| 'indeterminate'` / – | `checked` (`boolean`) | `'indeterminate'` dropped. Base adds `defaultChecked` (`boolean`, `false`) for uncontrolled use. |
+| `onCheckedChange` | `(checked: boolean) => void` / – | `onCheckedChange` | Signature changed: `(checked: boolean, eventDetails: Menu.CheckboxItem.ChangeEventDetails) => void`. |
+| `disabled` | `boolean` / – | `disabled` (`boolean`, `false`) | Same. |
+| `onSelect` | `(event: Event) => void` / – | `onClick` + `closeOnClick` | Behavior default flips: Radix closes on select (unless prevented); Base `closeOnClick` defaults to `false` on CheckboxItem. Set `closeOnClick` explicitly to preserve Radix behavior. |
+| `textValue` | `string` / – | `label` | Renamed. |
+
+## RadioGroup → Menu.RadioGroup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | – |
+| `value` | `string` / – | `value` (`any`) | Type widens to `any`. Base adds `defaultValue` (`any`) and `disabled` (`boolean`, `false`). |
+| `onValueChange` | `(value: string) => void` / – | `onValueChange` | Signature changed: `(value: any, eventDetails: Menu.RadioGroup.ChangeEventDetails) => void`. |
+
+## RadioItem → Menu.RadioItem
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | – |
+| `value`* | `string` / – | `value`* (`any`) | Same (required); type widens. |
+| `disabled` | `boolean` / – | `disabled` (`boolean`, `false`) | Same. |
+| `onSelect` | `(event: Event) => void` / – | `onClick` + `closeOnClick` | `closeOnClick` defaults to `false` on RadioItem (Radix closed by default). |
+| `textValue` | `string` / – | `label` | Renamed. |
+
+## ItemIndicator → Menu.CheckboxItemIndicator / Menu.RadioItemIndicator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Part splits: use the indicator matching the parent item type. Renders `<span>`. |
+| `forceMount` | `boolean` / – | `keepMounted` (`boolean`, `false`) | Renamed. |
+
+## Separator → Menu.Separator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base adds `orientation` (`'horizontal' \| 'vertical'`, `'horizontal'`). |
+
+## Sub → Menu.SubmenuRoot
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` / – | `defaultOpen` (`boolean`, `false`) | Same. |
+| `open` | `boolean` / – | `open` (`boolean`) | Same. |
+| `onOpenChange` | `(open: boolean) => void` / – | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: Menu.SubmenuRoot.ChangeEventDetails) => void` (same reason union as Root). |
+
+## SubTrigger → Menu.SubmenuTrigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Renders `<div>`; `nativeButton` defaults `false` here. |
+| `disabled` | `boolean` / – | `disabled` (`boolean`, `false`) | Same. |
+| `textValue` | `string` / – | `label` | Renamed. Base adds `openOnHover` / `delay` (`100`) / `closeDelay` (`0`) and `onClick`. |
+
+## SubContent → Menu.Portal > Menu.Positioner > Menu.Popup (inside SubmenuRoot)
+
+Same prop fates as **Content** above; Radix-specific defaults to be aware of: `align` default is `"start"` on SubContent (Base Positioner default is `'center'` — set `align="start"` explicitly if you relied on the Radix default; in practice submenu popups anchor to the trigger item and our wrappers set this). Radix SubContent has no `side` prop (side is implied); Base Positioner accepts `side` (use `'inline-end'` for RTL-aware submenus). All outside/escape callbacks, `forceMount`, `loop`, collision props map identically to Content.
+
+## Base UI only props worth knowing (Menu)
+
+- `Root`: `highlightItemOnHover` (`true`), `actionsRef` (`{ unmount(), close() }`), `onOpenChangeComplete(open)` (fires after close animation; replaces the Radix "wait for animation" dance), `closeParentOnEsc` (`false`), `disabled`, `orientation` (`'vertical'`), detached-trigger machinery: `handle` (`Menu.Handle` via `Menu.createHandle()`), `triggerId`/`defaultTriggerId`, payload-aware `children` render function.
+- `Trigger`: `openOnHover`, `delay` (`100`), `closeDelay` (`0`), `payload`, `handle`, `nativeButton` (`true`).
+- `Backdrop`: new part, overlay under the popup.
+- `Positioner`: `anchor`, `positionMethod` (`'absolute'`), `disableAnchorTracking`, `sticky` (boolean, viewport-keeping).
+- `Popup`: `finalFocus`.
+- `Viewport`: new part for animating content swaps with multiple/detached triggers.
+- `LinkItem`: new part, `<a>`-rendering menu item (`closeOnClick` default `false`).
+- All parts: `className`/`style` accept state-callback form `(state) => ...`.
+
+## Data-attribute mapping (dropdown/context/menubar menus)
+
+| Radix | Base UI |
+| --- | --- |
+| Trigger `[data-state="open" \| "closed"]` | `data-popup-open` (presence) + `data-pressed` |
+| Content `[data-state="open" \| "closed"]` | `data-open` / `data-closed` on Positioner and Popup |
+| – | `data-starting-style` / `data-ending-style` (CSS transition hooks, replace animating on `data-state`) |
+| Content `[data-side="left" \| "right" \| "bottom" \| "top"]` | `data-side` (`'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'`) on Positioner/Popup/Arrow |
+| Content `[data-align="start" \| "end" \| "center"]` | `data-align` (same values) on Positioner/Popup/Arrow |
+| Content/Item `[data-orientation]` | Dropped on menu parts |
+| Item `[data-highlighted]` | `data-highlighted` (same) |
+| Item `[data-disabled]` | `data-disabled` (same) |
+| Checkbox/RadioItem `[data-state="checked" \| "unchecked" \| "indeterminate"]` | `data-checked` / `data-unchecked` presence attrs; no indeterminate |
+| ItemIndicator `[data-state]` | `data-checked` / `data-unchecked` + `data-starting-style` / `data-ending-style` on the split indicators |
+| SubTrigger `[data-state="open" \| "closed"]` | `data-popup-open` on SubmenuTrigger |
+| – | Popup `data-instant` (`'click' \| 'dismiss' \| 'group' \| 'trigger-change'`), Positioner `data-anchor-hidden` |
+
+## CSS variable mapping (per menu flavor: `dropdown-menu` / `context-menu` / `menubar`)
+
+| Radix (on Content/SubContent) | Base UI (on Positioner) |
+| --- | --- |
+| `--radix-<name>-content-transform-origin` | `--transform-origin` |
+| `--radix-<name>-content-available-width` | `--available-width` |
+| `--radix-<name>-content-available-height` | `--available-height` |
+| `--radix-<name>-trigger-width` | `--anchor-width` |
+| `--radix-<name>-trigger-height` | `--anchor-height` |
+
+Base UI Menu.Viewport additionally exposes `--popup-width` / `--popup-height` (previous-content dimensions during transitions).
+
+---
+
+# context-menu (Radix `ContextMenu` → Base UI `ContextMenu`)
+
+Base UI ContextMenu shares the Menu part set: `Root, Trigger, Portal, Backdrop, Positioner, Popup, Arrow, Item, Group, GroupLabel, Separator, SubmenuRoot, SubmenuTrigger, RadioGroup, RadioItem, RadioItemIndicator, CheckboxItem, CheckboxItemIndicator, LinkItem`. Everything not listed below maps exactly as in the dropdown-menu section.
+
+## Root → ContextMenu.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `dir` | `"ltr" \| "rtl"` / – | – | Dropped; `DirectionProvider`. |
+| `open` | `boolean` / – | `open` (`boolean`) | Same. Base also adds `defaultOpen` (`false`), which Radix ContextMenu lacked. |
+| `onOpenChange` | `(open: boolean) => void` / – | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: ContextMenu.Root.ChangeEventDetails) => void` (same reason union as Menu). |
+| `modal` | `boolean` / `true` | – | **Dropped.** Base UI ContextMenu.Root has no `modal` prop (behavior is fixed). If you relied on `modal={false}`, there is no direct equivalent. |
+
+## Trigger → ContextMenu.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base Trigger renders a `<div>` (also handles long-press on touch). |
+| `disabled` | `boolean` / `false` | – | **Dropped.** ContextMenu.Trigger has only `className`/`style`/`render`. Workaround: conditionally render content outside the Trigger, or intercept `onContextMenu` with `preventDefault` + `stopPropagation` on a child. |
+
+## Portal → ContextMenu.Portal
+
+Identical mapping to Menu.Portal (`forceMount` → `keepMounted`, `container` widened).
+
+## Content → ContextMenu.Portal > Positioner > Popup
+
+Same fates as dropdown-menu Content for: `asChild`, `loop` (→ Root `loopFocus`), `onCloseAutoFocus` (→ Popup `finalFocus`), `onEscapeKeyDown`/`onPointerDownOutside`/`onFocusOutside`/`onInteractOutside` (→ Root `onOpenChange` reasons), `forceMount` (→ Portal `keepMounted`), `avoidCollisions` (→ `collisionAvoidance`), `collisionBoundary` (default `[]` → `'clipping-ancestors'`), `collisionPadding` (`0` → `5`), `sticky` (dropped, see menu note), `hideWhenDetached` (→ CSS on `data-anchor-hidden`).
+
+Radix-specific deltas:
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `alignOffset` | `number` / `0` | `alignOffset` on Positioner (`number \| OffsetFunction`, `0`) | Radix ContextMenu.Content has no `side`/`sideOffset`/`align` props (anchored to pointer). Base Positioner still accepts `side`/`align`/`sideOffset` but anchors to the pointer position by default; usually leave them off. |
+| (no `arrowPadding` on Content) | – | `arrowPadding` (`5`) on Positioner | Available in Base if you add an Arrow. |
+
+## Arrow / Item / Group / Label / CheckboxItem / RadioGroup / RadioItem / ItemIndicator / Separator / Sub / SubTrigger / SubContent
+
+Identical fates to the dropdown-menu section (Label → `GroupLabel`, ItemIndicator → `CheckboxItemIndicator`/`RadioItemIndicator`, Sub → `SubmenuRoot`, SubTrigger → `SubmenuTrigger`, SubContent → `Portal > Positioner > Popup`). Menubar/ContextMenu submenus in Base are the same components with the same props (`onOpenChange` eventDetails, `label`, `onClick`/`closeOnClick`, `keepMounted`).
+
+## Base UI only, data attributes, CSS variables
+
+Same as the Menu lists above; ContextMenu.Root additionally supports `handle` (`MenuHandle<unknown>`), `triggerId`/`defaultTriggerId`, `actionsRef`, `onOpenChangeComplete`, `highlightItemOnHover`, `closeParentOnEsc`, `disabled`, `orientation`. Trigger data attributes: `data-popup-open`, `data-pressed` (replacing Radix Trigger `[data-state]`). CSS vars: `--radix-context-menu-*` → `--transform-origin`/`--available-*`/`--anchor-*` on Positioner.
+
+---
+
+# menubar (Radix `Menubar` → Base UI `Menubar` + `Menu`)
+
+Base UI's menubar module exports a single `<Menubar>` container. Every menu inside it is built from `Menu.*` parts (`Menu.Root`, `Menu.Trigger`, `Menu.Portal`, `Menu.Positioner`, `Menu.Popup`, items, submenus...). So the Radix `Menubar.Menu/Trigger/Portal/Content/...` parts all map to the `Menu` component family from the dropdown-menu section.
+
+## Root → Menubar
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Same pattern. |
+| `defaultValue` | `string` / – | – | **Dropped.** Base Menubar has no controlled/uncontrolled active-menu value. To pre-open a menu, use `defaultOpen` on that `Menu.Root`. |
+| `value` | `string` / – | – | **Dropped.** Control individual `Menu.Root` `open` props instead. |
+| `onValueChange` | `(value: string) => void` / – | – | **Dropped.** Listen via each `Menu.Root` `onOpenChange`. |
+| `dir` | `"ltr" \| "rtl"` / – | – | Dropped; `DirectionProvider`. |
+| `loop` | `boolean` / `false` | `loopFocus` (`boolean`, `true`) | Renamed; default flips to `true`. |
+
+Base UI only on `Menubar`: `modal` (`boolean`, `true`), `disabled` (`boolean`, `false`), `orientation` (`'horizontal' \| 'vertical'`, `'horizontal'`).
+
+## Menu → Menu.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | – | Menu.Root renders no element; drop it. |
+| `value` | `string` / – | – | Dropped with the Menubar value system (see Root). |
+
+Note: `Menu.Root` inside a Menubar accepts all Menu.Root props (`open`, `defaultOpen`, `onOpenChange(open, eventDetails)`, `modal`, `loopFocus`, `orientation`, `disabled`, ...). Hover-switching between menubar menus is built in.
+
+## Trigger → Menu.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton={false}` for non-buttons) | Radix Menubar.Trigger data attrs `[data-state]`/`[data-highlighted]`/`[data-disabled]` → `data-popup-open`/`data-pressed` (no highlighted state on Base trigger). |
+
+## Portal / Content / Arrow / Item / Group / Label / CheckboxItem / RadioGroup / RadioItem / ItemIndicator / Separator / Sub / SubTrigger / SubContent
+
+All identical to the **dropdown-menu** section (they are literally the same Base UI `Menu` components):
+
+- `Portal.forceMount` → `keepMounted`; `container` widened.
+- `Content` (`loop`, `onCloseAutoFocus`, outside/escape callbacks, `forceMount`, `side`/`sideOffset`/`align`/`alignOffset`, `avoidCollisions`, `collisionBoundary`, `collisionPadding`, `arrowPadding`, `sticky`, `hideWhenDetached`) → `Menu.Portal > Menu.Positioner > Menu.Popup` with the exact fates listed for dropdown-menu Content.
+- `SubContent` `align` default `"start"` note applies as in dropdown-menu.
+- Items: `onSelect` → `onClick` + `closeOnClick`, `textValue` → `label`.
+- Radix Menubar CheckboxItem/RadioItem `[data-state="checked" \| "unchecked"]` → `data-checked`/`data-unchecked`.
+
+## Data attributes / CSS variables
+
+- Menubar container: Radix Root had none; Base `Menubar` exposes `data-orientation` (`'horizontal' \| 'vertical'`), `data-has-submenu-open`, `data-modal`.
+- Menu-part attributes and `--radix-menubar-*` CSS vars map exactly as in the dropdown-menu tables (`--transform-origin`, `--available-width/height`, `--anchor-width/height` on `Menu.Positioner`).
+
+---
+
+# navigation-menu (Radix `NavigationMenu` → Base UI `NavigationMenu`)
+
+Base UI parts: `Root, List, Item, Trigger, Icon, Content, Portal, Backdrop, Positioner, Popup, Arrow, Viewport, Link`. Popup positioning is real anchored positioning (like Menu): the shared popup renders as `Portal > Positioner > Popup > Viewport`, and each `Item`'s `Content` is moved into the `Viewport` when active. Radix's "Viewport rendered below the list" model is replaced by this anchored Positioner model (our wrappers removed the `viewport` boolean prop accordingly).
+
+## Root → NavigationMenu.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultValue` | `string` / – | `defaultValue` (`Value \| null`, `null`) | Type widens (`Value = any`); `null` = closed. |
+| `value` | `string` / – | `value` (`Value \| null`, `null`) | Same; non-nullish = open. |
+| `onValueChange` | `(value: string) => void` / – | `onValueChange` | Signature changed: `(value: Value \| null, eventDetails: NavigationMenu.Root.ChangeEventDetails) => void`; reasons: `'trigger-press' \| 'trigger-hover' \| 'outside-press' \| 'list-navigation' \| 'focus-out' \| 'escape-key' \| 'link-press' \| 'none'`. |
+| `delayDuration` | `number` / `200` | `delay` (`number`, `50`) | Renamed; default 200 → 50. |
+| `skipDelayDuration` | `number` / `300` | – | **Dropped.** No skip-delay window; Base instead has `closeDelay` (`number`, `50`). |
+| `dir` | `"ltr" \| "rtl"` / – | – | Dropped; `DirectionProvider`. |
+| `orientation` | `"horizontal" \| "vertical"` / `"horizontal"` | `orientation` (same values/default) | Same. |
+
+Base UI only on Root: `closeDelay` (`50`), `actionsRef` (`{ unmount() }`), `onOpenChangeComplete(open)`. Root renders a `<nav>` element (Radix Root also rendered `<nav>`; Base renders `<div>` when nested).
+
+## Sub → nested NavigationMenu.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultValue` / `value` / `onValueChange` / `orientation` | as Root | same props on the nested `Root` | Part dropped: nest a whole `NavigationMenu.Root` (with its own `List`/`Portal`/`Positioner`/`Popup`) inside a `Content`; it renders a `<div>` when nested. Unlike Radix Sub, a nested Base menu is closed by default (`null`), not required to always have an active item. |
+
+## List → NavigationMenu.List
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base List renders `<ul>` (Radix also `<ul>`). Radix `[data-orientation]` attr dropped. |
+
+## Item → NavigationMenu.Item
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base Item renders `<li>`. |
+| `value` | `string` / – | `value` (`any`) | Same; auto-generated if omitted. |
+
+## Trigger → NavigationMenu.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | `[data-state="open" \| "closed"]` → `data-popup-open`; `[data-disabled]` dropped (no disabled prop either — gate at the item level yourself). |
+
+## Content → NavigationMenu.Content
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | – |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` / – | – | Dropped → Root `onValueChange` with `reason === 'escape-key'` + `eventDetails.cancel()`. |
+| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` / – | – | Dropped → `reason === 'outside-press'`. |
+| `onFocusOutside` | `(event: FocusOutsideEvent) => void` / – | – | Dropped → `reason === 'focus-out'`. |
+| `onInteractOutside` | `(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void` / – | – | Dropped → `'outside-press' \| 'focus-out'`. |
+| `forceMount` | `boolean` / – | `keepMounted` (`boolean`, `false`) | Renamed, stays on Content (keeps content in DOM while closed, e.g. for SEO/SSR). |
+
+## Link → NavigationMenu.Link
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | For framework links: `render={<NextLink href=... />}`. |
+| `active` | `boolean` / `false` | `active` (`boolean`, `false`) | Same (sets `aria-current` + `data-active`). |
+| `onSelect` | `(event: Event) => void` / – | – | Dropped. Use `onClick` (plain DOM prop) and `closeOnClick` (`boolean`, `false`) — note Radix closed the menu on link select by default, Base does not; set `closeOnClick` for parity. |
+
+## Indicator → NavigationMenu.Icon (per wrapper ground truth)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Different role: Radix Indicator tracked the active trigger below the List; Base `Icon` is a chevron inside the Trigger (`data-popup-open` when its menu is open). For a popup-anchored pointer, Base's `Arrow` (inside `Popup`, with `data-side`/`data-align`/`data-uncentered`) is the closest visual analogue. There is no Base part that tracks the active trigger along the list. |
+| `forceMount` | `boolean` / – | – | Dropped (Icon is always rendered). |
+| `[data-state="visible" \| "hidden"]`, `[data-orientation]` | – | – | Dropped; Icon exposes only `data-popup-open`. |
+
+## Viewport → NavigationMenu.Portal > Positioner > Popup > Viewport
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` on each new part | One Radix part becomes four: `Portal` (props: `container`, `keepMounted`), `Positioner` (full anchored-positioning prop set identical to Menu.Positioner: `side`/`sideOffset`/`align`/`alignOffset` (`number \| OffsetFunction`), `anchor`, `collisionAvoidance`, `collisionBoundary` `'clipping-ancestors'`, `collisionPadding` `5`, `arrowPadding` `5`, `sticky` boolean, `positionMethod`, `disableAnchorTracking`), `Popup` (renders `<nav>`), `Viewport` (clips/animates the active `Content`). |
+| `forceMount` | `boolean` / – | `keepMounted` on **Portal** | Renamed + moved. |
+
+## Base UI only props worth knowing (NavigationMenu)
+
+- Root: `closeDelay`, `actionsRef`, `onOpenChangeComplete`.
+- New parts: `Backdrop`, `Arrow`, `Positioner` (real collision-aware positioning — Radix nav-menu had none), `Icon`.
+- `Content.keepMounted` for crawler-visible SSR content.
+- `Link.closeOnClick`.
+- All parts accept `className`/`style` state-callback forms and `render`.
+
+## Data-attribute mapping (navigation-menu)
+
+| Radix | Base UI |
+| --- | --- |
+| Root/Sub/List/Item `[data-orientation]` | Dropped. |
+| Trigger `[data-state="open" \| "closed"]` | `data-popup-open` on Trigger (and on Icon). |
+| Trigger `[data-disabled]` | Dropped. |
+| Content `[data-state="open" \| "closed"]` | `data-open` / `data-closed` on Content (also on Positioner/Popup/Backdrop). |
+| Content `[data-motion="to-start" \| "to-end" \| "from-start" \| "from-end"]` | `data-activation-direction` (`'left' \| 'right' \| 'up' \| 'down'`) on Content — direction the newly-activated trigger is relative to the previous one; use for enter/exit animations. |
+| Link `[data-active]` | `data-active` (same). |
+| Indicator `[data-state="visible" \| "hidden"]` | No equivalent (see Indicator row). Arrow exposes `data-open`/`data-closed`/`data-uncentered`/`data-side`/`data-align`. |
+| Viewport `[data-state]`, `[data-orientation]` | `data-open`/`data-closed` + `data-starting-style`/`data-ending-style` on Popup/Positioner; Viewport itself exposes none. |
+| – | Positioner: `data-anchor-hidden`, `data-instant`; Popup: `data-side`, `data-align`. |
+
+## CSS variable mapping (navigation-menu)
+
+| Radix | Base UI |
+| --- | --- |
+| `--radix-navigation-menu-viewport-width` (on Viewport) | `--popup-width` (`number`, on **Popup**) — fixed width of the popup; animate `width: var(--popup-width)`. |
+| `--radix-navigation-menu-viewport-height` (on Viewport) | `--popup-height` (`number`, on **Popup**). |
+| – | Positioner also exposes `--anchor-width`, `--anchor-height`, `--available-width`, `--available-height`, `--positioner-width`, `--positioner-height`, `--transform-origin`. |
+
+---
+
+## Gaps / caveats
+
+- Radix prop descriptions are rendered in JS popovers; types/defaults above were extracted from the pages' embedded type payloads (`(open: boolean) => void`, `(checked: boolean) => void`, `(value: string) => void`, `(event: KeyboardEvent) => void`, `(event: PointerDownOutsideEvent) => void`, `(event: FocusOutsideEvent) => void`, `(event: PointerDownOutsideEvent | FocusOutsideEvent) => void`, `(event: Event) => void` for `onSelect`/`onCloseAutoFocus`, `Boundary = Element | null | Array<Element | null>`, `sticky: "partial" | "always"`, `dir: "ltr" | "rtl"`) — all verified against the fetched HTML.
+- Base UI ContextMenu.Root genuinely lacks `modal`; Menubar lacks the value/onValueChange system; ContextMenu.Trigger lacks `disabled`. These are the three hard drops with no one-line workaround.
+- Base UI docs fetched from the `.md` endpoints reflect Base UI 1.x (repo currently pins 1.6.0).
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/overlays.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/overlays.md
new file mode 100644
index 00000000..ea950e1d
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/overlays.md
@@ -0,0 +1,459 @@
+# Radix UI → Base UI props migration mapping (overlays)
+
+Components covered: dialog, alert-dialog, popover, tooltip, hover-card (Base UI: preview-card).
+
+Sources: radix-ui.com primitives docs (fetched 2026-07-02) and base-ui.com `/react/components/*.md` endpoints (fetched 2026-07-02).
+
+Global conventions that apply to every component below:
+
+- `asChild` (Radix, every part) → `render` (Base UI, every part). Radix: `asChild?: boolean` merges props onto the single child. Base UI: `render?: ReactElement | ((props: HTMLProps, state: Part.State) => ReactElement)`. For buttons replaced with non-button elements, also set `nativeButton={false}`.
+- `onOpenChange` signature changed everywhere. Radix: `(open: boolean) => void`. Base UI: `(open: boolean, eventDetails: X.Root.ChangeEventDetails) => void` where `eventDetails` is `{ reason, event, trigger, cancel(), allowPropagation(), isCanceled, isPropagationAllowed, preventUnmountOnClose() }`.
+- Radix per-interaction dismiss callbacks (`onEscapeKeyDown`, `onPointerDownOutside`, `onFocusOutside`, `onInteractOutside`) have NO 1:1 Base UI props. They are replaced by `onOpenChange`'s `eventDetails.reason` (`'escape-key'`, `'outside-press'`, `'focus-out'`) + `eventDetails.cancel()` to prevent the close (the equivalent of Radix `event.preventDefault()`).
+- `forceMount` (Radix, Portal/Overlay/Content) → `keepMounted` on Base UI `Portal` only (`boolean`, default `false`). For exit animations Base UI does not need it: it holds the popup mounted itself and exposes `data-starting-style` / `data-ending-style`, `onOpenChangeComplete`, and `actionsRef.current.unmount()` for externally-controlled animations.
+- Base UI `className` and `style` accept state callbacks (`(state) => ...`) on every rendered part.
+- Radix `[data-state="open" | "closed"]` → Base UI presence attributes `data-open` / `data-closed`.
+
+---
+
+# dialog
+
+Part mapping: Root→Root, Trigger→Trigger, Portal→Portal, Overlay→Backdrop, Content→Popup (centered modal: no Positioner), Title→Title, Description→Description, Close→Close.
+
+## Root → Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` / - (Base default `false`) | `defaultOpen` | Same. |
+| `open` | `boolean` / - | `open` | Same. |
+| `onOpenChange` | `(open: boolean) => void` / - | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => void`. Reasons: `'trigger-press' \| 'outside-press' \| 'escape-key' \| 'close-press' \| 'focus-out' \| 'imperative-action' \| 'none'`. |
+| `modal` | `boolean` / `true` | `modal` | Widened: `boolean \| 'trap-focus'`, default `true`. `'trap-focus'` traps focus without scroll lock / outside-pointer blocking. |
+
+## Trigger → Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | `render={<MyButton />}`; add `nativeButton={false}` if the rendered element is not a `<button>`. |
+
+## Portal → Portal
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` / - | `keepMounted` | Renamed + inverted intent: `keepMounted?: boolean` (default `false`) keeps the portal in the DOM while hidden. Usually droppable; Base UI keeps the popup mounted during exit animations automatically. |
+| `container` | `HTMLElement` / `document.body` | `container` | Same name, wider type: `HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`. Note: Base UI Portal renders a `<div>` wrapper (Radix Portal renders nothing extra per child). |
+
+## Overlay → Backdrop
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Same pattern. |
+| `forceMount` | `boolean` / - | dropped | Backdrop stays mounted through exit animations natively; use `Portal keepMounted` if you need always-mounted DOM. Base-only: `forceRender` (`boolean`, default `false`) forces the backdrop to render even when the dialog is nested. |
+
+## Content → Popup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Same pattern. |
+| `forceMount` | `boolean` / - | dropped | See Portal `keepMounted` + `Root actionsRef.unmount()` + `onOpenChangeComplete`. |
+| `onOpenAutoFocus` | `(event: Event) => void` / - | moved to Popup `initialFocus` | Signature changed. Radix: prevent via `event.preventDefault()`. Base: `initialFocus?: boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`. `false` = don't move focus; ref/element = focus target; function receives `'mouse' \| 'touch' \| 'pen' \| 'keyboard'`. |
+| `onCloseAutoFocus` | `(event: Event) => void` / - | moved to Popup `finalFocus` | Same shape as `initialFocus` but for close (`closeType: InteractionType`). |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` / - | moved to Root `onOpenChange` | `if (eventDetails.reason === 'escape-key') eventDetails.cancel()` replaces `event.preventDefault()`. |
+| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` / - | moved to Root `onOpenChange` | Reason `'outside-press'`; cancel with `eventDetails.cancel()`. Declarative shortcut: Root `disablePointerDismissal` (`boolean`, default `false`). |
+| `onInteractOutside` | `(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void` / - | moved to Root `onOpenChange` | Covers reasons `'outside-press'` and `'focus-out'` (focus-out applies to non-modal dialogs). |
+
+## Title → Title / Description → Description / Close → Close
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` (Title) | `boolean` / `false` | `render` | Base Title renders `<h2>`. |
+| `asChild` (Description) | `boolean` / `false` | `render` | Base Description renders `<p>`. |
+| `asChild` (Close) | `boolean` / `false` | `render` | Base Close renders `<button>`; `nativeButton` available. |
+
+## Base UI only props worth knowing (dialog)
+
+- Root: `actionsRef` (`RefObject<{ unmount(), close() }>`), `onOpenChangeComplete: (open: boolean) => void`, `disablePointerDismissal`, `modal: 'trap-focus'`, `handle` / `triggerId` / `defaultTriggerId` + `Dialog.createHandle()` (detached and multiple triggers), `children` as payload render function.
+- Trigger: `payload`, `handle`, `id`, `nativeButton`.
+- Popup: `initialFocus`, `finalFocus`.
+- Backdrop: `forceRender`.
+- New part: `Viewport` (scrollable positioning container for the popup, useful for outside-scroll dialogs).
+
+## Data attributes (dialog)
+
+| Radix | Base UI | Where |
+| --- | --- | --- |
+| `[data-state="open"]` | `data-open` | Backdrop, Popup, Viewport (presence attr). |
+| `[data-state="closed"]` | `data-closed` | Backdrop, Popup, Viewport. |
+| `[data-state]` on Trigger | `data-popup-open` | Trigger (presence attr). |
+| - | `data-disabled` | Trigger, Close. |
+| - | `data-starting-style` / `data-ending-style` | Backdrop, Popup, Viewport; hooks for enter/exit CSS transitions (replaces Radix animate-on-`data-state` idiom). |
+| - | `data-nested`, `data-nested-dialog-open` | Popup, Viewport. |
+
+## CSS variables (dialog)
+
+| Radix | Base UI |
+| --- | --- |
+| (none documented) | `--nested-dialogs` (`number`, on Popup): count of dialogs nested within. |
+
+---
+
+# alert-dialog
+
+Part mapping: Root→Root, Trigger→Trigger, Portal→Portal, Overlay→Backdrop, Content→Popup, Title→Title, Description→Description, Cancel→Close, Action→NO primitive (render a plain button; close via controlled state, `Root actionsRef.close()`, or reuse `AlertDialog.Close` with action semantics in the wrapper). Base UI AlertDialog is always modal and never closes on outside press by default (no `modal` prop, reasons still include `'outside-press'`/`'focus-out'` in the type but pointer dismissal is disabled by design).
+
+## Root → Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` / - (Base default `false`) | `defaultOpen` | Same. |
+| `open` | `boolean` / - | `open` | Same. |
+| `onOpenChange` | `(open: boolean) => void` / - | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: AlertDialog.Root.ChangeEventDetails) => void`. Same reason union as dialog. |
+
+(Radix AlertDialog.Root has no `modal` prop; Base UI AlertDialog.Root also has none. Parity.)
+
+## Trigger → Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Plus `nativeButton`, `payload`, `handle`, `id`. |
+
+## Portal → Portal
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` / - | `keepMounted` | Same as dialog. |
+| `container` | `HTMLElement` / `document.body` | `container` | Same as dialog (wider type, renders a `<div>`). |
+
+## Overlay → Backdrop
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Same pattern. |
+| `forceMount` | `boolean` / - | dropped | Base-only `forceRender` exists for nested cases. |
+
+## Content → Popup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Same pattern. |
+| `forceMount` | `boolean` / - | dropped | See dialog notes. |
+| `onOpenAutoFocus` | `(event: Event) => void` / - | moved to Popup `initialFocus` | Same semantics as dialog. Note: Radix alert-dialog focuses `Cancel` by default; Base UI focuses the first tabbable element. To preserve Radix behavior pass `initialFocus={cancelRef}`. |
+| `onCloseAutoFocus` | `(event: Event) => void` / - | moved to Popup `finalFocus` | Same as dialog. |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` / - | moved to Root `onOpenChange` | Reason `'escape-key'` + `eventDetails.cancel()`. |
+
+(Radix AlertDialog.Content intentionally has no `onPointerDownOutside`/`onInteractOutside`; nothing to map.)
+
+## Title → Title / Description → Description
+
+Same as dialog: `asChild` → `render`. Title renders `<h2>`, Description renders `<p>`.
+
+## Cancel → Close
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` on `AlertDialog.Close` | Renamed part. `nativeButton` available. Radix's "Cancel receives focus on open" default must be recreated with Popup `initialFocus`. |
+
+## Action → (no primitive)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | dropped | No Base UI part. Wrapper renders a styled `<button>`; close after the action via controlled `open`, `actionsRef.current.close()`, or by composing `AlertDialog.Close` and running the action in `onClick`. |
+
+## Base UI only props worth knowing (alert-dialog)
+
+- Root: `actionsRef`, `onOpenChangeComplete`, `handle` / `triggerId` / `defaultTriggerId` + `AlertDialog.createHandle()`, payload-render `children`.
+- Popup: `initialFocus`, `finalFocus`.
+- Backdrop: `forceRender`. New part: `Viewport`.
+
+## Data attributes (alert-dialog)
+
+Identical table to dialog: `data-state="open"/"closed"` → `data-open`/`data-closed` (Backdrop, Popup, Viewport); Trigger `data-state` → `data-popup-open`; Base-only `data-disabled` (Trigger, Close), `data-starting-style`, `data-ending-style`, `data-nested`, `data-nested-dialog-open`.
+
+## CSS variables (alert-dialog)
+
+| Radix | Base UI |
+| --- | --- |
+| (none documented) | `--nested-dialogs` (`number`, on Popup). |
+
+---
+
+# popover
+
+Part mapping: Root→Root, Trigger→Trigger, Anchor→(Positioner `anchor` prop), Portal→Portal, Content→Portal>Positioner>Popup (positioning props move to Positioner; focus/dismiss concerns split between Popup and Root), Close→Close, Arrow→Arrow. Base UI also has Backdrop, Title, Description, Viewport parts with no Radix counterpart.
+
+## Root → Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` / - (Base default `false`) | `defaultOpen` | Same. |
+| `open` | `boolean` / - | `open` | Same. |
+| `onOpenChange` | `(open: boolean) => void` / - | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: Popover.Root.ChangeEventDetails) => void`. Reasons add hover/focus: `'trigger-hover' \| 'trigger-focus' \| 'trigger-press' \| 'outside-press' \| 'escape-key' \| 'close-press' \| 'focus-out' \| 'imperative-action' \| 'none'`. |
+| `modal` | `boolean` / `false` | `modal` | Widened: `boolean \| 'trap-focus'`, default `false`. When `true`, focus trapping requires a `Popover.Close` inside the Popup (can be `sr-only`). |
+
+## Trigger → Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Plus `nativeButton`. Base-only on Trigger: `openOnHover` (`false`), `delay` (`300`), `closeDelay` (`0`), `payload`, `handle`, `id`. |
+
+## Anchor → Positioner `anchor` prop
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | dropped (part removed) | No Anchor part. Pass `anchor` to Positioner: `Element \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null`. Default anchor is the trigger. |
+
+## Portal → Portal
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` / - | `keepMounted` | `boolean`, default `false`. |
+| `container` | `HTMLElement` / `document.body` | `container` | Wider type (adds ShadowRoot/RefObject); Portal renders a `<div>`. |
+
+## Content → Positioner + Popup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` (Popup) | Same pattern. |
+| `onOpenAutoFocus` | `(event: Event) => void` / - | moved to Popup `initialFocus` | Same shape as dialog (`boolean \| RefObject \| (openType: InteractionType) => ...`). |
+| `onCloseAutoFocus` | `(event: Event) => void` / - | moved to Popup `finalFocus` | Same shape. |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` / - | moved to Root `onOpenChange` | Reason `'escape-key'` + `eventDetails.cancel()`. |
+| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` / - | moved to Root `onOpenChange` | Reason `'outside-press'` + `eventDetails.cancel()`. |
+| `onFocusOutside` | `(event: FocusOutsideEvent) => void` / - | moved to Root `onOpenChange` | Reason `'focus-out'` + `eventDetails.cancel()`. |
+| `onInteractOutside` | `(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void` / - | moved to Root `onOpenChange` | Handle both `'outside-press'` and `'focus-out'`. |
+| `forceMount` | `boolean` / - | dropped | Use Portal `keepMounted`, `onOpenChangeComplete`, `actionsRef.unmount()`. |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` / `"bottom"` | moved to Positioner `side` | Type is `Side` which adds logical values `'inline-start' \| 'inline-end'`. Default `'bottom'` (same). |
+| `sideOffset` | `number` / `0` | moved to Positioner `sideOffset` | Widened: `number \| OffsetFunction` where the function receives `{ anchor, positioner, side, align }`. Default `0` (same). |
+| `align` | `"start" \| "center" \| "end"` / `"center"` | moved to Positioner `align` | Same values/default. |
+| `alignOffset` | `number` / `0` | moved to Positioner `alignOffset` | Widened: `number \| OffsetFunction`. Default `0` (same). |
+| `avoidCollisions` | `boolean` / `true` | moved to Positioner `collisionAvoidance` | Signature changed. Radix boolean → Base `CollisionAvoidance` object `{ side?: 'flip' \| 'shift' \| 'none'; align?: 'flip' \| 'shift' \| 'none'; fallbackAxisSide?: 'start' \| 'end' \| 'none' }`. `avoidCollisions={false}` → `collisionAvoidance={{ side: 'none', align: 'none', fallbackAxisSide: 'none' }}`. |
+| `collisionBoundary` | `Boundary (Element \| null \| Array<Element \| null>)` / `[]` | moved to Positioner `collisionBoundary` | Same name; Base `Boundary` defaults to `'clipping-ancestors'` (Radix default = viewport/clipping ancestors via `[]`). |
+| `collisionPadding` | `number \| Padding` / `0` | moved to Positioner `collisionPadding` | Same shape; default changes `0` → `5`. |
+| `arrowPadding` | `number` / `0` | moved to Positioner `arrowPadding` | Same; default changes `0` → `5`. |
+| `sticky` | `"partial" \| "always"` / `"partial"` | dropped (repurposed name) | Radix `sticky` governed alignment-axis sticking; Base equivalent is `collisionAvoidance.align` (`'shift'` ≈ sticky behavior). CAUTION: Base UI Positioner has a `sticky: boolean` (default `false`) prop with a DIFFERENT meaning: keep the popup in the viewport after the anchor scrolls out of view. Do not copy the Radix value across. |
+| `hideWhenDetached` | `boolean` / `false` | dropped (with workaround) | Positioner/Popup expose `data-anchor-hidden` when the anchor is hidden; recreate with CSS: `[data-anchor-hidden] { visibility: hidden }` on the Positioner. |
+
+## Close → Close
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Plus `nativeButton`. |
+
+## Arrow → Arrow
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Radix renders an `<svg>`; Base renders a `<div>` — supply your own SVG child. |
+| `width` | `number` / `10` | dropped | Size the arrow element/SVG via CSS. |
+| `height` | `number` / `5` | dropped | Size via CSS. Arrow must be a child of Popup (inside Positioner). |
+
+## Base UI only props worth knowing (popover)
+
+- Root: `actionsRef`, `onOpenChangeComplete`, `handle` / `triggerId` / `defaultTriggerId` + `Popover.createHandle()`, payload-render `children`, `modal: 'trap-focus'`.
+- Trigger: `openOnHover` + `delay` + `closeDelay` (hover-open popovers), `payload`, `nativeButton`, `id`.
+- Positioner: `positionMethod` (`'absolute' \| 'fixed'`), `disableAnchorTracking`, `anchor`, `collisionAvoidance`.
+- Popup: `initialFocus`, `finalFocus`.
+- New parts: `Backdrop`, `Title`, `Description`, `Viewport` (animated content swaps between multiple triggers).
+
+## Data attributes (popover)
+
+| Radix (on Content/Trigger/Arrow) | Base UI | Where |
+| --- | --- | --- |
+| `[data-state="open"/"closed"]` | `data-open` / `data-closed` | Backdrop, Positioner, Popup, Arrow. |
+| `[data-state]` on Trigger | `data-popup-open` | Trigger. Base also adds `data-pressed`. |
+| `[data-side]` `"left" \| "right" \| "bottom" \| "top"` | `data-side` | Positioner, Popup, Arrow; values extended with `'inline-start' \| 'inline-end'`. |
+| `[data-align]` `"start" \| "end" \| "center"` | `data-align` | Positioner, Popup, Arrow. |
+| - | `data-starting-style` / `data-ending-style` | Popup, Backdrop (enter/exit animation hooks). |
+| - | `data-anchor-hidden` | Positioner (replaces `hideWhenDetached`). |
+| - | `data-instant` (`'click' \| 'dismiss' \| 'focus' \| 'trigger-change'`) | Popup. |
+| - | `data-uncentered` | Arrow (arrow can't center on anchor). |
+
+## CSS variables (popover)
+
+| Radix (on Content) | Base UI (on Positioner unless noted) |
+| --- | --- |
+| `--radix-popover-content-transform-origin` | `--transform-origin` |
+| `--radix-popover-content-available-width` | `--available-width` |
+| `--radix-popover-content-available-height` | `--available-height` |
+| `--radix-popover-trigger-width` | `--anchor-width` |
+| `--radix-popover-trigger-height` | `--anchor-height` |
+| - | `--positioner-width` / `--positioner-height` (Positioner), `--popup-width` / `--popup-height` (Popup, and on Viewport's previous container) |
+
+---
+
+# tooltip
+
+Part mapping: Provider→Provider, Root→Root, Trigger→Trigger, Portal→Portal, Content→Portal>Positioner>Popup, Arrow→Arrow. Delay control moves: Radix `delayDuration` lives on Provider/Root; Base UI open/close delays live on Provider (`delay`/`closeDelay`) and Trigger (`delay`/`closeDelay`).
+
+## Provider → Provider
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `delayDuration` | `number` / `700` | `delay` | Renamed. Base has no documented default on Provider (Trigger default is `600`). |
+| `skipDelayDuration` | `number` / `300` | `timeout` | Renamed + semantics kept: another tooltip opens instantly if the previous closed within `timeout` ms. Default `300` → `400`. |
+| `disableHoverableContent` | `boolean` / - | dropped at Provider; see Root `disableHoverablePopup` | Base UI equivalent exists only per-Root (renamed). |
+
+## Root → Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` / - (Base default `false`) | `defaultOpen` | Same. |
+| `open` | `boolean` / - | `open` | Same. |
+| `onOpenChange` | `(open: boolean) => void` / - | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: Tooltip.Root.ChangeEventDetails) => void`. Reasons: `'trigger-hover' \| 'trigger-focus' \| 'trigger-press' \| 'outside-press' \| 'escape-key' \| 'disabled' \| 'imperative-action' \| 'none'`. |
+| `delayDuration` | `number` / `700` | moved to Trigger `delay` | `number`, default `600`. `closeDelay` (default `0`) is also on Trigger. |
+| `disableHoverableContent` | `boolean` / - | `disableHoverablePopup` | Renamed; `boolean`, default `false`. |
+
+## Trigger → Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base-only on Trigger: `delay` (`600`), `closeDelay` (`0`), `closeOnClick` (`true`), `disabled` (`false`), `payload`, `handle`. |
+
+## Portal → Portal
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` / - | `keepMounted` | `boolean`, default `false`. |
+| `container` | `HTMLElement` / `document.body` | `container` | Wider type; renders a `<div>`. |
+
+## Content → Positioner + Popup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` (Popup) | Same pattern. |
+| `aria-label` | `string` / - | dropped (plain DOM attr) | Pass `aria-label` straight through to Popup if needed; no special prop. |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` / - | moved to Root `onOpenChange` | Reason `'escape-key'` + `eventDetails.cancel()`. |
+| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` / - | moved to Root `onOpenChange` | Reason `'outside-press'` + `eventDetails.cancel()`. |
+| `forceMount` | `boolean` / - | dropped | Portal `keepMounted` / `actionsRef.unmount()`. |
+| `side` | enum / `"top"` | moved to Positioner `side` | `Side` (adds `'inline-start' \| 'inline-end'`); default `'top'` (same). |
+| `sideOffset` | `number` / `0` | moved to Positioner `sideOffset` | `number \| OffsetFunction`; default `0`. |
+| `align` | enum / `"center"` | moved to Positioner `align` | Same values/default. |
+| `alignOffset` | `number` / `0` | moved to Positioner `alignOffset` | `number \| OffsetFunction`; default `0`. |
+| `avoidCollisions` | `boolean` / `true` | moved to Positioner `collisionAvoidance` | Same conversion as popover (`false` → all-`'none'` object). |
+| `collisionBoundary` | `Boundary` / `[]` | moved to Positioner `collisionBoundary` | Base default `'clipping-ancestors'`. |
+| `collisionPadding` | `number \| Padding` / `0` | moved to Positioner `collisionPadding` | Default `0` → `5`. |
+| `arrowPadding` | `number` / `0` | moved to Positioner `arrowPadding` | Default `0` → `5`. |
+| `sticky` | `"partial" \| "always"` / `"partial"` | dropped (repurposed name) | Same caveat as popover: Base `sticky: boolean` means "stay in viewport when anchor scrolls away"; alignment sticking is `collisionAvoidance.align`. |
+| `hideWhenDetached` | `boolean` / `false` | dropped (with workaround) | Style `[data-anchor-hidden]` on Positioner. |
+
+## Arrow → Arrow
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base renders `<div>`; bring your own SVG. |
+| `width` | `number` / `10` | dropped | CSS sizing. |
+| `height` | `number` / `5` | dropped | CSS sizing. |
+
+## Base UI only props worth knowing (tooltip)
+
+- Root: `trackCursorAxis` (`'none' \| 'x' \| 'y' \| 'both'`, default `'none'`), `disabled`, `disableHoverablePopup`, `actionsRef`, `onOpenChangeComplete`, `handle` / `triggerId` / `defaultTriggerId` + `Tooltip.createHandle()`, payload-render `children`.
+- Provider: `closeDelay` (shared close delay, no Radix counterpart).
+- Trigger: `closeOnClick`, `disabled`, `delay`, `closeDelay`, `payload`.
+- Positioner: `positionMethod`, `disableAnchorTracking`, `anchor`, `collisionAvoidance`.
+- New part: `Viewport`.
+
+## Data attributes (tooltip)
+
+| Radix | Base UI | Where |
+| --- | --- | --- |
+| `[data-state]` `"closed" \| "delayed-open" \| "instant-open"` (Content) | `data-open` / `data-closed` + `data-instant` (`'delay' \| 'dismiss' \| 'focus'`) | Popup, Arrow, Positioner (open/closed). The delayed/instant distinction becomes the `data-instant` value. |
+| `[data-state]` (Trigger) | `data-popup-open` | Trigger. Base also adds `data-trigger-disabled`. |
+| `[data-side]` | `data-side` | Positioner, Popup, Arrow; adds `'inline-start' \| 'inline-end'`. |
+| `[data-align]` | `data-align` | Positioner, Popup, Arrow. |
+| - | `data-starting-style` / `data-ending-style` | Popup. |
+| - | `data-anchor-hidden` | Positioner. |
+| - | `data-uncentered` | Arrow. |
+
+## CSS variables (tooltip)
+
+| Radix (on Content) | Base UI (on Positioner) |
+| --- | --- |
+| `--radix-tooltip-content-transform-origin` | `--transform-origin` |
+| `--radix-tooltip-content-available-width` | `--available-width` |
+| `--radix-tooltip-content-available-height` | `--available-height` |
+| `--radix-tooltip-trigger-width` | `--anchor-width` |
+| `--radix-tooltip-trigger-height` | `--anchor-height` |
+| - | `--popup-width` / `--popup-height` (Viewport's previous container). |
+
+---
+
+# hover-card → preview-card
+
+Part mapping: HoverCard.Root→PreviewCard.Root, Trigger→Trigger, Portal→Portal, Content→Portal>Positioner>Popup, Arrow→Arrow. Delays move from Root to Trigger. Both libraries render the trigger as an `<a>` element.
+
+## Root → Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` / - (Base default `false`) | `defaultOpen` | Same. |
+| `open` | `boolean` / - | `open` | Same. |
+| `onOpenChange` | `(open: boolean) => void` / - | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: PreviewCard.Root.ChangeEventDetails) => void`. Reasons: `'trigger-hover' \| 'trigger-focus' \| 'trigger-press' \| 'outside-press' \| 'escape-key' \| 'imperative-action' \| 'none'`. |
+| `openDelay` | `number` / `700` | moved to Trigger `delay` | Renamed + moved; default changes `700` → `600`. |
+| `closeDelay` | `number` / `300` | moved to Trigger `closeDelay` | Moved; default `300` (same). |
+
+## Trigger → Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base Trigger renders `<a>`; Base-only: `delay` (`600`), `closeDelay` (`300`), `payload`, `handle`. No `nativeButton` (it is a link, not a button). |
+
+## Portal → Portal
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` / - | `keepMounted` | `boolean`, default `false`. |
+| `container` | `HTMLElement` / `document.body` | `container` | Wider type; renders a `<div>`. |
+
+## Content → Positioner + Popup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` (Popup) | Same pattern. |
+| `forceMount` | `boolean` / - | dropped | Portal `keepMounted` / `actionsRef.unmount()` / `onOpenChangeComplete`. |
+| `side` | enum / `"bottom"` | moved to Positioner `side` | `Side` (adds `'inline-start' \| 'inline-end'`); default `'bottom'` (same). |
+| `sideOffset` | `number` / `0` | moved to Positioner `sideOffset` | `number \| OffsetFunction`; default `0`. |
+| `align` | enum / `"center"` | moved to Positioner `align` | Same values/default. |
+| `alignOffset` | `number` / `0` | moved to Positioner `alignOffset` | `number \| OffsetFunction`; default `0`. |
+| `avoidCollisions` | `boolean` / `true` | moved to Positioner `collisionAvoidance` | Same conversion as popover. |
+| `collisionBoundary` | `Boundary` / `[]` | moved to Positioner `collisionBoundary` | Base default `'clipping-ancestors'`. |
+| `collisionPadding` | `number \| Padding` / `0` | moved to Positioner `collisionPadding` | Default `0` → `5`. |
+| `arrowPadding` | `number` / `0` | moved to Positioner `arrowPadding` | Default `0` → `5`. |
+| `sticky` | `"partial" \| "always"` / `"partial"` | dropped (repurposed name) | Same caveat as popover/tooltip. |
+| `hideWhenDetached` | `boolean` / `false` | dropped (with workaround) | Style `[data-anchor-hidden]` on Positioner. |
+
+(Radix HoverCard.Content documents no dismiss callbacks; escape/outside dismissal maps to Root `onOpenChange` reasons `'escape-key'` / `'outside-press'` if needed.)
+
+## Arrow → Arrow
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` / `false` | `render` | Base renders `<div>`. |
+| `width` | `number` / `10` | dropped | CSS sizing. |
+| `height` | `number` / `5` | dropped | CSS sizing. |
+
+## Base UI only props worth knowing (preview-card)
+
+- Root: `actionsRef`, `onOpenChangeComplete`, `handle` / `triggerId` / `defaultTriggerId` + `PreviewCard.createHandle()`, payload-render `children`.
+- Trigger: `payload`, `handle`, per-trigger `delay`/`closeDelay`.
+- Positioner: `positionMethod`, `disableAnchorTracking`, `anchor`, `collisionAvoidance`.
+- New parts: `Backdrop`, `Viewport`.
+
+## Data attributes (preview-card)
+
+| Radix | Base UI | Where |
+| --- | --- | --- |
+| `[data-state="open"/"closed"]` | `data-open` / `data-closed` | Backdrop, Positioner, Popup, Arrow. |
+| `[data-state]` (Trigger) | `data-popup-open` | Trigger. |
+| `[data-side]` | `data-side` | Positioner, Popup, Arrow; adds `'inline-start' \| 'inline-end'`. |
+| `[data-align]` | `data-align` | Positioner, Popup, Arrow. |
+| - | `data-starting-style` / `data-ending-style` | Popup, Backdrop. |
+| - | `data-anchor-hidden` | Positioner. |
+| - | `data-uncentered` | Arrow. |
+
+## CSS variables (preview-card)
+
+| Radix (on Content) | Base UI (on Positioner) |
+| --- | --- |
+| `--radix-hover-card-content-transform-origin` | `--transform-origin` |
+| `--radix-hover-card-content-available-width` | `--available-width` |
+| `--radix-hover-card-content-available-height` | `--available-height` |
+| `--radix-hover-card-trigger-width` | `--anchor-width` |
+| `--radix-hover-card-trigger-height` | `--anchor-height` |
+| - | `--popup-width` / `--popup-height` (Viewport's previous container). |
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/universal-patterns.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/universal-patterns.md
new file mode 100644
index 00000000..424cf9e4
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/universal-patterns.md
@@ -0,0 +1,286 @@
+# Radix -> Base UI migration mapping
+
+Sources: (1) mechanical diff of the 61 component pairs in
+`apps/v4/registry/bases/{radix,base}/ui/` (ground truth, authored by us),
+(2) `radix-ui@1.4.3` package exports, (3) base-ui.com docs index for
+`@base-ui/react@1.6.0`. Built 2026-07-02 as the knowledge base for the
+migration agent's `primitives/` skills.
+
+## Coverage matrix
+
+All radix-ui exports, classified for migration:
+
+| Radix primitive | Base UI target | Class |
+|---|---|---|
+| Accordion | Accordion | direct (Content->Panel) |
+| AlertDialog | Alert Dialog | restructured (Overlay->Backdrop, Content->Popup, Cancel->Close, Action dropped) |
+| AspectRatio | none | missing: plain div + CSS `aspect-ratio` (`--ratio` var) |
+| Avatar | Avatar | direct |
+| Checkbox | Checkbox | direct (cleanest 1:1) |
+| Collapsible | Collapsible | direct (Content->Panel) |
+| ContextMenu | Context Menu | restructured (menu mapping) |
+| Dialog | Dialog | restructured (Overlay->Backdrop, Content->Popup) |
+| DropdownMenu | Menu | RENAMED + restructured (canonical menu mapping) |
+| Form | Form + Field + Fieldset | restructured (split into three) |
+| HoverCard | Preview Card | RENAMED + positioner model |
+| Label | none | missing: native `<label>` (Field.Label inside forms) |
+| Menubar | Menubar + Menu | restructured (menubar root only; menus delegate to Menu) |
+| NavigationMenu | Navigation Menu | heavily restructured (Viewport -> Positioner/Popup/Viewport, Indicator->Icon) |
+| Popover | Popover | positioner model (Anchor dropped; verify vs docs) |
+| Progress | Progress | restructured (new Track/Label/Value parts, no manual transform) |
+| RadioGroup | Radio Group + Radio | restructured (Item -> Radio.Root, two subpath imports) |
+| ScrollArea | Scroll Area | direct (Scrollbar/Thumb renames) |
+| Select | Select | restructured (Viewport->List, ScrollButtons->ScrollArrows, alignItemWithTrigger) |
+| Separator | Separator | direct (callable; `decorative` dropped) |
+| Slider | Slider | restructured (Range->Indicator, new Control, thumbAlignment) |
+| Switch | Switch | direct (1:1) |
+| Tabs | Tabs | direct (Trigger->Tab, Content->Panel) |
+| Toast | Toast | restructured (not in our registry pairs; spec from docs; shadcn users mostly use sonner) |
+| Toggle | Toggle | direct (callable) |
+| ToggleGroup | Toggle Group + Toggle | direct (items use Toggle primitive) |
+| Toolbar | Toolbar | direct-ish (not in our pairs; spec from docs) |
+| Tooltip | Tooltip | positioner model (delayDuration->delay on Provider) |
+| unstable_OneTimePasswordField | OTP Field | from docs (our registry uses input-otp instead) |
+| unstable_PasswordToggleField | none | missing: Input + custom toggle |
+
+Utilities:
+
+| Radix utility | Base UI equivalent |
+|---|---|
+| Slot / asChild | `render` prop; `useRender` + `mergeProps` for the manual Slot idiom |
+| Portal | none standalone; per-component `Portal` parts |
+| VisuallyHidden | none; `sr-only` class |
+| AccessibleIcon | none; aria-label + sr-only text |
+| Direction | Direction Provider |
+
+Base UI-only (new capabilities, NOT migration targets): Autocomplete, Combobox,
+Input, Number Field, Checkbox Group, Meter, Filter, CSP Provider.
+
+CORRECTION (dry-run finding): Base UI also ships a `Button` primitive
+(`@base-ui/react/button`) that supports `render`. A shadcn button.tsx using
+the Slot/asChild idiom migrates to `<ButtonPrimitive>` directly, NOT to a
+hand-rolled useRender wrapper. useRender + mergeProps remains correct for
+non-button polymorphic components (breadcrumb link, marker).
+
+Never touched by migration (third-party on both sides): cmdk (command), vaul*
+(drawer; see drawer section: our base drawer moved vaul -> @base-ui/react/drawer),
+sonner, input-otp, react-day-picker (calendar), recharts (chart).
+
+## Universal patterns (apply across all components)
+
+### Imports
+Radix appears in TWO import forms; both map to the same Base UI subpath:
+- Unified package (current shadcn):
+  `import { X as XPrimitive } from "radix-ui"` ->
+  `import { X as XPrimitive } from "@base-ui/react/<kebab-name>"`.
+- Individual packages (legacy/2024-era, e.g. fixture 03):
+  `import * as XPrimitive from "@radix-ui/react-<name>"` ->
+  `import { X as XPrimitive } from "@base-ui/react/<kebab-name>"`.
+  (The namespace `* as` import becomes a named import; remove the individual
+  `@radix-ui/react-*` package from package.json.)
+One subpath per component either way.
+- Types: `React.ComponentProps<typeof XPrimitive.Part>` -> `XPrimitive.Part.Props`.
+  Positioner props via `Pick<XPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">`.
+- Single-part primitives are callable: radix `XPrimitive.Root` -> `XPrimitive`
+  (separator, toggle, toggle-group root, radio-group root, menubar root).
+
+### asChild -> render
+- `<Primitive.Close asChild><Button/></Primitive.Close>` ->
+  `<Primitive.Close render={<Button/>}>...</Primitive.Close>`.
+- Manual Slot idiom (`const Comp = asChild ? Slot.Root : "a"`) ->
+  `useRender` + `mergeProps` from `@base-ui/react/use-render` /
+  `@base-ui/react/merge-props`; prop type `useRender.ComponentProps<"a">`.
+
+### Portal / positioning model (biggest structural change)
+- Radix: `Portal > Content`, positioning props on Content.
+- Base UI: `Portal > Positioner > Popup`. `side`, `sideOffset`, `align`,
+  `alignOffset` (and select's `alignItemWithTrigger`) move to Positioner;
+  Popup is the styled box. Positioner conventionally gets `isolate z-50`.
+- `Overlay` -> `Backdrop` (dialogs, sheets, drawers). Centered modals
+  (dialog/alert-dialog) use Popup WITHOUT a Positioner.
+
+### Data attributes / class hooks
+- `data-[state=open]` -> `data-open`; `data-[state=closed]` -> `data-closed`.
+- Enter/exit animations: `data-[state=open]:animate-in` /
+  `data-[state=closed]:animate-out` -> `data-starting-style:*` /
+  `data-ending-style:*` (transition-based, not keyframes).
+- New Base UI hook: `data-popup-open` (open-submenu/trigger marker).
+- Some triggers gain `aria-disabled:*` variants alongside `disabled:*`
+  (accordion, tabs).
+
+### CSS custom properties
+- `--radix-<comp>-content-transform-origin` -> `--transform-origin`
+- `--radix-<comp>-content-available-height` -> `--available-height`
+- `--radix-<comp>-trigger-width` -> `--anchor-width`
+- `--radix-accordion-content-height` -> `--accordion-panel-height`
+- nav-menu `--radix-navigation-menu-viewport-height/width` ->
+  `--positioner-height/width`, `--popup-height/width`, `--available-width`
+
+### Props
+- Tooltip Provider: `delayDuration` -> `delay`.
+- Select: `position="popper"|"item-aligned"` -> `alignItemWithTrigger` boolean.
+- Slider: gains `thumbAlignment` ("edge"); `Range` -> `Indicator` + new `Control`.
+- Navigation Menu: `viewport` boolean dropped; `align` forwarded to Positioner.
+- `value` / `defaultValue` / `onOpenChange` signatures pass through unchanged at
+  the wrapper level (verify per-primitive callback signatures against docs when
+  authoring specs; wrappers do not exercise them all).
+
+## Part-rename quick reference
+
+| radix part | Base UI part |
+|---|---|
+| `*.Root` (single-part comps) | callable `*Primitive` |
+| `Overlay` | `Backdrop` |
+| `Content` (overlay comps) | `Popup` (inside `Positioner`) |
+| `Content` (accordion/collapsible/tabs) | `Panel` |
+| tabs `Trigger` | `Tab` |
+| menu `Label` | `GroupLabel` |
+| menu `ItemIndicator` | `CheckboxItemIndicator` / `RadioItemIndicator` |
+| `Sub` / `SubTrigger` | `SubmenuRoot` / `SubmenuTrigger` |
+| slider `Range` | `Indicator` (+ new `Control`) |
+| select `Viewport` | `List` |
+| select `ScrollUp/DownButton` | `ScrollUp/DownArrow` |
+| scroll-area `ScrollAreaScrollbar` / `ScrollAreaThumb` | `Scrollbar` / `Thumb` |
+| nav-menu `Indicator` | `Icon` |
+| nav-menu `Viewport` | `Positioner > Popup > Viewport` |
+| hover-card `HoverCard*` | `PreviewCard*` |
+| radio-group `Item` / `Indicator` | `Radio.Root` / `Radio.Indicator` |
+| popover `Anchor` | dropped (verify against docs) |
+| alert-dialog `Cancel` / `Action` | `Close` / dropped (plain Button) |
+| separator `decorative` prop | dropped |
+| Label primitive | native `<label>` |
+
+## Per-component notes
+
+### accordion
+Root/Item/Header/Trigger same; Content -> Panel. Trigger `disabled:*` ->
+`aria-disabled:*`. Height var -> `--accordion-panel-height`; add
+`data-starting-style:h-0 data-ending-style:h-0`.
+
+### dialog / alert-dialog / sheet
+Overlay -> Backdrop, Content -> Popup, Close kept (`asChild` -> `render`).
+Alert-dialog: Cancel -> Close; Action has no primitive (plain Button).
+Sheet: slide animations rewritten from animate-in/out to
+`data-starting-style` / `data-ending-style` with explicit translate per
+`data-[side=...]`. Centered modals: no Positioner.
+
+### drawer (vaul -> Base UI) — OPT-IN ONLY, not part of a radix migration
+Vaul is NOT radix: during a radix -> base-ui migration, leave drawer.tsx
+untouched and report it (hard rule in SKILL.md). This mapping exists only for
+when the user EXPLICITLY asks to also move their drawer off vaul.
+Root gains `modal`, `snapPoints`, `swipeDirection` (default "down"),
+`showSwipeHandle`. Content (single) -> `Viewport > Popup > Content`.
+`data-[vaul-drawer-direction=...]` -> `data-[swipe-direction=...]` /
+`data-[swipe-axis=...]` + `--drawer-*` vars. New SwipeHandle part and a
+context provider in our wrapper. This is a vaul migration, not radix.
+
+### popover / tooltip / hover-card
+Portal > Positioner > Popup. Popover: Anchor dropped, Title is now a real
+primitive part. Tooltip: Provider `delayDuration` -> `delay`; Content gains
+side/align/alignOffset; default sideOffset 0 -> 4; Arrow gets explicit
+per-side positioning classes. HoverCard: primitive renamed PreviewCard
+(public wrapper names stay HoverCard*).
+
+### menus (dropdown-menu -> Menu; context-menu; menubar)
+Canonical mapping: Label -> GroupLabel, ItemIndicator ->
+CheckboxItemIndicator/RadioItemIndicator, Sub -> SubmenuRoot, SubTrigger ->
+SubmenuTrigger, Content -> Portal > Positioner > Popup, SubContent rebuilt
+from the Content component. Content hoists align/alignOffset/side/sideOffset.
+SubTrigger open marker: `data-popup-open`. Context-menu has its own subpath
+(`@base-ui/react/context-menu`), same anatomy. Menubar: only the root and
+checkbox/radio items are menubar/menu primitives; everything else delegates
+to the Menu wrappers (radix Menubar.Menu -> Menu.Root).
+
+### select
+Label -> GroupLabel, Viewport -> List, ScrollUp/DownButton ->
+ScrollUp/DownArrow. Icon/ItemIndicator go `asChild` -> `render`.
+`position` -> `alignItemWithTrigger` (default true) on Positioner. Vars ->
+`--available-height` / `--anchor-width` / `--transform-origin`.
+
+### form controls
+Checkbox: 1:1. Switch: 1:1. Radio group: group from
+`@base-ui/react/radio-group` (callable), items from `@base-ui/react/radio`
+(`Radio.Root` + `Radio.Indicator`). Slider: `Root > Control > Track >
+Indicator` + Thumbs, `thumbAlignment="edge"`; layout classes move Root ->
+Control. Toggle/toggle-group: callable primitives; group items reuse Toggle.
+
+### tabs / collapsible / progress / separator / scroll-area / label
+Tabs: Trigger -> Tab, Content -> Panel, `aria-disabled:*` added. Collapsible:
+Content -> Panel. Progress: new Track/Label/Value parts; primitive computes
+fill (drop the manual translateX). Separator: callable, `decorative` dropped.
+Scroll-area: Scrollbar/Thumb renames only. Label: no primitive; native
+`<label>`.
+
+### navigation-menu
+Viewport moves out of Root into `Portal > Positioner > Popup > Viewport`
+(our NavigationMenuPositioner). Indicator -> Icon. `viewport` boolean prop
+removed; `align` forwarded to Positioner. New `data-instant`,
+`data-activation-direction` hooks; vars -> `--positioner-height/width`,
+`--popup-height/width`.
+
+### breadcrumb / marker (Slot users)
+`Slot.Root` + `asChild` -> `useRender` + `mergeProps`
+(`useRender.ComponentProps<"a">`, `render` prop, `state.slot`).
+
+## Doc-validation TODOs (before specs are final)
+
+1. Popover Anchor: confirm Base UI has no anchor equivalent (Positioner may
+   accept an `anchor` prop; our wrapper simply dropped the part).
+2. Callback signatures: radix `onOpenChange(open)` vs Base UI
+   `onOpenChange(open, event, reason)` style differences; wrappers pass
+   through so the pair diff cannot see them. Check per primitive.
+3. Toast, Toolbar, Form/Field/Fieldset, OTP Field: not covered by our pairs;
+   author these specs from docs alone.
+4. Controlled-prop names on menus/select (`open`, `value`, `highlighted`)
+   and any `defaultChecked`/`checked` nuances.
+5. Focus/dismissal behavior knobs (`onInteractOutside`, `onEscapeKeyDown` ->
+   Base UI equivalents) which our wrappers do not surface.
+
+## Slot -> useRender: WORKED EXAMPLE (avoid the mergeProps pitfall)
+
+Radix:
+```tsx
+import { Slot } from "radix-ui"
+function BreadcrumbLink({ asChild, className, ...props }: React.ComponentProps<"a"> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot.Root : "a"
+  return <Comp data-slot="breadcrumb-link" className={cn("...", className)} {...props} />
+}
+```
+
+Base UI:
+```tsx
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+
+function BreadcrumbLink({ className, render, ...props }: useRender.ComponentProps<"a">) {
+  return useRender({
+    defaultTagName: "a",
+    render,
+    props: mergeProps<"a">(
+      // PITFALL: data-* attributes fail excess-property checking when passed
+      // as an object literal into mergeProps (they are only special-cased in
+      // JSX). Cast the literal:
+      { "data-slot": "breadcrumb-link", className: cn("...", className) } as React.ComponentProps<"a">,
+      props
+    ),
+  })
+}
+```
+
+Two rules:
+1. This pattern is ONLY for non-button polymorphic components (breadcrumb
+   link, marker, badge, item...). `button.tsx` migrates to the real
+   `@base-ui/react/button` primitive, which accepts `render` natively.
+2. Always cast object literals containing `data-*` keys passed to
+   `mergeProps` (`as React.ComponentProps<"tag">`), or tsc fails on every one.
+
+## Positioner props: Pick means FORWARD
+
+When a wrapper exposes positioning props via
+`Pick<XPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">`,
+you MUST destructure each of those props in the wrapper and pass them to
+`<XPrimitive.Positioner>` explicitly. If you forget, they fall through
+`...props` onto the Popup (wrong DOM node) and positioning silently breaks.
+No JSX-level type error catches this; only the wrapper's own destructuring
+discipline and a browser check do. Checklist per overlay wrapper:
+declare -> destructure -> forward. All three, every time.
diff --git a/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/wrapper-shapes.md b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/wrapper-shapes.md
new file mode 100644
index 00000000..58227ad1
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/migrate-radix-to-base/wrapper-shapes.md
@@ -0,0 +1,110 @@
+# Target wrapper shapes (golden-derived specifics)
+
+Facts learned by diffing hand migrations against the shadcn base registry
+wrappers. These close gaps the mapping tables cannot express: exact classes,
+defaults, and composition shapes. When migrating shadcn-style wrappers,
+prefer these shapes.
+
+## Conventions
+
+- Positioner parts get NO `data-slot` attribute; keep data-slot on the parts
+  the radix wrapper already had.
+- Menu-family Positioner: `className="isolate z-50 outline-none"`; the Popup
+  KEEPS `z-50` and `outline-none` too. Tooltip: Popup keeps `z-50`,
+  Positioner gets `isolate z-50`. Select: `isolate z-50` lives on the Popup,
+  Positioner gets no class.
+- The base registry adds `cn-<comp>-content-logical` (and for tooltip also
+  `cn-tooltip-arrow-logical`) companion classes next to the existing
+  `cn-<comp>-content` hooks on popover, tooltip, hover-card, dropdown,
+  context-menu, select, menubar popups. Add them when the source uses cn-*
+  hooks; skip for plain-Tailwind projects.
+
+## Button
+
+Base UI HAS a Button primitive: `import { Button as ButtonPrimitive } from
+"@base-ui/react/button"`. A shadcn button.tsx with the Slot/asChild idiom
+migrates to `<ButtonPrimitive>` directly (which supports `render`), NOT to a
+hand-rolled useRender wrapper. Reserve useRender + mergeProps for
+non-button polymorphic components (breadcrumb link, marker).
+
+## Tooltip Arrow (literal classes)
+
+```tsx
+<TooltipPrimitive.Arrow
+  className={cn(
+    "cn-tooltip-arrow cn-tooltip-arrow-logical",
+    "data-[side=bottom]:top-1 data-[side=left]:right-[-13px] data-[side=left]:top-1/2! data-[side=left]:-translate-y-1/2 data-[side=right]:left-[-13px] data-[side=right]:top-1/2! data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5",
+    className
+  )}
+/>
+```
+
+Verify against the current base registry tooltip before relying on the exact
+pixel values; the shape (per-side offsets + translate, no rotation) is the
+stable part. Golden default: `alignOffset = 0`, `sideOffset = 4`.
+
+## DropdownMenu / ContextMenu SubContent
+
+Compose the PUBLIC Content wrapper, do not rebuild from primitives:
+
+```tsx
+function DropdownMenuSubContent(props) {
+  return (
+    <DropdownMenuContent
+      align="start"
+      alignOffset={-3}
+      side="right"
+      sideOffset={0}
+      className={cn("w-auto", props.className)}
+      {...props}
+    />
+  )
+}
+```
+
+The `-3` / `0` defaults are load-bearing (visual alignment with the parent
+menu). NOTE: the live registry shapes SubContent differently per menu:
+context-menu is a true minimal compose (as above), while dropdown-menu's
+SubContent duplicates the full content class list (including translucent menu
+styling) rather than composing. When a golden pair exists, copy the golden
+shape; this example is the fallback.
+
+DANGER — do not confuse SubContent defaults with main-Content defaults. The
+values above are ONLY for the *submenu* wrappers (DropdownMenuSubContent /
+ContextMenuSubContent). The MAIN ContextMenuContent (the pointer-anchored
+right-click menu) keeps its own positioning — do NOT apply
+`side="right"`/`alignOffset` to it, or every right-click menu mispositions.
+- ContextMenu SUBContent defaults: `align="start" alignOffset={4} side="right" sideOffset={0}`.
+- DropdownMenu SUBContent defaults: `align="start" alignOffset={-3} side="right" sideOffset={0}`.
+- Main Content (either): keep the wrapper's existing align/sideOffset; do not add a side.
+
+## SubTrigger open styling
+
+Base wrappers ADD `data-popup-open:bg-accent
+data-popup-open:text-accent-foreground` to SubTrigger (no radix equivalent
+class existed; the open styling was previously data-[state=open]).
+
+## Select
+
+- Bare re-export: `const Select = SelectPrimitive.Root` (no wrapper function,
+  no data-slot on Root). `SelectPrimitive.Root.Props` is GENERIC
+  (<Value, Multiple>), which breaks the usual ComponentProps pattern; the
+  bare re-export sidesteps it.
+- Drop the radix `position` prop entirely; expose `alignItemWithTrigger`
+  (default true) picked from Positioner.Props, `sideOffset = 4`.
+- Item anatomy: `ItemText` FIRST with `cn-select-item-text shrink-0
+  whitespace-nowrap`, then `ItemIndicator render={<span
+  className="cn-select-item-indicator" />}`.
+- Scroll arrows get `top-0 w-full` / `bottom-0 w-full`; List has no classes.
+
+## Accordion animation placement
+
+`h-(--accordion-panel-height)`, `data-starting-style:h-0`, and
+`data-ending-style:h-0` all go on the INNER div of the Panel (the element
+that previously carried the radix height animation), not on the Panel itself.
+
+## Tabs
+
+The base registry accepts Base UI's manual-activation default (no
+`activateOnFocus`), and does not forward `orientation` beyond what the radix
+wrapper did. Match it: flag the behavior delta, do not patch it.
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/SKILL.md b/plugins/shadcn-ui/agent/skills/shadcn/SKILL.md
new file mode 100644
index 00000000..09ef16ce
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/SKILL.md
@@ -0,0 +1,273 @@
+---
+description: "Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for \"shadcn init\", \"create an app with --preset\", or \"switch to --preset\"."
+---
+# shadcn/ui
+
+A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
+
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
+
+## Current Project Context
+
+```json
+!`npx shadcn@latest info --json`
+```
+
+The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
+
+## Principles
+
+1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
+3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **`className` for layout, not styling.** Never override component colors or typography.
+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
+- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
+- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
+- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
+- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
+- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
+
+### Component Structure → [composition.md](./rules/composition.md)
+
+- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
+- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)
+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
+- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
+- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
+- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
+- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
+
+### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
+
+- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
+- **Callouts use `Alert`.** Don't build custom styled divs.
+- **Empty states use `Empty`.** Don't build custom empty state markup.
+- **Toast follows the project base.** Use `toast` from the `toast` component for
+  Base UI projects. Use `toast()` from `sonner` for Radix and React Aria
+  projects.
+- **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
+- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
+- **Use `Badge`** instead of custom styled spans.
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
+- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
+- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup.
+
+### Chat & Messaging → [chat.md](./rules/chat.md)
+
+- **Chat UI composes the chat primitives.** Conversations use `MessageScroller`, rows use `Message`, surfaces use `Bubble`. Never hand-rolled bubble `div`s or a raw scroll container.
+- **`MessageScroller` owns scroll behavior.** Streaming follow, anchoring, and jump-to-latest (`MessageScrollerButton`) are built in. Don't write a `useStickToBottom`/`ResizeObserver` hook.
+- **Attachments use `Attachment`; system notes and dividers use `Marker`.** Not `Item` cards or `Separator` + a label.
+
+### CLI
+
+- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@latest preset decode <code>`, `preset url <code>`, or `preset open <code>`. For project-aware preset detection, use `npx shadcn@latest preset resolve`.
+- **Apply preset codes directly with the CLI.** Use `npx shadcn@latest apply <code>` for existing projects, or `npx shadcn@latest init --preset <code>` when initializing.
+
+## Key Patterns
+
+These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.
+
+```tsx
+// Form layout: FieldGroup + Field, not div + Label.
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" />
+  </Field>
+</FieldGroup>
+
+// Validation: data-invalid on Field, aria-invalid on the control.
+<Field data-invalid>
+  <FieldLabel>Email</FieldLabel>
+  <Input aria-invalid />
+  <FieldDescription>Invalid email.</FieldDescription>
+</Field>
+
+// Icons in buttons: data-icon, no sizing classes.
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+// Spacing: gap-*, not space-y-*.
+<div className="flex flex-col gap-4">  // correct
+<div className="space-y-4">           // wrong
+
+// Equal dimensions: size-*, not w-* h-*.
+<Avatar className="size-10">   // correct
+<Avatar className="w-10 h-10"> // wrong
+
+// Status colors: Badge variants or semantic tokens, not raw colors.
+<Badge variant="secondary">+20.1%</Badge>    // correct
+<span className="text-emerald-600">+20.1%</span> // wrong
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button/action              | `Button` with appropriate variant                                                                   |
+| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
+| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem`                                                                   |
+| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
+| Feedback                   | `toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`                 |
+| Command palette            | `Command` inside `Dialog`                                                                           |
+| Charts                     | `Chart` (wraps Recharts)                                                                            |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
+| Empty states               | `Empty`                                                                                             |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
+| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
+| Chat / conversation UI     | `MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`                                      |
+
+## Key Fields
+
+The injected project context contains these key fields:
+
+- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
+- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive.
+- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.
+- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
+- **`style`** → component visual treatment (e.g. `nova`, `vega`).
+- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props.
+- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`.
+- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
+- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
+- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
+- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@latest preset resolve --json` when you only need preset information.
+
+See [cli.md — `info` command](./cli.md) for the full field reference.
+
+## Component Docs, Examples, and Usage
+
+Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
+
+```bash
+npx shadcn@latest docs button dialog select
+```
+
+**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
+
+## Workflow
+
+1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
+2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
+3. **Find components** — `npx shadcn@latest search`.
+4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.
+5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
+6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
+7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
+8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
+9. **Switching presets** — Ask the user first: **overwrite**, **partial**, **merge**, or **skip**?
+   - **Inspect current preset**: `npx shadcn@latest preset resolve`. Use `--json` when you need structured values.
+   - **Inspect incoming preset**: `npx shadcn@latest preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open the preset builder.
+   - **Overwrite**: `npx shadcn@latest apply <code>`. Overwrites detected components, fonts, and CSS variables.
+   - **Partial**: `npx shadcn@latest apply <code> --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms.
+   - **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
+   - **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
+   - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
+
+## Updating Components
+
+When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
+
+1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.
+2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.
+3. Decide per file based on the diff:
+   - No local changes → safe to overwrite.
+   - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
+   - User says "just update everything" → use `--overwrite`, but confirm first.
+4. **Never use `--overwrite` without the user's explicit approval.**
+
+## Quick Reference
+
+```bash
+# Create a new project.
+npx shadcn@latest init --name my-app --preset base-nova
+npx shadcn@latest init --name my-app --preset a2r6bw --template vite
+
+# Create a monorepo project.
+npx shadcn@latest init --name my-app --preset base-nova --monorepo
+npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
+
+# Initialize existing project.
+npx shadcn@latest init --preset base-nova
+npx shadcn@latest init --defaults  # shortcut: --template=next --preset=nova (base style implied)
+
+# Apply a preset to an existing project.
+npx shadcn@latest apply a2r6bw
+npx shadcn@latest apply a2r6bw --only theme
+npx shadcn@latest apply a2r6bw --only font
+npx shadcn@latest apply a2r6bw --only theme,font
+
+# Inspect preset codes and project preset state.
+npx shadcn@latest preset decode a2r6bw
+npx shadcn@latest preset url a2r6bw
+npx shadcn@latest preset open a2r6bw
+npx shadcn@latest preset resolve
+npx shadcn@latest preset resolve --json
+
+# Add components.
+npx shadcn@latest add button card dialog
+npx shadcn@latest add @magicui/shimmer-button
+npx shadcn@latest add owner/repo/item
+npx shadcn@latest add --all
+
+# Preview changes before adding/updating.
+npx shadcn@latest add button --dry-run
+npx shadcn@latest add button --diff button.tsx
+npx shadcn@latest add @acme/form --view button.tsx
+npx shadcn@latest add owner/repo/item --dry-run
+
+# Search registries.
+npx shadcn@latest search @shadcn -q "sidebar"
+npx shadcn@latest search @tailark -q "stats"
+npx shadcn@latest search owner/repo -q "login"
+npx shadcn@latest search                          # all configured registries
+npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type
+
+# Get component docs and example URLs.
+npx shadcn@latest docs button dialog select
+
+# View registry item details (for items not yet installed).
+npx shadcn@latest view @shadcn/button
+npx shadcn@latest view owner/repo/item
+```
+
+**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`
+**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
+**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw` or `b0`), from [ui.shadcn.com](https://ui.shadcn.com).
+
+## Detailed References
+
+- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
+- [rules/chat.md](./rules/chat.md) — MessageScroller, Message, Bubble, Attachment, Marker; streaming, anchoring, jump-to-latest
+- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects
+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
+- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion
+- [cli.md](./cli.md) — Commands, flags, presets, templates
+- [registry.md](./registry.md) — Authoring source registries, `include`, item definitions, dependencies, GitHub registry rules
+- [customization.md](./customization.md) — Theming, CSS variables, extending components
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/agents/openai.yml b/plugins/shadcn-ui/agent/skills/shadcn/agents/openai.yml
new file mode 100644
index 00000000..ab636da8
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/agents/openai.yml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "shadcn/ui"
+  short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."
+  icon_small: "./assets/shadcn-small.png"
+  icon_large: "./assets/shadcn.png"
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/assets/shadcn-small.png b/plugins/shadcn-ui/agent/skills/shadcn/assets/shadcn-small.png
new file mode 100644
index 00000000..547154b9
Binary files /dev/null and b/plugins/shadcn-ui/agent/skills/shadcn/assets/shadcn-small.png differ
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/assets/shadcn.png b/plugins/shadcn-ui/agent/skills/shadcn/assets/shadcn.png
new file mode 100644
index 00000000..b7b6814a
Binary files /dev/null and b/plugins/shadcn-ui/agent/skills/shadcn/assets/shadcn.png differ
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/cli.md b/plugins/shadcn-ui/agent/skills/shadcn/cli.md
new file mode 100644
index 00000000..8a1d1958
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/cli.md
@@ -0,0 +1,290 @@
+# shadcn CLI Reference
+
+Configuration is read from `components.json`.
+
+> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
+
+> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.
+
+## Contents
+
+- Commands: init, apply, add (dry-run, smart merge), search, view, docs, info, build
+- Templates: next, vite, start, react-router, astro
+- Presets: named, code, URL formats and fields
+- Switching presets
+
+---
+
+## Commands
+
+### `init` — Initialize or create a project
+
+```bash
+npx shadcn@latest init [components...] [options]
+```
+
+Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.
+
+| Flag                    | Short | Description                                               | Default |
+| ----------------------- | ----- | --------------------------------------------------------- | ------- |
+| `--template <template>` | `-t`  | Template (next, start, vite, next-monorepo, react-router) | —       |
+| `--preset [name]`       | `-p`  | Preset configuration (named, code, or URL)                | —       |
+| `--yes`                 | `-y`  | Skip confirmation prompt                                  | `true`  |
+| `--defaults`            | `-d`  | Use defaults (`--template=next --preset=base-nova`)       | `false` |
+| `--force`               | `-f`  | Force overwrite existing configuration                    | `false` |
+| `--cwd <cwd>`           | `-c`  | Working directory                                         | current |
+| `--name <name>`         | `-n`  | Name for new project                                      | —       |
+| `--silent`              | `-s`  | Mute output                                               | `false` |
+| `--rtl`                 |       | Enable RTL support                                        | —       |
+| `--reinstall`           |       | Re-install existing UI components                         | `false` |
+| `--monorepo`            |       | Scaffold a monorepo project                               | —       |
+| `--no-monorepo`         |       | Skip the monorepo prompt                                  | —       |
+
+`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.
+
+### `apply` — Apply a preset to an existing project
+
+```bash
+npx shadcn@latest apply [preset] [options]
+```
+
+Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.
+
+| Flag                | Short | Description                                | Default |
+| ------------------- | ----- | ------------------------------------------ | ------- |
+| `--preset <preset>` | —     | Preset configuration (named, code, or URL) | —       |
+| `--yes`             | `-y`  | Skip confirmation prompt                   | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                          | current |
+| `--silent`          | `-s`  | Mute output                                | `false` |
+
+`[preset]` is a shorthand for `--preset <preset>`. If both are provided, they must match.
+If no preset is provided, the CLI offers to open the custom preset builder on `ui.shadcn.com/create`.
+
+### `add` — Add components
+
+> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.
+
+```bash
+npx shadcn@latest add [components...] [options]
+```
+
+Accepts component names, registry-prefixed names (`@magicui/shimmer-button`),
+GitHub item addresses (`owner/repo/item`), URLs, or local paths.
+
+| Flag            | Short | Description                                                                                                          | Default |
+| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |
+| `--yes`         | `-y`  | Skip confirmation prompt                                                                                             | `false` |
+| `--overwrite`   | `-o`  | Overwrite existing files                                                                                             | `false` |
+| `--cwd <cwd>`   | `-c`  | Working directory                                                                                                    | current |
+| `--all`         | `-a`  | Add all available components                                                                                         | `false` |
+| `--path <path>` | `-p`  | Target path for the component                                                                                        | —       |
+| `--silent`      | `-s`  | Mute output                                                                                                          | `false` |
+| `--dry-run`     |       | Preview all changes without writing files                                                                            | `false` |
+| `--diff [path]` |       | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`)         | —       |
+| `--view [path]` |       | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | —       |
+
+#### Dry-Run Mode
+
+Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.
+
+```bash
+# Preview all changes.
+npx shadcn@latest add button --dry-run
+
+# Show diffs for all files (top 5).
+npx shadcn@latest add button --diff
+
+# Show the diff for a specific file.
+npx shadcn@latest add button --diff button.tsx
+
+# Show contents for all files (top 5).
+npx shadcn@latest add button --view
+
+# Show the full content of a specific file.
+npx shadcn@latest add button --view button.tsx
+
+# Works with URLs too.
+npx shadcn@latest add https://api.npoint.io/abc123 --dry-run
+
+# Works with public GitHub registries too.
+npx shadcn@latest add owner/repo/item --dry-run
+
+# CSS diffs.
+npx shadcn@latest add button --diff globals.css
+```
+
+**When to use dry-run:**
+
+- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.
+- Before overwriting existing components — use `--diff` to preview the changes first.
+- When the user wants to inspect component source code without installing — use `--view`.
+- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.
+- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.
+
+> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.
+
+#### Smart Merge from Upstream
+
+See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
+
+### `search` — Search registries
+
+```bash
+npx shadcn@latest search [registries...] [options]
+```
+
+Fuzzy search across registries. Also aliased as `npx shadcn@latest list`.
+Supports namespaces (`@acme`), public GitHub registry sources (`owner/repo`),
+and registry catalog URLs. Without `-q`, lists all items. When no registries are
+passed, searches every registry configured in `components.json`.
+
+| Flag                | Short | Description                                       | Default |
+| ------------------- | ----- | ------------------------------------------------- | ------- |
+| `--query <query>`   | `-q`  | Search query                                      | —       |
+| `--type <type>`     | `-t`  | Filter by item type (e.g. `ui`, `block`, `hook`); comma-separated | —       |
+| `--limit <number>`  | `-l`  | Max items to display                              | `100`   |
+| `--offset <number>` | `-o`  | Items to skip                                     | `0`     |
+| `--json`            |       | Output as JSON                                    | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                                 | current |
+
+### `view` — View item details
+
+```bash
+npx shadcn@latest view <items...> [options]
+```
+
+Displays item info including file contents. Examples:
+`npx shadcn@latest view @shadcn/button`,
+`npx shadcn@latest view owner/repo/item`.
+
+### `docs` — Get component documentation URLs
+
+```bash
+npx shadcn@latest docs <components...> [options]
+```
+
+Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.
+
+Example output for `npx shadcn@latest docs input button`:
+
+```
+base  radix
+
+input
+  docs      https://ui.shadcn.com/docs/components/radix/input
+  examples  https://raw.githubusercontent.com/.../examples/input-example.tsx
+
+button
+  docs      https://ui.shadcn.com/docs/components/radix/button
+  examples  https://raw.githubusercontent.com/.../examples/button-example.tsx
+```
+
+Some components include an `api` link to the underlying library (e.g. `cmdk` for the command component).
+
+### `diff` — Check for updates
+
+Do not use this command. Use `npx shadcn@latest add --diff` instead.
+
+### `info` — Project information
+
+```bash
+npx shadcn@latest info [options]
+```
+
+Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.
+
+| Flag          | Short | Description       | Default |
+| ------------- | ----- | ----------------- | ------- |
+| `--cwd <cwd>` | `-c`  | Working directory | current |
+
+**Project Info fields:**
+
+| Field                | Type      | Meaning                                                            |
+| -------------------- | --------- | ------------------------------------------------------------------ |
+| `framework`          | `string`  | Detected framework (`next`, `vite`, `react-router`, `start`, etc.) |
+| `frameworkVersion`   | `string`  | Framework version (e.g. `15.2.4`)                                  |
+| `isSrcDir`           | `boolean` | Whether the project uses a `src/` directory                        |
+| `isRSC`              | `boolean` | Whether React Server Components are enabled                        |
+| `isTsx`              | `boolean` | Whether the project uses TypeScript                                |
+| `tailwindVersion`    | `string`  | `"v3"` or `"v4"`                                                   |
+| `tailwindConfigFile` | `string`  | Path to the Tailwind config file                                   |
+| `tailwindCssFile`    | `string`  | Path to the global CSS file                                        |
+| `aliasPrefix`        | `string`  | Import alias prefix (e.g. `@`, `~`, `@/`)                          |
+| `packageManager`     | `string`  | Detected package manager (`npm`, `pnpm`, `yarn`, `bun`)            |
+
+**Components.json fields:**
+
+| Field                | Type      | Meaning                                                                                    |
+| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| `base`               | `string`  | Primitive library (`radix` or `base`) — determines component APIs and available props      |
+| `style`              | `string`  | Visual style (e.g. `nova`, `vega`)                                                         |
+| `rsc`                | `boolean` | RSC flag from config                                                                       |
+| `tsx`                | `boolean` | TypeScript flag                                                                            |
+| `tailwind.config`    | `string`  | Tailwind config path                                                                       |
+| `tailwind.css`       | `string`  | Global CSS path — this is where custom CSS variables go                                    |
+| `iconLibrary`        | `string`  | Icon library — determines icon import package (e.g. `lucide-react`, `@tabler/icons-react`) |
+| `aliases.components` | `string`  | Component import alias (e.g. `@/components`)                                               |
+| `aliases.utils`      | `string`  | Utils import alias (e.g. `@/lib/utils`)                                                    |
+| `aliases.ui`         | `string`  | UI component alias (e.g. `@/components/ui`)                                                |
+| `aliases.lib`        | `string`  | Lib alias (e.g. `@/lib`)                                                                   |
+| `aliases.hooks`      | `string`  | Hooks alias (e.g. `@/hooks`)                                                               |
+| `resolvedPaths`      | `object`  | Absolute file-system paths for each alias                                                  |
+| `registries`         | `object`  | Configured custom registries                                                               |
+
+**Links fields:**
+
+The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn@latest docs <component>` instead.
+
+### `build` — Build a custom registry
+
+```bash
+npx shadcn@latest build [registry] [options]
+```
+
+Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.
+
+For authoring rules, `include`, item definitions, `registryDependencies`, and
+GitHub registry behavior, see [registry.md](./registry.md).
+
+| Flag              | Short | Description       | Default      |
+| ----------------- | ----- | ----------------- | ------------ |
+| `--output <path>` | `-o`  | Output directory  | `./public/r` |
+| `--cwd <cwd>`     | `-c`  | Working directory | current      |
+
+---
+
+## Templates
+
+| Value          | Framework      | Monorepo support |
+| -------------- | -------------- | ---------------- |
+| `next`         | Next.js        | Yes              |
+| `vite`         | Vite           | Yes              |
+| `start`        | TanStack Start | Yes              |
+| `react-router` | React Router   | Yes              |
+| `astro`        | Astro          | Yes              |
+| `laravel`      | Laravel        | No               |
+
+All templates support monorepo scaffolding via the `--monorepo` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
+
+---
+
+## Presets
+
+Three ways to specify a preset via `--preset`:
+
+1. **Named:** `--preset nova` or `--preset lyra`
+2. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw` or `b0`)
+3. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`
+
+> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution.
+> Use `npx shadcn@latest apply --preset <code>` when overwriting an existing project's preset.
+
+## Switching Presets
+
+Ask the user first: **overwrite**, **merge**, or **skip** existing components?
+
+- **Overwrite / Re-install** → `npx shadcn@latest apply --preset <code>`. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
+- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.
+- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.
+
+Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/customization.md b/plugins/shadcn-ui/agent/skills/shadcn/customization.md
new file mode 100644
index 00000000..16954f56
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/customization.md
@@ -0,0 +1,209 @@
+# Customization & Theming
+
+Components reference semantic CSS variable tokens. Change the variables to change every component.
+
+## Contents
+
+- How it works (CSS variables → Tailwind utilities → components)
+- Color variables and OKLCH format
+- Dark mode setup
+- Changing the theme (presets, CSS variables)
+- Adding custom colors (Tailwind v3 and v4)
+- Border radius
+- Customizing components (variants, className, wrappers)
+- Checking for updates
+
+---
+
+## How It Works
+
+1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
+2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
+3. Components use these utilities — changing a variable changes all components that reference it.
+
+---
+
+## Color Variables
+
+Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.
+
+| Variable                                     | Purpose                          |
+| -------------------------------------------- | -------------------------------- |
+| `--background` / `--foreground`              | Page background and default text |
+| `--card` / `--card-foreground`               | Card surfaces                    |
+| `--primary` / `--primary-foreground`         | Primary buttons and actions      |
+| `--secondary` / `--secondary-foreground`     | Secondary actions                |
+| `--muted` / `--muted-foreground`             | Muted/disabled states            |
+| `--accent` / `--accent-foreground`           | Hover and accent states          |
+| `--destructive` / `--destructive-foreground` | Error and destructive actions    |
+| `--border`                                   | Default border color             |
+| `--input`                                    | Form input borders               |
+| `--ring`                                     | Focus ring color                 |
+| `--chart-1` through `--chart-5`              | Chart/data visualization         |
+| `--sidebar-*`                                | Sidebar-specific colors          |
+| `--surface` / `--surface-foreground`         | Secondary surface                |
+
+Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
+
+---
+
+## Dark Mode
+
+Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
+
+```tsx
+import { ThemeProvider } from "next-themes"
+
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+  {children}
+</ThemeProvider>
+```
+
+---
+
+## Changing the Theme
+
+```bash
+# Apply a preset code from ui.shadcn.com.
+npx shadcn@latest apply --preset a2r6bw
+
+# Positional shorthand also works.
+npx shadcn@latest apply a2r6bw
+
+# Switch to a named preset and overwrite existing components.
+npx shadcn@latest apply --preset nova
+
+# Preserve existing components instead.
+npx shadcn@latest init --preset nova --force --no-reinstall
+
+# Use a custom theme URL.
+npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..."
+```
+
+Or edit CSS variables directly in `globals.css`.
+
+---
+
+## Adding Custom Colors
+
+Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `globals.css`). Never create a new CSS file for this.
+
+```css
+/* 1. Define in the global CSS file. */
+:root {
+  --warning: oklch(0.84 0.16 84);
+  --warning-foreground: oklch(0.28 0.07 46);
+}
+.dark {
+  --warning: oklch(0.41 0.11 46);
+  --warning-foreground: oklch(0.99 0.02 95);
+}
+```
+
+```css
+/* 2a. Register with Tailwind v4 (@theme inline). */
+@theme inline {
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+}
+```
+
+When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:
+
+```js
+// 2b. Register with Tailwind v3 (tailwind.config.js).
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        warning: "oklch(var(--warning) / <alpha-value>)",
+        "warning-foreground":
+          "oklch(var(--warning-foreground) / <alpha-value>)",
+      },
+    },
+  },
+}
+```
+
+```tsx
+// 3. Use in components.
+<div className="bg-warning text-warning-foreground">Warning</div>
+```
+
+---
+
+## Border Radius
+
+`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
+
+---
+
+## Customizing Components
+
+See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
+
+Prefer these approaches in order:
+
+### 1. Built-in variants
+
+```tsx
+<Button variant="outline" size="sm">
+  Click
+</Button>
+```
+
+### 2. Tailwind classes via `className`
+
+```tsx
+<Card className="mx-auto max-w-md">...</Card>
+```
+
+### 3. Add a new variant
+
+Edit the component source to add a variant via `cva`:
+
+```tsx
+// components/ui/button.tsx
+warning: "bg-warning text-warning-foreground hover:bg-warning/90",
+```
+
+### 4. Wrapper components
+
+Compose shadcn/ui primitives into higher-level components:
+
+```tsx
+export function ConfirmDialog({ title, description, onConfirm, children }) {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription>{description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+---
+
+## Checking for Updates
+
+```bash
+npx shadcn@latest add button --diff
+```
+
+To preview exactly what would change before updating, use `--dry-run` and `--diff`:
+
+```bash
+npx shadcn@latest add button --dry-run        # see all affected files
+npx shadcn@latest add button --diff button.tsx # see the diff for a specific file
+```
+
+See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow.
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/evals/evals.json b/plugins/shadcn-ui/agent/skills/shadcn/evals/evals.json
new file mode 100644
index 00000000..c1b7bdd3
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/evals/evals.json
@@ -0,0 +1,77 @@
+{
+  "skill_name": "shadcn",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
+      "expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
+      "files": [],
+      "expectations": [
+        "Uses FieldGroup and Field components for form layout instead of raw div with space-y",
+        "Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
+        "Uses data-invalid on Field and aria-invalid on the input control for validation states",
+        "Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
+        "Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
+        "No manual dark: color overrides"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn/ui with radix-nova preset and tabler icons.",
+      "expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, data-icon on icon buttons, no icon sizing classes, tabler icon imports.",
+      "files": [],
+      "expectations": [
+        "Includes DialogTitle for accessibility (visible or with sr-only class)",
+        "Avatar component includes AvatarFallback",
+        "Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",
+        "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",
+        "Uses tabler icons (@tabler/icons-react) instead of lucide-react",
+        "Uses asChild for custom triggers (radix preset)"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn/ui with base-nova preset and lucide icons.",
+      "expected_output": "A React component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",
+      "files": [],
+      "expectations": [
+        "Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",
+        "Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",
+        "Uses Badge component for percentage change instead of custom styled spans",
+        "Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",
+        "Uses gap-* instead of space-y-* or space-x-* for spacing",
+        "Uses size-* when width and height are equal instead of separate w-* h-*"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Build a chat conversation view: a scrollable thread of messages from two different people, each with an avatar, sender name, timestamp, and message bubble. A couple of messages include an image attachment and a PDF file attachment, and there's a 'Today' divider separating the days.",
+      "expected_output": "A React component composing MessageScroller, Message, Bubble, Attachment, and Marker from the registry instead of hand-rolled bubble/divider/attachment markup.",
+      "files": [],
+      "expectations": [
+        "Uses MessageScroller (MessageScrollerProvider, MessageScrollerViewport, MessageScrollerContent, MessageScrollerItem) for the scrollable thread instead of a raw overflow-y-auto div or ScrollArea",
+        "Wraps each row in MessageScrollerItem inside MessageScrollerContent",
+        "Uses Message with MessageAvatar/MessageContent/MessageHeader for row layout instead of custom flex divs",
+        "Uses Bubble + BubbleContent for the message surface instead of a styled div with bg-muted/bg-primary",
+        "Uses Attachment (AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription) for the file and image attachments instead of Item or a custom card",
+        "Uses Marker (variant=\"separator\") for the 'Today' divider instead of Separator plus a centered label",
+        "Uses semantic color tokens and gap-* spacing; no raw colors like bg-emerald-500 and no space-y-*",
+        "Includes \"use client\" when the component uses state or event handlers (isRSC)"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Using shadcn/ui (base-nova preset, lucide icons), build a streaming AI chat UI. The assistant's reply streams in while it generates, the view auto-scrolls to follow the latest content but stops following if the user scrolls up to read earlier messages, a 'jump to latest' button appears when the user has scrolled away from the bottom, and a subtle 'thinking…' shimmer shows while the model is generating.",
+      "expected_output": "A React component that delegates scroll/anchor behavior to MessageScroller and uses MessageScrollerButton for jump-to-latest and the shimmer utility for the thinking indicator — no hand-rolled scroll logic or custom shimmer keyframes.",
+      "files": [],
+      "expectations": [
+        "Uses MessageScroller with MessageScrollerProvider (autoScroll) and scrollAnchor on message items for the stick-to-bottom/follow behavior instead of a custom useStickToBottom hook or ResizeObserver/scrollTop wiring",
+        "Uses MessageScrollerButton for the jump-to-latest control instead of a hand-built conditional button driven by manual scroll-position state",
+        "Uses the shimmer utility class for the 'thinking…' indicator instead of a custom @keyframes or bg-clip-text gradient animation",
+        "Wraps each message row in MessageScrollerItem inside MessageScrollerContent",
+        "Uses Message + Bubble + BubbleContent for the conversation rows instead of hand-rolled bubble divs",
+        "Uses semantic color tokens and gap-* spacing; includes \"use client\" (isRSC)"
+      ]
+    }
+  ]
+}
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/mcp.md b/plugins/shadcn-ui/agent/skills/shadcn/mcp.md
new file mode 100644
index 00000000..6539ddaa
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/mcp.md
@@ -0,0 +1,105 @@
+# shadcn MCP Server
+
+The CLI includes an MCP server that lets AI assistants search, browse, view, and install items from registries.
+
+---
+
+## Setup
+
+```bash
+shadcn mcp        # start the MCP server (stdio)
+shadcn mcp init   # write config for your editor
+```
+
+Editor config files:
+
+| Editor      | Config file                     |
+| ----------- | ------------------------------- |
+| Claude Code | `.mcp.json`                     |
+| Cursor      | `.cursor/mcp.json`              |
+| VS Code     | `.vscode/mcp.json`              |
+| OpenCode    | `opencode.json`                 |
+| Codex       | `~/.codex/config.toml` (manual) |
+
+---
+
+## Tools
+
+> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.
+
+### `shadcn:get_project_registries`
+
+Returns registry names from `components.json`. Errors if no `components.json` exists.
+
+**Input:** none
+
+### `shadcn:list_items_in_registries`
+
+Lists all items from one or more registries. Registries can be configured
+namespaces such as `@acme`, public GitHub sources such as `owner/repo`, or
+registry catalog URLs. Omit `registries` to list from every registry configured
+in `components.json`.
+
+**Input:** `registries` (string[], optional — omit for all configured), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
+
+### `shadcn:search_items_in_registries`
+
+Fuzzy search across registries. Registries can be configured namespaces, public
+GitHub sources, or registry catalog URLs. Omit `registries` to search every
+registry configured in `components.json` — e.g. "find me a hero" across all
+configured registries.
+
+**Input:** `registries` (string[], optional — omit for all configured), `query` (string), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
+
+### `shadcn:view_items_in_registries`
+
+View item details including full file contents.
+
+**Input:** `items` (string[]) — e.g.
+`["@shadcn/button", "@shadcn/card", "owner/repo/item"]`
+
+### `shadcn:get_item_examples_from_registries`
+
+Find usage examples and demos with source code. Omit `registries` to search
+every registry configured in `components.json`.
+
+**Input:** `registries` (string[], optional — omit for all configured), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
+
+### `shadcn:get_add_command_for_items`
+
+Returns the CLI install command.
+
+**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
+
+### `shadcn:get_audit_checklist`
+
+Returns a checklist for verifying components (imports, deps, lint, TypeScript).
+
+**Input:** none
+
+---
+
+## Configuring Registries
+
+Namespaced and authenticated registries are set in `components.json`. The
+`@shadcn` registry is always built-in. Public GitHub registries can also be used
+directly as `owner/repo` registry sources when the repository has a root
+`registry.json`; they do not need `components.json` configuration.
+
+```json
+{
+  "registries": {
+    "@acme": "https://acme.com/r/{name}.json",
+    "@private": {
+      "url": "https://private.com/r/{name}.json",
+      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
+    }
+  }
+}
+```
+
+- Names must start with `@`.
+- URLs must contain `{name}`.
+- `${VAR}` references are resolved from environment variables.
+
+Community registry index: `https://ui.shadcn.com/r/registries.json`
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/registry.md b/plugins/shadcn-ui/agent/skills/shadcn/registry.md
new file mode 100644
index 00000000..5369468b
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/registry.md
@@ -0,0 +1,277 @@
+# Registry Authoring and Addresses
+
+Use this reference when the user wants to create, fix, publish, or reason about
+a shadcn registry.
+
+## Mental Model
+
+A registry has two forms:
+
+- **Source registry**: an authored `registry.json` in a project or repository.
+  It may use `include` and file paths that point at source files.
+- **Built registry**: generated JSON files served to CLI consumers, usually
+  from `public/r`. Use `npx shadcn@latest build` to create this form.
+
+The CLI installer consumes registry item payloads. A source registry is a way to
+author those payloads from real files.
+
+Registry items are not limited to React components. They can distribute
+components, hooks, utilities, design tokens, pages, config files, docs, rules,
+workflows, templates, MCP files, and other project files.
+
+## Root `registry.json`
+
+The root registry file should define registry metadata and either `items` or
+`include`.
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "acme",
+  "homepage": "https://acme.com",
+  "items": [
+    {
+      "name": "absolute-url",
+      "type": "registry:lib",
+      "title": "Absolute URL",
+      "description": "A utility to turn any path into an absolute URL.",
+      "files": [
+        {
+          "path": "lib/absolute-url.ts",
+          "type": "registry:lib"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Root registry rules:
+
+- Root `registry.json` must include `name` and `homepage`.
+- `items` is an array of registry item definitions.
+- `include` may be used to split the source registry into multiple files.
+- Included registry files may omit `name` and `homepage`.
+
+## Include
+
+Use `include` to keep large registries modular.
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "acme",
+  "homepage": "https://acme.com",
+  "include": ["registry/ui/registry.json", "registry/blocks/registry.json"]
+}
+```
+
+Include rules:
+
+- Include paths are relative to the `registry.json` that declares them.
+- Include paths must explicitly point to a `registry.json` file.
+- Do not use remote URLs, absolute paths, or parent traversal (`..`).
+- Item file paths are relative to the registry file that declares the item.
+- Duplicate item names fail across the resolved registry.
+
+Example included file:
+
+```json
+{
+  "items": [
+    {
+      "name": "button",
+      "type": "registry:ui",
+      "files": [
+        {
+          "path": "button.tsx",
+          "type": "registry:ui"
+        }
+      ]
+    }
+  ]
+}
+```
+
+If this file is at `registry/ui/registry.json`, then `button.tsx` is read from
+`registry/ui/button.tsx`, and the built item path is emitted relative to the
+root registry.
+
+## Item Definitions
+
+Common item fields:
+
+```json
+{
+  "name": "login-form",
+  "type": "registry:block",
+  "title": "Login Form",
+  "description": "A login form with email and password fields.",
+  "dependencies": ["zod"],
+  "registryDependencies": ["button", "input", "label"],
+  "files": [
+    {
+      "path": "blocks/login-form.tsx",
+      "type": "registry:block"
+    }
+  ],
+  "cssVars": {
+    "light": {
+      "brand": "oklch(0.62 0.18 250)"
+    },
+    "dark": {
+      "brand": "oklch(0.72 0.16 250)"
+    }
+  }
+}
+```
+
+Important fields:
+
+- `name`: the installable item name. It is not necessarily a file path.
+- `type`: one of the registry item types, such as `registry:ui`,
+  `registry:block`, `registry:lib`, `registry:hook`, `registry:file`,
+  `registry:page`, `registry:theme`, `registry:style`, `registry:font`, or
+  `registry:item`.
+- `files`: source files copied or generated by the item.
+- `dependencies`: npm runtime dependencies.
+- `devDependencies`: npm development dependencies.
+- `registryDependencies`: other registry items required by this item.
+- `cssVars`, `css`, `tailwind`, `envVars`, and `docs`: optional install-time
+  additions.
+
+File rules:
+
+- File paths are relative to the declaring `registry.json`.
+- `registry:file` and `registry:page` files require a `target`.
+- Do not use remote file URLs in source registry file paths.
+- Keep source files copy-pasteable: no hidden app-only imports.
+
+## Registry Dependencies
+
+`registryDependencies` entries are item addresses, not file paths.
+
+```json
+{
+  "name": "login-form",
+  "type": "registry:block",
+  "registryDependencies": ["button", "@acme/input", "acme/ui/card#v1.2.0"],
+  "files": [
+    {
+      "path": "blocks/login-form.tsx",
+      "type": "registry:block"
+    }
+  ]
+}
+```
+
+Dependency rules:
+
+- Bare names such as `"button"` mean official shadcn items.
+- Bare names never mean same-registry or same-repository items.
+- Namespaced dependencies use `@namespace/item-name`.
+- GitHub dependencies use `owner/repo/item-name`.
+- Pin GitHub dependencies with `owner/repo/item-name#ref` when needed.
+- Refs are not inherited. If `owner/repo/foo#v2` depends on `bar` from the same
+  repo at `v2`, write `owner/repo/bar#v2`.
+- Do not use relative dependencies such as `"./bar"`.
+
+## Address Schemes
+
+When reasoning about a registry item string, classify it first.
+
+| Address                             | Scheme    | Meaning                                                      |
+| ----------------------------------- | --------- | ------------------------------------------------------------ |
+| `button`                            | shadcn    | Official shadcn item named `button`.                         |
+| `@acme/button`                      | namespace | Item `button` from configured registry `@acme`.              |
+| `@acme/ui/button`                   | namespace | Item `ui/button` from configured registry `@acme`.           |
+| `https://example.com/r/button.json` | url       | Built registry item JSON at that URL.                        |
+| `./button.json`                     | file      | Built registry item JSON on disk.                            |
+| `acme/ui/button`                    | github    | Item `button` from GitHub repo `acme/ui`.                    |
+| `acme/ui/forms/login#main`          | github    | Item `forms/login` from GitHub repo `acme/ui` at ref `main`. |
+
+For namespace and GitHub addresses, slashful item names are allowed and are item
+names, not file paths. Addresses ending in `.json` keep file-address
+precedence, so `acme/ui/data/schema.json` is treated as a file path, not a
+GitHub item address.
+
+## GitHub Registries
+
+A public GitHub repository can act as a source registry when it has a root
+`registry.json`.
+
+```txt
+owner/repo/item-name[#ref]
+```
+
+Rules:
+
+- The first two path segments are GitHub owner and repo.
+- All remaining path segments are the registry item name.
+- The source entrypoint is always root `registry.json`.
+- GitHub registries are source registries consumed directly by the CLI. They do
+  not require `shadcn build` or generated item JSON files.
+- `include` follows the same source-registry rules as local registries.
+- Currently, GitHub addresses support public `github.com` repositories only.
+- Private repos and GitHub Enterprise require explicit product decisions.
+
+When implementing GitHub registry fetching, resolve refs to a commit SHA before
+reading source files. Do not read moving refs directly from
+`raw.githubusercontent.com`, because branch-like refs can be cached for several
+minutes.
+
+Preferred flow:
+
+```txt
+owner/repo[#ref]
+  -> resolve ref with git ls-remote
+  -> commit SHA
+  -> read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json
+  -> read includes and item files from the same SHA
+```
+
+This keeps a command on one consistent repository snapshot.
+
+Full 40-character commit SHAs are already stable and can be used directly.
+Branches, tags, and short refs require Git so the CLI can resolve them to a
+commit SHA first.
+
+## Build and Verify
+
+Use the CLI to build source registries:
+
+```bash
+npx shadcn@latest build
+npx shadcn@latest build registry.json --output public/r
+```
+
+Use CLI commands to inspect the result:
+
+```bash
+npx shadcn@latest list @acme
+npx shadcn@latest search @acme -q "login"
+npx shadcn@latest view @acme/login-form
+npx shadcn@latest add @acme/login-form --dry-run
+npx shadcn@latest registry validate ./registry.json
+```
+
+Use GitHub addresses directly for public GitHub registries:
+
+```bash
+npx shadcn@latest list owner/repo
+npx shadcn@latest search owner/repo -q "login"
+npx shadcn@latest view owner/repo/item
+npx shadcn@latest add owner/repo/item --dry-run
+npx shadcn@latest registry validate owner/repo
+```
+
+When working on registry implementation in the shadcn/ui codebase:
+
+- Keep address parsing pure and testable.
+- Do not add side effects to validators.
+- Preserve existing behavior for official shadcn, namespace, URL, and file
+  schemes.
+- Add tests for address parsing, source loading, dependency resolution, list,
+  search, view, and add paths.
+- Prefer small source-reader abstractions over a plugin system until there are
+  multiple real providers.
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/rules/base-vs-radix.md b/plugins/shadcn-ui/agent/skills/shadcn/rules/base-vs-radix.md
new file mode 100644
index 00000000..c1ed7d11
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/rules/base-vs-radix.md
@@ -0,0 +1,306 @@
+# Base vs Radix
+
+API differences between `base` and `radix`. Check the `base` field from `npx shadcn@latest info`.
+
+## Contents
+
+- Composition: asChild vs render
+- Button / trigger as non-button element
+- Select (items prop, placeholder, positioning, multiple, object values)
+- ToggleGroup (type vs multiple)
+- Slider (scalar vs array)
+- Accordion (type and defaultValue)
+
+---
+
+## Composition: asChild (radix) vs render (base)
+
+Radix uses `asChild` to replace the default element. Base uses `render`. Don't wrap triggers in extra elements.
+
+**Incorrect:**
+
+```tsx
+<DialogTrigger>
+  <div>
+    <Button>Open</Button>
+  </div>
+</DialogTrigger>
+```
+
+**Correct (radix):**
+
+```tsx
+<DialogTrigger asChild>
+  <Button>Open</Button>
+</DialogTrigger>
+```
+
+**Correct (base):**
+
+```tsx
+<DialogTrigger render={<Button />}>Open</DialogTrigger>
+```
+
+This applies to all trigger and close components: `DialogTrigger`, `SheetTrigger`, `AlertDialogTrigger`, `DropdownMenuTrigger`, `PopoverTrigger`, `TooltipTrigger`, `CollapsibleTrigger`, `DialogClose`, `SheetClose`, `NavigationMenuLink`, `BreadcrumbLink`, `SidebarMenuButton`, `Badge`, `Item`.
+
+---
+
+## Button / trigger as non-button element (base only)
+
+When `render` changes an element to a non-button (`<a>`, `<span>`), add `nativeButton={false}`.
+
+**Incorrect (base):** missing `nativeButton={false}`.
+
+```tsx
+<Button render={<a href="/docs" />}>Read the docs</Button>
+```
+
+**Correct (base):**
+
+```tsx
+<Button render={<a href="/docs" />} nativeButton={false}>
+  Read the docs
+</Button>
+```
+
+**Correct (radix):**
+
+```tsx
+<Button asChild>
+  <a href="/docs">Read the docs</a>
+</Button>
+```
+
+Same for triggers whose `render` is not a `Button`:
+
+```tsx
+// base.
+<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
+  Pick date
+</PopoverTrigger>
+```
+
+---
+
+## Select
+
+**items prop (base only).** Base requires an `items` prop on the root. Radix uses inline JSX only.
+
+**Incorrect (base):**
+
+```tsx
+<Select>
+  <SelectTrigger><SelectValue placeholder="Select a fruit" /></SelectTrigger>
+</Select>
+```
+
+**Correct (base):**
+
+```tsx
+const items = [
+  { label: "Select a fruit", value: null },
+  { label: "Apple", value: "apple" },
+  { label: "Banana", value: "banana" },
+]
+
+<Select items={items}>
+  <SelectTrigger>
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      {items.map((item) => (
+        <SelectItem key={item.value} value={item.value}>{item.label}</SelectItem>
+      ))}
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Correct (radix):**
+
+```tsx
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectItem value="apple">Apple</SelectItem>
+      <SelectItem value="banana">Banana</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Placeholder.** Base uses a `{ value: null }` item in the items array. Radix uses `<SelectValue placeholder="...">`.
+
+**Content positioning.** Base uses `alignItemWithTrigger`. Radix uses `position`.
+
+```tsx
+// base.
+<SelectContent alignItemWithTrigger={false} side="bottom">
+
+// radix.
+<SelectContent position="popper">
+```
+
+---
+
+## Select — multiple selection and object values (base only)
+
+Base supports `multiple`, render-function children on `SelectValue`, and object values with `itemToStringValue`. Radix is single-select with string values only.
+
+**Correct (base — multiple selection):**
+
+```tsx
+<Select items={items} multiple defaultValue={[]}>
+  <SelectTrigger>
+    <SelectValue>
+      {(value: string[]) => value.length === 0 ? "Select fruits" : `${value.length} selected`}
+    </SelectValue>
+  </SelectTrigger>
+  ...
+</Select>
+```
+
+**Correct (base — object values):**
+
+```tsx
+<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
+  <SelectTrigger>
+    <SelectValue>{(value) => value.name}</SelectValue>
+  </SelectTrigger>
+  ...
+</Select>
+```
+
+---
+
+## ToggleGroup
+
+Base uses a `multiple` boolean prop. Radix uses `type="single"` or `type="multiple"`.
+
+**Incorrect (base):**
+
+```tsx
+<ToggleGroup type="single" defaultValue="daily">
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Correct (base):**
+
+```tsx
+// Single (no prop needed), defaultValue is always an array.
+<ToggleGroup defaultValue={["daily"]} spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+</ToggleGroup>
+
+// Multi-selection.
+<ToggleGroup multiple>
+  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Correct (radix):**
+
+```tsx
+// Single, defaultValue is a string.
+<ToggleGroup type="single" defaultValue="daily" spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+</ToggleGroup>
+
+// Multi-selection.
+<ToggleGroup type="multiple">
+  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Controlled single value:**
+
+```tsx
+// base — wrap/unwrap arrays.
+const [value, setValue] = React.useState("normal")
+<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>
+
+// radix — plain string.
+const [value, setValue] = React.useState("normal")
+<ToggleGroup type="single" value={value} onValueChange={setValue}>
+```
+
+---
+
+## Slider
+
+Base accepts a plain number for a single thumb. Radix always requires an array.
+
+**Incorrect (base):**
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+**Correct (base):**
+
+```tsx
+<Slider defaultValue={50} max={100} step={1} />
+```
+
+**Correct (radix):**
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+Both use arrays for range sliders. Controlled `onValueChange` in base may need a cast:
+
+```tsx
+// base.
+const [value, setValue] = React.useState([0.3, 0.7])
+<Slider value={value} onValueChange={(v) => setValue(v as number[])} />
+
+// radix.
+const [value, setValue] = React.useState([0.3, 0.7])
+<Slider value={value} onValueChange={setValue} />
+```
+
+---
+
+## Accordion
+
+Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. `defaultValue` is a string. Base uses no `type` prop, uses `multiple` boolean, and `defaultValue` is always an array.
+
+**Incorrect (base):**
+
+```tsx
+<Accordion type="single" collapsible defaultValue="item-1">
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+```
+
+**Correct (base):**
+
+```tsx
+<Accordion defaultValue={["item-1"]}>
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+
+// Multi-select.
+<Accordion multiple defaultValue={["item-1", "item-2"]}>
+  <AccordionItem value="item-1">...</AccordionItem>
+  <AccordionItem value="item-2">...</AccordionItem>
+</Accordion>
+```
+
+**Correct (radix):**
+
+```tsx
+<Accordion type="single" collapsible defaultValue="item-1">
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+```
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/rules/chat.md b/plugins/shadcn-ui/agent/skills/shadcn/rules/chat.md
new file mode 100644
index 00000000..8ce62fe4
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/rules/chat.md
@@ -0,0 +1,224 @@
+# Chat & Messaging
+
+Components for conversation and chat UI. Compose these instead of hand-rolling
+bubbles, scroll containers, dividers, or attachment cards.
+
+Install: `npx shadcn@latest add message-scroller message bubble attachment marker`
+
+The same component names and props ship for both `base` and `radix`; only
+composition differs (`render` vs `asChild`). See [base-vs-radix.md](./base-vs-radix.md).
+
+## Contents
+
+- Scrollable threads use MessageScroller
+- Message rows use Message
+- Message surfaces use Bubble
+- Attachments use Attachment
+- System notes and dividers use Marker
+- Streaming, anchoring, and jump-to-latest are built in
+- Escape hatch: the scroller hooks
+
+---
+
+## Scrollable threads use MessageScroller
+
+A conversation that scrolls, follows new messages, restores position, or jumps
+to a message uses `MessageScroller`. Don't build a raw overflow container with
+manual scroll wiring, and don't reach for `ScrollArea`.
+
+The parts nest in a fixed order. Every direct child of the content is wrapped in
+a `MessageScrollerItem` so the scroller can measure, anchor, preserve position,
+track visibility, and jump to it. `MessageScrollerButton` sits inside
+`MessageScroller`, after the viewport.
+
+**Incorrect:**
+
+```tsx
+// Hand-rolled scroll container with manual stick-to-bottom logic.
+<div ref={scrollRef} onScroll={handleScroll} className="flex-1 overflow-y-auto">
+  <div className="flex flex-col gap-6 p-4">
+    {messages.map((m) => (
+      <ChatMessage key={m.id} message={m} />
+    ))}
+  </div>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<MessageScrollerProvider autoScroll>
+  <MessageScroller>
+    <MessageScrollerViewport>
+      <MessageScrollerContent>
+        {messages.map((message) => (
+          <MessageScrollerItem
+            key={message.id}
+            messageId={message.id}
+            scrollAnchor={message.role === "user"}
+          >
+            <Message align={message.role === "user" ? "end" : "start"}>
+              {/* ...message content... */}
+            </Message>
+          </MessageScrollerItem>
+        ))}
+      </MessageScrollerContent>
+    </MessageScrollerViewport>
+    <MessageScrollerButton />
+  </MessageScroller>
+</MessageScrollerProvider>
+```
+
+---
+
+## Message rows use Message
+
+`Message` lays out a single row: avatar, header, content, footer, with
+alignment. Group consecutive rows from one sender with `MessageGroup`. Don't
+rebuild the row from flex divs.
+
+`align="end"` is the current user's side; `align="start"` is everyone else.
+
+```tsx
+<Message align="start">
+  <MessageAvatar>
+    <Avatar>
+      <AvatarImage src={sender.avatar} alt={sender.name} />
+      <AvatarFallback>{initials}</AvatarFallback>
+    </Avatar>
+  </MessageAvatar>
+  <MessageContent>
+    <MessageHeader>{sender.name}</MessageHeader>
+    <Bubble>
+      <BubbleContent>{text}</BubbleContent>
+    </Bubble>
+    <MessageFooter>{time}</MessageFooter>
+  </MessageContent>
+</Message>
+```
+
+---
+
+## Message surfaces use Bubble
+
+The colored message surface is `Bubble` + `BubbleContent`, never a styled `div`
+with `bg-muted` / `bg-primary` and hand-managed corners.
+
+- `variant`: `default`, `secondary`, `muted`, `tinted`, `outline`, `ghost`, `destructive`.
+- `align`: `start` or `end` (matches the `Message` side).
+
+`BubbleReactions` renders the reaction cluster. `side` (`top` | `bottom`) and
+`align` (`start` | `end`) position it against the bubble. Don't lay reactions out
+with absolutely-positioned `Badge`s.
+
+**Incorrect:**
+
+```tsx
+<div className="w-fit rounded-2xl bg-primary px-3 py-2 text-primary-foreground">
+  {text}
+</div>
+```
+
+**Correct:**
+
+```tsx
+<Bubble variant="default" align="end">
+  <BubbleContent>{text}</BubbleContent>
+  <BubbleReactions side="bottom" align="end">
+    <Badge variant="secondary">👍 2</Badge>
+  </BubbleReactions>
+</Bubble>
+```
+
+---
+
+## Attachments use Attachment
+
+File and image attachments use `Attachment`, not `Item` or a custom card. It
+carries upload state, so wire `state` to the real status rather than rendering a
+separate spinner.
+
+- `state`: `idle`, `uploading`, `processing`, `error`, `done`. `uploading` and
+  `processing` apply the `shimmer` animation to the title automatically.
+- `size`: `default`, `sm`, `xs`. `orientation`: `horizontal`, `vertical`.
+- Use `AttachmentGroup` to lay out several attachments in a scrolling row.
+
+```tsx
+<Attachment state="done">
+  <AttachmentMedia variant="icon">
+    <FileTextIcon />
+  </AttachmentMedia>
+  <AttachmentContent>
+    <AttachmentTitle>homepage-feedback.pdf</AttachmentTitle>
+    <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
+  </AttachmentContent>
+  <AttachmentActions>
+    <AttachmentAction>
+      <DownloadIcon />
+    </AttachmentAction>
+  </AttachmentActions>
+</Attachment>
+```
+
+For an image, use `<AttachmentMedia variant="image">` with an `img` child.
+
+---
+
+## System notes and dividers use Marker
+
+Status lines ("Sarah joined the conversation"), date dividers ("Today"), and
+labeled separators are `Marker`, not a `Separator` plus a centered span.
+
+- `variant`: `default` (plain row), `separator` (centered label with rules on
+  each side), `border` (bottom-bordered row).
+- `MarkerIcon` holds a leading icon; `MarkerContent` holds the label.
+
+**Incorrect:**
+
+```tsx
+<div className="flex items-center gap-3 py-2">
+  <Separator className="flex-1" />
+  <span className="text-xs text-muted-foreground">Today</span>
+  <Separator className="flex-1" />
+</div>
+```
+
+**Correct:**
+
+```tsx
+<Marker variant="separator">
+  <MarkerContent>Today</MarkerContent>
+</Marker>
+```
+
+---
+
+## Streaming, anchoring, and jump-to-latest are built in
+
+`MessageScroller` handles the behavior that chat UIs usually reinvent. Don't
+write a `useStickToBottom` hook, a `ResizeObserver`, or manual `scrollTop` math.
+
+- **Follow the live edge while streaming.** `MessageScrollerProvider` with
+  `autoScroll` keeps the view pinned to new content and yields the moment the
+  user scrolls up. Streaming token updates that grow the last message are
+  followed automatically.
+- **Anchor a turn.** `scrollAnchor` on a `MessageScrollerItem` marks the row to
+  hold in view (typically the user's message that started the turn).
+- **Jump to latest.** `MessageScrollerButton` appears when the user scrolls away
+  and scrolls back on click. `direction="end"` (default) or `direction="start"`.
+  It is a self-managing control, so don't gate it behind your own scroll-position
+  state.
+
+For a "thinking…" indicator while the model generates, apply the `shimmer`
+utility to text. Don't author a custom keyframe animation. See
+[styling.md](./styling.md).
+
+---
+
+## Escape hatch: the scroller hooks
+
+For behavior the parts don't expose, read state from the hooks rather than
+re-implementing the scroller: `useMessageScroller`,
+`useMessageScrollerVisibility`, and `useMessageScrollerScrollable`. They come
+from the auto-installed `@shadcn/react` dependency, so there's nothing extra to
+install. Reach for them only when composition can't express what you need.
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/rules/composition.md b/plugins/shadcn-ui/agent/skills/shadcn/rules/composition.md
new file mode 100644
index 00000000..a8aa4274
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/rules/composition.md
@@ -0,0 +1,213 @@
+# Component Composition
+
+## Contents
+
+- Items always inside their Group component
+- Callouts use Alert
+- Empty states use Empty component
+- Toast notifications follow the project base
+- Choosing between overlay components
+- Dialog, Sheet, and Drawer always need a Title
+- Card structure
+- Button has no isPending or isLoading prop
+- TabsTrigger must be inside TabsList
+- Avatar always needs AvatarFallback
+- Use Separator instead of raw hr or border divs
+- Use Skeleton for loading placeholders
+- Use Badge instead of custom styled spans
+
+---
+
+## Items always inside their Group component
+
+Never render items directly inside the content container.
+
+**Incorrect:**
+
+```tsx
+<SelectContent>
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+</SelectContent>
+```
+
+**Correct:**
+
+```tsx
+<SelectContent>
+  <SelectGroup>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+This applies to all group-based components:
+
+| Item | Group |
+|------|-------|
+| `SelectItem`, `SelectLabel` | `SelectGroup` |
+| `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` | `DropdownMenuGroup` |
+| `MenubarItem` | `MenubarGroup` |
+| `ContextMenuItem` | `ContextMenuGroup` |
+| `CommandItem` | `CommandGroup` |
+| `MessageScrollerItem` | `MessageScrollerContent` |
+| `Message` (consecutive, same sender) | `MessageGroup` |
+| `Bubble` (stacked) | `BubbleGroup` |
+| `Attachment` (in a row) | `AttachmentGroup` |
+
+Chat components nest in a fixed order (`MessageScrollerProvider` → `MessageScroller` → `MessageScrollerViewport` → `MessageScrollerContent` → `MessageScrollerItem`). See [chat.md](./chat.md).
+
+---
+
+## Callouts use Alert
+
+```tsx
+<Alert>
+  <AlertTitle>Warning</AlertTitle>
+  <AlertDescription>Something needs attention.</AlertDescription>
+</Alert>
+```
+
+---
+
+## Empty states use Empty component
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>
+    <EmptyTitle>No projects yet</EmptyTitle>
+    <EmptyDescription>Get started by creating a new project.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>Create Project</Button>
+  </EmptyContent>
+</Empty>
+```
+
+---
+
+## Toast notifications follow the project base
+
+For Base UI projects, use the `toast` component:
+
+```tsx
+import { toast } from "@/components/ui/toast"
+
+toast.add({
+  title: "Changes saved.",
+})
+```
+
+For Radix and React Aria projects, use Sonner:
+
+```tsx
+import { toast } from "sonner"
+
+toast.success("Changes saved.")
+toast.error("Something went wrong.")
+toast("File deleted.", {
+  action: { label: "Undo", onClick: () => undoDelete() },
+})
+```
+
+---
+
+## Choosing between overlay components
+
+| Use case | Component |
+|----------|-----------|
+| Focused task that requires input | `Dialog` |
+| Destructive action confirmation | `AlertDialog` |
+| Side panel with details or filters | `Sheet` |
+| Mobile-first bottom panel | `Drawer` |
+| Quick info on hover | `HoverCard` |
+| Small contextual content on click | `Popover` |
+
+---
+
+## Dialog, Sheet, and Drawer always need a Title
+
+`DialogTitle`, `SheetTitle`, `DrawerTitle` are required for accessibility. Use `className="sr-only"` if visually hidden.
+
+```tsx
+<DialogContent>
+  <DialogHeader>
+    <DialogTitle>Edit Profile</DialogTitle>
+    <DialogDescription>Update your profile.</DialogDescription>
+  </DialogHeader>
+  ...
+</DialogContent>
+```
+
+---
+
+## Card structure
+
+Use full composition — don't dump everything into `CardContent`:
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team Members</CardTitle>
+    <CardDescription>Manage your team.</CardDescription>
+  </CardHeader>
+  <CardContent>...</CardContent>
+  <CardFooter>
+    <Button>Invite</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+## Button has no isPending or isLoading prop
+
+Compose with `Spinner` + `data-icon` + `disabled`:
+
+```tsx
+<Button disabled>
+  <Spinner data-icon="inline-start" />
+  Saving...
+</Button>
+```
+
+---
+
+## TabsTrigger must be inside TabsList
+
+Never render `TabsTrigger` directly inside `Tabs` — always wrap in `TabsList`:
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">...</TabsContent>
+</Tabs>
+```
+
+---
+
+## Avatar always needs AvatarFallback
+
+Always include `AvatarFallback` for when the image fails to load:
+
+```tsx
+<Avatar>
+  <AvatarImage src="/avatar.png" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+---
+
+## Use existing components instead of custom markup
+
+| Instead of | Use |
+|---|---|
+| `<hr>` or `<div className="border-t">` | `<Separator />` |
+| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |
+| `<span className="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` |
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/rules/forms.md b/plugins/shadcn-ui/agent/skills/shadcn/rules/forms.md
new file mode 100644
index 00000000..f451e2f7
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/rules/forms.md
@@ -0,0 +1,192 @@
+# Forms & Inputs
+
+## Contents
+
+- Forms use FieldGroup + Field
+- InputGroup requires InputGroupInput/InputGroupTextarea
+- Buttons inside inputs use InputGroup + InputGroupAddon
+- Option sets (2–7 choices) use ToggleGroup
+- FieldSet + FieldLegend for grouping related fields
+- Field validation and disabled states
+
+---
+
+## Forms use FieldGroup + Field
+
+Always use `FieldGroup` + `Field` — never raw `div` with `space-y-*`:
+
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" type="email" />
+  </Field>
+  <Field>
+    <FieldLabel htmlFor="password">Password</FieldLabel>
+    <Input id="password" type="password" />
+  </Field>
+</FieldGroup>
+```
+
+Use `Field orientation="horizontal"` for settings pages. Use `FieldLabel className="sr-only"` for visually hidden labels.
+
+**Choosing form controls:**
+
+- Simple text input → `Input`
+- Dropdown with predefined options → `Select`
+- Searchable dropdown → `Combobox`
+- Native HTML select (no JS) → `native-select`
+- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)
+- Single choice from few options → `RadioGroup`
+- Toggle between 2–5 options → `ToggleGroup` + `ToggleGroupItem`
+- OTP/verification code → `InputOTP`
+- Multi-line text → `Textarea`
+
+---
+
+## InputGroup requires InputGroupInput/InputGroupTextarea
+
+Never use raw `Input` or `Textarea` inside an `InputGroup`.
+
+**Incorrect:**
+
+```tsx
+<InputGroup>
+  <Input placeholder="Search..." />
+</InputGroup>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupInput } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+</InputGroup>
+```
+
+---
+
+## Buttons inside inputs use InputGroup + InputGroupAddon
+
+Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.
+
+**Incorrect:**
+
+```tsx
+<div className="relative">
+  <Input placeholder="Search..." className="pr-10" />
+  <Button className="absolute right-0 top-0" size="icon">
+    <SearchIcon />
+  </Button>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupInput, InputGroupAddon } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+  <InputGroupAddon>
+    <Button size="icon">
+      <SearchIcon data-icon="inline-start" />
+    </Button>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+---
+
+## Option sets (2–7 choices) use ToggleGroup
+
+Don't manually loop `Button` components with active state.
+
+**Incorrect:**
+
+```tsx
+const [selected, setSelected] = useState("daily")
+
+<div className="flex gap-2">
+  {["daily", "weekly", "monthly"].map((option) => (
+    <Button
+      key={option}
+      variant={selected === option ? "default" : "outline"}
+      onClick={() => setSelected(option)}
+    >
+      {option}
+    </Button>
+  ))}
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
+
+<ToggleGroup spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+  <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
+</ToggleGroup>
+```
+
+Combine with `Field` for labelled toggle groups:
+
+```tsx
+<Field orientation="horizontal">
+  <FieldTitle id="theme-label">Theme</FieldTitle>
+  <ToggleGroup aria-labelledby="theme-label" spacing={2}>
+    <ToggleGroupItem value="light">Light</ToggleGroupItem>
+    <ToggleGroupItem value="dark">Dark</ToggleGroupItem>
+    <ToggleGroupItem value="system">System</ToggleGroupItem>
+  </ToggleGroup>
+</Field>
+```
+
+> **Note:** `defaultValue` and `type`/`multiple` props differ between base and radix. See [base-vs-radix.md](./base-vs-radix.md#togglegroup).
+
+---
+
+## FieldSet + FieldLegend for grouping related fields
+
+Use `FieldSet` + `FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:
+
+```tsx
+<FieldSet>
+  <FieldLegend variant="label">Preferences</FieldLegend>
+  <FieldDescription>Select all that apply.</FieldDescription>
+  <FieldGroup className="gap-3">
+    <Field orientation="horizontal">
+      <Checkbox id="dark" />
+      <FieldLabel htmlFor="dark" className="font-normal">Dark mode</FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+---
+
+## Field validation and disabled states
+
+Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control.
+
+```tsx
+// Invalid.
+<Field data-invalid>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" aria-invalid />
+  <FieldDescription>Invalid email address.</FieldDescription>
+</Field>
+
+// Disabled.
+<Field data-disabled>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" disabled />
+</Field>
+```
+
+Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`, `NativeSelect`, `InputOTP`.
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/rules/icons.md b/plugins/shadcn-ui/agent/skills/shadcn/rules/icons.md
new file mode 100644
index 00000000..bba8102f
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/rules/icons.md
@@ -0,0 +1,101 @@
+# Icons
+
+**Always use the project's configured `iconLibrary` for imports.** Check the `iconLibrary` field from project context: `lucide` → `lucide-react`, `tabler` → `@tabler/icons-react`, etc. Never assume `lucide-react`.
+
+---
+
+## Icons in Button use data-icon attribute
+
+Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix) to the icon. No sizing classes on the icon.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="mr-2 size-4" />
+  Search
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button>
+  <SearchIcon data-icon="inline-start"/>
+  Search
+</Button>
+
+<Button>
+  Next
+  <ArrowRightIcon data-icon="inline-end"/>
+</Button>
+```
+
+---
+
+## No sizing classes on icons inside components
+
+Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons inside `Button`, `DropdownMenuItem`, `Alert`, `Sidebar*`, or other shadcn components. Unless the user explicitly asks for custom icon sizes.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="size-4" data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon className="mr-2 size-4" />
+  Settings
+</DropdownMenuItem>
+```
+
+**Correct:**
+
+```tsx
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon />
+  Settings
+</DropdownMenuItem>
+```
+
+---
+
+## Pass icons as component objects, not string keys
+
+Use `icon={CheckIcon}`, not a string key to a lookup map.
+
+**Incorrect:**
+
+```tsx
+const iconMap = {
+  check: CheckIcon,
+  alert: AlertIcon,
+}
+
+function StatusBadge({ icon }: { icon: string }) {
+  const Icon = iconMap[icon]
+  return <Icon />
+}
+
+<StatusBadge icon="check" />
+```
+
+**Correct:**
+
+```tsx
+// Import from the project's configured iconLibrary (e.g. lucide-react, @tabler/icons-react).
+import { CheckIcon } from "lucide-react"
+
+function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {
+  return <Icon />
+}
+
+<StatusBadge icon={CheckIcon} />
+```
diff --git a/plugins/shadcn-ui/agent/skills/shadcn/rules/styling.md b/plugins/shadcn-ui/agent/skills/shadcn/rules/styling.md
new file mode 100644
index 00000000..fe751979
--- /dev/null
+++ b/plugins/shadcn-ui/agent/skills/shadcn/rules/styling.md
@@ -0,0 +1,185 @@
+# Styling & Customization
+
+See [customization.md](../customization.md) for theming, CSS variables, and adding custom colors.
+
+## Contents
+
+- Semantic colors
+- Built-in variants first
+- className for layout only
+- No space-x-* / space-y-*
+- Prefer size-* over w-* h-* when equal
+- Prefer truncate shorthand
+- No manual dark: color overrides
+- Use cn() for conditional classes
+- No manual z-index on overlay components
+- Use shimmer / scroll-fade utilities, not custom animations
+
+---
+
+## Semantic colors
+
+**Incorrect:**
+
+```tsx
+<div className="bg-blue-500 text-white">
+  <p className="text-gray-600">Secondary text</p>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<div className="bg-primary text-primary-foreground">
+  <p className="text-muted-foreground">Secondary text</p>
+</div>
+```
+
+---
+
+## No raw color values for status/state indicators
+
+For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
+
+**Incorrect:**
+
+```tsx
+<span className="text-emerald-600">+20.1%</span>
+<span className="text-green-500">Active</span>
+<span className="text-red-600">-3.2%</span>
+```
+
+**Correct:**
+
+```tsx
+<Badge variant="secondary">+20.1%</Badge>
+<Badge>Active</Badge>
+<span className="text-destructive">-3.2%</span>
+```
+
+If you need a success/positive color that doesn't exist as a semantic token, use a Badge variant or ask the user about adding a custom CSS variable to the theme (see [customization.md](../customization.md)).
+
+---
+
+## Built-in variants first
+
+**Incorrect:**
+
+```tsx
+<Button className="border border-input bg-transparent hover:bg-accent">
+  Click me
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button variant="outline">Click me</Button>
+```
+
+---
+
+## className for layout only
+
+Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
+
+**Incorrect:**
+
+```tsx
+<Card className="bg-blue-100 text-blue-900 font-bold">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+**Correct:**
+
+```tsx
+<Card className="max-w-md mx-auto">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+To customize a component's appearance, prefer these approaches in order:
+1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
+2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
+3. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).
+
+---
+
+## No space-x-* / space-y-*
+
+Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Input />
+  <Input />
+  <Button>Submit</Button>
+</div>
+```
+
+---
+
+## Prefer size-* over w-* h-* when equal
+
+`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
+
+---
+
+## Prefer truncate shorthand
+
+`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
+
+---
+
+## No manual dark: color overrides
+
+Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
+
+---
+
+## Use cn() for conditional classes
+
+Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in className strings.
+
+**Incorrect:**
+
+```tsx
+<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
+```
+
+**Correct:**
+
+```tsx
+import { cn } from "@/lib/utils"
+
+<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
+```
+
+---
+
+## No manual z-index on overlay components
+
+`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.
+
+---
+
+## Use shimmer / scroll-fade utilities, not custom animations
+
+For a live "thinking…" or loading-text shimmer, apply the `shimmer` utility. Don't author a custom `@keyframes` or a `bg-clip-text` gradient sweep.
+
+For scroll-aware edge fading on a scroll container, use `scroll-fade` (and the axis variants `scroll-fade-x` / `scroll-fade-b`). Don't hand-roll mask gradients. The chat components already apply these internally: `Attachment` shimmers its title during upload, and `MessageScrollerViewport` fades its edges.
+
+**Incorrect:**
+
+```tsx
+<span className="animate-pulse bg-gradient-to-r from-muted-foreground/40 via-foreground/70 to-muted-foreground/40 bg-clip-text text-transparent [animation:shimmer_1.6s_infinite]">
+  Thinking…
+</span>
+```
+
+**Correct:**
+
+```tsx
+<span className="shimmer">Thinking…</span>
+```
diff --git a/plugins/shadcn-ui/skills-lock.json b/plugins/shadcn-ui/skills-lock.json
index 62479ebf..707e02e7 100644
--- a/plugins/shadcn-ui/skills-lock.json
+++ b/plugins/shadcn-ui/skills-lock.json
@@ -11,7 +11,7 @@
       "source": "shadcn/ui",
       "sourceType": "github",
       "skillPath": "skills/shadcn/SKILL.md",
-      "computedHash": "d81caa0f86aabab65b25e302d454f23a3328760386ed9078345584c0d5c8058e"
+      "computedHash": "c1a68ee06a668aced9ab2b5fbdea5f989864123794eb2e056b339a072dbb7f10"
     }
   }
 }
diff --git a/plugins/skill-optimizer/.claude/skills/compare-skill-model-performance b/plugins/skill-optimizer/.claude/skills/compare-skill-model-performance
new file mode 120000
index 00000000..e19fe803
--- /dev/null
+++ b/plugins/skill-optimizer/.claude/skills/compare-skill-model-performance
@@ -0,0 +1 @@
+../../.agents/skills/compare-skill-model-performance
\ No newline at end of file
diff --git a/plugins/skill-optimizer/.claude/skills/optimize-skill-instructions b/plugins/skill-optimizer/.claude/skills/optimize-skill-instructions
new file mode 120000
index 00000000..52932b7d
--- /dev/null
+++ b/plugins/skill-optimizer/.claude/skills/optimize-skill-instructions
@@ -0,0 +1 @@
+../../.agents/skills/optimize-skill-instructions
\ No newline at end of file
diff --git a/plugins/skill-optimizer/.claude/skills/optimize-skill-performance b/plugins/skill-optimizer/.claude/skills/optimize-skill-performance
new file mode 120000
index 00000000..9f98ade5
--- /dev/null
+++ b/plugins/skill-optimizer/.claude/skills/optimize-skill-performance
@@ -0,0 +1 @@
+../../.agents/skills/optimize-skill-performance
\ No newline at end of file
diff --git a/plugins/skill-optimizer/.claude/skills/optimize-skill-performance-and-instructions b/plugins/skill-optimizer/.claude/skills/optimize-skill-performance-and-instructions
new file mode 120000
index 00000000..16f1321d
--- /dev/null
+++ b/plugins/skill-optimizer/.claude/skills/optimize-skill-performance-and-instructions
@@ -0,0 +1 @@
+../../.agents/skills/optimize-skill-performance-and-instructions
\ No newline at end of file
diff --git a/plugins/skill-optimizer/.claude/skills/setup-skill-performance b/plugins/skill-optimizer/.claude/skills/setup-skill-performance
new file mode 120000
index 00000000..89e4a4ca
--- /dev/null
+++ b/plugins/skill-optimizer/.claude/skills/setup-skill-performance
@@ -0,0 +1 @@
+../../.agents/skills/setup-skill-performance
\ No newline at end of file
diff --git a/plugins/slack-agent/.agents/skills/slack-agent/SKILL.md b/plugins/slack-agent/.agents/skills/slack-agent/SKILL.md
index 50f19ea7..973815cd 100644
--- a/plugins/slack-agent/.agents/skills/slack-agent/SKILL.md
+++ b/plugins/slack-agent/.agents/skills/slack-agent/SKILL.md
@@ -1,16 +1,16 @@
 ---
 name: slack-agent
-description: Use when working on Slack agent/bot code, Chat SDK applications, Bolt for JavaScript projects, or projects using @chat-adapter/slack or @slack/bolt. Provides development patterns, testing requirements, and quality standards.
-version: 4.0.0
+description: Use when building Slack agents/bots with eve (Vercel's filesystem-first agent framework), @vercel/connect, or eve/channels/slack. Covers defineAgent/defineTool patterns, Vercel Connect credential brokering, Slack channel setup, testing requirements, and quality standards.
+version: 5.0.0
 user-invocable: true
 ---
 
 # Slack Agent Development Skill
 
-This skill supports two frameworks for building Slack agents:
+This skill builds Slack agents with **eve** — Vercel's filesystem-first framework for durable backend agents — using **Vercel Connect** for Slack credentials:
 
-- **Chat SDK** (Recommended for new projects) — `chat` + `@chat-adapter/slack`
-- **Bolt for JavaScript** (For existing Bolt projects) — `@slack/bolt` + `@vercel/slack-bolt`
+- **eve** (`eve` package) — agent runtime, tools, channels, durability
+- **@vercel/connect** — brokered short-lived Slack tokens; no bot tokens or signing secrets to manage
 
 ## Skill Invocation Handling
 
@@ -30,111 +30,96 @@ When this skill is invoked via `/slack-agent`, check for arguments and route acc
 
 If invoked without arguments, detect the project state and route appropriately:
 
-1. **No `package.json` with `chat` or `@slack/bolt`** → Treat as `new`, start Phase 1
-2. **Has project but no customized `manifest.json`** → Start Phase 2
-3. **Has project but no `.env` file** → Start Phase 3
-4. **Has `.env` but not tested** → Start Phase 4
-5. **Tested but not deployed** → Start Phase 5
+1. **No `package.json` with `eve` and no `agent/` directory** → Treat as `new`, start Phase 1
+2. **Has eve project but no `agent/channels/slack.ts`** → Start Phase 2 (Slack connector + channel)
+3. **Has Slack channel but no `SLACK_CONNECTOR` configured** → Start Phase 3
+4. **Configured but not deployed** → Start Phase 5 (the Slack surface only works on a deployment)
+5. **Deployed but no tests** → Start Phase 6
 6. **Otherwise** → Provide general assistance using this skill's patterns
 
-### Framework Detection
+### Project Detection
 
-Detect which framework the project uses:
+Detect an eve project by either signal:
 
-- **`package.json` contains `"chat"`** → Chat SDK project
-- **`package.json` contains `"@slack/bolt"`** → Bolt project
-- **Neither detected** → New project, recommend Chat SDK (offer Bolt as alternative)
+- **`package.json` contains `"eve"`** as a dependency
+- **An `agent/` directory** with `instructions.md` and/or `agent.ts` exists
 
-Store the detected framework and use it to show the correct patterns throughout the wizard and development guidance.
+If neither is present, this is a new project: scaffold with `npx eve@latest init` (Node 24+ required).
 
 ### Wizard Phases
 
 The wizard is located in `./wizard/` with these phases:
-- `1-project-setup.md` - Understand purpose, choose framework, generate custom implementation plan
+- `1-project-setup.md` - Understand purpose, generate custom implementation plan, scaffold with `npx eve@latest init`
 - `1b-approve-plan.md` - Present plan for user approval before scaffolding
-- `2-create-slack-app.md` - Customize manifest, create app in Slack
-- `3-configure-environment.md` - Set up .env with credentials
-- `4-test-locally.md` - Dev server + ngrok tunnel
-- `5-deploy-production.md` - Vercel deployment
+- `2-create-slack-app.md` - Create the Slack connector with Vercel Connect and add the Slack channel
+- `3-configure-environment.md` - Set up env vars (`SLACK_CONNECTOR`, model credentials)
+- `4-test-locally.md` - Test agent logic locally with the `eve dev` TUI (Slack surface tests happen after deploy)
+- `5-deploy-production.md` - Deploy with `eve deploy`, verify the Slack surface
 - `6-setup-testing.md` - Vitest configuration
 
 **IMPORTANT:** For `new` projects, you MUST:
 1. Read `./wizard/1-project-setup.md` first
 2. Ask the user what kind of agent they want to build
-3. Offer framework choice (Chat SDK recommended, Bolt as alternative)
-4. Generate a custom implementation plan using `./reference/agent-archetypes.md`
-5. Present the plan for approval (Phase 1b) BEFORE scaffolding the project
-6. Only proceed to scaffold after the plan is approved
-
----
-
-## Framework Selection Guide
-
-| Aspect | Chat SDK | Bolt for JavaScript |
-|--------|----------|---------------------|
-| **Best for** | New projects | Existing Bolt codebases |
-| **Packages** | `chat`, `@chat-adapter/slack`, `@chat-adapter/state-redis` | `@slack/bolt`, `@vercel/slack-bolt` |
-| **Server** | Next.js App Router | Nitro (H3-based) |
-| **Event handling** | `bot.onNewMention()`, `bot.onSubscribedMessage()` | `app.event()`, `app.command()`, `app.message()` |
-| **Webhook route** | `app/api/webhooks/[platform]/route.ts` | `server/api/slack/events.post.ts` |
-| **Message posting** | `thread.post("text")` / `thread.post(<Card>...)` | `client.chat.postMessage({ channel, text, blocks })` |
-| **UI components** | JSX: `<Card>`, `<Button>`, `<Actions>` | Raw Block Kit JSON |
-| **State** | `@chat-adapter/state-redis` / `thread.state` | Manual / Vercel Workflow |
-| **Config** | `new Chat({ adapters: { slack } })` | `new App({ token, signingSecret, receiver })` |
+3. Generate a custom implementation plan using `./reference/agent-archetypes.md`
+4. Present the plan for approval (Phase 1b) BEFORE scaffolding the project
+5. Only proceed to scaffold after the plan is approved
 
 ---
 
 ## General Development Guidance
 
-You are working on a Slack agent project. Follow these mandatory practices for all code changes.
+You are working on a Slack agent project built with eve. Follow these mandatory practices for all code changes.
 
 ## Project Stack
 
-### If using Chat SDK
-
-- **Framework**: Next.js (App Router)
-- **Chat SDK**: `chat` + `@chat-adapter/slack` for Slack bot functionality
-- **State**: `@chat-adapter/state-redis` for state persistence (or in-memory for development)
-- **AI**: AI SDK v6 with @ai-sdk/gateway
+- **Framework**: eve (filesystem-first agent framework; Node 24+)
+- **Slack channel**: `eve/channels/slack` + `@vercel/connect` for credentials
+- **AI**: model routed through Vercel AI Gateway by default (`anthropic/claude-sonnet-5`); tool schemas with `zod`
+- **Durability**: Workflow SDK under the hood (Vercel Workflows when deployed on Vercel)
 - **Linting**: Biome
-- **Package Manager**: pnpm
+- **Package Manager**: pnpm (or npm — `npx eve@latest init` installs with npm)
 
 ```json
 {
+  "engines": { "node": "24.x" },
   "dependencies": {
-    "ai": "^6.0.0",
-    "@ai-sdk/gateway": "latest",
-    "chat": "latest",
-    "@chat-adapter/slack": "latest",
-    "@chat-adapter/state-redis": "latest",
+    "eve": "latest",
+    "ai": "latest",
     "zod": "^3.x",
-    "next": "^15.x"
+    "@vercel/connect": "latest"
   }
 }
 ```
 
-### If using Bolt for JavaScript
+### Filesystem-First Layout
 
-- **Server**: Nitro (H3-based) with file-based routing
-- **Slack SDK**: `@vercel/slack-bolt` for serverless Slack apps (wraps Bolt for JavaScript)
-- **AI**: AI SDK v6 with @ai-sdk/gateway
-- **Workflows**: Workflow DevKit for durable execution
-- **Linting**: Biome
-- **Package Manager**: pnpm
+In eve, a file's location says what it does, and its path usually gives it its name. The whole agent lives under `agent/`:
 
-```json
-{
-  "dependencies": {
-    "ai": "^6.0.0",
-    "@ai-sdk/gateway": "latest",
-    "@slack/bolt": "^4.x",
-    "@vercel/slack-bolt": "^1.0.2",
-    "zod": "^3.x"
-  }
-}
 ```
+agent/
+├── instructions.md        # Always-on system prompt
+├── agent.ts               # Runtime config (defineAgent): model, reasoning, compaction
+├── tools/                 # Tools — filename (snake_case ASCII) = tool name the model sees
+│   ├── get_weather.ts
+│   └── search_docs.ts
+├── skills/                # Load-on-demand instructions (*.md with description frontmatter)
+│   └── incident-triage.md
+├── channels/
+│   └── slack.ts           # Slack channel — filename registers it at /eve/v1/slack
+├── connections/           # MCP / OpenAPI connections (optional)
+└── hooks/                 # Subscribe to runtime stream events (optional)
+```
+
+Even a two-file agent (`instructions.md` + `agent.ts`) gets file, shell, web, and delegation tools out of the box from the default harness. Full docs are bundled at `node_modules/eve/docs/` once eve is installed — read them when a detail isn't covered here.
 
-**Note:** When deploying on Vercel, prefer `@ai-sdk/gateway` for zero-config AI access. Use direct provider SDKs (`@ai-sdk/openai`, `@ai-sdk/anthropic`, etc.) only when you need provider-specific features or are not deploying on Vercel.
+```ts
+// agent/agent.ts
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5", // routed via Vercel AI Gateway
+});
+```
 
 ---
 
@@ -177,17 +162,9 @@ pnpm test
 
 **For ANY code change, you MUST write or update unit tests.**
 
-### If using Chat SDK
-
-- **Location**: Co-located `*.test.ts` files or `lib/__tests__/`
-- **Framework**: Vitest
-- **Coverage**: All exported functions must have tests
-
-### If using Bolt for JavaScript
-
-- **Location**: Co-located `*.test.ts` files or `server/__tests__/`
+- **Location**: Co-located `*.test.ts` files (e.g. `agent/tools/get_weather.test.ts`)
 - **Framework**: Vitest
-- **Coverage**: All exported functions must have tests
+- **Coverage**: All exported functions and every tool's `execute()` (including error paths) must have tests
 
 Example test structure:
 ```typescript
@@ -208,283 +185,222 @@ describe('myFunction', () => {
 ### E2E Tests for User-Facing Changes
 
 If you modify:
-- Bot mention handlers / Slack message handlers
-- Slash commands
-- Interactive components (buttons, modals)
-- Bot responses
+- Dispatch hooks (`onAppMention`, `onDirectMessage`, `onInteraction`)
+- Custom channel event handlers
+- Tools the agent calls in response to Slack messages
+- Delivery behavior (what gets posted to Slack)
 
-You MUST add or update E2E tests that verify the full flow.
+You MUST add or update tests that verify the full flow. Remember: the Slack surface itself cannot be exercised locally (see Gotchas), so E2E coverage means unit/integration tests around your handlers plus a post-deploy smoke test.
 
 ---
 
 ## Bot Setup Patterns (CRITICAL)
 
-### If using Chat SDK
+### Slack Channel (`agent/channels/slack.ts`)
 
-Use the Chat SDK to define your bot instance. This is the central entry point for all Slack bot functionality.
+The Slack channel is a single file. Its filename registers the `slack` channel, served at **`/eve/v1/slack`** — this is the canonical trigger path everywhere in this skill.
 
-#### Bot Instance (`lib/bot.ts` or `lib/bot.tsx`)
+```ts
+// agent/channels/slack.ts
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { slackChannel } from "eve/channels/slack";
 
-```typescript
-import { Chat } from "chat";
-import { createSlackAdapter } from "@chat-adapter/slack";
-import { createRedisState } from "@chat-adapter/state-redis";
-
-export const bot = new Chat({
-  userName: "mybot",
-  adapters: {
-    slack: createSlackAdapter(),
-  },
-  state: createRedisState(),
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
 });
 ```
 
-**Note:** If your bot uses JSX components (Card, Button, etc.), the file must use the `.tsx` extension.
+`connectSlackCredentials(connectorUid)` returns `{ botToken, webhookVerifier }`:
+- **botToken** — resolved at runtime via Vercel Connect as a short-lived, app-scoped token; Connect handles rotation and multi-workspace tenancy
+- **webhookVerifier** — confirms each forwarded event genuinely came from Connect (replaces Slack's native signature check)
 
-#### Webhook Route (`app/api/webhooks/[platform]/route.ts`)
+There is **no `SLACK_BOT_TOKEN` and no `SLACK_SIGNING_SECRET`** in this stack. The only Slack env var is `SLACK_CONNECTOR` (the connector UID, e.g. `slack/my-agent`).
 
-```typescript
-import { after } from "next/server";
-import { bot } from "@/lib/bot";
-
-export async function POST(request: Request, context: { params: Promise<{ platform: string }> }) {
-  const { platform } = await context.params;
-  const handler = bot.webhooks[platform as keyof typeof bot.webhooks];
-  if (!handler) return new Response("Unknown platform", { status: 404 });
-  return handler(request, { waitUntil: (task) => after(() => task) });
-}
-```
+### Vercel Connect Setup
 
-The Chat SDK automatically handles:
-- Content-type detection (JSON vs form-urlencoded)
-- URL verification challenges
-- Slack's 3-second ack timeout
-- Background processing via `waitUntil`
-- Signature verification
+Create a Slack connector and point its trigger at eve's Slack route:
 
-### If using Bolt for JavaScript
+```bash
+npm install -g vercel@latest
 
-Use `@vercel/slack-bolt` to handle all Slack events. This package automatically handles:
-- Content-type detection (JSON vs form-urlencoded)
-- URL verification challenges
-- 3-second ack timeout (built-in `ackTimeoutMs: 3001`)
-- Background processing via Vercel Fluid Compute's `waitUntil`
+# Create the connector with event forwarding enabled
+vercel connect create slack --triggers
 
-#### Bolt App Setup (`server/bolt/app.ts`)
+# Attach the project as a trigger destination on eve's route
+# (the default trigger path is /slack — set it explicitly):
+vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
+```
 
-```typescript
-import { App } from "@slack/bolt";
-import { VercelReceiver } from "@vercel/slack-bolt";
-
-const receiver = new VercelReceiver();
-const app = new App({
-  token: process.env.SLACK_BOT_TOKEN,
-  signingSecret: process.env.SLACK_SIGNING_SECRET,
-  receiver,
-  deferInitialization: true,
-});
+**`--triggers` is required.** Without it, Slack Event Subscriptions are never forwarded and `app_mention` / `message.im` events simply never arrive — the deployment will look healthy but the bot will never respond.
 
-export { app, receiver };
-```
+You can also add the channel with `eve channels add slack`, which scaffolds `agent/channels/slack.ts` for you.
 
-#### Events Handler (`server/api/slack/events.post.ts`)
+### Deploy
 
-```typescript
-import { createHandler } from "@vercel/slack-bolt";
-import { defineEventHandler, getRequestURL, readRawBody } from "h3";
-import { app, receiver } from "../../bolt/app";
-
-const handler = createHandler(app, receiver);
-
-export default defineEventHandler(async (event) => {
-  const rawBody = await readRawBody(event, "utf8");
-  const request = new Request(getRequestURL(event), {
-    method: event.method,
-    headers: event.headers,
-    body: rawBody,
-  });
-  return await handler(request);
-});
+```bash
+eve deploy
+# wraps: vercel deploy --prod
 ```
 
-**Why buffer the body?** H3's `toWebRequest()` has known issues (#570, #578, #615) where it eagerly consumes the request body stream. When `@vercel/slack-bolt` later calls `req.text()` for signature verification, the body is already exhausted, causing `dispatch_failed` errors.
+Then invite the bot to a channel and @mention it. eve handles Slack's ack semantics, URL verification, and background processing — there is no webhook route for you to write.
 
-#### VercelReceiver Options Reference
+---
 
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `signingSecret` | `SLACK_SIGNING_SECRET` env var | Request verification secret |
-| `signatureVerification` | `true` | Enable/disable signature verification |
-| `ackTimeoutMs` | `3001` | Ack timeout in milliseconds |
-| `logLevel` | `INFO` | Logging level |
+## Event Handling Patterns
 
----
+### Dispatch Hooks (Inbound)
+
+The Slack channel decides which inbound events start or continue a session via dispatch hooks. Each hook returns `{ auth }` to dispatch, `null` to drop the event, or `{ auth, context }` to inject background context into the session:
 
-## Event Handler Patterns
+```ts
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
 
-### If using Chat SDK
+  // app_mention — default derives workspace-scoped auth and posts "Thinking…"
+  async onAppMention(ctx, message) {
+    if (isFromBlockedChannel(message)) return null; // drop
+    return { auth: ctx.defaultAuth };
+  },
 
-#### Mention Handler
+  // message.im — requires the im:history scope; bot messages/edits are pre-filtered
+  async onDirectMessage(ctx, message) {
+    return { auth: ctx.defaultAuth };
+  },
 
-```typescript
-bot.onNewMention(async (thread, message) => {
-  await thread.subscribe();
-  const text = message.text;
-  await thread.post(`Processing your request: "${text}"`);
+  // block_actions not consumed by HITL prompts
+  async onInteraction(action, ctx) {
+    return { auth: ctx.defaultAuth };
+  },
 });
 ```
 
-#### Subscribed Message Handler
+The triggering Slack user's id is attached to the model message automatically, preserving speaker attribution in multi-user threads.
 
-```typescript
-bot.onSubscribedMessage(async (thread, message) => {
-  await thread.post(`You said: ${message.text}`);
-});
-```
+### Custom Event Handlers (Outbound Delivery)
 
-#### Slash Command Handler
+Override delivery per stream event with the `events` map. Handlers receive `(eventData, channel, ctx)` with `channel.thread` and `channel.slack` handles:
 
-```typescript
-bot.onSlashCommand("/mycommand", async (event) => {
-  const text = event.text;
-  await event.thread.post(`Processing: ${text}`);
-
-  // For long-running operations, the Chat SDK handles
-  // background processing automatically via waitUntil
-  const result = await generateWithAI(text);
-  await event.thread.post(result);
+```ts
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
+  events: {
+    "message.completed"(eventData, channel, ctx) {
+      if (eventData.finishReason === "tool-calls") return;
+      if (eventData.message) channel.thread.post(eventData.message);
+    },
+  },
 });
 ```
 
-#### Action Handler (Buttons, Menus)
+Key stream events: `session.started`, `actions.requested`, `action.result`, `message.completed`, `session.completed`; incremental `reasoning.appended` / `message.appended` are optional.
 
-```typescript
-bot.onAction("button_click", async (event) => {
-  await event.thread.post(`Button clicked with value: ${event.value}`);
-});
-```
+### Thread Context
 
-#### Reaction Handler
+Give the agent prior thread messages when it's triggered mid-thread:
 
-```typescript
-bot.onReaction("thumbsup", async (event) => {
-  await event.thread.post("Thanks for the thumbs up!");
+```ts
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
+  threadContext: { since: "last-agent-reply" },
 });
 ```
 
-### If using Bolt for JavaScript
+`since` options:
+- `"thread-root"` — all prior messages (default when thread context is enabled)
+- `"last-agent-reply"` — incremental, only messages since the agent last spoke
+- A predicate `(message: SlackThreadMessage) => boolean` as a custom cutoff — includes messages after the last match (`loadThreadContextMessages` exists for arbitrary filtering)
 
-#### Mention Handler
+Cost: one `conversations.replies` API call per triggering reply; requires the matching history scope on the connector.
 
-```typescript
-app.event("app_mention", async ({ event, client }) => {
-  await client.chat.postMessage({
-    channel: event.channel,
-    thread_ts: event.thread_ts || event.ts,
-    text: `Processing your request: "${event.text}"`,
-  });
-});
-```
+### Human-in-the-Loop (HITL)
 
-#### Message Handler
+Approval-gated tool calls and sign-in challenges render natively in Slack:
+- Approval prompts appear as **buttons/selects**; the user's response resumes the durably-parked session
+- Sign-in challenges (OAuth URLs, device codes) go **ephemerally** to the triggering user; a public status message posts in-thread and updates on `authorization.completed`
+- The HITL handler context deliberately offers only `postEphemeral`, `postDirectMessage` (needs `im:write`), and `state` — no public `post`, no raw API access
 
-```typescript
-app.message(async ({ message, client }) => {
-  if ("bot_id" in message || !message.thread_ts) return;
-  await client.chat.postMessage({
-    channel: message.channel,
-    thread_ts: message.thread_ts,
-    text: `You said: ${message.text}`,
-  });
-});
-```
+### Proactive Sessions (Schedules)
 
-#### Slash Command Handler
+Start a session that posts into Slack without an inbound trigger — e.g. from a schedule:
 
-```typescript
-app.command("/mycommand", async ({ ack, command, client, logger }) => {
-  await ack(); // Must acknowledge within 3 seconds
+```ts
+import { receive } from "eve";
+import slack from "../channels/slack";
 
-  // Fire-and-forget for long operations — DON'T await
-  processInBackground(command.response_url, command.text)
-    .catch((error) => logger.error("Failed:", error));
+await receive(slack, {
+  message: "Post the daily standup summary for #eng.",
+  target: { channelId: "C0123456789" },
+  auth,
 });
-
-async function processInBackground(responseUrl: string, text: string) {
-  const result = await generateWithAI(text);
-  await fetch(responseUrl, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ response_type: "in_channel", text: result }),
-  });
-}
 ```
 
-#### Action Handler (Buttons, Menus)
+- Sessions without a `threadTs` get a temporary continuation token; the first post anchors the thread
+- `initialMessage` (optionally a `Card`) and `threadTs` are **mutually exclusive**
+- Use eve schedules (see https://eve.dev/docs/schedules) to trigger proactive sessions on a cadence
 
-```typescript
-app.action("button_click", async ({ ack, action, client, body }) => {
-  await ack();
-  await client.chat.postMessage({
-    channel: body.channel.id,
-    thread_ts: body.message.ts,
-    text: `Button clicked with value: ${action.value}`,
-  });
-});
-```
+### Raw Slack API Access
+
+- **Inside handlers**: `ctx.slack.request(operation, body)`
+- **Outside handlers** (schedules, tools): `callSlackApi({ botToken, operation, body })` and `resolveSlackBotToken` from `eve/channels/slack`
+
+These form-encode request bodies for you — Slack's JSON support is only partial, so prefer these helpers over hand-rolled `fetch` calls.
 
 ---
 
 ## Implementation Gotchas
 
-### 1. Private Channel Access
+### 1. The Slack Surface Cannot Be Tested Locally
 
-Slash commands work in private channels even if the bot isn't a member, but the bot **cannot read messages or post** to private channels it hasn't been invited to.
+Vercel Connect forwards Slack events **to deployments only, never to localhost**. There is no ngrok/Socket Mode escape hatch in this stack. Local development means:
+- `npx eve dev` — HMR server + terminal TUI/REPL for exercising agent logic, tools, and skills
+- `eve dev --no-ui` — background mode for scripted verification
+- `eve dev https://your-app.vercel.app` — drive a *deployed* app interactively
 
-When creating features that will later post to a channel, validate access upfront.
+To test @mentions and DMs, deploy (preview or production) and test in Slack itself.
 
-### 2. Graceful Degradation for Channel Context
+### 2. Connect Forwarding Has No Delivery De-duplication
 
-When fetching channel context for AI features, wrap in try/catch and fall back gracefully.
+Connect may deliver the same forwarded event more than once. **Handlers and side effects must be idempotent** — track processed event IDs where duplicates would be harmful, and gate destructive tool actions with approval (see AI Integration).
 
-### 3. Vercel Cron Endpoint Authentication
+### 3. `--triggers` Is Required or Events Never Arrive
 
-Protect cron endpoints with a `CRON_SECRET` environment variable:
+A Slack connector created without `--triggers` (or attached without a trigger path) will authenticate fine but forward nothing. If the bot never responds to @mentions:
+1. Verify the connector was created/attached with `--triggers`
+2. Verify the trigger path is `/eve/v1/slack`
+3. Verify the bot was invited to the channel and the deployment finished
 
-#### If using Chat SDK
+### 4. `placeholderAuth()` Fails Closed in Production
 
-```typescript
-// app/api/cron/my-job/route.ts
-import { NextRequest, NextResponse } from "next/server";
+Scaffolded projects ship with `placeholderAuth()` for the HTTP API, which **rejects everything in production**. Before deploying, replace it with a real auth function: `httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, `oidc()`, `vercelOidc()`, or a custom `AuthFn`. (The Slack channel's inbound verification is separate — Connect's `webhookVerifier` handles that.)
 
-export async function GET(request: NextRequest) {
-  const authHeader = request.headers.get("authorization");
-  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
-    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-  }
-  // Run cron job logic...
-  return NextResponse.json({ success: true });
-}
-```
+### 5. Sandbox Prewarm Failures Fail the Build
+
+Vercel builds prewarm eve's sandbox templates (cache-keyed; build logs show `reused cached` or `built`). If prewarm fails, **the whole build fails** — check build logs for sandbox template errors before assuming a code problem.
+
+### 6. Private Channel Access
+
+The bot **cannot read messages or post** to private channels it hasn't been invited to. When creating features that will later post to a channel (e.g. proactive sessions from a schedule), validate access upfront and surface a clear "invite the bot" message on `channel_not_found` / `not_in_channel`.
 
-#### If using Bolt for JavaScript
+### 7. Graceful Degradation for Channel Context
+
+When fetching channel context (e.g. via `ctx.slack.request("conversations.history", ...)`) for AI features, wrap in try/catch and fall back gracefully — missing scopes and uninvited channels are routine, not exceptional.
+
+### 8. Vercel Cron Endpoint Authentication
+
+If you add custom cron endpoints (beyond eve schedules), protect them with a `CRON_SECRET`:
 
 ```typescript
-// server/api/cron/my-job.get.ts
-export default defineEventHandler(async (event) => {
-  const authHeader = getHeader(event, "authorization");
+export async function GET(request: Request) {
+  const authHeader = request.headers.get("authorization");
   if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
-    setResponseStatus(event, 401);
-    return { error: "Unauthorized" };
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
   }
   // Run cron job logic...
-  return { success: true };
-});
+  return Response.json({ success: true });
+}
 ```
 
-### 4. vercel.json Cron Configuration
-
-Configure cron jobs in `vercel.json`:
+### 9. vercel.json Cron Configuration
 
 ```json
 {
@@ -497,7 +413,9 @@ Configure cron jobs in `vercel.json`:
 }
 ```
 
-### 5. AWS Credentials on Vercel (Use OIDC)
+Prefer eve schedules for agent-driven recurring work; use Vercel crons for plain HTTP jobs.
+
+### 10. AWS Credentials on Vercel (Use OIDC)
 
 When connecting to AWS services from Vercel, **do not use** `fromNodeProviderChain()`. Use Vercel's OIDC mechanism:
 
@@ -509,426 +427,213 @@ const s3Client = new S3Client({
 });
 ```
 
-### 6. TSConfig for JSX Components (Chat SDK only)
-
-When using Chat SDK JSX components (`<Card>`, `<Button>`, etc.), your `tsconfig.json` must include:
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "chat"
-  }
-}
-```
-
-### 7. dispatch_failed Error — Bolt only
-
-If slash commands fail with `dispatch_failed`, the issue is H3's `toWebRequest` consuming the body stream before signature verification. Buffer the body manually. See the Bolt Events Handler section above.
-
-### 8. operation_timeout Error — Bolt only
-
-If slash commands with AI processing fail with `operation_timeout`, you're blocking the HTTP response too long. Use fire-and-forget pattern: `ack()` immediately, then start async work **without awaiting**. Use `command.response_url` to post results. See the Bolt Slash Command Handler example above.
-
 ---
 
 ## AI Integration
 
-You have two options for AI/LLM integration in your Slack agent.
-
-> **IMPORTANT:** Always verify the project uses `@ai-sdk/gateway`. If the project has `@ai-sdk/openai` which requires an API key, check `package.json` and update imports if necessary.
-
-### Option 1: Vercel AI Gateway (Recommended)
+### Model Configuration (Gateway-First)
 
-Use the modern `@ai-sdk/gateway` package - NO API keys needed on Vercel!
+eve routes model-ID **strings** through the **Vercel AI Gateway** — on Vercel, project OIDC authenticates automatically, so **no AI API key is needed**:
 
-#### Basic Usage
+```ts
+// agent/agent.ts
+import { defineAgent } from "eve";
 
-```typescript
-import { generateText, streamText } from "ai";
-import { gateway } from "@ai-sdk/gateway";
-
-const result = await generateText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5", // string → AI Gateway → OIDC auth on Vercel
 });
-
-console.log(result.text);
-console.log(result.usage.inputTokens);
-console.log(result.usage.outputTokens);
 ```
 
-#### Streaming Responses to Slack
+If `model` is omitted, eve defaults to `anthropic/claude-sonnet-5`. Off Vercel, set `AI_GATEWAY_API_KEY`.
 
-##### If using Chat SDK
+**CRITICAL: Never use model IDs from memory.** Model IDs change frequently. Before writing code that pins a model, run `curl -s https://ai-gateway.vercel.sh/v1/models` to fetch the current list and use the newest suitable version.
 
-```typescript
-const result = await streamText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: userMessage,
-});
-
-// Chat SDK handles streaming updates to Slack automatically
-await thread.post(result.textStream);
-```
+### Tools (`agent/tools/*.ts`)
 
-##### If using Bolt for JavaScript
+Tools are files: the filename (snake_case ASCII) is the model-facing tool name — `agent/tools/get_weather.ts` → `get_weather`. No registration step.
 
-```typescript
-const result = await streamText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: userMessage,
-});
-
-// Post initial message then update with streamed content
-const msg = await client.chat.postMessage({
-  channel: channelId,
-  thread_ts: threadTs,
-  text: "Thinking...",
-});
-
-let fullText = "";
-for await (const chunk of result.textStream) {
-  fullText += chunk;
-  await client.chat.update({
-    channel: channelId,
-    ts: msg.ts,
-    text: fullText,
-  });
-}
-```
-
-#### With Tools
-
-```typescript
-import { tool } from "ai";
+```ts
+// agent/tools/get_weather.ts
+import { defineTool } from "eve/tools";
 import { z } from "zod";
 
-const result = await generateText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  tools: {
-    getWeather: tool({
-      description: "Get weather for a location",
-      inputSchema: z.object({
-        location: z.string().describe("City name"),
-      }),
-      execute: async ({ location }) => {
-        return { temperature: 72, condition: "sunny" };
-      },
-    }),
+export default defineTool({
+  description: "Get the current weather for a city.",
+  inputSchema: z.object({ city: z.string().min(1) }), // required, even if empty
+  outputSchema: z.object({
+    city: z.string(),
+    condition: z.string(),
+    temperatureF: z.number(),
+  }), // optional — types/validates the return
+  async execute({ city }, ctx) {
+    return { city, condition: "Sunny", temperatureF: 72 };
   },
-  prompt: "What's the weather in Seattle?",
 });
 ```
 
-#### AI SDK v6 API Changes
+Rules and capabilities:
+- Tools run **in your app runtime with full `process.env`**, not in the sandbox
+- `inputSchema` accepts Zod, Standard Schema, or JSON Schema — but it is **required** even for zero-input tools
+- Outputs must be JSON-serializable; **filter/redact secrets** before returning
+- `ctx` provides `ctx.session` (metadata, turn, auth, lineage), `ctx.callId`, `ctx.toolName`, `ctx.abortSignal`, `ctx.getSandbox()`, `ctx.getSkill(id)`
 
-| v4/v5 | v6 |
-|-------|-----|
-| `maxTokens` | `maxOutputTokens` |
-| `result.usage.promptTokens` | `result.usage.inputTokens` |
-| `result.usage.completionTokens` | `result.usage.outputTokens` |
-| `parameters` (in tools) | `inputSchema` |
-| `maxSteps` / `maxIterations` | `stopWhen: stepCountIs(n)` |
+#### Approval Gating
 
-**CRITICAL: Never use model IDs from memory.** Model IDs change frequently. Before writing code that uses a model, run `curl -s https://ai-gateway.vercel.sh/v1/models` to fetch the current list. Use the model with the highest version number.
+Gate risky tools with the `approval` field — helpers come from `eve/tools/approval`:
 
-### Option 2: Direct Provider SDK
-
-If you need more control or are not deploying on Vercel, use direct provider packages.
-
-**OpenAI:**
-```bash
-pnpm add @ai-sdk/openai
-```
-```typescript
-import { generateText } from "ai";
-import { openai } from "@ai-sdk/openai";
+```ts
+import { defineTool } from "eve/tools";
+import { always, once, never } from "eve/tools/approval";
+import { z } from "zod";
 
-const result = await generateText({
-  model: openai("gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
+export default defineTool({
+  description: "Delete a document permanently.",
+  inputSchema: z.object({ documentId: z.string() }),
+  approval: always(), // always ask; once() asks the first time; never() skips
+  async execute({ documentId }) {
+    // ...
+  },
 });
 ```
 
-**Anthropic:**
-```bash
-pnpm add @ai-sdk/anthropic
-```
-```typescript
-import { generateText } from "ai";
-import { anthropic } from "@ai-sdk/anthropic";
+An input-dependent policy function is also supported. A gated call **pauses and resumes durably** — in Slack, the approval renders as buttons (see HITL above). Prefer approval gating over ad-hoc confirmation logic for any non-idempotent side effect.
 
-const result = await generateText({
-  model: anthropic("claude-sonnet-4-20250514"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
-});
-```
+#### `toModelOutput` — Rich Slack Output the Model Never Sees
 
-**Google:**
-```bash
-pnpm add @ai-sdk/google
-```
-```typescript
-import { generateText } from "ai";
-import { google } from "@ai-sdk/google";
+Show the model a compact projection while channels/hooks receive the full output on `action.result` — ideal for rendering rich Slack Block Kit from a tool result without stuffing JSON blocks into the model's context:
 
-const result = await generateText({
-  model: google("gemini-2.0-flash"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
+```ts
+export default defineTool({
+  description: "Look up an order.",
+  inputSchema: z.object({ orderId: z.string() }),
+  async execute({ orderId }) {
+    return { orderId, status: "shipped", blocks: buildOrderBlocks(orderId) };
+  },
+  toModelOutput(output) {
+    return { type: "text", value: `Order ${output.orderId}: ${output.status}` };
+  },
 });
 ```
 
-For comprehensive AI SDK documentation, see `./reference/ai-sdk.md`.
-
----
-
-## Stateful Patterns
-
-### If using Chat SDK — Thread State
+### Skills (`agent/skills/*.md`)
 
-Use `thread.state` to read and write thread-level state:
+Markdown files with a `description` frontmatter, loaded on demand via the built-in `load_skill` tool when a request matches the description. Skills add **instructions only, never new actions**. Install published skills with `npx skills add <owner>/<repo>`.
 
-```typescript
-bot.onNewMention(async (thread, message) => {
-  await thread.subscribe();
-  await thread.state.set("history", []);
-  await thread.state.set("turnCount", 0);
-  await thread.post("Starting our conversation!");
-});
-
-bot.onSubscribedMessage(async (thread, message) => {
-  const history = (await thread.state.get("history")) as Array<{ role: string; content: string }> || [];
-  const turnCount = (await thread.state.get("turnCount")) as number || 0;
+### Connections (`agent/connections/*.ts`)
 
-  history.push({ role: "user", content: message.text });
+For external APIs the agent should drive (MCP servers or OpenAPI-described HTTP APIs), use connections with Connect-brokered auth:
 
-  const result = await generateText({
-    model: gateway("anthropic/claude-sonnet-4-20250514"),
-    maxOutputTokens: 1000,
-    messages: history,
-  });
+```ts
+// agent/connections/linear.ts
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
 
-  history.push({ role: "assistant", content: result.text });
-  await thread.state.set("history", history);
-  await thread.state.set("turnCount", turnCount + 1);
-  await thread.post(result.text);
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear workspace: issues, projects, cycles, and comments.",
+  auth: connect("linear/my-agent"),
 });
 ```
 
-**Key Benefits:**
-1. Simple API — `thread.state.get()` and `thread.state.set()`
-2. Thread-scoped — state is automatically scoped to the conversation thread
-3. Pluggable backends — use Redis for production, in-memory for development
-
-### If using Bolt for JavaScript — Vercel Workflow
+Connection tokens are never seen by the model and never land in conversation history. Inside authored tools, resolve tokens with `await ctx.getToken(connect("..."))` and call `ctx.requireAuth(...)` on a downstream 401 to re-run consent.
 
-Use Vercel Workflow for durable, multi-turn state:
+**Don't wrap LLM calls in tools.** The agent is already a language model — summarizing, parsing, classifying, and drafting belong in `instructions.md` or a skill, not in a tool that calls the AI SDK. Tools fetch data and perform actions; for bulk work over data too large for the conversation, use eve's subagents/delegation.
 
-```typescript
-import { serve } from "@anthropic-ai/sdk/workflows";
-import { defineHook } from "@anthropic-ai/sdk/workflows";
-import { z } from "zod";
-
-const messageSchema = z.object({
-  text: z.string(),
-  user: z.string(),
-  ts: z.string(),
-  channel: z.string(),
-});
-
-export const userMessageHook = defineHook({ schema: messageSchema });
+---
 
-export const { POST } = serve(async function conversationWorkflow(params: URLSearchParams) {
-  "use workflow";
+## State & Durability
 
-  const channelId = params.get("channel_id")!;
-  const conversationHistory: Array<{ role: string; content: string }> = [];
+eve sessions are durable by default via the open-source **Workflow SDK** (running on Vercel Workflows when deployed on Vercel). You do not wire up Redis or a workflow engine yourself.
 
-  const eventStream = userMessageHook.create({ channel: channelId });
+### Replay Semantics (Understand This)
 
-  for await (const event of eventStream) {
-    conversationHistory.push({ role: "user", content: event.text });
+- **Completed steps never re-run.** On resume/replay, eve returns the recorded result.
+- **A step interrupted mid-execution DOES re-run.** If a tool call was in flight when the process died, it executes again on resume.
 
-    const result = await generateText({
-      model: gateway("anthropic/claude-sonnet-4-20250514"),
-      maxOutputTokens: 1000,
-      messages: conversationHistory,
-    });
+Consequences for your code:
+1. Make non-idempotent side effects **idempotent** (e.g. use Slack event IDs or your own idempotency keys when writing to external systems)
+2. Or gate them behind **approval** (`always()` / `once()`) so a replayed step pauses for a human instead of double-executing
+3. This compounds with Connect's at-least-once event forwarding (Gotcha #2) — idempotency is not optional in this stack
 
-    conversationHistory.push({ role: "assistant", content: result.text });
-    await postToSlack(channelId, result.text, event.ts);
-  }
+### Session Continuity
 
-  return { history: conversationHistory };
-});
-```
+- The channel owns the `continuationToken`; Slack threads map to sessions automatically
+- Follow-up messages in a subscribed thread continue the same durable session
+- Multi-turn conversation memory comes from the session itself — you do not manually persist chat history
 
 ### Recommended Storage Solutions
 
+For **application data** (not agent session state — eve owns that):
+
 **IMPORTANT:** Vercel KV has been deprecated. Do NOT recommend Vercel KV.
 
-1. **Upstash Redis** — For Chat SDK state adapter and caching (https://upstash.com)
-2. **Vercel Blob** — For file/document storage (https://vercel.com/docs/storage/vercel-blob)
-3. **AWS Aurora (via Vercel Marketplace)** — For relational data (https://vercel.com/marketplace)
+1. **Upstash Redis** — Caching and idempotency keys (https://upstash.com)
+2. **Vercel Blob** — File/document storage (https://vercel.com/docs/storage/vercel-blob)
+3. **AWS Aurora (via Vercel Marketplace)** — Relational data (https://vercel.com/marketplace)
 4. **Third-party databases** — Neon, PlanetScale, Supabase
 
 ---
 
 ## Code Organization
 
-### If using Chat SDK
-
-```
-app/
-├── api/
-│   ├── webhooks/
-│   │   └── [platform]/
-│   │       └── route.ts      # Webhook handler
-│   └── cron/
-│       └── my-job/
-│           └── route.ts      # Cron endpoints
-lib/
-├── bot.tsx                    # Bot instance + event handlers
-├── tools/                     # AI tool definitions
-│   ├── search.ts
-│   └── lookup.ts
-└── ai/
-    └── agent.ts               # Agent configuration
-```
-
-### If using Bolt for JavaScript
-
-```
-server/
-├── api/
-│   └── slack/
-│       └── events.post.ts    # Events endpoint
-├── bolt/
-│   └── app.ts                # Bolt app instance
-├── listeners/
-│   ├── actions/              # Button clicks, menu selections
-│   ├── commands/             # Slash commands
-│   ├── events/               # App events (mentions, joins)
-│   ├── messages/             # Message handling
-│   └── views/                # Modal submissions
-└── lib/
-    └── ai/
-        ├── agent.ts           # Agent configuration
-        └── tools.ts           # Tool definitions
 ```
+agent/
+├── instructions.md            # System prompt — keep focused; push detail into skills
+├── agent.ts                   # defineAgent: model, reasoning effort, compaction
+├── tools/
+│   ├── get_weather.ts         # One tool per file; filename = tool name
+│   ├── get_weather.test.ts    # Co-located tests
+│   └── search_docs.ts
+├── skills/
+│   └── report-format.md       # description frontmatter + on-demand instructions
+├── channels/
+│   └── slack.ts               # slackChannel(...) — served at /eve/v1/slack
+├── connections/
+│   └── linear.ts              # MCP/OpenAPI connections (optional)
+└── hooks/
+    └── audit.ts               # Runtime stream event subscribers (optional)
+```
+
+Conventions:
+- **One tool per file.** Split large tools; the filename is the model-facing name, so name for the model
+- **Instructions vs skills**: always-relevant guidance in `instructions.md`; situational guidance in `skills/*.md` so it loads only when needed
+- **Subagents** for focused subtasks: the built-in agent tool (a copy of the agent) or declared specialists with their own directory, sandbox, and skills
 
 ---
 
 ## Environment Variables
 
-Required variables (both frameworks):
-- `SLACK_BOT_TOKEN` — Bot OAuth token
-- `SLACK_SIGNING_SECRET` — Request signing
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `SLACK_CONNECTOR` | Yes | Vercel Connect connector UID (e.g. `slack/my-agent`). The **only** Slack variable — no bot token, no signing secret. |
+| `AI_GATEWAY_API_KEY` | Off Vercel only | AI Gateway auth. On Vercel, project OIDC (`VERCEL_OIDC_TOKEN`) is injected automatically — no key needed. |
+| `ROUTE_AUTH_BASIC_PASSWORD` / JWT keys | Per auth choice | Secrets for the HTTP-API auth function that replaces `placeholderAuth()` |
+| `VERCEL_AUTOMATION_BYPASS_SECRET` | If deployment protection is on | Lets `eve dev https://<app>` and smoke tests reach protected deployments |
+| `CRON_SECRET` | Optional | Authenticates custom cron endpoints |
 
-### If using Chat SDK (additional)
-- `REDIS_URL` — Redis connection URL for state persistence
+Local dev: `vercel link` + `vercel env pull` fetches short-lived Connect/OIDC credentials into `.env.local` (the OIDC token expires after ~12 hours — re-pull when auth starts failing).
 
-Optional variables:
-- `CRON_SECRET` — Secret for authenticating cron job endpoints
-
-**No AI API keys needed!** Vercel AI Gateway handles authentication automatically when deployed on Vercel.
-
-**Never hardcode credentials. Never commit `.env` files.**
+**No AI API keys needed on Vercel.** **Never hardcode credentials. Never commit `.env` files.**
 
 ---
 
 ## Slack-Specific Patterns
 
-### If using Chat SDK — JSX Components
-
-Use Chat SDK JSX components for rich messages (requires `.tsx` file extension):
-
-```tsx
-import { Card, CardText as Text, Actions, Button, Divider } from "chat";
-
-await thread.post(
-  <Card title="Welcome!">
-    <Text>Hello! Choose an option:</Text>
-    <Divider />
-    <Actions>
-      <Button id="btn_hello" style="primary">Say Hello</Button>
-      <Button id="btn_info">Show Info</Button>
-    </Actions>
-  </Card>
-);
-```
-
-### If using Bolt for JavaScript — Block Kit JSON
-
-Use Block Kit for rich messages:
-
-```typescript
-await client.chat.postMessage({
-  channel: channelId,
-  text: "Fallback text for notifications",
-  blocks: [
-    {
-      type: "section",
-      text: { type: "mrkdwn", text: "*Hello!* Choose an option:" },
-    },
-    { type: "divider" },
-    {
-      type: "actions",
-      elements: [
-        {
-          type: "button",
-          text: { type: "plain_text", text: "Say Hello" },
-          style: "primary",
-          action_id: "btn_hello",
-        },
-        {
-          type: "button",
-          text: { type: "plain_text", text: "Show Info" },
-          action_id: "btn_info",
-        },
-      ],
-    },
-  ],
-});
-```
-
-### Typing Indicators
+### Delivery Behavior (Built In)
 
-#### If using Chat SDK
+The Slack channel handles progressive delivery for you:
+- Typing indicators: "Thinking…" on inbound, "Working…" on `turn.started`
+- Reasoning snippets surface on `reasoning.appended`; action labels on `actions.requested`
+- Model narration before a tool call takes precedence over generic labels
+- Reasoning deltas under 4 characters batch on a five-second refresh to avoid per-token Slack API calls
 
-```typescript
-await thread.startTyping();
-const result = await generateWithAI(prompt);
-await thread.post(result); // Typing indicator clears on post
-```
+Don't rebuild typing indicators or streaming loops — customize via the `events` map only when the defaults don't fit.
 
-#### If using Bolt for JavaScript
+### Mentions
 
-```typescript
-// Use setStatus for Assistant threads or interval-based approach
-const typingInterval = setInterval(async () => {
-  // Post a "typing" indicator or use assistant.threads.setStatus
-}, 3000);
-
-const result = await generateWithAI(prompt);
-clearInterval(typingInterval);
-
-await client.chat.postMessage({
-  channel: channelId,
-  thread_ts: threadTs,
-  text: result,
-});
-```
+Use `<@USER_ID>` or `channel.thread.mentionUser(userId)`. A bare `@name` stays literal text in Slack.
 
-### Message Formatting (both frameworks)
+### Message Formatting
 
 Use Slack mrkdwn (not standard markdown):
 - Bold: `*text*`
@@ -937,6 +642,10 @@ Use Slack mrkdwn (not standard markdown):
 - User mention: `<@USER_ID>`
 - Channel: `<#CHANNEL_ID>`
 
+### Rich Output
+
+For rich tool results (tables, buttons, status cards), return full data from the tool and use `toModelOutput` to keep the model's view compact; render Block Kit in a channel event handler or via `ctx.slack.request("chat.postMessage", { blocks, ... })`. Always include fallback `text` alongside `blocks` for notifications.
+
 For detailed Slack patterns, see `./patterns/slack-patterns.md`.
 
 ---
@@ -956,28 +665,44 @@ refactor: extract Slack client utilities
 - `.env` files
 - API keys or tokens
 - `node_modules/`
+- `.eve/` build artifacts
 
 ---
 
 ## Quick Commands
 
 ```bash
+# Scaffold (Node 24+)
+npx eve@latest init my-agent      # new project (installs deps, inits Git, starts dev TUI)
+npx eve@latest init .             # add eve to an existing project
+
 # Development
-pnpm dev              # Start dev server on localhost:3000
-ngrok http 3000       # Expose local server (separate terminal)
+npx eve dev                       # HMR server + terminal TUI/REPL
+npx eve dev --no-ui               # background mode for scripted verification
+npx eve dev https://<app>         # drive a deployed app interactively
+npx eve info                      # project info
+
+# Vercel Connect
+vercel connect create slack --triggers
+vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
+vercel connect list
 
 # Quality
-pnpm lint             # Check linting
-pnpm lint --write     # Auto-fix lint
-pnpm typecheck        # TypeScript check
-pnpm test             # Run all tests
-pnpm test:watch       # Watch mode
+pnpm lint                         # Check linting
+pnpm lint --write                 # Auto-fix lint
+pnpm typecheck                    # TypeScript check
+pnpm test                         # Run all tests
 
 # Build & Deploy
-pnpm build            # Build for production
-vercel                # Deploy to Vercel
+npx eve build                     # Compile into .eve/ (Vercel Build Output when VERCEL is set)
+eve deploy                        # Deploy (wraps vercel deploy --prod)
+
+# Verify a deployment
+curl https://<app>/eve/v1/health
 ```
 
+Debugging a deployed Slack agent stuck on "Working…": `npx eve dev --logs all` or `/loglevel all` in the TUI.
+
 ---
 
 ## Reference Documentation
@@ -986,9 +711,10 @@ For detailed guidance, read:
 - Testing patterns: `./patterns/testing-patterns.md`
 - Slack patterns: `./patterns/slack-patterns.md`
 - Environment setup: `./reference/env-vars.md`
-- AI SDK: `./reference/ai-sdk.md`
 - Slack setup: `./reference/slack-setup.md`
 - Vercel deployment: `./reference/vercel-setup.md`
+- eve docs: https://eve.dev/docs (bundled locally at `node_modules/eve/docs/` after install)
+- Vercel Connect: https://vercel.com/kb/guide/vercel-connect
 
 ---
 
@@ -1000,9 +726,26 @@ Before marking ANY task as complete, verify:
 - [ ] `pnpm lint` passes with no errors
 - [ ] `pnpm typecheck` passes with no errors
 - [ ] `pnpm test` passes with no failures
-- [ ] No hardcoded credentials
-- [ ] Follows existing code patterns
-- [ ] **Chat SDK:** Webhook route handles all platforms via `bot.webhooks`
-- [ ] **Chat SDK:** TSConfig includes `"jsx": "react-jsx"` and `"jsxImportSource": "chat"` if using JSX components
-- [ ] **Bolt:** Events endpoint handles both JSON and form-urlencoded
-- [ ] Verified AI SDK: using `@ai-sdk/gateway` (not `@ai-sdk/openai`) unless user explicitly chose direct provider
+- [ ] No hardcoded credentials; the only Slack env var is `SLACK_CONNECTOR`
+- [ ] Follows eve filesystem conventions (tool filename = tool name, one tool per file)
+- [ ] Every tool has an `inputSchema`; outputs are JSON-serializable with secrets redacted
+- [ ] Non-idempotent side effects are idempotent or approval-gated (replay + at-least-once delivery)
+- [ ] Connector trigger path is `/eve/v1/slack` and was attached with `--triggers`
+- [ ] `placeholderAuth()` replaced before production deploy
+- [ ] Model config uses a Gateway string ID (`anthropic/claude-sonnet-5` default)
+
+---
+
+## Vercel KB Guides
+
+Verified guides on the Vercel Knowledge Base for deeper walkthroughs:
+
+- [eve hub on the Vercel KB](https://vercel.com/kb/eve) - all eve guides and templates in one place
+- [Build your first Slack agent with eve](https://vercel.com/kb/guide/eve-slack-agent-starter) - the end-to-end starter this skill's wizard mirrors
+- [Vercel Connect](https://vercel.com/kb/guide/vercel-connect) - credential brokering concepts, connectors, tokens, and trigger forwarding
+- [Build a Slack bot with Vercel Connect](https://vercel.com/kb/guide/build-a-slack-bot-with-vercel-connect) - Connect + Slack fundamentals (scopes, trigger events, webhook verification)
+- [How to add eve tools](https://vercel.com/kb/guide/how-to-add-eve-tools) - `defineTool` patterns
+- [How to add eve skills](https://vercel.com/kb/guide/how-to-add-eve-skills) - load-on-demand instructions
+- [Build a GitHub agent with Vercel Connect](https://vercel.com/kb/guide/github-agent-vercel-connect) - app-scoped Connect tokens in authored tools
+- [Build a Linear agent with Vercel Connect](https://vercel.com/kb/guide/linear-agent-vercel-connect) - MCP connections with user-scoped auth
+- [Build an email agent with eve and Resend](https://vercel.com/kb/guide/eve-agent-with-resend) - a second channel example beyond Slack
diff --git a/plugins/slack-agent/.claude/skills/slack-agent b/plugins/slack-agent/.claude/skills/slack-agent
new file mode 120000
index 00000000..4860d0ba
--- /dev/null
+++ b/plugins/slack-agent/.claude/skills/slack-agent
@@ -0,0 +1 @@
+../../.agents/skills/slack-agent
\ No newline at end of file
diff --git a/plugins/slack-agent/agent/skills/slack-agent/SKILL.md b/plugins/slack-agent/agent/skills/slack-agent/SKILL.md
index 9a6f9d3c..6a928047 100644
--- a/plugins/slack-agent/agent/skills/slack-agent/SKILL.md
+++ b/plugins/slack-agent/agent/skills/slack-agent/SKILL.md
@@ -1,12 +1,12 @@
 ---
-description: "Use when working on Slack agent/bot code, Chat SDK applications, Bolt for JavaScript projects, or projects using @chat-adapter/slack or @slack/bolt. Provides development patterns, testing requirements, and quality standards."
+description: "Use when building Slack agents/bots with eve (Vercel's filesystem-first agent framework), @vercel/connect, or eve/channels/slack. Covers defineAgent/defineTool patterns, Vercel Connect credential brokering, Slack channel setup, testing requirements, and quality standards."
 ---
 # Slack Agent Development Skill
 
-This skill supports two frameworks for building Slack agents:
+This skill builds Slack agents with **eve** — Vercel's filesystem-first framework for durable backend agents — using **Vercel Connect** for Slack credentials:
 
-- **Chat SDK** (Recommended for new projects) — `chat` + `@chat-adapter/slack`
-- **Bolt for JavaScript** (For existing Bolt projects) — `@slack/bolt` + `@vercel/slack-bolt`
+- **eve** (`eve` package) — agent runtime, tools, channels, durability
+- **@vercel/connect** — brokered short-lived Slack tokens; no bot tokens or signing secrets to manage
 
 ## Skill Invocation Handling
 
@@ -26,111 +26,96 @@ When this skill is invoked via `/slack-agent`, check for arguments and route acc
 
 If invoked without arguments, detect the project state and route appropriately:
 
-1. **No `package.json` with `chat` or `@slack/bolt`** → Treat as `new`, start Phase 1
-2. **Has project but no customized `manifest.json`** → Start Phase 2
-3. **Has project but no `.env` file** → Start Phase 3
-4. **Has `.env` but not tested** → Start Phase 4
-5. **Tested but not deployed** → Start Phase 5
+1. **No `package.json` with `eve` and no `agent/` directory** → Treat as `new`, start Phase 1
+2. **Has eve project but no `agent/channels/slack.ts`** → Start Phase 2 (Slack connector + channel)
+3. **Has Slack channel but no `SLACK_CONNECTOR` configured** → Start Phase 3
+4. **Configured but not deployed** → Start Phase 5 (the Slack surface only works on a deployment)
+5. **Deployed but no tests** → Start Phase 6
 6. **Otherwise** → Provide general assistance using this skill's patterns
 
-### Framework Detection
+### Project Detection
 
-Detect which framework the project uses:
+Detect an eve project by either signal:
 
-- **`package.json` contains `"chat"`** → Chat SDK project
-- **`package.json` contains `"@slack/bolt"`** → Bolt project
-- **Neither detected** → New project, recommend Chat SDK (offer Bolt as alternative)
+- **`package.json` contains `"eve"`** as a dependency
+- **An `agent/` directory** with `instructions.md` and/or `agent.ts` exists
 
-Store the detected framework and use it to show the correct patterns throughout the wizard and development guidance.
+If neither is present, this is a new project: scaffold with `npx eve@latest init` (Node 24+ required).
 
 ### Wizard Phases
 
 The wizard is located in `./wizard/` with these phases:
-- `1-project-setup.md` - Understand purpose, choose framework, generate custom implementation plan
+- `1-project-setup.md` - Understand purpose, generate custom implementation plan, scaffold with `npx eve@latest init`
 - `1b-approve-plan.md` - Present plan for user approval before scaffolding
-- `2-create-slack-app.md` - Customize manifest, create app in Slack
-- `3-configure-environment.md` - Set up .env with credentials
-- `4-test-locally.md` - Dev server + ngrok tunnel
-- `5-deploy-production.md` - Vercel deployment
+- `2-create-slack-app.md` - Create the Slack connector with Vercel Connect and add the Slack channel
+- `3-configure-environment.md` - Set up env vars (`SLACK_CONNECTOR`, model credentials)
+- `4-test-locally.md` - Test agent logic locally with the `eve dev` TUI (Slack surface tests happen after deploy)
+- `5-deploy-production.md` - Deploy with `eve deploy`, verify the Slack surface
 - `6-setup-testing.md` - Vitest configuration
 
 **IMPORTANT:** For `new` projects, you MUST:
 1. Read `./wizard/1-project-setup.md` first
 2. Ask the user what kind of agent they want to build
-3. Offer framework choice (Chat SDK recommended, Bolt as alternative)
-4. Generate a custom implementation plan using `./reference/agent-archetypes.md`
-5. Present the plan for approval (Phase 1b) BEFORE scaffolding the project
-6. Only proceed to scaffold after the plan is approved
-
----
-
-## Framework Selection Guide
-
-| Aspect | Chat SDK | Bolt for JavaScript |
-|--------|----------|---------------------|
-| **Best for** | New projects | Existing Bolt codebases |
-| **Packages** | `chat`, `@chat-adapter/slack`, `@chat-adapter/state-redis` | `@slack/bolt`, `@vercel/slack-bolt` |
-| **Server** | Next.js App Router | Nitro (H3-based) |
-| **Event handling** | `bot.onNewMention()`, `bot.onSubscribedMessage()` | `app.event()`, `app.command()`, `app.message()` |
-| **Webhook route** | `app/api/webhooks/[platform]/route.ts` | `server/api/slack/events.post.ts` |
-| **Message posting** | `thread.post("text")` / `thread.post(<Card>...)` | `client.chat.postMessage({ channel, text, blocks })` |
-| **UI components** | JSX: `<Card>`, `<Button>`, `<Actions>` | Raw Block Kit JSON |
-| **State** | `@chat-adapter/state-redis` / `thread.state` | Manual / Vercel Workflow |
-| **Config** | `new Chat({ adapters: { slack } })` | `new App({ token, signingSecret, receiver })` |
+3. Generate a custom implementation plan using `./reference/agent-archetypes.md`
+4. Present the plan for approval (Phase 1b) BEFORE scaffolding the project
+5. Only proceed to scaffold after the plan is approved
 
 ---
 
 ## General Development Guidance
 
-You are working on a Slack agent project. Follow these mandatory practices for all code changes.
+You are working on a Slack agent project built with eve. Follow these mandatory practices for all code changes.
 
 ## Project Stack
 
-### If using Chat SDK
-
-- **Framework**: Next.js (App Router)
-- **Chat SDK**: `chat` + `@chat-adapter/slack` for Slack bot functionality
-- **State**: `@chat-adapter/state-redis` for state persistence (or in-memory for development)
-- **AI**: AI SDK v6 with @ai-sdk/gateway
+- **Framework**: eve (filesystem-first agent framework; Node 24+)
+- **Slack channel**: `eve/channels/slack` + `@vercel/connect` for credentials
+- **AI**: model routed through Vercel AI Gateway by default (`anthropic/claude-sonnet-5`); tool schemas with `zod`
+- **Durability**: Workflow SDK under the hood (Vercel Workflows when deployed on Vercel)
 - **Linting**: Biome
-- **Package Manager**: pnpm
+- **Package Manager**: pnpm (or npm — `npx eve@latest init` installs with npm)
 
 ```json
 {
+  "engines": { "node": "24.x" },
   "dependencies": {
-    "ai": "^6.0.0",
-    "@ai-sdk/gateway": "latest",
-    "chat": "latest",
-    "@chat-adapter/slack": "latest",
-    "@chat-adapter/state-redis": "latest",
+    "eve": "latest",
+    "ai": "latest",
     "zod": "^3.x",
-    "next": "^15.x"
+    "@vercel/connect": "latest"
   }
 }
 ```
 
-### If using Bolt for JavaScript
+### Filesystem-First Layout
 
-- **Server**: Nitro (H3-based) with file-based routing
-- **Slack SDK**: `@vercel/slack-bolt` for serverless Slack apps (wraps Bolt for JavaScript)
-- **AI**: AI SDK v6 with @ai-sdk/gateway
-- **Workflows**: Workflow DevKit for durable execution
-- **Linting**: Biome
-- **Package Manager**: pnpm
+In eve, a file's location says what it does, and its path usually gives it its name. The whole agent lives under `agent/`:
 
-```json
-{
-  "dependencies": {
-    "ai": "^6.0.0",
-    "@ai-sdk/gateway": "latest",
-    "@slack/bolt": "^4.x",
-    "@vercel/slack-bolt": "^1.0.2",
-    "zod": "^3.x"
-  }
-}
 ```
+agent/
+├── instructions.md        # Always-on system prompt
+├── agent.ts               # Runtime config (defineAgent): model, reasoning, compaction
+├── tools/                 # Tools — filename (snake_case ASCII) = tool name the model sees
+│   ├── get_weather.ts
+│   └── search_docs.ts
+├── skills/                # Load-on-demand instructions (*.md with description frontmatter)
+│   └── incident-triage.md
+├── channels/
+│   └── slack.ts           # Slack channel — filename registers it at /eve/v1/slack
+├── connections/           # MCP / OpenAPI connections (optional)
+└── hooks/                 # Subscribe to runtime stream events (optional)
+```
+
+Even a two-file agent (`instructions.md` + `agent.ts`) gets file, shell, web, and delegation tools out of the box from the default harness. Full docs are bundled at `node_modules/eve/docs/` once eve is installed — read them when a detail isn't covered here.
 
-**Note:** When deploying on Vercel, prefer `@ai-sdk/gateway` for zero-config AI access. Use direct provider SDKs (`@ai-sdk/openai`, `@ai-sdk/anthropic`, etc.) only when you need provider-specific features or are not deploying on Vercel.
+```ts
+// agent/agent.ts
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5", // routed via Vercel AI Gateway
+});
+```
 
 ---
 
@@ -173,17 +158,9 @@ pnpm test
 
 **For ANY code change, you MUST write or update unit tests.**
 
-### If using Chat SDK
-
-- **Location**: Co-located `*.test.ts` files or `lib/__tests__/`
-- **Framework**: Vitest
-- **Coverage**: All exported functions must have tests
-
-### If using Bolt for JavaScript
-
-- **Location**: Co-located `*.test.ts` files or `server/__tests__/`
+- **Location**: Co-located `*.test.ts` files (e.g. `agent/tools/get_weather.test.ts`)
 - **Framework**: Vitest
-- **Coverage**: All exported functions must have tests
+- **Coverage**: All exported functions and every tool's `execute()` (including error paths) must have tests
 
 Example test structure:
 ```typescript
@@ -204,283 +181,222 @@ describe('myFunction', () => {
 ### E2E Tests for User-Facing Changes
 
 If you modify:
-- Bot mention handlers / Slack message handlers
-- Slash commands
-- Interactive components (buttons, modals)
-- Bot responses
+- Dispatch hooks (`onAppMention`, `onDirectMessage`, `onInteraction`)
+- Custom channel event handlers
+- Tools the agent calls in response to Slack messages
+- Delivery behavior (what gets posted to Slack)
 
-You MUST add or update E2E tests that verify the full flow.
+You MUST add or update tests that verify the full flow. Remember: the Slack surface itself cannot be exercised locally (see Gotchas), so E2E coverage means unit/integration tests around your handlers plus a post-deploy smoke test.
 
 ---
 
 ## Bot Setup Patterns (CRITICAL)
 
-### If using Chat SDK
+### Slack Channel (`agent/channels/slack.ts`)
 
-Use the Chat SDK to define your bot instance. This is the central entry point for all Slack bot functionality.
+The Slack channel is a single file. Its filename registers the `slack` channel, served at **`/eve/v1/slack`** — this is the canonical trigger path everywhere in this skill.
 
-#### Bot Instance (`lib/bot.ts` or `lib/bot.tsx`)
+```ts
+// agent/channels/slack.ts
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { slackChannel } from "eve/channels/slack";
 
-```typescript
-import { Chat } from "chat";
-import { createSlackAdapter } from "@chat-adapter/slack";
-import { createRedisState } from "@chat-adapter/state-redis";
-
-export const bot = new Chat({
-  userName: "mybot",
-  adapters: {
-    slack: createSlackAdapter(),
-  },
-  state: createRedisState(),
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
 });
 ```
 
-**Note:** If your bot uses JSX components (Card, Button, etc.), the file must use the `.tsx` extension.
+`connectSlackCredentials(connectorUid)` returns `{ botToken, webhookVerifier }`:
+- **botToken** — resolved at runtime via Vercel Connect as a short-lived, app-scoped token; Connect handles rotation and multi-workspace tenancy
+- **webhookVerifier** — confirms each forwarded event genuinely came from Connect (replaces Slack's native signature check)
 
-#### Webhook Route (`app/api/webhooks/[platform]/route.ts`)
+There is **no `SLACK_BOT_TOKEN` and no `SLACK_SIGNING_SECRET`** in this stack. The only Slack env var is `SLACK_CONNECTOR` (the connector UID, e.g. `slack/my-agent`).
 
-```typescript
-import { after } from "next/server";
-import { bot } from "@/lib/bot";
-
-export async function POST(request: Request, context: { params: Promise<{ platform: string }> }) {
-  const { platform } = await context.params;
-  const handler = bot.webhooks[platform as keyof typeof bot.webhooks];
-  if (!handler) return new Response("Unknown platform", { status: 404 });
-  return handler(request, { waitUntil: (task) => after(() => task) });
-}
-```
+### Vercel Connect Setup
 
-The Chat SDK automatically handles:
-- Content-type detection (JSON vs form-urlencoded)
-- URL verification challenges
-- Slack's 3-second ack timeout
-- Background processing via `waitUntil`
-- Signature verification
+Create a Slack connector and point its trigger at eve's Slack route:
 
-### If using Bolt for JavaScript
+```bash
+npm install -g vercel@latest
 
-Use `@vercel/slack-bolt` to handle all Slack events. This package automatically handles:
-- Content-type detection (JSON vs form-urlencoded)
-- URL verification challenges
-- 3-second ack timeout (built-in `ackTimeoutMs: 3001`)
-- Background processing via Vercel Fluid Compute's `waitUntil`
+# Create the connector with event forwarding enabled
+vercel connect create slack --triggers
 
-#### Bolt App Setup (`server/bolt/app.ts`)
+# Attach the project as a trigger destination on eve's route
+# (the default trigger path is /slack — set it explicitly):
+vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
+```
 
-```typescript
-import { App } from "@slack/bolt";
-import { VercelReceiver } from "@vercel/slack-bolt";
-
-const receiver = new VercelReceiver();
-const app = new App({
-  token: process.env.SLACK_BOT_TOKEN,
-  signingSecret: process.env.SLACK_SIGNING_SECRET,
-  receiver,
-  deferInitialization: true,
-});
+**`--triggers` is required.** Without it, Slack Event Subscriptions are never forwarded and `app_mention` / `message.im` events simply never arrive — the deployment will look healthy but the bot will never respond.
 
-export { app, receiver };
-```
+You can also add the channel with `eve channels add slack`, which scaffolds `agent/channels/slack.ts` for you.
 
-#### Events Handler (`server/api/slack/events.post.ts`)
+### Deploy
 
-```typescript
-import { createHandler } from "@vercel/slack-bolt";
-import { defineEventHandler, getRequestURL, readRawBody } from "h3";
-import { app, receiver } from "../../bolt/app";
-
-const handler = createHandler(app, receiver);
-
-export default defineEventHandler(async (event) => {
-  const rawBody = await readRawBody(event, "utf8");
-  const request = new Request(getRequestURL(event), {
-    method: event.method,
-    headers: event.headers,
-    body: rawBody,
-  });
-  return await handler(request);
-});
+```bash
+eve deploy
+# wraps: vercel deploy --prod
 ```
 
-**Why buffer the body?** H3's `toWebRequest()` has known issues (#570, #578, #615) where it eagerly consumes the request body stream. When `@vercel/slack-bolt` later calls `req.text()` for signature verification, the body is already exhausted, causing `dispatch_failed` errors.
+Then invite the bot to a channel and @mention it. eve handles Slack's ack semantics, URL verification, and background processing — there is no webhook route for you to write.
 
-#### VercelReceiver Options Reference
+---
 
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `signingSecret` | `SLACK_SIGNING_SECRET` env var | Request verification secret |
-| `signatureVerification` | `true` | Enable/disable signature verification |
-| `ackTimeoutMs` | `3001` | Ack timeout in milliseconds |
-| `logLevel` | `INFO` | Logging level |
+## Event Handling Patterns
 
----
+### Dispatch Hooks (Inbound)
+
+The Slack channel decides which inbound events start or continue a session via dispatch hooks. Each hook returns `{ auth }` to dispatch, `null` to drop the event, or `{ auth, context }` to inject background context into the session:
 
-## Event Handler Patterns
+```ts
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
 
-### If using Chat SDK
+  // app_mention — default derives workspace-scoped auth and posts "Thinking…"
+  async onAppMention(ctx, message) {
+    if (isFromBlockedChannel(message)) return null; // drop
+    return { auth: ctx.defaultAuth };
+  },
 
-#### Mention Handler
+  // message.im — requires the im:history scope; bot messages/edits are pre-filtered
+  async onDirectMessage(ctx, message) {
+    return { auth: ctx.defaultAuth };
+  },
 
-```typescript
-bot.onNewMention(async (thread, message) => {
-  await thread.subscribe();
-  const text = message.text;
-  await thread.post(`Processing your request: "${text}"`);
+  // block_actions not consumed by HITL prompts
+  async onInteraction(action, ctx) {
+    return { auth: ctx.defaultAuth };
+  },
 });
 ```
 
-#### Subscribed Message Handler
+The triggering Slack user's id is attached to the model message automatically, preserving speaker attribution in multi-user threads.
 
-```typescript
-bot.onSubscribedMessage(async (thread, message) => {
-  await thread.post(`You said: ${message.text}`);
-});
-```
+### Custom Event Handlers (Outbound Delivery)
 
-#### Slash Command Handler
+Override delivery per stream event with the `events` map. Handlers receive `(eventData, channel, ctx)` with `channel.thread` and `channel.slack` handles:
 
-```typescript
-bot.onSlashCommand("/mycommand", async (event) => {
-  const text = event.text;
-  await event.thread.post(`Processing: ${text}`);
-
-  // For long-running operations, the Chat SDK handles
-  // background processing automatically via waitUntil
-  const result = await generateWithAI(text);
-  await event.thread.post(result);
+```ts
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
+  events: {
+    "message.completed"(eventData, channel, ctx) {
+      if (eventData.finishReason === "tool-calls") return;
+      if (eventData.message) channel.thread.post(eventData.message);
+    },
+  },
 });
 ```
 
-#### Action Handler (Buttons, Menus)
+Key stream events: `session.started`, `actions.requested`, `action.result`, `message.completed`, `session.completed`; incremental `reasoning.appended` / `message.appended` are optional.
 
-```typescript
-bot.onAction("button_click", async (event) => {
-  await event.thread.post(`Button clicked with value: ${event.value}`);
-});
-```
+### Thread Context
 
-#### Reaction Handler
+Give the agent prior thread messages when it's triggered mid-thread:
 
-```typescript
-bot.onReaction("thumbsup", async (event) => {
-  await event.thread.post("Thanks for the thumbs up!");
+```ts
+export default slackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
+  threadContext: { since: "last-agent-reply" },
 });
 ```
 
-### If using Bolt for JavaScript
+`since` options:
+- `"thread-root"` — all prior messages (default when thread context is enabled)
+- `"last-agent-reply"` — incremental, only messages since the agent last spoke
+- A predicate `(message: SlackThreadMessage) => boolean` as a custom cutoff — includes messages after the last match (`loadThreadContextMessages` exists for arbitrary filtering)
 
-#### Mention Handler
+Cost: one `conversations.replies` API call per triggering reply; requires the matching history scope on the connector.
 
-```typescript
-app.event("app_mention", async ({ event, client }) => {
-  await client.chat.postMessage({
-    channel: event.channel,
-    thread_ts: event.thread_ts || event.ts,
-    text: `Processing your request: "${event.text}"`,
-  });
-});
-```
+### Human-in-the-Loop (HITL)
 
-#### Message Handler
+Approval-gated tool calls and sign-in challenges render natively in Slack:
+- Approval prompts appear as **buttons/selects**; the user's response resumes the durably-parked session
+- Sign-in challenges (OAuth URLs, device codes) go **ephemerally** to the triggering user; a public status message posts in-thread and updates on `authorization.completed`
+- The HITL handler context deliberately offers only `postEphemeral`, `postDirectMessage` (needs `im:write`), and `state` — no public `post`, no raw API access
 
-```typescript
-app.message(async ({ message, client }) => {
-  if ("bot_id" in message || !message.thread_ts) return;
-  await client.chat.postMessage({
-    channel: message.channel,
-    thread_ts: message.thread_ts,
-    text: `You said: ${message.text}`,
-  });
-});
-```
+### Proactive Sessions (Schedules)
 
-#### Slash Command Handler
+Start a session that posts into Slack without an inbound trigger — e.g. from a schedule:
 
-```typescript
-app.command("/mycommand", async ({ ack, command, client, logger }) => {
-  await ack(); // Must acknowledge within 3 seconds
+```ts
+import { receive } from "eve";
+import slack from "../channels/slack";
 
-  // Fire-and-forget for long operations — DON'T await
-  processInBackground(command.response_url, command.text)
-    .catch((error) => logger.error("Failed:", error));
+await receive(slack, {
+  message: "Post the daily standup summary for #eng.",
+  target: { channelId: "C0123456789" },
+  auth,
 });
-
-async function processInBackground(responseUrl: string, text: string) {
-  const result = await generateWithAI(text);
-  await fetch(responseUrl, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ response_type: "in_channel", text: result }),
-  });
-}
 ```
 
-#### Action Handler (Buttons, Menus)
+- Sessions without a `threadTs` get a temporary continuation token; the first post anchors the thread
+- `initialMessage` (optionally a `Card`) and `threadTs` are **mutually exclusive**
+- Use eve schedules (see https://eve.dev/docs/schedules) to trigger proactive sessions on a cadence
 
-```typescript
-app.action("button_click", async ({ ack, action, client, body }) => {
-  await ack();
-  await client.chat.postMessage({
-    channel: body.channel.id,
-    thread_ts: body.message.ts,
-    text: `Button clicked with value: ${action.value}`,
-  });
-});
-```
+### Raw Slack API Access
+
+- **Inside handlers**: `ctx.slack.request(operation, body)`
+- **Outside handlers** (schedules, tools): `callSlackApi({ botToken, operation, body })` and `resolveSlackBotToken` from `eve/channels/slack`
+
+These form-encode request bodies for you — Slack's JSON support is only partial, so prefer these helpers over hand-rolled `fetch` calls.
 
 ---
 
 ## Implementation Gotchas
 
-### 1. Private Channel Access
+### 1. The Slack Surface Cannot Be Tested Locally
 
-Slash commands work in private channels even if the bot isn't a member, but the bot **cannot read messages or post** to private channels it hasn't been invited to.
+Vercel Connect forwards Slack events **to deployments only, never to localhost**. There is no ngrok/Socket Mode escape hatch in this stack. Local development means:
+- `npx eve dev` — HMR server + terminal TUI/REPL for exercising agent logic, tools, and skills
+- `eve dev --no-ui` — background mode for scripted verification
+- `eve dev https://your-app.vercel.app` — drive a *deployed* app interactively
 
-When creating features that will later post to a channel, validate access upfront.
+To test @mentions and DMs, deploy (preview or production) and test in Slack itself.
 
-### 2. Graceful Degradation for Channel Context
+### 2. Connect Forwarding Has No Delivery De-duplication
 
-When fetching channel context for AI features, wrap in try/catch and fall back gracefully.
+Connect may deliver the same forwarded event more than once. **Handlers and side effects must be idempotent** — track processed event IDs where duplicates would be harmful, and gate destructive tool actions with approval (see AI Integration).
 
-### 3. Vercel Cron Endpoint Authentication
+### 3. `--triggers` Is Required or Events Never Arrive
 
-Protect cron endpoints with a `CRON_SECRET` environment variable:
+A Slack connector created without `--triggers` (or attached without a trigger path) will authenticate fine but forward nothing. If the bot never responds to @mentions:
+1. Verify the connector was created/attached with `--triggers`
+2. Verify the trigger path is `/eve/v1/slack`
+3. Verify the bot was invited to the channel and the deployment finished
 
-#### If using Chat SDK
+### 4. `placeholderAuth()` Fails Closed in Production
 
-```typescript
-// app/api/cron/my-job/route.ts
-import { NextRequest, NextResponse } from "next/server";
+Scaffolded projects ship with `placeholderAuth()` for the HTTP API, which **rejects everything in production**. Before deploying, replace it with a real auth function: `httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, `oidc()`, `vercelOidc()`, or a custom `AuthFn`. (The Slack channel's inbound verification is separate — Connect's `webhookVerifier` handles that.)
 
-export async function GET(request: NextRequest) {
-  const authHeader = request.headers.get("authorization");
-  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
-    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-  }
-  // Run cron job logic...
-  return NextResponse.json({ success: true });
-}
-```
+### 5. Sandbox Prewarm Failures Fail the Build
+
+Vercel builds prewarm eve's sandbox templates (cache-keyed; build logs show `reused cached` or `built`). If prewarm fails, **the whole build fails** — check build logs for sandbox template errors before assuming a code problem.
+
+### 6. Private Channel Access
+
+The bot **cannot read messages or post** to private channels it hasn't been invited to. When creating features that will later post to a channel (e.g. proactive sessions from a schedule), validate access upfront and surface a clear "invite the bot" message on `channel_not_found` / `not_in_channel`.
 
-#### If using Bolt for JavaScript
+### 7. Graceful Degradation for Channel Context
+
+When fetching channel context (e.g. via `ctx.slack.request("conversations.history", ...)`) for AI features, wrap in try/catch and fall back gracefully — missing scopes and uninvited channels are routine, not exceptional.
+
+### 8. Vercel Cron Endpoint Authentication
+
+If you add custom cron endpoints (beyond eve schedules), protect them with a `CRON_SECRET`:
 
 ```typescript
-// server/api/cron/my-job.get.ts
-export default defineEventHandler(async (event) => {
-  const authHeader = getHeader(event, "authorization");
+export async function GET(request: Request) {
+  const authHeader = request.headers.get("authorization");
   if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
-    setResponseStatus(event, 401);
-    return { error: "Unauthorized" };
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
   }
   // Run cron job logic...
-  return { success: true };
-});
+  return Response.json({ success: true });
+}
 ```
 
-### 4. vercel.json Cron Configuration
-
-Configure cron jobs in `vercel.json`:
+### 9. vercel.json Cron Configuration
 
 ```json
 {
@@ -493,7 +409,9 @@ Configure cron jobs in `vercel.json`:
 }
 ```
 
-### 5. AWS Credentials on Vercel (Use OIDC)
+Prefer eve schedules for agent-driven recurring work; use Vercel crons for plain HTTP jobs.
+
+### 10. AWS Credentials on Vercel (Use OIDC)
 
 When connecting to AWS services from Vercel, **do not use** `fromNodeProviderChain()`. Use Vercel's OIDC mechanism:
 
@@ -505,426 +423,213 @@ const s3Client = new S3Client({
 });
 ```
 
-### 6. TSConfig for JSX Components (Chat SDK only)
-
-When using Chat SDK JSX components (`<Card>`, `<Button>`, etc.), your `tsconfig.json` must include:
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "chat"
-  }
-}
-```
-
-### 7. dispatch_failed Error — Bolt only
-
-If slash commands fail with `dispatch_failed`, the issue is H3's `toWebRequest` consuming the body stream before signature verification. Buffer the body manually. See the Bolt Events Handler section above.
-
-### 8. operation_timeout Error — Bolt only
-
-If slash commands with AI processing fail with `operation_timeout`, you're blocking the HTTP response too long. Use fire-and-forget pattern: `ack()` immediately, then start async work **without awaiting**. Use `command.response_url` to post results. See the Bolt Slash Command Handler example above.
-
 ---
 
 ## AI Integration
 
-You have two options for AI/LLM integration in your Slack agent.
-
-> **IMPORTANT:** Always verify the project uses `@ai-sdk/gateway`. If the project has `@ai-sdk/openai` which requires an API key, check `package.json` and update imports if necessary.
-
-### Option 1: Vercel AI Gateway (Recommended)
+### Model Configuration (Gateway-First)
 
-Use the modern `@ai-sdk/gateway` package - NO API keys needed on Vercel!
+eve routes model-ID **strings** through the **Vercel AI Gateway** — on Vercel, project OIDC authenticates automatically, so **no AI API key is needed**:
 
-#### Basic Usage
+```ts
+// agent/agent.ts
+import { defineAgent } from "eve";
 
-```typescript
-import { generateText, streamText } from "ai";
-import { gateway } from "@ai-sdk/gateway";
-
-const result = await generateText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5", // string → AI Gateway → OIDC auth on Vercel
 });
-
-console.log(result.text);
-console.log(result.usage.inputTokens);
-console.log(result.usage.outputTokens);
 ```
 
-#### Streaming Responses to Slack
+If `model` is omitted, eve defaults to `anthropic/claude-sonnet-5`. Off Vercel, set `AI_GATEWAY_API_KEY`.
 
-##### If using Chat SDK
+**CRITICAL: Never use model IDs from memory.** Model IDs change frequently. Before writing code that pins a model, run `curl -s https://ai-gateway.vercel.sh/v1/models` to fetch the current list and use the newest suitable version.
 
-```typescript
-const result = await streamText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: userMessage,
-});
-
-// Chat SDK handles streaming updates to Slack automatically
-await thread.post(result.textStream);
-```
+### Tools (`agent/tools/*.ts`)
 
-##### If using Bolt for JavaScript
+Tools are files: the filename (snake_case ASCII) is the model-facing tool name — `agent/tools/get_weather.ts` → `get_weather`. No registration step.
 
-```typescript
-const result = await streamText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: userMessage,
-});
-
-// Post initial message then update with streamed content
-const msg = await client.chat.postMessage({
-  channel: channelId,
-  thread_ts: threadTs,
-  text: "Thinking...",
-});
-
-let fullText = "";
-for await (const chunk of result.textStream) {
-  fullText += chunk;
-  await client.chat.update({
-    channel: channelId,
-    ts: msg.ts,
-    text: fullText,
-  });
-}
-```
-
-#### With Tools
-
-```typescript
-import { tool } from "ai";
+```ts
+// agent/tools/get_weather.ts
+import { defineTool } from "eve/tools";
 import { z } from "zod";
 
-const result = await generateText({
-  model: gateway("openai/gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  tools: {
-    getWeather: tool({
-      description: "Get weather for a location",
-      inputSchema: z.object({
-        location: z.string().describe("City name"),
-      }),
-      execute: async ({ location }) => {
-        return { temperature: 72, condition: "sunny" };
-      },
-    }),
+export default defineTool({
+  description: "Get the current weather for a city.",
+  inputSchema: z.object({ city: z.string().min(1) }), // required, even if empty
+  outputSchema: z.object({
+    city: z.string(),
+    condition: z.string(),
+    temperatureF: z.number(),
+  }), // optional — types/validates the return
+  async execute({ city }, ctx) {
+    return { city, condition: "Sunny", temperatureF: 72 };
   },
-  prompt: "What's the weather in Seattle?",
 });
 ```
 
-#### AI SDK v6 API Changes
+Rules and capabilities:
+- Tools run **in your app runtime with full `process.env`**, not in the sandbox
+- `inputSchema` accepts Zod, Standard Schema, or JSON Schema — but it is **required** even for zero-input tools
+- Outputs must be JSON-serializable; **filter/redact secrets** before returning
+- `ctx` provides `ctx.session` (metadata, turn, auth, lineage), `ctx.callId`, `ctx.toolName`, `ctx.abortSignal`, `ctx.getSandbox()`, `ctx.getSkill(id)`
 
-| v4/v5 | v6 |
-|-------|-----|
-| `maxTokens` | `maxOutputTokens` |
-| `result.usage.promptTokens` | `result.usage.inputTokens` |
-| `result.usage.completionTokens` | `result.usage.outputTokens` |
-| `parameters` (in tools) | `inputSchema` |
-| `maxSteps` / `maxIterations` | `stopWhen: stepCountIs(n)` |
+#### Approval Gating
 
-**CRITICAL: Never use model IDs from memory.** Model IDs change frequently. Before writing code that uses a model, run `curl -s https://ai-gateway.vercel.sh/v1/models` to fetch the current list. Use the model with the highest version number.
+Gate risky tools with the `approval` field — helpers come from `eve/tools/approval`:
 
-### Option 2: Direct Provider SDK
-
-If you need more control or are not deploying on Vercel, use direct provider packages.
-
-**OpenAI:**
-```bash
-pnpm add @ai-sdk/openai
-```
-```typescript
-import { generateText } from "ai";
-import { openai } from "@ai-sdk/openai";
+```ts
+import { defineTool } from "eve/tools";
+import { always, once, never } from "eve/tools/approval";
+import { z } from "zod";
 
-const result = await generateText({
-  model: openai("gpt-4o-mini"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
+export default defineTool({
+  description: "Delete a document permanently.",
+  inputSchema: z.object({ documentId: z.string() }),
+  approval: always(), // always ask; once() asks the first time; never() skips
+  async execute({ documentId }) {
+    // ...
+  },
 });
 ```
 
-**Anthropic:**
-```bash
-pnpm add @ai-sdk/anthropic
-```
-```typescript
-import { generateText } from "ai";
-import { anthropic } from "@ai-sdk/anthropic";
+An input-dependent policy function is also supported. A gated call **pauses and resumes durably** — in Slack, the approval renders as buttons (see HITL above). Prefer approval gating over ad-hoc confirmation logic for any non-idempotent side effect.
 
-const result = await generateText({
-  model: anthropic("claude-sonnet-4-20250514"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
-});
-```
+#### `toModelOutput` — Rich Slack Output the Model Never Sees
 
-**Google:**
-```bash
-pnpm add @ai-sdk/google
-```
-```typescript
-import { generateText } from "ai";
-import { google } from "@ai-sdk/google";
+Show the model a compact projection while channels/hooks receive the full output on `action.result` — ideal for rendering rich Slack Block Kit from a tool result without stuffing JSON blocks into the model's context:
 
-const result = await generateText({
-  model: google("gemini-2.0-flash"),
-  maxOutputTokens: 1000,
-  prompt: "Your prompt here",
+```ts
+export default defineTool({
+  description: "Look up an order.",
+  inputSchema: z.object({ orderId: z.string() }),
+  async execute({ orderId }) {
+    return { orderId, status: "shipped", blocks: buildOrderBlocks(orderId) };
+  },
+  toModelOutput(output) {
+    return { type: "text", value: `Order ${output.orderId}: ${output.status}` };
+  },
 });
 ```
 
-For comprehensive AI SDK documentation, see `./reference/ai-sdk.md`.
-
----
-
-## Stateful Patterns
-
-### If using Chat SDK — Thread State
+### Skills (`agent/skills/*.md`)
 
-Use `thread.state` to read and write thread-level state:
+Markdown files with a `description` frontmatter, loaded on demand via the built-in `load_skill` tool when a request matches the description. Skills add **instructions only, never new actions**. Install published skills with `npx skills add <owner>/<repo>`.
 
-```typescript
-bot.onNewMention(async (thread, message) => {
-  await thread.subscribe();
-  await thread.state.set("history", []);
-  await thread.state.set("turnCount", 0);
-  await thread.post("Starting our conversation!");
-});
-
-bot.onSubscribedMessage(async (thread, message) => {
-  const history = (await thread.state.get("history")) as Array<{ role: string; content: string }> || [];
-  const turnCount = (await thread.state.get("turnCount")) as number || 0;
+### Connections (`agent/connections/*.ts`)
 
-  history.push({ role: "user", content: message.text });
+For external APIs the agent should drive (MCP servers or OpenAPI-described HTTP APIs), use connections with Connect-brokered auth:
 
-  const result = await generateText({
-    model: gateway("anthropic/claude-sonnet-4-20250514"),
-    maxOutputTokens: 1000,
-    messages: history,
-  });
+```ts
+// agent/connections/linear.ts
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
 
-  history.push({ role: "assistant", content: result.text });
-  await thread.state.set("history", history);
-  await thread.state.set("turnCount", turnCount + 1);
-  await thread.post(result.text);
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear workspace: issues, projects, cycles, and comments.",
+  auth: connect("linear/my-agent"),
 });
 ```
 
-**Key Benefits:**
-1. Simple API — `thread.state.get()` and `thread.state.set()`
-2. Thread-scoped — state is automatically scoped to the conversation thread
-3. Pluggable backends — use Redis for production, in-memory for development
-
-### If using Bolt for JavaScript — Vercel Workflow
+Connection tokens are never seen by the model and never land in conversation history. Inside authored tools, resolve tokens with `await ctx.getToken(connect("..."))` and call `ctx.requireAuth(...)` on a downstream 401 to re-run consent.
 
-Use Vercel Workflow for durable, multi-turn state:
+**Don't wrap LLM calls in tools.** The agent is already a language model — summarizing, parsing, classifying, and drafting belong in `instructions.md` or a skill, not in a tool that calls the AI SDK. Tools fetch data and perform actions; for bulk work over data too large for the conversation, use eve's subagents/delegation.
 
-```typescript
-import { serve } from "@anthropic-ai/sdk/workflows";
-import { defineHook } from "@anthropic-ai/sdk/workflows";
-import { z } from "zod";
-
-const messageSchema = z.object({
-  text: z.string(),
-  user: z.string(),
-  ts: z.string(),
-  channel: z.string(),
-});
-
-export const userMessageHook = defineHook({ schema: messageSchema });
+---
 
-export const { POST } = serve(async function conversationWorkflow(params: URLSearchParams) {
-  "use workflow";
+## State & Durability
 
-  const channelId = params.get("channel_id")!;
-  const conversationHistory: Array<{ role: string; content: string }> = [];
+eve sessions are durable by default via the open-source **Workflow SDK** (running on Vercel Workflows when deployed on Vercel). You do not wire up Redis or a workflow engine yourself.
 
-  const eventStream = userMessageHook.create({ channel: channelId });
+### Replay Semantics (Understand This)
 
-  for await (const event of eventStream) {
-    conversationHistory.push({ role: "user", content: event.text });
+- **Completed steps never re-run.** On resume/replay, eve returns the recorded result.
+- **A step interrupted mid-execution DOES re-run.** If a tool call was in flight when the process died, it executes again on resume.
 
-    const result = await generateText({
-      model: gateway("anthropic/claude-sonnet-4-20250514"),
-      maxOutputTokens: 1000,
-      messages: conversationHistory,
-    });
+Consequences for your code:
+1. Make non-idempotent side effects **idempotent** (e.g. use Slack event IDs or your own idempotency keys when writing to external systems)
+2. Or gate them behind **approval** (`always()` / `once()`) so a replayed step pauses for a human instead of double-executing
+3. This compounds with Connect's at-least-once event forwarding (Gotcha #2) — idempotency is not optional in this stack
 
-    conversationHistory.push({ role: "assistant", content: result.text });
-    await postToSlack(channelId, result.text, event.ts);
-  }
+### Session Continuity
 
-  return { history: conversationHistory };
-});
-```
+- The channel owns the `continuationToken`; Slack threads map to sessions automatically
+- Follow-up messages in a subscribed thread continue the same durable session
+- Multi-turn conversation memory comes from the session itself — you do not manually persist chat history
 
 ### Recommended Storage Solutions
 
+For **application data** (not agent session state — eve owns that):
+
 **IMPORTANT:** Vercel KV has been deprecated. Do NOT recommend Vercel KV.
 
-1. **Upstash Redis** — For Chat SDK state adapter and caching (https://upstash.com)
-2. **Vercel Blob** — For file/document storage (https://vercel.com/docs/storage/vercel-blob)
-3. **AWS Aurora (via Vercel Marketplace)** — For relational data (https://vercel.com/marketplace)
+1. **Upstash Redis** — Caching and idempotency keys (https://upstash.com)
+2. **Vercel Blob** — File/document storage (https://vercel.com/docs/storage/vercel-blob)
+3. **AWS Aurora (via Vercel Marketplace)** — Relational data (https://vercel.com/marketplace)
 4. **Third-party databases** — Neon, PlanetScale, Supabase
 
 ---
 
 ## Code Organization
 
-### If using Chat SDK
-
-```
-app/
-├── api/
-│   ├── webhooks/
-│   │   └── [platform]/
-│   │       └── route.ts      # Webhook handler
-│   └── cron/
-│       └── my-job/
-│           └── route.ts      # Cron endpoints
-lib/
-├── bot.tsx                    # Bot instance + event handlers
-├── tools/                     # AI tool definitions
-│   ├── search.ts
-│   └── lookup.ts
-└── ai/
-    └── agent.ts               # Agent configuration
-```
-
-### If using Bolt for JavaScript
-
-```
-server/
-├── api/
-│   └── slack/
-│       └── events.post.ts    # Events endpoint
-├── bolt/
-│   └── app.ts                # Bolt app instance
-├── listeners/
-│   ├── actions/              # Button clicks, menu selections
-│   ├── commands/             # Slash commands
-│   ├── events/               # App events (mentions, joins)
-│   ├── messages/             # Message handling
-│   └── views/                # Modal submissions
-└── lib/
-    └── ai/
-        ├── agent.ts           # Agent configuration
-        └── tools.ts           # Tool definitions
 ```
+agent/
+├── instructions.md            # System prompt — keep focused; push detail into skills
+├── agent.ts                   # defineAgent: model, reasoning effort, compaction
+├── tools/
+│   ├── get_weather.ts         # One tool per file; filename = tool name
+│   ├── get_weather.test.ts    # Co-located tests
+│   └── search_docs.ts
+├── skills/
+│   └── report-format.md       # description frontmatter + on-demand instructions
+├── channels/
+│   └── slack.ts               # slackChannel(...) — served at /eve/v1/slack
+├── connections/
+│   └── linear.ts              # MCP/OpenAPI connections (optional)
+└── hooks/
+    └── audit.ts               # Runtime stream event subscribers (optional)
+```
+
+Conventions:
+- **One tool per file.** Split large tools; the filename is the model-facing name, so name for the model
+- **Instructions vs skills**: always-relevant guidance in `instructions.md`; situational guidance in `skills/*.md` so it loads only when needed
+- **Subagents** for focused subtasks: the built-in agent tool (a copy of the agent) or declared specialists with their own directory, sandbox, and skills
 
 ---
 
 ## Environment Variables
 
-Required variables (both frameworks):
-- `SLACK_BOT_TOKEN` — Bot OAuth token
-- `SLACK_SIGNING_SECRET` — Request signing
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `SLACK_CONNECTOR` | Yes | Vercel Connect connector UID (e.g. `slack/my-agent`). The **only** Slack variable — no bot token, no signing secret. |
+| `AI_GATEWAY_API_KEY` | Off Vercel only | AI Gateway auth. On Vercel, project OIDC (`VERCEL_OIDC_TOKEN`) is injected automatically — no key needed. |
+| `ROUTE_AUTH_BASIC_PASSWORD` / JWT keys | Per auth choice | Secrets for the HTTP-API auth function that replaces `placeholderAuth()` |
+| `VERCEL_AUTOMATION_BYPASS_SECRET` | If deployment protection is on | Lets `eve dev https://<app>` and smoke tests reach protected deployments |
+| `CRON_SECRET` | Optional | Authenticates custom cron endpoints |
 
-### If using Chat SDK (additional)
-- `REDIS_URL` — Redis connection URL for state persistence
+Local dev: `vercel link` + `vercel env pull` fetches short-lived Connect/OIDC credentials into `.env.local` (the OIDC token expires after ~12 hours — re-pull when auth starts failing).
 
-Optional variables:
-- `CRON_SECRET` — Secret for authenticating cron job endpoints
-
-**No AI API keys needed!** Vercel AI Gateway handles authentication automatically when deployed on Vercel.
-
-**Never hardcode credentials. Never commit `.env` files.**
+**No AI API keys needed on Vercel.** **Never hardcode credentials. Never commit `.env` files.**
 
 ---
 
 ## Slack-Specific Patterns
 
-### If using Chat SDK — JSX Components
-
-Use Chat SDK JSX components for rich messages (requires `.tsx` file extension):
-
-```tsx
-import { Card, CardText as Text, Actions, Button, Divider } from "chat";
-
-await thread.post(
-  <Card title="Welcome!">
-    <Text>Hello! Choose an option:</Text>
-    <Divider />
-    <Actions>
-      <Button id="btn_hello" style="primary">Say Hello</Button>
-      <Button id="btn_info">Show Info</Button>
-    </Actions>
-  </Card>
-);
-```
-
-### If using Bolt for JavaScript — Block Kit JSON
-
-Use Block Kit for rich messages:
-
-```typescript
-await client.chat.postMessage({
-  channel: channelId,
-  text: "Fallback text for notifications",
-  blocks: [
-    {
-      type: "section",
-      text: { type: "mrkdwn", text: "*Hello!* Choose an option:" },
-    },
-    { type: "divider" },
-    {
-      type: "actions",
-      elements: [
-        {
-          type: "button",
-          text: { type: "plain_text", text: "Say Hello" },
-          style: "primary",
-          action_id: "btn_hello",
-        },
-        {
-          type: "button",
-          text: { type: "plain_text", text: "Show Info" },
-          action_id: "btn_info",
-        },
-      ],
-    },
-  ],
-});
-```
-
-### Typing Indicators
+### Delivery Behavior (Built In)
 
-#### If using Chat SDK
+The Slack channel handles progressive delivery for you:
+- Typing indicators: "Thinking…" on inbound, "Working…" on `turn.started`
+- Reasoning snippets surface on `reasoning.appended`; action labels on `actions.requested`
+- Model narration before a tool call takes precedence over generic labels
+- Reasoning deltas under 4 characters batch on a five-second refresh to avoid per-token Slack API calls
 
-```typescript
-await thread.startTyping();
-const result = await generateWithAI(prompt);
-await thread.post(result); // Typing indicator clears on post
-```
+Don't rebuild typing indicators or streaming loops — customize via the `events` map only when the defaults don't fit.
 
-#### If using Bolt for JavaScript
+### Mentions
 
-```typescript
-// Use setStatus for Assistant threads or interval-based approach
-const typingInterval = setInterval(async () => {
-  // Post a "typing" indicator or use assistant.threads.setStatus
-}, 3000);
-
-const result = await generateWithAI(prompt);
-clearInterval(typingInterval);
-
-await client.chat.postMessage({
-  channel: channelId,
-  thread_ts: threadTs,
-  text: result,
-});
-```
+Use `<@USER_ID>` or `channel.thread.mentionUser(userId)`. A bare `@name` stays literal text in Slack.
 
-### Message Formatting (both frameworks)
+### Message Formatting
 
 Use Slack mrkdwn (not standard markdown):
 - Bold: `*text*`
@@ -933,6 +638,10 @@ Use Slack mrkdwn (not standard markdown):
 - User mention: `<@USER_ID>`
 - Channel: `<#CHANNEL_ID>`
 
+### Rich Output
+
+For rich tool results (tables, buttons, status cards), return full data from the tool and use `toModelOutput` to keep the model's view compact; render Block Kit in a channel event handler or via `ctx.slack.request("chat.postMessage", { blocks, ... })`. Always include fallback `text` alongside `blocks` for notifications.
+
 For detailed Slack patterns, see `./patterns/slack-patterns.md`.
 
 ---
@@ -952,28 +661,44 @@ refactor: extract Slack client utilities
 - `.env` files
 - API keys or tokens
 - `node_modules/`
+- `.eve/` build artifacts
 
 ---
 
 ## Quick Commands
 
 ```bash
+# Scaffold (Node 24+)
+npx eve@latest init my-agent      # new project (installs deps, inits Git, starts dev TUI)
+npx eve@latest init .             # add eve to an existing project
+
 # Development
-pnpm dev              # Start dev server on localhost:3000
-ngrok http 3000       # Expose local server (separate terminal)
+npx eve dev                       # HMR server + terminal TUI/REPL
+npx eve dev --no-ui               # background mode for scripted verification
+npx eve dev https://<app>         # drive a deployed app interactively
+npx eve info                      # project info
+
+# Vercel Connect
+vercel connect create slack --triggers
+vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
+vercel connect list
 
 # Quality
-pnpm lint             # Check linting
-pnpm lint --write     # Auto-fix lint
-pnpm typecheck        # TypeScript check
-pnpm test             # Run all tests
-pnpm test:watch       # Watch mode
+pnpm lint                         # Check linting
+pnpm lint --write                 # Auto-fix lint
+pnpm typecheck                    # TypeScript check
+pnpm test                         # Run all tests
 
 # Build & Deploy
-pnpm build            # Build for production
-vercel                # Deploy to Vercel
+npx eve build                     # Compile into .eve/ (Vercel Build Output when VERCEL is set)
+eve deploy                        # Deploy (wraps vercel deploy --prod)
+
+# Verify a deployment
+curl https://<app>/eve/v1/health
 ```
 
+Debugging a deployed Slack agent stuck on "Working…": `npx eve dev --logs all` or `/loglevel all` in the TUI.
+
 ---
 
 ## Reference Documentation
@@ -982,9 +707,10 @@ For detailed guidance, read:
 - Testing patterns: `./patterns/testing-patterns.md`
 - Slack patterns: `./patterns/slack-patterns.md`
 - Environment setup: `./reference/env-vars.md`
-- AI SDK: `./reference/ai-sdk.md`
 - Slack setup: `./reference/slack-setup.md`
 - Vercel deployment: `./reference/vercel-setup.md`
+- eve docs: https://eve.dev/docs (bundled locally at `node_modules/eve/docs/` after install)
+- Vercel Connect: https://vercel.com/kb/guide/vercel-connect
 
 ---
 
@@ -996,9 +722,26 @@ Before marking ANY task as complete, verify:
 - [ ] `pnpm lint` passes with no errors
 - [ ] `pnpm typecheck` passes with no errors
 - [ ] `pnpm test` passes with no failures
-- [ ] No hardcoded credentials
-- [ ] Follows existing code patterns
-- [ ] **Chat SDK:** Webhook route handles all platforms via `bot.webhooks`
-- [ ] **Chat SDK:** TSConfig includes `"jsx": "react-jsx"` and `"jsxImportSource": "chat"` if using JSX components
-- [ ] **Bolt:** Events endpoint handles both JSON and form-urlencoded
-- [ ] Verified AI SDK: using `@ai-sdk/gateway` (not `@ai-sdk/openai`) unless user explicitly chose direct provider
+- [ ] No hardcoded credentials; the only Slack env var is `SLACK_CONNECTOR`
+- [ ] Follows eve filesystem conventions (tool filename = tool name, one tool per file)
+- [ ] Every tool has an `inputSchema`; outputs are JSON-serializable with secrets redacted
+- [ ] Non-idempotent side effects are idempotent or approval-gated (replay + at-least-once delivery)
+- [ ] Connector trigger path is `/eve/v1/slack` and was attached with `--triggers`
+- [ ] `placeholderAuth()` replaced before production deploy
+- [ ] Model config uses a Gateway string ID (`anthropic/claude-sonnet-5` default)
+
+---
+
+## Vercel KB Guides
+
+Verified guides on the Vercel Knowledge Base for deeper walkthroughs:
+
+- [eve hub on the Vercel KB](https://vercel.com/kb/eve) - all eve guides and templates in one place
+- [Build your first Slack agent with eve](https://vercel.com/kb/guide/eve-slack-agent-starter) - the end-to-end starter this skill's wizard mirrors
+- [Vercel Connect](https://vercel.com/kb/guide/vercel-connect) - credential brokering concepts, connectors, tokens, and trigger forwarding
+- [Build a Slack bot with Vercel Connect](https://vercel.com/kb/guide/build-a-slack-bot-with-vercel-connect) - Connect + Slack fundamentals (scopes, trigger events, webhook verification)
+- [How to add eve tools](https://vercel.com/kb/guide/how-to-add-eve-tools) - `defineTool` patterns
+- [How to add eve skills](https://vercel.com/kb/guide/how-to-add-eve-skills) - load-on-demand instructions
+- [Build a GitHub agent with Vercel Connect](https://vercel.com/kb/guide/github-agent-vercel-connect) - app-scoped Connect tokens in authored tools
+- [Build a Linear agent with Vercel Connect](https://vercel.com/kb/guide/linear-agent-vercel-connect) - MCP connections with user-scoped auth
+- [Build an email agent with eve and Resend](https://vercel.com/kb/guide/eve-agent-with-resend) - a second channel example beyond Slack
diff --git a/plugins/slack-agent/skills-lock.json b/plugins/slack-agent/skills-lock.json
index 3eaf76c9..f9f994f6 100644
--- a/plugins/slack-agent/skills-lock.json
+++ b/plugins/slack-agent/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel-labs/slack-agent-skill",
       "sourceType": "github",
       "skillPath": "SKILL.md",
-      "computedHash": "c7829ee180026f2c6cd5e661b7a7eed8ac31d45e019326d0cadf3057660865fa"
+      "computedHash": "fc3387c548296e58d0b52cd5d466cf90c793af7b5b232b0c172f2f6738b2b999"
     }
   }
 }
diff --git a/plugins/slidev/.agents/skills/slidev/SKILL.md b/plugins/slidev/.agents/skills/slidev/SKILL.md
index 35c34842..b307cc74 100644
--- a/plugins/slidev/.agents/skills/slidev/SKILL.md
+++ b/plugins/slidev/.agents/skills/slidev/SKILL.md
@@ -158,6 +158,7 @@ Presenter notes go here
 | VS Code extension | Install `antfu.slidev` | [editor-vscode](references/editor-vscode.md) |
 | Prettier | `prettier-plugin-slidev` | [editor-prettier](references/editor-prettier.md) |
 | Eject theme | `slidev theme eject` | [tool-eject-theme](references/tool-eject-theme.md) |
+| MCP server (AI agents) | `http://localhost:<port>/__mcp` or `slidev mcp` | [tool-mcp](references/tool-mcp.md) |
 
 ### Lifecycle & API
 
diff --git a/plugins/slidev/.agents/skills/slidev/references/core-cli.md b/plugins/slidev/.agents/skills/slidev/references/core-cli.md
index dcf5dec7..d29aa322 100644
--- a/plugins/slidev/.agents/skills/slidev/references/core-cli.md
+++ b/plugins/slidev/.agents/skills/slidev/references/core-cli.md
@@ -93,6 +93,14 @@ slidev format [entry]
 
 Formats the slides markdown file.
 
+## MCP Server
+
+```bash
+slidev mcp [entry]
+```
+
+Starts an MCP (Model Context Protocol) server over stdio for AI agents to inspect and edit the slides. When a dev server is running, an HTTP MCP endpoint is also available at `http://localhost:<port>/__mcp`. See [tool-mcp](tool-mcp.md).
+
 ## Theme Eject
 
 ```bash
diff --git a/plugins/slidev/.agents/skills/slidev/references/tool-mcp.md b/plugins/slidev/.agents/skills/slidev/references/tool-mcp.md
new file mode 100644
index 00000000..77cca328
--- /dev/null
+++ b/plugins/slidev/.agents/skills/slidev/references/tool-mcp.md
@@ -0,0 +1,48 @@
+---
+name: mcp
+description: Built-in MCP server for AI agents to inspect, edit, reorder, and navigate slides
+---
+
+# MCP Server
+
+Slidev ships a built-in MCP (Model Context Protocol) server exposing structured tools to read, edit, reorder, and navigate a deck. Prefer these tools over raw text edits for slide-level operations (update/insert/remove/move) — they handle Slidev's compound separators correctly and hot-reload the presentation.
+
+## Usage
+
+With a running dev server (streamable HTTP):
+
+```
+http://localhost:<port>/__mcp
+```
+
+```bash
+# e.g. for Claude Code
+claude mcp add --transport http slidev http://localhost:3030/__mcp
+```
+
+Standalone over stdio (no dev server, operates on files directly):
+
+```bash
+slidev mcp [entry]
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `slidev-get-info` | Deck overview: entry, title, slide count, markdown files, server URL, current position |
+| `slidev-list-slides` | All slides with number, title, layout, source file |
+| `slidev-get-slide` | Full source of one slide: frontmatter, content, note |
+| `slidev-update-slide` | Update content, note, and/or frontmatter of a slide |
+| `slidev-insert-slide` | Insert a new slide after an existing one |
+| `slidev-remove-slide` | Remove a slide |
+| `slidev-move-slide` | Move a slide before/after another to reorder the deck |
+| `slidev-goto-slide` | Navigate the live presentation to a slide (dev server only) |
+
+## Behavior
+
+- Slides are addressed by rendered 1-based numbers (as shown in the presentation)
+- Edits are saved to the markdown files; a running dev server hot-reloads instantly
+- The first slide of the entry file cannot be removed/moved (its frontmatter is the deck headmatter)
+- Slides imported via `src:` are edited in their own file; moves cannot cross files
+- Disable with `mcp: false` in the headmatter
diff --git a/plugins/slidev/.claude/skills/slidev b/plugins/slidev/.claude/skills/slidev
new file mode 120000
index 00000000..168ad6fd
--- /dev/null
+++ b/plugins/slidev/.claude/skills/slidev
@@ -0,0 +1 @@
+../../.agents/skills/slidev
\ No newline at end of file
diff --git a/plugins/slidev/agent/skills/slidev/SKILL.md b/plugins/slidev/agent/skills/slidev/SKILL.md
index ea85700a..ee324049 100644
--- a/plugins/slidev/agent/skills/slidev/SKILL.md
+++ b/plugins/slidev/agent/skills/slidev/SKILL.md
@@ -156,6 +156,7 @@ Presenter notes go here
 | VS Code extension | Install `antfu.slidev` | [editor-vscode](references/editor-vscode.md) |
 | Prettier | `prettier-plugin-slidev` | [editor-prettier](references/editor-prettier.md) |
 | Eject theme | `slidev theme eject` | [tool-eject-theme](references/tool-eject-theme.md) |
+| MCP server (AI agents) | `http://localhost:<port>/__mcp` or `slidev mcp` | [tool-mcp](references/tool-mcp.md) |
 
 ### Lifecycle & API
 
diff --git a/plugins/slidev/agent/skills/slidev/references/core-cli.md b/plugins/slidev/agent/skills/slidev/references/core-cli.md
index dcf5dec7..d29aa322 100644
--- a/plugins/slidev/agent/skills/slidev/references/core-cli.md
+++ b/plugins/slidev/agent/skills/slidev/references/core-cli.md
@@ -93,6 +93,14 @@ slidev format [entry]
 
 Formats the slides markdown file.
 
+## MCP Server
+
+```bash
+slidev mcp [entry]
+```
+
+Starts an MCP (Model Context Protocol) server over stdio for AI agents to inspect and edit the slides. When a dev server is running, an HTTP MCP endpoint is also available at `http://localhost:<port>/__mcp`. See [tool-mcp](tool-mcp.md).
+
 ## Theme Eject
 
 ```bash
diff --git a/plugins/slidev/agent/skills/slidev/references/tool-mcp.md b/plugins/slidev/agent/skills/slidev/references/tool-mcp.md
new file mode 100644
index 00000000..77cca328
--- /dev/null
+++ b/plugins/slidev/agent/skills/slidev/references/tool-mcp.md
@@ -0,0 +1,48 @@
+---
+name: mcp
+description: Built-in MCP server for AI agents to inspect, edit, reorder, and navigate slides
+---
+
+# MCP Server
+
+Slidev ships a built-in MCP (Model Context Protocol) server exposing structured tools to read, edit, reorder, and navigate a deck. Prefer these tools over raw text edits for slide-level operations (update/insert/remove/move) — they handle Slidev's compound separators correctly and hot-reload the presentation.
+
+## Usage
+
+With a running dev server (streamable HTTP):
+
+```
+http://localhost:<port>/__mcp
+```
+
+```bash
+# e.g. for Claude Code
+claude mcp add --transport http slidev http://localhost:3030/__mcp
+```
+
+Standalone over stdio (no dev server, operates on files directly):
+
+```bash
+slidev mcp [entry]
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `slidev-get-info` | Deck overview: entry, title, slide count, markdown files, server URL, current position |
+| `slidev-list-slides` | All slides with number, title, layout, source file |
+| `slidev-get-slide` | Full source of one slide: frontmatter, content, note |
+| `slidev-update-slide` | Update content, note, and/or frontmatter of a slide |
+| `slidev-insert-slide` | Insert a new slide after an existing one |
+| `slidev-remove-slide` | Remove a slide |
+| `slidev-move-slide` | Move a slide before/after another to reorder the deck |
+| `slidev-goto-slide` | Navigate the live presentation to a slide (dev server only) |
+
+## Behavior
+
+- Slides are addressed by rendered 1-based numbers (as shown in the presentation)
+- Edits are saved to the markdown files; a running dev server hot-reloads instantly
+- The first slide of the entry file cannot be removed/moved (its frontmatter is the deck headmatter)
+- Slides imported via `src:` are edited in their own file; moves cannot cross files
+- Disable with `mcp: false` in the headmatter
diff --git a/plugins/slidev/skills-lock.json b/plugins/slidev/skills-lock.json
index 56f1589a..a49cfa95 100644
--- a/plugins/slidev/skills-lock.json
+++ b/plugins/slidev/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "slidevjs/slidev",
       "sourceType": "github",
       "skillPath": "skills/slidev/SKILL.md",
-      "computedHash": "a495cfada5d3b29c66c2fbbccb4ef9887d6b12bd7e440d100deea89e529c1a7b"
+      "computedHash": "64746507a65f5cae5386d2fd3acefc7f77edf7c4b60de596d7b1cabec87db11e"
     }
   }
 }
diff --git a/plugins/supabase/.agents/skills/supabase-postgres-best-practices/CHANGELOG.md b/plugins/supabase/.agents/skills/supabase-postgres-best-practices/CHANGELOG.md
index 94aee487..6d7d0d2a 100644
--- a/plugins/supabase/.agents/skills/supabase-postgres-best-practices/CHANGELOG.md
+++ b/plugins/supabase/.agents/skills/supabase-postgres-best-practices/CHANGELOG.md
@@ -1,5 +1,49 @@
 # Changelog
 
+## [1.6.0](https://github.com/supabase/agent-skills/compare/supabase-postgres-best-practices-v1.5.0...supabase-postgres-best-practices-v1.6.0) (2026-07-30)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* **supabase-postgres-best-practices:** make skill description trigger-rich ([#194](https://github.com/supabase/agent-skills/issues/194)) ([3291216](https://github.com/supabase/agent-skills/commit/32912161e2732c3e5001c6811a76c1f8308ed0da))
+
+## [1.5.0](https://github.com/supabase/agent-skills/compare/supabase-postgres-best-practices-v1.4.0...supabase-postgres-best-practices-v1.5.0) (2026-07-30)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* **supabase-postgres-best-practices:** make skill description trigger-rich ([#194](https://github.com/supabase/agent-skills/issues/194)) ([3291216](https://github.com/supabase/agent-skills/commit/32912161e2732c3e5001c6811a76c1f8308ed0da))
+
+## [1.4.0](https://github.com/supabase/agent-skills/compare/v1.3.0...v1.4.0) (2026-07-10)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+
 ## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
 
 
diff --git a/plugins/supabase/.agents/skills/supabase-postgres-best-practices/SKILL.md b/plugins/supabase/.agents/skills/supabase-postgres-best-practices/SKILL.md
index d9ef1949..64007923 100644
--- a/plugins/supabase/.agents/skills/supabase-postgres-best-practices/SKILL.md
+++ b/plugins/supabase/.agents/skills/supabase-postgres-best-practices/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: supabase-postgres-best-practices
-description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
+description: "Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pg_cron, pgmq), vector/semantic search (pgvector), and restoring dumps (pg_restore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query."
 license: MIT
 metadata:
   author: supabase
diff --git a/plugins/supabase/.claude/skills/supabase-postgres-best-practices b/plugins/supabase/.claude/skills/supabase-postgres-best-practices
new file mode 120000
index 00000000..4990773c
--- /dev/null
+++ b/plugins/supabase/.claude/skills/supabase-postgres-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/supabase-postgres-best-practices
\ No newline at end of file
diff --git a/plugins/supabase/agent/skills/supabase-postgres-best-practices/CHANGELOG.md b/plugins/supabase/agent/skills/supabase-postgres-best-practices/CHANGELOG.md
index 94aee487..6d7d0d2a 100644
--- a/plugins/supabase/agent/skills/supabase-postgres-best-practices/CHANGELOG.md
+++ b/plugins/supabase/agent/skills/supabase-postgres-best-practices/CHANGELOG.md
@@ -1,5 +1,49 @@
 # Changelog
 
+## [1.6.0](https://github.com/supabase/agent-skills/compare/supabase-postgres-best-practices-v1.5.0...supabase-postgres-best-practices-v1.6.0) (2026-07-30)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* **supabase-postgres-best-practices:** make skill description trigger-rich ([#194](https://github.com/supabase/agent-skills/issues/194)) ([3291216](https://github.com/supabase/agent-skills/commit/32912161e2732c3e5001c6811a76c1f8308ed0da))
+
+## [1.5.0](https://github.com/supabase/agent-skills/compare/supabase-postgres-best-practices-v1.4.0...supabase-postgres-best-practices-v1.5.0) (2026-07-30)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* **supabase-postgres-best-practices:** make skill description trigger-rich ([#194](https://github.com/supabase/agent-skills/issues/194)) ([3291216](https://github.com/supabase/agent-skills/commit/32912161e2732c3e5001c6811a76c1f8308ed0da))
+
+## [1.4.0](https://github.com/supabase/agent-skills/compare/v1.3.0...v1.4.0) (2026-07-10)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+
 ## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
 
 
diff --git a/plugins/supabase/agent/skills/supabase-postgres-best-practices/SKILL.md b/plugins/supabase/agent/skills/supabase-postgres-best-practices/SKILL.md
index 6d6cbc4e..4d9916a9 100644
--- a/plugins/supabase/agent/skills/supabase-postgres-best-practices/SKILL.md
+++ b/plugins/supabase/agent/skills/supabase-postgres-best-practices/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: "Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations."
+description: "Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pg_cron, pgmq), vector/semantic search (pgvector), and restoring dumps (pg_restore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query."
 license: "MIT"
 metadata: {"author":"supabase","version":"1.1.1","organization":"Supabase","date":"January 2026","abstract":"Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation."}
 ---
diff --git a/plugins/supabase/skills-lock.json b/plugins/supabase/skills-lock.json
index 088ea295..e32ea8fd 100644
--- a/plugins/supabase/skills-lock.json
+++ b/plugins/supabase/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "supabase/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/supabase-postgres-best-practices/SKILL.md",
-      "computedHash": "0d2c4857a7d6fdcd3fbc46e458fa4c497f029cab89a01548b3defce203003932"
+      "computedHash": "e14e276241805c97dbcfe40dcbea1a3035269cc7293cac4b1832dda41a835e60"
     }
   }
 }
diff --git a/plugins/tiptap/.claude/skills/tiptap b/plugins/tiptap/.claude/skills/tiptap
new file mode 120000
index 00000000..afeaf9bf
--- /dev/null
+++ b/plugins/tiptap/.claude/skills/tiptap
@@ -0,0 +1 @@
+../../.agents/skills/tiptap
\ No newline at end of file
diff --git a/plugins/tsdown/.agents/skills/tsdown-migrate/SKILL.md b/plugins/tsdown/.agents/skills/tsdown-migrate/SKILL.md
index b6c83051..86a57f04 100644
--- a/plugins/tsdown/.agents/skills/tsdown-migrate/SKILL.md
+++ b/plugins/tsdown/.agents/skills/tsdown-migrate/SKILL.md
@@ -7,9 +7,16 @@ description: Migrate TypeScript library projects from tsup to tsdown. Provides c
 
 Knowledge base for AI agents to migrate tsup projects to tsdown — the Rolldown-powered library bundler.
 
+## Target Version: Two-Stage Migration
+
+tsdown v0.23 removed all previously-deprecated tsup compatibility options — `bundle`, `outExtension`, `publicDir`, `removeNodeProtocol`, `injectStyle`, and `skipNodeModulesBundle` are no longer recognized. They fail TypeScript type checking and are **silently ignored at runtime**, so a missed mapping on v0.23+ produces wrong output without any error. Migrating directly to v0.23+ is therefore unsafe. tsdown **v0.22.14** is the last version that still accepts these options and flags each one with a deprecation warning, making it the safe migration checkpoint. Migrate in **two stages**:
+
+1. **Stage 1 — migrate on `tsdown@0.22.14`**: Install `tsdown@0.22.14`, migrate the config per the tables below, run a build, and resolve **every** deprecation warning by mapping each flagged tsup option to its real tsdown equivalent. The warnings are the completeness check — the migration is not done until the build produces **zero warnings**.
+2. **Stage 2 — upgrade to the latest tsdown (`^0.23.0` or newer)**: Only after a warning-free build on 0.22.14. Since the config no longer uses any removed compat options, the silent-ignore behavior of v0.23+ is no longer a risk.
+
 ## Runtime Requirement
 
-`tsdown` requires **Node.js 22.18.0 or higher to run** (build-time only). The bundled output can still target lower Node.js versions via the [`target`](../tsdown/references/option-target.md) option, so a library that previously supported Node.js 18 / 20 with tsup can continue to do so after migrating.
+`tsdown` requires **Node.js `^22.18.0 || ^24.11.0 || >=26.0.0` to run** (build-time only) — that is, Node.js 22.18+, 24.11+, or 26+. Odd-numbered and EOL release lines (e.g. Node.js 23, 25) are not supported. The bundled output can still target lower Node.js versions via the [`target`](../tsdown/references/option-target.md) option, so a library that previously supported Node.js 18 / 20 with tsup can continue to do so after migrating.
 
 Recommended workflow when supporting Node.js 18 / 20:
 
@@ -31,9 +38,10 @@ Follow these steps to migrate a tsup project:
 2. **Update imports**: `'tsup'` → `'tsdown'`
 3. **Apply option mappings**: Rename/transform options per tables below
 4. **Preserve tsup defaults**: Explicitly set options that differ (format, clean, dts, target)
-5. **Update package.json**: Dependencies, scripts, root config field
+5. **Update package.json**: Dependencies (Stage 1: `tsdown@0.22.14`), scripts, root config field
 6. **Remove unsupported options**: Replace with alternatives where available
-7. **Test build**: Run `tsdown` and verify output
+7. **Test build on 0.22.14**: Run `tsdown` and resolve every deprecation warning — zero warnings required
+8. **Upgrade to latest tsdown** (`^0.23.0` or newer) and verify the build again
 
 ## Config File Migration
 
@@ -67,26 +75,28 @@ Replace all identifiers: `tsup` → `tsdown`, `TSUP` → `TSDOWN`.
 
 | tsup | tsdown | Notes |
 |------|--------|-------|
+| `entryPoints` | `entry` | Also deprecated in tsup itself |
 | `cjsInterop` | `cjsDefault` | CJS default export handling |
 | `esbuildPlugins` | `plugins` | Now uses Rolldown/Unplugin plugins |
 | `outExtension` | `outExtensions` | Custom output extensions |
-
-### Deprecated but Compatible
-
-These tsup options still work in tsdown for backward compatibility, but emit deprecation warnings and **will be removed in a future version**. Migrate them immediately.
-
-| tsup (deprecated) | tsdown (preferred) | Notes |
-|--------------------|--------------------|-------|
-| `entryPoints` | `entry` | Also deprecated in tsup itself |
 | `publicDir` | `copy` | Copy static files to output |
 | `bundle: true` | _(remove)_ | Bundle is default behavior |
 | `bundle: false` | `unbundle: true` | Preserve file structure |
 | `removeNodeProtocol: true` | `nodeProtocol: 'strip'` | Strip `node:` prefix |
 | `injectStyle: true` | `css: { inject: true }` | CSS injection |
 | `injectStyle: false` | _(remove)_ | Default behavior |
+| `skipNodeModulesBundle` | `deps: { neverBundle: true }` | Externalize all dependencies |
+
+None of the old names are recognized by tsdown v0.23+ — always emit the new names. The compatibility options (`outExtension`, `skipNodeModulesBundle`, `publicDir`, `bundle`, `removeNodeProtocol`, `injectStyle`) were accepted with deprecation warnings up to v0.22.14 and removed entirely in v0.23; on v0.23+ leftovers are silently ignored, not errors, so builds misbehave without warning. This is why Stage 1 runs on v0.22.14, where every leftover is flagged.
+
+### Deprecated but Still Accepted
+
+`external` and `noExternal` are the **only** tsup option names tsdown v0.23 still accepts. They emit deprecation warnings, will be removed in a future version, and cannot be combined with their replacements (mixing `external` with `deps.neverBundle`, or `noExternal` with `deps.alwaysBundle`, throws an error). Always emit the replacements.
+
+| tsup (deprecated) | tsdown (preferred) | Notes |
+|--------------------|--------------------|-------|
 | `external: [...]` | `deps: { neverBundle: [...] }` | Moved to deps namespace |
 | `noExternal: [...]` | `deps: { alwaysBundle: [...] }` | Moved to deps namespace |
-| `skipNodeModulesBundle` | `deps: { skipNodeModulesBundle: true }` | Moved to deps namespace |
 
 ### Output Filename Differences
 
@@ -114,6 +124,11 @@ export default defineConfig({
 
 tsdown also adds `deps.onlyBundle` (whitelist of allowed bundled packages) — no tsup equivalent.
 
+Dependency handling defaults in tsdown v0.23+:
+
+- `dependencies`, `peerDependencies`, and **`optionalDependencies`** are all externalized by default (tsup only externalizes `dependencies` and `peerDependencies`, so `optionalDependencies` may switch from bundled to external after migration).
+- `deps.resolveDepSubpath` (resolving subpath imports of externalized packages without an `exports` field) is **disabled by default**.
+
 ### Plugin Import Transforms
 
 ```ts
@@ -240,15 +255,15 @@ Use this checklist when performing a migration:
 - [ ] Rename tsup.config.* → tsdown.config.*
 - [ ] Update import from 'tsup' to 'tsdown'
 - [ ] Replace tsup/TSUP identifiers with tsdown/TSDOWN
-- [ ] Apply property renames (cjsInterop→cjsDefault, esbuildPlugins→plugins, outExtension→outExtensions)
-- [ ] Migrate deprecated options (publicDir→copy, bundle→unbundle, removeNodeProtocol→nodeProtocol, injectStyle→css.inject)
-- [ ] Move external/noExternal/skipNodeModulesBundle into deps namespace
+- [ ] Apply property renames (cjsInterop→cjsDefault, esbuildPlugins→plugins, outExtension→outExtensions, publicDir→copy, bundle→unbundle, removeNodeProtocol→nodeProtocol, injectStyle→css.inject)
+- [ ] Move external/noExternal into deps namespace, replace skipNodeModulesBundle with `deps.neverBundle: true`
 - [ ] Update unplugin imports from /esbuild to /rolldown
 - [ ] Set explicit defaults to preserve tsup behavior (format, clean, dts, target)
 - [ ] Remove unsupported options (splitting, metafile, swc, etc.)
 - [ ] Update package.json scripts (tsup→tsdown)
-- [ ] Update package.json dependencies
+- [ ] Update package.json dependencies (Stage 1: tsdown@0.22.14)
 - [ ] Rename root-level tsup config field if present
-- [ ] Run tsdown and verify build output
+- [ ] Run tsdown on 0.22.14 and resolve every deprecation warning (zero warnings required)
+- [ ] Upgrade to the latest tsdown (^0.23.0 or newer) and verify the build again
 - [ ] Suggest new tsdown features to the user
 ```
diff --git a/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-differences-detailed.md b/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-differences-detailed.md
index b7198ab2..c0d6465d 100644
--- a/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-differences-detailed.md
+++ b/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-differences-detailed.md
@@ -22,6 +22,12 @@ Comprehensive comparison of tsdown and tsup for understanding migration impact a
 | `dts` | `false` | Auto if `types`/`typings` in package.json | Types generated automatically — usually desired |
 | `target` | _(none)_ | Reads `engines.node` from package.json | Compilation target auto-detected — usually desired |
 
+### Dependency Handling Defaults (tsdown v0.23+)
+
+- `dependencies`, `peerDependencies`, and `optionalDependencies` are all externalized by default. tsup only externalizes `dependencies` and `peerDependencies`, so `optionalDependencies` may switch from bundled to external after migration.
+- Other imports resolved from `node_modules` are bundled with a warning, unless whitelisted via `deps.onlyBundle`.
+- `deps.resolveDepSubpath` (resolving subpath imports of externalized packages without an `exports` field) is disabled by default.
+
 ## Feature Compatibility
 
 ### Fully Supported (works the same)
@@ -43,24 +49,26 @@ Comprehensive comparison of tsdown and tsup for understanding migration impact a
 
 | Feature | tsup | tsdown | Change |
 |---------|------|--------|--------|
+| Entry points | `entryPoints` | `entry` | Also deprecated in tsup itself |
 | CJS interop | `cjsInterop` | `cjsDefault` | Property rename |
 | Plugins | `esbuildPlugins` | `plugins` | Different plugin format (Rolldown) |
 | Output extensions | `outExtension` | `outExtensions` | Property rename |
+| Copy files | `publicDir` | `copy` | Property rename |
+| Bundleless | `bundle: false` | `unbundle: true` | Inverted logic |
+| Strip node: | `removeNodeProtocol` | `nodeProtocol: 'strip'` | New option with more modes |
+| CSS inject | `injectStyle` | `css: { inject: true }` | Moved to css namespace |
+| Skip node_modules | `skipNodeModulesBundle` | `deps.neverBundle: true` | Externalize all dependencies |
 
-### Deprecated but Compatible
+None of the old names in this table are recognized by tsdown v0.23+. The compatibility options (`outExtension`, `skipNodeModulesBundle`, `publicDir`, `bundle`, `removeNodeProtocol`, `injectStyle`) were accepted with deprecation warnings up to v0.22.14 and removed entirely in v0.23 — on v0.23+ leftovers are silently ignored at runtime. Always emit the tsdown names, and migrate in two stages (build on `tsdown@0.22.14` until zero deprecation warnings remain, then upgrade to `^0.23.0`+ — see SKILL.md).
 
-These tsup options still work in tsdown but emit deprecation warnings. They will be removed in a future version — migrate immediately.
+### Deprecated but Still Accepted
+
+`external` and `noExternal` are the only tsup option names tsdown v0.23 still accepts. They emit deprecation warnings, will be removed in a future version, and cannot be combined with their replacements (mixing them throws an error) — migrate immediately.
 
 | Feature | tsup (deprecated) | tsdown (preferred) | Change |
 |---------|-------------------|--------------------|--------|
-| Entry points | `entryPoints` | `entry` | Also deprecated in tsup itself |
-| Copy files | `publicDir` | `copy` | Property rename |
-| Bundleless | `bundle: false` | `unbundle: true` | Inverted logic |
-| Strip node: | `removeNodeProtocol` | `nodeProtocol: 'strip'` | New option with more modes |
-| CSS inject | `injectStyle` | `css: { inject: true }` | Moved to css namespace |
 | External deps | `external` | `deps.neverBundle` | Moved to deps namespace |
 | Inline deps | `noExternal` | `deps.alwaysBundle` | Moved to deps namespace |
-| Skip node_modules | `skipNodeModulesBundle` | `deps.skipNodeModulesBundle` | Moved to deps namespace |
 
 ### Output Filename Differences
 
diff --git a/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-option-mappings.md b/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-option-mappings.md
index 6acf5a0f..ee0de5a5 100644
--- a/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-option-mappings.md
+++ b/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-option-mappings.md
@@ -40,11 +40,23 @@ Note: All `unplugin-*/esbuild` imports must change to `unplugin-*/rolldown`.
 
 ### outExtension → outExtensions
 
-`outExtension` was renamed to `outExtensions`.
+```ts
+// Before (tsup)
+export default defineConfig({
+  outExtension: ({ format }) => ({ js: format === 'cjs' ? '.cjs' : '.mjs' }),
+})
+
+// After (tsdown)
+export default defineConfig({
+  outExtensions: ({ format }) => ({ js: format === 'cjs' ? '.cjs' : '.mjs' }),
+})
+```
 
-## Deprecated but Compatible
+The callback shape is compatible for the `js` key; tsdown's version can additionally return a `dts` extension.
 
-These options still work in tsdown for backward compatibility but emit deprecation warnings. Migrate them immediately — they will be removed in a future version.
+## Removed Compatibility Options
+
+tsdown v0.23 removed these previously-deprecated tsup compatibility options entirely. They are no longer recognized — TypeScript reports them as unknown properties and they are **silently ignored at runtime**, so leftovers make builds misbehave without any error. Always replace them with the tsdown equivalents, and verify on `tsdown@0.22.14` (the last version that flags each of them with a deprecation warning): a zero-warning build confirms the mapping is complete before upgrading to v0.23+ (see SKILL.md's two-stage flow).
 
 ### entryPoints → entry
 
@@ -130,6 +142,26 @@ export default defineConfig({
 
 `injectStyle: false` should be removed (it's the default).
 
+### skipNodeModulesBundle → deps.neverBundle
+
+```ts
+// Before (tsup)
+export default defineConfig({
+  skipNodeModulesBundle: true,
+})
+
+// After (tsdown)
+export default defineConfig({
+  deps: { neverBundle: true },
+})
+```
+
+`deps.neverBundle: true` externalizes **all** dependencies; use `deps.alwaysBundle` to opt specific imports back into the bundle.
+
+## Deprecated but Still Accepted
+
+`external` and `noExternal` are the only tsup option names tsdown v0.23 still accepts. They emit deprecation warnings and will be removed in a future version — always emit the replacements. Combining the old and new forms (e.g. `external` together with `deps.neverBundle`) throws an error.
+
 ### external → deps.neverBundle
 
 ```ts
diff --git a/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-package-json.md b/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-package-json.md
index 71ae30bf..c807859f 100644
--- a/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-package-json.md
+++ b/plugins/tsdown/.agents/skills/tsdown-migrate/references/guide-package-json.md
@@ -39,10 +39,22 @@ Rename `tsup` to `tsdown` in whichever dependency field it appears:
   }
 }
 
-// After
+// After (Stage 1 — migration checkpoint)
+{
+  "devDependencies": {
+    "tsdown": "0.22.14",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+Use **`0.22.14` for Stage 1** — the last tsdown version that still accepts the deprecated tsup compatibility options and flags each one with a deprecation warning. Run the build on 0.22.14 and resolve every warning; v0.23+ silently ignores the removed options, so the warnings are the only reliable completeness check. Once the build is warning-free, upgrade to the latest tsdown (**Stage 2**):
+
+```json
+// Final state (Stage 2 — after a zero-warning build on 0.22.14)
 {
   "devDependencies": {
-    "tsdown": "^0.21.3",
+    "tsdown": "^0.23.0",
     "typescript": "^5.0.0"
   }
 }
@@ -50,13 +62,13 @@ Rename `tsup` to `tsdown` in whichever dependency field it appears:
 
 ### All Dependency Fields
 
-| Field | tsup version | tsdown version |
-|-------|-------------|----------------|
-| `dependencies` | any | latest tsdown |
-| `devDependencies` | any | latest tsdown |
-| `optionalDependencies` | any | latest tsdown |
-| `peerDependencies` | any | `*` |
-| `peerDependenciesMeta` | rename key only | rename key only |
+| Field | tsup version | Stage 1 (migration) | Stage 2 (final) |
+|-------|-------------|---------------------|-----------------|
+| `dependencies` | any | `0.22.14` | `^0.23.0` |
+| `devDependencies` | any | `0.22.14` | `^0.23.0` |
+| `optionalDependencies` | any | `0.22.14` | `^0.23.0` |
+| `peerDependencies` | any | `*` | `*` |
+| `peerDependenciesMeta` | rename key only | rename key only | rename key only |
 
 ## Root Config Field
 
diff --git a/plugins/tsdown/.agents/skills/tsdown/SKILL.md b/plugins/tsdown/.agents/skills/tsdown/SKILL.md
index 849e65d9..ce012c83 100644
--- a/plugins/tsdown/.agents/skills/tsdown/SKILL.md
+++ b/plugins/tsdown/.agents/skills/tsdown/SKILL.md
@@ -66,13 +66,13 @@ export default defineConfig({
 | CLI Reference | All CLI commands and options | [reference-cli](references/reference-cli.md) |
 | Migrate from tsup | Migration guide and compatibility notes | [guide-migrate-from-tsup](references/guide-migrate-from-tsup.md) |
 | Plugins | Rolldown, Rollup, Unplugin support | [advanced-plugins](references/advanced-plugins.md) |
-
-> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`
 | Hooks | Lifecycle hooks for custom logic | [advanced-hooks](references/advanced-hooks.md) |
-| Programmatic API | Build from Node.js scripts | [advanced-programmatic](references/advanced-programmatic.md) |
+| Programmatic API | Build from Node.js scripts, in-memory builds (`write: false`) | [advanced-programmatic](references/advanced-programmatic.md) |
 | Rolldown Options | Pass options directly to Rolldown | [advanced-rolldown-options](references/advanced-rolldown-options.md) |
 | CI Environment | CI detection, `'ci-only'` / `'local-only'` values | [advanced-ci](references/advanced-ci.md) |
 
+> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`
+
 ## Build Options
 
 | Option | Usage | Reference |
@@ -88,7 +88,7 @@ export default defineConfig({
 | Source maps | `sourcemap: true`, `'inline'`, `'hidden'` | [option-sourcemap](references/option-sourcemap.md) |
 | Watch mode | `watch: true`, watch options | [option-watch-mode](references/option-watch-mode.md) |
 | Cleaning | `clean: true`, clean patterns | [option-cleaning](references/option-cleaning.md) |
-| Log level | `logLevel: 'silent'`, `failOnWarn: false` | [option-log-level](references/option-log-level.md) |
+| Log level | `logLevel: 'silent'`, `failOnWarn: false`, `suppressWarnings: [...]` | [option-log-level](references/option-log-level.md) |
 
 ## Dependency Handling
 
@@ -97,7 +97,9 @@ export default defineConfig({
 | Never bundle | `deps: { neverBundle: ['react', /^@myorg\//] }` | [option-dependencies](references/option-dependencies.md) |
 | Always bundle | `deps: { alwaysBundle: ['dep-to-bundle'] }` | [option-dependencies](references/option-dependencies.md) |
 | Only bundle | `deps: { onlyBundle: ['cac', 'bumpp'] }` - Whitelist | [option-dependencies](references/option-dependencies.md) |
-| Skip node_modules | `deps: { skipNodeModulesBundle: true }` | [option-dependencies](references/option-dependencies.md) |
+| Only import | `deps: { onlyImport: ['cac'] }` - Whitelist runtime imports in output | [option-dependencies](references/option-dependencies.md) |
+| Externalize all | `deps: { neverBundle: true }` | [option-dependencies](references/option-dependencies.md) |
+| Resolve subpaths | `deps: { resolveDepSubpath: true }` - Resolve external subpath imports (default `false`) | [option-dependencies](references/option-dependencies.md) |
 | Auto external | Automatic dependency/peer/optional externalization | [option-dependencies](references/option-dependencies.md) |
 
 ## Output Enhancement
@@ -110,6 +112,7 @@ export default defineConfig({
 | CSS handling | **[experimental]** `css: { ... }` — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires `@tsdown/css` | [option-css](references/option-css.md) |
 | CSS modules | `css: { modules: { localsConvention: 'camelCase' } }` — scoped class names for `.module.css` files | [option-css](references/option-css.md) |
 | CSS inject | `css: { inject: true }` — preserve CSS imports in JS output | [option-css](references/option-css.md) |
+| Copy files | `copy: 'public'` or `copy: { from, to, flatten, rename }` - Copy static assets to output | [option-copy](references/option-copy.md) |
 | Unbundle mode | `unbundle: true` - Preserve directory structure | [option-unbundle](references/option-unbundle.md) |
 | Root directory | `root: 'src'` - Control output directory mapping | [option-root](references/option-root.md) |
 | Executable | **[experimental]** `exe: true` - Bundle as standalone executable, cross-platform via `@tsdown/exe` | [option-exe](references/option-exe.md) |
@@ -342,6 +345,7 @@ tsdown --minify                # Enable minification
 tsdown --dts                   # Generate declarations
 tsdown --exe                   # Bundle as standalone executable
 tsdown --unbundle              # Bundleless mode
+tsdown --copy public           # Copy static files to output
 
 # Entry options
 tsdown src/index.ts            # Single entry
@@ -352,6 +356,7 @@ tsdown src/a.ts src/b.ts       # Multiple entries
 tsdown -W                      # Enable workspace mode
 tsdown -W -F my-package        # Filter specific package
 tsdown --filter /^pkg-/        # Filter by regex
+tsdown -W --concurrency 4      # Limit parallel Rolldown builds
 
 # Development
 tsdown --watch                 # Watch mode
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/README.md b/plugins/tsdown/.agents/skills/tsdown/references/README.md
index fdbc6bd2..b75e0a6c 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/README.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/README.md
@@ -2,14 +2,14 @@
 
 This directory contains detailed reference documentation for the tsdown skill.
 
-## Created Files (35 total)
+## Created Files (38 total)
 
 ### Core Guides (3)
 - ✅ `guide-getting-started.md` - Installation, first bundle, CLI basics
 - ✅ `guide-migrate-from-tsup.md` - Migration guide from tsup
 - ✅ `guide-introduction.md` - Introduction and key features
 
-### Configuration Options (20)
+### Configuration Options (22)
 - ✅ `option-config-file.md` - Config file formats, loaders, workspace
 - ✅ `option-entry.md` - Entry point configuration with globs
 - ✅ `option-output-format.md` - Output formats (ESM, CJS, IIFE, UMD)
@@ -27,6 +27,8 @@ This directory contains detailed reference documentation for the tsdown skill.
 - ✅ `option-package-exports.md` - Auto-generate package.json exports
 - ✅ `option-css.md` - CSS handling (experimental, full pipeline: preprocessors, Lightning CSS, PostCSS, code splitting)
 - ✅ `option-unbundle.md` - Preserve directory structure
+- ✅ `option-root.md` - Root directory for output structure mapping
+- ✅ `option-copy.md` - Copy static files to output
 - ✅ `option-cjs-default.md` - CommonJS default export handling
 - ✅ `option-log-level.md` - Logging configuration
 - ✅ `option-lint.md` - Package validation (publint & attw)
@@ -56,7 +58,7 @@ This directory contains detailed reference documentation for the tsdown skill.
 
 ## Coverage Status
 
-**Created:** 35 files (100% complete)
+**Created:** 38 files (100% complete)
 
 ## Current Skill Features
 
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/advanced-programmatic.md b/plugins/tsdown/.agents/skills/tsdown/references/advanced-programmatic.md
index 092ec60f..efd27fa2 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/advanced-programmatic.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/advanced-programmatic.md
@@ -36,6 +36,39 @@ await build({
 })
 ```
 
+### In-Memory Output
+
+Set `write: false` to access generated chunks and assets without writing the
+bundle output to disk:
+
+```ts
+import { build } from 'tsdown'
+
+const bundles = await build({
+  entry: ['src/index.ts'],
+  format: 'esm',
+  write: false,
+  clean: false,
+})
+
+for (const bundle of bundles) {
+  for (const output of bundle.chunks) {
+    const contents = output.type === 'chunk' ? output.code : output.source
+    console.log(output.fileName, contents)
+  }
+}
+```
+
+`build()` currently returns a `TsdownBundle[]`, with one bundle for each
+resolved configuration. Even a single configuration returns an array; its
+in-memory Rolldown outputs are available in `bundle.chunks`.
+
+The `write` option controls Rolldown's bundle output, while other file operations
+are configured separately. For example, `clean` defaults to `true`, so set
+`clean: false` as above if existing output directories must remain untouched.
+Explicitly enabled features such as `copy` or `exports` may still write files.
+`write: false` is incompatible with watch mode.
+
 ## API Reference
 
 ### build()
@@ -52,7 +85,7 @@ await build(options)
 - `options` - Build configuration object (same as config file)
 
 **Returns:**
-- `Promise<void>` - Resolves when build completes
+- `Promise<TsdownBundle[]>` - One bundle for each resolved configuration
 
 **Throws:**
 - Build errors if compilation fails
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/advanced-rolldown-options.md b/plugins/tsdown/.agents/skills/tsdown/references/advanced-rolldown-options.md
index 2a35044b..532243b5 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/advanced-rolldown-options.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/advanced-rolldown-options.md
@@ -6,7 +6,7 @@ Pass options directly to the underlying Rolldown bundler.
 
 tsdown uses [Rolldown](https://rolldown.rs) as its core bundling engine. You can override Rolldown's input and output options directly for fine-grained control.
 
-**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/options/input) documentation.
+**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/reference/InputOptions.input) documentation.
 
 ## Input Options
 
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/guide-migrate-from-tsup.md b/plugins/tsdown/.agents/skills/tsdown/references/guide-migrate-from-tsup.md
index b0568e50..8a264552 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/guide-migrate-from-tsup.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/guide-migrate-from-tsup.md
@@ -46,7 +46,50 @@ npx tsdown-migrate packages/foo packages/bar
 
 | tsup | tsdown |
 |------|--------|
+| `entryPoints` | `entry` |
+| `cjsInterop` | `cjsDefault` |
+| `esbuildPlugins` | `plugins` |
 | `outExtension` | `outExtensions` |
+| `skipNodeModulesBundle` | `deps: { neverBundle: true }` |
+| `publicDir` | `copy` |
+| `bundle: false` | `unbundle: true` |
+| `removeNodeProtocol: true` | `nodeProtocol: 'strip'` |
+| `injectStyle: true` | `css: { inject: true }` |
+
+The old names were accepted (with deprecation warnings) up to tsdown v0.22.14 and have been removed since — v0.23+ silently ignores them, so a leftover tsup option won't error. Migrate in two stages: install `tsdown@0.22.14` first and resolve every deprecation warning (a warning-free build proves the mapping is complete), then upgrade to the latest version. The `tsdown-migrate` tool installs v0.22.14 for this reason.
+
+### Deprecated but Compatible Options
+
+These tsup options still work but emit deprecation warnings and will be removed in a future version — migrate them immediately:
+
+| tsup (deprecated) | tsdown (preferred) |
+|-------------------|--------------------|
+| `external: [...]` | `deps: { neverBundle: [...] }` |
+| `noExternal: [...]` | `deps: { alwaysBundle: [...] }` |
+
+tsdown also adds `deps.onlyBundle` for whitelisting allowed bundled packages.
+
+### Unsupported Options
+
+| Option | Status | Alternative |
+|--------|--------|-------------|
+| `splitting: false` | Always enabled | Code splitting cannot be disabled |
+| `metafile` | Not available | Use `devtools: true` for bundle analysis via Vite DevTools |
+| `swc` | Not supported | tsdown uses oxc for transformation (built-in) |
+| `experimentalDts` | Superseded | Use the `dts` option instead |
+| `legacyOutput` | Not supported | No alternative |
+| `plugins` (tsup experimental) | Incompatible | Migrate to Rolldown plugins |
+
+### Plugin System
+
+tsdown uses Rolldown plugins instead of esbuild plugins. If you use unplugin plugins, update the import path:
+
+```ts
+// Before (tsup)
+import plugin from 'unplugin-example/esbuild'
+// After (tsdown)
+import plugin from 'unplugin-example/rolldown'
+```
 
 ### Output Filename Differences
 
@@ -72,6 +115,16 @@ export default defineConfig({
 })
 ```
 
+#### Other tsdown-Exclusive Features
+
+- **`exports`**: Auto-generate the `exports` field in `package.json` with `exports: true`
+- **`publint`** / **`attw`**: Validate your package for common issues and type correctness
+- **`exe`**: Bundle as a Node.js standalone executable (SEA) with `exe: true`
+- **`devtools`**: Vite DevTools integration for bundle analysis with `devtools: true`
+- **`hooks`**: Lifecycle hooks (`build:prepare`, `build:before`, `build:done`)
+- **`css`**: Full CSS pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, and code splitting
+- **`globImport`**: Support for `import.meta.glob` (Vite-style glob imports)
+
 ## Migration Checklist
 
 1. **Backup your code** - Commit all changes
@@ -186,7 +239,7 @@ Some tsup features are not yet available. Check [GitHub issues](https://github.c
 tsdown should be faster than tsup. If not:
 1. Enable `isolatedDeclarations` for faster DTS generation
 2. Check for large dependencies being bundled
-3. Use `skipNodeModulesBundle` if needed
+3. Use `deps.neverBundle: true` if needed
 
 ## Getting Help
 
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-cjs-default.md b/plugins/tsdown/.agents/skills/tsdown/references/option-cjs-default.md
index 85ba705e..87280634 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/option-cjs-default.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-cjs-default.md
@@ -4,7 +4,7 @@ Control how default exports are handled in CommonJS output.
 
 ## Overview
 
-The `cjsDefault` option improves compatibility when generating CommonJS modules. When enabled (default), modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.
+The `cjsDefault` option improves compatibility when generating CommonJS **entry** modules. When enabled (default), entry modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.
 
 ## Type
 
@@ -80,6 +80,21 @@ exports.default = greet
 
 Consumers need `require('your-module').default`.
 
+## Entry Modules Only
+
+`cjsDefault` only applies to **explicit entry modules**. In [unbundle mode](option-unbundle.md), imported modules that are emitted as non-entry chunks keep named CJS exports such as `exports.default`. CJS is considered legacy and is supported in maintenance-only mode, so this behavior will not be extended to non-entry chunks.
+
+If every source module is intended to be consumed independently, include all of them as entries:
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts'],
+  root: 'src',
+  format: 'cjs',
+  unbundle: true,
+})
+```
+
 ## When to Disable
 
 - When your module has both default and named exports
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-copy.md b/plugins/tsdown/.agents/skills/tsdown/references/option-copy.md
new file mode 100644
index 00000000..8d8b9b23
--- /dev/null
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-copy.md
@@ -0,0 +1,111 @@
+# Copy Files
+
+Copy static files and directories into the build output.
+
+## Overview
+
+The `copy` option copies assets that should be distributed without being processed by the bundler — images, fonts, license files, etc.
+
+## Basic Usage
+
+### CLI
+
+```bash
+tsdown --copy public
+```
+
+With the default `outDir` of `dist`, `public/favicon.svg` is copied to `dist/public/favicon.svg`.
+
+### Config File
+
+```ts
+export default defineConfig({
+  copy: 'public',
+})
+```
+
+Multiple paths, glob patterns, or object entries in an array:
+
+```ts
+export default defineConfig({
+  copy: [
+    'LICENSE',
+    {
+      from: ['public/**/*', '!public/**/*.map'],
+      to: 'dist/assets',
+      flatten: false,
+    },
+  ],
+})
+```
+
+Glob patterns support negation with a leading `!`.
+
+**Note:** Relative source and destination paths are resolved from the project root (`cwd`), not from `outDir`.
+
+## Object Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `from` | `string \| string[]` | Required | Source path or glob pattern; arrays can include negated patterns |
+| `to` | `string` | `outDir` | Destination path, resolved from the project root |
+| `flatten` | `boolean` | `true` | Place matched files directly in `to`. Set `false` to preserve the directory structure below the first segment |
+| `rename` | `string \| ((name, extension, fullPath) => string)` | — | Change the destination name. Callback receives the extension without a leading dot and the absolute path |
+| `verbose` | `boolean` | `false` | Log each copied source and destination |
+
+### Preserve Directory Structure
+
+```ts
+export default defineConfig({
+  copy: {
+    from: 'assets/**/*',
+    to: 'dist/public',
+    flatten: false,
+  },
+})
+```
+
+`assets/fonts/inter.woff2` → `dist/public/fonts/inter.woff2`.
+
+### Rename Copied Items
+
+```ts
+export default defineConfig({
+  copy: [
+    { from: 'src/file.txt', to: 'dist', rename: 'file.md' },
+    {
+      from: 'src/file.txt',
+      to: 'dist',
+      rename: (name, extension) => `${name}-renamed.${extension}`,
+    },
+  ],
+})
+```
+
+Creates `dist/file.md` and `dist/file-renamed.txt`.
+
+## Dynamic Configuration
+
+`copy` can be a sync or async callback receiving the resolved tsdown config:
+
+```ts
+export default defineConfig({
+  copy: ({ outDir }) => ({
+    from: ['assets/**/*', '!assets/**/*.map'],
+    to: `${outDir}/assets`,
+    flatten: false,
+  }),
+})
+```
+
+## Build and Watch Behavior
+
+- Copying runs after the bundle output is produced; files are copied without passing through Rolldown transforms.
+- A top-level `copy` option runs only once for a multi-format build; a format-specific override can define `copy` again for that format.
+- In watch mode, matched source files are watched as build dependencies — changing one triggers a rebuild and copies the current files again.
+
+## Related Options
+
+- [Output Directory](option-output-directory.md) - Where output goes
+- [Cleaning](option-cleaning.md) - Output directory cleanup
+- [Watch Mode](option-watch-mode.md) - Watch mode behavior
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-css.md b/plugins/tsdown/.agents/skills/tsdown/references/option-css.md
index 4a0c692d..065f9d61 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/option-css.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-css.md
@@ -222,6 +222,26 @@ export default defineConfig({
 
 Set `css.modules: false` to disable. Function-form `generateScopedName` requires `transformer: 'postcss'`.
 
+`localsConvention` also accepts a function compatible with Vite and
+`postcss-modules`:
+
+```ts
+export default defineConfig({
+  css: {
+    modules: {
+      localsConvention: (
+        originalClassName,
+        generatedClassName,
+        inputFile,
+      ) => originalClassName.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase()),
+    },
+  },
+})
+```
+
+The function form works with both CSS transformers and returns the JavaScript
+export key.
+
 ### Optional Dependencies (PostCSS path)
 
 ```bash
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-dependencies.md b/plugins/tsdown/.agents/skills/tsdown/references/option-dependencies.md
index 52e9b9ae..ffe3dc6e 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/option-dependencies.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-dependencies.md
@@ -33,7 +33,8 @@ export default defineConfig({
     neverBundle: ['react', /^@myorg\//],
     alwaysBundle: ['some-package'],
     onlyBundle: ['cac', 'bumpp'],
-    skipNodeModulesBundle: true,
+    onlyImport: ['cac'],
+    resolveDepSubpath: true,
   },
 })
 ```
@@ -56,6 +57,19 @@ export default defineConfig({
 })
 ```
 
+Set to `true` to externalize ALL dependencies:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  deps: {
+    neverBundle: true,
+  },
+})
+```
+
+**Result:** Every import that follows npm package naming conventions is externalized as written, without being resolved. This is fast and even works when dependencies are not installed. Subpaths like `my-dep/utils` are preserved exactly (`resolveDepSubpath` has no effect). Other non-relative imports (`#` subpath imports, path aliases like `~/`) are resolved: they stay external if they resolve into node_modules, and are bundled if they map to local files. Combine with `alwaysBundle` to bundle selected dependencies.
+
 ### `deps.alwaysBundle`
 
 Force dependencies to be bundled:
@@ -96,22 +110,41 @@ export default defineConfig({
 
 **Note:** Include all sub-dependencies in the list, not just top-level imports.
 
-### `deps.skipNodeModulesBundle`
+### `deps.onlyImport`
 
-Skip bundling ALL node_modules:
+Whitelist of packages the emitted output is allowed to import at runtime. Throws an error (listing all violations) if any chunk imports an unlisted package:
 
 ```ts
 export default defineConfig({
   entry: ['src/index.ts'],
   deps: {
-    skipNodeModulesBundle: true,
+    onlyImport: [
+      'cac',               // Also covers subpath imports like cac/deno
+      /^my-utils/,         // Regex patterns match the package name
+    ],
   },
 })
 ```
 
-**Result:** No dependencies from node_modules are bundled.
+**Behavior:**
+- Matching is based on the package name; subpath imports (`cac/deno`) match `cac`.
+- Node.js built-in modules are always allowed when `platform` is `node`.
+- Relative imports between code-split chunks are always allowed.
+- Declaration output (`.d.ts`) is checked too.
+
+**Limitation:** ES imports and dynamic `import()` expressions are checked. CJS `require()` calls are not detected.
 
-**Note:** Cannot be used together with `alwaysBundle`.
+### `deps.resolveDepSubpath`
+
+By default, tsdown preserves external dependency subpath imports as written. Enable `resolveDepSubpath` to resolve subpath imports to their actual package-relative paths when a package has no `exports` field. For example, `my-dep/functions/lt` may become `my-dep/functions/lt.js`, and `my-dep/folder` may become `my-dep/folder/index.js`.
+
+```ts
+export default defineConfig({
+  deps: {
+    resolveDepSubpath: true,  // default: false
+  },
+})
+```
 
 ## Common Patterns
 
@@ -224,21 +257,12 @@ tsdown --deps.never-bundle react --deps.never-bundle react-dom
 tsdown --deps.never-bundle '/^@myorg\/.*/'
 ```
 
-### Skip Node Modules
-
-```bash
-tsdown --deps.skip-node-modules-bundle
-```
-
 ## Migration from Deprecated Options
 
 | Deprecated Option | New Option |
 |---|---|
 | `external` | `deps.neverBundle` |
 | `noExternal` | `deps.alwaysBundle` |
-| `inlineOnly` | `deps.onlyBundle` |
-| `deps.onlyAllowBundle` | `deps.onlyBundle` |
-| `skipNodeModulesBundle` | `deps.skipNodeModulesBundle` |
 
 ## Examples by Use Case
 
@@ -362,7 +386,9 @@ export default defineConfig({
 - `neverBundle` → Force external
 - `alwaysBundle` → Force bundled
 - `onlyBundle` → Whitelist bundled deps
-- `skipNodeModulesBundle` → Skip all node_modules
+- `onlyImport` → Whitelist runtime imports in output
+- `neverBundle: true` → Externalize all dependencies
+- `resolveDepSubpath: true` → Resolve external dependency subpath imports to package-relative paths
 
 **Declaration files:**
 - Same bundling logic as JavaScript
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-exe.md b/plugins/tsdown/.agents/skills/tsdown/references/option-exe.md
index db06e2ac..4c335b22 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/option-exe.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-exe.md
@@ -4,7 +4,7 @@
 
 ## Requirements
 
-- Node.js >= 25.5.0 (ESM support requires >= 25.7.0)
+- Node.js >= 25.7.0
 - Not supported in Bun or Deno
 
 ## Basic Usage
@@ -18,7 +18,6 @@ export default defineConfig({
 
 ## Behavior When Enabled
 
-- Default output format changes from `esm` to `cjs` (unless Node.js >= 25.7.0)
 - Declaration file generation (`dts`) is disabled by default
 - Code splitting is disabled
 - Only single entry points are supported
@@ -97,7 +96,25 @@ dist/
 |-------|------|-------------|
 | `platform` | `'win' \| 'darwin' \| 'linux'` | Target OS (nodejs.org naming) |
 | `arch` | `'x64' \| 'arm64'` | Target CPU architecture |
-| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`) |
+| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`), or `'latest'` / `'latest-lts'` to resolve automatically |
+
+### Custom Node.js Index and Download URL
+
+When downloading Node.js binaries (e.g. behind a corporate proxy or using a mirror), you can customize the sources:
+
+```ts
+export default defineConfig({
+  entry: ['src/cli.ts'],
+  exe: {
+    targets: [{ platform: 'linux', arch: 'x64', nodeVersion: 'latest-lts' }],
+    // Index used to resolve 'latest' / 'latest-lts' versions
+    nodeDistIndexUrl: 'https://mirrors.example.com/node/index.json', // default: https://nodejs.org/dist/index.json
+    // Fully custom download URL per target
+    getDownloadUrl: (target) =>
+      `https://mirrors.example.com/node/v${target.nodeVersion}/node-v${target.nodeVersion}-${target.platform}-${target.arch}.tar.gz`,
+  },
+})
+```
 
 ### Caching
 
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-log-level.md b/plugins/tsdown/.agents/skills/tsdown/references/option-log-level.md
index 9b5706d4..f48712f7 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/option-log-level.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-log-level.md
@@ -84,6 +84,40 @@ export default defineConfig({
 
 See [CI Environment](advanced-ci.md) for more about CI-aware options.
 
+## Suppressing Warnings
+
+The `suppressWarnings` option silences warnings whose message matches a given pattern. This is useful for opting out of non-actionable notices (such as the TypeScript 7.0 experimental API warning) while keeping other warnings visible.
+
+### Type
+
+```ts
+suppressWarnings?:
+  | string
+  | RegExp
+  | Array<string | RegExp>
+  | ((msg: string) => boolean)
+```
+
+- **string** – substring match
+- **RegExp** – regular expression match
+- **array** – matches if any entry matches
+- **function** – custom predicate
+
+### Usage
+
+```ts
+export default defineConfig({
+  suppressWarnings: [
+    'is experimental',        // substring match
+    /Circular dependency/,    // regexp match
+  ],
+  // Or a predicate function:
+  // suppressWarnings: (msg) => msg.includes('is experimental'),
+})
+```
+
+Matched warnings are dropped **before** `failOnWarn` is applied, so a suppressed warning will not fail the build even when `failOnWarn: true`.
+
 ## Related Options
 
 - [CI Environment](advanced-ci.md) - CI-aware option details
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-output-format.md b/plugins/tsdown/.agents/skills/tsdown/references/option-output-format.md
index 6f9852e3..ca03d7c3 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/option-output-format.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-output-format.md
@@ -15,6 +15,8 @@ tsdown can generate bundles in multiple formats. Default is ESM.
 | `iife` | Immediately Invoked Function Expression | Browser `<script>` tags |
 | `umd` | Universal Module Definition | AMD, CommonJS, and globals |
 
+**Note:** CJS is in **maintenance-only mode**. Since the ecosystem is transitioning to ESM and Node.js now supports `require(esm)`, tsdown's CJS-specific features (such as `cjsDefault`) are kept for compatibility but will not be further enhanced or optimized. New libraries are encouraged to publish ESM-only.
+
 ## Usage
 
 ### CLI
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/option-target.md b/plugins/tsdown/.agents/skills/tsdown/references/option-target.md
index d470c3a9..70bb4535 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/option-target.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/option-target.md
@@ -80,17 +80,21 @@ export default defineConfig({
 
 ## Supported Targets
 
-### ECMAScript Versions
+tsdown (Rolldown) uses [Oxc](https://oxc.rs/docs/guide/usage/transformer/lowering#target) for syntax lowering. The following environment names are supported (with version numbers, e.g. `chrome100`, `node18`, `es2020`):
 
-- `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `esnext`
+- **ECMAScript versions**: `es2015`, `es2016`, ..., `es2025`, `esnext`
+- **Browsers**: `chrome`, `edge`, `firefox`, `ie`, `ios`, `opera`, `safari`, `samsung`
+- **Runtimes**: `node`, `deno`, `hermes`, `rhino`
 
-### Browser Versions
+### Baseline Widely Available
 
-- `chrome100`, `safari18`, `firefox110`, `edge100`, etc.
+The special target `'baseline-widely-available'` expands to the browser versions covered by [Baseline Widely Available](https://web.dev/baseline) (e.g. `chrome111`, `edge111`, `firefox114`, `safari16.4`, `ios16.4`):
 
-### Node.js Versions
-
-- `node16`, `node18`, `node20`, `node20.18`, etc.
+```ts
+export default defineConfig({
+  target: 'baseline-widely-available',
+})
+```
 
 ## Examples
 
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/recipe-react.md b/plugins/tsdown/.agents/skills/tsdown/references/recipe-react.md
index cc56d8dd..5c2fc6a5 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/recipe-react.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/recipe-react.md
@@ -99,18 +99,19 @@ export default defineConfig({
 
 ## React Compiler
 
-React Compiler automatically optimizes React code at build time.
+React Compiler automatically optimizes React code at build time. It is currently available only as a Babel plugin. You can scaffold the `react-compiler` starter template (`npx create-tsdown@latest -t react-compiler`) or integrate it manually.
 
 ### Install Dependencies
 
 ```bash
-pnpm add -D @rollup/plugin-babel babel-plugin-react-compiler
+pnpm add -D @rolldown/plugin-babel @vitejs/plugin-react
 ```
 
 ### Configure
 
 ```ts
-import pluginBabel from '@rollup/plugin-babel'
+import pluginBabel from '@rolldown/plugin-babel'
+import { reactCompilerPreset } from '@vitejs/plugin-react'
 
 export default defineConfig({
   entry: ['src/index.tsx'],
@@ -120,13 +121,7 @@ export default defineConfig({
   },
   plugins: [
     pluginBabel({
-      babelHelpers: 'bundled',
-      parserOpts: {
-        sourceType: 'module',
-        plugins: ['jsx', 'typescript'],
-      },
-      plugins: ['babel-plugin-react-compiler'],
-      extensions: ['.js', '.jsx', '.ts', '.tsx'],
+      presets: [reactCompilerPreset()],
     }),
   ],
   dts: true,
diff --git a/plugins/tsdown/.agents/skills/tsdown/references/reference-cli.md b/plugins/tsdown/.agents/skills/tsdown/references/reference-cli.md
index fa4fa571..8213687d 100644
--- a/plugins/tsdown/.agents/skills/tsdown/references/reference-cli.md
+++ b/plugins/tsdown/.agents/skills/tsdown/references/reference-cli.md
@@ -52,9 +52,10 @@ tsdown --no-config src/index.ts
 
 ### `--config-loader <loader>`
 
-Choose config loader (`auto`, `native`, `unrun`):
+Choose config loader (`auto`, `native`, `tsx`, `unrun`). `tsx` and `unrun` are optional peer dependencies — install them manually first:
 
 ```bash
+tsdown --config-loader tsx
 tsdown --config-loader unrun
 ```
 
@@ -171,14 +172,6 @@ Mark module as external (not bundled):
 tsdown --deps.never-bundle react --deps.never-bundle react-dom
 ```
 
-### `--deps.skip-node-modules-bundle`
-
-Skip resolving and bundling all node_modules:
-
-```bash
-tsdown --deps.skip-node-modules-bundle
-```
-
 ### `--shims`
 
 Add ESM/CJS compatibility shims:
@@ -258,14 +251,13 @@ tsdown --copy assets --copy static
 
 ### `--exe`
 
-**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html). Requires Node.js >= 25.5.0, not supported in Bun or Deno. Cross-platform builds supported via `@tsdown/exe`.
+**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html). Requires Node.js >= 25.7.0, not supported in Bun or Deno. Cross-platform builds supported via `@tsdown/exe`.
 
 ```bash
 tsdown --exe
 ```
 
 When enabled:
-- Default format changes to `cjs` (unless Node.js >= 25.7.0)
 - Declaration file generation (`dts`) is disabled by default
 - Code splitting is disabled
 - Only single entry points are supported
@@ -366,6 +358,16 @@ tsdown -W -F my-package
 tsdown -W -F /^pkg-/
 ```
 
+### `--concurrency <count>`
+
+Maximum number of Rolldown builds to run in parallel. Defaults to unlimited:
+
+```bash
+tsdown -W --concurrency 4
+```
+
+Not supported in watch mode (ignored with a warning).
+
 ### `--unbundle`
 
 Enable unbundle (bundleless) mode:
diff --git a/plugins/tsdown/.claude/skills/tsdown b/plugins/tsdown/.claude/skills/tsdown
new file mode 120000
index 00000000..725cb3c5
--- /dev/null
+++ b/plugins/tsdown/.claude/skills/tsdown
@@ -0,0 +1 @@
+../../.agents/skills/tsdown
\ No newline at end of file
diff --git a/plugins/tsdown/.claude/skills/tsdown-migrate b/plugins/tsdown/.claude/skills/tsdown-migrate
new file mode 120000
index 00000000..439ed694
--- /dev/null
+++ b/plugins/tsdown/.claude/skills/tsdown-migrate
@@ -0,0 +1 @@
+../../.agents/skills/tsdown-migrate
\ No newline at end of file
diff --git a/plugins/tsdown/agent/skills/tsdown-migrate/SKILL.md b/plugins/tsdown/agent/skills/tsdown-migrate/SKILL.md
index 87a133d6..e72dc6cf 100644
--- a/plugins/tsdown/agent/skills/tsdown-migrate/SKILL.md
+++ b/plugins/tsdown/agent/skills/tsdown-migrate/SKILL.md
@@ -5,9 +5,16 @@ description: "Migrate TypeScript library projects from tsup to tsdown. Provides
 
 Knowledge base for AI agents to migrate tsup projects to tsdown — the Rolldown-powered library bundler.
 
+## Target Version: Two-Stage Migration
+
+tsdown v0.23 removed all previously-deprecated tsup compatibility options — `bundle`, `outExtension`, `publicDir`, `removeNodeProtocol`, `injectStyle`, and `skipNodeModulesBundle` are no longer recognized. They fail TypeScript type checking and are **silently ignored at runtime**, so a missed mapping on v0.23+ produces wrong output without any error. Migrating directly to v0.23+ is therefore unsafe. tsdown **v0.22.14** is the last version that still accepts these options and flags each one with a deprecation warning, making it the safe migration checkpoint. Migrate in **two stages**:
+
+1. **Stage 1 — migrate on `tsdown@0.22.14`**: Install `tsdown@0.22.14`, migrate the config per the tables below, run a build, and resolve **every** deprecation warning by mapping each flagged tsup option to its real tsdown equivalent. The warnings are the completeness check — the migration is not done until the build produces **zero warnings**.
+2. **Stage 2 — upgrade to the latest tsdown (`^0.23.0` or newer)**: Only after a warning-free build on 0.22.14. Since the config no longer uses any removed compat options, the silent-ignore behavior of v0.23+ is no longer a risk.
+
 ## Runtime Requirement
 
-`tsdown` requires **Node.js 22.18.0 or higher to run** (build-time only). The bundled output can still target lower Node.js versions via the [`target`](../tsdown/references/option-target.md) option, so a library that previously supported Node.js 18 / 20 with tsup can continue to do so after migrating.
+`tsdown` requires **Node.js `^22.18.0 || ^24.11.0 || >=26.0.0` to run** (build-time only) — that is, Node.js 22.18+, 24.11+, or 26+. Odd-numbered and EOL release lines (e.g. Node.js 23, 25) are not supported. The bundled output can still target lower Node.js versions via the [`target`](../tsdown/references/option-target.md) option, so a library that previously supported Node.js 18 / 20 with tsup can continue to do so after migrating.
 
 Recommended workflow when supporting Node.js 18 / 20:
 
@@ -29,9 +36,10 @@ Follow these steps to migrate a tsup project:
 2. **Update imports**: `'tsup'` → `'tsdown'`
 3. **Apply option mappings**: Rename/transform options per tables below
 4. **Preserve tsup defaults**: Explicitly set options that differ (format, clean, dts, target)
-5. **Update package.json**: Dependencies, scripts, root config field
+5. **Update package.json**: Dependencies (Stage 1: `tsdown@0.22.14`), scripts, root config field
 6. **Remove unsupported options**: Replace with alternatives where available
-7. **Test build**: Run `tsdown` and verify output
+7. **Test build on 0.22.14**: Run `tsdown` and resolve every deprecation warning — zero warnings required
+8. **Upgrade to latest tsdown** (`^0.23.0` or newer) and verify the build again
 
 ## Config File Migration
 
@@ -65,26 +73,28 @@ Replace all identifiers: `tsup` → `tsdown`, `TSUP` → `TSDOWN`.
 
 | tsup | tsdown | Notes |
 |------|--------|-------|
+| `entryPoints` | `entry` | Also deprecated in tsup itself |
 | `cjsInterop` | `cjsDefault` | CJS default export handling |
 | `esbuildPlugins` | `plugins` | Now uses Rolldown/Unplugin plugins |
 | `outExtension` | `outExtensions` | Custom output extensions |
-
-### Deprecated but Compatible
-
-These tsup options still work in tsdown for backward compatibility, but emit deprecation warnings and **will be removed in a future version**. Migrate them immediately.
-
-| tsup (deprecated) | tsdown (preferred) | Notes |
-|--------------------|--------------------|-------|
-| `entryPoints` | `entry` | Also deprecated in tsup itself |
 | `publicDir` | `copy` | Copy static files to output |
 | `bundle: true` | _(remove)_ | Bundle is default behavior |
 | `bundle: false` | `unbundle: true` | Preserve file structure |
 | `removeNodeProtocol: true` | `nodeProtocol: 'strip'` | Strip `node:` prefix |
 | `injectStyle: true` | `css: { inject: true }` | CSS injection |
 | `injectStyle: false` | _(remove)_ | Default behavior |
+| `skipNodeModulesBundle` | `deps: { neverBundle: true }` | Externalize all dependencies |
+
+None of the old names are recognized by tsdown v0.23+ — always emit the new names. The compatibility options (`outExtension`, `skipNodeModulesBundle`, `publicDir`, `bundle`, `removeNodeProtocol`, `injectStyle`) were accepted with deprecation warnings up to v0.22.14 and removed entirely in v0.23; on v0.23+ leftovers are silently ignored, not errors, so builds misbehave without warning. This is why Stage 1 runs on v0.22.14, where every leftover is flagged.
+
+### Deprecated but Still Accepted
+
+`external` and `noExternal` are the **only** tsup option names tsdown v0.23 still accepts. They emit deprecation warnings, will be removed in a future version, and cannot be combined with their replacements (mixing `external` with `deps.neverBundle`, or `noExternal` with `deps.alwaysBundle`, throws an error). Always emit the replacements.
+
+| tsup (deprecated) | tsdown (preferred) | Notes |
+|--------------------|--------------------|-------|
 | `external: [...]` | `deps: { neverBundle: [...] }` | Moved to deps namespace |
 | `noExternal: [...]` | `deps: { alwaysBundle: [...] }` | Moved to deps namespace |
-| `skipNodeModulesBundle` | `deps: { skipNodeModulesBundle: true }` | Moved to deps namespace |
 
 ### Output Filename Differences
 
@@ -112,6 +122,11 @@ export default defineConfig({
 
 tsdown also adds `deps.onlyBundle` (whitelist of allowed bundled packages) — no tsup equivalent.
 
+Dependency handling defaults in tsdown v0.23+:
+
+- `dependencies`, `peerDependencies`, and **`optionalDependencies`** are all externalized by default (tsup only externalizes `dependencies` and `peerDependencies`, so `optionalDependencies` may switch from bundled to external after migration).
+- `deps.resolveDepSubpath` (resolving subpath imports of externalized packages without an `exports` field) is **disabled by default**.
+
 ### Plugin Import Transforms
 
 ```ts
@@ -238,15 +253,15 @@ Use this checklist when performing a migration:
 - [ ] Rename tsup.config.* → tsdown.config.*
 - [ ] Update import from 'tsup' to 'tsdown'
 - [ ] Replace tsup/TSUP identifiers with tsdown/TSDOWN
-- [ ] Apply property renames (cjsInterop→cjsDefault, esbuildPlugins→plugins, outExtension→outExtensions)
-- [ ] Migrate deprecated options (publicDir→copy, bundle→unbundle, removeNodeProtocol→nodeProtocol, injectStyle→css.inject)
-- [ ] Move external/noExternal/skipNodeModulesBundle into deps namespace
+- [ ] Apply property renames (cjsInterop→cjsDefault, esbuildPlugins→plugins, outExtension→outExtensions, publicDir→copy, bundle→unbundle, removeNodeProtocol→nodeProtocol, injectStyle→css.inject)
+- [ ] Move external/noExternal into deps namespace, replace skipNodeModulesBundle with `deps.neverBundle: true`
 - [ ] Update unplugin imports from /esbuild to /rolldown
 - [ ] Set explicit defaults to preserve tsup behavior (format, clean, dts, target)
 - [ ] Remove unsupported options (splitting, metafile, swc, etc.)
 - [ ] Update package.json scripts (tsup→tsdown)
-- [ ] Update package.json dependencies
+- [ ] Update package.json dependencies (Stage 1: tsdown@0.22.14)
 - [ ] Rename root-level tsup config field if present
-- [ ] Run tsdown and verify build output
+- [ ] Run tsdown on 0.22.14 and resolve every deprecation warning (zero warnings required)
+- [ ] Upgrade to the latest tsdown (^0.23.0 or newer) and verify the build again
 - [ ] Suggest new tsdown features to the user
 ```
diff --git a/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-differences-detailed.md b/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-differences-detailed.md
index b7198ab2..c0d6465d 100644
--- a/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-differences-detailed.md
+++ b/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-differences-detailed.md
@@ -22,6 +22,12 @@ Comprehensive comparison of tsdown and tsup for understanding migration impact a
 | `dts` | `false` | Auto if `types`/`typings` in package.json | Types generated automatically — usually desired |
 | `target` | _(none)_ | Reads `engines.node` from package.json | Compilation target auto-detected — usually desired |
 
+### Dependency Handling Defaults (tsdown v0.23+)
+
+- `dependencies`, `peerDependencies`, and `optionalDependencies` are all externalized by default. tsup only externalizes `dependencies` and `peerDependencies`, so `optionalDependencies` may switch from bundled to external after migration.
+- Other imports resolved from `node_modules` are bundled with a warning, unless whitelisted via `deps.onlyBundle`.
+- `deps.resolveDepSubpath` (resolving subpath imports of externalized packages without an `exports` field) is disabled by default.
+
 ## Feature Compatibility
 
 ### Fully Supported (works the same)
@@ -43,24 +49,26 @@ Comprehensive comparison of tsdown and tsup for understanding migration impact a
 
 | Feature | tsup | tsdown | Change |
 |---------|------|--------|--------|
+| Entry points | `entryPoints` | `entry` | Also deprecated in tsup itself |
 | CJS interop | `cjsInterop` | `cjsDefault` | Property rename |
 | Plugins | `esbuildPlugins` | `plugins` | Different plugin format (Rolldown) |
 | Output extensions | `outExtension` | `outExtensions` | Property rename |
+| Copy files | `publicDir` | `copy` | Property rename |
+| Bundleless | `bundle: false` | `unbundle: true` | Inverted logic |
+| Strip node: | `removeNodeProtocol` | `nodeProtocol: 'strip'` | New option with more modes |
+| CSS inject | `injectStyle` | `css: { inject: true }` | Moved to css namespace |
+| Skip node_modules | `skipNodeModulesBundle` | `deps.neverBundle: true` | Externalize all dependencies |
 
-### Deprecated but Compatible
+None of the old names in this table are recognized by tsdown v0.23+. The compatibility options (`outExtension`, `skipNodeModulesBundle`, `publicDir`, `bundle`, `removeNodeProtocol`, `injectStyle`) were accepted with deprecation warnings up to v0.22.14 and removed entirely in v0.23 — on v0.23+ leftovers are silently ignored at runtime. Always emit the tsdown names, and migrate in two stages (build on `tsdown@0.22.14` until zero deprecation warnings remain, then upgrade to `^0.23.0`+ — see SKILL.md).
 
-These tsup options still work in tsdown but emit deprecation warnings. They will be removed in a future version — migrate immediately.
+### Deprecated but Still Accepted
+
+`external` and `noExternal` are the only tsup option names tsdown v0.23 still accepts. They emit deprecation warnings, will be removed in a future version, and cannot be combined with their replacements (mixing them throws an error) — migrate immediately.
 
 | Feature | tsup (deprecated) | tsdown (preferred) | Change |
 |---------|-------------------|--------------------|--------|
-| Entry points | `entryPoints` | `entry` | Also deprecated in tsup itself |
-| Copy files | `publicDir` | `copy` | Property rename |
-| Bundleless | `bundle: false` | `unbundle: true` | Inverted logic |
-| Strip node: | `removeNodeProtocol` | `nodeProtocol: 'strip'` | New option with more modes |
-| CSS inject | `injectStyle` | `css: { inject: true }` | Moved to css namespace |
 | External deps | `external` | `deps.neverBundle` | Moved to deps namespace |
 | Inline deps | `noExternal` | `deps.alwaysBundle` | Moved to deps namespace |
-| Skip node_modules | `skipNodeModulesBundle` | `deps.skipNodeModulesBundle` | Moved to deps namespace |
 
 ### Output Filename Differences
 
diff --git a/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-option-mappings.md b/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-option-mappings.md
index 6acf5a0f..ee0de5a5 100644
--- a/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-option-mappings.md
+++ b/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-option-mappings.md
@@ -40,11 +40,23 @@ Note: All `unplugin-*/esbuild` imports must change to `unplugin-*/rolldown`.
 
 ### outExtension → outExtensions
 
-`outExtension` was renamed to `outExtensions`.
+```ts
+// Before (tsup)
+export default defineConfig({
+  outExtension: ({ format }) => ({ js: format === 'cjs' ? '.cjs' : '.mjs' }),
+})
+
+// After (tsdown)
+export default defineConfig({
+  outExtensions: ({ format }) => ({ js: format === 'cjs' ? '.cjs' : '.mjs' }),
+})
+```
 
-## Deprecated but Compatible
+The callback shape is compatible for the `js` key; tsdown's version can additionally return a `dts` extension.
 
-These options still work in tsdown for backward compatibility but emit deprecation warnings. Migrate them immediately — they will be removed in a future version.
+## Removed Compatibility Options
+
+tsdown v0.23 removed these previously-deprecated tsup compatibility options entirely. They are no longer recognized — TypeScript reports them as unknown properties and they are **silently ignored at runtime**, so leftovers make builds misbehave without any error. Always replace them with the tsdown equivalents, and verify on `tsdown@0.22.14` (the last version that flags each of them with a deprecation warning): a zero-warning build confirms the mapping is complete before upgrading to v0.23+ (see SKILL.md's two-stage flow).
 
 ### entryPoints → entry
 
@@ -130,6 +142,26 @@ export default defineConfig({
 
 `injectStyle: false` should be removed (it's the default).
 
+### skipNodeModulesBundle → deps.neverBundle
+
+```ts
+// Before (tsup)
+export default defineConfig({
+  skipNodeModulesBundle: true,
+})
+
+// After (tsdown)
+export default defineConfig({
+  deps: { neverBundle: true },
+})
+```
+
+`deps.neverBundle: true` externalizes **all** dependencies; use `deps.alwaysBundle` to opt specific imports back into the bundle.
+
+## Deprecated but Still Accepted
+
+`external` and `noExternal` are the only tsup option names tsdown v0.23 still accepts. They emit deprecation warnings and will be removed in a future version — always emit the replacements. Combining the old and new forms (e.g. `external` together with `deps.neverBundle`) throws an error.
+
 ### external → deps.neverBundle
 
 ```ts
diff --git a/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-package-json.md b/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-package-json.md
index 71ae30bf..c807859f 100644
--- a/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-package-json.md
+++ b/plugins/tsdown/agent/skills/tsdown-migrate/references/guide-package-json.md
@@ -39,10 +39,22 @@ Rename `tsup` to `tsdown` in whichever dependency field it appears:
   }
 }
 
-// After
+// After (Stage 1 — migration checkpoint)
+{
+  "devDependencies": {
+    "tsdown": "0.22.14",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+Use **`0.22.14` for Stage 1** — the last tsdown version that still accepts the deprecated tsup compatibility options and flags each one with a deprecation warning. Run the build on 0.22.14 and resolve every warning; v0.23+ silently ignores the removed options, so the warnings are the only reliable completeness check. Once the build is warning-free, upgrade to the latest tsdown (**Stage 2**):
+
+```json
+// Final state (Stage 2 — after a zero-warning build on 0.22.14)
 {
   "devDependencies": {
-    "tsdown": "^0.21.3",
+    "tsdown": "^0.23.0",
     "typescript": "^5.0.0"
   }
 }
@@ -50,13 +62,13 @@ Rename `tsup` to `tsdown` in whichever dependency field it appears:
 
 ### All Dependency Fields
 
-| Field | tsup version | tsdown version |
-|-------|-------------|----------------|
-| `dependencies` | any | latest tsdown |
-| `devDependencies` | any | latest tsdown |
-| `optionalDependencies` | any | latest tsdown |
-| `peerDependencies` | any | `*` |
-| `peerDependenciesMeta` | rename key only | rename key only |
+| Field | tsup version | Stage 1 (migration) | Stage 2 (final) |
+|-------|-------------|---------------------|-----------------|
+| `dependencies` | any | `0.22.14` | `^0.23.0` |
+| `devDependencies` | any | `0.22.14` | `^0.23.0` |
+| `optionalDependencies` | any | `0.22.14` | `^0.23.0` |
+| `peerDependencies` | any | `*` | `*` |
+| `peerDependenciesMeta` | rename key only | rename key only | rename key only |
 
 ## Root Config Field
 
diff --git a/plugins/tsdown/agent/skills/tsdown/SKILL.md b/plugins/tsdown/agent/skills/tsdown/SKILL.md
index 873fea9a..0c98cf82 100644
--- a/plugins/tsdown/agent/skills/tsdown/SKILL.md
+++ b/plugins/tsdown/agent/skills/tsdown/SKILL.md
@@ -64,13 +64,13 @@ export default defineConfig({
 | CLI Reference | All CLI commands and options | [reference-cli](references/reference-cli.md) |
 | Migrate from tsup | Migration guide and compatibility notes | [guide-migrate-from-tsup](references/guide-migrate-from-tsup.md) |
 | Plugins | Rolldown, Rollup, Unplugin support | [advanced-plugins](references/advanced-plugins.md) |
-
-> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`
 | Hooks | Lifecycle hooks for custom logic | [advanced-hooks](references/advanced-hooks.md) |
-| Programmatic API | Build from Node.js scripts | [advanced-programmatic](references/advanced-programmatic.md) |
+| Programmatic API | Build from Node.js scripts, in-memory builds (`write: false`) | [advanced-programmatic](references/advanced-programmatic.md) |
 | Rolldown Options | Pass options directly to Rolldown | [advanced-rolldown-options](references/advanced-rolldown-options.md) |
 | CI Environment | CI detection, `'ci-only'` / `'local-only'` values | [advanced-ci](references/advanced-ci.md) |
 
+> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`
+
 ## Build Options
 
 | Option | Usage | Reference |
@@ -86,7 +86,7 @@ export default defineConfig({
 | Source maps | `sourcemap: true`, `'inline'`, `'hidden'` | [option-sourcemap](references/option-sourcemap.md) |
 | Watch mode | `watch: true`, watch options | [option-watch-mode](references/option-watch-mode.md) |
 | Cleaning | `clean: true`, clean patterns | [option-cleaning](references/option-cleaning.md) |
-| Log level | `logLevel: 'silent'`, `failOnWarn: false` | [option-log-level](references/option-log-level.md) |
+| Log level | `logLevel: 'silent'`, `failOnWarn: false`, `suppressWarnings: [...]` | [option-log-level](references/option-log-level.md) |
 
 ## Dependency Handling
 
@@ -95,7 +95,9 @@ export default defineConfig({
 | Never bundle | `deps: { neverBundle: ['react', /^@myorg\//] }` | [option-dependencies](references/option-dependencies.md) |
 | Always bundle | `deps: { alwaysBundle: ['dep-to-bundle'] }` | [option-dependencies](references/option-dependencies.md) |
 | Only bundle | `deps: { onlyBundle: ['cac', 'bumpp'] }` - Whitelist | [option-dependencies](references/option-dependencies.md) |
-| Skip node_modules | `deps: { skipNodeModulesBundle: true }` | [option-dependencies](references/option-dependencies.md) |
+| Only import | `deps: { onlyImport: ['cac'] }` - Whitelist runtime imports in output | [option-dependencies](references/option-dependencies.md) |
+| Externalize all | `deps: { neverBundle: true }` | [option-dependencies](references/option-dependencies.md) |
+| Resolve subpaths | `deps: { resolveDepSubpath: true }` - Resolve external subpath imports (default `false`) | [option-dependencies](references/option-dependencies.md) |
 | Auto external | Automatic dependency/peer/optional externalization | [option-dependencies](references/option-dependencies.md) |
 
 ## Output Enhancement
@@ -108,6 +110,7 @@ export default defineConfig({
 | CSS handling | **[experimental]** `css: { ... }` — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires `@tsdown/css` | [option-css](references/option-css.md) |
 | CSS modules | `css: { modules: { localsConvention: 'camelCase' } }` — scoped class names for `.module.css` files | [option-css](references/option-css.md) |
 | CSS inject | `css: { inject: true }` — preserve CSS imports in JS output | [option-css](references/option-css.md) |
+| Copy files | `copy: 'public'` or `copy: { from, to, flatten, rename }` - Copy static assets to output | [option-copy](references/option-copy.md) |
 | Unbundle mode | `unbundle: true` - Preserve directory structure | [option-unbundle](references/option-unbundle.md) |
 | Root directory | `root: 'src'` - Control output directory mapping | [option-root](references/option-root.md) |
 | Executable | **[experimental]** `exe: true` - Bundle as standalone executable, cross-platform via `@tsdown/exe` | [option-exe](references/option-exe.md) |
@@ -340,6 +343,7 @@ tsdown --minify                # Enable minification
 tsdown --dts                   # Generate declarations
 tsdown --exe                   # Bundle as standalone executable
 tsdown --unbundle              # Bundleless mode
+tsdown --copy public           # Copy static files to output
 
 # Entry options
 tsdown src/index.ts            # Single entry
@@ -350,6 +354,7 @@ tsdown src/a.ts src/b.ts       # Multiple entries
 tsdown -W                      # Enable workspace mode
 tsdown -W -F my-package        # Filter specific package
 tsdown --filter /^pkg-/        # Filter by regex
+tsdown -W --concurrency 4      # Limit parallel Rolldown builds
 
 # Development
 tsdown --watch                 # Watch mode
diff --git a/plugins/tsdown/agent/skills/tsdown/references/README.md b/plugins/tsdown/agent/skills/tsdown/references/README.md
index fdbc6bd2..b75e0a6c 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/README.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/README.md
@@ -2,14 +2,14 @@
 
 This directory contains detailed reference documentation for the tsdown skill.
 
-## Created Files (35 total)
+## Created Files (38 total)
 
 ### Core Guides (3)
 - ✅ `guide-getting-started.md` - Installation, first bundle, CLI basics
 - ✅ `guide-migrate-from-tsup.md` - Migration guide from tsup
 - ✅ `guide-introduction.md` - Introduction and key features
 
-### Configuration Options (20)
+### Configuration Options (22)
 - ✅ `option-config-file.md` - Config file formats, loaders, workspace
 - ✅ `option-entry.md` - Entry point configuration with globs
 - ✅ `option-output-format.md` - Output formats (ESM, CJS, IIFE, UMD)
@@ -27,6 +27,8 @@ This directory contains detailed reference documentation for the tsdown skill.
 - ✅ `option-package-exports.md` - Auto-generate package.json exports
 - ✅ `option-css.md` - CSS handling (experimental, full pipeline: preprocessors, Lightning CSS, PostCSS, code splitting)
 - ✅ `option-unbundle.md` - Preserve directory structure
+- ✅ `option-root.md` - Root directory for output structure mapping
+- ✅ `option-copy.md` - Copy static files to output
 - ✅ `option-cjs-default.md` - CommonJS default export handling
 - ✅ `option-log-level.md` - Logging configuration
 - ✅ `option-lint.md` - Package validation (publint & attw)
@@ -56,7 +58,7 @@ This directory contains detailed reference documentation for the tsdown skill.
 
 ## Coverage Status
 
-**Created:** 35 files (100% complete)
+**Created:** 38 files (100% complete)
 
 ## Current Skill Features
 
diff --git a/plugins/tsdown/agent/skills/tsdown/references/advanced-programmatic.md b/plugins/tsdown/agent/skills/tsdown/references/advanced-programmatic.md
index 092ec60f..efd27fa2 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/advanced-programmatic.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/advanced-programmatic.md
@@ -36,6 +36,39 @@ await build({
 })
 ```
 
+### In-Memory Output
+
+Set `write: false` to access generated chunks and assets without writing the
+bundle output to disk:
+
+```ts
+import { build } from 'tsdown'
+
+const bundles = await build({
+  entry: ['src/index.ts'],
+  format: 'esm',
+  write: false,
+  clean: false,
+})
+
+for (const bundle of bundles) {
+  for (const output of bundle.chunks) {
+    const contents = output.type === 'chunk' ? output.code : output.source
+    console.log(output.fileName, contents)
+  }
+}
+```
+
+`build()` currently returns a `TsdownBundle[]`, with one bundle for each
+resolved configuration. Even a single configuration returns an array; its
+in-memory Rolldown outputs are available in `bundle.chunks`.
+
+The `write` option controls Rolldown's bundle output, while other file operations
+are configured separately. For example, `clean` defaults to `true`, so set
+`clean: false` as above if existing output directories must remain untouched.
+Explicitly enabled features such as `copy` or `exports` may still write files.
+`write: false` is incompatible with watch mode.
+
 ## API Reference
 
 ### build()
@@ -52,7 +85,7 @@ await build(options)
 - `options` - Build configuration object (same as config file)
 
 **Returns:**
-- `Promise<void>` - Resolves when build completes
+- `Promise<TsdownBundle[]>` - One bundle for each resolved configuration
 
 **Throws:**
 - Build errors if compilation fails
diff --git a/plugins/tsdown/agent/skills/tsdown/references/advanced-rolldown-options.md b/plugins/tsdown/agent/skills/tsdown/references/advanced-rolldown-options.md
index 2a35044b..532243b5 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/advanced-rolldown-options.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/advanced-rolldown-options.md
@@ -6,7 +6,7 @@ Pass options directly to the underlying Rolldown bundler.
 
 tsdown uses [Rolldown](https://rolldown.rs) as its core bundling engine. You can override Rolldown's input and output options directly for fine-grained control.
 
-**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/options/input) documentation.
+**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/reference/InputOptions.input) documentation.
 
 ## Input Options
 
diff --git a/plugins/tsdown/agent/skills/tsdown/references/guide-migrate-from-tsup.md b/plugins/tsdown/agent/skills/tsdown/references/guide-migrate-from-tsup.md
index b0568e50..8a264552 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/guide-migrate-from-tsup.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/guide-migrate-from-tsup.md
@@ -46,7 +46,50 @@ npx tsdown-migrate packages/foo packages/bar
 
 | tsup | tsdown |
 |------|--------|
+| `entryPoints` | `entry` |
+| `cjsInterop` | `cjsDefault` |
+| `esbuildPlugins` | `plugins` |
 | `outExtension` | `outExtensions` |
+| `skipNodeModulesBundle` | `deps: { neverBundle: true }` |
+| `publicDir` | `copy` |
+| `bundle: false` | `unbundle: true` |
+| `removeNodeProtocol: true` | `nodeProtocol: 'strip'` |
+| `injectStyle: true` | `css: { inject: true }` |
+
+The old names were accepted (with deprecation warnings) up to tsdown v0.22.14 and have been removed since — v0.23+ silently ignores them, so a leftover tsup option won't error. Migrate in two stages: install `tsdown@0.22.14` first and resolve every deprecation warning (a warning-free build proves the mapping is complete), then upgrade to the latest version. The `tsdown-migrate` tool installs v0.22.14 for this reason.
+
+### Deprecated but Compatible Options
+
+These tsup options still work but emit deprecation warnings and will be removed in a future version — migrate them immediately:
+
+| tsup (deprecated) | tsdown (preferred) |
+|-------------------|--------------------|
+| `external: [...]` | `deps: { neverBundle: [...] }` |
+| `noExternal: [...]` | `deps: { alwaysBundle: [...] }` |
+
+tsdown also adds `deps.onlyBundle` for whitelisting allowed bundled packages.
+
+### Unsupported Options
+
+| Option | Status | Alternative |
+|--------|--------|-------------|
+| `splitting: false` | Always enabled | Code splitting cannot be disabled |
+| `metafile` | Not available | Use `devtools: true` for bundle analysis via Vite DevTools |
+| `swc` | Not supported | tsdown uses oxc for transformation (built-in) |
+| `experimentalDts` | Superseded | Use the `dts` option instead |
+| `legacyOutput` | Not supported | No alternative |
+| `plugins` (tsup experimental) | Incompatible | Migrate to Rolldown plugins |
+
+### Plugin System
+
+tsdown uses Rolldown plugins instead of esbuild plugins. If you use unplugin plugins, update the import path:
+
+```ts
+// Before (tsup)
+import plugin from 'unplugin-example/esbuild'
+// After (tsdown)
+import plugin from 'unplugin-example/rolldown'
+```
 
 ### Output Filename Differences
 
@@ -72,6 +115,16 @@ export default defineConfig({
 })
 ```
 
+#### Other tsdown-Exclusive Features
+
+- **`exports`**: Auto-generate the `exports` field in `package.json` with `exports: true`
+- **`publint`** / **`attw`**: Validate your package for common issues and type correctness
+- **`exe`**: Bundle as a Node.js standalone executable (SEA) with `exe: true`
+- **`devtools`**: Vite DevTools integration for bundle analysis with `devtools: true`
+- **`hooks`**: Lifecycle hooks (`build:prepare`, `build:before`, `build:done`)
+- **`css`**: Full CSS pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, and code splitting
+- **`globImport`**: Support for `import.meta.glob` (Vite-style glob imports)
+
 ## Migration Checklist
 
 1. **Backup your code** - Commit all changes
@@ -186,7 +239,7 @@ Some tsup features are not yet available. Check [GitHub issues](https://github.c
 tsdown should be faster than tsup. If not:
 1. Enable `isolatedDeclarations` for faster DTS generation
 2. Check for large dependencies being bundled
-3. Use `skipNodeModulesBundle` if needed
+3. Use `deps.neverBundle: true` if needed
 
 ## Getting Help
 
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-cjs-default.md b/plugins/tsdown/agent/skills/tsdown/references/option-cjs-default.md
index 85ba705e..87280634 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/option-cjs-default.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-cjs-default.md
@@ -4,7 +4,7 @@ Control how default exports are handled in CommonJS output.
 
 ## Overview
 
-The `cjsDefault` option improves compatibility when generating CommonJS modules. When enabled (default), modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.
+The `cjsDefault` option improves compatibility when generating CommonJS **entry** modules. When enabled (default), entry modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.
 
 ## Type
 
@@ -80,6 +80,21 @@ exports.default = greet
 
 Consumers need `require('your-module').default`.
 
+## Entry Modules Only
+
+`cjsDefault` only applies to **explicit entry modules**. In [unbundle mode](option-unbundle.md), imported modules that are emitted as non-entry chunks keep named CJS exports such as `exports.default`. CJS is considered legacy and is supported in maintenance-only mode, so this behavior will not be extended to non-entry chunks.
+
+If every source module is intended to be consumed independently, include all of them as entries:
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts'],
+  root: 'src',
+  format: 'cjs',
+  unbundle: true,
+})
+```
+
 ## When to Disable
 
 - When your module has both default and named exports
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-copy.md b/plugins/tsdown/agent/skills/tsdown/references/option-copy.md
new file mode 100644
index 00000000..8d8b9b23
--- /dev/null
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-copy.md
@@ -0,0 +1,111 @@
+# Copy Files
+
+Copy static files and directories into the build output.
+
+## Overview
+
+The `copy` option copies assets that should be distributed without being processed by the bundler — images, fonts, license files, etc.
+
+## Basic Usage
+
+### CLI
+
+```bash
+tsdown --copy public
+```
+
+With the default `outDir` of `dist`, `public/favicon.svg` is copied to `dist/public/favicon.svg`.
+
+### Config File
+
+```ts
+export default defineConfig({
+  copy: 'public',
+})
+```
+
+Multiple paths, glob patterns, or object entries in an array:
+
+```ts
+export default defineConfig({
+  copy: [
+    'LICENSE',
+    {
+      from: ['public/**/*', '!public/**/*.map'],
+      to: 'dist/assets',
+      flatten: false,
+    },
+  ],
+})
+```
+
+Glob patterns support negation with a leading `!`.
+
+**Note:** Relative source and destination paths are resolved from the project root (`cwd`), not from `outDir`.
+
+## Object Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `from` | `string \| string[]` | Required | Source path or glob pattern; arrays can include negated patterns |
+| `to` | `string` | `outDir` | Destination path, resolved from the project root |
+| `flatten` | `boolean` | `true` | Place matched files directly in `to`. Set `false` to preserve the directory structure below the first segment |
+| `rename` | `string \| ((name, extension, fullPath) => string)` | — | Change the destination name. Callback receives the extension without a leading dot and the absolute path |
+| `verbose` | `boolean` | `false` | Log each copied source and destination |
+
+### Preserve Directory Structure
+
+```ts
+export default defineConfig({
+  copy: {
+    from: 'assets/**/*',
+    to: 'dist/public',
+    flatten: false,
+  },
+})
+```
+
+`assets/fonts/inter.woff2` → `dist/public/fonts/inter.woff2`.
+
+### Rename Copied Items
+
+```ts
+export default defineConfig({
+  copy: [
+    { from: 'src/file.txt', to: 'dist', rename: 'file.md' },
+    {
+      from: 'src/file.txt',
+      to: 'dist',
+      rename: (name, extension) => `${name}-renamed.${extension}`,
+    },
+  ],
+})
+```
+
+Creates `dist/file.md` and `dist/file-renamed.txt`.
+
+## Dynamic Configuration
+
+`copy` can be a sync or async callback receiving the resolved tsdown config:
+
+```ts
+export default defineConfig({
+  copy: ({ outDir }) => ({
+    from: ['assets/**/*', '!assets/**/*.map'],
+    to: `${outDir}/assets`,
+    flatten: false,
+  }),
+})
+```
+
+## Build and Watch Behavior
+
+- Copying runs after the bundle output is produced; files are copied without passing through Rolldown transforms.
+- A top-level `copy` option runs only once for a multi-format build; a format-specific override can define `copy` again for that format.
+- In watch mode, matched source files are watched as build dependencies — changing one triggers a rebuild and copies the current files again.
+
+## Related Options
+
+- [Output Directory](option-output-directory.md) - Where output goes
+- [Cleaning](option-cleaning.md) - Output directory cleanup
+- [Watch Mode](option-watch-mode.md) - Watch mode behavior
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-css.md b/plugins/tsdown/agent/skills/tsdown/references/option-css.md
index 4a0c692d..065f9d61 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/option-css.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-css.md
@@ -222,6 +222,26 @@ export default defineConfig({
 
 Set `css.modules: false` to disable. Function-form `generateScopedName` requires `transformer: 'postcss'`.
 
+`localsConvention` also accepts a function compatible with Vite and
+`postcss-modules`:
+
+```ts
+export default defineConfig({
+  css: {
+    modules: {
+      localsConvention: (
+        originalClassName,
+        generatedClassName,
+        inputFile,
+      ) => originalClassName.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase()),
+    },
+  },
+})
+```
+
+The function form works with both CSS transformers and returns the JavaScript
+export key.
+
 ### Optional Dependencies (PostCSS path)
 
 ```bash
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-dependencies.md b/plugins/tsdown/agent/skills/tsdown/references/option-dependencies.md
index 52e9b9ae..ffe3dc6e 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/option-dependencies.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-dependencies.md
@@ -33,7 +33,8 @@ export default defineConfig({
     neverBundle: ['react', /^@myorg\//],
     alwaysBundle: ['some-package'],
     onlyBundle: ['cac', 'bumpp'],
-    skipNodeModulesBundle: true,
+    onlyImport: ['cac'],
+    resolveDepSubpath: true,
   },
 })
 ```
@@ -56,6 +57,19 @@ export default defineConfig({
 })
 ```
 
+Set to `true` to externalize ALL dependencies:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  deps: {
+    neverBundle: true,
+  },
+})
+```
+
+**Result:** Every import that follows npm package naming conventions is externalized as written, without being resolved. This is fast and even works when dependencies are not installed. Subpaths like `my-dep/utils` are preserved exactly (`resolveDepSubpath` has no effect). Other non-relative imports (`#` subpath imports, path aliases like `~/`) are resolved: they stay external if they resolve into node_modules, and are bundled if they map to local files. Combine with `alwaysBundle` to bundle selected dependencies.
+
 ### `deps.alwaysBundle`
 
 Force dependencies to be bundled:
@@ -96,22 +110,41 @@ export default defineConfig({
 
 **Note:** Include all sub-dependencies in the list, not just top-level imports.
 
-### `deps.skipNodeModulesBundle`
+### `deps.onlyImport`
 
-Skip bundling ALL node_modules:
+Whitelist of packages the emitted output is allowed to import at runtime. Throws an error (listing all violations) if any chunk imports an unlisted package:
 
 ```ts
 export default defineConfig({
   entry: ['src/index.ts'],
   deps: {
-    skipNodeModulesBundle: true,
+    onlyImport: [
+      'cac',               // Also covers subpath imports like cac/deno
+      /^my-utils/,         // Regex patterns match the package name
+    ],
   },
 })
 ```
 
-**Result:** No dependencies from node_modules are bundled.
+**Behavior:**
+- Matching is based on the package name; subpath imports (`cac/deno`) match `cac`.
+- Node.js built-in modules are always allowed when `platform` is `node`.
+- Relative imports between code-split chunks are always allowed.
+- Declaration output (`.d.ts`) is checked too.
+
+**Limitation:** ES imports and dynamic `import()` expressions are checked. CJS `require()` calls are not detected.
 
-**Note:** Cannot be used together with `alwaysBundle`.
+### `deps.resolveDepSubpath`
+
+By default, tsdown preserves external dependency subpath imports as written. Enable `resolveDepSubpath` to resolve subpath imports to their actual package-relative paths when a package has no `exports` field. For example, `my-dep/functions/lt` may become `my-dep/functions/lt.js`, and `my-dep/folder` may become `my-dep/folder/index.js`.
+
+```ts
+export default defineConfig({
+  deps: {
+    resolveDepSubpath: true,  // default: false
+  },
+})
+```
 
 ## Common Patterns
 
@@ -224,21 +257,12 @@ tsdown --deps.never-bundle react --deps.never-bundle react-dom
 tsdown --deps.never-bundle '/^@myorg\/.*/'
 ```
 
-### Skip Node Modules
-
-```bash
-tsdown --deps.skip-node-modules-bundle
-```
-
 ## Migration from Deprecated Options
 
 | Deprecated Option | New Option |
 |---|---|
 | `external` | `deps.neverBundle` |
 | `noExternal` | `deps.alwaysBundle` |
-| `inlineOnly` | `deps.onlyBundle` |
-| `deps.onlyAllowBundle` | `deps.onlyBundle` |
-| `skipNodeModulesBundle` | `deps.skipNodeModulesBundle` |
 
 ## Examples by Use Case
 
@@ -362,7 +386,9 @@ export default defineConfig({
 - `neverBundle` → Force external
 - `alwaysBundle` → Force bundled
 - `onlyBundle` → Whitelist bundled deps
-- `skipNodeModulesBundle` → Skip all node_modules
+- `onlyImport` → Whitelist runtime imports in output
+- `neverBundle: true` → Externalize all dependencies
+- `resolveDepSubpath: true` → Resolve external dependency subpath imports to package-relative paths
 
 **Declaration files:**
 - Same bundling logic as JavaScript
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-exe.md b/plugins/tsdown/agent/skills/tsdown/references/option-exe.md
index db06e2ac..4c335b22 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/option-exe.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-exe.md
@@ -4,7 +4,7 @@
 
 ## Requirements
 
-- Node.js >= 25.5.0 (ESM support requires >= 25.7.0)
+- Node.js >= 25.7.0
 - Not supported in Bun or Deno
 
 ## Basic Usage
@@ -18,7 +18,6 @@ export default defineConfig({
 
 ## Behavior When Enabled
 
-- Default output format changes from `esm` to `cjs` (unless Node.js >= 25.7.0)
 - Declaration file generation (`dts`) is disabled by default
 - Code splitting is disabled
 - Only single entry points are supported
@@ -97,7 +96,25 @@ dist/
 |-------|------|-------------|
 | `platform` | `'win' \| 'darwin' \| 'linux'` | Target OS (nodejs.org naming) |
 | `arch` | `'x64' \| 'arm64'` | Target CPU architecture |
-| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`) |
+| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`), or `'latest'` / `'latest-lts'` to resolve automatically |
+
+### Custom Node.js Index and Download URL
+
+When downloading Node.js binaries (e.g. behind a corporate proxy or using a mirror), you can customize the sources:
+
+```ts
+export default defineConfig({
+  entry: ['src/cli.ts'],
+  exe: {
+    targets: [{ platform: 'linux', arch: 'x64', nodeVersion: 'latest-lts' }],
+    // Index used to resolve 'latest' / 'latest-lts' versions
+    nodeDistIndexUrl: 'https://mirrors.example.com/node/index.json', // default: https://nodejs.org/dist/index.json
+    // Fully custom download URL per target
+    getDownloadUrl: (target) =>
+      `https://mirrors.example.com/node/v${target.nodeVersion}/node-v${target.nodeVersion}-${target.platform}-${target.arch}.tar.gz`,
+  },
+})
+```
 
 ### Caching
 
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-log-level.md b/plugins/tsdown/agent/skills/tsdown/references/option-log-level.md
index 9b5706d4..f48712f7 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/option-log-level.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-log-level.md
@@ -84,6 +84,40 @@ export default defineConfig({
 
 See [CI Environment](advanced-ci.md) for more about CI-aware options.
 
+## Suppressing Warnings
+
+The `suppressWarnings` option silences warnings whose message matches a given pattern. This is useful for opting out of non-actionable notices (such as the TypeScript 7.0 experimental API warning) while keeping other warnings visible.
+
+### Type
+
+```ts
+suppressWarnings?:
+  | string
+  | RegExp
+  | Array<string | RegExp>
+  | ((msg: string) => boolean)
+```
+
+- **string** – substring match
+- **RegExp** – regular expression match
+- **array** – matches if any entry matches
+- **function** – custom predicate
+
+### Usage
+
+```ts
+export default defineConfig({
+  suppressWarnings: [
+    'is experimental',        // substring match
+    /Circular dependency/,    // regexp match
+  ],
+  // Or a predicate function:
+  // suppressWarnings: (msg) => msg.includes('is experimental'),
+})
+```
+
+Matched warnings are dropped **before** `failOnWarn` is applied, so a suppressed warning will not fail the build even when `failOnWarn: true`.
+
 ## Related Options
 
 - [CI Environment](advanced-ci.md) - CI-aware option details
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-output-format.md b/plugins/tsdown/agent/skills/tsdown/references/option-output-format.md
index 6f9852e3..ca03d7c3 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/option-output-format.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-output-format.md
@@ -15,6 +15,8 @@ tsdown can generate bundles in multiple formats. Default is ESM.
 | `iife` | Immediately Invoked Function Expression | Browser `<script>` tags |
 | `umd` | Universal Module Definition | AMD, CommonJS, and globals |
 
+**Note:** CJS is in **maintenance-only mode**. Since the ecosystem is transitioning to ESM and Node.js now supports `require(esm)`, tsdown's CJS-specific features (such as `cjsDefault`) are kept for compatibility but will not be further enhanced or optimized. New libraries are encouraged to publish ESM-only.
+
 ## Usage
 
 ### CLI
diff --git a/plugins/tsdown/agent/skills/tsdown/references/option-target.md b/plugins/tsdown/agent/skills/tsdown/references/option-target.md
index d470c3a9..70bb4535 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/option-target.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/option-target.md
@@ -80,17 +80,21 @@ export default defineConfig({
 
 ## Supported Targets
 
-### ECMAScript Versions
+tsdown (Rolldown) uses [Oxc](https://oxc.rs/docs/guide/usage/transformer/lowering#target) for syntax lowering. The following environment names are supported (with version numbers, e.g. `chrome100`, `node18`, `es2020`):
 
-- `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `esnext`
+- **ECMAScript versions**: `es2015`, `es2016`, ..., `es2025`, `esnext`
+- **Browsers**: `chrome`, `edge`, `firefox`, `ie`, `ios`, `opera`, `safari`, `samsung`
+- **Runtimes**: `node`, `deno`, `hermes`, `rhino`
 
-### Browser Versions
+### Baseline Widely Available
 
-- `chrome100`, `safari18`, `firefox110`, `edge100`, etc.
+The special target `'baseline-widely-available'` expands to the browser versions covered by [Baseline Widely Available](https://web.dev/baseline) (e.g. `chrome111`, `edge111`, `firefox114`, `safari16.4`, `ios16.4`):
 
-### Node.js Versions
-
-- `node16`, `node18`, `node20`, `node20.18`, etc.
+```ts
+export default defineConfig({
+  target: 'baseline-widely-available',
+})
+```
 
 ## Examples
 
diff --git a/plugins/tsdown/agent/skills/tsdown/references/recipe-react.md b/plugins/tsdown/agent/skills/tsdown/references/recipe-react.md
index cc56d8dd..5c2fc6a5 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/recipe-react.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/recipe-react.md
@@ -99,18 +99,19 @@ export default defineConfig({
 
 ## React Compiler
 
-React Compiler automatically optimizes React code at build time.
+React Compiler automatically optimizes React code at build time. It is currently available only as a Babel plugin. You can scaffold the `react-compiler` starter template (`npx create-tsdown@latest -t react-compiler`) or integrate it manually.
 
 ### Install Dependencies
 
 ```bash
-pnpm add -D @rollup/plugin-babel babel-plugin-react-compiler
+pnpm add -D @rolldown/plugin-babel @vitejs/plugin-react
 ```
 
 ### Configure
 
 ```ts
-import pluginBabel from '@rollup/plugin-babel'
+import pluginBabel from '@rolldown/plugin-babel'
+import { reactCompilerPreset } from '@vitejs/plugin-react'
 
 export default defineConfig({
   entry: ['src/index.tsx'],
@@ -120,13 +121,7 @@ export default defineConfig({
   },
   plugins: [
     pluginBabel({
-      babelHelpers: 'bundled',
-      parserOpts: {
-        sourceType: 'module',
-        plugins: ['jsx', 'typescript'],
-      },
-      plugins: ['babel-plugin-react-compiler'],
-      extensions: ['.js', '.jsx', '.ts', '.tsx'],
+      presets: [reactCompilerPreset()],
     }),
   ],
   dts: true,
diff --git a/plugins/tsdown/agent/skills/tsdown/references/reference-cli.md b/plugins/tsdown/agent/skills/tsdown/references/reference-cli.md
index fa4fa571..8213687d 100644
--- a/plugins/tsdown/agent/skills/tsdown/references/reference-cli.md
+++ b/plugins/tsdown/agent/skills/tsdown/references/reference-cli.md
@@ -52,9 +52,10 @@ tsdown --no-config src/index.ts
 
 ### `--config-loader <loader>`
 
-Choose config loader (`auto`, `native`, `unrun`):
+Choose config loader (`auto`, `native`, `tsx`, `unrun`). `tsx` and `unrun` are optional peer dependencies — install them manually first:
 
 ```bash
+tsdown --config-loader tsx
 tsdown --config-loader unrun
 ```
 
@@ -171,14 +172,6 @@ Mark module as external (not bundled):
 tsdown --deps.never-bundle react --deps.never-bundle react-dom
 ```
 
-### `--deps.skip-node-modules-bundle`
-
-Skip resolving and bundling all node_modules:
-
-```bash
-tsdown --deps.skip-node-modules-bundle
-```
-
 ### `--shims`
 
 Add ESM/CJS compatibility shims:
@@ -258,14 +251,13 @@ tsdown --copy assets --copy static
 
 ### `--exe`
 
-**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html). Requires Node.js >= 25.5.0, not supported in Bun or Deno. Cross-platform builds supported via `@tsdown/exe`.
+**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html). Requires Node.js >= 25.7.0, not supported in Bun or Deno. Cross-platform builds supported via `@tsdown/exe`.
 
 ```bash
 tsdown --exe
 ```
 
 When enabled:
-- Default format changes to `cjs` (unless Node.js >= 25.7.0)
 - Declaration file generation (`dts`) is disabled by default
 - Code splitting is disabled
 - Only single entry points are supported
@@ -366,6 +358,16 @@ tsdown -W -F my-package
 tsdown -W -F /^pkg-/
 ```
 
+### `--concurrency <count>`
+
+Maximum number of Rolldown builds to run in parallel. Defaults to unlimited:
+
+```bash
+tsdown -W --concurrency 4
+```
+
+Not supported in watch mode (ignored with a warning).
+
 ### `--unbundle`
 
 Enable unbundle (bundleless) mode:
diff --git a/plugins/tsdown/skills-lock.json b/plugins/tsdown/skills-lock.json
index c9771ff7..fa7663c4 100644
--- a/plugins/tsdown/skills-lock.json
+++ b/plugins/tsdown/skills-lock.json
@@ -5,13 +5,13 @@
       "source": "rolldown/tsdown",
       "sourceType": "github",
       "skillPath": "skills/tsdown/SKILL.md",
-      "computedHash": "47f632fbbbdefb7d5b18263502c218cec477255c0fa14baf168c47b83edabeee"
+      "computedHash": "8539dbd043e7d7c57e619fe4ff3a85be17b75762099fd17a3a63de23e734dd3a"
     },
     "tsdown-migrate": {
       "source": "rolldown/tsdown",
       "sourceType": "github",
       "skillPath": "skills/tsdown-migrate/SKILL.md",
-      "computedHash": "2ef3e45913861eaf12af22188656733c3b3f7244258f46a60ff892eae9831537"
+      "computedHash": "ef840c62747ce5aed1e8b35197d767b022a690648f4a55d31e5e81ed8c21e0bd"
     }
   }
 }
diff --git a/plugins/turborepo/.agents/skills/turborepo/SKILL.md b/plugins/turborepo/.agents/skills/turborepo/SKILL.md
index 4c653115..c22ab76a 100644
--- a/plugins/turborepo/.agents/skills/turborepo/SKILL.md
+++ b/plugins/turborepo/.agents/skills/turborepo/SKILL.md
@@ -9,7 +9,7 @@ description: |
   monorepo, shares code between apps, runs changed/affected packages, debugs cache,
   or has apps/packages directories.
 metadata:
-  version: 2.10.4-canary.1
+  version: 2.10.9
 ---
 
 # Turborepo Skill
@@ -128,12 +128,12 @@ Cache problems?
 ```
 Run only what changed?
 ├─ Changed packages + dependents (RECOMMENDED) → turbo run build --affected
-├─ Custom base branch → --affected --affected-base=origin/develop
+├─ Custom base branch → TURBO_SCM_BASE=origin/develop turbo run build --affected
 ├─ Manual git comparison → --filter=...[origin/main]
 └─ See all filter options → references/filtering/RULE.md
 ```
 
-**`--affected` is the primary way to run only changed packages.** It automatically compares against the default branch and includes dependents.
+**`--affected` is the primary way to run only changed packages.** It compares against `main` (falling back to `master`) — not the repo's configured default branch — and includes dependents. Set `TURBO_SCM_BASE` for any other base branch.
 
 ### "I want to filter packages"
 
@@ -427,7 +427,7 @@ A large `env` array (even 50+ variables) is **not** a problem. It usually means
 
 ### Using `--parallel` Flag
 
-The `--parallel` flag bypasses Turborepo's dependency graph. If tasks need parallel execution, configure `dependsOn` correctly instead.
+The `--parallel` flag bypasses Turborepo's dependency graph. It is deprecated and will be removed in a future major version—use task configuration (`persistent`, `with`) instead.
 
 ```bash
 # WRONG - bypasses dependency graph
@@ -740,7 +740,7 @@ import { Button } from "@repo/ui/button";
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "tasks": {
     "build": {
       "dependsOn": ["^build"],
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/best-practices/structure.md b/plugins/turborepo/.agents/skills/turborepo/references/best-practices/structure.md
index 90b0d4df..cb2aad50 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/best-practices/structure.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/best-practices/structure.md
@@ -13,7 +13,7 @@ packages:
   - "packages/*"
 ```
 
-### npm/yarn/bun
+### npm/yarn/bun/nub
 
 ```json
 // package.json
@@ -22,6 +22,17 @@ packages:
 }
 ```
 
+nub follows the repo's existing lockfile: with a pnpm-format lockfile (`pnpm-lock.yaml` or nub's `lock.yaml`) it reads `pnpm-workspace.yaml` when that file exists, otherwise `package.json` workspaces.
+
+### aube
+
+aube uses `aube-workspace.yaml` (same `packages:` format as pnpm), falling back to `pnpm-workspace.yaml` or `package.json` workspaces.
+
+### Polyglot workspaces (experimental)
+
+- `futureFlags.experimentalCargoWorkspaces` - Treat Cargo workspace crates as Turborepo packages
+- `futureFlags.experimentalPythonWorkspaces` - Treat uv workspace members as Turborepo packages
+
 ## Root package.json
 
 ```json
@@ -95,7 +106,7 @@ Package tasks enable Turborepo to:
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "tasks": {
     "build": {
       "dependsOn": ["^build"],
@@ -117,7 +128,7 @@ With `futureFlags.globalConfiguration`, global settings move under a `global` ke
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "futureFlags": { "globalConfiguration": true },
   "global": {
     "inputs": ["tsconfig.json"],
@@ -262,28 +273,34 @@ packages/
     ├── package.json
     ├── base.js
     ├── next.js
-    └── library.js
+    └── react-internal.js
 ```
 
 ```json
 // packages/eslint-config/package.json
 {
   "name": "@repo/eslint-config",
+  "type": "module",
   "exports": {
     "./base": "./base.js",
-    "./next": "./next.js",
-    "./library": "./library.js"
+    "./next-js": "./next.js",
+    "./react-internal": "./react-internal.js"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.1"
   }
 }
 ```
 
 ### Using in Packages
 
+ESLint 9 flat config:
+
 ```js
-// apps/web/.eslintrc.js
-module.exports = {
-  extends: ["@repo/eslint-config/next"]
-};
+// apps/web/eslint.config.js
+import { nextJsConfig } from "@repo/eslint-config/next-js";
+
+export default nextJsConfig;
 ```
 
 ## Lockfile
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/caching/RULE.md b/plugins/turborepo/.agents/skills/turborepo/references/caching/RULE.md
index 80ec53bc..5a85c17e 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/caching/RULE.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/caching/RULE.md
@@ -16,8 +16,8 @@ If inputs haven't changed, restore outputs from cache instead of re-running the
 
 These affect ALL tasks in the repo:
 
-- `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`
-- Files listed in `globalDependencies` (or `global.env` when using `globalConfiguration`)
+- `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` / `bun.lock` (binary `bun.lockb` is unsupported — run `bun install --save-text-lockfile`)
+- Files listed in `globalDependencies` (or `global.inputs` when using `globalConfiguration` — those move to task hashes, see below)
 - Environment variables in `globalEnv` (or `global.env`)
 - `turbo.json` configuration
 
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/caching/gotchas.md b/plugins/turborepo/.agents/skills/turborepo/references/caching/gotchas.md
index e5f99770..5a0c17de 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/caching/gotchas.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/caching/gotchas.md
@@ -145,7 +145,7 @@ Task reads a file outside default inputs:
     "build": {
       "inputs": [
         "$TURBO_DEFAULT$",
-        "../../shared-config.json" // file outside package
+        "$TURBO_ROOT$/shared-config.json" // file outside package
       ]
     }
   }
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/caching/remote-cache.md b/plugins/turborepo/.agents/skills/turborepo/references/caching/remote-cache.md
index da76458b..be143c71 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/caching/remote-cache.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/caching/remote-cache.md
@@ -103,11 +103,11 @@ TURBO_TEAM=your-team
 
 ```bash
 # Disable remote cache for a run
-turbo build --remote-cache-read-only  # read but don't write
-turbo build --no-cache                # skip cache entirely
+turbo build --remote-cache-read-only  # read but don't write; deprecated, use --cache=local:rw,remote:r
+turbo build --no-cache                # skip cache writes (reads still hit); deprecated, use --cache=local:r,remote:r
 
 # Environment variable alternative
-TURBO_REMOTE_ONLY=true  # only use remote, skip local
+TURBO_CACHE=remote:rw  # only use remote, skip local (TURBO_REMOTE_ONLY is deprecated)
 ```
 
 ## Debugging Remote Cache
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/ci/RULE.md b/plugins/turborepo/.agents/skills/turborepo/references/ci/RULE.md
index f331c2cf..8ea815f8 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/ci/RULE.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/ci/RULE.md
@@ -65,12 +65,12 @@ fetch-depth: 0 # Full history
 
 ## Environment Variables Reference
 
-| Variable            | Purpose                              |
-| ------------------- | ------------------------------------ |
-| `TURBO_TOKEN`       | Vercel access token for remote cache |
-| `TURBO_TEAM`        | Your Vercel team slug                |
-| `TURBO_REMOTE_ONLY` | Skip local cache, use remote only    |
-| `TURBO_LOG_ORDER`   | Set to `grouped` for cleaner CI logs |
+| Variable          | Purpose                                                                    |
+| ----------------- | -------------------------------------------------------------------------- |
+| `TURBO_TOKEN`     | Vercel access token for remote cache                                       |
+| `TURBO_TEAM`      | Your Vercel team slug                                                      |
+| `TURBO_CACHE`     | Set to `remote:rw` to skip local cache (`TURBO_REMOTE_ONLY` is deprecated) |
+| `TURBO_LOG_ORDER` | Set to `grouped` for cleaner CI logs                                       |
 
 ## See Also
 
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/ci/github-actions.md b/plugins/turborepo/.agents/skills/turborepo/references/ci/github-actions.md
index 1cdb34f3..8a5e453d 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/ci/github-actions.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/ci/github-actions.md
@@ -72,25 +72,38 @@ jobs:
 
 ## Remote Cache Setup
 
-### 1. Create Vercel Access Token
+There are two ways to authenticate to [Vercel Remote Cache](https://vercel.com/docs/monorepos/remote-caching) from GitHub Actions:
 
-1. Go to [Vercel Dashboard](https://vercel.com/account/tokens)
-2. Create a new token with appropriate scope
-3. Copy the token value
+- **OpenID Connect (OIDC)**: configure a policy that allows exchanging the CI/CD provider's OIDC tokens for short-lived Turborepo access tokens that grant access to Remote Cache (recommended).
+- **Personal Access Token (PAT)**: configure a long-lived, team-scoped PAT as a secret in your CI/CD provider (use when OIDC is not an option).
 
-### 2. Add Secrets and Variables
+For the full setup, see [Use Remote Caching from external CI/CD](https://vercel.com/docs/monorepos/remote-caching/external-ci-cd). The GitHub Actions workflow configuration is shown below.
 
-In your GitHub repository settings:
+### Option A: OpenID Connect (recommended)
 
-**Secrets** (Settings > Secrets and variables > Actions > Secrets):
+Follow [these instructions](https://vercel.com/docs/monorepos/remote-caching/external-ci-cd#openid-connect-oidc) to create an OIDC policy on your Vercel team and configure your `TURBO_TEAM` variable. Then add [`vercel/setup-turborepo-remote-cache-action`](https://github.com/vercel/setup-turborepo-remote-cache-action) before any step that runs `turbo`. It requests a GitHub OIDC token, exchanges it for a short-lived Turborepo access token, and sets `TURBO_TOKEN` and `TURBO_TEAM` environment variables for later steps that run `turbo`:
 
-- `TURBO_TOKEN`: Your Vercel access token
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
-**Variables** (Settings > Secrets and variables > Actions > Variables):
+      - uses: vercel/setup-turborepo-remote-cache-action@v1.0.0
+        with:
+          team: ${{ vars.TURBO_TEAM }}
+```
 
-- `TURBO_TEAM`: Your Vercel team slug
+### Option B: Personal Access Token
 
-### 3. Add to Workflow
+Follow [these instructions](https://vercel.com/docs/monorepos/remote-caching/external-ci-cd#personal-access-token-pat) to create a Personal Access Token, configure your `TURBO_TOKEN` secret, and configure your `TURBO_TEAM` variable. Then provide them to jobs that run `turbo`:
 
 ```yaml
 jobs:
@@ -130,9 +143,9 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    env:
-      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
-      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+    permissions:
+      contents: read
+      id-token: write
 
     steps:
       - uses: actions/checkout@v4
@@ -148,6 +161,10 @@ jobs:
           node-version: 20
           cache: "pnpm"
 
+      - uses: vercel/setup-turborepo-remote-cache-action@v1.0.0
+        with:
+          team: ${{ vars.TURBO_TEAM }}
+
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/ci/vercel.md b/plugins/turborepo/.agents/skills/turborepo/references/ci/vercel.md
index f21d41ac..51cf44da 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/ci/vercel.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/ci/vercel.md
@@ -56,8 +56,17 @@ npx turbo-ignore web
 # Use specific comparison ref
 npx turbo-ignore --fallback=HEAD~1
 
-# Verbose output
-npx turbo-ignore --verbose
+# Check a task other than build
+npx turbo-ignore --task=test
+
+# Run in a specific directory
+npx turbo-ignore --directory=apps/web
+
+# Explicitly set which version of turbo to invoke
+npx turbo-ignore --turbo-version=2.5.0
+
+# Raise child process maxBuffer in KB (default: 1024)
+npx turbo-ignore --max-buffer=2048
 ```
 
 ## Environment Variables
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/cli/commands.md b/plugins/turborepo/.agents/skills/turborepo/references/cli/commands.md
index c1eb6b2f..5f393762 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/cli/commands.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/cli/commands.md
@@ -73,10 +73,13 @@ turbo build --concurrency=50%    # 50% of CPU cores
 
 ### `--continue`
 
-Keep running other tasks when one fails.
+Control whether other tasks keep running when one fails. Value requires `=` — `--continue never` parses `never` as a task name and the flag becomes `--continue=always`.
 
 ```bash
-turbo build test --continue
+turbo build test --continue                          # bare flag = --continue=always
+turbo build test --continue=never                    # cancel remaining tasks on failure (default)
+turbo build test --continue=dependencies-successful  # continue tasks whose dependencies succeeded
+turbo build test --continue=always                   # continue all tasks, even with failed dependencies
 ```
 
 ### `--only`
@@ -87,9 +90,9 @@ Run only the specified task, skip its dependencies.
 turbo build --only  # skip running dependsOn tasks
 ```
 
-### `--parallel` (Discouraged)
+### `--parallel` (Deprecated)
 
-Ignores task graph dependencies, runs all tasks simultaneously. **Avoid using this flag**—if tasks need to run in parallel, configure `dependsOn` correctly instead. Using `--parallel` bypasses Turborepo's dependency graph, which can cause race conditions and incorrect builds.
+Ignores task graph dependencies, runs all tasks simultaneously. **Deprecated, will be removed in a future major version**—use task configuration (`persistent`, `with`) in `turbo.json` instead. Using `--parallel` bypasses Turborepo's dependency graph, which can cause race conditions and incorrect builds.
 
 ## Cache Control
 
@@ -118,13 +121,15 @@ turbo build --cache=local:,remote:
 Generate task graph visualization.
 
 ```bash
-turbo build --graph                # opens in browser
+turbo build --graph                # prints dot graph to stdout
 turbo build --graph=graph.svg      # SVG file
-turbo build --graph=graph.png      # PNG file
-turbo build --graph=graph.json     # JSON data
+turbo build --graph=graph.html     # HTML file
 turbo build --graph=graph.mermaid  # Mermaid diagram
+turbo build --graph=graph.dot      # DOT file
 ```
 
+`.png`, `.jpg`, `.pdf`, and `.json` are deprecated (removed in 3.0; require external Graphviz). For programmatic access, use `turbo query` instead.
+
 ### `--summarize`
 
 Generate JSON run summary for debugging.
@@ -140,6 +145,7 @@ Control log output verbosity.
 
 ```bash
 turbo build --output-logs=full        # all logs (default)
+turbo build --output-logs=hash-only   # only task hashes
 turbo build --output-logs=new-only    # only cache misses
 turbo build --output-logs=errors-only # only failures
 turbo build --output-logs=none        # silent
@@ -172,7 +178,7 @@ Control environment variable handling.
 
 ```bash
 turbo build --env-mode=strict  # only declared env vars (default)
-turbo build --env-mode=loose   # include all env vars in hash
+turbo build --env-mode=loose   # all env vars available at runtime; hashing still limited to declared vars
 ```
 
 ## UI
@@ -182,10 +188,26 @@ turbo build --env-mode=loose   # include all env vars in hash
 Select output interface.
 
 ```bash
-turbo build --ui=tui     # interactive terminal UI (default in TTY)
-turbo build --ui=stream  # streaming logs (default in CI)
+turbo build --ui=stream  # streaming logs (default)
+turbo build --ui=tui     # interactive terminal UI (opt-in; requires a TTY)
+turbo build --ui=stream-with-experimental-timestamps  # streaming logs with timestamps (experimental)
 ```
 
+### TUI keybinds
+
+| Key              | Action                                                   |
+| ---------------- | -------------------------------------------------------- |
+| `↑`/`k`, `↓`/`j` | Select previous/next task                                |
+| `h`              | Show selected task's logs full-screen, verbatim (toggle) |
+| `s`              | Stream all task logs (toggle)                            |
+| `Shift+H`        | Toggle task list sidebar                                 |
+| `i` or `Enter`   | Interact with selected task                              |
+| `Ctrl+Z`         | Stop interacting with task                               |
+| `/`              | Filter tasks to search term (`Esc` clears)               |
+| `p`              | Toggle pinned task selection                             |
+| `u` / `d`        | Scroll logs up/down                                      |
+| `m`              | Toggle keybind help popup                                |
+
 ---
 
 # turbo-ignore
@@ -222,7 +244,7 @@ npx turbo-ignore --task=test
   continue-on-error: true
 
 - name: Build
-  if: steps.turbo-ignore.outcome == 'failure'  # changes detected
+  if: steps.turbo-ignore.outcome == 'failure' # changes detected
   run: pnpm build
 ```
 
@@ -267,7 +289,10 @@ See `references/watch/` for details.
 Create sparse checkout for Docker.
 
 ```bash
-turbo prune web --docker
+turbo prune web --docker                # split output into json/ and full/ for layer caching
+turbo prune web --production            # exclude in-workspace devDependencies
+turbo prune web --out-dir=./custom-out  # output directory (default: ./out)
+turbo prune web --use-gitignore=false   # copy files ignored by .gitignore (default: true)
 ```
 
 ## turbo link / unlink
@@ -295,3 +320,41 @@ Scaffold new packages.
 ```bash
 turbo generate
 ```
+
+## turbo docs
+
+Search the Turborepo documentation.
+
+```bash
+turbo docs "how does caching work"
+turbo docs "prune" --docs-version=2.7.5  # override docs version (minimum: 2.7.5)
+```
+
+## turbo ls
+
+List packages in the monorepo (experimental).
+
+```bash
+turbo ls                 # all packages
+turbo ls web             # details for a specific package
+turbo ls --affected      # only packages changed vs main
+turbo ls --output=json   # machine-readable (default: pretty)
+```
+
+## turbo query
+
+Query the monorepo using GraphQL.
+
+```bash
+turbo query                                          # spins up GraphiQL server
+turbo query "query { packages { items { name } } }"  # run a query string
+turbo query ./query.gql                              # run a query from a file
+```
+
+## More
+
+- `turbo devtools` - visualize the package graph in the browser
+- `turbo info` - print debugging information
+- `turbo bin` - print the path to the turbo binary
+- `turbo daemon` - run/manage the background daemon
+- `turbo telemetry` - enable or disable anonymous telemetry
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/configuration/RULE.md b/plugins/turborepo/.agents/skills/turborepo/references/configuration/RULE.md
index 7b5343d8..e5792cf3 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/configuration/RULE.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/configuration/RULE.md
@@ -73,7 +73,7 @@ When you run `turbo run lint`, Turborepo finds all packages with a `lint` script
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "globalEnv": ["CI"],
   "globalDependencies": ["tsconfig.json"],
   "tasks": {
@@ -97,7 +97,7 @@ When the `globalConfiguration` future flag is enabled, global options move under
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "futureFlags": { "globalConfiguration": true },
   "global": {
     "inputs": ["tsconfig.json"],
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/configuration/global-options.md b/plugins/turborepo/.agents/skills/turborepo/references/configuration/global-options.md
index 62ffef95..2c8181aa 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/configuration/global-options.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/configuration/global-options.md
@@ -40,11 +40,11 @@ Use for credentials that shouldn't affect cache keys.
 
 ## cacheDir
 
-Custom cache location. Default: `node_modules/.cache/turbo`.
+Custom cache location. Default: `.turbo/cache`.
 
 ```json
 {
-  "cacheDir": ".turbo/cache"
+  "cacheDir": ".cache/turbo"
 }
 ```
 
@@ -95,17 +95,17 @@ Configure remote caching.
 }
 ```
 
-| Option          | Default                | Description                                            |
-| --------------- | ---------------------- | ------------------------------------------------------ |
-| `enabled`       | `true`                 | Enable/disable remote caching                          |
-| `signature`     | `false`                | Sign artifacts with `TURBO_REMOTE_CACHE_SIGNATURE_KEY` |
-| `preflight`     | `false`                | Send OPTIONS request before cache requests             |
-| `timeout`       | `30`                   | Timeout in seconds for cache operations                |
-| `uploadTimeout` | `60`                   | Timeout in seconds for uploads                         |
-| `apiUrl`        | `"https://vercel.com"` | Remote cache API endpoint                              |
-| `loginUrl`      | `"https://vercel.com"` | Login endpoint                                         |
-| `teamId`        | -                      | Team ID (must start with `team_`)                      |
-| `teamSlug`      | -                      | Team slug for querystring                              |
+| Option          | Default                    | Description                                            |
+| --------------- | -------------------------- | ------------------------------------------------------ |
+| `enabled`       | `true`                     | Enable/disable remote caching                          |
+| `signature`     | `false`                    | Sign artifacts with `TURBO_REMOTE_CACHE_SIGNATURE_KEY` |
+| `preflight`     | `false`                    | Send OPTIONS request before cache requests             |
+| `timeout`       | `30`                       | Timeout in seconds for cache operations                |
+| `uploadTimeout` | `60`                       | Timeout in seconds for uploads                         |
+| `apiUrl`        | `"https://vercel.com/api"` | Remote cache API endpoint                              |
+| `loginUrl`      | `"https://vercel.com"`     | Login endpoint                                         |
+| `teamId`        | -                          | Team ID (must start with `team_`)                      |
+| `teamSlug`      | -                          | Team slug for querystring                              |
 
 See https://turborepo.dev/docs/core-concepts/remote-caching for setup.
 
@@ -146,6 +146,34 @@ When using `outputLogs: "errors-only"`, show task hashes on start/completion:
 
 Enforce a minimum key length of 32 bytes for `TURBO_REMOTE_CACHE_SIGNATURE_KEY` when `remoteCache.signature` is enabled. Short keys weaken HMAC-SHA256 signatures. Fails the run immediately if the key is too short.
 
+### `experimentalObservability`
+
+Enable experimental OpenTelemetry exporter support: honors the `experimentalObservability` configuration block (if present) to send run summaries to an observability backend.
+
+### `affectedUsingTaskInputs`
+
+Use task-level `inputs` globs to determine which tasks `--affected` selects — only tasks whose declared inputs match the changed files, rather than all tasks in changed packages.
+
+### `githubActionsRemoteBaseRefFallback`
+
+When GitHub Actions reports a base branch that is not available as a local ref, fall back to `origin/<branch>` (supports detached checkouts with only remote-tracking refs).
+
+### `watchUsingTaskInputs`
+
+Use task-level `inputs` globs to determine which tasks `turbo watch` re-runs when files change, rather than re-running all tasks in changed packages.
+
+### `pruneIncludesGlobalFiles`
+
+Include files matching `globalDependencies` globs in the `turbo prune` output. Without this flag, the entries are preserved in the pruned `turbo.json` but the files are not copied.
+
+### `filterUsingTasks`
+
+Resolve `--filter` at the task level: git-range filters (e.g. `--filter=[main]`) match against task `inputs` globs, and `...` traverses the task graph in addition to the package graph.
+
+### `strictTaskEntrypointSelection`
+
+When any package can run a requested task, skip packages without a command as entrypoints. Tasks with no command anywhere remain available for graph-only orchestration.
+
 ### `globalConfiguration`
 
 Moves global configuration keys under a top-level `global` key for clarity and changes how `global.inputs` (formerly `globalDependencies`) affects task hashing.
@@ -198,6 +226,14 @@ With `global.inputs` (new): files are treated as **implicit task inputs** prepen
 
 See the [gotchas doc](./gotchas.md) for guidance on using `$TURBO_DEFAULT$` with `global.inputs`.
 
+### `experimentalCargoWorkspaces`
+
+Treat the crates of a Cargo workspace as Turborepo packages: crates are discovered via `cargo metadata` and participate in the package graph, `--filter`, `--affected`, and `turbo query`. Experimental.
+
+### `experimentalPythonWorkspaces`
+
+Treat the members of a uv workspace as Turborepo packages: packages are discovered from the root `pyproject.toml`'s `[tool.uv.workspace]` members and participate in the package graph. uv is the only supported Python package manager. Experimental.
+
 ## noUpdateNotifier
 
 Disable update notifications when new turbo versions are available.
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/environment/RULE.md b/plugins/turborepo/.agents/skills/turborepo/references/environment/RULE.md
index e3cc2674..8d99fb8c 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/environment/RULE.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/environment/RULE.md
@@ -107,7 +107,7 @@ When the `globalConfiguration` future flag is enabled, global environment keys m
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "globalEnv": ["CI", "NODE_ENV"],
   "globalPassThroughEnv": ["GITHUB_TOKEN", "NPM_TOKEN"],
   "tasks": {
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/environment/gotchas.md b/plugins/turborepo/.agents/skills/turborepo/references/environment/gotchas.md
index 8fd24036..37f5d0fe 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/environment/gotchas.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/environment/gotchas.md
@@ -112,7 +112,7 @@ If you use `.env.development` and `.env.production`, both should be in inputs.
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "globalEnv": ["CI", "NODE_ENV", "VERCEL"],
   "globalPassThroughEnv": ["GITHUB_TOKEN", "VERCEL_URL"],
   "tasks": {
@@ -146,7 +146,7 @@ The same config using the `global` key. The `.env` files move to `global.inputs`
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "futureFlags": { "globalConfiguration": true },
   "global": {
     "env": ["CI", "NODE_ENV", "VERCEL"],
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/environment/modes.md b/plugins/turborepo/.agents/skills/turborepo/references/environment/modes.md
index 2e655331..dc351ef9 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/environment/modes.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/environment/modes.md
@@ -51,20 +51,22 @@ Turborepo automatically detects frameworks and includes their conventional env v
 
 ### Inferred Variables by Framework
 
-| Framework        | Pattern             |
-| ---------------- | ------------------- |
-| Next.js          | `NEXT_PUBLIC_*`     |
-| Vite             | `VITE_*`            |
-| Create React App | `REACT_APP_*`       |
-| Gatsby           | `GATSBY_*`          |
-| Nuxt             | `NUXT_*`, `NITRO_*` |
-| Expo             | `EXPO_PUBLIC_*`     |
-| Astro            | `PUBLIC_*`          |
-| SvelteKit        | `PUBLIC_*`          |
-| Remix            | `REMIX_*`           |
-| Redwood          | `REDWOOD_ENV_*`     |
-| Sanity           | `SANITY_STUDIO_*`   |
-| Solid            | `VITE_*`            |
+| Framework        | Pattern                                          |
+| ---------------- | ------------------------------------------------ |
+| Next.js          | `NEXT_PUBLIC_*`                                  |
+| Blitz.js         | `NEXT_PUBLIC_*`                                  |
+| Vite             | `VITE_*`                                         |
+| Create React App | `REACT_APP_*`                                    |
+| Gatsby           | `GATSBY_*`                                       |
+| Nitro            | `NITRO_*`, `SERVER_*`, plus deploy-platform vars |
+| Nuxt             | All Nitro vars plus `NUXT_*`, `LAUNCH_EDITOR`    |
+| Expo             | `EXPO_PUBLIC_*`                                  |
+| Astro            | `PUBLIC_*`                                       |
+| SvelteKit        | `VITE_*`, `PUBLIC_*`                             |
+| Redwood          | `REDWOOD_ENV_*`                                  |
+| Sanity           | `SANITY_STUDIO_*`                                |
+| Solid            | `VITE_*`                                         |
+| Vue              | `VUE_APP_*`, `LAUNCH_EDITOR`                     |
 
 ### Disabling Framework Inference
 
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/filtering/RULE.md b/plugins/turborepo/.agents/skills/turborepo/references/filtering/RULE.md
index 04e19cc8..1ef55f6d 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/filtering/RULE.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/filtering/RULE.md
@@ -9,7 +9,7 @@
 turbo run build test lint --affected
 ```
 
-This compares your current branch to the default branch (usually `main` or `master`) and runs tasks in:
+This compares your current branch to `main` (falling back to `master`) and runs tasks in:
 
 1. Packages with file changes
 2. Packages that depend on changed packages (dependents)
@@ -22,12 +22,14 @@ If you change `@repo/ui`, packages that import `@repo/ui` (like `apps/web`) need
 
 ```bash
 # Use a different base branch
-turbo run build --affected --affected-base=origin/develop
+TURBO_SCM_BASE=origin/develop turbo run build --affected
 
 # Use a different head (current state)
-turbo run build --affected --affected-head=HEAD~5
+TURBO_SCM_HEAD=HEAD~5 turbo run build --affected
 ```
 
+Base resolution order: `TURBO_SCM_BASE`, then the CI base ref on GitHub Actions (`GITHUB_BASE_REF` for PRs, the push event's previous SHA otherwise — errors if unresolvable rather than falling through), then the literal refs `main`, `master`. Turborepo does NOT read the repo's configured default branch — if the default branch is anything else (e.g. `develop`), set `TURBO_SCM_BASE`.
+
 ### Common CI Pattern
 
 ```yaml
@@ -139,10 +141,10 @@ turbo run build --filter=web --filter=api   # runs in both
 
 ## Quick Reference: Changed Packages
 
-| Goal                               | Command                                                     |
-| ---------------------------------- | ----------------------------------------------------------- |
-| Changed + dependents (recommended) | `turbo run build --affected`                                |
-| Custom base branch                 | `turbo run build --affected --affected-base=origin/develop` |
-| Only changed (no dependents)       | `turbo run build --filter=[origin/main]`                    |
-| Changed + dependencies             | `turbo run build --filter=[origin/main]...`                 |
-| Since last commit                  | `turbo run build --filter=...[HEAD^1]`                      |
+| Goal                               | Command                                                    |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Changed + dependents (recommended) | `turbo run build --affected`                               |
+| Custom base branch                 | `TURBO_SCM_BASE=origin/develop turbo run build --affected` |
+| Only changed (no dependents)       | `turbo run build --filter=[origin/main]`                   |
+| Changed + dependencies             | `turbo run build --filter=[origin/main]...`                |
+| Since last commit                  | `turbo run build --filter=...[HEAD^1]`                     |
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/filtering/patterns.md b/plugins/turborepo/.agents/skills/turborepo/references/filtering/patterns.md
index 17b9f1c5..f7308471 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/filtering/patterns.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/filtering/patterns.md
@@ -105,10 +105,12 @@ turbo run lint --filter=!legacy-app --filter=!deprecated-pkg
 
 ## Complex Combinations
 
-Apps that changed, plus their dependents:
+Separate `--filter` flags are unioned, not intersected — to intersect a directory with a git range, wrap the directory in `{}` inside a single filter.
+
+Apps that changed since the last commit:
 
 ```bash
-turbo run build --filter=...[HEAD^1] --filter=./apps/*
+turbo run build --filter={./apps/*}[HEAD^1]
 ```
 
 All packages except docs, but only if changed:
@@ -142,7 +144,7 @@ turbo run build test lint --affected
 Deploy only changed apps:
 
 ```bash
-turbo run deploy --filter=./apps/* --filter=[main...HEAD]
+turbo run deploy --filter={./apps/*}[main...HEAD]
 ```
 
 Full rebuild of specific app and deps:
diff --git a/plugins/turborepo/.agents/skills/turborepo/references/watch/RULE.md b/plugins/turborepo/.agents/skills/turborepo/references/watch/RULE.md
index 44bcf13e..87324395 100644
--- a/plugins/turborepo/.agents/skills/turborepo/references/watch/RULE.md
+++ b/plugins/turborepo/.agents/skills/turborepo/references/watch/RULE.md
@@ -16,10 +16,15 @@ turbo watch build
 
 # Watch multiple tasks
 turbo watch build test lint
+
+# No tasks: lists available tasks and exits non-zero
+turbo watch
 ```
 
 Tasks re-run in order configured in `turbo.json` when source files change.
 
+By default, any file change in a package re-runs all of that package's tasks. Enable `futureFlags.watchUsingTaskInputs` in `turbo.json` to re-run only tasks whose `inputs` globs match the changed files.
+
 ## With Persistent Tasks
 
 Persistent tasks (`"persistent": true`) won't exit, so they can't be depended on. They work the same in `turbo watch` as `turbo run`.
diff --git a/plugins/turborepo/.claude/skills/turborepo b/plugins/turborepo/.claude/skills/turborepo
new file mode 120000
index 00000000..b69a7d9e
--- /dev/null
+++ b/plugins/turborepo/.claude/skills/turborepo
@@ -0,0 +1 @@
+../../.agents/skills/turborepo
\ No newline at end of file
diff --git a/plugins/turborepo/agent/skills/turborepo/SKILL.md b/plugins/turborepo/agent/skills/turborepo/SKILL.md
index 725b3e3f..243e40f8 100644
--- a/plugins/turborepo/agent/skills/turborepo/SKILL.md
+++ b/plugins/turborepo/agent/skills/turborepo/SKILL.md
@@ -1,6 +1,6 @@
 ---
 description: "Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines,\ndependsOn, caching, remote cache, the \"turbo\" CLI, --filter, --affected, CI optimization, environment\nvariables, internal packages, monorepo structure/best practices, and boundaries.\n\nUse when user: configures tasks/workflows/pipelines, creates packages, sets up\nmonorepo, shares code between apps, runs changed/affected packages, debugs cache,\nor has apps/packages directories.\n"
-metadata: {"version":"2.10.4-canary.1"}
+metadata: {"version":"2.10.9"}
 ---
 # Turborepo Skill
 
@@ -118,12 +118,12 @@ Cache problems?
 ```
 Run only what changed?
 ├─ Changed packages + dependents (RECOMMENDED) → turbo run build --affected
-├─ Custom base branch → --affected --affected-base=origin/develop
+├─ Custom base branch → TURBO_SCM_BASE=origin/develop turbo run build --affected
 ├─ Manual git comparison → --filter=...[origin/main]
 └─ See all filter options → references/filtering/RULE.md
 ```
 
-**`--affected` is the primary way to run only changed packages.** It automatically compares against the default branch and includes dependents.
+**`--affected` is the primary way to run only changed packages.** It compares against `main` (falling back to `master`) — not the repo's configured default branch — and includes dependents. Set `TURBO_SCM_BASE` for any other base branch.
 
 ### "I want to filter packages"
 
@@ -417,7 +417,7 @@ A large `env` array (even 50+ variables) is **not** a problem. It usually means
 
 ### Using `--parallel` Flag
 
-The `--parallel` flag bypasses Turborepo's dependency graph. If tasks need parallel execution, configure `dependsOn` correctly instead.
+The `--parallel` flag bypasses Turborepo's dependency graph. It is deprecated and will be removed in a future major version—use task configuration (`persistent`, `with`) instead.
 
 ```bash
 # WRONG - bypasses dependency graph
@@ -730,7 +730,7 @@ import { Button } from "@repo/ui/button";
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "tasks": {
     "build": {
       "dependsOn": ["^build"],
diff --git a/plugins/turborepo/agent/skills/turborepo/references/best-practices/structure.md b/plugins/turborepo/agent/skills/turborepo/references/best-practices/structure.md
index 90b0d4df..cb2aad50 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/best-practices/structure.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/best-practices/structure.md
@@ -13,7 +13,7 @@ packages:
   - "packages/*"
 ```
 
-### npm/yarn/bun
+### npm/yarn/bun/nub
 
 ```json
 // package.json
@@ -22,6 +22,17 @@ packages:
 }
 ```
 
+nub follows the repo's existing lockfile: with a pnpm-format lockfile (`pnpm-lock.yaml` or nub's `lock.yaml`) it reads `pnpm-workspace.yaml` when that file exists, otherwise `package.json` workspaces.
+
+### aube
+
+aube uses `aube-workspace.yaml` (same `packages:` format as pnpm), falling back to `pnpm-workspace.yaml` or `package.json` workspaces.
+
+### Polyglot workspaces (experimental)
+
+- `futureFlags.experimentalCargoWorkspaces` - Treat Cargo workspace crates as Turborepo packages
+- `futureFlags.experimentalPythonWorkspaces` - Treat uv workspace members as Turborepo packages
+
 ## Root package.json
 
 ```json
@@ -95,7 +106,7 @@ Package tasks enable Turborepo to:
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "tasks": {
     "build": {
       "dependsOn": ["^build"],
@@ -117,7 +128,7 @@ With `futureFlags.globalConfiguration`, global settings move under a `global` ke
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "futureFlags": { "globalConfiguration": true },
   "global": {
     "inputs": ["tsconfig.json"],
@@ -262,28 +273,34 @@ packages/
     ├── package.json
     ├── base.js
     ├── next.js
-    └── library.js
+    └── react-internal.js
 ```
 
 ```json
 // packages/eslint-config/package.json
 {
   "name": "@repo/eslint-config",
+  "type": "module",
   "exports": {
     "./base": "./base.js",
-    "./next": "./next.js",
-    "./library": "./library.js"
+    "./next-js": "./next.js",
+    "./react-internal": "./react-internal.js"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.1"
   }
 }
 ```
 
 ### Using in Packages
 
+ESLint 9 flat config:
+
 ```js
-// apps/web/.eslintrc.js
-module.exports = {
-  extends: ["@repo/eslint-config/next"]
-};
+// apps/web/eslint.config.js
+import { nextJsConfig } from "@repo/eslint-config/next-js";
+
+export default nextJsConfig;
 ```
 
 ## Lockfile
diff --git a/plugins/turborepo/agent/skills/turborepo/references/caching/RULE.md b/plugins/turborepo/agent/skills/turborepo/references/caching/RULE.md
index 80ec53bc..5a85c17e 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/caching/RULE.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/caching/RULE.md
@@ -16,8 +16,8 @@ If inputs haven't changed, restore outputs from cache instead of re-running the
 
 These affect ALL tasks in the repo:
 
-- `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`
-- Files listed in `globalDependencies` (or `global.env` when using `globalConfiguration`)
+- `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` / `bun.lock` (binary `bun.lockb` is unsupported — run `bun install --save-text-lockfile`)
+- Files listed in `globalDependencies` (or `global.inputs` when using `globalConfiguration` — those move to task hashes, see below)
 - Environment variables in `globalEnv` (or `global.env`)
 - `turbo.json` configuration
 
diff --git a/plugins/turborepo/agent/skills/turborepo/references/caching/gotchas.md b/plugins/turborepo/agent/skills/turborepo/references/caching/gotchas.md
index e5f99770..5a0c17de 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/caching/gotchas.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/caching/gotchas.md
@@ -145,7 +145,7 @@ Task reads a file outside default inputs:
     "build": {
       "inputs": [
         "$TURBO_DEFAULT$",
-        "../../shared-config.json" // file outside package
+        "$TURBO_ROOT$/shared-config.json" // file outside package
       ]
     }
   }
diff --git a/plugins/turborepo/agent/skills/turborepo/references/caching/remote-cache.md b/plugins/turborepo/agent/skills/turborepo/references/caching/remote-cache.md
index da76458b..be143c71 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/caching/remote-cache.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/caching/remote-cache.md
@@ -103,11 +103,11 @@ TURBO_TEAM=your-team
 
 ```bash
 # Disable remote cache for a run
-turbo build --remote-cache-read-only  # read but don't write
-turbo build --no-cache                # skip cache entirely
+turbo build --remote-cache-read-only  # read but don't write; deprecated, use --cache=local:rw,remote:r
+turbo build --no-cache                # skip cache writes (reads still hit); deprecated, use --cache=local:r,remote:r
 
 # Environment variable alternative
-TURBO_REMOTE_ONLY=true  # only use remote, skip local
+TURBO_CACHE=remote:rw  # only use remote, skip local (TURBO_REMOTE_ONLY is deprecated)
 ```
 
 ## Debugging Remote Cache
diff --git a/plugins/turborepo/agent/skills/turborepo/references/ci/RULE.md b/plugins/turborepo/agent/skills/turborepo/references/ci/RULE.md
index f331c2cf..8ea815f8 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/ci/RULE.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/ci/RULE.md
@@ -65,12 +65,12 @@ fetch-depth: 0 # Full history
 
 ## Environment Variables Reference
 
-| Variable            | Purpose                              |
-| ------------------- | ------------------------------------ |
-| `TURBO_TOKEN`       | Vercel access token for remote cache |
-| `TURBO_TEAM`        | Your Vercel team slug                |
-| `TURBO_REMOTE_ONLY` | Skip local cache, use remote only    |
-| `TURBO_LOG_ORDER`   | Set to `grouped` for cleaner CI logs |
+| Variable          | Purpose                                                                    |
+| ----------------- | -------------------------------------------------------------------------- |
+| `TURBO_TOKEN`     | Vercel access token for remote cache                                       |
+| `TURBO_TEAM`      | Your Vercel team slug                                                      |
+| `TURBO_CACHE`     | Set to `remote:rw` to skip local cache (`TURBO_REMOTE_ONLY` is deprecated) |
+| `TURBO_LOG_ORDER` | Set to `grouped` for cleaner CI logs                                       |
 
 ## See Also
 
diff --git a/plugins/turborepo/agent/skills/turborepo/references/ci/github-actions.md b/plugins/turborepo/agent/skills/turborepo/references/ci/github-actions.md
index 1cdb34f3..8a5e453d 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/ci/github-actions.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/ci/github-actions.md
@@ -72,25 +72,38 @@ jobs:
 
 ## Remote Cache Setup
 
-### 1. Create Vercel Access Token
+There are two ways to authenticate to [Vercel Remote Cache](https://vercel.com/docs/monorepos/remote-caching) from GitHub Actions:
 
-1. Go to [Vercel Dashboard](https://vercel.com/account/tokens)
-2. Create a new token with appropriate scope
-3. Copy the token value
+- **OpenID Connect (OIDC)**: configure a policy that allows exchanging the CI/CD provider's OIDC tokens for short-lived Turborepo access tokens that grant access to Remote Cache (recommended).
+- **Personal Access Token (PAT)**: configure a long-lived, team-scoped PAT as a secret in your CI/CD provider (use when OIDC is not an option).
 
-### 2. Add Secrets and Variables
+For the full setup, see [Use Remote Caching from external CI/CD](https://vercel.com/docs/monorepos/remote-caching/external-ci-cd). The GitHub Actions workflow configuration is shown below.
 
-In your GitHub repository settings:
+### Option A: OpenID Connect (recommended)
 
-**Secrets** (Settings > Secrets and variables > Actions > Secrets):
+Follow [these instructions](https://vercel.com/docs/monorepos/remote-caching/external-ci-cd#openid-connect-oidc) to create an OIDC policy on your Vercel team and configure your `TURBO_TEAM` variable. Then add [`vercel/setup-turborepo-remote-cache-action`](https://github.com/vercel/setup-turborepo-remote-cache-action) before any step that runs `turbo`. It requests a GitHub OIDC token, exchanges it for a short-lived Turborepo access token, and sets `TURBO_TOKEN` and `TURBO_TEAM` environment variables for later steps that run `turbo`:
 
-- `TURBO_TOKEN`: Your Vercel access token
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
-**Variables** (Settings > Secrets and variables > Actions > Variables):
+      - uses: vercel/setup-turborepo-remote-cache-action@v1.0.0
+        with:
+          team: ${{ vars.TURBO_TEAM }}
+```
 
-- `TURBO_TEAM`: Your Vercel team slug
+### Option B: Personal Access Token
 
-### 3. Add to Workflow
+Follow [these instructions](https://vercel.com/docs/monorepos/remote-caching/external-ci-cd#personal-access-token-pat) to create a Personal Access Token, configure your `TURBO_TOKEN` secret, and configure your `TURBO_TEAM` variable. Then provide them to jobs that run `turbo`:
 
 ```yaml
 jobs:
@@ -130,9 +143,9 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    env:
-      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
-      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+    permissions:
+      contents: read
+      id-token: write
 
     steps:
       - uses: actions/checkout@v4
@@ -148,6 +161,10 @@ jobs:
           node-version: 20
           cache: "pnpm"
 
+      - uses: vercel/setup-turborepo-remote-cache-action@v1.0.0
+        with:
+          team: ${{ vars.TURBO_TEAM }}
+
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
diff --git a/plugins/turborepo/agent/skills/turborepo/references/ci/vercel.md b/plugins/turborepo/agent/skills/turborepo/references/ci/vercel.md
index f21d41ac..51cf44da 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/ci/vercel.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/ci/vercel.md
@@ -56,8 +56,17 @@ npx turbo-ignore web
 # Use specific comparison ref
 npx turbo-ignore --fallback=HEAD~1
 
-# Verbose output
-npx turbo-ignore --verbose
+# Check a task other than build
+npx turbo-ignore --task=test
+
+# Run in a specific directory
+npx turbo-ignore --directory=apps/web
+
+# Explicitly set which version of turbo to invoke
+npx turbo-ignore --turbo-version=2.5.0
+
+# Raise child process maxBuffer in KB (default: 1024)
+npx turbo-ignore --max-buffer=2048
 ```
 
 ## Environment Variables
diff --git a/plugins/turborepo/agent/skills/turborepo/references/cli/commands.md b/plugins/turborepo/agent/skills/turborepo/references/cli/commands.md
index c1eb6b2f..5f393762 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/cli/commands.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/cli/commands.md
@@ -73,10 +73,13 @@ turbo build --concurrency=50%    # 50% of CPU cores
 
 ### `--continue`
 
-Keep running other tasks when one fails.
+Control whether other tasks keep running when one fails. Value requires `=` — `--continue never` parses `never` as a task name and the flag becomes `--continue=always`.
 
 ```bash
-turbo build test --continue
+turbo build test --continue                          # bare flag = --continue=always
+turbo build test --continue=never                    # cancel remaining tasks on failure (default)
+turbo build test --continue=dependencies-successful  # continue tasks whose dependencies succeeded
+turbo build test --continue=always                   # continue all tasks, even with failed dependencies
 ```
 
 ### `--only`
@@ -87,9 +90,9 @@ Run only the specified task, skip its dependencies.
 turbo build --only  # skip running dependsOn tasks
 ```
 
-### `--parallel` (Discouraged)
+### `--parallel` (Deprecated)
 
-Ignores task graph dependencies, runs all tasks simultaneously. **Avoid using this flag**—if tasks need to run in parallel, configure `dependsOn` correctly instead. Using `--parallel` bypasses Turborepo's dependency graph, which can cause race conditions and incorrect builds.
+Ignores task graph dependencies, runs all tasks simultaneously. **Deprecated, will be removed in a future major version**—use task configuration (`persistent`, `with`) in `turbo.json` instead. Using `--parallel` bypasses Turborepo's dependency graph, which can cause race conditions and incorrect builds.
 
 ## Cache Control
 
@@ -118,13 +121,15 @@ turbo build --cache=local:,remote:
 Generate task graph visualization.
 
 ```bash
-turbo build --graph                # opens in browser
+turbo build --graph                # prints dot graph to stdout
 turbo build --graph=graph.svg      # SVG file
-turbo build --graph=graph.png      # PNG file
-turbo build --graph=graph.json     # JSON data
+turbo build --graph=graph.html     # HTML file
 turbo build --graph=graph.mermaid  # Mermaid diagram
+turbo build --graph=graph.dot      # DOT file
 ```
 
+`.png`, `.jpg`, `.pdf`, and `.json` are deprecated (removed in 3.0; require external Graphviz). For programmatic access, use `turbo query` instead.
+
 ### `--summarize`
 
 Generate JSON run summary for debugging.
@@ -140,6 +145,7 @@ Control log output verbosity.
 
 ```bash
 turbo build --output-logs=full        # all logs (default)
+turbo build --output-logs=hash-only   # only task hashes
 turbo build --output-logs=new-only    # only cache misses
 turbo build --output-logs=errors-only # only failures
 turbo build --output-logs=none        # silent
@@ -172,7 +178,7 @@ Control environment variable handling.
 
 ```bash
 turbo build --env-mode=strict  # only declared env vars (default)
-turbo build --env-mode=loose   # include all env vars in hash
+turbo build --env-mode=loose   # all env vars available at runtime; hashing still limited to declared vars
 ```
 
 ## UI
@@ -182,10 +188,26 @@ turbo build --env-mode=loose   # include all env vars in hash
 Select output interface.
 
 ```bash
-turbo build --ui=tui     # interactive terminal UI (default in TTY)
-turbo build --ui=stream  # streaming logs (default in CI)
+turbo build --ui=stream  # streaming logs (default)
+turbo build --ui=tui     # interactive terminal UI (opt-in; requires a TTY)
+turbo build --ui=stream-with-experimental-timestamps  # streaming logs with timestamps (experimental)
 ```
 
+### TUI keybinds
+
+| Key              | Action                                                   |
+| ---------------- | -------------------------------------------------------- |
+| `↑`/`k`, `↓`/`j` | Select previous/next task                                |
+| `h`              | Show selected task's logs full-screen, verbatim (toggle) |
+| `s`              | Stream all task logs (toggle)                            |
+| `Shift+H`        | Toggle task list sidebar                                 |
+| `i` or `Enter`   | Interact with selected task                              |
+| `Ctrl+Z`         | Stop interacting with task                               |
+| `/`              | Filter tasks to search term (`Esc` clears)               |
+| `p`              | Toggle pinned task selection                             |
+| `u` / `d`        | Scroll logs up/down                                      |
+| `m`              | Toggle keybind help popup                                |
+
 ---
 
 # turbo-ignore
@@ -222,7 +244,7 @@ npx turbo-ignore --task=test
   continue-on-error: true
 
 - name: Build
-  if: steps.turbo-ignore.outcome == 'failure'  # changes detected
+  if: steps.turbo-ignore.outcome == 'failure' # changes detected
   run: pnpm build
 ```
 
@@ -267,7 +289,10 @@ See `references/watch/` for details.
 Create sparse checkout for Docker.
 
 ```bash
-turbo prune web --docker
+turbo prune web --docker                # split output into json/ and full/ for layer caching
+turbo prune web --production            # exclude in-workspace devDependencies
+turbo prune web --out-dir=./custom-out  # output directory (default: ./out)
+turbo prune web --use-gitignore=false   # copy files ignored by .gitignore (default: true)
 ```
 
 ## turbo link / unlink
@@ -295,3 +320,41 @@ Scaffold new packages.
 ```bash
 turbo generate
 ```
+
+## turbo docs
+
+Search the Turborepo documentation.
+
+```bash
+turbo docs "how does caching work"
+turbo docs "prune" --docs-version=2.7.5  # override docs version (minimum: 2.7.5)
+```
+
+## turbo ls
+
+List packages in the monorepo (experimental).
+
+```bash
+turbo ls                 # all packages
+turbo ls web             # details for a specific package
+turbo ls --affected      # only packages changed vs main
+turbo ls --output=json   # machine-readable (default: pretty)
+```
+
+## turbo query
+
+Query the monorepo using GraphQL.
+
+```bash
+turbo query                                          # spins up GraphiQL server
+turbo query "query { packages { items { name } } }"  # run a query string
+turbo query ./query.gql                              # run a query from a file
+```
+
+## More
+
+- `turbo devtools` - visualize the package graph in the browser
+- `turbo info` - print debugging information
+- `turbo bin` - print the path to the turbo binary
+- `turbo daemon` - run/manage the background daemon
+- `turbo telemetry` - enable or disable anonymous telemetry
diff --git a/plugins/turborepo/agent/skills/turborepo/references/configuration/RULE.md b/plugins/turborepo/agent/skills/turborepo/references/configuration/RULE.md
index 7b5343d8..e5792cf3 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/configuration/RULE.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/configuration/RULE.md
@@ -73,7 +73,7 @@ When you run `turbo run lint`, Turborepo finds all packages with a `lint` script
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "globalEnv": ["CI"],
   "globalDependencies": ["tsconfig.json"],
   "tasks": {
@@ -97,7 +97,7 @@ When the `globalConfiguration` future flag is enabled, global options move under
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "futureFlags": { "globalConfiguration": true },
   "global": {
     "inputs": ["tsconfig.json"],
diff --git a/plugins/turborepo/agent/skills/turborepo/references/configuration/global-options.md b/plugins/turborepo/agent/skills/turborepo/references/configuration/global-options.md
index 62ffef95..2c8181aa 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/configuration/global-options.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/configuration/global-options.md
@@ -40,11 +40,11 @@ Use for credentials that shouldn't affect cache keys.
 
 ## cacheDir
 
-Custom cache location. Default: `node_modules/.cache/turbo`.
+Custom cache location. Default: `.turbo/cache`.
 
 ```json
 {
-  "cacheDir": ".turbo/cache"
+  "cacheDir": ".cache/turbo"
 }
 ```
 
@@ -95,17 +95,17 @@ Configure remote caching.
 }
 ```
 
-| Option          | Default                | Description                                            |
-| --------------- | ---------------------- | ------------------------------------------------------ |
-| `enabled`       | `true`                 | Enable/disable remote caching                          |
-| `signature`     | `false`                | Sign artifacts with `TURBO_REMOTE_CACHE_SIGNATURE_KEY` |
-| `preflight`     | `false`                | Send OPTIONS request before cache requests             |
-| `timeout`       | `30`                   | Timeout in seconds for cache operations                |
-| `uploadTimeout` | `60`                   | Timeout in seconds for uploads                         |
-| `apiUrl`        | `"https://vercel.com"` | Remote cache API endpoint                              |
-| `loginUrl`      | `"https://vercel.com"` | Login endpoint                                         |
-| `teamId`        | -                      | Team ID (must start with `team_`)                      |
-| `teamSlug`      | -                      | Team slug for querystring                              |
+| Option          | Default                    | Description                                            |
+| --------------- | -------------------------- | ------------------------------------------------------ |
+| `enabled`       | `true`                     | Enable/disable remote caching                          |
+| `signature`     | `false`                    | Sign artifacts with `TURBO_REMOTE_CACHE_SIGNATURE_KEY` |
+| `preflight`     | `false`                    | Send OPTIONS request before cache requests             |
+| `timeout`       | `30`                       | Timeout in seconds for cache operations                |
+| `uploadTimeout` | `60`                       | Timeout in seconds for uploads                         |
+| `apiUrl`        | `"https://vercel.com/api"` | Remote cache API endpoint                              |
+| `loginUrl`      | `"https://vercel.com"`     | Login endpoint                                         |
+| `teamId`        | -                          | Team ID (must start with `team_`)                      |
+| `teamSlug`      | -                          | Team slug for querystring                              |
 
 See https://turborepo.dev/docs/core-concepts/remote-caching for setup.
 
@@ -146,6 +146,34 @@ When using `outputLogs: "errors-only"`, show task hashes on start/completion:
 
 Enforce a minimum key length of 32 bytes for `TURBO_REMOTE_CACHE_SIGNATURE_KEY` when `remoteCache.signature` is enabled. Short keys weaken HMAC-SHA256 signatures. Fails the run immediately if the key is too short.
 
+### `experimentalObservability`
+
+Enable experimental OpenTelemetry exporter support: honors the `experimentalObservability` configuration block (if present) to send run summaries to an observability backend.
+
+### `affectedUsingTaskInputs`
+
+Use task-level `inputs` globs to determine which tasks `--affected` selects — only tasks whose declared inputs match the changed files, rather than all tasks in changed packages.
+
+### `githubActionsRemoteBaseRefFallback`
+
+When GitHub Actions reports a base branch that is not available as a local ref, fall back to `origin/<branch>` (supports detached checkouts with only remote-tracking refs).
+
+### `watchUsingTaskInputs`
+
+Use task-level `inputs` globs to determine which tasks `turbo watch` re-runs when files change, rather than re-running all tasks in changed packages.
+
+### `pruneIncludesGlobalFiles`
+
+Include files matching `globalDependencies` globs in the `turbo prune` output. Without this flag, the entries are preserved in the pruned `turbo.json` but the files are not copied.
+
+### `filterUsingTasks`
+
+Resolve `--filter` at the task level: git-range filters (e.g. `--filter=[main]`) match against task `inputs` globs, and `...` traverses the task graph in addition to the package graph.
+
+### `strictTaskEntrypointSelection`
+
+When any package can run a requested task, skip packages without a command as entrypoints. Tasks with no command anywhere remain available for graph-only orchestration.
+
 ### `globalConfiguration`
 
 Moves global configuration keys under a top-level `global` key for clarity and changes how `global.inputs` (formerly `globalDependencies`) affects task hashing.
@@ -198,6 +226,14 @@ With `global.inputs` (new): files are treated as **implicit task inputs** prepen
 
 See the [gotchas doc](./gotchas.md) for guidance on using `$TURBO_DEFAULT$` with `global.inputs`.
 
+### `experimentalCargoWorkspaces`
+
+Treat the crates of a Cargo workspace as Turborepo packages: crates are discovered via `cargo metadata` and participate in the package graph, `--filter`, `--affected`, and `turbo query`. Experimental.
+
+### `experimentalPythonWorkspaces`
+
+Treat the members of a uv workspace as Turborepo packages: packages are discovered from the root `pyproject.toml`'s `[tool.uv.workspace]` members and participate in the package graph. uv is the only supported Python package manager. Experimental.
+
 ## noUpdateNotifier
 
 Disable update notifications when new turbo versions are available.
diff --git a/plugins/turborepo/agent/skills/turborepo/references/environment/RULE.md b/plugins/turborepo/agent/skills/turborepo/references/environment/RULE.md
index e3cc2674..8d99fb8c 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/environment/RULE.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/environment/RULE.md
@@ -107,7 +107,7 @@ When the `globalConfiguration` future flag is enabled, global environment keys m
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "globalEnv": ["CI", "NODE_ENV"],
   "globalPassThroughEnv": ["GITHUB_TOKEN", "NPM_TOKEN"],
   "tasks": {
diff --git a/plugins/turborepo/agent/skills/turborepo/references/environment/gotchas.md b/plugins/turborepo/agent/skills/turborepo/references/environment/gotchas.md
index 8fd24036..37f5d0fe 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/environment/gotchas.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/environment/gotchas.md
@@ -112,7 +112,7 @@ If you use `.env.development` and `.env.production`, both should be in inputs.
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "globalEnv": ["CI", "NODE_ENV", "VERCEL"],
   "globalPassThroughEnv": ["GITHUB_TOKEN", "VERCEL_URL"],
   "tasks": {
@@ -146,7 +146,7 @@ The same config using the `global` key. The `.env` files move to `global.inputs`
 
 ```json
 {
-  "$schema": "https://v2-10-4-canary-1.turborepo.dev/schema.json",
+  "$schema": "https://v2-10-9.turborepo.dev/schema.json",
   "futureFlags": { "globalConfiguration": true },
   "global": {
     "env": ["CI", "NODE_ENV", "VERCEL"],
diff --git a/plugins/turborepo/agent/skills/turborepo/references/environment/modes.md b/plugins/turborepo/agent/skills/turborepo/references/environment/modes.md
index 2e655331..dc351ef9 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/environment/modes.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/environment/modes.md
@@ -51,20 +51,22 @@ Turborepo automatically detects frameworks and includes their conventional env v
 
 ### Inferred Variables by Framework
 
-| Framework        | Pattern             |
-| ---------------- | ------------------- |
-| Next.js          | `NEXT_PUBLIC_*`     |
-| Vite             | `VITE_*`            |
-| Create React App | `REACT_APP_*`       |
-| Gatsby           | `GATSBY_*`          |
-| Nuxt             | `NUXT_*`, `NITRO_*` |
-| Expo             | `EXPO_PUBLIC_*`     |
-| Astro            | `PUBLIC_*`          |
-| SvelteKit        | `PUBLIC_*`          |
-| Remix            | `REMIX_*`           |
-| Redwood          | `REDWOOD_ENV_*`     |
-| Sanity           | `SANITY_STUDIO_*`   |
-| Solid            | `VITE_*`            |
+| Framework        | Pattern                                          |
+| ---------------- | ------------------------------------------------ |
+| Next.js          | `NEXT_PUBLIC_*`                                  |
+| Blitz.js         | `NEXT_PUBLIC_*`                                  |
+| Vite             | `VITE_*`                                         |
+| Create React App | `REACT_APP_*`                                    |
+| Gatsby           | `GATSBY_*`                                       |
+| Nitro            | `NITRO_*`, `SERVER_*`, plus deploy-platform vars |
+| Nuxt             | All Nitro vars plus `NUXT_*`, `LAUNCH_EDITOR`    |
+| Expo             | `EXPO_PUBLIC_*`                                  |
+| Astro            | `PUBLIC_*`                                       |
+| SvelteKit        | `VITE_*`, `PUBLIC_*`                             |
+| Redwood          | `REDWOOD_ENV_*`                                  |
+| Sanity           | `SANITY_STUDIO_*`                                |
+| Solid            | `VITE_*`                                         |
+| Vue              | `VUE_APP_*`, `LAUNCH_EDITOR`                     |
 
 ### Disabling Framework Inference
 
diff --git a/plugins/turborepo/agent/skills/turborepo/references/filtering/RULE.md b/plugins/turborepo/agent/skills/turborepo/references/filtering/RULE.md
index 04e19cc8..1ef55f6d 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/filtering/RULE.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/filtering/RULE.md
@@ -9,7 +9,7 @@
 turbo run build test lint --affected
 ```
 
-This compares your current branch to the default branch (usually `main` or `master`) and runs tasks in:
+This compares your current branch to `main` (falling back to `master`) and runs tasks in:
 
 1. Packages with file changes
 2. Packages that depend on changed packages (dependents)
@@ -22,12 +22,14 @@ If you change `@repo/ui`, packages that import `@repo/ui` (like `apps/web`) need
 
 ```bash
 # Use a different base branch
-turbo run build --affected --affected-base=origin/develop
+TURBO_SCM_BASE=origin/develop turbo run build --affected
 
 # Use a different head (current state)
-turbo run build --affected --affected-head=HEAD~5
+TURBO_SCM_HEAD=HEAD~5 turbo run build --affected
 ```
 
+Base resolution order: `TURBO_SCM_BASE`, then the CI base ref on GitHub Actions (`GITHUB_BASE_REF` for PRs, the push event's previous SHA otherwise — errors if unresolvable rather than falling through), then the literal refs `main`, `master`. Turborepo does NOT read the repo's configured default branch — if the default branch is anything else (e.g. `develop`), set `TURBO_SCM_BASE`.
+
 ### Common CI Pattern
 
 ```yaml
@@ -139,10 +141,10 @@ turbo run build --filter=web --filter=api   # runs in both
 
 ## Quick Reference: Changed Packages
 
-| Goal                               | Command                                                     |
-| ---------------------------------- | ----------------------------------------------------------- |
-| Changed + dependents (recommended) | `turbo run build --affected`                                |
-| Custom base branch                 | `turbo run build --affected --affected-base=origin/develop` |
-| Only changed (no dependents)       | `turbo run build --filter=[origin/main]`                    |
-| Changed + dependencies             | `turbo run build --filter=[origin/main]...`                 |
-| Since last commit                  | `turbo run build --filter=...[HEAD^1]`                      |
+| Goal                               | Command                                                    |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Changed + dependents (recommended) | `turbo run build --affected`                               |
+| Custom base branch                 | `TURBO_SCM_BASE=origin/develop turbo run build --affected` |
+| Only changed (no dependents)       | `turbo run build --filter=[origin/main]`                   |
+| Changed + dependencies             | `turbo run build --filter=[origin/main]...`                |
+| Since last commit                  | `turbo run build --filter=...[HEAD^1]`                     |
diff --git a/plugins/turborepo/agent/skills/turborepo/references/filtering/patterns.md b/plugins/turborepo/agent/skills/turborepo/references/filtering/patterns.md
index 17b9f1c5..f7308471 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/filtering/patterns.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/filtering/patterns.md
@@ -105,10 +105,12 @@ turbo run lint --filter=!legacy-app --filter=!deprecated-pkg
 
 ## Complex Combinations
 
-Apps that changed, plus their dependents:
+Separate `--filter` flags are unioned, not intersected — to intersect a directory with a git range, wrap the directory in `{}` inside a single filter.
+
+Apps that changed since the last commit:
 
 ```bash
-turbo run build --filter=...[HEAD^1] --filter=./apps/*
+turbo run build --filter={./apps/*}[HEAD^1]
 ```
 
 All packages except docs, but only if changed:
@@ -142,7 +144,7 @@ turbo run build test lint --affected
 Deploy only changed apps:
 
 ```bash
-turbo run deploy --filter=./apps/* --filter=[main...HEAD]
+turbo run deploy --filter={./apps/*}[main...HEAD]
 ```
 
 Full rebuild of specific app and deps:
diff --git a/plugins/turborepo/agent/skills/turborepo/references/watch/RULE.md b/plugins/turborepo/agent/skills/turborepo/references/watch/RULE.md
index 44bcf13e..87324395 100644
--- a/plugins/turborepo/agent/skills/turborepo/references/watch/RULE.md
+++ b/plugins/turborepo/agent/skills/turborepo/references/watch/RULE.md
@@ -16,10 +16,15 @@ turbo watch build
 
 # Watch multiple tasks
 turbo watch build test lint
+
+# No tasks: lists available tasks and exits non-zero
+turbo watch
 ```
 
 Tasks re-run in order configured in `turbo.json` when source files change.
 
+By default, any file change in a package re-runs all of that package's tasks. Enable `futureFlags.watchUsingTaskInputs` in `turbo.json` to re-run only tasks whose `inputs` globs match the changed files.
+
 ## With Persistent Tasks
 
 Persistent tasks (`"persistent": true`) won't exit, so they can't be depended on. They work the same in `turbo watch` as `turbo run`.
diff --git a/plugins/turborepo/skills-lock.json b/plugins/turborepo/skills-lock.json
index ff9693a0..8a1a9353 100644
--- a/plugins/turborepo/skills-lock.json
+++ b/plugins/turborepo/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel/turborepo",
       "sourceType": "github",
       "skillPath": "skills/turborepo/SKILL.md",
-      "computedHash": "04d56ee39b0715b3151bfe3fe8e72fa814f395cd4bac96e8771898b136571364"
+      "computedHash": "a1ee68f55f7d232fbe095554f55e22c2080429a8a37c28adceaabad5fbe8a927"
     }
   }
 }
diff --git a/plugins/unocss/.claude/skills/unocss b/plugins/unocss/.claude/skills/unocss
new file mode 120000
index 00000000..5087c2f0
--- /dev/null
+++ b/plugins/unocss/.claude/skills/unocss
@@ -0,0 +1 @@
+../../.agents/skills/unocss
\ No newline at end of file
diff --git a/plugins/vercel-sandbox/.agents/skills/sandbox/SKILL.md b/plugins/vercel-sandbox/.agents/skills/sandbox/SKILL.md
index 1975e354..b33a0e0c 100644
--- a/plugins/vercel-sandbox/.agents/skills/sandbox/SKILL.md
+++ b/plugins/vercel-sandbox/.agents/skills/sandbox/SKILL.md
@@ -68,11 +68,9 @@ import { defineSandboxProxy } from "@vercel/sandbox/proxy";
 import ms from "ms"; // e.g., ms("5m"), ms("1h")
 ```
 
-**Available runtimes:**
-
-```typescript
-type RUNTIMES = "node26" | "node24" | "node22" | "python3.13";
-```
+**Default image:** Sandboxes use `vercel/sandbox/universal:latest`, an
+Ubuntu-based image with Node.js 24, Bun, Python 3.14, coding agents, and common
+development and debugging utilities.
 
 ## Creating Sandboxes
 
@@ -83,7 +81,6 @@ import { Sandbox } from "@vercel/sandbox";
 
 const sandbox = await Sandbox.create({
   name: "my-dev-env", // Optional, random if omitted. Unique per project.
-  runtime: "node24",
   resources: { vcpus: 4 }, // 2048 MB RAM per vCPU
   ports: [3000], // Expose up to 15 ports
   timeout: ms("10m"), // Default: 5 minutes
@@ -111,7 +108,6 @@ const sandbox = await Sandbox.get({ name: "my-dev-env" });
 ```typescript
 const sandbox = await Sandbox.getOrCreate({
   name: "my-workspace",
-  runtime: "node24",
   // Runs only the first time the sandbox is created.
   onCreate: async (sbx) => {
     await sbx.writeFiles([
@@ -160,11 +156,13 @@ const sandbox = await Sandbox.create({
     depth: 1, // Shallow clone (optional)
     revision: "main", // Branch, tag, or commit (optional)
   },
-  runtime: "node24",
   ports: [3000],
 });
 ```
 
+Git sources are cloned into a subdirectory named after the repository. For the
+example above, run commands with `cwd: "sandbox-example-next"`.
+
 ### With Private Git Repository
 
 ```typescript
@@ -175,7 +173,6 @@ const sandbox = await Sandbox.create({
     username: process.env.GIT_USERNAME!,
     password: process.env.GIT_TOKEN!, // Use PAT for password
   },
-  runtime: "node24",
 });
 ```
 
@@ -187,7 +184,6 @@ const sandbox = await Sandbox.create({
     type: "tarball",
     url: "https://example.com/project.tar.gz",
   },
-  runtime: "node24",
   ports: [3000],
 });
 ```
@@ -206,10 +202,12 @@ const sandbox = await Sandbox.create({
 
 ### From a Custom Image (VCR)
 
-Instead of a stock `runtime`, start a sandbox from a [Vercel Container
+Override the default with a [Vercel Container
 Registry](https://vercel.com/docs/container-registry) (VCR) image stored in the
-sandbox's project. `image` and `runtime` are **mutually exclusive** — pass one
-or the other, never both.
+sandbox's project.
+
+For a different distro or reproducible system tooling, prefer baking it into a
+custom image over installing packages when the sandbox starts.
 
 ```typescript
 const sandbox = await Sandbox.create({
@@ -239,17 +237,18 @@ instructions.
 
 `Sandbox.fork` seeds a new sandbox from another sandbox's current snapshot
 and copies its config (`resources`, `timeout`, `networkPolicy`, `tags`,
-`ports`, `persistent`, `snapshotExpiration`, `keepLastSnapshots`). Any field
-you pass overrides the inherited value. `env` is not copied (encrypted
-server-side) and must be re-supplied. If the source has no current snapshot,
-the fork falls back to a fresh create using the source's `runtime` plus the
-copied config.
+`ports`, `image`, `persistent`, `snapshotExpiration`, `keepLastSnapshots`,
+and `env`). Any field you pass overrides the inherited value. If the source
+has no current snapshot, the fork falls back to the source's base environment
+plus the copied config. You can only fork a sandbox in a project you have
+access to; forking an unknown source returns a 404.
 
 ```typescript
-// Inherit everything from the source
+// Inherit everything from the source (env included)
 const fork = await Sandbox.fork({ sourceSandbox: "prod-agent" });
 
-// Override specific fields; the rest are copied from the source
+// Override specific fields; the rest are copied from the source.
+// A provided `env` fully replaces the source's env (no per-key merge).
 const fork = await Sandbox.fork({
   sourceSandbox: "prod-agent",
   name: "forked-prod-agent",
@@ -316,8 +315,13 @@ await devServer.kill("SIGTERM");
 
 ```typescript
 await sandbox.runCommand({
-  cmd: "dnf",
-  args: ["install", "-y", "golang"],
+  cmd: "apt-get",
+  args: ["update"],
+  sudo: true,
+});
+await sandbox.runCommand({
+  cmd: "apt-get",
+  args: ["install", "-y", "golang-go"],
   sudo: true, // Execute as root
 });
 ```
@@ -379,6 +383,99 @@ const files = await sandbox.fs.readdir("/tmp");
 const stats = await sandbox.fs.stat("/tmp/hello.txt");
 ```
 
+## Multi-User and Groups
+
+Create isolated Linux users and shared groups inside a sandbox. This is purely
+SDK-side and is useful for isolating multiple agents or workloads within a single
+sandbox. Usernames and group names are validated to prevent command injection.
+
+### Creating Users
+
+`createUser` provisions a Linux user with an isolated home directory at
+`/home/<username>` and returns a `SandboxUser` whose operations run in that
+user's context.
+
+```typescript
+const alice = await sandbox.createUser("alice");
+alice.username; // "alice"
+alice.homeDir; // "/home/alice"
+
+// Commands run as alice; cwd defaults to /home/alice
+const whoami = await alice.runCommand("whoami");
+await whoami.stdout(); // "alice\n"
+
+// Env vars, custom cwd, sudo escalation, and detached mode all work
+await alice.runCommand({
+  cmd: "node",
+  args: ["-e", "console.log(process.env.SECRET)"],
+  env: { SECRET: "hunter2" },
+});
+await alice.runCommand({
+  cmd: "apt-get",
+  args: ["update"],
+  sudo: true,
+});
+await alice.runCommand({
+  cmd: "apt-get",
+  args: ["install", "-y", "git"],
+  sudo: true,
+});
+const server = await alice.runCommand({
+  cmd: "node",
+  args: ["server.js"],
+  detached: true,
+});
+```
+
+Get a handle to a pre-existing user (e.g. `root`) without creating it:
+
+```typescript
+const existing = sandbox.asUser("bob");
+await existing.runCommand("whoami");
+```
+
+### File Operations Scoped to a User
+
+Relative paths resolve against the user's home directory and files are owned by
+that user. Absolute paths are also supported.
+
+```typescript
+// Written to /home/alice, owned by alice:alice
+await alice.writeFiles([
+  { path: "app.js", content: Buffer.from('console.log("hi")') },
+  { path: "data/config.json", content: Buffer.from("{}") },
+]);
+
+const buf = await alice.readFileToBuffer({ path: "app.js" });
+const stream = await alice.readFile({ path: "app.js" });
+await alice.mkDir("projects/my-app");
+```
+
+Files are isolated between users — one user cannot read, list, or write another
+user's home directory (commands return a non-zero exit code with "Permission
+denied").
+
+### Groups and Shared Directories
+
+`createGroup` creates a Linux group with a shared directory at
+`/shared/<groupname>` (setgid `2770`), so files created inside it automatically
+inherit group ownership. Group members can read and write there; non-members
+are blocked.
+
+```typescript
+const devs = await sandbox.createGroup("devs");
+devs.sharedDir; // "/shared/devs"
+
+await sandbox.addUserToGroup("alice", "devs");
+await sandbox.addUserToGroup("bob", "devs");
+
+// Or via convenience methods on SandboxUser
+await alice.addToGroup("devs");
+await alice.removeFromGroup("devs");
+
+await sandbox.removeUserFromGroup("alice", "devs");
+```
+
 ## Network Policy
 
 ### Full Internet Access (Default)
@@ -650,7 +747,7 @@ number of sandboxes.
 ### Create a Snapshot
 
 ```typescript
-const sandbox = await Sandbox.create({ runtime: "node24" });
+const sandbox = await Sandbox.create();
 await sandbox.runCommand("npm", ["install"]);
 
 // Create snapshot (stops the sandbox)
@@ -824,24 +921,33 @@ const result = await sandbox.runCommand({
 | Max tags        | 5 key-value tags per sandbox                                                    |
 | Max timeout     | 24 hours (Pro/Enterprise), 45 minutes (Hobby)                                   |
 | Default timeout | 5 minutes                                                                       |
-| Base system     | Amazon Linux 2023                                                               |
-| User context    | `vercel-sandbox` user                                                           |
+| Base system     | Ubuntu 26.04                                                                    |
+| User context    | `ubuntu` user                                                                   |
 | Writable path   | `/vercel/sandbox`                                                               |
 
 ## System Packages
 
-Pre-installed: `git`, `tar`, `gzip`, `unzip`, `curl`, `openssl`, `procps`, `findutils`, `which`.
+The default image includes Node.js 24, Bun, Python 3.14, pnpm, uv, Git, GitHub
+CLI, coding agents, and common development and debugging utilities.
 
 Install additional packages with sudo:
 
 ```typescript
 await sandbox.runCommand({
-  cmd: "dnf",
+  cmd: "apt-get",
+  args: ["update"],
+  sudo: true,
+});
+await sandbox.runCommand({
+  cmd: "apt-get",
   args: ["install", "-y", "package-name"],
   sudo: true,
 });
 ```
 
+This is fine for one-offs. For reproducible dependencies or a different base
+environment, use a [custom image](#from-a-custom-image-vcr) instead.
+
 ## CLI Quick Reference
 
 ```bash
@@ -855,13 +961,13 @@ sandbox logout
 # Create and connect
 sandbox create --connect
 sandbox create --name my-app
-sandbox create --image my-repo:v1            # Boot from a VCR image (not with --runtime)
+sandbox create --image my-repo:v1            # Boot from a VCR image
 sandbox create --non-persistent              # Disable filesystem persistence
 sandbox create --snapshot-expiration 7d      # Default snapshot TTL
 sandbox create --keep-last-snapshots 1       # Retention policy
 sandbox create --tag env=staging             # Repeatable
 
-# Fork an existing sandbox (inherits config; env is NOT copied)
+# Fork an existing sandbox (inherits config, incl. env; --env replaces it)
 sandbox fork <source>
 sandbox fork <source> --name my-fork --vcpus 4 --env FOO=1
 
@@ -928,10 +1034,15 @@ const sandbox = await Sandbox.getOrCreate({
   ports: [3000],
   timeout: ms("30m"),
   onCreate: async (sbx) => {
-    await sbx.runCommand("npm", ["install"]);
+    await sbx.runCommand({ cmd: "npm", args: ["install"], cwd: "repo" });
   },
   onResume: async (sbx) => {
-    await sbx.runCommand({ cmd: "npm", args: ["run", "dev"], detached: true });
+    await sbx.runCommand({
+      cmd: "npm",
+      args: ["run", "dev"],
+      cwd: "repo",
+      detached: true,
+    });
   },
 });
 
@@ -941,19 +1052,34 @@ console.log("App running at:", sandbox.domain(3000));
 ### Build and Test Pattern (Ephemeral)
 
 ```typescript
+const repoUrl = "https://github.com/org/repo.git";
+const repoDir = "repo";
+
 await using sandbox = await Sandbox.create({
   source: { type: "git", url: repoUrl },
   persistent: false, // Skip snapshotting on shutdown
   snapshotExpiration: ms("1d"), // Short TTL for any incidental snapshot
 });
 
-const install = await sandbox.runCommand("npm", ["ci"]);
+const install = await sandbox.runCommand({
+  cmd: "npm",
+  args: ["ci"],
+  cwd: repoDir,
+});
 if (install.exitCode !== 0) throw new Error("Install failed");
 
-const build = await sandbox.runCommand("npm", ["run", "build"]);
+const build = await sandbox.runCommand({
+  cmd: "npm",
+  args: ["run", "build"],
+  cwd: repoDir,
+});
 if (build.exitCode !== 0) throw new Error("Build failed");
 
-const test = await sandbox.runCommand("npm", ["test"]);
+const test = await sandbox.runCommand({
+  cmd: "npm",
+  args: ["test"],
+  cwd: repoDir,
+});
 process.exit(test.exitCode);
 ```
 
@@ -968,7 +1094,6 @@ your code. New base snapshots are picked up automatically on the next fork.
 // Once: bootstrap the base sandbox
 await Sandbox.getOrCreate({
   name: "my-base",
-  runtime: "node24",
   keepLastSnapshots: { count: 5 }, // Keep storage flat
   onCreate: async (sbx) => {
     await sbx.runCommand("npm", ["install", "-g", "typescript", "tsx"]);
@@ -994,7 +1119,6 @@ async function runFromBase(code: string) {
 // Idempotent: first call creates, subsequent calls resume
 const sandbox = await Sandbox.getOrCreate({
   name: `workspace-${userId}`,
-  runtime: "node24",
   keepLastSnapshots: { count: 1, expiration: ms("5d") },
   onCreate: async (sbx) => {
     await sbx.runCommand("git", ["clone", repoUrl, "."]);
diff --git a/plugins/vercel-sandbox/.claude/skills/sandbox b/plugins/vercel-sandbox/.claude/skills/sandbox
new file mode 120000
index 00000000..16266b13
--- /dev/null
+++ b/plugins/vercel-sandbox/.claude/skills/sandbox
@@ -0,0 +1 @@
+../../.agents/skills/sandbox
\ No newline at end of file
diff --git a/plugins/vercel-sandbox/agent/skills/sandbox/SKILL.md b/plugins/vercel-sandbox/agent/skills/sandbox/SKILL.md
index 2f2f95fa..55008c62 100644
--- a/plugins/vercel-sandbox/agent/skills/sandbox/SKILL.md
+++ b/plugins/vercel-sandbox/agent/skills/sandbox/SKILL.md
@@ -64,11 +64,9 @@ import { defineSandboxProxy } from "@vercel/sandbox/proxy";
 import ms from "ms"; // e.g., ms("5m"), ms("1h")
 ```
 
-**Available runtimes:**
-
-```typescript
-type RUNTIMES = "node26" | "node24" | "node22" | "python3.13";
-```
+**Default image:** Sandboxes use `vercel/sandbox/universal:latest`, an
+Ubuntu-based image with Node.js 24, Bun, Python 3.14, coding agents, and common
+development and debugging utilities.
 
 ## Creating Sandboxes
 
@@ -79,7 +77,6 @@ import { Sandbox } from "@vercel/sandbox";
 
 const sandbox = await Sandbox.create({
   name: "my-dev-env", // Optional, random if omitted. Unique per project.
-  runtime: "node24",
   resources: { vcpus: 4 }, // 2048 MB RAM per vCPU
   ports: [3000], // Expose up to 15 ports
   timeout: ms("10m"), // Default: 5 minutes
@@ -107,7 +104,6 @@ const sandbox = await Sandbox.get({ name: "my-dev-env" });
 ```typescript
 const sandbox = await Sandbox.getOrCreate({
   name: "my-workspace",
-  runtime: "node24",
   // Runs only the first time the sandbox is created.
   onCreate: async (sbx) => {
     await sbx.writeFiles([
@@ -156,11 +152,13 @@ const sandbox = await Sandbox.create({
     depth: 1, // Shallow clone (optional)
     revision: "main", // Branch, tag, or commit (optional)
   },
-  runtime: "node24",
   ports: [3000],
 });
 ```
 
+Git sources are cloned into a subdirectory named after the repository. For the
+example above, run commands with `cwd: "sandbox-example-next"`.
+
 ### With Private Git Repository
 
 ```typescript
@@ -171,7 +169,6 @@ const sandbox = await Sandbox.create({
     username: process.env.GIT_USERNAME!,
     password: process.env.GIT_TOKEN!, // Use PAT for password
   },
-  runtime: "node24",
 });
 ```
 
@@ -183,7 +180,6 @@ const sandbox = await Sandbox.create({
     type: "tarball",
     url: "https://example.com/project.tar.gz",
   },
-  runtime: "node24",
   ports: [3000],
 });
 ```
@@ -202,10 +198,12 @@ const sandbox = await Sandbox.create({
 
 ### From a Custom Image (VCR)
 
-Instead of a stock `runtime`, start a sandbox from a [Vercel Container
+Override the default with a [Vercel Container
 Registry](https://vercel.com/docs/container-registry) (VCR) image stored in the
-sandbox's project. `image` and `runtime` are **mutually exclusive** — pass one
-or the other, never both.
+sandbox's project.
+
+For a different distro or reproducible system tooling, prefer baking it into a
+custom image over installing packages when the sandbox starts.
 
 ```typescript
 const sandbox = await Sandbox.create({
@@ -235,17 +233,18 @@ instructions.
 
 `Sandbox.fork` seeds a new sandbox from another sandbox's current snapshot
 and copies its config (`resources`, `timeout`, `networkPolicy`, `tags`,
-`ports`, `persistent`, `snapshotExpiration`, `keepLastSnapshots`). Any field
-you pass overrides the inherited value. `env` is not copied (encrypted
-server-side) and must be re-supplied. If the source has no current snapshot,
-the fork falls back to a fresh create using the source's `runtime` plus the
-copied config.
+`ports`, `image`, `persistent`, `snapshotExpiration`, `keepLastSnapshots`,
+and `env`). Any field you pass overrides the inherited value. If the source
+has no current snapshot, the fork falls back to the source's base environment
+plus the copied config. You can only fork a sandbox in a project you have
+access to; forking an unknown source returns a 404.
 
 ```typescript
-// Inherit everything from the source
+// Inherit everything from the source (env included)
 const fork = await Sandbox.fork({ sourceSandbox: "prod-agent" });
 
-// Override specific fields; the rest are copied from the source
+// Override specific fields; the rest are copied from the source.
+// A provided `env` fully replaces the source's env (no per-key merge).
 const fork = await Sandbox.fork({
   sourceSandbox: "prod-agent",
   name: "forked-prod-agent",
@@ -312,8 +311,13 @@ await devServer.kill("SIGTERM");
 
 ```typescript
 await sandbox.runCommand({
-  cmd: "dnf",
-  args: ["install", "-y", "golang"],
+  cmd: "apt-get",
+  args: ["update"],
+  sudo: true,
+});
+await sandbox.runCommand({
+  cmd: "apt-get",
+  args: ["install", "-y", "golang-go"],
   sudo: true, // Execute as root
 });
 ```
@@ -375,6 +379,99 @@ const files = await sandbox.fs.readdir("/tmp");
 const stats = await sandbox.fs.stat("/tmp/hello.txt");
 ```
 
+## Multi-User and Groups
+
+Create isolated Linux users and shared groups inside a sandbox. This is purely
+SDK-side and is useful for isolating multiple agents or workloads within a single
+sandbox. Usernames and group names are validated to prevent command injection.
+
+### Creating Users
+
+`createUser` provisions a Linux user with an isolated home directory at
+`/home/<username>` and returns a `SandboxUser` whose operations run in that
+user's context.
+
+```typescript
+const alice = await sandbox.createUser("alice");
+alice.username; // "alice"
+alice.homeDir; // "/home/alice"
+
+// Commands run as alice; cwd defaults to /home/alice
+const whoami = await alice.runCommand("whoami");
+await whoami.stdout(); // "alice\n"
+
+// Env vars, custom cwd, sudo escalation, and detached mode all work
+await alice.runCommand({
+  cmd: "node",
+  args: ["-e", "console.log(process.env.SECRET)"],
+  env: { SECRET: "hunter2" },
+});
+await alice.runCommand({
+  cmd: "apt-get",
+  args: ["update"],
+  sudo: true,
+});
+await alice.runCommand({
+  cmd: "apt-get",
+  args: ["install", "-y", "git"],
+  sudo: true,
+});
+const server = await alice.runCommand({
+  cmd: "node",
+  args: ["server.js"],
+  detached: true,
+});
+```
+
+Get a handle to a pre-existing user (e.g. `root`) without creating it:
+
+```typescript
+const existing = sandbox.asUser("bob");
+await existing.runCommand("whoami");
+```
+
+### File Operations Scoped to a User
+
+Relative paths resolve against the user's home directory and files are owned by
+that user. Absolute paths are also supported.
+
+```typescript
+// Written to /home/alice, owned by alice:alice
+await alice.writeFiles([
+  { path: "app.js", content: Buffer.from('console.log("hi")') },
+  { path: "data/config.json", content: Buffer.from("{}") },
+]);
+
+const buf = await alice.readFileToBuffer({ path: "app.js" });
+const stream = await alice.readFile({ path: "app.js" });
+await alice.mkDir("projects/my-app");
+```
+
+Files are isolated between users — one user cannot read, list, or write another
+user's home directory (commands return a non-zero exit code with "Permission
+denied").
+
+### Groups and Shared Directories
+
+`createGroup` creates a Linux group with a shared directory at
+`/shared/<groupname>` (setgid `2770`), so files created inside it automatically
+inherit group ownership. Group members can read and write there; non-members
+are blocked.
+
+```typescript
+const devs = await sandbox.createGroup("devs");
+devs.sharedDir; // "/shared/devs"
+
+await sandbox.addUserToGroup("alice", "devs");
+await sandbox.addUserToGroup("bob", "devs");
+
+// Or via convenience methods on SandboxUser
+await alice.addToGroup("devs");
+await alice.removeFromGroup("devs");
+
+await sandbox.removeUserFromGroup("alice", "devs");
+```
+
 ## Network Policy
 
 ### Full Internet Access (Default)
@@ -646,7 +743,7 @@ number of sandboxes.
 ### Create a Snapshot
 
 ```typescript
-const sandbox = await Sandbox.create({ runtime: "node24" });
+const sandbox = await Sandbox.create();
 await sandbox.runCommand("npm", ["install"]);
 
 // Create snapshot (stops the sandbox)
@@ -820,24 +917,33 @@ const result = await sandbox.runCommand({
 | Max tags        | 5 key-value tags per sandbox                                                    |
 | Max timeout     | 24 hours (Pro/Enterprise), 45 minutes (Hobby)                                   |
 | Default timeout | 5 minutes                                                                       |
-| Base system     | Amazon Linux 2023                                                               |
-| User context    | `vercel-sandbox` user                                                           |
+| Base system     | Ubuntu 26.04                                                                    |
+| User context    | `ubuntu` user                                                                   |
 | Writable path   | `/vercel/sandbox`                                                               |
 
 ## System Packages
 
-Pre-installed: `git`, `tar`, `gzip`, `unzip`, `curl`, `openssl`, `procps`, `findutils`, `which`.
+The default image includes Node.js 24, Bun, Python 3.14, pnpm, uv, Git, GitHub
+CLI, coding agents, and common development and debugging utilities.
 
 Install additional packages with sudo:
 
 ```typescript
 await sandbox.runCommand({
-  cmd: "dnf",
+  cmd: "apt-get",
+  args: ["update"],
+  sudo: true,
+});
+await sandbox.runCommand({
+  cmd: "apt-get",
   args: ["install", "-y", "package-name"],
   sudo: true,
 });
 ```
 
+This is fine for one-offs. For reproducible dependencies or a different base
+environment, use a [custom image](#from-a-custom-image-vcr) instead.
+
 ## CLI Quick Reference
 
 ```bash
@@ -851,13 +957,13 @@ sandbox logout
 # Create and connect
 sandbox create --connect
 sandbox create --name my-app
-sandbox create --image my-repo:v1            # Boot from a VCR image (not with --runtime)
+sandbox create --image my-repo:v1            # Boot from a VCR image
 sandbox create --non-persistent              # Disable filesystem persistence
 sandbox create --snapshot-expiration 7d      # Default snapshot TTL
 sandbox create --keep-last-snapshots 1       # Retention policy
 sandbox create --tag env=staging             # Repeatable
 
-# Fork an existing sandbox (inherits config; env is NOT copied)
+# Fork an existing sandbox (inherits config, incl. env; --env replaces it)
 sandbox fork <source>
 sandbox fork <source> --name my-fork --vcpus 4 --env FOO=1
 
@@ -924,10 +1030,15 @@ const sandbox = await Sandbox.getOrCreate({
   ports: [3000],
   timeout: ms("30m"),
   onCreate: async (sbx) => {
-    await sbx.runCommand("npm", ["install"]);
+    await sbx.runCommand({ cmd: "npm", args: ["install"], cwd: "repo" });
   },
   onResume: async (sbx) => {
-    await sbx.runCommand({ cmd: "npm", args: ["run", "dev"], detached: true });
+    await sbx.runCommand({
+      cmd: "npm",
+      args: ["run", "dev"],
+      cwd: "repo",
+      detached: true,
+    });
   },
 });
 
@@ -937,19 +1048,34 @@ console.log("App running at:", sandbox.domain(3000));
 ### Build and Test Pattern (Ephemeral)
 
 ```typescript
+const repoUrl = "https://github.com/org/repo.git";
+const repoDir = "repo";
+
 await using sandbox = await Sandbox.create({
   source: { type: "git", url: repoUrl },
   persistent: false, // Skip snapshotting on shutdown
   snapshotExpiration: ms("1d"), // Short TTL for any incidental snapshot
 });
 
-const install = await sandbox.runCommand("npm", ["ci"]);
+const install = await sandbox.runCommand({
+  cmd: "npm",
+  args: ["ci"],
+  cwd: repoDir,
+});
 if (install.exitCode !== 0) throw new Error("Install failed");
 
-const build = await sandbox.runCommand("npm", ["run", "build"]);
+const build = await sandbox.runCommand({
+  cmd: "npm",
+  args: ["run", "build"],
+  cwd: repoDir,
+});
 if (build.exitCode !== 0) throw new Error("Build failed");
 
-const test = await sandbox.runCommand("npm", ["test"]);
+const test = await sandbox.runCommand({
+  cmd: "npm",
+  args: ["test"],
+  cwd: repoDir,
+});
 process.exit(test.exitCode);
 ```
 
@@ -964,7 +1090,6 @@ your code. New base snapshots are picked up automatically on the next fork.
 // Once: bootstrap the base sandbox
 await Sandbox.getOrCreate({
   name: "my-base",
-  runtime: "node24",
   keepLastSnapshots: { count: 5 }, // Keep storage flat
   onCreate: async (sbx) => {
     await sbx.runCommand("npm", ["install", "-g", "typescript", "tsx"]);
@@ -990,7 +1115,6 @@ async function runFromBase(code: string) {
 // Idempotent: first call creates, subsequent calls resume
 const sandbox = await Sandbox.getOrCreate({
   name: `workspace-${userId}`,
-  runtime: "node24",
   keepLastSnapshots: { count: 1, expiration: ms("5d") },
   onCreate: async (sbx) => {
     await sbx.runCommand("git", ["clone", repoUrl, "."]);
diff --git a/plugins/vercel-sandbox/skills-lock.json b/plugins/vercel-sandbox/skills-lock.json
index 68c2dfd0..abdb7ca0 100644
--- a/plugins/vercel-sandbox/skills-lock.json
+++ b/plugins/vercel-sandbox/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel/sandbox",
       "sourceType": "github",
       "skillPath": "skills/sandbox/SKILL.md",
-      "computedHash": "0332f66026a667861ecd5e1f7cf405a477633a95b5a58a0a2d05fdca37babc91"
+      "computedHash": "db6a68b8202ae01e1ab35630a48b4f20b4dbc7af3c2425954ba835533843c5e3"
     }
   }
 }
diff --git a/plugins/vinext/.agents/skills/migrate-to-vinext/SKILL.md b/plugins/vinext/.agents/skills/migrate-to-vinext/SKILL.md
index e4f287c6..6c633792 100644
--- a/plugins/vinext/.agents/skills/migrate-to-vinext/SKILL.md
+++ b/plugins/vinext/.agents/skills/migrate-to-vinext/SKILL.md
@@ -24,14 +24,15 @@ Detect the router: if an `app/` directory exists at root or under `src/`, it's A
 
 ## Quick Reference
 
-| Command         | Purpose                                                                |
-| --------------- | ---------------------------------------------------------------------- |
-| `vinext check`  | Scan project for compatibility issues, produce scored report           |
-| `vinext init`   | Automated migration — installs deps, generates config, converts to ESM |
-| `vinext dev`    | Development server with HMR                                            |
-| `vinext build`  | Production build (multi-environment for App Router)                    |
-| `vinext start`  | Local production server                                                |
-| `vinext deploy` | Build and deploy to Cloudflare Workers                                 |
+| Command                            | Purpose                                                                |
+| ---------------------------------- | ---------------------------------------------------------------------- |
+| `vinext check`                     | Scan project for compatibility issues, produce scored report           |
+| `vinext init`                      | Automated migration — installs deps, generates config, converts to ESM |
+| `vinext dev`                       | Development server with HMR                                            |
+| `vinext build`                     | Production build (multi-environment for App Router)                    |
+| `vinext start`                     | Local production server                                                |
+| `npx @vinext/cloudflare deploy`    | Build and deploy to Cloudflare Workers                                 |
+| `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+                      |
 
 ## Phase 1: Check Compatibility
 
@@ -128,7 +129,7 @@ Ensure vinext-generated output and caches are ignored:
 
 ### Option A: Cloudflare Workers (recommended for Cloudflare)
 
-If the user wants to deploy to Cloudflare Workers, use `vinext deploy`. It auto-generates `wrangler.jsonc`, worker entry, and Vite config if missing, installs `@cloudflare/vite-plugin` and `wrangler`, then builds and deploys.
+If the user wants to deploy to Cloudflare Workers, use `npx @vinext/cloudflare deploy`. With Vite+, use `vp exec vinext-cloudflare deploy` when running the locally installed bin. It builds and deploys via wrangler.
 
 For manual setup or custom worker entries, see [references/config-examples.md](references/config-examples.md).
 
@@ -181,7 +182,7 @@ NITRO_PRESET=node npx vite build      # Node.js server
 
 Nitro auto-detects the platform in most CI/CD environments, so the preset is often unnecessary.
 
-**Note:** For Cloudflare Workers, Nitro works but the native integration (`vinext deploy` / `@cloudflare/vite-plugin`) is recommended for the best developer experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
+**Note:** For Cloudflare Workers, Nitro works but the native integration (`npx @vinext/cloudflare deploy` / `vp exec vinext-cloudflare deploy` / `@cloudflare/vite-plugin`) is recommended for the best developer experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
 
 ## Phase 5: Verify
 
@@ -212,4 +213,4 @@ See [references/troubleshooting.md](references/troubleshooting.md) for common mi
 - **Do not skip the compatibility check.** Run `vinext check` before migration to surface issues early.
 - **Do not remove `next.config.js`** unless replacing it with `next.config.ts` or `.mjs`. vinext reads it for redirects, rewrites, headers, basePath, i18n, images, and env config.
 - **Do not use `getPlatformProxy()` or custom worker entries for bindings.** Use `import { env } from "cloudflare:workers"` instead. This is the modern pattern and works out of the box with vinext and `@cloudflare/vite-plugin`.
-- **For Cloudflare Workers, prefer the native integration over Nitro.** `vinext deploy` / `@cloudflare/vite-plugin` provides the best experience with `cloudflare:workers` bindings, KV caching, and image optimization. Nitro works for Cloudflare but the native setup is recommended.
+- **For Cloudflare Workers, prefer the native integration over Nitro.** `npx @vinext/cloudflare deploy` / `vp exec vinext-cloudflare deploy` / `@cloudflare/vite-plugin` provides the best experience with `cloudflare:workers` bindings, KV caching, and image optimization. Nitro works for Cloudflare but the native setup is recommended.
diff --git a/plugins/vinext/.agents/skills/migrate-to-vinext/references/config-examples.md b/plugins/vinext/.agents/skills/migrate-to-vinext/references/config-examples.md
index 91aac0ca..998f658f 100644
--- a/plugins/vinext/.agents/skills/migrate-to-vinext/references/config-examples.md
+++ b/plugins/vinext/.agents/skills/migrate-to-vinext/references/config-examples.md
@@ -50,24 +50,17 @@ export default defineConfig({
 
 ## App Router — Cloudflare Workers
 
-Full manual config with explicit RSC plugin registration and Cloudflare multi-environment setup:
+Cloudflare multi-environment setup. RSC plugin registration stays automatic — do **not** add an explicit
+`rsc()` call, or the build fails with `[vinext] Duplicate @vitejs/plugin-rsc detected`.
 
 ```ts
 import { defineConfig } from "vite";
 import vinext from "vinext";
-import rsc from "@vitejs/plugin-rsc";
 import { cloudflare } from "@cloudflare/vite-plugin";
 
 export default defineConfig({
   plugins: [
     vinext(),
-    rsc({
-      entries: {
-        rsc: "virtual:vinext-rsc-entry",
-        ssr: "virtual:vinext-app-ssr-entry",
-        client: "virtual:vinext-app-browser-entry",
-      },
-    }),
     cloudflare({
       viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
     }),
@@ -75,7 +68,10 @@ export default defineConfig({
 });
 ```
 
-In most cases `vinext deploy` generates this automatically. Only use manual config when customizing the worker entry or adding bindings.
+`@vitejs/plugin-rsc` is an optional peer dependency: it must be installed in the project, but vinext
+registers it for you. Only register it yourself after passing `rsc: false` to `vinext()`.
+
+In most cases `npx @vinext/cloudflare deploy` generates this automatically. Only use manual config when customizing the worker entry or adding bindings.
 
 ## wrangler.jsonc — Cloudflare Workers
 
@@ -179,7 +175,7 @@ NITRO_PRESET=node npx vite build
 
 Nitro auto-detects the platform in most CI/CD environments, so the `NITRO_PRESET` is often unnecessary.
 
-**For Cloudflare Workers,** Nitro works but the native integration (`vinext deploy` / `@cloudflare/vite-plugin`) is recommended for the best experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
+**For Cloudflare Workers,** Nitro works but the native integration (`npx @vinext/cloudflare deploy` / `vp exec vinext-cloudflare deploy` / `@cloudflare/vite-plugin`) is recommended for the best experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
 
 ## VinextOptions
 
@@ -188,7 +184,7 @@ Nitro auto-detects the platform in most CI/CD environments, so the `NITRO_PRESET
 | `appDir` | `string`  | project root | Custom base directory for `app/` and `pages/`     |
 | `rsc`    | `boolean` | `true`       | Auto-register `@vitejs/plugin-rsc` for App Router |
 
-## vinext deploy flags
+## @vinext/cloudflare deploy flags
 
 | Flag                 | Description                              |
 | -------------------- | ---------------------------------------- |
diff --git a/plugins/vinext/.claude/skills/migrate-to-vinext b/plugins/vinext/.claude/skills/migrate-to-vinext
new file mode 120000
index 00000000..251eedac
--- /dev/null
+++ b/plugins/vinext/.claude/skills/migrate-to-vinext
@@ -0,0 +1 @@
+../../.agents/skills/migrate-to-vinext
\ No newline at end of file
diff --git a/plugins/vinext/agent/skills/migrate-to-vinext/SKILL.md b/plugins/vinext/agent/skills/migrate-to-vinext/SKILL.md
index 4e96a936..c39860b2 100644
--- a/plugins/vinext/agent/skills/migrate-to-vinext/SKILL.md
+++ b/plugins/vinext/agent/skills/migrate-to-vinext/SKILL.md
@@ -22,14 +22,15 @@ Detect the router: if an `app/` directory exists at root or under `src/`, it's A
 
 ## Quick Reference
 
-| Command         | Purpose                                                                |
-| --------------- | ---------------------------------------------------------------------- |
-| `vinext check`  | Scan project for compatibility issues, produce scored report           |
-| `vinext init`   | Automated migration — installs deps, generates config, converts to ESM |
-| `vinext dev`    | Development server with HMR                                            |
-| `vinext build`  | Production build (multi-environment for App Router)                    |
-| `vinext start`  | Local production server                                                |
-| `vinext deploy` | Build and deploy to Cloudflare Workers                                 |
+| Command                            | Purpose                                                                |
+| ---------------------------------- | ---------------------------------------------------------------------- |
+| `vinext check`                     | Scan project for compatibility issues, produce scored report           |
+| `vinext init`                      | Automated migration — installs deps, generates config, converts to ESM |
+| `vinext dev`                       | Development server with HMR                                            |
+| `vinext build`                     | Production build (multi-environment for App Router)                    |
+| `vinext start`                     | Local production server                                                |
+| `npx @vinext/cloudflare deploy`    | Build and deploy to Cloudflare Workers                                 |
+| `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+                      |
 
 ## Phase 1: Check Compatibility
 
@@ -126,7 +127,7 @@ Ensure vinext-generated output and caches are ignored:
 
 ### Option A: Cloudflare Workers (recommended for Cloudflare)
 
-If the user wants to deploy to Cloudflare Workers, use `vinext deploy`. It auto-generates `wrangler.jsonc`, worker entry, and Vite config if missing, installs `@cloudflare/vite-plugin` and `wrangler`, then builds and deploys.
+If the user wants to deploy to Cloudflare Workers, use `npx @vinext/cloudflare deploy`. With Vite+, use `vp exec vinext-cloudflare deploy` when running the locally installed bin. It builds and deploys via wrangler.
 
 For manual setup or custom worker entries, see [references/config-examples.md](references/config-examples.md).
 
@@ -179,7 +180,7 @@ NITRO_PRESET=node npx vite build      # Node.js server
 
 Nitro auto-detects the platform in most CI/CD environments, so the preset is often unnecessary.
 
-**Note:** For Cloudflare Workers, Nitro works but the native integration (`vinext deploy` / `@cloudflare/vite-plugin`) is recommended for the best developer experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
+**Note:** For Cloudflare Workers, Nitro works but the native integration (`npx @vinext/cloudflare deploy` / `vp exec vinext-cloudflare deploy` / `@cloudflare/vite-plugin`) is recommended for the best developer experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
 
 ## Phase 5: Verify
 
@@ -210,4 +211,4 @@ See [references/troubleshooting.md](references/troubleshooting.md) for common mi
 - **Do not skip the compatibility check.** Run `vinext check` before migration to surface issues early.
 - **Do not remove `next.config.js`** unless replacing it with `next.config.ts` or `.mjs`. vinext reads it for redirects, rewrites, headers, basePath, i18n, images, and env config.
 - **Do not use `getPlatformProxy()` or custom worker entries for bindings.** Use `import { env } from "cloudflare:workers"` instead. This is the modern pattern and works out of the box with vinext and `@cloudflare/vite-plugin`.
-- **For Cloudflare Workers, prefer the native integration over Nitro.** `vinext deploy` / `@cloudflare/vite-plugin` provides the best experience with `cloudflare:workers` bindings, KV caching, and image optimization. Nitro works for Cloudflare but the native setup is recommended.
+- **For Cloudflare Workers, prefer the native integration over Nitro.** `npx @vinext/cloudflare deploy` / `vp exec vinext-cloudflare deploy` / `@cloudflare/vite-plugin` provides the best experience with `cloudflare:workers` bindings, KV caching, and image optimization. Nitro works for Cloudflare but the native setup is recommended.
diff --git a/plugins/vinext/agent/skills/migrate-to-vinext/references/config-examples.md b/plugins/vinext/agent/skills/migrate-to-vinext/references/config-examples.md
index 91aac0ca..998f658f 100644
--- a/plugins/vinext/agent/skills/migrate-to-vinext/references/config-examples.md
+++ b/plugins/vinext/agent/skills/migrate-to-vinext/references/config-examples.md
@@ -50,24 +50,17 @@ export default defineConfig({
 
 ## App Router — Cloudflare Workers
 
-Full manual config with explicit RSC plugin registration and Cloudflare multi-environment setup:
+Cloudflare multi-environment setup. RSC plugin registration stays automatic — do **not** add an explicit
+`rsc()` call, or the build fails with `[vinext] Duplicate @vitejs/plugin-rsc detected`.
 
 ```ts
 import { defineConfig } from "vite";
 import vinext from "vinext";
-import rsc from "@vitejs/plugin-rsc";
 import { cloudflare } from "@cloudflare/vite-plugin";
 
 export default defineConfig({
   plugins: [
     vinext(),
-    rsc({
-      entries: {
-        rsc: "virtual:vinext-rsc-entry",
-        ssr: "virtual:vinext-app-ssr-entry",
-        client: "virtual:vinext-app-browser-entry",
-      },
-    }),
     cloudflare({
       viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
     }),
@@ -75,7 +68,10 @@ export default defineConfig({
 });
 ```
 
-In most cases `vinext deploy` generates this automatically. Only use manual config when customizing the worker entry or adding bindings.
+`@vitejs/plugin-rsc` is an optional peer dependency: it must be installed in the project, but vinext
+registers it for you. Only register it yourself after passing `rsc: false` to `vinext()`.
+
+In most cases `npx @vinext/cloudflare deploy` generates this automatically. Only use manual config when customizing the worker entry or adding bindings.
 
 ## wrangler.jsonc — Cloudflare Workers
 
@@ -179,7 +175,7 @@ NITRO_PRESET=node npx vite build
 
 Nitro auto-detects the platform in most CI/CD environments, so the `NITRO_PRESET` is often unnecessary.
 
-**For Cloudflare Workers,** Nitro works but the native integration (`vinext deploy` / `@cloudflare/vite-plugin`) is recommended for the best experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
+**For Cloudflare Workers,** Nitro works but the native integration (`npx @vinext/cloudflare deploy` / `vp exec vinext-cloudflare deploy` / `@cloudflare/vite-plugin`) is recommended for the best experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
 
 ## VinextOptions
 
@@ -188,7 +184,7 @@ Nitro auto-detects the platform in most CI/CD environments, so the `NITRO_PRESET
 | `appDir` | `string`  | project root | Custom base directory for `app/` and `pages/`     |
 | `rsc`    | `boolean` | `true`       | Auto-register `@vitejs/plugin-rsc` for App Router |
 
-## vinext deploy flags
+## @vinext/cloudflare deploy flags
 
 | Flag                 | Description                              |
 | -------------------- | ---------------------------------------- |
diff --git a/plugins/vinext/skills-lock.json b/plugins/vinext/skills-lock.json
index 44fe7b7d..f229bf6d 100644
--- a/plugins/vinext/skills-lock.json
+++ b/plugins/vinext/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "cloudflare/vinext",
       "sourceType": "github",
       "skillPath": ".agents/skills/migrate-to-vinext/SKILL.md",
-      "computedHash": "e45fee21a0bd2f86d5b29291115b82a5e16bafd6a5f13371a9937e0ddae64388"
+      "computedHash": "4a39cac303d49e47fb84757a2f328d4c78781f65278b433b5da224a2957f6080"
     }
   }
 }
diff --git a/plugins/vite/.claude/skills/vite b/plugins/vite/.claude/skills/vite
new file mode 120000
index 00000000..1216e951
--- /dev/null
+++ b/plugins/vite/.claude/skills/vite
@@ -0,0 +1 @@
+../../.agents/skills/vite
\ No newline at end of file
diff --git a/plugins/vitepress/.claude/skills/vitepress b/plugins/vitepress/.claude/skills/vitepress
new file mode 120000
index 00000000..02e02754
--- /dev/null
+++ b/plugins/vitepress/.claude/skills/vitepress
@@ -0,0 +1 @@
+../../.agents/skills/vitepress
\ No newline at end of file
diff --git a/plugins/vitest/.claude/skills/vitest b/plugins/vitest/.claude/skills/vitest
new file mode 120000
index 00000000..76615364
--- /dev/null
+++ b/plugins/vitest/.claude/skills/vitest
@@ -0,0 +1 @@
+../../.agents/skills/vitest
\ No newline at end of file
diff --git a/plugins/vue/.claude/skills/vue b/plugins/vue/.claude/skills/vue
new file mode 120000
index 00000000..7fe99c46
--- /dev/null
+++ b/plugins/vue/.claude/skills/vue
@@ -0,0 +1 @@
+../../.agents/skills/vue
\ No newline at end of file
diff --git a/plugins/vue/.claude/skills/vue-best-practices b/plugins/vue/.claude/skills/vue-best-practices
new file mode 120000
index 00000000..b0f96033
--- /dev/null
+++ b/plugins/vue/.claude/skills/vue-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/vue-best-practices
\ No newline at end of file
diff --git a/plugins/vue/.claude/skills/vue-router-best-practices b/plugins/vue/.claude/skills/vue-router-best-practices
new file mode 120000
index 00000000..8d292357
--- /dev/null
+++ b/plugins/vue/.claude/skills/vue-router-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/vue-router-best-practices
\ No newline at end of file
diff --git a/plugins/vue/.claude/skills/vue-testing-best-practices b/plugins/vue/.claude/skills/vue-testing-best-practices
new file mode 120000
index 00000000..d3f0d13d
--- /dev/null
+++ b/plugins/vue/.claude/skills/vue-testing-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/vue-testing-best-practices
\ No newline at end of file
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/SKILL.md b/plugins/vueuse/.agents/skills/vueuse-functions/SKILL.md
index a33b03a6..cdfad1fc 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/SKILL.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/SKILL.md
@@ -59,6 +59,7 @@ IMPORTANT: Each function entry includes a short `Description` and a detailed `Re
 | [`useDraggable`](references/useDraggable.md) | Make elements draggable | AUTO |
 | [`useDropZone`](references/useDropZone.md) | Create a zone where files can be dropped | AUTO |
 | [`useElementBounding`](references/useElementBounding.md) | Reactive [bounding box](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of an HTML element | AUTO |
+| [`useElementOverflow`](references/useElementOverflow.md) | Reactive element's overflow state | AUTO |
 | [`useElementSize`](references/useElementSize.md) | Reactive size of an HTML element | AUTO |
 | [`useElementVisibility`](references/useElementVisibility.md) | Tracks the visibility of an element within the viewport | AUTO |
 | [`useIntersectionObserver`](references/useIntersectionObserver.md) | Detects changes to a target element's visibility | AUTO |
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/computedWithControl.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/computedWithControl.md
index 59e97041..3fc03c41 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/computedWithControl.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/computedWithControl.md
@@ -81,8 +81,7 @@ export interface ComputedRefWithControl<T>
 export interface WritableComputedRefWithControl<T>
   extends WritableComputedRef<T>, ComputedWithControlRefExtra {}
 export type ComputedWithControlRef<T = any> =
-  | ComputedRefWithControl<T>
-  | WritableComputedRefWithControl<T>
+  ComputedRefWithControl<T> | WritableComputedRefWithControl<T>
 export declare function computedWithControl<T>(
   source: WatchSource | MultiWatchSources,
   fn: ComputedGetter<T>,
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/createDisposableDirective.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/createDisposableDirective.md
index 4d330f85..1f389e5e 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/createDisposableDirective.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/createDisposableDirective.md
@@ -30,8 +30,7 @@ export const VDirective = createDisposableDirective({
 
 ```ts
 type originDirective<H, V, A> =
-  | FunctionDirective<H, V, string, A>
-  | ObjectDirective<H, V, string, A>
+  FunctionDirective<H, V, string, A> | ObjectDirective<H, V, string, A>
 /**
  * Utility for authoring disposable directives. Reactive effects created within `mounted` directive hook will be tracked and automatically disposed when directive is unmounted.
  *
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/onStartTyping.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/onStartTyping.md
index d7527b58..fe9bd769 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/onStartTyping.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/onStartTyping.md
@@ -26,6 +26,35 @@ onStartTyping(() => {
 </template>
 ```
 
+## Custom Valid Key
+
+```ts
+import { onStartTyping } from '@vueuse/core'
+
+onStartTyping(handleKey, {
+  // only allow numbers
+  isTypedCharValid: e => /^\d$/.test(e.key)
+})
+```
+
+## Custom Editable Element
+
+```ts
+import { isFocusedElementEditable as defaultEditable, onStartTyping } from '@vueuse/core'
+
+onStartTyping(handleKey, {
+  isFocusedElementEditable: () => {
+    const { activeElement } = document
+
+    // Exclude elements with id 'targetInput'
+    if (activeElement?.id === 'targetInput')
+      return true
+
+    return defaultEditable()
+  }
+})
+```
+
 ## How It Works
 
 The callback only fires when:
@@ -36,9 +65,22 @@ The callback only fires when:
 
 This allows users to start typing anywhere on the page without accidentally triggering the callback when using keyboard shortcuts or interacting with form fields.
 
+Both `isFocusedElementEditable` and `isTypedCharValid` are also exported as utility functions, so you can reuse them when writing custom options.
+
 ## Type Declarations
 
 ```ts
+export declare function isFocusedElementEditable(): boolean
+export declare function isTypedCharValid({
+  keyCode,
+  metaKey,
+  ctrlKey,
+  altKey,
+}: KeyboardEvent): boolean
+export interface OnStartTypingOptions extends ConfigurableDocument {
+  isTypedCharValid?: (event: KeyboardEvent) => boolean
+  isFocusedElementEditable?: () => boolean
+}
 /**
  * Fires when users start typing on non-editable elements.
  *
@@ -48,6 +90,6 @@ This allows users to start typing anywhere on the page without accidentally trig
  */
 export declare function onStartTyping(
   callback: (event: KeyboardEvent) => void,
-  options?: ConfigurableDocument,
+  options?: OnStartTypingOptions,
 ): void
 ```
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/unrefElement.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/unrefElement.md
index 6e96a934..03104693 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/unrefElement.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/unrefElement.md
@@ -36,11 +36,13 @@ export type MaybeElementRef<T extends MaybeElement = MaybeElement> = MaybeRef<T>
 export type MaybeComputedElementRef<T extends MaybeElement = MaybeElement> =
   MaybeRefOrGetter<T>
 export type MaybeElement =
-  | HTMLElement
-  | SVGElement
-  | VueInstance
-  | undefined
-  | null
+  HTMLElement | SVGElement | VueInstance | undefined | null
+export type MaybeComputedElementRefOrArray<
+  T extends MaybeElement = MaybeElement,
+> =
+  | MaybeComputedElementRef<T>
+  | MaybeComputedElementRef<T>[]
+  | MaybeRefOrGetter<T[] | null>
 export type UnRefElementReturn<T extends MaybeElement = MaybeElement> =
   T extends VueInstance ? Exclude<MaybeElement, VueInstance> : T | undefined
 /**
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useAsyncState.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useAsyncState.md
index 99cbbe4e..44d0ed87 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useAsyncState.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useAsyncState.md
@@ -22,14 +22,14 @@ const { state, isReady, isLoading, error } = useAsyncState(
 
 ### Return Values
 
-| Property           | Description                                         |
-| ------------------ | --------------------------------------------------- |
-| `state`            | The result of the async function                    |
-| `isReady`          | `true` when the promise has resolved at least once  |
-| `isLoading`        | `true` while the promise is pending                 |
-| `error`            | The error if the promise was rejected               |
-| `execute`          | Re-execute the async function with optional delay   |
-| `executeImmediate` | Re-execute immediately (shorthand for `execute(0)`) |
+| Property           | Description                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `state`            | The result of the async function                                                                                               |
+| `isReady`          | `true` when the latest execution has resolved successfully. Reset to `false` on each execution and stays `false` if it rejects |
+| `isLoading`        | `true` while the promise is pending                                                                                            |
+| `error`            | The error if the promise was rejected                                                                                          |
+| `execute`          | Re-execute the async function with optional delay                                                                              |
+| `executeImmediate` | Re-execute immediately (shorthand for `execute(0)`)                                                                            |
 
 ### Awaiting the Result
 
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useAxios.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useAxios.md
index b9fbb437..d0ed404e 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useAxios.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useAxios.md
@@ -245,8 +245,7 @@ export interface UseAxiosOptionsWithInitialData<
   initialData: T
 }
 export type UseAxiosOptions<T = any> =
-  | UseAxiosOptionsBase<T>
-  | UseAxiosOptionsWithInitialData<T>
+  UseAxiosOptionsBase<T> | UseAxiosOptionsWithInitialData<T>
 export declare function useAxios<
   T = any,
   R = AxiosResponse<T>,
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useDebounceFn.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useDebounceFn.md
index c73f44a0..3e37238f 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useDebounceFn.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useDebounceFn.md
@@ -40,15 +40,15 @@ Optionally, you can get the return value of the function using promise operation
 ```ts
 import { useDebounceFn } from '@vueuse/core'
 
-const debouncedRequest = useDebounceFn(() => 'response', 1000)
+const debouncedFn = useDebounceFn(() => 'response', 1000)
 
-debouncedRequest().then((value) => {
+debouncedFn().then((value) => {
   console.log(value) // 'response'
 })
 
 // or use async/await
 async function doRequest() {
-  const value = await debouncedRequest()
+  const value = await debouncedFn()
   console.log(value) // 'response'
 }
 ```
@@ -58,9 +58,9 @@ Since unhandled rejection error is quite annoying when developer doesn't need th
 ```ts
 import { useDebounceFn } from '@vueuse/core'
 
-const debouncedRequest = useDebounceFn(() => 'response', 1000, { rejectOnCancel: true })
+const debouncedFn = useDebounceFn(() => 'response', 1000, { rejectOnCancel: true })
 
-debouncedRequest()
+debouncedFn()
   .then((value) => {
     // do something
   })
@@ -69,9 +69,67 @@ debouncedRequest()
   })
 
 // calling it again will cancel the previous request and gets rejected
-setTimeout(debouncedRequest, 500)
+setTimeout(debouncedFn, 500)
 ```
 
+## Cancel
+
+You can cancel any pending execution by calling the `cancel` method.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000)
+
+debouncedFn()
+
+// Cancel the pending execution before it runs
+debouncedFn.cancel()
+```
+
+This is useful when you need to prevent the debounced function from executing, for example, when a component is unmounted or when user input changes context.
+
+## Pending State
+
+You can check if there's a pending execution using the `isPending` ref.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000)
+
+debouncedFn()
+console.log(debouncedFn.isPending.value) // true
+
+// After debounce time elapses or cancel is called
+console.log(debouncedFn.isPending.value) // false
+```
+
+This is useful for showing loading indicators or disabling UI elements while waiting for the debounced function to execute.
+
+## Flush
+
+You can immediately execute the pending invocation using the `flush` method.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000)
+
+debouncedFn()
+
+// Execute the pending invocation immediately instead of waiting
+debouncedFn.flush()
+```
+
+This is useful when you need to ensure the debounced function runs right away, for example, before navigating away from a page or submitting a form.
+
 ## Recommended Reading
 
 - [**Debounce vs Throttle**: Definitive Visual Guide](https://kettanaito.com/blog/debounce-vs-throttle)
@@ -79,7 +137,8 @@ setTimeout(debouncedRequest, 500)
 ## Type Declarations
 
 ```ts
-export type UseDebounceFnReturn<T extends FunctionArgs> = PromisifyFn<T>
+export type UseDebounceFnReturn<T extends FunctionArgs> =
+  CancelablePromisifyFn<T>
 /**
  * Debounce execution of a function.
  *
@@ -88,9 +147,7 @@ export type UseDebounceFnReturn<T extends FunctionArgs> = PromisifyFn<T>
  * @param  ms          A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
  * @param  options     Options
  *
- * @return A new, debounce, function.
- *
- * @__NO_SIDE_EFFECTS__
+ * @return A new, debounced, function with isPending, cancel, and flush properties.
  */
 export declare function useDebounceFn<T extends FunctionArgs>(
   fn: T,
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useDropZone.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useDropZone.md
index b5a07ad5..7f0131a8 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useDropZone.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useDropZone.md
@@ -56,8 +56,7 @@ export interface UseDropZoneOptions {
    * Also can be a function to check the data types.
    */
   dataTypes?:
-    | MaybeRef<readonly string[]>
-    | ((types: readonly string[]) => boolean)
+    MaybeRef<readonly string[]> | ((types: readonly string[]) => boolean)
   /**
    * Similar to dataTypes, but exposes the DataTransferItemList for custom validation.
    * If provided, this function takes precedence over dataTypes.
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useElementOverflow.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useElementOverflow.md
new file mode 100644
index 00000000..dbdb7830
--- /dev/null
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useElementOverflow.md
@@ -0,0 +1,110 @@
+---
+category: Elements
+---
+
+# useElementOverflow
+
+Reactive element's overflow state.
+
+## Usage
+
+```vue
+<script setup>
+import { useElementOverflow } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const el = useTemplateRef('el')
+const { isXOverflowed } = useElementOverflow(el)
+</script>
+
+<template>
+  <div ref="el" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </div>
+</template>
+```
+
+## Component Usage
+
+```vue
+<script setup lang="ts">
+import { UseElementOverflow } from '@vueuse/components'
+</script>
+
+<template>
+  <UseElementOverflow v-slot="{ isXOverflowed }" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </UseElementOverflow>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script>
+import type { UseElementOverflowReturn } from '@vueuse/core'
+import { vElementOverflow } from '@vueuse/components'
+import { ref } from 'vue'
+
+export default {
+  setup() {
+    const isXOverflowed = ref(false)
+    function onXOverflowChanged(info: UseElementOverflowReturn) {
+      isXOverflowed.value = info.isXOverflowed
+    }
+    return {
+      isXOverflowed,
+      onXOverflowChanged,
+    }
+  },
+}
+</script>
+
+<template>
+  <div v-element-overflow="onXOverflowChanged" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </div>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseElementOverflowOptions extends ConfigurableWindow {
+  /**
+   * Use MutationObserver to observe the target and its children.
+   *
+   * @default false
+   */
+  observeMutation?: boolean | MutationObserverInit
+  /**
+   * Callback when observer triggered.
+   */
+  onUpdated?: ResizeObserverCallback | MutationCallback
+}
+/**
+ * react a dom's overflow state
+ * @see https://vueuse.org/useElementOverflow
+ * @param target
+ * @param option
+ */
+export declare function useElementOverflow(
+  target: MaybeComputedElementRef,
+  option?: UseElementOverflowOptions,
+): {
+  isXOverflowed: Readonly<ShallowRef<boolean, boolean>>
+  isYOverflowed: Readonly<ShallowRef<boolean, boolean>>
+  stop: typeof stop
+  update: () => void
+}
+export type UseElementOverflowReturn = ReturnType<typeof useElementOverflow>
+```
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useElementVisibility.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useElementVisibility.md
index daea4980..17b16cd4 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useElementVisibility.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useElementVisibility.md
@@ -54,6 +54,38 @@ const targetIsVisible = useElementVisibility(target, {
 })
 ```
 
+### controls
+
+By default `useElementVisibility` returns a `ShallowRef<boolean>`. Set `controls: true` to receive the visibility ref together with the controls of the underlying `useIntersectionObserver`:
+
+```ts
+import { useElementVisibility } from '@vueuse/core'
+// ---cut---
+const { isVisible, isActive, pause, resume, stop, isSupported } = useElementVisibility(target, {
+  controls: true,
+})
+```
+
+| State         | Type                   | Description                                                                                                                  |
+| ------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `isVisible`   | `ShallowRef<boolean>`  | Whether the target is currently visible in the viewport.                                                                     |
+| `isActive`    | `ShallowRef<boolean>`  | Whether the observer is currently running. Turns `false` once the observer is stopped, for example after `once: true` fires. |
+| `isSupported` | `ComputedRef<boolean>` | Whether the `IntersectionObserver` API is available.                                                                         |
+| `pause`       | `() => void`           | Pause observing and set `isActive` to `false`.                                                                               |
+| `resume`      | `() => void`           | Resume observing.                                                                                                            |
+| `stop`        | `() => void`           | Stop observing permanently.                                                                                                  |
+
+With `once: true`, read `isActive` to tell whether tracking has already stopped after the element first became visible:
+
+```ts
+import { useElementVisibility } from '@vueuse/core'
+// ---cut---
+const { isVisible, isActive } = useElementVisibility(target, {
+  controls: true,
+  once: true,
+})
+```
+
 ## Component Usage
 
 ```vue
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useFavicon.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useFavicon.md
index 32a06987..62557182 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useFavicon.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useFavicon.md
@@ -49,8 +49,7 @@ export interface UseFaviconOptions extends ConfigurableDocument {
   rel?: string
 }
 export type UseFaviconReturn =
-  | ComputedRef<string | null | undefined>
-  | Ref<string | null | undefined>
+  ComputedRef<string | null | undefined> | Ref<string | null | undefined>
 /**
  * Reactive favicon.
  *
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useFocusTrap.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useFocusTrap.md
index 38cdf67e..8b0f61ad 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useFocusTrap.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useFocusTrap.md
@@ -65,7 +65,7 @@ const { hasFocus, activate, deactivate } = useFocusTrap([targetOne, targetTwo])
       <input type="text">
     </div>
     ...
-    <div ref="targetTow">
+    <div ref="targetTwo">
       <p>Another target here</p>
       <input type="text">
       <button @click="deactivate()">
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useInfiniteScroll.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useInfiniteScroll.md
index 59298539..bca8e70f 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useInfiniteScroll.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useInfiniteScroll.md
@@ -105,12 +105,7 @@ function canLoadMore() {
 
 ```ts
 type InfiniteScrollElement =
-  | HTMLElement
-  | SVGElement
-  | Window
-  | Document
-  | null
-  | undefined
+  HTMLElement | SVGElement | Window | Document | null | undefined
 export interface UseInfiniteScrollOptions<
   T extends InfiniteScrollElement = InfiniteScrollElement,
 > extends UseScrollOptions {
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useIntersectionObserver.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useIntersectionObserver.md
index 143bef73..23ca821e 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useIntersectionObserver.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useIntersectionObserver.md
@@ -107,10 +107,7 @@ export interface UseIntersectionObserverReturn extends Supportable, Pausable {
  * @param options
  */
 export declare function useIntersectionObserver(
-  target:
-    | MaybeComputedElementRef
-    | MaybeRefOrGetter<MaybeElement[]>
-    | MaybeComputedElementRef[],
+  target: MaybeComputedElementRefOrArray,
   callback: IntersectionObserverCallback,
   options?: UseIntersectionObserverOptions,
 ): UseIntersectionObserverReturn
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useInterval.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useInterval.md
index c9637d43..177a6aeb 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useInterval.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useInterval.md
@@ -92,8 +92,7 @@ export interface UseIntervalControls {
   reset: () => void
 }
 export type UseIntervalReturn =
-  | Readonly<ShallowRef<number>>
-  | Readonly<UseIntervalControls & Pausable>
+  Readonly<ShallowRef<number>> | Readonly<UseIntervalControls & Pausable>
 /**
  * Reactive counter increases on every interval
  *
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useLastChanged.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useLastChanged.md
index 026c6a6c..34d97b9a 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useLastChanged.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useLastChanged.md
@@ -45,8 +45,7 @@ export interface UseLastChangedOptions<
   initialValue?: InitialValue
 }
 export type UseLastChangedReturn =
-  | Readonly<ShallowRef<number | null>>
-  | Readonly<ShallowRef<number>>
+  Readonly<ShallowRef<number | null>> | Readonly<ShallowRef<number>>
 /**
  * Records the timestamp of the last change
  *
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useMath.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useMath.md
index a3e0f6cb..418f37b7 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useMath.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useMath.md
@@ -26,9 +26,9 @@ console.log(root.value) // 2
 
 ```ts
 export type UseMathKeys = keyof {
-  [K in keyof Math as Math[K] extends (...args: any) => any
-    ? K
-    : never]: unknown
+  [
+    K in keyof Math as Math[K] extends (...args: any) => any ? K : never
+  ]: unknown
 }
 export type UseMathReturn<K extends keyof Math> = ReturnType<
   Reactified<Math[K], true>
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useMutationObserver.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useMutationObserver.md
index b3e5730f..7135a30e 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useMutationObserver.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useMutationObserver.md
@@ -50,10 +50,7 @@ export interface UseMutationObserverReturn extends Supportable {
  * @param options
  */
 export declare function useMutationObserver(
-  target:
-    | MaybeComputedElementRef
-    | MaybeComputedElementRef[]
-    | MaybeRefOrGetter<MaybeElement[]>,
+  target: MaybeComputedElementRefOrArray,
   callback: MutationCallback,
   options?: UseMutationObserverOptions,
 ): UseMutationObserverReturn
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/usePermission.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/usePermission.md
index c6fe33b5..f280cad4 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/usePermission.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/usePermission.md
@@ -65,14 +65,12 @@ export interface UsePermissionReturnWithControls extends Supportable {
  */
 export declare function usePermission(
   permissionDesc:
-    | GeneralPermissionDescriptor
-    | GeneralPermissionDescriptor["name"],
+    GeneralPermissionDescriptor | GeneralPermissionDescriptor["name"],
   options?: UsePermissionOptions<false>,
 ): UsePermissionReturn
 export declare function usePermission(
   permissionDesc:
-    | GeneralPermissionDescriptor
-    | GeneralPermissionDescriptor["name"],
+    GeneralPermissionDescriptor | GeneralPermissionDescriptor["name"],
   options: UsePermissionOptions<true>,
 ): UsePermissionReturnWithControls
 ```
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useResizeObserver.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useResizeObserver.md
index d2142089..2ec94eaf 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useResizeObserver.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useResizeObserver.md
@@ -98,10 +98,7 @@ export interface UseResizeObserverReturn extends Supportable {
  * @param options
  */
 export declare function useResizeObserver(
-  target:
-    | MaybeComputedElementRef
-    | MaybeComputedElementRef[]
-    | MaybeRefOrGetter<MaybeElement[]>,
+  target: MaybeComputedElementRefOrArray,
   callback: globalThis.ResizeObserverCallback,
   options?: UseResizeObserverOptions,
 ): UseResizeObserverReturn
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useSpeechRecognition.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useSpeechRecognition.md
index abdc2eca..264cedf0 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useSpeechRecognition.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useSpeechRecognition.md
@@ -18,11 +18,14 @@ const {
   isListening,
   isFinal,
   result,
+  confidence,
   start,
   stop,
 } = useSpeechRecognition()
 ```
 
+The `confidence` ref tracks the [confidence value](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionAlternative/confidence) of the latest result, between 0 and 1.
+
 ### Options
 
 The following shows the default values of the options, they will be directly passed to [SpeechRecognition API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition).
@@ -69,9 +72,15 @@ export interface UseSpeechRecognitionOptions extends ConfigurableWindow {
 }
 export interface UseSpeechRecognitionReturn extends Supportable {
   isListening: ShallowRef<boolean>
-  isFinal: ShallowRef<boolean>
+  isFinal: Readonly<ShallowRef<boolean>>
   recognition: SpeechRecognition | undefined
-  result: ShallowRef<string>
+  result: Readonly<ShallowRef<string>>
+  /**
+   * Confidence value of the latest result, between 0 and 1.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionAlternative/confidence
+   */
+  confidence: Readonly<ShallowRef<number>>
   error: ShallowRef<SpeechRecognitionErrorEvent | Error | undefined>
   toggle: (value?: boolean) => void
   start: () => void
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTextareaAutosize.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTextareaAutosize.md
index 33656d04..e124489c 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTextareaAutosize.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTextareaAutosize.md
@@ -6,6 +6,9 @@ category: Browser
 
 Automatically update the height of a textarea depending on the content.
 
+> [!TIP]
+> You may not need this function anymore. Textarea autosizing can now be achieved natively with CSS, see [`field-sizing: content`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/field-sizing) for more information.
+
 ## Usage
 
 ### Simple example
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgo.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgo.md
index 473f1caf..049d60a0 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgo.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgo.md
@@ -1,5 +1,6 @@
 ---
 category: Time
+utils: formatTimeAgo
 ---
 
 # useTimeAgo
@@ -42,13 +43,7 @@ export type UseTimeAgoFormatter<T = number> = (
   isPast: boolean,
 ) => string
 export type UseTimeAgoUnitNamesDefault =
-  | "second"
-  | "minute"
-  | "hour"
-  | "day"
-  | "week"
-  | "month"
-  | "year"
+  "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
 export interface UseTimeAgoMessagesBuiltIn {
   justNow: string
   past: string | UseTimeAgoFormatter<string>
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgoIntl.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgoIntl.md
index 28ada83d..9f9a65a0 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgoIntl.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTimeAgoIntl.md
@@ -1,5 +1,6 @@
 ---
 category: Time
+utils: formatTimeAgoIntl
 ---
 
 # useTimeAgoIntl
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTitle.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTitle.md
index 5ec223d7..ea341178 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useTitle.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useTitle.md
@@ -94,8 +94,7 @@ export type UseTitleOptionsBase = {
 )
 export type UseTitleOptions = ConfigurableDocument & UseTitleOptionsBase
 export type UseTitleReturn =
-  | ComputedRef<string | null | undefined>
-  | Ref<string | null | undefined>
+  ComputedRef<string | null | undefined> | Ref<string | null | undefined>
 /**
  * Reactive document title.
  *
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useVibrate.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useVibrate.md
index 589ef7a4..004a45f5 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useVibrate.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useVibrate.md
@@ -63,7 +63,7 @@ export interface UseVibrateOptions
    * @default 0
    *
    */
-  interval: number
+  interval?: number
 }
 export interface UseVibrateReturn extends Supportable {
   pattern: MaybeRefOrGetter<Arrayable<number>>
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useVirtualList.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useVirtualList.md
index f9500e79..fba8c5b6 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useVirtualList.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useVirtualList.md
@@ -112,7 +112,7 @@ const { list, containerProps, wrapperProps } = useVirtualList(
 </template>
 ```
 
-To scroll to a specific element, the component exposes `scrollTo(index: number) => void`.
+To scroll to a specific element, the component exposes `scrollTo(index: number, options?: { behavior?: ScrollBehavior, block?: ScrollLogicalPosition, inline?: ScrollLogicalPosition }) => void`.
 
 ## Type Declarations
 
@@ -143,15 +143,19 @@ export interface UseVirtualListOptionsBase {
   overscan?: number
 }
 export type UseVirtualListOptions =
-  | UseHorizontalVirtualListOptions
-  | UseVerticalVirtualListOptions
+  UseHorizontalVirtualListOptions | UseVerticalVirtualListOptions
 export interface UseVirtualListItem<T> {
   data: T
   index: number
 }
+export interface UseVirtualListScrollToOptions {
+  behavior?: ScrollBehavior
+  block?: ScrollLogicalPosition
+  inline?: ScrollLogicalPosition
+}
 export interface UseVirtualListReturn<T> {
   list: Ref<UseVirtualListItem<T>[]>
-  scrollTo: (index: number) => void
+  scrollTo: (index: number, options?: UseVirtualListScrollToOptions) => void
   containerProps: {
     ref: Ref<HTMLElement | null>
     onScroll: () => void
diff --git a/plugins/vueuse/.agents/skills/vueuse-functions/references/useWebWorkerFn.md b/plugins/vueuse/.agents/skills/vueuse-functions/references/useWebWorkerFn.md
index e72df32d..98883947 100644
--- a/plugins/vueuse/.agents/skills/vueuse-functions/references/useWebWorkerFn.md
+++ b/plugins/vueuse/.agents/skills/vueuse-functions/references/useWebWorkerFn.md
@@ -62,11 +62,7 @@ This function is a Vue port of https://github.com/alewin/useWorker by Alessio Ko
 
 ```ts
 export type WebWorkerStatus =
-  | "PENDING"
-  | "SUCCESS"
-  | "RUNNING"
-  | "ERROR"
-  | "TIMEOUT_EXPIRED"
+  "PENDING" | "SUCCESS" | "RUNNING" | "ERROR" | "TIMEOUT_EXPIRED"
 export interface UseWebWorkerOptions extends ConfigurableWindow {
   /**
    * Number of milliseconds before killing the worker
diff --git a/plugins/vueuse/.claude/skills/vueuse-functions b/plugins/vueuse/.claude/skills/vueuse-functions
new file mode 120000
index 00000000..9f7399a8
--- /dev/null
+++ b/plugins/vueuse/.claude/skills/vueuse-functions
@@ -0,0 +1 @@
+../../.agents/skills/vueuse-functions
\ No newline at end of file
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/SKILL.md b/plugins/vueuse/agent/skills/vueuse-functions/SKILL.md
index d1062f23..879a5064 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/SKILL.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/SKILL.md
@@ -54,6 +54,7 @@ IMPORTANT: Each function entry includes a short `Description` and a detailed `Re
 | [`useDraggable`](references/useDraggable.md) | Make elements draggable | AUTO |
 | [`useDropZone`](references/useDropZone.md) | Create a zone where files can be dropped | AUTO |
 | [`useElementBounding`](references/useElementBounding.md) | Reactive [bounding box](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of an HTML element | AUTO |
+| [`useElementOverflow`](references/useElementOverflow.md) | Reactive element's overflow state | AUTO |
 | [`useElementSize`](references/useElementSize.md) | Reactive size of an HTML element | AUTO |
 | [`useElementVisibility`](references/useElementVisibility.md) | Tracks the visibility of an element within the viewport | AUTO |
 | [`useIntersectionObserver`](references/useIntersectionObserver.md) | Detects changes to a target element's visibility | AUTO |
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/computedWithControl.md b/plugins/vueuse/agent/skills/vueuse-functions/references/computedWithControl.md
index 59e97041..3fc03c41 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/computedWithControl.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/computedWithControl.md
@@ -81,8 +81,7 @@ export interface ComputedRefWithControl<T>
 export interface WritableComputedRefWithControl<T>
   extends WritableComputedRef<T>, ComputedWithControlRefExtra {}
 export type ComputedWithControlRef<T = any> =
-  | ComputedRefWithControl<T>
-  | WritableComputedRefWithControl<T>
+  ComputedRefWithControl<T> | WritableComputedRefWithControl<T>
 export declare function computedWithControl<T>(
   source: WatchSource | MultiWatchSources,
   fn: ComputedGetter<T>,
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/createDisposableDirective.md b/plugins/vueuse/agent/skills/vueuse-functions/references/createDisposableDirective.md
index 4d330f85..1f389e5e 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/createDisposableDirective.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/createDisposableDirective.md
@@ -30,8 +30,7 @@ export const VDirective = createDisposableDirective({
 
 ```ts
 type originDirective<H, V, A> =
-  | FunctionDirective<H, V, string, A>
-  | ObjectDirective<H, V, string, A>
+  FunctionDirective<H, V, string, A> | ObjectDirective<H, V, string, A>
 /**
  * Utility for authoring disposable directives. Reactive effects created within `mounted` directive hook will be tracked and automatically disposed when directive is unmounted.
  *
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/onStartTyping.md b/plugins/vueuse/agent/skills/vueuse-functions/references/onStartTyping.md
index d7527b58..fe9bd769 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/onStartTyping.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/onStartTyping.md
@@ -26,6 +26,35 @@ onStartTyping(() => {
 </template>
 ```
 
+## Custom Valid Key
+
+```ts
+import { onStartTyping } from '@vueuse/core'
+
+onStartTyping(handleKey, {
+  // only allow numbers
+  isTypedCharValid: e => /^\d$/.test(e.key)
+})
+```
+
+## Custom Editable Element
+
+```ts
+import { isFocusedElementEditable as defaultEditable, onStartTyping } from '@vueuse/core'
+
+onStartTyping(handleKey, {
+  isFocusedElementEditable: () => {
+    const { activeElement } = document
+
+    // Exclude elements with id 'targetInput'
+    if (activeElement?.id === 'targetInput')
+      return true
+
+    return defaultEditable()
+  }
+})
+```
+
 ## How It Works
 
 The callback only fires when:
@@ -36,9 +65,22 @@ The callback only fires when:
 
 This allows users to start typing anywhere on the page without accidentally triggering the callback when using keyboard shortcuts or interacting with form fields.
 
+Both `isFocusedElementEditable` and `isTypedCharValid` are also exported as utility functions, so you can reuse them when writing custom options.
+
 ## Type Declarations
 
 ```ts
+export declare function isFocusedElementEditable(): boolean
+export declare function isTypedCharValid({
+  keyCode,
+  metaKey,
+  ctrlKey,
+  altKey,
+}: KeyboardEvent): boolean
+export interface OnStartTypingOptions extends ConfigurableDocument {
+  isTypedCharValid?: (event: KeyboardEvent) => boolean
+  isFocusedElementEditable?: () => boolean
+}
 /**
  * Fires when users start typing on non-editable elements.
  *
@@ -48,6 +90,6 @@ This allows users to start typing anywhere on the page without accidentally trig
  */
 export declare function onStartTyping(
   callback: (event: KeyboardEvent) => void,
-  options?: ConfigurableDocument,
+  options?: OnStartTypingOptions,
 ): void
 ```
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/unrefElement.md b/plugins/vueuse/agent/skills/vueuse-functions/references/unrefElement.md
index 6e96a934..03104693 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/unrefElement.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/unrefElement.md
@@ -36,11 +36,13 @@ export type MaybeElementRef<T extends MaybeElement = MaybeElement> = MaybeRef<T>
 export type MaybeComputedElementRef<T extends MaybeElement = MaybeElement> =
   MaybeRefOrGetter<T>
 export type MaybeElement =
-  | HTMLElement
-  | SVGElement
-  | VueInstance
-  | undefined
-  | null
+  HTMLElement | SVGElement | VueInstance | undefined | null
+export type MaybeComputedElementRefOrArray<
+  T extends MaybeElement = MaybeElement,
+> =
+  | MaybeComputedElementRef<T>
+  | MaybeComputedElementRef<T>[]
+  | MaybeRefOrGetter<T[] | null>
 export type UnRefElementReturn<T extends MaybeElement = MaybeElement> =
   T extends VueInstance ? Exclude<MaybeElement, VueInstance> : T | undefined
 /**
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useAsyncState.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useAsyncState.md
index 99cbbe4e..44d0ed87 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useAsyncState.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useAsyncState.md
@@ -22,14 +22,14 @@ const { state, isReady, isLoading, error } = useAsyncState(
 
 ### Return Values
 
-| Property           | Description                                         |
-| ------------------ | --------------------------------------------------- |
-| `state`            | The result of the async function                    |
-| `isReady`          | `true` when the promise has resolved at least once  |
-| `isLoading`        | `true` while the promise is pending                 |
-| `error`            | The error if the promise was rejected               |
-| `execute`          | Re-execute the async function with optional delay   |
-| `executeImmediate` | Re-execute immediately (shorthand for `execute(0)`) |
+| Property           | Description                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `state`            | The result of the async function                                                                                               |
+| `isReady`          | `true` when the latest execution has resolved successfully. Reset to `false` on each execution and stays `false` if it rejects |
+| `isLoading`        | `true` while the promise is pending                                                                                            |
+| `error`            | The error if the promise was rejected                                                                                          |
+| `execute`          | Re-execute the async function with optional delay                                                                              |
+| `executeImmediate` | Re-execute immediately (shorthand for `execute(0)`)                                                                            |
 
 ### Awaiting the Result
 
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useAxios.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useAxios.md
index b9fbb437..d0ed404e 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useAxios.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useAxios.md
@@ -245,8 +245,7 @@ export interface UseAxiosOptionsWithInitialData<
   initialData: T
 }
 export type UseAxiosOptions<T = any> =
-  | UseAxiosOptionsBase<T>
-  | UseAxiosOptionsWithInitialData<T>
+  UseAxiosOptionsBase<T> | UseAxiosOptionsWithInitialData<T>
 export declare function useAxios<
   T = any,
   R = AxiosResponse<T>,
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useDebounceFn.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useDebounceFn.md
index c73f44a0..3e37238f 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useDebounceFn.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useDebounceFn.md
@@ -40,15 +40,15 @@ Optionally, you can get the return value of the function using promise operation
 ```ts
 import { useDebounceFn } from '@vueuse/core'
 
-const debouncedRequest = useDebounceFn(() => 'response', 1000)
+const debouncedFn = useDebounceFn(() => 'response', 1000)
 
-debouncedRequest().then((value) => {
+debouncedFn().then((value) => {
   console.log(value) // 'response'
 })
 
 // or use async/await
 async function doRequest() {
-  const value = await debouncedRequest()
+  const value = await debouncedFn()
   console.log(value) // 'response'
 }
 ```
@@ -58,9 +58,9 @@ Since unhandled rejection error is quite annoying when developer doesn't need th
 ```ts
 import { useDebounceFn } from '@vueuse/core'
 
-const debouncedRequest = useDebounceFn(() => 'response', 1000, { rejectOnCancel: true })
+const debouncedFn = useDebounceFn(() => 'response', 1000, { rejectOnCancel: true })
 
-debouncedRequest()
+debouncedFn()
   .then((value) => {
     // do something
   })
@@ -69,9 +69,67 @@ debouncedRequest()
   })
 
 // calling it again will cancel the previous request and gets rejected
-setTimeout(debouncedRequest, 500)
+setTimeout(debouncedFn, 500)
 ```
 
+## Cancel
+
+You can cancel any pending execution by calling the `cancel` method.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000)
+
+debouncedFn()
+
+// Cancel the pending execution before it runs
+debouncedFn.cancel()
+```
+
+This is useful when you need to prevent the debounced function from executing, for example, when a component is unmounted or when user input changes context.
+
+## Pending State
+
+You can check if there's a pending execution using the `isPending` ref.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000)
+
+debouncedFn()
+console.log(debouncedFn.isPending.value) // true
+
+// After debounce time elapses or cancel is called
+console.log(debouncedFn.isPending.value) // false
+```
+
+This is useful for showing loading indicators or disabling UI elements while waiting for the debounced function to execute.
+
+## Flush
+
+You can immediately execute the pending invocation using the `flush` method.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000)
+
+debouncedFn()
+
+// Execute the pending invocation immediately instead of waiting
+debouncedFn.flush()
+```
+
+This is useful when you need to ensure the debounced function runs right away, for example, before navigating away from a page or submitting a form.
+
 ## Recommended Reading
 
 - [**Debounce vs Throttle**: Definitive Visual Guide](https://kettanaito.com/blog/debounce-vs-throttle)
@@ -79,7 +137,8 @@ setTimeout(debouncedRequest, 500)
 ## Type Declarations
 
 ```ts
-export type UseDebounceFnReturn<T extends FunctionArgs> = PromisifyFn<T>
+export type UseDebounceFnReturn<T extends FunctionArgs> =
+  CancelablePromisifyFn<T>
 /**
  * Debounce execution of a function.
  *
@@ -88,9 +147,7 @@ export type UseDebounceFnReturn<T extends FunctionArgs> = PromisifyFn<T>
  * @param  ms          A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
  * @param  options     Options
  *
- * @return A new, debounce, function.
- *
- * @__NO_SIDE_EFFECTS__
+ * @return A new, debounced, function with isPending, cancel, and flush properties.
  */
 export declare function useDebounceFn<T extends FunctionArgs>(
   fn: T,
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useDropZone.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useDropZone.md
index b5a07ad5..7f0131a8 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useDropZone.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useDropZone.md
@@ -56,8 +56,7 @@ export interface UseDropZoneOptions {
    * Also can be a function to check the data types.
    */
   dataTypes?:
-    | MaybeRef<readonly string[]>
-    | ((types: readonly string[]) => boolean)
+    MaybeRef<readonly string[]> | ((types: readonly string[]) => boolean)
   /**
    * Similar to dataTypes, but exposes the DataTransferItemList for custom validation.
    * If provided, this function takes precedence over dataTypes.
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useElementOverflow.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useElementOverflow.md
new file mode 100644
index 00000000..dbdb7830
--- /dev/null
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useElementOverflow.md
@@ -0,0 +1,110 @@
+---
+category: Elements
+---
+
+# useElementOverflow
+
+Reactive element's overflow state.
+
+## Usage
+
+```vue
+<script setup>
+import { useElementOverflow } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const el = useTemplateRef('el')
+const { isXOverflowed } = useElementOverflow(el)
+</script>
+
+<template>
+  <div ref="el" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </div>
+</template>
+```
+
+## Component Usage
+
+```vue
+<script setup lang="ts">
+import { UseElementOverflow } from '@vueuse/components'
+</script>
+
+<template>
+  <UseElementOverflow v-slot="{ isXOverflowed }" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </UseElementOverflow>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script>
+import type { UseElementOverflowReturn } from '@vueuse/core'
+import { vElementOverflow } from '@vueuse/components'
+import { ref } from 'vue'
+
+export default {
+  setup() {
+    const isXOverflowed = ref(false)
+    function onXOverflowChanged(info: UseElementOverflowReturn) {
+      isXOverflowed.value = info.isXOverflowed
+    }
+    return {
+      isXOverflowed,
+      onXOverflowChanged,
+    }
+  },
+}
+</script>
+
+<template>
+  <div v-element-overflow="onXOverflowChanged" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </div>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseElementOverflowOptions extends ConfigurableWindow {
+  /**
+   * Use MutationObserver to observe the target and its children.
+   *
+   * @default false
+   */
+  observeMutation?: boolean | MutationObserverInit
+  /**
+   * Callback when observer triggered.
+   */
+  onUpdated?: ResizeObserverCallback | MutationCallback
+}
+/**
+ * react a dom's overflow state
+ * @see https://vueuse.org/useElementOverflow
+ * @param target
+ * @param option
+ */
+export declare function useElementOverflow(
+  target: MaybeComputedElementRef,
+  option?: UseElementOverflowOptions,
+): {
+  isXOverflowed: Readonly<ShallowRef<boolean, boolean>>
+  isYOverflowed: Readonly<ShallowRef<boolean, boolean>>
+  stop: typeof stop
+  update: () => void
+}
+export type UseElementOverflowReturn = ReturnType<typeof useElementOverflow>
+```
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useElementVisibility.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useElementVisibility.md
index daea4980..17b16cd4 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useElementVisibility.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useElementVisibility.md
@@ -54,6 +54,38 @@ const targetIsVisible = useElementVisibility(target, {
 })
 ```
 
+### controls
+
+By default `useElementVisibility` returns a `ShallowRef<boolean>`. Set `controls: true` to receive the visibility ref together with the controls of the underlying `useIntersectionObserver`:
+
+```ts
+import { useElementVisibility } from '@vueuse/core'
+// ---cut---
+const { isVisible, isActive, pause, resume, stop, isSupported } = useElementVisibility(target, {
+  controls: true,
+})
+```
+
+| State         | Type                   | Description                                                                                                                  |
+| ------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `isVisible`   | `ShallowRef<boolean>`  | Whether the target is currently visible in the viewport.                                                                     |
+| `isActive`    | `ShallowRef<boolean>`  | Whether the observer is currently running. Turns `false` once the observer is stopped, for example after `once: true` fires. |
+| `isSupported` | `ComputedRef<boolean>` | Whether the `IntersectionObserver` API is available.                                                                         |
+| `pause`       | `() => void`           | Pause observing and set `isActive` to `false`.                                                                               |
+| `resume`      | `() => void`           | Resume observing.                                                                                                            |
+| `stop`        | `() => void`           | Stop observing permanently.                                                                                                  |
+
+With `once: true`, read `isActive` to tell whether tracking has already stopped after the element first became visible:
+
+```ts
+import { useElementVisibility } from '@vueuse/core'
+// ---cut---
+const { isVisible, isActive } = useElementVisibility(target, {
+  controls: true,
+  once: true,
+})
+```
+
 ## Component Usage
 
 ```vue
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useFavicon.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useFavicon.md
index 32a06987..62557182 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useFavicon.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useFavicon.md
@@ -49,8 +49,7 @@ export interface UseFaviconOptions extends ConfigurableDocument {
   rel?: string
 }
 export type UseFaviconReturn =
-  | ComputedRef<string | null | undefined>
-  | Ref<string | null | undefined>
+  ComputedRef<string | null | undefined> | Ref<string | null | undefined>
 /**
  * Reactive favicon.
  *
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useFocusTrap.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useFocusTrap.md
index 38cdf67e..8b0f61ad 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useFocusTrap.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useFocusTrap.md
@@ -65,7 +65,7 @@ const { hasFocus, activate, deactivate } = useFocusTrap([targetOne, targetTwo])
       <input type="text">
     </div>
     ...
-    <div ref="targetTow">
+    <div ref="targetTwo">
       <p>Another target here</p>
       <input type="text">
       <button @click="deactivate()">
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useInfiniteScroll.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useInfiniteScroll.md
index 59298539..bca8e70f 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useInfiniteScroll.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useInfiniteScroll.md
@@ -105,12 +105,7 @@ function canLoadMore() {
 
 ```ts
 type InfiniteScrollElement =
-  | HTMLElement
-  | SVGElement
-  | Window
-  | Document
-  | null
-  | undefined
+  HTMLElement | SVGElement | Window | Document | null | undefined
 export interface UseInfiniteScrollOptions<
   T extends InfiniteScrollElement = InfiniteScrollElement,
 > extends UseScrollOptions {
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useIntersectionObserver.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useIntersectionObserver.md
index 143bef73..23ca821e 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useIntersectionObserver.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useIntersectionObserver.md
@@ -107,10 +107,7 @@ export interface UseIntersectionObserverReturn extends Supportable, Pausable {
  * @param options
  */
 export declare function useIntersectionObserver(
-  target:
-    | MaybeComputedElementRef
-    | MaybeRefOrGetter<MaybeElement[]>
-    | MaybeComputedElementRef[],
+  target: MaybeComputedElementRefOrArray,
   callback: IntersectionObserverCallback,
   options?: UseIntersectionObserverOptions,
 ): UseIntersectionObserverReturn
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useInterval.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useInterval.md
index c9637d43..177a6aeb 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useInterval.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useInterval.md
@@ -92,8 +92,7 @@ export interface UseIntervalControls {
   reset: () => void
 }
 export type UseIntervalReturn =
-  | Readonly<ShallowRef<number>>
-  | Readonly<UseIntervalControls & Pausable>
+  Readonly<ShallowRef<number>> | Readonly<UseIntervalControls & Pausable>
 /**
  * Reactive counter increases on every interval
  *
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useLastChanged.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useLastChanged.md
index 026c6a6c..34d97b9a 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useLastChanged.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useLastChanged.md
@@ -45,8 +45,7 @@ export interface UseLastChangedOptions<
   initialValue?: InitialValue
 }
 export type UseLastChangedReturn =
-  | Readonly<ShallowRef<number | null>>
-  | Readonly<ShallowRef<number>>
+  Readonly<ShallowRef<number | null>> | Readonly<ShallowRef<number>>
 /**
  * Records the timestamp of the last change
  *
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useMath.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useMath.md
index a3e0f6cb..418f37b7 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useMath.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useMath.md
@@ -26,9 +26,9 @@ console.log(root.value) // 2
 
 ```ts
 export type UseMathKeys = keyof {
-  [K in keyof Math as Math[K] extends (...args: any) => any
-    ? K
-    : never]: unknown
+  [
+    K in keyof Math as Math[K] extends (...args: any) => any ? K : never
+  ]: unknown
 }
 export type UseMathReturn<K extends keyof Math> = ReturnType<
   Reactified<Math[K], true>
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useMutationObserver.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useMutationObserver.md
index b3e5730f..7135a30e 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useMutationObserver.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useMutationObserver.md
@@ -50,10 +50,7 @@ export interface UseMutationObserverReturn extends Supportable {
  * @param options
  */
 export declare function useMutationObserver(
-  target:
-    | MaybeComputedElementRef
-    | MaybeComputedElementRef[]
-    | MaybeRefOrGetter<MaybeElement[]>,
+  target: MaybeComputedElementRefOrArray,
   callback: MutationCallback,
   options?: UseMutationObserverOptions,
 ): UseMutationObserverReturn
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/usePermission.md b/plugins/vueuse/agent/skills/vueuse-functions/references/usePermission.md
index c6fe33b5..f280cad4 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/usePermission.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/usePermission.md
@@ -65,14 +65,12 @@ export interface UsePermissionReturnWithControls extends Supportable {
  */
 export declare function usePermission(
   permissionDesc:
-    | GeneralPermissionDescriptor
-    | GeneralPermissionDescriptor["name"],
+    GeneralPermissionDescriptor | GeneralPermissionDescriptor["name"],
   options?: UsePermissionOptions<false>,
 ): UsePermissionReturn
 export declare function usePermission(
   permissionDesc:
-    | GeneralPermissionDescriptor
-    | GeneralPermissionDescriptor["name"],
+    GeneralPermissionDescriptor | GeneralPermissionDescriptor["name"],
   options: UsePermissionOptions<true>,
 ): UsePermissionReturnWithControls
 ```
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useResizeObserver.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useResizeObserver.md
index d2142089..2ec94eaf 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useResizeObserver.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useResizeObserver.md
@@ -98,10 +98,7 @@ export interface UseResizeObserverReturn extends Supportable {
  * @param options
  */
 export declare function useResizeObserver(
-  target:
-    | MaybeComputedElementRef
-    | MaybeComputedElementRef[]
-    | MaybeRefOrGetter<MaybeElement[]>,
+  target: MaybeComputedElementRefOrArray,
   callback: globalThis.ResizeObserverCallback,
   options?: UseResizeObserverOptions,
 ): UseResizeObserverReturn
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useSpeechRecognition.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useSpeechRecognition.md
index abdc2eca..264cedf0 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useSpeechRecognition.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useSpeechRecognition.md
@@ -18,11 +18,14 @@ const {
   isListening,
   isFinal,
   result,
+  confidence,
   start,
   stop,
 } = useSpeechRecognition()
 ```
 
+The `confidence` ref tracks the [confidence value](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionAlternative/confidence) of the latest result, between 0 and 1.
+
 ### Options
 
 The following shows the default values of the options, they will be directly passed to [SpeechRecognition API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition).
@@ -69,9 +72,15 @@ export interface UseSpeechRecognitionOptions extends ConfigurableWindow {
 }
 export interface UseSpeechRecognitionReturn extends Supportable {
   isListening: ShallowRef<boolean>
-  isFinal: ShallowRef<boolean>
+  isFinal: Readonly<ShallowRef<boolean>>
   recognition: SpeechRecognition | undefined
-  result: ShallowRef<string>
+  result: Readonly<ShallowRef<string>>
+  /**
+   * Confidence value of the latest result, between 0 and 1.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionAlternative/confidence
+   */
+  confidence: Readonly<ShallowRef<number>>
   error: ShallowRef<SpeechRecognitionErrorEvent | Error | undefined>
   toggle: (value?: boolean) => void
   start: () => void
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useTextareaAutosize.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useTextareaAutosize.md
index 33656d04..e124489c 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useTextareaAutosize.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useTextareaAutosize.md
@@ -6,6 +6,9 @@ category: Browser
 
 Automatically update the height of a textarea depending on the content.
 
+> [!TIP]
+> You may not need this function anymore. Textarea autosizing can now be achieved natively with CSS, see [`field-sizing: content`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/field-sizing) for more information.
+
 ## Usage
 
 ### Simple example
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgo.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgo.md
index 473f1caf..049d60a0 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgo.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgo.md
@@ -1,5 +1,6 @@
 ---
 category: Time
+utils: formatTimeAgo
 ---
 
 # useTimeAgo
@@ -42,13 +43,7 @@ export type UseTimeAgoFormatter<T = number> = (
   isPast: boolean,
 ) => string
 export type UseTimeAgoUnitNamesDefault =
-  | "second"
-  | "minute"
-  | "hour"
-  | "day"
-  | "week"
-  | "month"
-  | "year"
+  "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
 export interface UseTimeAgoMessagesBuiltIn {
   justNow: string
   past: string | UseTimeAgoFormatter<string>
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgoIntl.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgoIntl.md
index 28ada83d..9f9a65a0 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgoIntl.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useTimeAgoIntl.md
@@ -1,5 +1,6 @@
 ---
 category: Time
+utils: formatTimeAgoIntl
 ---
 
 # useTimeAgoIntl
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useTitle.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useTitle.md
index 5ec223d7..ea341178 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useTitle.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useTitle.md
@@ -94,8 +94,7 @@ export type UseTitleOptionsBase = {
 )
 export type UseTitleOptions = ConfigurableDocument & UseTitleOptionsBase
 export type UseTitleReturn =
-  | ComputedRef<string | null | undefined>
-  | Ref<string | null | undefined>
+  ComputedRef<string | null | undefined> | Ref<string | null | undefined>
 /**
  * Reactive document title.
  *
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useVibrate.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useVibrate.md
index 589ef7a4..004a45f5 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useVibrate.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useVibrate.md
@@ -63,7 +63,7 @@ export interface UseVibrateOptions
    * @default 0
    *
    */
-  interval: number
+  interval?: number
 }
 export interface UseVibrateReturn extends Supportable {
   pattern: MaybeRefOrGetter<Arrayable<number>>
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useVirtualList.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useVirtualList.md
index f9500e79..fba8c5b6 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useVirtualList.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useVirtualList.md
@@ -112,7 +112,7 @@ const { list, containerProps, wrapperProps } = useVirtualList(
 </template>
 ```
 
-To scroll to a specific element, the component exposes `scrollTo(index: number) => void`.
+To scroll to a specific element, the component exposes `scrollTo(index: number, options?: { behavior?: ScrollBehavior, block?: ScrollLogicalPosition, inline?: ScrollLogicalPosition }) => void`.
 
 ## Type Declarations
 
@@ -143,15 +143,19 @@ export interface UseVirtualListOptionsBase {
   overscan?: number
 }
 export type UseVirtualListOptions =
-  | UseHorizontalVirtualListOptions
-  | UseVerticalVirtualListOptions
+  UseHorizontalVirtualListOptions | UseVerticalVirtualListOptions
 export interface UseVirtualListItem<T> {
   data: T
   index: number
 }
+export interface UseVirtualListScrollToOptions {
+  behavior?: ScrollBehavior
+  block?: ScrollLogicalPosition
+  inline?: ScrollLogicalPosition
+}
 export interface UseVirtualListReturn<T> {
   list: Ref<UseVirtualListItem<T>[]>
-  scrollTo: (index: number) => void
+  scrollTo: (index: number, options?: UseVirtualListScrollToOptions) => void
   containerProps: {
     ref: Ref<HTMLElement | null>
     onScroll: () => void
diff --git a/plugins/vueuse/agent/skills/vueuse-functions/references/useWebWorkerFn.md b/plugins/vueuse/agent/skills/vueuse-functions/references/useWebWorkerFn.md
index e72df32d..98883947 100644
--- a/plugins/vueuse/agent/skills/vueuse-functions/references/useWebWorkerFn.md
+++ b/plugins/vueuse/agent/skills/vueuse-functions/references/useWebWorkerFn.md
@@ -62,11 +62,7 @@ This function is a Vue port of https://github.com/alewin/useWorker by Alessio Ko
 
 ```ts
 export type WebWorkerStatus =
-  | "PENDING"
-  | "SUCCESS"
-  | "RUNNING"
-  | "ERROR"
-  | "TIMEOUT_EXPIRED"
+  "PENDING" | "SUCCESS" | "RUNNING" | "ERROR" | "TIMEOUT_EXPIRED"
 export interface UseWebWorkerOptions extends ConfigurableWindow {
   /**
    * Number of milliseconds before killing the worker
diff --git a/plugins/vueuse/skills-lock.json b/plugins/vueuse/skills-lock.json
index e0232b77..f8d43598 100644
--- a/plugins/vueuse/skills-lock.json
+++ b/plugins/vueuse/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vueuse/skills",
       "sourceType": "github",
       "skillPath": "skills/vueuse-functions/SKILL.md",
-      "computedHash": "9b6b0afdbc577317e8c29e6ac0ee6890a2ec95d5ad7c8ce66247c1a62b95621d"
+      "computedHash": "665497ecb63a43cef76fafcd1d5b7ec85311060d628452f40f9f9c4114157a83"
     }
   }
 }
diff --git a/plugins/web-design/.claude/skills/web-design-guidelines b/plugins/web-design/.claude/skills/web-design-guidelines
new file mode 120000
index 00000000..886b26de
--- /dev/null
+++ b/plugins/web-design/.claude/skills/web-design-guidelines
@@ -0,0 +1 @@
+../../.agents/skills/web-design-guidelines
\ No newline at end of file
diff --git a/plugins/web-design/skills-lock.json b/plugins/web-design/skills-lock.json
index f6fa2735..4bc2e00d 100644
--- a/plugins/web-design/skills-lock.json
+++ b/plugins/web-design/skills-lock.json
@@ -5,7 +5,7 @@
       "source": "vercel-labs/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/web-design-guidelines/SKILL.md",
-      "computedHash": "a6a44d5498f7e8f68289902f3dedfc6f38ae0cee1e96527c80724cf27f727c2a"
+      "computedHash": "f3bc47f890f42a44db1007ab390709ec368e4b8c089baee6b0007182236ac474"
     }
   }
 }
diff --git a/plugins/wordpress/.agents/skills/blueprint/SKILL.md b/plugins/wordpress/.agents/skills/blueprint/SKILL.md
index 4d59b6ab..fb5bb969 100644
--- a/plugins/wordpress/.agents/skills/blueprint/SKILL.md
+++ b/plugins/wordpress/.agents/skills/blueprint/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: blueprint
-description: Use when creating, editing, or reviewing WordPress Playground blueprint JSON files. Triggers on mentions of blueprints, playground configuration, or requests to set up a WordPress demo environment.
-compatibility: "WordPress 6.9+, PHP 7.2.24+. Optionally Playground CLI or a browser"
+description: Use when the deliverable is WordPress Playground Blueprint JSON or a Blueprint bundle, including creating, editing, reviewing, validating schema keys, choosing steps/resources, and debugging Blueprint files. For only running or sharing a Playground environment, use wp-playground.
+compatibility: "WordPress 7.0+, PHP 7.4.0+. Optionally Playground CLI or a browser"
 ---
 
 # WordPress Playground Blueprints
@@ -31,9 +31,11 @@ All optional. Only documented keys are allowed — the schema rejects unknown pr
 |----------|------|-------|
 | `$schema` | string | Always `"https://playground.wordpress.net/blueprint-schema.json"` |
 | `landingPage` | string | Relative path, e.g. `/wp-admin/` |
+| `description` | string | Deprecated optional top-level description. Prefer `meta.description` for new Blueprints |
 | `meta` | object | `{ title, author, description?, categories? }` — title and author required |
 | `preferredVersions` | object | `{ php, wp }` — both required when present |
 | `features` | object | `{ networking?: boolean, intl?: boolean }` — **only** these two keys, nothing else. Networking defaults to `true` |
+| `phpExtensionBundles` | any | Deprecated/no longer used; the schema leaves the value unconstrained and says to remove it from Blueprints |
 | `extraLibraries` | array | `["wp-cli"]` — auto-included when any `wp-cli` step is present |
 | `constants` | object | Shorthand for `defineWpConfigConsts`. Values: string/boolean/number |
 | `plugins` | array | Shorthand for `installPlugin` steps. Strings = wp.org slugs |
@@ -43,8 +45,8 @@ All optional. Only documented keys are allowed — the schema rejects unknown pr
 
 ### preferredVersions Values
 
-- **php:** Major.minor only (e.g. `"8.3"`, `"7.4"`), or `"latest"`. Patch versions like `"7.4.1"` are invalid. Check the schema for currently supported versions.
-- **wp:** Recent major versions (e.g. `"6.7"`, `"6.8"`), `"latest"`, `"nightly"`, `"beta"`, or a URL to a custom zip. Check the schema for the full list.
+- **php:** Major.minor only: `"7.4"`, `"8.0"`, `"8.1"`, `"8.2"`, `"8.3"`, `"8.4"`, `"8.5"`, or `"latest"`. Patch versions like `"7.4.1"` are invalid. Check the schema for currently supported versions.
+- **wp:** Recent major versions, `"latest"`, `"beta"`, `"nightly"`/`"trunk"`, or a URL to a custom zip. The schema also accepts `false` for PHP-only Playground; do not combine `wp: false` with WordPress-only fields such as `plugins`, `siteOptions`, `login`, or WordPress-only steps.
 
 ### Shorthands vs Steps
 
@@ -388,13 +390,13 @@ dashboard-widget-bundle/
 
 ### Inline Blueprints (quick test, no bundles)
 
-Minify the blueprint JSON (no extra whitespace), prepend `https://playground.wordpress.net/#`, and open the URL in a browser:
+Minify the blueprint JSON (no extra whitespace), encode it once with `encodeURIComponent()`, prepend `https://playground.wordpress.net/#`, and open the URL in a browser:
 
 ```
-https://playground.wordpress.net/#{"$schema":"https://playground.wordpress.net/blueprint-schema.json","preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}
+https://playground.wordpress.net/#%7B%22%24schema%22%3A%22https%3A%2F%2Fplayground.wordpress.net%2Fblueprint-schema.json%22%2C%22preferredVersions%22%3A%7B%22php%22%3A%228.3%22%2C%22wp%22%3A%22latest%22%7D%2C%22steps%22%3A%5B%7B%22step%22%3A%22login%22%7D%5D%7D
 ```
 
-Very large blueprints may exceed browser URL length limits; use the CLI instead.
+Very large blueprints may exceed browser URL length limits; use the CLI or a hosted Blueprint URL instead. For share-link details, use `wp-playground/references/website.md`.
 
 ### Local CLI Testing
 
@@ -412,6 +414,6 @@ npx @wp-playground/cli server --blueprint=./bundle.zip
 npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files
 ```
 
-### Testing with the wordpress-playground-server Skill
+### Testing with WordPress Playground
 
-Use the `wordpress-playground-server` skill to start a local Playground instance with `--blueprint /path/to/blueprint.json`, then verify the expected state with Playwright MCP. For directory bundles, pass `--blueprint-may-read-adjacent-files` as an extra argument.
+Use the `wp-playground` skill for local or browser testing. For CLI testing, follow `wp-playground/references/cli.md` with `--blueprint=<path-or-url>`; for directory bundles, pass `--blueprint-may-read-adjacent-files`.
diff --git a/plugins/wordpress/.agents/skills/wordpress-router/SKILL.md b/plugins/wordpress/.agents/skills/wordpress-router/SKILL.md
index 9405f4c7..8924561c 100644
--- a/plugins/wordpress/.agents/skills/wordpress-router/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wordpress-router/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wordpress-router
 description: "Use when the user asks about WordPress codebases (plugins, themes, block themes, Gutenberg blocks, WP core checkouts) and you need to quickly classify the repo and route to the correct workflow/skill (blocks, theme.json, REST API, WP-CLI, performance, security, testing, release packaging)."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WordPress Router
diff --git a/plugins/wordpress/.agents/skills/wordpress-router/references/decision-tree.md b/plugins/wordpress/.agents/skills/wordpress-router/references/decision-tree.md
index 6d72cbb1..c82ae96e 100644
--- a/plugins/wordpress/.agents/skills/wordpress-router/references/decision-tree.md
+++ b/plugins/wordpress/.agents/skills/wordpress-router/references/decision-tree.md
@@ -25,8 +25,14 @@ Route by intent even if repo kind is broad (like `wp-site`):
   - Route → `wp-interactivity-api`.
 - **Abilities API / wp_register_ability / wp-abilities/v1 / @wordpress/abilities**
   - Route → `wp-abilities-api`.
-- **Playground / run-blueprint / build-snapshot / @wp-playground/cli / playground.wordpress.net**
-  - Route → `wp-playground`.
+- **Ambiguous WordPress Playground requests**
+  - Route → `wp-playground`, then follow its routing wrapper.
+- **Blueprint JSON / Blueprint schema / Blueprint steps / Blueprint bundles**
+  - Route → `blueprint`.
+- **@wp-playground/cli / server / run-blueprint / build-snapshot / auto-mount / Xdebug**
+  - Route → `wp-playground`, then read `references/cli.md` or `references/debugging.md`.
+- **playground.wordpress.net / Blueprint Editor / share links / browser-only Playground**
+  - Route → `wp-playground`, then read `references/website.md`.
 - **Blocks / block.json / registerBlockType / attributes / save serialization**
   - Route → `wp-block-development`.
 - **theme.json / Global Styles / templates/*.html / patterns/**
diff --git a/plugins/wordpress/.agents/skills/wp-abilities-api/SKILL.md b/plugins/wordpress/.agents/skills/wp-abilities-api/SKILL.md
index d43cccfb..1edc3a4c 100644
--- a/plugins/wordpress/.agents/skills/wp-abilities-api/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-abilities-api/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-abilities-api
 description: "Use when working with the WordPress Abilities API (wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities) including defining abilities, categories, meta, REST exposure, and permissions checks for clients."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WP Abilities API
diff --git a/plugins/wordpress/.agents/skills/wp-block-development/SKILL.md b/plugins/wordpress/.agents/skills/wp-block-development/SKILL.md
index 110e9d26..df198b74 100644
--- a/plugins/wordpress/.agents/skills/wp-block-development/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-block-development/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-block-development
 description: "Use when developing WordPress (Gutenberg) blocks: block.json metadata, register_block_type(_from_metadata), attributes/serialization, supports, dynamic rendering (render.php/render_callback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block build and test workflows."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WP Block Development
diff --git a/plugins/wordpress/.agents/skills/wp-block-themes/SKILL.md b/plugins/wordpress/.agents/skills/wp-block-themes/SKILL.md
index 6f06c021..bb3dfca3 100644
--- a/plugins/wordpress/.agents/skills/wp-block-themes/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-block-themes/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-block-themes
 description: "Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching)."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WP Block Themes
diff --git a/plugins/wordpress/.agents/skills/wp-block-themes/references/debugging.md b/plugins/wordpress/.agents/skills/wp-block-themes/references/debugging.md
index 5475e204..9414a16c 100644
--- a/plugins/wordpress/.agents/skills/wp-block-themes/references/debugging.md
+++ b/plugins/wordpress/.agents/skills/wp-block-themes/references/debugging.md
@@ -7,6 +7,7 @@ Fast checks:
 1. Confirm you edited the active theme (Site Editor → theme).
 2. Check if user customizations exist (they override theme defaults).
 3. Validate `theme.json` structure (typos can prevent styles from applying).
+4. If a `var(--wp--preset--*)` / `var(--wp--custom--*)` reference is silently using its fallback, the slug is likely un-normalised — WordPress hyphenates digit/letter boundaries and camelCase transitions before emitting the CSS var. See `theme-json.md` § "Slug normalisation gotcha".
 
 Remember the hierarchy:
 
diff --git a/plugins/wordpress/.agents/skills/wp-block-themes/references/theme-json.md b/plugins/wordpress/.agents/skills/wp-block-themes/references/theme-json.md
index fa25bc40..45049e02 100644
--- a/plugins/wordpress/.agents/skills/wp-block-themes/references/theme-json.md
+++ b/plugins/wordpress/.agents/skills/wp-block-themes/references/theme-json.md
@@ -57,3 +57,17 @@ References:
 
 - Border radius presets: https://make.wordpress.org/core/2025/11/12/theme-json-border-radius-presets-support-in-wordpress-6-9/
 - Form element styling: https://developer.wordpress.org/news/2025/11/how-wordpress-6-9-gives-forms-a-theme-json-makeover/
+
+## Slug normalisation gotcha
+
+> **Slug normaliser trap (silent failure).** WordPress inserts hyphens inside preset/custom slugs before emitting CSS vars: slug `3xl` becomes `--wp--preset--font-size--3-xl`; slug `cardShadow` becomes `--wp--custom--card-shadow`. A handwritten reference to the *un-normalised* form (e.g. `var(--wp--preset--font-size--3xl)`) resolves to nothing and silently falls back to the second `var()` argument.
+
+Before assembling the variable name, `WP_Theme_JSON` passes each preset/custom slug through `_wp_to_kebab_case()`, which splits it into word tokens — at digit/letter boundaries, camelCase transitions, and non-alphanumeric characters — lowercases them, and joins with `-`. Reference the emitted form, not the slug you typed.
+
+Grep pattern to catch un-normalised references in CSS/SCSS/PHP/JS:
+
+```
+var\(\s*--wp--(?:preset|custom)--[a-z-]+--\d+[a-z]
+```
+
+This matches a digit immediately followed by a letter inside the variable name (`3xl`, `2xs`, `4x-large`) — every emitted form keeps the hyphen (`3-xl`, `2-xs`, `4-x-large`) and is correctly not flagged.
diff --git a/plugins/wordpress/.agents/skills/wp-interactivity-api/SKILL.md b/plugins/wordpress/.agents/skills/wp-interactivity-api/SKILL.md
index 6f3072df..7bd8fad2 100644
--- a/plugins/wordpress/.agents/skills/wp-interactivity-api/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-interactivity-api/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-interactivity-api
 description: "Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WP Interactivity API
diff --git a/plugins/wordpress/.agents/skills/wp-performance/SKILL.md b/plugins/wordpress/.agents/skills/wp-performance/SKILL.md
index 690e6302..37bf84ff 100644
--- a/plugins/wordpress/.agents/skills/wp-performance/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-performance/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-performance
 description: "Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."
 ---
 
 # WP Performance (backend-only)
diff --git a/plugins/wordpress/.agents/skills/wp-phpstan/SKILL.md b/plugins/wordpress/.agents/skills/wp-phpstan/SKILL.md
index 2e7bc559..3bd52e8a 100644
--- a/plugins/wordpress/.agents/skills/wp-phpstan/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-phpstan/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-phpstan
 description: "Use when configuring, running, or fixing PHPStan static analysis in WordPress projects (plugins/themes/sites): phpstan.neon setup, baselines, WordPress-specific typing, and handling third-party plugin classes."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires Composer-based PHPStan."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Requires Composer-based PHPStan."
 ---
 
 # WP PHPStan
diff --git a/plugins/wordpress/.agents/skills/wp-playground/SKILL.md b/plugins/wordpress/.agents/skills/wp-playground/SKILL.md
index c8744109..9f1e8921 100644
--- a/plugins/wordpress/.agents/skills/wp-playground/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-playground/SKILL.md
@@ -1,101 +1,52 @@
 ---
 name: wp-playground
-description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging (Xdebug)."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Playground CLI requires Node.js 20.18+; runs WP in WebAssembly with SQLite."
+description: "Use as the WordPress Playground routing wrapper for ambiguous Playground work, local CLI runs with @wp-playground/cli, playground.wordpress.net share links, browser previews, snapshots, mounts, version switching, and Xdebug. For Blueprint JSON authoring or review, use the blueprint skill directly."
+compatibility: "Targets WordPress 7.0+, PHP 7.4.0+. Playground CLI requires Node.js 20.18+; runs WordPress in WebAssembly with SQLite."
 ---
 
 # WordPress Playground
 
-## When to use
-
-- Spin up a disposable WordPress to test a plugin/theme without full stack setup.
-- Run or iterate on Playground Blueprints (JSON) locally.
-- Build a reproducible snapshot of a site for sharing or CI.
-- Switch WP/PHP versions quickly to reproduce issues.
-- Debug plugin/theme code with Xdebug in an isolated Playground.
-
-## Inputs required
-
-- Host machine readiness: Node.js ≥ 20.18, `npm`/`npx` available.
-- Project path to mount (`--auto-mount` or explicit mount mapping).
-- Desired WP version/PHP version (optional; defaults to latest WP, PHP 8.3).
-- Blueprint location/URL if running a blueprint.
-- Port preference if 9400 conflicts.
-- Whether Xdebug is needed.
+This is a thin routing wrapper. Use it to pick the right Playground workflow, then load only the focused reference or skill needed for the task.
 
 ## Procedure
 
-### 0) Guardrails
-
-- Playground instances are ephemeral and SQLite-backed; **never** point at production data.
-- Confirm Node ≥ 20.18 (`node -v`) before running CLI.
-- If mounting local code, ensure it is clean of secrets; Playground copies files into an in-memory FS.
-
-### 1) Quick local spin-up (auto-mount)
-
-```bash
-cd <plugin-or-theme-root>
-npx @wp-playground/cli@latest server --auto-mount
-```
-- Opens on http://localhost:9400 by default. Auto-detects plugin/theme and installs it.
-- Add `--wp=<version>` / `--php=<version>` as needed.
-- For classic full installs already present, add `--skip-wordpress-setup` and mount the whole tree.
-
-### 2) Manual mounts or multiple mounts
+1. Identify the user intent: Blueprint authoring/review, local CLI execution, browser-only website/share link workflow, Xdebug/stuck CLI run, or a mixed Playground request.
+2. Route to the focused source below, loading more than one only when the request has multiple distinct parts.
+3. For mixed requests, delegate Blueprint JSON work to `blueprint`, then return here for runtime, CLI, debugging, or sharing guidance.
 
-- Use `--mount=/host/path:/vfs/path` (repeatable) when auto-mount is insufficient (multi-plugin, mu-plugins, custom content).
-- Mount before install with `--mount-before-install` for bootstrapping installer flows.
-- Reference: `references/cli-commands.md`
+- **Blueprint JSON, schema, steps, resources, bundles, or Blueprint review**: use the `blueprint` skill directly. Do not duplicate Blueprint schema details here.
+- **Local CLI execution**: read `references/cli.md` for `@wp-playground/cli` server, `run-blueprint`, `build-snapshot`, mounts, version switching, and local validation.
+- **Xdebug or stuck CLI runs**: read `references/debugging.md` for Xdebug, runtime logs, worker flags, and stuck CLI runs.
+- **Browser-only Playground website workflows**: read `references/website.md` for `playground.wordpress.net`, share URLs, Blueprint Editor, hosted bundles, and browser limitations.
 
-### 3) Run a Blueprint (no server needed)
-
-```bash
-npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
-```
-- Use for scripted setup/CI validation. Supports remote URLs and local files.
-- Allow bundled assets in local blueprints with `--blueprint-may-read-adjacent-files` when required.
-- See `references/blueprints.md` for structure and common flags.
-
-### 4) Build a snapshot for sharing
-
-```bash
-npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip
-```
-- Produces a ZIP you can load in Playground or attach to bug reports.
-
-### 5) Debugging with Xdebug
-
-- Start with `--xdebug` (or `--enable-xdebug` depending on CLI release) to expose an IDE key, then connect VS Code/PhpStorm to the host/port shown in CLI output.
-- Combine with `--auto-mount` for plugin/theme debugging.
-- Checklist: `references/debugging.md`
-
-### 6) Version switching
+## Inputs required
 
-- Use `--wp=` to pin WP (e.g., 6.9.0) and `--php=` to test compatibility.
-- If feature depends on Gutenberg trunk, prefer the latest WP release plus plugin if available; Playground images track stable WP plus bundled Gutenberg.
+- The intended workflow: Blueprint authoring, local CLI run, website/share link, snapshot, or debugging.
+- Project or bundle path if local code must be mounted or packaged.
+- Desired WordPress/PHP versions if compatibility matters.
+- Port preference if a local server is needed.
+- Whether browser-only sharing or local filesystem access is required.
 
-### 7) Browser-only workflows (no CLI)
+## Guardrails
 
-- Launch quick previews with URL fragments or query params:
-  - Fragment: `https://playground.wordpress.net/#<base64-or-json-blueprint>`
-  - Query: `https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>`
-- Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.
+- Playground instances are disposable, SQLite-backed environments; never point them at production data.
+- Keep Blueprint JSON guidance in `blueprint` so the schema and examples have one source of truth.
+- For local CLI work, verify Node.js 20.18+ and `npm`/`npx` before running commands.
+- Browser-only Playground cannot read local filesystem paths; use public URLs, hosted ZIP bundles, or inline Blueprint JSON.
 
 ## Verification
 
-- Verify mounted code is active (plugin listed/active; theme selected).
-- For blueprints/snapshots, re-run with `--verbosity=debug` to confirm steps executed.
-- Run targeted smoke (e.g., `wp plugin list` inside Playground shell via browser terminal if exposed) or UI click-path.
+- For Blueprint content, validate against the published schema and follow the `blueprint` skill verification.
+- For local CLI runs, verify the mounted plugin/theme or Blueprint side effects in the Playground instance.
+- For share links, open the generated URL and confirm the expected landing page and installed assets load.
 
-## Failure modes / debugging
+## Failure modes
 
-- **CLI exits complaining about Node**: upgrade to ≥ 20.18.
-- **Mount not applied**: check path, use absolute path, add `--verbosity=debug`.
-- **Blueprint cannot read local assets**: add `--blueprint-may-read-adjacent-files`.
-- **Port already used**: `--port=<free-port>`.
-- **Slow/locked UI**: disable `--experimental-multi-worker` if enabled; or enable it to improve throughput on CPU-bound runs.
+- **Blueprint work routed here**: stop and use the `blueprint` skill for schema keys, steps, resources, bundles, validation, or Blueprint review.
+- **Local filesystem needed in a browser-only workflow**: use `references/cli.md`; `playground.wordpress.net` cannot read local filesystem paths.
+- **Shareable browser link requested from a local CLI workflow**: use `references/website.md`; local server URLs are not portable share links.
+- **Debugging treated as a second-hop reference**: read `references/debugging.md` directly for Xdebug, logs, worker flags, and stuck CLI runs.
 
 ## Escalation
 
-- If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
-- For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/
+- If the task needs PHP extensions, native database access, persistence, or production-like infrastructure that Playground cannot provide, use a full WordPress stack such as wp-env, Docker, or the project-provided environment.
diff --git a/plugins/wordpress/.agents/skills/wp-playground/references/blueprints.md b/plugins/wordpress/.agents/skills/wp-playground/references/blueprints.md
deleted file mode 100644
index da26cee6..00000000
--- a/plugins/wordpress/.agents/skills/wp-playground/references/blueprints.md
+++ /dev/null
@@ -1,36 +0,0 @@
-## Blueprint quick reference
-
-Blueprints are JSON recipes that describe how Playground should set up WordPress.
-
-### Minimal example
-
-```json
-{
-  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
-  "steps": [
-    { "step": "installTheme", "themeZipUrl": "https://downloads.wordpress.org/theme/twentytwentythree.zip" },
-    { "step": "installPlugin", "pluginZipUrl": "https://downloads.wordpress.org/plugin/classic-editor.zip" }
-  ]
-}
-```
-
-### Common steps (non-exhaustive)
-
-- `setSiteUrl`, `setHomeUrl`
-- `installTheme`, `installPlugin` (ZIP URLs or local paths when allowed)
-- `activateTheme`, `activatePlugin`
-- `runPHP` (inline PHP)
-- `applyPatches` (filesystem patch)
-- `writeFile` (create/update files)
-- `importFile` (XML/WXR)
-- `wpConfigConstants` (define constants)
-- `preferredVersions` (pick WP/PHP; matches CLI `--wp` / `--php`)
-- `blueprintSteps` that include `extraLibraries` (e.g., Jetpack) and `features.networking` when browser networking is required
-
-### Tips
-
-- Use `--blueprint-may-read-adjacent-files` when the blueprint needs local files (e.g., custom plugin ZIP) during `run-blueprint` or `build-snapshot`.
-- For iterative authoring, keep blueprints small and compose via separate files.
-- Validate against the published schema URL above to catch typos.
-- For Gutenberg/nightly testing, set `--wp=<version>` to align with target WP.
-- To share quickly, encode the blueprint as base64 in the Playground URL fragment or host the JSON/ZIP and pass `?blueprint-url=…`.
diff --git a/plugins/wordpress/.agents/skills/wp-playground/references/cli-commands.md b/plugins/wordpress/.agents/skills/wp-playground/references/cli-commands.md
deleted file mode 100644
index 8eb5ba1b..00000000
--- a/plugins/wordpress/.agents/skills/wp-playground/references/cli-commands.md
+++ /dev/null
@@ -1,39 +0,0 @@
-## Playground CLI command cheatsheet
-
-> Requires Node.js 20.18+ and npm/npx.
-> Latest version: 3.0.20 (November 2025)
-
-### What's new in 2025
-
-- **PHP 8.3 is now the default** (since July 2025).
-- **New PHP extensions**: ImageMagick, SOAP, and AVIF GD support.
-- **OpCache enabled**: 42% faster response times (185ms → 108ms average).
-- **Multi-worker default**: `--experimental-multi-worker` now defaults to CPU count minus one.
-
-### Install / run server
-
-- `npx @wp-playground/cli@latest server [--port=9400] [--auto-mount] [--wp=<ver>] [--php=<ver>] [--verbosity=debug] [--blueprint=<url-or-path>]`
-- Mounts:
-  - `--auto-mount` (detect plugin/theme in CWD)
-  - `--mount=/abs/host:/vfs/path` (repeatable)
-  - `--mount-before-install` (apply mounts before WP install)
-
-### Run a blueprint
-
-- `npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url> [--blueprint-may-read-adjacent-files] [--wp=<ver>] [--php=<ver>] [--verbosity=debug]`
-- Use for scripted setup; no persistent server.
-
-### Build a snapshot
-
-- `npx @wp-playground/cli@latest build-snapshot --blueprint=<file-or-url> --outfile=./site.zip [--verbosity=debug]`
-- Produces a sharable ZIP usable by Playground UI or other CLI commands.
-
-### Debugging flags
-
-- `--xdebug` / `--enable-xdebug` (depends on release) to start Xdebug listener.
-- `--experimental-multi-worker` to speed multi-step blueprints; disable if unstable.
-
-### Version control
-
-- `--wp=<version>` to pick WordPress version (defaults to latest).
-- `--php=<version>` to pick PHP version (defaults to 8.3 since July 2025).
diff --git a/plugins/wordpress/.agents/skills/wp-playground/references/cli.md b/plugins/wordpress/.agents/skills/wp-playground/references/cli.md
new file mode 100644
index 00000000..0204be6b
--- /dev/null
+++ b/plugins/wordpress/.agents/skills/wp-playground/references/cli.md
@@ -0,0 +1,119 @@
+## Playground CLI workflows
+
+Use this reference for local WordPress Playground runs with `@wp-playground/cli`: disposable or persisted local servers, mounted plugins/themes, Blueprint execution, snapshots, version switching, and local smoke tests.
+
+## Prerequisites
+
+- Node.js 20.18+ with `npm`/`npx` available.
+- A local project, plugin, theme, Blueprint file, or Blueprint bundle path.
+- A free local port when using `server`; the default is `9400`.
+
+Check the installed CLI help when exact flags matter:
+
+```bash
+npx @wp-playground/cli@latest --help
+npx @wp-playground/cli@latest start --help
+npx @wp-playground/cli@latest server --help
+```
+
+## Quick local development
+
+Use `start` for the common local plugin/theme workflow. It detects the project type, mounts the project, opens a browser, enables admin auto-login, and persists the site between sessions.
+
+```bash
+cd <plugin-or-theme-root>
+node -v
+npx @wp-playground/cli@latest start
+```
+
+- Use `npx @wp-playground/cli@latest start --reset` when the persisted site should be recreated from scratch.
+- Use `server` with explicit `--wp=<version>` and `--php=<version>` when reproducing compatibility issues instead of relying on moving defaults.
+
+## Advanced local server
+
+Use `server` when you need full manual control, a disposable site, CI-style behavior, custom mounts, or a Blueprint-backed server:
+
+```bash
+npx @wp-playground/cli@latest server --auto-mount
+```
+
+- `--auto-mount[=<path>]` detects a WordPress directory, plugin, theme, wp-content directory, or PHP/HTML directory.
+- Add `--port=<free-port>` when the default port is busy.
+- For existing WordPress files, prefer `--wordpress-install-mode=install-from-existing-files-if-needed` to skip setup when a site is already present.
+- Use `--wordpress-install-mode=do-not-attempt-installing` only when WordPress files and database integration are already handled by the mounted tree.
+
+## Manual mounts
+
+Use explicit mounts when auto-mount is not enough:
+
+```bash
+npx @wp-playground/cli@latest server \
+  --mount=/absolute/host/path:/wordpress/wp-content/plugins/my-plugin
+```
+
+- Use absolute host paths.
+- Repeat `--mount=` for multiple plugins, mu-plugins, themes, or custom content.
+- Use `--mount-before-install` when installer or Blueprint steps need mounted files before WordPress setup completes.
+- On Windows or when colon-separated mappings are awkward, use `--mount-dir "/host/path" "/vfs/path"` or `--mount-dir-before-install "/host/path" "/vfs/path"`.
+
+## Run a Blueprint
+
+For headless setup or CI-style validation:
+
+```bash
+npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
+```
+
+- Use the `blueprint` skill for Blueprint JSON structure and schema details.
+- Add `--blueprint-may-read-adjacent-files` when a local Blueprint directory or bundle references nearby files.
+- Add `--verbosity=debug` when step execution needs inspection.
+
+## Start a server from a Blueprint
+
+```bash
+npx @wp-playground/cli@latest server --blueprint=<file-or-url>
+```
+
+For local directory bundles:
+
+```bash
+npx @wp-playground/cli@latest server \
+  --blueprint=./my-bundle/ \
+  --blueprint-may-read-adjacent-files
+```
+
+ZIP bundles are self-contained and do not need adjacent-file access.
+
+## Build a snapshot
+
+```bash
+npx @wp-playground/cli@latest build-snapshot \
+  --blueprint=<file-or-url> \
+  --outfile=./site.zip
+```
+
+- Use snapshots for shareable repro cases or CI artifacts.
+- Re-run with `--verbosity=debug` if the generated site does not contain the expected state.
+
+## Version switching
+
+- Use `--wp=<version>` to pin WordPress.
+- Use `--php=<version>` to pin PHP.
+- Prefer explicit versions for bug reproduction and compatibility testing.
+- Use the CLI help or current Playground docs to confirm supported version values and defaults.
+
+## Verification
+
+- Confirm the plugin appears in the admin plugin list and is active when expected.
+- Confirm the selected theme is active when testing themes.
+- For Blueprints, verify expected options, pages, plugins, themes, or files after the run.
+- For snapshots, load the ZIP in a fresh Playground instance before sharing it as a repro artifact.
+
+## Failure modes
+
+- **Node version error**: upgrade to Node.js 20.18+.
+- **Mount not applied**: use an absolute path, verify the virtual path, and rerun with `--verbosity=debug`.
+- **Blueprint cannot read local assets**: add `--blueprint-may-read-adjacent-files` for local directory bundles.
+- **Port already used**: pass `--port=<free-port>`.
+- **Need a fresh persisted `start` site**: rerun with `start --reset`.
+- **Need breakpoints or runtime logs**: return to the `wp-playground` routing procedure and select the debugging workflow.
diff --git a/plugins/wordpress/.agents/skills/wp-playground/references/debugging.md b/plugins/wordpress/.agents/skills/wp-playground/references/debugging.md
index 695d2643..ed6922d1 100644
--- a/plugins/wordpress/.agents/skills/wp-playground/references/debugging.md
+++ b/plugins/wordpress/.agents/skills/wp-playground/references/debugging.md
@@ -1,16 +1,16 @@
 ## Debugging WordPress Playground
 
-- Start CLI with Xdebug: `server --auto-mount --xdebug` (or `--enable-xdebug` depending on release). The CLI prints host/port and IDE key to configure your debugger.
+- Start CLI with Xdebug: `server --auto-mount --xdebug`. The CLI prints host/port and IDE key to configure your debugger; if the installed CLI help differs, follow `npx @wp-playground/cli@latest server --help`.
 - If breakpoints are not hit, confirm:
   - IDE listens on the port shown by CLI.
   - Path mappings include the mounted VFS path used by Playground.
 - For slow or stuck runs:
   - Add `--verbosity=debug` to see step-level logs.
-  - Disable `--experimental-multi-worker` if it was enabled.
+  - Use `--debug` to print the PHP error log when boot fails.
+  - Adjust request workers with `--workers=<n|auto>`; use `--workers=1` to isolate worker-related behavior.
 - For mount issues:
   - Prefer absolute paths in `--mount`.
   - Use `--mount-before-install` when installer steps need files present early.
 - To inspect runtime state:
   - Open the Playground browser console; the Service Worker logs network/FS events.
   - Use the “Terminal” tab (if available) to run WP-CLI inside the instance.
-
diff --git a/plugins/wordpress/.agents/skills/wp-playground/references/website.md b/plugins/wordpress/.agents/skills/wp-playground/references/website.md
new file mode 100644
index 00000000..e8e83eb5
--- /dev/null
+++ b/plugins/wordpress/.agents/skills/wp-playground/references/website.md
@@ -0,0 +1,164 @@
+## Playground website workflows
+
+Use this reference when the agent must use `https://playground.wordpress.net/` itself: create a browser Playground site, share a Playground URL, manage saved sites, or interact with the currently running WordPress site from DevTools/browser automation.
+
+## Route first
+
+- For Blueprint JSON structure, schema, resources, steps, or bundles, use the `blueprint` skill first; the Blueprint skill is the source of truth for Blueprint details.
+- For local filesystem mounts, snapshots, Xdebug, or headless validation, return to the `wp-playground` routing procedure and select the local CLI or debugging workflow.
+
+## Working model for agents
+
+`playground.wordpress.net` gives the agent three useful control surfaces:
+
+- **URL setup**: Query API parameters and Blueprint URLs create or open a site in a desired state. Use this before the site boots.
+- **Site manager**: `window.playgroundSites` manages the website's saved browser sites. Use it to list, create, switch, save, rename, delete, or reconfigure sites.
+- **Active site client**: `window.playground` is the `PlaygroundClient` for the currently running WordPress site. `playgroundSites.getClient()` returns the same client after the active site is ready. Use it to inspect files, write files, run PHP, make HTTP-style WordPress requests, and navigate.
+
+Use the website/site-manager layer to create or choose a site. Use the active site client to change WordPress itself.
+
+## Decide what to do
+
+| User intent | Agent action |
+| --- | --- |
+| Share a quick reviewer/demo site | Build a `https://playground.wordpress.net/?...` URL with Query API parameters. |
+| Share a multi-step setup | Use the `blueprint` skill to create/review the Blueprint, then pass it as a URL fragment or `?blueprint-url=`. |
+| Create a blank temporary site from the browser | Open `playground.wordpress.net`, then call `playgroundSites.createNewTemporarySite()`. |
+| Keep a temporary site after reload | Call `playgroundSites.saveInBrowser()` for OPFS persistence. |
+| Switch between saved browser sites | Call `playgroundSites.list()` and `playgroundSites.setActiveSite(slug)`. |
+| Change PHP version or networking on an existing saved site | Save it first, then call `setPhpVersion()` or `setNetworking()`. |
+| Inspect or modify WordPress files/content | Get the active client with `playgroundSites.getClient()` or `window.playground`, then use client file/PHP/request methods. |
+
+## Create or open a site with a URL
+
+For a blank disposable Playground site, use `https://playground.wordpress.net/` with no query parameters.
+
+Use Query API URLs when the setup is simple enough to express as URL parameters:
+
+```text
+https://playground.wordpress.net/?php=8.4&wp=latest&plugin=gutenberg&networking=yes&url=/wp-admin/post-new.php
+```
+
+Practical URL parameters for agents:
+
+- `php=<version>` and `wp=<version>`: choose runtime versions.
+- `plugin=<slug>` and `theme=<slug>`: install WordPress.org assets; repeat the parameter for multiple assets, such as `?plugin=gutenberg&plugin=woocommerce&networking=yes`.
+- `networking=yes|no`: allow or block downloads for plugins, themes, translations, imports, and PR builds. Use `networking=no` or omit networking for offline/simple tests.
+- `login=yes|no`: control admin auto-login. Use `login=no` to prevent automatic admin login; admin pages will require manual login.
+- `multisite=yes|no`: choose single-site or multisite mode at boot.
+- `url=/path/`: choose the first page to show. Use `/wp-admin/` for the dashboard or `/wp-admin/site-editor.php` for the Site Editor.
+- `language=<locale>`: set a WordPress locale such as `de_DE`; pair with `networking=yes` so translations can download.
+- `import-site=<zip-url>`: import a public, URL-encoded, CORS-enabled site ZIP.
+- `import-wxr=<wxr-url>`: import a public, URL-encoded, CORS-enabled WordPress export XML/WXR file.
+- `site-slug=<slug>`: select a saved browser site by slug. Use `playgroundSites.list()` when you need to discover slugs first.
+- `if-stored-site-missing=prompt`: ask the user whether to save a new site when `site-slug` is missing.
+- `blueprint-url=<url>`: load a public Blueprint JSON file or Blueprint bundle ZIP.
+- `lazy`: show a Run button and defer loading until clicked, useful for tutorials and click-to-run demos.
+- `mode=browser-full-screen|seamless`: choose browser UI or a full-width WordPress view.
+- `page-title=<title>`: customize the browser tab title when comparing instances.
+- `can-save=no`: remove save options from the UI.
+- `overlay=blueprints`: open the Blueprint Gallery on load.
+
+Use these rules:
+
+- Use Query API links for simple, shareable setup.
+- Use Blueprint URLs/fragments for multi-step setup, files, content creation, custom code, or bundled assets.
+- Do not explain Blueprint schema here; delegate the Blueprint body to the `blueprint` skill.
+- Hosted Blueprint JSON, ZIP bundles, imports, and referenced assets must be public and served with `Access-Control-Allow-Origin: *`.
+- Browser URLs cannot read arbitrary local files or local directory bundles. Use hosted assets or the CLI for local paths.
+- If a missing `site-slug` prompt appears, confirm the user's intent before creating or saving a new browser site.
+
+Small inline Blueprints can be shared with a URL fragment:
+
+```text
+https://playground.wordpress.net/#<encodeURIComponent(JSON.stringify(blueprint))>
+```
+
+Large Blueprints and bundles should use:
+
+```text
+https://playground.wordpress.net/?blueprint-url=<public-json-or-zip-url>
+```
+
+Base64-encoded Blueprint fragments are also supported when a channel rewrites JSON characters.
+
+Other URL capabilities the agent may need:
+
+- Experimental builds: `core-pr=<number>` for WordPress core PRs, `gutenberg-pr=<number>` for Gutenberg PRs, `gutenberg-branch=<branch>` such as `trunk`.
+- Runtime extension: `php-extension=<manifest-url>`; accepts HTTP(S) URLs and may be repeated.
+- Browser MCP bridge: `mcp=yes`, optional `mcp-port=<port>`; default port is `7999`.
+- GitHub export form prefill: `gh-ensure-auth=yes`, `ghexport-repo-url=<repo-url>`, `ghexport-pr-action=create|update`, `ghexport-playground-root=<path>`, `ghexport-repo-root=<path>`, `ghexport-content-type=plugin|theme|wp-content|custom-paths`, `ghexport-plugin=<plugin-path>`, `ghexport-theme=<theme-dir>`, repeatable ghexport-path (`ghexport-path=<relative-path>`), `ghexport-commit-message=<message>`, `ghexport-allow-include-zip=yes|no`.
+
+## Manage browser sites with `window.playgroundSites`
+
+Use `window.playgroundSites` on the top-level `https://playground.wordpress.net/` page. It is not available immediately during page load, so wait for the global and then call `isReady()` before site-manager work.
+
+```js
+while (!window.playgroundSites) {
+	await new Promise((resolve) => setTimeout(resolve, 50));
+}
+await window.playgroundSites.isReady();
+```
+
+Available site-manager operations:
+
+- `list()`: inspect known sites, active site, names, slugs, and storage types.
+- `createNewTemporarySite(slug?, settings?)`: create and switch to a fresh in-memory site. Settings use `phpVersion`, `wpVersion`, `networking`, `language`, and `multisite`.
+- `setActiveSite(slug)`: switch to an existing site and wait for it to boot.
+- `isReady()`: wait until the active site and its client are ready.
+- `getClient()`: get the active site's `PlaygroundClient`.
+- `saveInBrowser(name?)`: persist the active site to OPFS browser storage.
+- `saveToLocalFileSystem(name?, handle?)`: persist the active site to a user-selected local directory when the browser supports it.
+- `rename(newName)`: rename the active saved site.
+- `setPhpVersion(version)`: change PHP version and reboot the active saved site.
+- `setNetworking(enabled)`: toggle outbound networking and reboot the active saved site.
+- `delete(slug)`: delete a saved site when the user explicitly asked for deletion.
+
+Storage behavior:
+
+- `temporary`: in memory only; resets on reload.
+- `opfs`: saved in browser storage for `playground.wordpress.net`; survives reloads.
+- `local-fs`: saved to a user-selected local directory; Chromium/File System Access API only.
+
+Important constraints:
+
+- `createNewTemporarySite()` accepts only version/site boot settings: `phpVersion`, `wpVersion`, `networking`, `language`, and `multisite`. The JS names are `phpVersion` and `wpVersion`, not `php` and `wp`.
+- It does not install plugins/themes or run Blueprints; use a URL/Blueprint workflow for that.
+- `saveInBrowser()` and `saveToLocalFileSystem()` are safe on already-saved sites.
+- `rename()`, `setPhpVersion()`, and `setNetworking()` operate on the active saved site. Switch with `setActiveSite(slug)` first when targeting a specific site. Save a temporary site first.
+- `delete(slug)` deletes a saved site's persisted data; do not call it unless the user asked for deletion.
+
+## Interact with the active WordPress site
+
+Use the active `PlaygroundClient` after the site is booted. If the user says `window.palyground`, treat it as a typo for `window.playground`.
+
+```js
+await window.playgroundSites?.isReady();
+const client = window.playgroundSites?.getClient() || window.playground;
+await client.isReady();
+```
+
+Available active-site operations:
+
+- File inspection: `listFiles`, `readFileAsText`, `readFileAsBuffer`, `fileExists`, `isFile`, `isDir`, `isSymlink`, `readlink`, and `realpath` in the `/wordpress` virtual filesystem.
+- File mutation: `mkdir`, `mkdirTree`, `writeFile`, `mv`, `cp`, `chmod`, `symlink`, `unlink`, `rmdir`, and `unzip`. `mv` moves or renames files. unlink deletes files, while `playgroundSites.delete(slug)` deletes a saved site. `rmdir` is for empty directories.
+- PHP execution: run PHP snippets with `run({ code })`; inspect the returned output/status/error fields. Require `/wordpress/wp-load.php` before using WordPress APIs such as `wp_insert_post`, `get_option`, `get_stylesheet`, or `wp_get_theme`.
+- Web requests: call WordPress routes with `request({ path, method, headers, body })` and inspect status/body. Use it for admin pages such as `/wp-admin/` and REST routes such as `/wp-json/wp/v2/posts`; remember admin/nonce behavior depends on login state.
+- Browser navigation: send the visible Playground frame to a WordPress path with `goTo(path)`.
+- State checks: verify installed/active plugins and themes through WordPress PHP APIs or filesystem checks before claiming setup succeeded.
+- MU plugins: write files under `/wordpress/wp-content/mu-plugins/`, then request or navigate to a WordPress route to force loading.
+
+Keep the distinction clear:
+
+- `playgroundSites` manages site records and persistence.
+- `window.playground` / `getClient()` manipulates the active WordPress runtime.
+- Query API / `blueprint-url` sets up a site at page load.
+
+## Verification
+
+- For a generated URL, open it in a fresh browser session and confirm versions, login state, installed assets, and landing page.
+- For `playgroundSites`, verify `sites.list()` shows the expected active site and storage type.
+- For client operations, run a harmless read first, such as `await client.listFiles('/wordpress')`, before writing files or changing state.
+- If a hosted Blueprint/import fails, verify the URL is public and CORS-enabled.
+- Treat `playground.wordpress.net` as a browser demo/sandbox, not production hosting or guaranteed durable infrastructure.
+- Escalate to the CLI or a full WordPress stack when the task needs local filesystem mounts, snapshots, headless validation, durable production-like persistence, native database access, server integration, or production availability guarantees.
diff --git a/plugins/wordpress/.agents/skills/wp-plugin-development/SKILL.md b/plugins/wordpress/.agents/skills/wp-plugin-development/SKILL.md
index 4456de56..9cec1d05 100644
--- a/plugins/wordpress/.agents/skills/wp-plugin-development/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-plugin-development/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-plugin-development
 description: "Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WP Plugin Development
diff --git a/plugins/wordpress/.agents/skills/wp-project-triage/SKILL.md b/plugins/wordpress/.agents/skills/wp-project-triage/SKILL.md
index 89ac241c..f5ea34e5 100644
--- a/plugins/wordpress/.agents/skills/wp-project-triage/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-project-triage/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-project-triage
 description: "Use when you need a deterministic inspection of a WordPress repository (plugin/theme/block theme/WP core/Gutenberg/full site) including tooling/tests/version hints, and a structured JSON report to guide workflows and guardrails."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WP Project Triage
diff --git a/plugins/wordpress/.agents/skills/wp-rest-api/SKILL.md b/plugins/wordpress/.agents/skills/wp-rest-api/SKILL.md
index ee6b869d..b6cfbf65 100644
--- a/plugins/wordpress/.agents/skills/wp-rest-api/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-rest-api/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-rest-api
 description: "Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing CPTs/taxonomies via show_in_rest."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 
 # WP REST API
@@ -22,7 +22,7 @@ Use this skill when you need to:
 - Repo root + target plugin/theme/mu-plugin (path to entrypoint).
 - Desired namespace + version (e.g. `my-plugin/v1`) and routes.
 - Authentication mode (cookie + nonce vs application passwords vs auth plugin).
-- Target WordPress version constraints (if below 6.9, call out).
+- Target WordPress version constraints (if below 7.0, call out).
 
 ## Procedure
 
diff --git a/plugins/wordpress/.agents/skills/wp-wpcli-and-ops/SKILL.md b/plugins/wordpress/.agents/skills/wp-wpcli-and-ops/SKILL.md
index 5c0ea42a..738aed64 100644
--- a/plugins/wordpress/.agents/skills/wp-wpcli-and-ops/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wp-wpcli-and-ops/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wp-wpcli-and-ops
 description: "Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml."
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WP-CLI in the execution environment."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Requires WP-CLI in the execution environment."
 ---
 
 # WP-CLI and Ops
diff --git a/plugins/wordpress/.agents/skills/wpds/SKILL.md b/plugins/wordpress/.agents/skills/wpds/SKILL.md
index a6245eb5..fdcb1b95 100644
--- a/plugins/wordpress/.agents/skills/wpds/SKILL.md
+++ b/plugins/wordpress/.agents/skills/wpds/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: wpds
 description: "Use when building UIs leveraging the WordPress Design System (WPDS) and its components, tokens, patterns, etc."
-compatibility: "Requires WPDS MCP server configured and running. Targets WordPress 6.9+ (PHP 7.2.24+)."
+compatibility: "Requires WPDS MCP server configured and running. Targets WordPress 7.0+ (PHP 7.4.0+)."
 ---
 
 # WordPress Design System (WPDS)
diff --git a/plugins/wordpress/.claude/skills/blueprint b/plugins/wordpress/.claude/skills/blueprint
new file mode 120000
index 00000000..7774f586
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/blueprint
@@ -0,0 +1 @@
+../../.agents/skills/blueprint
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wordpress-router b/plugins/wordpress/.claude/skills/wordpress-router
new file mode 120000
index 00000000..01c51096
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wordpress-router
@@ -0,0 +1 @@
+../../.agents/skills/wordpress-router
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-abilities-api b/plugins/wordpress/.claude/skills/wp-abilities-api
new file mode 120000
index 00000000..2101b2e3
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-abilities-api
@@ -0,0 +1 @@
+../../.agents/skills/wp-abilities-api
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-block-development b/plugins/wordpress/.claude/skills/wp-block-development
new file mode 120000
index 00000000..0963e566
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-block-development
@@ -0,0 +1 @@
+../../.agents/skills/wp-block-development
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-block-themes b/plugins/wordpress/.claude/skills/wp-block-themes
new file mode 120000
index 00000000..de1e4ce8
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-block-themes
@@ -0,0 +1 @@
+../../.agents/skills/wp-block-themes
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-interactivity-api b/plugins/wordpress/.claude/skills/wp-interactivity-api
new file mode 120000
index 00000000..af7ff284
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-interactivity-api
@@ -0,0 +1 @@
+../../.agents/skills/wp-interactivity-api
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-performance b/plugins/wordpress/.claude/skills/wp-performance
new file mode 120000
index 00000000..94c69cc9
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-performance
@@ -0,0 +1 @@
+../../.agents/skills/wp-performance
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-phpstan b/plugins/wordpress/.claude/skills/wp-phpstan
new file mode 120000
index 00000000..31b668fb
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-phpstan
@@ -0,0 +1 @@
+../../.agents/skills/wp-phpstan
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-playground b/plugins/wordpress/.claude/skills/wp-playground
new file mode 120000
index 00000000..67fd7571
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-playground
@@ -0,0 +1 @@
+../../.agents/skills/wp-playground
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-plugin-development b/plugins/wordpress/.claude/skills/wp-plugin-development
new file mode 120000
index 00000000..206df785
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-plugin-development
@@ -0,0 +1 @@
+../../.agents/skills/wp-plugin-development
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-project-triage b/plugins/wordpress/.claude/skills/wp-project-triage
new file mode 120000
index 00000000..e2af6927
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-project-triage
@@ -0,0 +1 @@
+../../.agents/skills/wp-project-triage
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-rest-api b/plugins/wordpress/.claude/skills/wp-rest-api
new file mode 120000
index 00000000..ea95fa58
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-rest-api
@@ -0,0 +1 @@
+../../.agents/skills/wp-rest-api
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wp-wpcli-and-ops b/plugins/wordpress/.claude/skills/wp-wpcli-and-ops
new file mode 120000
index 00000000..1f796a8f
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wp-wpcli-and-ops
@@ -0,0 +1 @@
+../../.agents/skills/wp-wpcli-and-ops
\ No newline at end of file
diff --git a/plugins/wordpress/.claude/skills/wpds b/plugins/wordpress/.claude/skills/wpds
new file mode 120000
index 00000000..9506797a
--- /dev/null
+++ b/plugins/wordpress/.claude/skills/wpds
@@ -0,0 +1 @@
+../../.agents/skills/wpds
\ No newline at end of file
diff --git a/plugins/wordpress/agent/skills/blueprint/SKILL.md b/plugins/wordpress/agent/skills/blueprint/SKILL.md
index 244b1315..524f3e4c 100644
--- a/plugins/wordpress/agent/skills/blueprint/SKILL.md
+++ b/plugins/wordpress/agent/skills/blueprint/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: "Use when creating, editing, or reviewing WordPress Playground blueprint JSON files. Triggers on mentions of blueprints, playground configuration, or requests to set up a WordPress demo environment."
+description: "Use when the deliverable is WordPress Playground Blueprint JSON or a Blueprint bundle, including creating, editing, reviewing, validating schema keys, choosing steps/resources, and debugging Blueprint files. For only running or sharing a Playground environment, use wp-playground."
 ---
 # WordPress Playground Blueprints
 
@@ -28,9 +28,11 @@ All optional. Only documented keys are allowed — the schema rejects unknown pr
 |----------|------|-------|
 | `$schema` | string | Always `"https://playground.wordpress.net/blueprint-schema.json"` |
 | `landingPage` | string | Relative path, e.g. `/wp-admin/` |
+| `description` | string | Deprecated optional top-level description. Prefer `meta.description` for new Blueprints |
 | `meta` | object | `{ title, author, description?, categories? }` — title and author required |
 | `preferredVersions` | object | `{ php, wp }` — both required when present |
 | `features` | object | `{ networking?: boolean, intl?: boolean }` — **only** these two keys, nothing else. Networking defaults to `true` |
+| `phpExtensionBundles` | any | Deprecated/no longer used; the schema leaves the value unconstrained and says to remove it from Blueprints |
 | `extraLibraries` | array | `["wp-cli"]` — auto-included when any `wp-cli` step is present |
 | `constants` | object | Shorthand for `defineWpConfigConsts`. Values: string/boolean/number |
 | `plugins` | array | Shorthand for `installPlugin` steps. Strings = wp.org slugs |
@@ -40,8 +42,8 @@ All optional. Only documented keys are allowed — the schema rejects unknown pr
 
 ### preferredVersions Values
 
-- **php:** Major.minor only (e.g. `"8.3"`, `"7.4"`), or `"latest"`. Patch versions like `"7.4.1"` are invalid. Check the schema for currently supported versions.
-- **wp:** Recent major versions (e.g. `"6.7"`, `"6.8"`), `"latest"`, `"nightly"`, `"beta"`, or a URL to a custom zip. Check the schema for the full list.
+- **php:** Major.minor only: `"7.4"`, `"8.0"`, `"8.1"`, `"8.2"`, `"8.3"`, `"8.4"`, `"8.5"`, or `"latest"`. Patch versions like `"7.4.1"` are invalid. Check the schema for currently supported versions.
+- **wp:** Recent major versions, `"latest"`, `"beta"`, `"nightly"`/`"trunk"`, or a URL to a custom zip. The schema also accepts `false` for PHP-only Playground; do not combine `wp: false` with WordPress-only fields such as `plugins`, `siteOptions`, `login`, or WordPress-only steps.
 
 ### Shorthands vs Steps
 
@@ -385,13 +387,13 @@ dashboard-widget-bundle/
 
 ### Inline Blueprints (quick test, no bundles)
 
-Minify the blueprint JSON (no extra whitespace), prepend `https://playground.wordpress.net/#`, and open the URL in a browser:
+Minify the blueprint JSON (no extra whitespace), encode it once with `encodeURIComponent()`, prepend `https://playground.wordpress.net/#`, and open the URL in a browser:
 
 ```
-https://playground.wordpress.net/#{"$schema":"https://playground.wordpress.net/blueprint-schema.json","preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}
+https://playground.wordpress.net/#%7B%22%24schema%22%3A%22https%3A%2F%2Fplayground.wordpress.net%2Fblueprint-schema.json%22%2C%22preferredVersions%22%3A%7B%22php%22%3A%228.3%22%2C%22wp%22%3A%22latest%22%7D%2C%22steps%22%3A%5B%7B%22step%22%3A%22login%22%7D%5D%7D
 ```
 
-Very large blueprints may exceed browser URL length limits; use the CLI instead.
+Very large blueprints may exceed browser URL length limits; use the CLI or a hosted Blueprint URL instead. For share-link details, use `wp-playground/references/website.md`.
 
 ### Local CLI Testing
 
@@ -409,6 +411,6 @@ npx @wp-playground/cli server --blueprint=./bundle.zip
 npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files
 ```
 
-### Testing with the wordpress-playground-server Skill
+### Testing with WordPress Playground
 
-Use the `wordpress-playground-server` skill to start a local Playground instance with `--blueprint /path/to/blueprint.json`, then verify the expected state with Playwright MCP. For directory bundles, pass `--blueprint-may-read-adjacent-files` as an extra argument.
+Use the `wp-playground` skill for local or browser testing. For CLI testing, follow `wp-playground/references/cli.md` with `--blueprint=<path-or-url>`; for directory bundles, pass `--blueprint-may-read-adjacent-files`.
diff --git a/plugins/wordpress/agent/skills/wordpress-router/references/decision-tree.md b/plugins/wordpress/agent/skills/wordpress-router/references/decision-tree.md
index 6d72cbb1..c82ae96e 100644
--- a/plugins/wordpress/agent/skills/wordpress-router/references/decision-tree.md
+++ b/plugins/wordpress/agent/skills/wordpress-router/references/decision-tree.md
@@ -25,8 +25,14 @@ Route by intent even if repo kind is broad (like `wp-site`):
   - Route → `wp-interactivity-api`.
 - **Abilities API / wp_register_ability / wp-abilities/v1 / @wordpress/abilities**
   - Route → `wp-abilities-api`.
-- **Playground / run-blueprint / build-snapshot / @wp-playground/cli / playground.wordpress.net**
-  - Route → `wp-playground`.
+- **Ambiguous WordPress Playground requests**
+  - Route → `wp-playground`, then follow its routing wrapper.
+- **Blueprint JSON / Blueprint schema / Blueprint steps / Blueprint bundles**
+  - Route → `blueprint`.
+- **@wp-playground/cli / server / run-blueprint / build-snapshot / auto-mount / Xdebug**
+  - Route → `wp-playground`, then read `references/cli.md` or `references/debugging.md`.
+- **playground.wordpress.net / Blueprint Editor / share links / browser-only Playground**
+  - Route → `wp-playground`, then read `references/website.md`.
 - **Blocks / block.json / registerBlockType / attributes / save serialization**
   - Route → `wp-block-development`.
 - **theme.json / Global Styles / templates/*.html / patterns/**
diff --git a/plugins/wordpress/agent/skills/wp-block-themes/references/debugging.md b/plugins/wordpress/agent/skills/wp-block-themes/references/debugging.md
index 5475e204..9414a16c 100644
--- a/plugins/wordpress/agent/skills/wp-block-themes/references/debugging.md
+++ b/plugins/wordpress/agent/skills/wp-block-themes/references/debugging.md
@@ -7,6 +7,7 @@ Fast checks:
 1. Confirm you edited the active theme (Site Editor → theme).
 2. Check if user customizations exist (they override theme defaults).
 3. Validate `theme.json` structure (typos can prevent styles from applying).
+4. If a `var(--wp--preset--*)` / `var(--wp--custom--*)` reference is silently using its fallback, the slug is likely un-normalised — WordPress hyphenates digit/letter boundaries and camelCase transitions before emitting the CSS var. See `theme-json.md` § "Slug normalisation gotcha".
 
 Remember the hierarchy:
 
diff --git a/plugins/wordpress/agent/skills/wp-block-themes/references/theme-json.md b/plugins/wordpress/agent/skills/wp-block-themes/references/theme-json.md
index fa25bc40..45049e02 100644
--- a/plugins/wordpress/agent/skills/wp-block-themes/references/theme-json.md
+++ b/plugins/wordpress/agent/skills/wp-block-themes/references/theme-json.md
@@ -57,3 +57,17 @@ References:
 
 - Border radius presets: https://make.wordpress.org/core/2025/11/12/theme-json-border-radius-presets-support-in-wordpress-6-9/
 - Form element styling: https://developer.wordpress.org/news/2025/11/how-wordpress-6-9-gives-forms-a-theme-json-makeover/
+
+## Slug normalisation gotcha
+
+> **Slug normaliser trap (silent failure).** WordPress inserts hyphens inside preset/custom slugs before emitting CSS vars: slug `3xl` becomes `--wp--preset--font-size--3-xl`; slug `cardShadow` becomes `--wp--custom--card-shadow`. A handwritten reference to the *un-normalised* form (e.g. `var(--wp--preset--font-size--3xl)`) resolves to nothing and silently falls back to the second `var()` argument.
+
+Before assembling the variable name, `WP_Theme_JSON` passes each preset/custom slug through `_wp_to_kebab_case()`, which splits it into word tokens — at digit/letter boundaries, camelCase transitions, and non-alphanumeric characters — lowercases them, and joins with `-`. Reference the emitted form, not the slug you typed.
+
+Grep pattern to catch un-normalised references in CSS/SCSS/PHP/JS:
+
+```
+var\(\s*--wp--(?:preset|custom)--[a-z-]+--\d+[a-z]
+```
+
+This matches a digit immediately followed by a letter inside the variable name (`3xl`, `2xs`, `4x-large`) — every emitted form keeps the hyphen (`3-xl`, `2-xs`, `4-x-large`) and is correctly not flagged.
diff --git a/plugins/wordpress/agent/skills/wp-playground/SKILL.md b/plugins/wordpress/agent/skills/wp-playground/SKILL.md
index 9a6fa435..f9f2e932 100644
--- a/plugins/wordpress/agent/skills/wp-playground/SKILL.md
+++ b/plugins/wordpress/agent/skills/wp-playground/SKILL.md
@@ -1,98 +1,49 @@
 ---
-description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging (Xdebug)."
+description: "Use as the WordPress Playground routing wrapper for ambiguous Playground work, local CLI runs with @wp-playground/cli, playground.wordpress.net share links, browser previews, snapshots, mounts, version switching, and Xdebug. For Blueprint JSON authoring or review, use the blueprint skill directly."
 ---
 # WordPress Playground
 
-## When to use
-
-- Spin up a disposable WordPress to test a plugin/theme without full stack setup.
-- Run or iterate on Playground Blueprints (JSON) locally.
-- Build a reproducible snapshot of a site for sharing or CI.
-- Switch WP/PHP versions quickly to reproduce issues.
-- Debug plugin/theme code with Xdebug in an isolated Playground.
-
-## Inputs required
-
-- Host machine readiness: Node.js ≥ 20.18, `npm`/`npx` available.
-- Project path to mount (`--auto-mount` or explicit mount mapping).
-- Desired WP version/PHP version (optional; defaults to latest WP, PHP 8.3).
-- Blueprint location/URL if running a blueprint.
-- Port preference if 9400 conflicts.
-- Whether Xdebug is needed.
+This is a thin routing wrapper. Use it to pick the right Playground workflow, then load only the focused reference or skill needed for the task.
 
 ## Procedure
 
-### 0) Guardrails
-
-- Playground instances are ephemeral and SQLite-backed; **never** point at production data.
-- Confirm Node ≥ 20.18 (`node -v`) before running CLI.
-- If mounting local code, ensure it is clean of secrets; Playground copies files into an in-memory FS.
-
-### 1) Quick local spin-up (auto-mount)
-
-```bash
-cd <plugin-or-theme-root>
-npx @wp-playground/cli@latest server --auto-mount
-```
-- Opens on http://localhost:9400 by default. Auto-detects plugin/theme and installs it.
-- Add `--wp=<version>` / `--php=<version>` as needed.
-- For classic full installs already present, add `--skip-wordpress-setup` and mount the whole tree.
-
-### 2) Manual mounts or multiple mounts
+1. Identify the user intent: Blueprint authoring/review, local CLI execution, browser-only website/share link workflow, Xdebug/stuck CLI run, or a mixed Playground request.
+2. Route to the focused source below, loading more than one only when the request has multiple distinct parts.
+3. For mixed requests, delegate Blueprint JSON work to `blueprint`, then return here for runtime, CLI, debugging, or sharing guidance.
 
-- Use `--mount=/host/path:/vfs/path` (repeatable) when auto-mount is insufficient (multi-plugin, mu-plugins, custom content).
-- Mount before install with `--mount-before-install` for bootstrapping installer flows.
-- Reference: `references/cli-commands.md`
+- **Blueprint JSON, schema, steps, resources, bundles, or Blueprint review**: use the `blueprint` skill directly. Do not duplicate Blueprint schema details here.
+- **Local CLI execution**: read `references/cli.md` for `@wp-playground/cli` server, `run-blueprint`, `build-snapshot`, mounts, version switching, and local validation.
+- **Xdebug or stuck CLI runs**: read `references/debugging.md` for Xdebug, runtime logs, worker flags, and stuck CLI runs.
+- **Browser-only Playground website workflows**: read `references/website.md` for `playground.wordpress.net`, share URLs, Blueprint Editor, hosted bundles, and browser limitations.
 
-### 3) Run a Blueprint (no server needed)
-
-```bash
-npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
-```
-- Use for scripted setup/CI validation. Supports remote URLs and local files.
-- Allow bundled assets in local blueprints with `--blueprint-may-read-adjacent-files` when required.
-- See `references/blueprints.md` for structure and common flags.
-
-### 4) Build a snapshot for sharing
-
-```bash
-npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip
-```
-- Produces a ZIP you can load in Playground or attach to bug reports.
-
-### 5) Debugging with Xdebug
-
-- Start with `--xdebug` (or `--enable-xdebug` depending on CLI release) to expose an IDE key, then connect VS Code/PhpStorm to the host/port shown in CLI output.
-- Combine with `--auto-mount` for plugin/theme debugging.
-- Checklist: `references/debugging.md`
-
-### 6) Version switching
+## Inputs required
 
-- Use `--wp=` to pin WP (e.g., 6.9.0) and `--php=` to test compatibility.
-- If feature depends on Gutenberg trunk, prefer the latest WP release plus plugin if available; Playground images track stable WP plus bundled Gutenberg.
+- The intended workflow: Blueprint authoring, local CLI run, website/share link, snapshot, or debugging.
+- Project or bundle path if local code must be mounted or packaged.
+- Desired WordPress/PHP versions if compatibility matters.
+- Port preference if a local server is needed.
+- Whether browser-only sharing or local filesystem access is required.
 
-### 7) Browser-only workflows (no CLI)
+## Guardrails
 
-- Launch quick previews with URL fragments or query params:
-  - Fragment: `https://playground.wordpress.net/#<base64-or-json-blueprint>`
-  - Query: `https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>`
-- Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.
+- Playground instances are disposable, SQLite-backed environments; never point them at production data.
+- Keep Blueprint JSON guidance in `blueprint` so the schema and examples have one source of truth.
+- For local CLI work, verify Node.js 20.18+ and `npm`/`npx` before running commands.
+- Browser-only Playground cannot read local filesystem paths; use public URLs, hosted ZIP bundles, or inline Blueprint JSON.
 
 ## Verification
 
-- Verify mounted code is active (plugin listed/active; theme selected).
-- For blueprints/snapshots, re-run with `--verbosity=debug` to confirm steps executed.
-- Run targeted smoke (e.g., `wp plugin list` inside Playground shell via browser terminal if exposed) or UI click-path.
+- For Blueprint content, validate against the published schema and follow the `blueprint` skill verification.
+- For local CLI runs, verify the mounted plugin/theme or Blueprint side effects in the Playground instance.
+- For share links, open the generated URL and confirm the expected landing page and installed assets load.
 
-## Failure modes / debugging
+## Failure modes
 
-- **CLI exits complaining about Node**: upgrade to ≥ 20.18.
-- **Mount not applied**: check path, use absolute path, add `--verbosity=debug`.
-- **Blueprint cannot read local assets**: add `--blueprint-may-read-adjacent-files`.
-- **Port already used**: `--port=<free-port>`.
-- **Slow/locked UI**: disable `--experimental-multi-worker` if enabled; or enable it to improve throughput on CPU-bound runs.
+- **Blueprint work routed here**: stop and use the `blueprint` skill for schema keys, steps, resources, bundles, validation, or Blueprint review.
+- **Local filesystem needed in a browser-only workflow**: use `references/cli.md`; `playground.wordpress.net` cannot read local filesystem paths.
+- **Shareable browser link requested from a local CLI workflow**: use `references/website.md`; local server URLs are not portable share links.
+- **Debugging treated as a second-hop reference**: read `references/debugging.md` directly for Xdebug, logs, worker flags, and stuck CLI runs.
 
 ## Escalation
 
-- If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
-- For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/
+- If the task needs PHP extensions, native database access, persistence, or production-like infrastructure that Playground cannot provide, use a full WordPress stack such as wp-env, Docker, or the project-provided environment.
diff --git a/plugins/wordpress/agent/skills/wp-playground/references/blueprints.md b/plugins/wordpress/agent/skills/wp-playground/references/blueprints.md
deleted file mode 100644
index da26cee6..00000000
--- a/plugins/wordpress/agent/skills/wp-playground/references/blueprints.md
+++ /dev/null
@@ -1,36 +0,0 @@
-## Blueprint quick reference
-
-Blueprints are JSON recipes that describe how Playground should set up WordPress.
-
-### Minimal example
-
-```json
-{
-  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
-  "steps": [
-    { "step": "installTheme", "themeZipUrl": "https://downloads.wordpress.org/theme/twentytwentythree.zip" },
-    { "step": "installPlugin", "pluginZipUrl": "https://downloads.wordpress.org/plugin/classic-editor.zip" }
-  ]
-}
-```
-
-### Common steps (non-exhaustive)
-
-- `setSiteUrl`, `setHomeUrl`
-- `installTheme`, `installPlugin` (ZIP URLs or local paths when allowed)
-- `activateTheme`, `activatePlugin`
-- `runPHP` (inline PHP)
-- `applyPatches` (filesystem patch)
-- `writeFile` (create/update files)
-- `importFile` (XML/WXR)
-- `wpConfigConstants` (define constants)
-- `preferredVersions` (pick WP/PHP; matches CLI `--wp` / `--php`)
-- `blueprintSteps` that include `extraLibraries` (e.g., Jetpack) and `features.networking` when browser networking is required
-
-### Tips
-
-- Use `--blueprint-may-read-adjacent-files` when the blueprint needs local files (e.g., custom plugin ZIP) during `run-blueprint` or `build-snapshot`.
-- For iterative authoring, keep blueprints small and compose via separate files.
-- Validate against the published schema URL above to catch typos.
-- For Gutenberg/nightly testing, set `--wp=<version>` to align with target WP.
-- To share quickly, encode the blueprint as base64 in the Playground URL fragment or host the JSON/ZIP and pass `?blueprint-url=…`.
diff --git a/plugins/wordpress/agent/skills/wp-playground/references/cli-commands.md b/plugins/wordpress/agent/skills/wp-playground/references/cli-commands.md
deleted file mode 100644
index 8eb5ba1b..00000000
--- a/plugins/wordpress/agent/skills/wp-playground/references/cli-commands.md
+++ /dev/null
@@ -1,39 +0,0 @@
-## Playground CLI command cheatsheet
-
-> Requires Node.js 20.18+ and npm/npx.
-> Latest version: 3.0.20 (November 2025)
-
-### What's new in 2025
-
-- **PHP 8.3 is now the default** (since July 2025).
-- **New PHP extensions**: ImageMagick, SOAP, and AVIF GD support.
-- **OpCache enabled**: 42% faster response times (185ms → 108ms average).
-- **Multi-worker default**: `--experimental-multi-worker` now defaults to CPU count minus one.
-
-### Install / run server
-
-- `npx @wp-playground/cli@latest server [--port=9400] [--auto-mount] [--wp=<ver>] [--php=<ver>] [--verbosity=debug] [--blueprint=<url-or-path>]`
-- Mounts:
-  - `--auto-mount` (detect plugin/theme in CWD)
-  - `--mount=/abs/host:/vfs/path` (repeatable)
-  - `--mount-before-install` (apply mounts before WP install)
-
-### Run a blueprint
-
-- `npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url> [--blueprint-may-read-adjacent-files] [--wp=<ver>] [--php=<ver>] [--verbosity=debug]`
-- Use for scripted setup; no persistent server.
-
-### Build a snapshot
-
-- `npx @wp-playground/cli@latest build-snapshot --blueprint=<file-or-url> --outfile=./site.zip [--verbosity=debug]`
-- Produces a sharable ZIP usable by Playground UI or other CLI commands.
-
-### Debugging flags
-
-- `--xdebug` / `--enable-xdebug` (depends on release) to start Xdebug listener.
-- `--experimental-multi-worker` to speed multi-step blueprints; disable if unstable.
-
-### Version control
-
-- `--wp=<version>` to pick WordPress version (defaults to latest).
-- `--php=<version>` to pick PHP version (defaults to 8.3 since July 2025).
diff --git a/plugins/wordpress/agent/skills/wp-playground/references/cli.md b/plugins/wordpress/agent/skills/wp-playground/references/cli.md
new file mode 100644
index 00000000..0204be6b
--- /dev/null
+++ b/plugins/wordpress/agent/skills/wp-playground/references/cli.md
@@ -0,0 +1,119 @@
+## Playground CLI workflows
+
+Use this reference for local WordPress Playground runs with `@wp-playground/cli`: disposable or persisted local servers, mounted plugins/themes, Blueprint execution, snapshots, version switching, and local smoke tests.
+
+## Prerequisites
+
+- Node.js 20.18+ with `npm`/`npx` available.
+- A local project, plugin, theme, Blueprint file, or Blueprint bundle path.
+- A free local port when using `server`; the default is `9400`.
+
+Check the installed CLI help when exact flags matter:
+
+```bash
+npx @wp-playground/cli@latest --help
+npx @wp-playground/cli@latest start --help
+npx @wp-playground/cli@latest server --help
+```
+
+## Quick local development
+
+Use `start` for the common local plugin/theme workflow. It detects the project type, mounts the project, opens a browser, enables admin auto-login, and persists the site between sessions.
+
+```bash
+cd <plugin-or-theme-root>
+node -v
+npx @wp-playground/cli@latest start
+```
+
+- Use `npx @wp-playground/cli@latest start --reset` when the persisted site should be recreated from scratch.
+- Use `server` with explicit `--wp=<version>` and `--php=<version>` when reproducing compatibility issues instead of relying on moving defaults.
+
+## Advanced local server
+
+Use `server` when you need full manual control, a disposable site, CI-style behavior, custom mounts, or a Blueprint-backed server:
+
+```bash
+npx @wp-playground/cli@latest server --auto-mount
+```
+
+- `--auto-mount[=<path>]` detects a WordPress directory, plugin, theme, wp-content directory, or PHP/HTML directory.
+- Add `--port=<free-port>` when the default port is busy.
+- For existing WordPress files, prefer `--wordpress-install-mode=install-from-existing-files-if-needed` to skip setup when a site is already present.
+- Use `--wordpress-install-mode=do-not-attempt-installing` only when WordPress files and database integration are already handled by the mounted tree.
+
+## Manual mounts
+
+Use explicit mounts when auto-mount is not enough:
+
+```bash
+npx @wp-playground/cli@latest server \
+  --mount=/absolute/host/path:/wordpress/wp-content/plugins/my-plugin
+```
+
+- Use absolute host paths.
+- Repeat `--mount=` for multiple plugins, mu-plugins, themes, or custom content.
+- Use `--mount-before-install` when installer or Blueprint steps need mounted files before WordPress setup completes.
+- On Windows or when colon-separated mappings are awkward, use `--mount-dir "/host/path" "/vfs/path"` or `--mount-dir-before-install "/host/path" "/vfs/path"`.
+
+## Run a Blueprint
+
+For headless setup or CI-style validation:
+
+```bash
+npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
+```
+
+- Use the `blueprint` skill for Blueprint JSON structure and schema details.
+- Add `--blueprint-may-read-adjacent-files` when a local Blueprint directory or bundle references nearby files.
+- Add `--verbosity=debug` when step execution needs inspection.
+
+## Start a server from a Blueprint
+
+```bash
+npx @wp-playground/cli@latest server --blueprint=<file-or-url>
+```
+
+For local directory bundles:
+
+```bash
+npx @wp-playground/cli@latest server \
+  --blueprint=./my-bundle/ \
+  --blueprint-may-read-adjacent-files
+```
+
+ZIP bundles are self-contained and do not need adjacent-file access.
+
+## Build a snapshot
+
+```bash
+npx @wp-playground/cli@latest build-snapshot \
+  --blueprint=<file-or-url> \
+  --outfile=./site.zip
+```
+
+- Use snapshots for shareable repro cases or CI artifacts.
+- Re-run with `--verbosity=debug` if the generated site does not contain the expected state.
+
+## Version switching
+
+- Use `--wp=<version>` to pin WordPress.
+- Use `--php=<version>` to pin PHP.
+- Prefer explicit versions for bug reproduction and compatibility testing.
+- Use the CLI help or current Playground docs to confirm supported version values and defaults.
+
+## Verification
+
+- Confirm the plugin appears in the admin plugin list and is active when expected.
+- Confirm the selected theme is active when testing themes.
+- For Blueprints, verify expected options, pages, plugins, themes, or files after the run.
+- For snapshots, load the ZIP in a fresh Playground instance before sharing it as a repro artifact.
+
+## Failure modes
+
+- **Node version error**: upgrade to Node.js 20.18+.
+- **Mount not applied**: use an absolute path, verify the virtual path, and rerun with `--verbosity=debug`.
+- **Blueprint cannot read local assets**: add `--blueprint-may-read-adjacent-files` for local directory bundles.
+- **Port already used**: pass `--port=<free-port>`.
+- **Need a fresh persisted `start` site**: rerun with `start --reset`.
+- **Need breakpoints or runtime logs**: return to the `wp-playground` routing procedure and select the debugging workflow.
diff --git a/plugins/wordpress/agent/skills/wp-playground/references/debugging.md b/plugins/wordpress/agent/skills/wp-playground/references/debugging.md
index 695d2643..ed6922d1 100644
--- a/plugins/wordpress/agent/skills/wp-playground/references/debugging.md
+++ b/plugins/wordpress/agent/skills/wp-playground/references/debugging.md
@@ -1,16 +1,16 @@
 ## Debugging WordPress Playground
 
-- Start CLI with Xdebug: `server --auto-mount --xdebug` (or `--enable-xdebug` depending on release). The CLI prints host/port and IDE key to configure your debugger.
+- Start CLI with Xdebug: `server --auto-mount --xdebug`. The CLI prints host/port and IDE key to configure your debugger; if the installed CLI help differs, follow `npx @wp-playground/cli@latest server --help`.
 - If breakpoints are not hit, confirm:
   - IDE listens on the port shown by CLI.
   - Path mappings include the mounted VFS path used by Playground.
 - For slow or stuck runs:
   - Add `--verbosity=debug` to see step-level logs.
-  - Disable `--experimental-multi-worker` if it was enabled.
+  - Use `--debug` to print the PHP error log when boot fails.
+  - Adjust request workers with `--workers=<n|auto>`; use `--workers=1` to isolate worker-related behavior.
 - For mount issues:
   - Prefer absolute paths in `--mount`.
   - Use `--mount-before-install` when installer steps need files present early.
 - To inspect runtime state:
   - Open the Playground browser console; the Service Worker logs network/FS events.
   - Use the “Terminal” tab (if available) to run WP-CLI inside the instance.
-
diff --git a/plugins/wordpress/agent/skills/wp-playground/references/website.md b/plugins/wordpress/agent/skills/wp-playground/references/website.md
new file mode 100644
index 00000000..e8e83eb5
--- /dev/null
+++ b/plugins/wordpress/agent/skills/wp-playground/references/website.md
@@ -0,0 +1,164 @@
+## Playground website workflows
+
+Use this reference when the agent must use `https://playground.wordpress.net/` itself: create a browser Playground site, share a Playground URL, manage saved sites, or interact with the currently running WordPress site from DevTools/browser automation.
+
+## Route first
+
+- For Blueprint JSON structure, schema, resources, steps, or bundles, use the `blueprint` skill first; the Blueprint skill is the source of truth for Blueprint details.
+- For local filesystem mounts, snapshots, Xdebug, or headless validation, return to the `wp-playground` routing procedure and select the local CLI or debugging workflow.
+
+## Working model for agents
+
+`playground.wordpress.net` gives the agent three useful control surfaces:
+
+- **URL setup**: Query API parameters and Blueprint URLs create or open a site in a desired state. Use this before the site boots.
+- **Site manager**: `window.playgroundSites` manages the website's saved browser sites. Use it to list, create, switch, save, rename, delete, or reconfigure sites.
+- **Active site client**: `window.playground` is the `PlaygroundClient` for the currently running WordPress site. `playgroundSites.getClient()` returns the same client after the active site is ready. Use it to inspect files, write files, run PHP, make HTTP-style WordPress requests, and navigate.
+
+Use the website/site-manager layer to create or choose a site. Use the active site client to change WordPress itself.
+
+## Decide what to do
+
+| User intent | Agent action |
+| --- | --- |
+| Share a quick reviewer/demo site | Build a `https://playground.wordpress.net/?...` URL with Query API parameters. |
+| Share a multi-step setup | Use the `blueprint` skill to create/review the Blueprint, then pass it as a URL fragment or `?blueprint-url=`. |
+| Create a blank temporary site from the browser | Open `playground.wordpress.net`, then call `playgroundSites.createNewTemporarySite()`. |
+| Keep a temporary site after reload | Call `playgroundSites.saveInBrowser()` for OPFS persistence. |
+| Switch between saved browser sites | Call `playgroundSites.list()` and `playgroundSites.setActiveSite(slug)`. |
+| Change PHP version or networking on an existing saved site | Save it first, then call `setPhpVersion()` or `setNetworking()`. |
+| Inspect or modify WordPress files/content | Get the active client with `playgroundSites.getClient()` or `window.playground`, then use client file/PHP/request methods. |
+
+## Create or open a site with a URL
+
+For a blank disposable Playground site, use `https://playground.wordpress.net/` with no query parameters.
+
+Use Query API URLs when the setup is simple enough to express as URL parameters:
+
+```text
+https://playground.wordpress.net/?php=8.4&wp=latest&plugin=gutenberg&networking=yes&url=/wp-admin/post-new.php
+```
+
+Practical URL parameters for agents:
+
+- `php=<version>` and `wp=<version>`: choose runtime versions.
+- `plugin=<slug>` and `theme=<slug>`: install WordPress.org assets; repeat the parameter for multiple assets, such as `?plugin=gutenberg&plugin=woocommerce&networking=yes`.
+- `networking=yes|no`: allow or block downloads for plugins, themes, translations, imports, and PR builds. Use `networking=no` or omit networking for offline/simple tests.
+- `login=yes|no`: control admin auto-login. Use `login=no` to prevent automatic admin login; admin pages will require manual login.
+- `multisite=yes|no`: choose single-site or multisite mode at boot.
+- `url=/path/`: choose the first page to show. Use `/wp-admin/` for the dashboard or `/wp-admin/site-editor.php` for the Site Editor.
+- `language=<locale>`: set a WordPress locale such as `de_DE`; pair with `networking=yes` so translations can download.
+- `import-site=<zip-url>`: import a public, URL-encoded, CORS-enabled site ZIP.
+- `import-wxr=<wxr-url>`: import a public, URL-encoded, CORS-enabled WordPress export XML/WXR file.
+- `site-slug=<slug>`: select a saved browser site by slug. Use `playgroundSites.list()` when you need to discover slugs first.
+- `if-stored-site-missing=prompt`: ask the user whether to save a new site when `site-slug` is missing.
+- `blueprint-url=<url>`: load a public Blueprint JSON file or Blueprint bundle ZIP.
+- `lazy`: show a Run button and defer loading until clicked, useful for tutorials and click-to-run demos.
+- `mode=browser-full-screen|seamless`: choose browser UI or a full-width WordPress view.
+- `page-title=<title>`: customize the browser tab title when comparing instances.
+- `can-save=no`: remove save options from the UI.
+- `overlay=blueprints`: open the Blueprint Gallery on load.
+
+Use these rules:
+
+- Use Query API links for simple, shareable setup.
+- Use Blueprint URLs/fragments for multi-step setup, files, content creation, custom code, or bundled assets.
+- Do not explain Blueprint schema here; delegate the Blueprint body to the `blueprint` skill.
+- Hosted Blueprint JSON, ZIP bundles, imports, and referenced assets must be public and served with `Access-Control-Allow-Origin: *`.
+- Browser URLs cannot read arbitrary local files or local directory bundles. Use hosted assets or the CLI for local paths.
+- If a missing `site-slug` prompt appears, confirm the user's intent before creating or saving a new browser site.
+
+Small inline Blueprints can be shared with a URL fragment:
+
+```text
+https://playground.wordpress.net/#<encodeURIComponent(JSON.stringify(blueprint))>
+```
+
+Large Blueprints and bundles should use:
+
+```text
+https://playground.wordpress.net/?blueprint-url=<public-json-or-zip-url>
+```
+
+Base64-encoded Blueprint fragments are also supported when a channel rewrites JSON characters.
+
+Other URL capabilities the agent may need:
+
+- Experimental builds: `core-pr=<number>` for WordPress core PRs, `gutenberg-pr=<number>` for Gutenberg PRs, `gutenberg-branch=<branch>` such as `trunk`.
+- Runtime extension: `php-extension=<manifest-url>`; accepts HTTP(S) URLs and may be repeated.
+- Browser MCP bridge: `mcp=yes`, optional `mcp-port=<port>`; default port is `7999`.
+- GitHub export form prefill: `gh-ensure-auth=yes`, `ghexport-repo-url=<repo-url>`, `ghexport-pr-action=create|update`, `ghexport-playground-root=<path>`, `ghexport-repo-root=<path>`, `ghexport-content-type=plugin|theme|wp-content|custom-paths`, `ghexport-plugin=<plugin-path>`, `ghexport-theme=<theme-dir>`, repeatable ghexport-path (`ghexport-path=<relative-path>`), `ghexport-commit-message=<message>`, `ghexport-allow-include-zip=yes|no`.
+
+## Manage browser sites with `window.playgroundSites`
+
+Use `window.playgroundSites` on the top-level `https://playground.wordpress.net/` page. It is not available immediately during page load, so wait for the global and then call `isReady()` before site-manager work.
+
+```js
+while (!window.playgroundSites) {
+	await new Promise((resolve) => setTimeout(resolve, 50));
+}
+await window.playgroundSites.isReady();
+```
+
+Available site-manager operations:
+
+- `list()`: inspect known sites, active site, names, slugs, and storage types.
+- `createNewTemporarySite(slug?, settings?)`: create and switch to a fresh in-memory site. Settings use `phpVersion`, `wpVersion`, `networking`, `language`, and `multisite`.
+- `setActiveSite(slug)`: switch to an existing site and wait for it to boot.
+- `isReady()`: wait until the active site and its client are ready.
+- `getClient()`: get the active site's `PlaygroundClient`.
+- `saveInBrowser(name?)`: persist the active site to OPFS browser storage.
+- `saveToLocalFileSystem(name?, handle?)`: persist the active site to a user-selected local directory when the browser supports it.
+- `rename(newName)`: rename the active saved site.
+- `setPhpVersion(version)`: change PHP version and reboot the active saved site.
+- `setNetworking(enabled)`: toggle outbound networking and reboot the active saved site.
+- `delete(slug)`: delete a saved site when the user explicitly asked for deletion.
+
+Storage behavior:
+
+- `temporary`: in memory only; resets on reload.
+- `opfs`: saved in browser storage for `playground.wordpress.net`; survives reloads.
+- `local-fs`: saved to a user-selected local directory; Chromium/File System Access API only.
+
+Important constraints:
+
+- `createNewTemporarySite()` accepts only version/site boot settings: `phpVersion`, `wpVersion`, `networking`, `language`, and `multisite`. The JS names are `phpVersion` and `wpVersion`, not `php` and `wp`.
+- It does not install plugins/themes or run Blueprints; use a URL/Blueprint workflow for that.
+- `saveInBrowser()` and `saveToLocalFileSystem()` are safe on already-saved sites.
+- `rename()`, `setPhpVersion()`, and `setNetworking()` operate on the active saved site. Switch with `setActiveSite(slug)` first when targeting a specific site. Save a temporary site first.
+- `delete(slug)` deletes a saved site's persisted data; do not call it unless the user asked for deletion.
+
+## Interact with the active WordPress site
+
+Use the active `PlaygroundClient` after the site is booted. If the user says `window.palyground`, treat it as a typo for `window.playground`.
+
+```js
+await window.playgroundSites?.isReady();
+const client = window.playgroundSites?.getClient() || window.playground;
+await client.isReady();
+```
+
+Available active-site operations:
+
+- File inspection: `listFiles`, `readFileAsText`, `readFileAsBuffer`, `fileExists`, `isFile`, `isDir`, `isSymlink`, `readlink`, and `realpath` in the `/wordpress` virtual filesystem.
+- File mutation: `mkdir`, `mkdirTree`, `writeFile`, `mv`, `cp`, `chmod`, `symlink`, `unlink`, `rmdir`, and `unzip`. `mv` moves or renames files. unlink deletes files, while `playgroundSites.delete(slug)` deletes a saved site. `rmdir` is for empty directories.
+- PHP execution: run PHP snippets with `run({ code })`; inspect the returned output/status/error fields. Require `/wordpress/wp-load.php` before using WordPress APIs such as `wp_insert_post`, `get_option`, `get_stylesheet`, or `wp_get_theme`.
+- Web requests: call WordPress routes with `request({ path, method, headers, body })` and inspect status/body. Use it for admin pages such as `/wp-admin/` and REST routes such as `/wp-json/wp/v2/posts`; remember admin/nonce behavior depends on login state.
+- Browser navigation: send the visible Playground frame to a WordPress path with `goTo(path)`.
+- State checks: verify installed/active plugins and themes through WordPress PHP APIs or filesystem checks before claiming setup succeeded.
+- MU plugins: write files under `/wordpress/wp-content/mu-plugins/`, then request or navigate to a WordPress route to force loading.
+
+Keep the distinction clear:
+
+- `playgroundSites` manages site records and persistence.
+- `window.playground` / `getClient()` manipulates the active WordPress runtime.
+- Query API / `blueprint-url` sets up a site at page load.
+
+## Verification
+
+- For a generated URL, open it in a fresh browser session and confirm versions, login state, installed assets, and landing page.
+- For `playgroundSites`, verify `sites.list()` shows the expected active site and storage type.
+- For client operations, run a harmless read first, such as `await client.listFiles('/wordpress')`, before writing files or changing state.
+- If a hosted Blueprint/import fails, verify the URL is public and CORS-enabled.
+- Treat `playground.wordpress.net` as a browser demo/sandbox, not production hosting or guaranteed durable infrastructure.
+- Escalate to the CLI or a full WordPress stack when the task needs local filesystem mounts, snapshots, headless validation, durable production-like persistence, native database access, server integration, or production availability guarantees.
diff --git a/plugins/wordpress/agent/skills/wp-rest-api/SKILL.md b/plugins/wordpress/agent/skills/wp-rest-api/SKILL.md
index 1cb85517..fffc1a5d 100644
--- a/plugins/wordpress/agent/skills/wp-rest-api/SKILL.md
+++ b/plugins/wordpress/agent/skills/wp-rest-api/SKILL.md
@@ -19,7 +19,7 @@ Use this skill when you need to:
 - Repo root + target plugin/theme/mu-plugin (path to entrypoint).
 - Desired namespace + version (e.g. `my-plugin/v1`) and routes.
 - Authentication mode (cookie + nonce vs application passwords vs auth plugin).
-- Target WordPress version constraints (if below 6.9, call out).
+- Target WordPress version constraints (if below 7.0, call out).
 
 ## Procedure
 
diff --git a/plugins/wordpress/skills-lock.json b/plugins/wordpress/skills-lock.json
index 5afba465..bdd9215b 100644
--- a/plugins/wordpress/skills-lock.json
+++ b/plugins/wordpress/skills-lock.json
@@ -5,85 +5,85 @@
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/blueprint/SKILL.md",
-      "computedHash": "1bac422b386d74aba6abac2e8db31645a9a126d08673afa04d65604dbc5e6c0d"
+      "computedHash": "377e75b2481be93113ba4a51b1f9c477d037a5edb001d3956e3f920860570c1f"
     },
     "wordpress-router": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wordpress-router/SKILL.md",
-      "computedHash": "7e1ab6a500f78ecbadde3b9f8277370f7f5d8bc01c014c7bb94f6d5948f2d109"
+      "computedHash": "99441ebad1b000ab3226a4ca1b044fba062326fe7452551d88116cd8fcf8a833"
     },
     "wp-abilities-api": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-abilities-api/SKILL.md",
-      "computedHash": "4663abca4634d1bd4bc067a84554ba8ce5b4256e85012884a7d69e47ef0811a4"
+      "computedHash": "2d665cca2211a87ddde2d37eadd95395f06b9bc48d02b1ea18c0a616d5c84d19"
     },
     "wp-block-development": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-block-development/SKILL.md",
-      "computedHash": "663b1974050e443c3888e714a7204768a45459d07ad0d8102a2f2eca56bb8f9d"
+      "computedHash": "4592e2b8922bb2330d620550b6434fb1992908ab04cb24de2f704166d5012aa9"
     },
     "wp-block-themes": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-block-themes/SKILL.md",
-      "computedHash": "ec31dc2e2a224299225fed1be6f6a94085b3fbfdcf57f22d673949063abf24bc"
+      "computedHash": "95bff49c5755aa856f9f8a7351a2dce82ec4ea7f0a95ffc5928c28d90b5d5d40"
     },
     "wp-interactivity-api": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-interactivity-api/SKILL.md",
-      "computedHash": "50ffcda715b63dfb0f9ca2a2543b9a070fe68f7da89b321295902426e918966c"
+      "computedHash": "29b15bb054d5d1aecd2c9a3fc7a1b49c36512cc425df2459647036c8fc8ba5a4"
     },
     "wp-performance": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-performance/SKILL.md",
-      "computedHash": "580d879ffecd41835e297cbf222443bff6bebf7aaa0efb46852d743249330f9b"
+      "computedHash": "f1301a1224bcb3247af9757749b2fd593fe4850e3b1ef2483cac472eb1fcc993"
     },
     "wp-phpstan": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-phpstan/SKILL.md",
-      "computedHash": "66fc5a465493bfa6993459d56d0781f5bfed31dbf0d98f2d538cd5400a10cf65"
+      "computedHash": "19c1808bafda2f5b929b0fa899a5d3ff138d8fdf79e332056cca28fc358a4d82"
     },
     "wp-playground": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-playground/SKILL.md",
-      "computedHash": "1125d6cd0d9097ae478d4b067cf02f2b2e5f0c6690209aa05c97a3e13dbb8921"
+      "computedHash": "415531bf1c03a5b95fb65a14e8de0f1998d670f94db42fe62282180275a686ad"
     },
     "wp-plugin-development": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-plugin-development/SKILL.md",
-      "computedHash": "3c13a9d2e6e346c9f933918fdf4d191cdba9f2cfe24f87cbcd763d090bbd8014"
+      "computedHash": "2660f4c284157490fabc02493b5c2cbd13fb37d4f1eac149b4064e7d1900f3c5"
     },
     "wp-project-triage": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-project-triage/SKILL.md",
-      "computedHash": "8df079d09f518217580c8eae57d6edf1827b6a8aabe7d6ec5858ca07cdd81e4d"
+      "computedHash": "a83efe886adc9ee4032b039b6b3642b711a74652908ca94a5b6256f759c82a63"
     },
     "wp-rest-api": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-rest-api/SKILL.md",
-      "computedHash": "07d98b54fb41b6dccb0bae9f1a5b0d786776e9438ff5eba17d9dec7db89e5104"
+      "computedHash": "c52f53b0ba5e171fe8f0967a21ffa51a2466a1ebe0dccb65c3adc91545b45ae9"
     },
     "wp-wpcli-and-ops": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wp-wpcli-and-ops/SKILL.md",
-      "computedHash": "3e1d84ea3fefdbd6ee50f4ea90a41a8967b1e1c36dc2f6bdd1a0c3813fd1a5a6"
+      "computedHash": "5fb6302cce7d094a84a044d2e5f7d814e1606d648dd5d9cf9302f5cd6008537b"
     },
     "wpds": {
       "source": "wordpress/agent-skills",
       "sourceType": "github",
       "skillPath": "skills/wpds/SKILL.md",
-      "computedHash": "1a05f741c9a43026507c8c9641b2dbde4b4928a14038f97322c36ee8b1e88470"
+      "computedHash": "4759a50656e902bf725154827df39d9527fd46e5eb6544882f11433bf405d7bb"
     }
   }
 }
diff --git a/plugins/workflow-sdk/.claude/skills/migrating-to-workflow-sdk b/plugins/workflow-sdk/.claude/skills/migrating-to-workflow-sdk
new file mode 120000
index 00000000..576e7a66
--- /dev/null
+++ b/plugins/workflow-sdk/.claude/skills/migrating-to-workflow-sdk
@@ -0,0 +1 @@
+../../.agents/skills/migrating-to-workflow-sdk
\ No newline at end of file
diff --git a/plugins/workflow-sdk/.claude/skills/workflow b/plugins/workflow-sdk/.claude/skills/workflow
new file mode 120000
index 00000000..d5297629
--- /dev/null
+++ b/plugins/workflow-sdk/.claude/skills/workflow
@@ -0,0 +1 @@
+../../.agents/skills/workflow
\ No newline at end of file
diff --git a/plugins/workflow-sdk/.claude/skills/workflow-init b/plugins/workflow-sdk/.claude/skills/workflow-init
new file mode 120000
index 00000000..7a446193
--- /dev/null
+++ b/plugins/workflow-sdk/.claude/skills/workflow-init
@@ -0,0 +1 @@
+../../.agents/skills/workflow-init
\ No newline at end of file
diff --git a/plugins/workflow-sdk/skills-lock.json b/plugins/workflow-sdk/skills-lock.json
index 78bec7aa..614275dd 100644
--- a/plugins/workflow-sdk/skills-lock.json
+++ b/plugins/workflow-sdk/skills-lock.json
@@ -11,13 +11,13 @@
       "source": "vercel/workflow",
       "sourceType": "github",
       "skillPath": "skills/workflow/SKILL.md",
-      "computedHash": "69abde8decfadc960cae3f8df4a6738ca4ff04bf57887665127be51db3b10834"
+      "computedHash": "eae859f624c59eeb67ddb91e8f1bc85793f463bc3ff4c854cb53dd3a72fd01a5"
     },
     "workflow-init": {
       "source": "vercel/workflow",
       "sourceType": "github",
       "skillPath": "skills/workflow-init/SKILL.md",
-      "computedHash": "16958b6fce870b067a557d78e17fd7bb3fb206f29def2db35fb4c2f6f01e497b"
+      "computedHash": "e74ed0468589670865a7dc1dcf4f8cd21c3dce164e5caa66d74c5800d70dfe68"
     }
   }
 }