@netlify/agent-runner-cli 2.16.0-server.2 → 2.16.0

package/dist/skills/netlify-identity/references/advanced-patterns.md

@@ -0,0 +1,104 @@
+# Advanced Identity Patterns
+
+## Password Recovery
+
+Three-step flow: request recovery email, handle the callback, then set a new password.
+
+```typescript
+import { requestPasswordRecovery, handleAuthCallback, updateUser, AuthError } from '@netlify/identity'
+
+// Step 1: Send recovery email
+async function handleForgotPassword(email: string) {
+  try {
+    await requestPasswordRecovery(email)
+    showSuccess('Check your email for a password reset link.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+
+// Step 2: handleAuthCallback() returns { type: 'recovery', user } — show password reset form
+// (See the handleAuthCallback switch in SKILL.md)
+
+// Step 3: Set new password
+async function handlePasswordReset(newPassword: string) {
+  try {
+    await updateUser({ password: newPassword })
+    showSuccess('Password updated.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
+
+The recovery callback fires a `'recovery'` auth event, not `'login'`. The user is authenticated but should be prompted to set a new password before navigating away.
+
+## Invite Acceptance
+
+When a user clicks an invite link, `handleAuthCallback()` returns `{ type: 'invite', user: null, token }`. Use the token to accept the invite and set a password.
+
+```typescript
+import { acceptInvite, AuthError } from '@netlify/identity'
+
+async function handleAcceptInvite(token: string, password: string) {
+  try {
+    const user = await acceptInvite(token, password)
+    showSuccess(`Welcome, ${user.email}! Your account is ready.`)
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
+
+## Email Change
+
+When a user verifies an email change, `handleAuthCallback()` returns `{ type: 'email_change', user }` with the change already applied — the returned `user` carries the new email. The user must be logged in when clicking the verification link.
+
+Like recovery (and unlike invite acceptance), there is no token to consume and no follow-up call — `handleAuthCallback()` does the work. Handle it in the `handleAuthCallback()` switch (see SKILL.md) and confirm the new address.
+
+```typescript
+// In the handleAuthCallback() switch (see SKILL.md):
+case 'email_change':
+  showSuccess(`Email updated to ${result.user?.email}`)
+  break
+```
+
+If you process the verification token yourself instead of letting `handleAuthCallback()` read the URL hash, call `verifyEmailChange(token)` directly — it applies the change and returns the updated user.
+
+## Session Hydration
+
+`hydrateSession()` bridges server-set cookies to the browser session. Call it on page load when using server-side login (e.g., login inside a Netlify Function followed by a redirect).
+
+```typescript
+import { hydrateSession } from '@netlify/identity'
+
+const user = await hydrateSession()
+if (user) {
+  // Browser session is now in sync with server-set cookies
+}
+```
+
+`getUser()` auto-hydrates from the `nf_jwt` cookie if no browser session exists, so explicit `hydrateSession()` is only needed when you want to restore the full session (including token refresh timers) after a server-side login.
+
+## SSR Integration Patterns
+
+For SSR frameworks, the recommended pattern is:
+
+- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
+- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
+
+Browser-side auth mutations set the `nf_jwt` cookie and localStorage, and emit `onAuthChange` events. The server reads the cookie on the next request.
+
+The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these require the Netlify Functions runtime to set cookies. After a server-side mutation, use a full page navigation so the browser sends the new cookie.
+
+Always use `window.location.href` (not framework router navigation) after server-side auth mutations in Next.js, TanStack Start, and SvelteKit. Remix `redirect()` is safe because Remix actions return real HTTP responses.
+
+## Full API Reference
+
+For the complete API reference — all function signatures, type definitions, OAuth helpers, admin operations, session management, auth events, and framework-specific examples — read the package README:
+
+```
+node_modules/@netlify/identity/README.md
+```
+
+The README is shipped with the npm package and is always in sync with the installed version.

package/dist/skills/netlify-identity/references/authorization-and-sessions.md

@@ -0,0 +1,24 @@
+# Netlify Identity — authorization and session gotchas
+
+Where role-based access actually gets enforced, and why a role change doesn't take effect immediately.
+
+## Admin operations run only in the Functions runtime
+
+Identity's admin API — creating users, updating a user's roles or metadata, deleting users (the `admin.*` operations) — requires a privileged admin token that is available **only in the Netlify Functions runtime**. It is not exposed to browser code and is not available in Edge Functions. Do all role assignment and user administration from inside a modern v2 Function (or an Identity event function), never from the client and never from an edge function. A "promote this user to admin" button in the UI must call a Function endpoint that performs the change server-side — it cannot call the admin API directly from the browser.
+
+You don't configure or read the admin token yourself — the Netlify Functions runtime provides it automatically to `admin.*` calls made inside a Function, so there is no env var to set and no `Netlify.env.get(...)` to call for it. Run the `admin.*` operations server-side in a Function; never hardcode an admin token, ship one in the client bundle, or expose the admin operations to the browser. Exposing an admin capability client-side would let any visitor grant themselves the `admin` role.
+
+## Redirect gating only covers CDN document requests
+
+`conditions = { Role = [...] }` redirects are enforced by the CDN **only when it serves a document (navigation) request** — a fresh HTTP request for the path. They are a coarse page-level perimeter, not real authorization:
+
+- **SPA client-side navigation bypasses them.** When a client-side router (React, Vue, SvelteKit, etc.) navigates to `/admin` in the browser, no new document request reaches the CDN, so the redirect rule never runs and the route renders regardless of the user's role.
+- **Anything in the client bundle is downloadable by anyone.** Role-gated content compiled into the JavaScript bundle ships to every visitor who can load the page; hiding a component behind a client-side role check does not protect the data inside it.
+
+So use redirect gating for coarse routing only. Enforce anything sensitive **server-side on every request** — a Netlify Function (or the API it calls) that resolves the user with `getUser()` and checks the server-controlled `app_metadata.roles` — never a client-side route guard or a hidden UI element as the only gate.
+
+## Role changes don't affect live sessions until the JWT refreshes
+
+Roles are baked into the `nf_jwt` when the token is issued, and that JWT stays valid until it expires (about an hour). Changing a user's roles — via the dashboard, the admin API, or an Identity event function — does **not** update tokens already held by signed-in users. A user you just promoted keeps seeing the old view, and a user whose role you just revoked keeps their access, until their token refreshes (`AUTH_EVENTS.TOKEN_REFRESH`) or they log out and log back in. Both redirect `Role` conditions and function-side `app_metadata.roles` checks read the current token, so both see the stale roles until then.
+
+Don't expect a role change to take effect mid-session. When it needs to apply right away, direct the user to log out and back in (or otherwise refresh their token) so a new `nf_jwt` carrying the updated roles is issued.

package/dist/skills/netlify-server@netlifyserver/SKILL.md

@@ -9,20 +9,17 @@ A Netlify Server is one long-running Node.js process deployed alongside your sit
 
 ## When to use this skill: explicit request only
 
-Netlify Server is in Early Access. The rule for choosing it is strict:
+Netlify Server is an experimental primitive. The rule for choosing it is strict:
 
 - ONLY build with a Netlify Server when the prompt **explicitly requests a "Netlify Server"** by name (for example "build this as a Netlify Server" or "use the Netlify Server primitive").
 - If the prompt does not name it, discard this skill entirely, even when the request mentions Express, Hono, WebSockets, servers in general, or would otherwise seem like a good fit. In those cases use **Netlify Functions** (see the `netlify-functions` skill) and the other platform primitives as usual.
 - NEVER migrate an existing site's functions to a Netlify Server unless explicitly asked to.
 
-Once a Netlify Server has been explicitly requested:
-
-- Start without a template. Every template is a full-stack framework whose catch-all function takes the requests before the server, so the server would never receive traffic.
-- Implement all API routes inside the server app. Create files in `netlify/functions/` only for scheduled jobs (see below), never for endpoints.
+Once a Netlify Server has been explicitly requested: implement all API routes inside the server app, and do NOT create files in `netlify/functions/` alongside it.
 
 ## Quick start
 
-Create exactly one entrypoint at `netlify/server/index.mjs`.
+Create exactly one entrypoint at `netlify/server/index.mjs`. Any Node.js server works. It MUST listen on `process.env.PORT`.
 
 Express:
 
@@ -52,87 +49,49 @@ app.get('/api/hello', (c) => c.json({ hello: 'world' }))
 export default app
 ```
 
-What the entry file exports decides how Netlify runs it:
-
-- **An `http.Server`**, such as `http.createServer(app)`: requests go to that server. WebSocket libraries attached to it (`ws`, Socket.IO) work.
-- **An object with a `fetch` method**, such as a Hono app: called for each request.
-- **An Express app**, or a function with 3 or more parameters: hosted in an HTTP server Netlify creates. WebSocket upgrades get a `501`, so export `http.createServer(app)` instead when you need them.
-- **Any other function**: called as a handler `(request, context) => Response`, the same signature as a Netlify Function. A plain Node.js `(req, res)` listener lands here too and breaks; wrap it in `http.createServer()`.
-- **Anything else, or no default export**: Netlify waits for your code to start a server with `listen` on `process.env.PORT`, the way the framework's documentation shows. It must be listening within 10 seconds.
-
-A handler or `fetch` app accepts WebSockets with `upgradeWebSocket(request)` from `@netlify/server`, which returns `{ socket, response }`; return `response` from the handler.
-
 Declare dependencies in `package.json` as usual. Deploy is the normal site deploy; nothing extra to configure. The build log confirms detection with the line `Netlify Server detected at netlify/server/index.mjs`.
 
 ## Rules
 
 - **One entrypoint only.** `netlify/server/` must contain exactly one of `index.mjs`, `index.js`, `index.ts`, or `index.mts`. Two entry files fail the build. Prefer `index.mjs` with ESM syntax; split the rest of the server into modules that the entrypoint imports.
-- **A server that calls `listen` uses `process.env.PORT`.** It is set before your code is imported. Do not hardcode a port.
-- **Node.js 24 or later.** The server runs on the build's Node.js version, and the deploy fails on anything earlier.
+- **Listen on `process.env.PORT`.** It is set before your code is imported. Do not hardcode a port.
 - **Do not daemonize, fork, or spawn long-lived child processes.** One process serves the traffic.
 - Environment variables work as usual via `process.env`.
 - When adding npm modules, ensure `node_modules` is in `.gitignore`.
 
 ## Routing and static files
 
-By default, the server receives every request that nothing else in the project handles. Requests are handled in this order:
-
-1. Edge Functions.
-2. Redirect and rewrite rules.
-3. Static files in the publish directory.
-4. Netlify Functions, on the paths they're configured for.
-5. The server, for everything else (or only the paths it's configured for, see below).
+The server receives every request that is not served as a static file:
 
-Rules:
-
-- Files in the publish directory win over the server for matching paths, even on paths the server claims. Use the publish directory for assets like images, fonts, or a favicon.
+- Files in the publish directory win over the server for matching paths (`preferStatic`). Use the publish directory for assets like images, fonts, or a favicon.
 - Do NOT put an `index.html` in the publish directory if the server should render `/`. A static `index.html` shadows the server's root route.
-- A rewrite rule that matches every path, such as a single-page app's `/* /index.html 200`, sends requests to its destination instead of the server. Limit such rules to the paths the frontend handles.
-- Full-stack frameworks (Next.js, Nuxt, SvelteKit, Astro, TanStack Start) usually deploy a Netlify Function on `/*` that handles every request not served by a static file, covering both page rendering and the framework's API routes. Like the rewrite above, it takes those requests before the server does, so the server never receives any. If a Netlify Server is explicitly required, do not use a full-stack framework. Otherwise, put server code in the framework's own server routes.
-- There is no path prefix: the server sees its requests with their original paths.
-
-To have the server handle only some paths, set `path` (defaults to `/*`) and `excludedPath`, using the same syntax as function paths. Export them as `config` from the entry file, or set them in a `[server]` section in `netlify.toml`:
-
-```javascript
-export const config = {
-  path: '/api/*',
-  excludedPath: ['/api/legacy/*'],
-}
-```
+- There is no path prefix: the server sees `/`, `/api/anything`, and everything else, with the original paths.
 
 ## Lifecycle: scale to zero
 
 This is the most important mental model for building correctly:
 
-- After 5 minutes with no requests, the server is shut down. The next request starts a fresh process (a cold start).
+- After a period with no traffic, the server is shut down. The next request starts a fresh process (a cold start).
 - **All process memory is lost on every scale-to-zero, deploy, and platform maintenance event.** In-memory caches are fine as caches; they are NEVER storage. Anything that must survive belongs in Netlify Blobs or Netlify Database (see the `general-database` skill to choose).
-- Netlify can run several instances of the server at once (up to 3; 1 on Free and Personal plans). Each has its own memory and its own WebSocket connections; nothing in memory is shared between them.
-- In-flight requests and open WebSocket or Server-Sent Events connections are never cut off by the idle shutdown; while any are open, the instance stays running.
-- The server must send a response's status and headers within 20 seconds, or the request fails with a `502`. Stream slow responses, such as AI output, or respond right away and finish with `waitUntil`.
+- In-flight requests are never cut off by the idle shutdown.
 - Background work that outlives the request that triggered it (for example, responding early and then finishing a task) MUST be registered with `getContext().waitUntil(promise)`. Registered work keeps the process alive until the promise settles; unregistered work may be reclaimed the moment no requests are active.
-- Never keep the server alive on purpose: no self-pings, no timer that calls the server, no `waitUntil` chain that schedules more work to stay running, and no `scale.min` above `0` (during Early Access a deploy that sets it fails). Scale to zero is the design. If the user asks for an always-on server, explain this and build without it.
-- Scheduled or recurring work (cron, nightly cleanup, periodic sync) goes in a scheduled function (see the `netlify-functions` skill) that calls a server route. Never use `setInterval` or other timers meant to outlive a request.
 - `waitUntil` extends the idle lifetime, but deploys and platform maintenance still stop the process with only a short grace window. Keep background tasks short (seconds, not minutes), and persist anything critical before responding. For genuinely long jobs, persist a job record and process it in resumable increments across requests.
 
-Graceful shutdown hook (optional): register it with `onShutdown` from `@netlify/server`. It runs as soon as the instance starts stopping and receives `drained`, a promise that resolves once in-flight requests and `waitUntil` work have finished. Stop background work and close WebSockets right away, then `await drained` before releasing what that work still uses. Apps that already listen for `SIGTERM` keep working.
+Graceful shutdown hook (optional): export a `shutdown` function from the entrypoint; it is called before the process is stopped. Keep it fast (a few seconds), for example flushing a buffer to Blobs. For Express-style apps that call `listen`, you can also listen for `SIGTERM` directly.
 
 ```javascript
-import { onShutdown } from '@netlify/server'
-
-onShutdown(async ({ drained }) => {
-  wss.close()
-  await drained
-  await pool.end()
-})
+export const shutdown = async () => {
+  await flushPendingWrites()
+}
 ```
 
 ## Request context: geolocation, cookies, site metadata
 
-Inside request handling, get the Netlify request context with `getContext` from the `@netlify/server` package (add it to `package.json`):
+Inside request handling, get the Netlify request context with `getContext` from the `@netlify/functions` package (add it to `package.json`):
 
 ```javascript
 import express from 'express'
-import { getContext } from '@netlify/server'
+import { getContext } from '@netlify/functions'
 
 const app = express()
 
@@ -148,7 +107,6 @@ Rules:
 
 - ONLY call `getContext()` while handling a request (inside a route handler, middleware, or code awaited from one). It throws outside a request.
 - Works with every server form, including WebSocket upgrade handling.
-- Anything started inside a request (a `setInterval`, a lazily started background loop, a client that creates its own timers, WebSocket message handlers) keeps that request's context for its whole life, so `getContext()` there returns a stale request instead of throwing. Start long-lived work outside request handling, and never read per-request context from it.
 
 ### SSO user: `context.user`
 
@@ -168,62 +126,52 @@ See the [changelog post](https://www.netlify.com/changelog/2026-10-07-context-us
 
 The AI Gateway works with zero configuration: provider credentials and base URLs (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, and equivalents for other providers) are injected into `process.env` automatically. See the `netlify-ai-gateway` skill for supported models and usage.
 
-AI Gateway, Netlify Blobs, and Netlify Database clients can be created once at module scope and reused: the platform keeps their credentials current. One exception: `NETLIFY_PURGE_API_TOKEN` expires after 15 minutes, so read it from `process.env` each time you call the purge API and never store it in a module-level variable.
+One rule specific to servers: **construct AI SDK clients inside request handling, never at module scope.** Credentials are injected per request, so they do not exist when the module is first imported.
 
 ```javascript
 import OpenAI from 'openai'
 
-const client = new OpenAI()
-
 app.post('/api/chat', async (req, res) => {
+  const client = new OpenAI() // created per request: credentials are available here
   // ...
 })
 ```
 
 ## WebSockets
 
-WebSockets work for servers that handle HTTP upgrades. Create the HTTP server, attach the WebSocket server to it, and export it. Starting it with `server.listen(process.env.PORT)` instead of exporting it works too.
+WebSockets work for servers that handle HTTP upgrades (the `listen` form). Attach the WebSocket server to the same HTTP server:
 
 ```javascript
 // netlify/server/index.mjs
-import { createServer } from 'node:http'
 import express from 'express'
 import { WebSocketServer } from 'ws'
 
 const app = express()
-const server = createServer(app)
-const wss = new WebSocketServer({ server, path: '/ws' })
-
-wss.on('connection', (ws) => {
-  ws.send('connected')
+const server = app.listen(process.env.PORT)
+const wss = new WebSocketServer({ noServer: true })
+
+server.on('upgrade', (req, socket, head) => {
+  if (req.url !== '/ws') {
+    socket.destroy()
+    return
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => {
+    ws.send('connected')
+  })
 })
-
-export default server
 ```
 
 Rules for WebSocket clients you generate:
 
 - ALWAYS implement automatic reconnection with backoff in the browser client. The platform may terminate long-lived connections periodically; a reconnecting client makes this invisible to users.
 - Do not rely on a socket staying open indefinitely, and do not keep client state only on the server side of a socket: rebuild the needed state on reconnect.
-- Clients can be connected to different instances, and each instance only sees its own sockets. Keep state every client must see, such as chat history, in Netlify Database or Blobs.
-
-## Fetching user-supplied URLs
-
-An endpoint that fetches a URL taken from the request (link previews, webhook testers, image proxies) runs inside Netlify's network, so it must:
-
-- Accept only `http:` and `https:` URLs.
-- Resolve the hostname and refuse loopback, private, link-local, and unique-local addresses, including `169.254.169.254`.
-- Follow redirects manually (`redirect: 'manual'`) and check every hop the same way.
-- Return only what the feature needs (extracted fields, a capped body), never forward the caller's method, headers, or body. A generic `/proxy?url=` endpoint is an open relay; don't build one.
 
 ## Common mistakes
 
 - Treating process memory as a database. It is wiped on every cold start. Use Blobs or Database.
 - Hardcoding a port or defaulting to `3000` without reading `process.env.PORT` first.
 - Adding an `index.html` to the publish directory that shadows the server's `/` route.
-- Creating `netlify/functions/` endpoints alongside the server. Put API routes in the server app; use functions only for scheduled jobs.
+- Creating `netlify/functions/` endpoints alongside the server. Put API routes in the server app.
 - Two entry files in `netlify/server/` (for example both `index.mjs` and `index.ts`). Keep one.
 - Fire-and-forget background jobs without `getContext().waitUntil(promise)`. Unregistered work may be reclaimed mid-flight; registered work should still be short and non-critical.
-- Calling `getContext()` at module scope. It only works while handling a request.
-- Storing `NETLIFY_PURGE_API_TOKEN` in a module-level variable. Read it when you call the purge API.
-- Keeping the server warm with self-pings or timers, or running scheduled work with `setInterval`. Use a scheduled function that calls a server route.
+- Constructing AI SDK clients (or calling `getContext()`) at module scope. Per-request state does not exist at import time.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "2.16.0-server.2",
+  "version": "2.16.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -43,6 +43,7 @@
     "test:integration:claude": "vitest run test/integration/claude.test.ts",
     "test:integration:gemini": "vitest run test/integration/gemini.test.ts",
     "test:integration:opencode": "vitest run test/integration/opencode.test.ts",
+    "test:integration:antigravity": "vitest run test/integration/antigravity.test.ts",
     "test:integration:muse": "vitest run test/integration/muse.test.ts",
     "test:integration:skill-invocation": "vitest run test/integration/skill-invocation.test.ts",
     "check:types": "tsc --noEmit",

package/scripts/build-skills.js

@@ -1,4 +1,5 @@
-import { appendFile, cp, mkdir, readdir, readFile, rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import process from 'node:process'
@@ -8,34 +9,55 @@ const localSkillsDir = new URL('../src/skills/', import.meta.url)
 const sharedPackagePath = createRequire(import.meta.url).resolve('@netlify/skills/package.json')
 const sharedSkillsDir = path.join(path.dirname(sharedPackagePath), 'skills')
 export const bundledSkillsDir = fileURLToPath(new URL('../dist/skills/', import.meta.url))
-const selectedSharedSkills = [
-  { name: 'netlify-access-control' },
-  {
-    name: 'netlify-forms',
-    instructions: new URL('../src/skill-instructions/netlify-forms.md', import.meta.url),
-    assets: new URL('../src/skill-assets/netlify-forms/', import.meta.url),
-  },
-  {
-    name: 'netlify-image-cdn',
-    instructions: new URL('../src/skill-instructions/netlify-image-cdn.md', import.meta.url),
-  },
-]
+const skillOverridesDir = fileURLToPath(new URL('../src/skill-overrides/', import.meta.url))
+export const selectedSharedSkills = ['netlify-access-control', 'netlify-forms', 'netlify-image-cdn', 'netlify-identity']
+
+const readOptionalFile = async (filePath) => {
+  try {
+    return await readFile(filePath, 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+export const applySkillReplacements = (content, replacements) => {
+  let result = content
+  for (const { from, to } of replacements) {
+    if (!from || result.split(from).length !== 2) {
+      throw new Error(`Expected exactly one occurrence of shared skill text: ${JSON.stringify(from)}`)
+    }
+    result = result.replace(from, () => to)
+  }
+  return result
+}
 
 export const buildSkills = async (targetDir = bundledSkillsDir) => {
   await rm(targetDir, { recursive: true, force: true })
   await cp(localSkillsDir, targetDir, { recursive: true })
 
-  for (const { name, instructions, assets } of selectedSharedSkills) {
+  for (const name of selectedSharedSkills) {
     await cp(path.join(sharedSkillsDir, name), path.join(targetDir, name), {
       recursive: true,
       force: false,
       errorOnExist: true,
     })
-    if (instructions) {
-      await appendFile(path.join(targetDir, name, 'SKILL.md'), `\n\n${await readFile(instructions, 'utf8')}`)
+    const overrideDir = path.join(skillOverridesDir, name)
+    const replacements = await readOptionalFile(path.join(overrideDir, 'replacements.json'))
+    const instructions = await readOptionalFile(path.join(overrideDir, 'instructions.md'))
+    if (instructions !== undefined || replacements !== undefined) {
+      const skillPath = path.join(targetDir, name, 'SKILL.md')
+      let content = await readFile(skillPath, 'utf8')
+      if (replacements !== undefined) {
+        content = applySkillReplacements(content, JSON.parse(replacements))
+      }
+      if (instructions !== undefined) {
+        content += `\n\n${instructions}`
+      }
+      await writeFile(skillPath, content)
     }
-    if (assets) {
-      const assetsDir = fileURLToPath(assets)
+    const assetsDir = path.join(overrideDir, 'assets')
+    if (existsSync(assetsDir)) {
       for (const entry of await readdir(assetsDir, { recursive: true, withFileTypes: true })) {
         if (!entry.isFile()) continue
         const source = path.join(entry.parentPath, entry.name)

package/dist/skills/general-backend@backend/SKILL.md

@@ -1,78 +0,0 @@
----
-name: general-backend
-description: Use this skill whenever the task involves server-side code — API endpoints, backend logic, request handlers, WebSockets, server-side AI calls, auth checks, or any code that must run on a server rather than in the browser. Covers Netlify Server, Netlify Functions, Edge Functions, and full-stack framework server routes.
----
-
-# Server-side code on Netlify
-
-Where server-side code goes depends on the project. Work out which case applies before writing code, and for a
-new project, before scaffolding a template.
-
-## New project that needs a Netlify Server: no template
-
-The create-mode templates are built on a full-stack framework that deploys its server-side rendering as a Netlify
-Function on every path, so a Netlify Server added to a template project never receives requests. If the project
-needs a Netlify Server, don't scaffold a template. A new project needs one when it has any request-driven backend
-code: API endpoints, data saved and read through the backend, WebSockets, server-side AI calls, or an HTTP server
-framework such as Express, Hono, or Fastify.
-
-A site with no backend code (static pages, a marketing or content site, a client-only tool) needs neither a server
-nor functions. Use the templates as usual for it.
-
-## Project with a full-stack framework: use its server routes
-
-Full-stack frameworks (such as TanStack Start, Next.js, Astro, SvelteKit, Remix, Nuxt) build
-their own server code into Netlify Functions at deploy time. In these projects, put request handling in the
-framework's server routes or server functions instead of adding a Netlify Server. Call Netlify Database, Blobs, and
-the AI Gateway from those routes. Use Netlify Functions alongside them only for the cases listed under "Only when
-Server can't" below.
-
-HTTP server frameworks such as Express, Hono, Fastify, and Koa are different: nothing deploys them for you, so they
-run as a Netlify Server, covered next.
-
-## Otherwise: Netlify Server
-
-**Netlify Server** runs one long-running Node.js process (Express, Hono, Fastify, or plain `node:http`) from
-`netlify/server/index.mjs`. Put every request-driven piece of backend code in it:
-
-- API endpoints and route handlers
-- Server-rendered pages and form handling in your own routes
-- WebSockets and streaming responses
-- Calls to the Netlify AI Gateway, Netlify Database, and Netlify Blobs
-- Short work that continues after the response (seconds, such as sending an email), registered with `waitUntil`
-- Auth checks, webhooks from third-party services, proxies to external APIs
-
-Don't pick Functions just because the task is small or looks like a single endpoint.
-
-See the **netlify-server** skill for complete setup instructions and usage examples.
-
-## Only when Server can't: Netlify Functions
-
-Use **Netlify Functions** alongside the server only for:
-
-- **Scheduled functions**: work that runs on a cron schedule, with no incoming request.
-- **Event handlers**: code triggered by platform events, such as Netlify Forms submissions, Netlify Identity events
-  (signup, login, validate), or deploy events.
-- **Background functions**: jobs that can run longer than about a minute and must not be cut off midway, such as
-  generating a report or processing an upload (up to 15 minutes). When a server instance is replaced by a deploy or
-  scaling event, its background work gets only 90 seconds to finish. The server enqueues the job by calling the
-  background function and returns right away.
-
-Scheduled functions and event handlers run without an incoming request, which a server can't do, and background
-functions aren't cut off when a server instance is replaced. Everything else stays in the server, including the
-endpoints these functions talk to.
-
-See the **netlify-functions** skill for complete setup instructions and usage examples.
-
-## Request and response changes at the edge: Edge Functions
-
-Use **Edge Functions** for logic that runs on every request before it reaches the server or the site: rewrites and
-redirects based on geolocation or cookies, A/B tests, header changes, or lightweight auth checks. They run in Deno
-close to visitors and don't replace the server for application logic.
-
-See the **netlify-edge-functions** skill for setup instructions.
-
-## Existing projects
-
-If an existing project already serves its backend from `netlify/functions/`, keep using that for changes to it.
-Don't migrate an existing backend to a Netlify Server unless asked.