Update to Netlify

SKILL.md line diff

--- before
+++ after
@@ -1,247 +1,191 @@
 ---
 name: netlify-deploy
-description: Deploy projects to Netlify with the Netlify CLI. Use when the user wants to link a repo, validate deploy settings, run a deploy, or choose between preview and production flows.
+description: Create, configure, and manage Netlify deploys from code — reach for this when setting up Git continuous deployment, running netlify deploy or netlify deploy --prod from the CLI, writing netlify.toml deploy contexts, adding a Deploy to Netlify button, wiring build hooks, configuring Deploy Previews or branch deploys, locking or skipping deploys, fixing a failed or secrets-scanning deploy, or when someone asks to "deploy my site", "set up preview deploys", "add per-branch build config", or "add a deploy button to my README".
 ---
 
-# Netlify Deployment Skill
+# Netlify deploy
 
-Deploy web projects to Netlify using the Netlify CLI with intelligent detection of project configuration and deployment context.
-
-## Overview
-
-This skill automates Netlify deployments by:
-- Verifying Netlify CLI authentication
-- Detecting project configuration and framework
-- Linking to existing sites or creating new ones
-- Deploying to production or preview environments
-
-## Prerequisites
-
-- **Netlify CLI**: Installed via npx (no global install required)
-- **Authentication**: Netlify account with active login session
-- **Project**: Valid web project in current directory
-- When sandboxing blocks the deployment network calls, rerun with `sandbox_permissions=require_escalated`.
-- The deployment might take a few minutes. Use appropriate timeout values.
-
-## Authentication Pattern
-
-The skill uses the **pre-authenticated Netlify CLI** approach:
-
-1. Check authentication status with `npx netlify status`
-2. If not authenticated, guide user through `npx netlify login`
-3. Fail gracefully if authentication cannot be established
-
-Authentication uses either:
-- **Browser-based OAuth** (primary): `netlify login` opens browser for authentication
-- **API Key** (alternative): Set `NETLIFY_AUTH_TOKEN` environment variable
-
-## Workflow
-
-### 1. Verify Netlify CLI Authentication
-
-Check if the user is logged into Netlify:
+## Modern CLI
 
 ```bash
-npx netlify status
+netlify deploy              # manual draft deploy (no CI)
+netlify deploy --prod       # deploy straight to production
+netlify create              # new project from a natural-language prompt
+netlify deploy --allow-anonymous   # temp project, claim within 1 hour
+npm update -g netlify-cli   # skew protection needs 23.11.0+
 ```
 
-**Expected output patterns**:
-- ✅ Authenticated: Shows logged-in user email and site link status
-- ❌ Not authenticated: "Not logged into any site" or authentication error
+A deploy is a versioned, **atomic** snapshot: Netlify uploads only changed files and switches the live site only after all files land — the site is never in an inconsistent state. A deploy can be a preview or a production version served at your primary domain.
 
-**If not authenticated**, guide the user:
+**Continuous deployment vs manual deploys:** Deploy with Git and the Netlify CLI support continuous deployment — a push auto-triggers a build. Drag and drop and the API create one-off manual deploys. Manual deploys (`netlify deploy`) do **not** run a build command; drag-and-drop while logged in is the only exception (framework auto-detected).
 
-```bash
-npx netlify login
-```
-
-This opens a browser window for OAuth authentication. Wait for user to complete login, then verify with `netlify status` again.
-
-**Alternative: API Key authentication**
+**⚠ When linking or creating a site, add `.netlify` to `.gitignore`.** Every linking path writes `.netlify/state.json`, which must not be committed.
 
-If browser authentication isn't available, users can set:
+## Ways to create a deploy
 
-```bash
-export NETLIFY_AUTH_TOKEN=your_token_here
-```
+- **Git CD** — connect a repo; Netlify builds and deploys on every push (OAuth2 or the Netlify GitHub App). This is the default path.
+- **CLI** — `netlify create`, `netlify deploy`, `netlify deploy --prod`.
+- **Drag and drop** — https://app.netlify.com/drop. Logged in: builds if needed. Not logged in: publishes files as-is.
+- **API** — create deploys via file digest or ZIP (one-off manual).
+- **Deploy to Netlify button** — one-click from a public template repo.
+- **Build hooks** — unique URLs that trigger builds. (Deploys from build hooks are treated as trusted and bypass the deploy request policy.)
+- **AI agents** — Agent Runners (Claude Code, OpenAI Codex, Google Gemini) from the dashboard; every file-changing run auto-generates a Deploy Preview at `agent-<runID>--<site>.netlify.app`. The inline preview shown next to the prompt is the same Deploy Preview available at that URL.
+- **Zapier / n8n** — automation integrations.
 
-Tokens can be generated at: https://app.netlify.com/user/applications#personal-access-tokens
+Not sure which path? The Deploy Navigator gives personalized recommendations: https://docs.netlify.com/start/choose-your-path#deploy-navigator (also embedded on the create-deploys page as "Not sure where to start?").
 
-### 2. Detect Site Link Status
+## netlify.toml deploy contexts
 
-From `netlify status` output, determine:
-- **Linked**: Site already connected to Netlify (shows site name/URL)
-- **Not linked**: Need to link or create site
+At the repo root. File config overrides UI settings. Five predefined contexts: `production`, `deploy-preview`, `branch-deploy`, `preview-server`, `dev`. Branch names also work as custom contexts; more specific contexts override general ones.
 
-### 3. Link to Existing Site or Create New
+```toml
+[context.production]
+  command = "make production"
+  [context.production.environment]
+    ACCESS_TOKEN = "super secret"
+  [[context.production.plugins]]        # plugins REQUIRE double brackets
+    package = "@netlify/plugin-sitemap"
 
-**If already linked** → Skip to step 4
+[context.deploy-preview.environment]
+  ACCESS_TOKEN = "not so secret"
 
-**If not linked**, attempt to link by Git remote:
+[context.branch-deploy]
+  command = "make staging"
 
-```bash
-# Check if project is Git-based
-git remote show origin
+[context.dev.environment]
+  NODE_ENV = "development"
 
-# If Git-based, extract remote URL
-# Format: https://github.com/username/repo or git@github.com:username/repo.git
-
-# Try to link by Git remote
-npx netlify link --git-remote-url <REMOTE_URL>
-```
-
-**If link fails** (site doesn't exist on Netlify):
-
-```bash
-# Create new site interactively
-npx netlify init
+[context."features/branch"]             # quote slashed branch names
+  command = "gulp"
 ```
 
-This guides user through:
-1. Choosing team/account
-2. Setting site name
-3. Configuring build settings
-4. Creating netlify.toml if needed
+**⚠ Environment variables set in `netlify.toml` are NOT available to the deploy environment** — set them via UI/CLI/API. `netlify.toml` is committed, so keep sensitive values out of it; use per-context env vars via UI/CLI/API instead.
 
-### 4. Verify Dependencies
+See `references/netlify-toml.md` for the full context precedence rules and `references/deployment-patterns.md` for context strategy.
 
-Before deploying, ensure project dependencies are installed:
+## Deploy Previews & branch deploys
 
-```bash
-# For npm projects
-npm install
-
-# For other package managers, detect and use appropriate command
-# yarn install, pnpm install, etc.
-```
+- **Deploy Previews** auto-build for PRs/MRs (GitHub, GitLab, Bitbucket, Azure DevOps, Cursor Origin) and agent runs. The base branch must be a production branch or a branch-deploy-enabled branch. URL: `deploy-preview-<num>--<site>.netlify.app`. While the first deploy is pending the URL returns `Not Found`.
+- **Branch deploys** require setup: Project configuration > Developer settings > Continuous deployment > Branches and deploy contexts > Configure. Enable specific branches (prefix wildcard `features/*` supported) or **All** new branches. URL: `<branch>--<site>.netlify.app`.
+- A branch-deploy branch with an open PR yields **both** a Deploy Preview and a branch deploy.
+- **Entry path:** put `@netlify /some/path` in the PR/MR description, then push a new commit to regenerate. Once set in the PR, you can't change it in the Netlify Drawer.
+- **Skip a deploy:** `[skip ci]` or `[skip netlify]` — in the PR/MR **title** to skip the Deploy Preview; **anywhere in the commit message** to skip a branch/production deploy. Next unmarked commit deploys all skipped changes.
 
-### 5. Deploy to Netlify
+## Locking, skipping, and manual production deploys
 
-Choose deployment type based on context:
+- **Lock** (disable auto publishing): Deploys list > **Lock to stop auto publishing**. New deploys still build but are not published. Unlock to resume.
+- **⚠ Manual `netlify deploy --prod` on a Git-CD site:** the next push to the production branch silently replaces your hand-shipped deploy. Warn the user; lock the published deploy if it must stay live.
 
-**Preview/Draft Deploy** (default for existing sites):
+## Managing deploys
 
-```bash
-npx netlify deploy
-```
+- **Find:** Deploys tab (Developer or Team Owner); search by deploy ID or branch name; filter by time frame, deploy context, and status.
+- **Cancel:** on the in-progress deploy's detail page, **Cancel deploy** > **Yes, cancel deploy**.
+- **Retry:** builds from the branch HEAD (optionally clearing cache) — if HEAD moved past the original deploy SHA, it still builds from HEAD.
+- **Download:** on a successful deploy's detail page — a single file via **Deploy file browser**, or all files as a ZIP via the header **Download** > **Download ready**.
+- **Delete:** Developer or Team Owner only. You cannot delete the deploy most recently published to the site's main URL, or one still in progress. Deletion is permanent and does not reduce team costs or preserve build minutes.
 
-This creates a deploy preview with a unique URL for testing.
+## Deploy to Netlify button
 
-**Production Deploy** (for new sites or explicit production deployments):
+Template code must be in a **public** repo on **GitHub.com or GitLab.com**.
 
-```bash
-npx netlify deploy --prod
+Markdown:
+```md
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify/netlify-statuskit)
 ```
 
-This deploys to the live production URL.
+URL variants (base link `https://app.netlify.com/start/deploy`):
+```txt
+# require/pre-fill env vars (hash, client-side only; values may be null)
+...?repository=<repo>#SECRET_TOKEN=specialuniquevalue&CUSTOM_LOGO=
 
-**Deployment process**:
-1. CLI detects build settings (from netlify.toml or prompts user)
-2. Builds the project locally
-3. Uploads built assets to Netlify
-4. Returns deployment URL
+# monorepo base dir (whole repo cloned, builds from blog/)
+...?repository=<repo>&base=blog
 
-### 6. Report Results
+# clone only a subdirectory
+...?repository=<repo>&create_from_path=examples/hello
 
-After deployment, report to user:
-- **Deploy URL**: Unique URL for this deployment
-- **Site URL**: Production URL (if production deploy)
-- **Deploy logs**: Link to Netlify dashboard for logs
-- **Next steps**: Suggest `netlify open` to view site or dashboard
+# deploy a specific branch (sets it as production branch)
+...?repository=<repo>&branch=beta-feature
 
-## Handling netlify.toml
-
-If a `netlify.toml` file exists, the CLI uses it automatically. If not, the CLI will prompt for:
-- **Build command**: e.g., `npm run build`, `next build`
-- **Publish directory**: e.g., `dist`, `build`, `.next`
-
-Common framework defaults:
-- **Next.js**: build command `npm run build`, publish `.next`
-- **React (Vite)**: build command `npm run build`, publish `dist`
-- **Static HTML**: no build command, publish current directory
-
-The skill should detect framework from `package.json` if possible and suggest appropriate settings.
-
-## Example Full Workflow
-
-```bash
-# 1. Check authentication
-npx netlify status
-
-# If not authenticated:
-npx netlify login
-
-# 2. Link site (if needed)
-# Try Git-based linking first
-git remote show origin
-npx netlify link --git-remote-url https://github.com/user/repo
-
-# If no site exists, create new one:
-npx netlify init
-
-# 3. Install dependencies
-npm install
-
-# 4. Deploy (preview for testing)
-npx netlify deploy
-
-# 5. Deploy to production (when ready)
-npx netlify deploy --prod
+# install required SDK extensions before first deploy
+...?repository=<repo>&fullConfiguration=true
 ```
 
-## Error Handling
+File-based template config, `[template]` in the repo root `netlify.toml`:
+```toml
+[template]
+  incoming-hooks = ["Contentful"]
+  required-extensions = ["supabase"]
 
-Common issues and solutions:
-
-**"Not logged in"**
-→ Run `npx netlify login`
-
-**"No site linked"**
-→ Run `npx netlify link` or `npx netlify init`
+[template.environment]
+  SECRET_TOKEN = "change me for your secret token"
+  CUSTOM_LOGO = "set the url to your custom logo here"
+```
 
-**"Build failed"**
-→ Check build command and publish directory in netlify.toml or CLI prompts
-→ Verify dependencies are installed
-→ Review build logs for specific errors
+You **cannot** set env var values or a base directory in `[template]` — use URL params. `[template.environment]` placeholder strings are only UI labels.
 
-**"Publish directory not found"**
-→ Verify build command ran successfully
-→ Check publish directory path is correct
+**⚠ Template configuration (incoming hooks, template env vars) is read ONLY from the repository ROOT.** When the button targets a subdirectory via `base`, the base-directory `netlify.toml` takes precedence for builds, but template config there is ignored. State this limitation explicitly rather than leaving it implied.
 
-## Troubleshooting
+## Secrets scanning failures
 
-### Escalated Network Access
+**⚠ A secrets-scanning deploy failure means a value that looks like a secret reached your build output.** If it's a real secret, that's a leak — stop shipping it in client/published output and rotate it. **Never** set `SECRETS_SCAN_ENABLED=false` to silence the scanner over a real leak. For genuinely non-secret values, scope narrowly with `SECRETS_SCAN_OMIT_KEYS` / `SECRETS_SCAN_OMIT_PATHS`.
 
-If deployment fails due to network issues (timeouts, DNS errors, connection resets), rerun the deploy with escalated permissions (use `sandbox_permissions=require_escalated`). The deploy requires escalated network access when sandbox networking blocks outbound requests.
+## Fixing a failed deploy — no rollbacks
 
-Example guidance to the user:
+**A failed deploy never publishes** — the previous deploy is still live, so there is nothing to restore. If someone asks to roll back or restore a previous deploy, correct the premise: after a failed deploy nothing changed, and for a bad *published* deploy, **fix forward** — revert the commit and let CI redeploy it. Do not call `restoreSiteDeploy` or `publishDeploy`, and do not hand over a dashboard rollback as the answer.
 
-```
-The deploy needs escalated network access to deploy to Netlify. I can rerun the command with escalated permissions—want me to proceed?
-```
+Netlify surfaces a **Why did it fail?** AI diagnosis above the deploy log — this diagnosis and its suggested solution do **NOT** consume credits. Selecting **Fix with agent** starts an agent run, which **DOES** consume credits from your team's balance. See https://docs.netlify.com/resources/troubleshooting/fix-a-failed-deploy/.
 
-## Environment Variables
+## Deploy permissions (private repos)
 
-For secrets and configuration:
+Netlify only builds changes pushed to private repos from **recognized authors** (Owners, Developers, Git Contributors; Marketplace bots count). An unrecognized author's merge shows **Pending approval**; a Team Owner must associate them with a team account before the build starts. Build-hook deploys are exempt.
 
-1. Never commit secrets to Git
-2. Set in Netlify dashboard: Site Settings → Environment Variables
-3. Access in builds via `process.env.VARIABLE_NAME`
+## Constraints & gotchas
 
-## Tips
+- **Files per directory: 54,000.** Any directory over this in the publish dir fails the deploy. No limit on total files per deploy.
+- **Skew protection:** all plans; **production context only** — branch deploys, Deploy Previews, and permalinks bypass it and serve the latest deploy. Needs Netlify CLI 23.11.0+. Astro 5.15.0+ enables it by default via the Netlify Adapter; Next.js is opt-in. Password protection on production deploys (or on all deploys) turns skew protection off — it only works when you protect non-production deploys only. Netlify discards skew protection signals on hard navigation (`Sec-Fetch-Mode: navigate`, or `Sec-Fetch-Site` present and not `same-origin`). Framework maintainers add support via `netlify/v1/skew-protection.json`.
+- **Search indexing:** only the published production deploy and most recent branch deploys are indexable; previews and old deploys get `X-Robots-Tag: noindex`.
+- **Preview URL visibility:** Deploy Preview / branch deploy URLs are shareable with anyone holding the link unless you add password or team-login protection.
+- **New-project visibility:** on Credit-based plans with "private by default", new projects start private regardless of how they're created.
+- **Automatic deletion:** deploys are deleted after 30 days (90 days on paid plans); Enterprise can raise this up to 365 days. Never deleted: the published deploy, the most recent successful production deploy, and the most recent successful branch deploy per branch. Configure at Project configuration > Developer settings > Automatic Deletion.
 
-- Use `netlify deploy` (no `--prod`) first to test before production
-- Run `netlify open` to view site in Netlify dashboard
-- Run `netlify logs` to view function logs (if using Netlify Functions)
-- Use `netlify dev` for local development with Netlify Functions
+See `references/cli-commands.md` for the full CLI surface and flags.
 
-## Reference
+<!-- Retention period for failed/canceled deploys is stated inconsistently in sources (30/90 days vs 6 months); used the 30/90-day figure. -->
 
-- Netlify CLI Docs: https://docs.netlify.com/cli/get-started/
-- netlify.toml Reference: https://docs.netlify.com/configure-builds/file-based-configuration/
+<!-- system: agent-context/deploy/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
+# Netlify house rules (deploy)
 
-## Bundled References (Load As Needed)
+These are org conventions, not docs facts — merged into the rendered skill by
+ctx-gen and never generated. Owned by the skills maintainer.
 
-- [CLI commands](references/cli-commands.md)
-- [Deployment patterns](references/deployment-patterns.md)
-- [netlify.toml guide](references/netlify-toml.md)
+1. Agents do not roll back deploys: never call `restoreSiteDeploy` or
+   `publishDeploy` to restore an older deploy. Fix forward — revert the
+   commit and let CI deploy it.
+2. A failed deploy never publishes; on failure there is nothing to roll
+   back.
+3. Deep guides live in this skill: `references/netlify-toml.md`,
+   `references/cli-commands.md`, `references/deployment-patterns.md`.
+4. The frontmatter description must never advertise rollback or restore as a
+   capability — no "roll back", "restore a deploy", or equivalent.
+5. When the user asks to roll back or restore a previous deploy, correct the
+   premise rather than complying: after a failed deploy the previous deploy
+   is still live and there is nothing to restore; for a bad published deploy,
+   fix forward per rule 1. Do not hand over `restoreSiteDeploy` /
+   `publishDeploy` or a dashboard rollback as the answer.
+6. Always add `.netlify` to `.gitignore` when linking or creating a site —
+   every linking path writes `.netlify/state.json`, which must not be
+   committed. Mention it whenever you link.
+7. Secrets-scanning deploy failures: if the flagged value is a real secret,
+   that is a leak — stop shipping it in client/published output and rotate
+   it; never silence the scanner over a real leak. For genuinely non-secret
+   values, scope narrowly with `SECRETS_SCAN_OMIT_KEYS` /
+   `SECRETS_SCAN_OMIT_PATHS`, never `SECRETS_SCAN_ENABLED=false`.
+8. Before running a manual `netlify deploy --prod` on a site with Git CD
+   connected, warn the user that the next push to the production branch
+   silently replaces the hand-shipped deploy; suggest locking the published
+   deploy if it must stay live.
+9. Deploy-to-Netlify buttons: template configuration (incoming hooks,
+   template env vars) is only read from the repository ROOT. When a
+   button targets a subdirectory via `base`, state this limitation
+   explicitly — do not leave it implied.