@sanity/runtime-cli 17.3.2 → 17.4.0-blueprinit.g596ac51

package/skills/blueprinit.md

@@ -0,0 +1,155 @@
+# Blueprinit
+
+Use `blueprinit` to scaffold a Blueprint around an existing Sanity project. The command is
+experimental, hidden from root help, and available from the `blueprinit` npm dist-tag.
+
+Use it for demos and evaluation, not as a stable project initializer. Its flags, generated files,
+and resource model may change.
+
+## Know what it does
+
+`blueprinit` uses an existing Sanity organization, project, and dataset. It writes local Blueprint
+files, then creates an empty organization-scoped Stack. The generated Blueprint attaches the
+project and dataset and declares resources for a later deployment.
+
+It does not create an organization, project, or dataset. It does not deploy the attached resources,
+CORS origin, Studio, or Function. Those changes happen only if `blueprints deploy` is run later.
+
+## Inspect the target directory
+
+Run the command from the directory that should contain the Blueprint.
+
+Before running:
+
+1. Check the working tree and existing files. Do not discard unrelated user changes.
+2. Look for a root `sanity.blueprint.*` file. If one exists, use the existing Blueprint instead of
+   initializing again.
+3. Look for a root `sanity.config.*` file. Its presence selects the Studio adoption flow.
+4. Confirm the user asked to initialize this directory. The command writes files and creates a
+   remote Stack.
+5. Confirm the user is signed in. If needed, have them run:
+
+```sh
+npx sanity login
+```
+
+The account must have at least one organization, one project in the selected organization, and one
+dataset in the selected project.
+
+Interactive runs show the Blueprint resources, hosted Studio URL, local changes, and remote Stack
+action before the confirmation prompt. Project and dataset attachment plus CORS, Studio, and
+Function creation remain pending until a later deployment.
+
+## Choose the flow
+
+- **Existing Blueprint with a configured Stack:** Exit without changes and use
+  `blueprints config --edit` or `blueprints doctor`.
+- **Existing Blueprint without a configured Stack:** Finish setup with `blueprints init`; it can
+  connect the existing manifest without rewriting it.
+- **Root Studio config:** Adopt the Studio in place. Read literal `projectId` and `dataset` strings
+  from `sanity.config.*`, falling back to `sanity.cli.*`. Do not move the Studio.
+- **Fresh workspace:** Create a Blueprint, an npm-workspace Studio, and a starter `set-slug`
+  document function.
+
+Do not rewrite a Studio config merely to make adoption work unless the user asks. Dynamic
+`projectId` or `dataset` values built from environment variables or imports cannot be detected.
+
+For an existing Blueprint, inspect it with:
+
+```sh
+npx @sanity/runtime-cli@blueprinit blueprints doctor
+```
+
+## Run unattended
+
+When the organization and project IDs are known, run this from the target directory:
+
+```sh
+npx @sanity/runtime-cli@blueprinit blueprinit --yes \
+  --organization-id <organization-id> \
+  --project-id <project-id> \
+  --dataset <dataset-name>
+```
+
+Replace all placeholders with real values. The project must belong to the organization, and the
+dataset must belong to the project. Do not guess any value.
+
+`--yes` skips confirmation. Without explicit values, an unattended run stops when the account has
+several organizations, projects, or datasets. Ask the user for the missing value or have them run
+the command interactively.
+
+Use `--stack-name <name>` and `--studio-name <name>` when those generated names need to be stable.
+The command normalizes both names to lowercase kebab case. The Studio name is also its hosted slug,
+so it must be available in the target environment. Stack and Studio names must differ because they
+also name Blueprint resources.
+
+When `SANITY_INTERNAL_ENV=staging`, the generated Studio URL and CORS origin use
+`https://<studio-name>.studio.sanity.work`. Other environments use
+`https://<studio-name>.sanity.studio`.
+
+For interactive organization, project, dataset, confirmation, and Studio-name prompts, have the
+user run:
+
+```sh
+npx @sanity/runtime-cli@blueprinit blueprinit
+```
+
+When the project has several datasets, the interactive command prompts for one and lists
+`production` first. Report the selected dataset from the command output.
+
+## Review the result
+
+A successful fresh run creates or updates:
+
+```text
+.
+├── .sanity/blueprint.config.json
+├── sanity.blueprint.ts
+├── package.json
+├── functions/
+│   └── set-slug/
+└── studios/
+    └── studio/
+```
+
+The command also creates or updates `.gitignore`. It preserves existing package metadata and adds
+the required npm workspaces and `@sanity/blueprints` dependency.
+
+An adopted Studio stays at the repository root. The command adds the Blueprint, Blueprint config,
+dependency, and `.gitignore` entry, but does not generate the starter Function.
+
+After the command exits:
+
+1. Confirm the output names the expected organization, project, and dataset.
+2. Confirm `.sanity/blueprint.config.json` exists. Its presence means Stack creation completed.
+3. Review `sanity.blueprint.ts`, including the Studio slug and credentialed CORS origin, plus
+   `package.json`, `.gitignore`, and the working-tree diff.
+4. Report the Stack ID and every created or modified path.
+
+Do not deploy as part of initialization unless the user separately asks for deployment. To continue
+after reviewing the scaffold, install dependencies and preview the deployment:
+
+```sh
+npm install
+npx @sanity/runtime-cli@blueprinit blueprints plan
+```
+
+Treat dependency installation and planning as separate follow-up actions when they were not part of
+the user's request.
+
+## Handle failures
+
+- **`No Sanity session found.`** Stop and ask the user to run `npx sanity login`. Authentication
+  fails before files are written.
+- **Multiple organizations or projects found.** Rerun with the matching `--organization-id` and
+  `--project-id`. Selection fails before files are written.
+- **No datasets found.** Ask the user to create or choose a project with a dataset. The command does
+  not create datasets.
+- **Could not read `projectId` and `dataset`.** The detected Studio config does not contain both
+  values as string literals. Pass explicit `--project-id` and `--dataset` values or report the config
+  file and let the user decide whether to change it.
+- **Refusing to overwrite an existing path.** Inspect the reported Studio or Function directory.
+  Do not delete or replace it without the user's direction.
+- **Stack quota or duplicate-name error.** Local scaffold files may already exist while
+  `.sanity/blueprint.config.json` does not. Resolve the Stack error, then run the recovery command
+  printed by `blueprinit`. It uses `blueprints init` to connect the existing manifest.

package/skills/blueprints-add.md

@@ -0,0 +1,8 @@
+# `npx @sanity/cli blueprints add`
+
+Treat this command as legacy compatibility only. It is deprecated and supports only the `function` resource type. Prefer `npx @sanity/cli functions add` for new work.
+
+## Agent guidance
+
+- Warn that the command is deprecated before adding new usage to scripts or documentation.
+- Migrate existing legacy invocations to `npx @sanity/cli functions add`.

package/skills/blueprints-config.md

@@ -0,0 +1,33 @@
+# `npx @sanity/cli blueprints config`
+
+Read or update `.sanity/blueprint.config.json`, written next to the Blueprint manifest, which connects the local Blueprint to a Sanity scope and Stack.
+
+## Inspect first
+
+Run from the Blueprint directory and request structured output:
+
+```sh
+npx @sanity/cli blueprints config --json
+```
+
+Without `--edit`, the command only displays the current configuration; with no config file on disk, `--json` emits nothing and exits `0`. Treat the project or organization ID and Stack ID as a single target; changing one can redirect later plan, deploy, info, logs, promote, or destroy commands.
+
+## Update
+
+For agent-driven changes, pass the intended values instead of using the interactive editor:
+
+```sh
+npx @sanity/cli blueprints config --edit --project-id PROJECT_ID --stack NAME_OR_ID --json
+```
+
+Use `--organization-id ORGANIZATION_ID` instead of `--project-id` for an organization scope. The two scope flags are mutually exclusive. `--stack` accepts a Stack name or ID.
+
+Scope or Stack flags without `--edit` write nothing: the command prints `To update the Blueprint config, use the --edit flag.` (suppressed under `--json`) and exits `0`, so a successful exit does not mean the change was applied.
+
+## Switching scope
+
+An update only sets the keys it was given. Adding `--organization-id` to a config that already holds `projectId` leaves both in the file, and project scope takes precedence over organization scope, so the switch has no effect on later commands.
+
+To move a Blueprint from project to organization scope, either edit `.sanity/blueprint.config.json` to remove `projectId`, or use `blueprints promote`, which clears it as part of the scope change.
+
+After an update, run `blueprints config --json` again and verify every ID before executing a mutating command.

package/skills/blueprints-deploy.md

@@ -0,0 +1,36 @@
+# `npx @sanity/cli blueprints deploy`
+
+Apply the local Blueprint to a remote Stack. This command can create, update, and remove remote resources.
+
+## Preflight
+
+1. Locate and inspect the Blueprint manifest.
+2. Resolve the target from local configuration, or pass an explicit scope and `--stack`.
+3. Run `npx @sanity/cli blueprints plan --json`.
+4. Review all planned changes, especially replacements and removals.
+
+Do not deploy when the target or plan is ambiguous.
+
+## Deploy
+
+Include a message that records the reason for the change:
+
+```sh
+npx @sanity/cli blueprints deploy --message "Deploy order processing changes" --json
+```
+
+To target another Stack, pass `--stack NAME_OR_ID`, adding `--project-id PROJECT_ID` or `--organization-id ORGANIZATION_ID` when the scope also differs.
+
+Use `--no-wait` only when the caller does not need a confirmed result. Follow an asynchronous deployment with:
+
+```sh
+npx @sanity/cli blueprints info --json
+```
+
+Exit code `0` means the deployment completed, or was accepted when `--no-wait` is set. Exit code `2` means it failed. Exit code `75` means the request was accepted but completion could not be confirmed; inspect `blueprints info` and `blueprints logs` before retrying.
+
+The command refuses to start while the Stack has a `QUEUED` or `IN_PROGRESS` operation, so a retry during one fails with that message rather than deploying twice. Once the earlier operation settles, a retry does deploy again.
+
+Use `--new-stack-name NAME` only when the deployment should also rename the Stack.
+
+Set `SANITY_ASSET_TIMEOUT` in seconds to raise the 180-second per-asset limit on processing resource assets when large Functions time out during preparation. Set `SANITY_ASSET_CONCURRENCY` to change how many assets are processed at once (default 4).

package/skills/blueprints-destroy.md

@@ -0,0 +1,30 @@
+# `npx @sanity/cli blueprints destroy`
+
+Permanently destroy a remote Stack and its provisioned resources. The local Blueprint manifest and resource files remain, and a matching local Stack ID is cleared from `.sanity/blueprint.config.json`.
+
+## Required safety checks
+
+1. Obtain explicit authorization to destroy the Stack.
+2. Resolve the exact project or organization scope and Stack ID.
+3. Run `npx @sanity/cli blueprints info --json` for that target.
+4. Present the resolved target and affected resources before continuing.
+
+Do not infer authorization from a request to clean up files, redeploy, or fix configuration.
+
+## Run
+
+Interactive use prompts for confirmation:
+
+```sh
+npx @sanity/cli blueprints destroy
+```
+
+For an authorized non-interactive destruction, provide the complete target:
+
+```sh
+npx @sanity/cli blueprints destroy --project-id PROJECT_ID --stack NAME_OR_ID --force --json
+```
+
+Use `--organization-id` instead of `--project-id` for an organization-scoped Stack. The explicit scope flags require both `--stack` and `--force`.
+
+Use `--no-wait` only when asynchronous destruction is intended: it exits `0` as soon as the request is accepted. While waiting, exit code `75` means the request was accepted but completion could not be confirmed. Check `blueprints info` before retrying.

package/skills/blueprints-doctor.md

@@ -0,0 +1,31 @@
+# `npx @sanity/cli blueprints doctor`
+
+Runs five checks: Host online, Authenticated, Manifest valid, Stack ready, User has access. Run this before changing files when another Blueprint command fails for an unclear reason.
+
+## Diagnose
+
+Run from the project directory:
+
+```sh
+npx @sanity/cli blueprints doctor
+```
+
+Use `--path PATH` when the Blueprint manifest is outside the current directory or cannot be discovered automatically. `SANITY_BLUEPRINT_PATH` provides the same path through the environment.
+
+Read the reported diagnostics and warnings before proposing changes. Do not assume every warning requires a fix.
+
+## Read the exit code, not just the JSON
+
+The command exits non-zero unless every check passes; a check that cannot be determined also fails the run. `--json` suppresses the report: a clean run prints `{"diagnostics": {"online": true, "tokenValid": true, ...}}` with `true`, `false`, or `null` per check, and a failing run prints an error object with no diagnostics. Rerun without `--json` to see which checks failed and why.
+
+## Fix
+
+`--fix` prompts for scope and Stack, then writes `.sanity/blueprint.config.json`:
+
+```sh
+npx @sanity/cli blueprints doctor --fix
+```
+
+`--fix` cannot be combined with `--path`, including a path supplied through `SANITY_BLUEPRINT_PATH`. It also requires authentication and a readable Blueprint manifest; without either it reports what is missing and changes nothing.
+
+Use `--fix` only when interactive input is available and the user has authorized configuration changes. Otherwise, apply a specific, reviewed fix and rerun the read-only diagnostic command.

package/skills/blueprints-info.md

@@ -0,0 +1,23 @@
+# `npx @sanity/cli blueprints info`
+
+Read the current state and deployed resources of one remote Stack, including the status of its most recent deploy or destroy operation. Use it to verify a target before mutation.
+
+## Run
+
+Use the locally configured Stack:
+
+```sh
+npx @sanity/cli blueprints info --json
+```
+
+Query a specific target when local configuration is absent or should not be trusted:
+
+```sh
+npx @sanity/cli blueprints info --project-id PROJECT_ID --stack NAME_OR_ID --json
+```
+
+Use `--organization-id` instead of `--project-id` for an organization scope. `--stack` accepts a Stack name or ID. `--verbose` (`-v`) adds each resource's ID and external ID to human-readable output.
+
+The JSON result contains a `stack` object with `id`, `name`, `scopeType`, `scopeId`, `resources`, and `recentOperation`. Check `recentOperation.status` rather than relying on a successful exit alone.
+
+Run this command after `deploy --no-wait`, `destroy --no-wait`, or exit code `75`. Use `blueprints stacks --json` first when the Stack ID is unknown.

package/skills/blueprints-init.md

@@ -0,0 +1,48 @@
+# `npx @sanity/cli blueprints init`
+
+Initialize a local Blueprint and connect it to a new or existing remote Stack. Use this at the start of a Blueprint project or to configure an existing manifest.
+
+## Before running
+
+- Authenticate with Sanity.
+- Choose the target directory and whether the Stack belongs to a project or an organization.
+- Check the target directory and its parents for an existing manifest (`sanity.blueprint` or `blueprint`, with `.json`, `.js`, `.mjs`, or `.ts`). When one is found, the command configures it instead of creating another manifest.
+- Confirm whether to create a Stack or attach an existing one.
+
+## Run
+
+Pass `.` to initialize the current directory without the directory confirmation prompt:
+
+```sh
+npx @sanity/cli blueprints init . --project-id PROJECT_ID --stack-name development
+```
+
+To connect to an existing Stack, provide its ID and scope:
+
+```sh
+npx @sanity/cli blueprints init . --project-id PROJECT_ID --stack-id STACK_ID
+```
+
+Use `--organization-id` instead of `--project-id` for an organization-scoped Stack. `--stack-id` and `--stack-name` are mutually exclusive, and either one requires an explicit project or organization scope.
+
+For a new local Blueprint, choose the manifest format with `--blueprint-type json|js|ts`. JavaScript and TypeScript setups add `@sanity/blueprints` to `devDependencies`, writing a `package.json` with `"type": "module"` if the directory has none. A `js` manifest is written as `sanity.blueprint.mjs` when a `package.json` already exists there without `"type": "module"`. The command also writes `.sanity/blueprint.config.json` and a `.gitignore` covering `node_modules`, `.env`, and function build output; the `.sanity` config itself is not ignored. `--example NAME` takes a different path: it scaffolds a published example into the named directory (or `./NAME` when none is given), creates a project-scoped Stack called `example-NAME`, and cannot be combined with `--blueprint-type`, `--stack-id`, or `--stack-name`.
+
+## Avoid the prompts
+
+A fresh initialization is interactive unless every decision is supplied up front. Pass all four:
+
+```sh
+npx @sanity/cli blueprints init . --project-id PROJECT_ID --stack-name development --blueprint-type ts
+```
+
+Omitting `--blueprint-type` prompts for the manifest format. Omitting both `--stack-id` and `--stack-name` prompts for Stack selection. Omitting the scope starts a full organization and project wizard. Omitting the directory prompts to confirm the current one.
+
+## Verify
+
+Inspect the created files, then preview the first deployment:
+
+```sh
+npx @sanity/cli blueprints plan --json
+```
+
+Do not deploy until the plan targets the expected Stack and contains the expected resource changes.

package/skills/blueprints-logs.md

@@ -0,0 +1,33 @@
+# `npx @sanity/cli blueprints logs`
+
+Retrieve deployment logs for one remote Stack. Prefer bounded, one-shot queries for agent work.
+
+## Query logs
+
+Request structured output with an explicit limit:
+
+```sh
+npx @sanity/cli blueprints logs --limit 100 --json
+```
+
+Narrow a query with ISO 8601 timestamps:
+
+```sh
+npx @sanity/cli blueprints logs --since 2026-07-29T00:00:00Z --limit 100 --json
+```
+
+Use `--before` to page toward older entries. `--limit` must be between 1 and 500; without it the API's default page size applies. When entries are found, the JSON result contains `logs` and `hasMore`; an empty range returns no JSON payload.
+
+Pass `--stack NAME_OR_ID` with `--project-id PROJECT_ID` or `--organization-id ORGANIZATION_ID` when overriding the locally configured target.
+
+## Watch mode
+
+`--watch` (`-w`, alias `--follow`) prints the 10 most recent entries, then polls for new ones until interrupted. It cannot be combined with `--json`, `--limit`, `--since`, or `--before`.
+
+Use watch mode only when continuous monitoring is requested:
+
+```sh
+npx @sanity/cli blueprints logs --watch
+```
+
+If no expected logs appear, run `blueprints info --json` and verify the Stack ID and deployment status.

package/skills/blueprints-mint-deploy-token.md

@@ -0,0 +1,25 @@
+# `npx @sanity/cli blueprints mint-deploy-token`
+
+Create a robot token for deploying Blueprints from CI, scoped to one project or organization. The role granted is `blueprints-deployer` for a project, `blueprints-deployer-robot` for an organization.
+
+## Protect the credential
+
+- Obtain authorization before creating a new robot credential.
+- Confirm the exact scope and use a label that identifies the CI system or deployment purpose.
+- Send the token only to the user-approved secret destination.
+- Never write the token to source files, commit it, paste it into an issue, or include it in a response or log.
+- Revoke unused tokens in Sanity Manage.
+
+## Run
+
+The default command prints the robot label, ID, and expiry, then prompts for clipboard, terminal, or discard handling. For automation, `--print` emits only the raw token:
+
+```sh
+npx @sanity/cli blueprints mint-deploy-token --project-id PROJECT_ID --label "production-ci" --print
+```
+
+Use `--organization-id ORGANIZATION_ID` instead of `--project-id` for organization scope. The two scope flags are mutually exclusive.
+
+`--json` returns the full robot response, including sensitive token material. Do not use it when output is collected in ordinary build logs.
+
+A `ROLE_UNAVAILABLE` error means the role does not exist in that project or organization. Other access or permission errors mean the account needs project or organization administrator access. Do not mint repeated replacement tokens without checking whether the earlier request succeeded.

package/skills/blueprints-plan.md

@@ -0,0 +1,28 @@
+# `npx @sanity/cli blueprints plan`
+
+Preview the resource changes produced by the local Blueprint without creating, modifying, or deleting deployed resources.
+
+## Run
+
+Run after editing the Blueprint and before every deployment:
+
+```sh
+npx @sanity/cli blueprints plan --json
+```
+
+The JSON result contains the resolved local `resources` and the remote deployment `plan`. Review the operations instead of treating a zero exit code as approval to deploy.
+
+To plan against a Stack other than the locally configured one, pass its name or ID, and the scope when that differs too:
+
+```sh
+npx @sanity/cli blueprints plan --project-id PROJECT_ID --stack NAME_OR_ID --json
+```
+
+Use `--organization-id` instead of `--project-id` for organization scope. The scope flags are mutually exclusive.
+
+## Review
+
+- Confirm the Stack ID and scope.
+- Match planned resources to the requested change.
+- Flag unexpected deletions, replacements, or unrelated changes.
+- Stop when the target or impact cannot be determined.

package/skills/blueprints-promote.md

@@ -0,0 +1,31 @@
+# `npx @sanity/cli blueprints promote`
+
+Promote a deployed Stack from project scope to organization scope. Promotion cannot be reversed, and the local Blueprint configuration is updated to the organization scope after success.
+
+## Required safety checks
+
+1. Obtain explicit authorization for the scope change.
+2. Run `npx @sanity/cli blueprints info --json`.
+3. Confirm the exact Stack ID, current project scope, and deployed resources.
+4. Confirm the caller has organization admin access.
+
+The command requires a local Blueprint manifest and an existing `.sanity/blueprint.config.json` to update.
+
+## Run
+
+Interactive use prompts for confirmation:
+
+```sh
+npx @sanity/cli blueprints promote --project-id PROJECT_ID --stack NAME_OR_ID
+```
+
+`--force` skips that prompt. Use `--new-stack-name NAME` to rename during promotion, which is required when the destination organization already holds a Stack with the current name; it is rejected on a Stack that is already organization-scoped.
+
+After success, run:
+
+```sh
+npx @sanity/cli blueprints config --json
+npx @sanity/cli blueprints info --json
+```
+
+If the remote promotion succeeds but the local config update fails, repair the configuration with `blueprints config --edit`; do not promote the Stack again.

package/skills/blueprints-stacks.md

@@ -0,0 +1,28 @@
+# `npx @sanity/cli blueprints stacks`
+
+List remote Stacks for a project or organization. Use this read-only command to discover a Stack ID before running a targeted info, logs, config, deploy, promote, or destroy command.
+
+## Run
+
+List Stacks for the locally configured scope:
+
+```sh
+npx @sanity/cli blueprints stacks --json
+```
+
+Select a scope explicitly when working outside the local Blueprint:
+
+```sh
+npx @sanity/cli blueprints stacks --project-id PROJECT_ID --json
+npx @sanity/cli blueprints stacks --organization-id ORGANIZATION_ID --json
+```
+
+The JSON result contains `stacks`, `scopeType`, and `scopeId`; each entry carries `resourceCount` rather than a full `resources` array. Zero results prints `No stacks found` and emits no JSON. Match both the Stack and its scope; names alone may be ambiguous.
+
+To also include Stacks scoped to the organization's projects:
+
+```sh
+npx @sanity/cli blueprints stacks --organization-id ORGANIZATION_ID --include-projects --json
+```
+
+`--include-projects` requires `--organization-id`, cannot be combined with `--project-id`, and only queries the organization's first 50 projects. This command does not change the local Blueprint target; use `blueprints config --edit` for that.

package/skills/functions-add.md

@@ -0,0 +1,35 @@
+# `npx @sanity/cli functions add`
+
+Scaffold a local Function and its resource definition for the current Blueprint.
+
+## Before running
+
+- Run from a project containing a Blueprint manifest.
+- Choose a Function name not already used by a Blueprint resource, and one event family: document, media-library asset, scheduled, or sync-tag invalidation.
+- Names must be at least three characters, start with a letter or digit, and otherwise contain only letters, digits, hyphens, and underscores.
+- Decide whether to install `@sanity/functions`, which provides typed helpers for authoring handler code, and which package manager to use.
+
+## Add a Function
+
+Provide flags to avoid interactive prompts:
+
+```sh
+npx @sanity/cli functions add --name process-order --type document-create --type document-update --language ts --helpers --installer npm
+```
+
+No flag is required and any omitted value is prompted for, but `--type` without `--name` is rejected. The accepted `--type` values are `document-create`, `document-update`, `document-delete`, `document-publish`, `media-library-asset-create`, `media-library-asset-update`, `media-library-asset-delete`, `scheduled-function`, and `sync-tag-invalidate`. Repeat the flag for multiple events from the same family; the command rejects a mix of families.
+
+TypeScript is the default language. Use `--language js` or `--javascript` for JavaScript, but do not combine those flags. Use `--no-helpers` when helper installation is not wanted. `--installer` accepts `npm`, `pnpm`, `yarn`, or `skip`.
+
+`--example EXAMPLE_NAME` downloads a Function example from the `sanity-labs/function-recipes` repository into `functions/EXAMPLE_NAME/` instead of running the normal scaffold flow. Browse recipes at https://www.sanity.io/exchange/type=recipes/solution=functions. Each recipe's Quick Start contains the correct `--example` value. Pass it alone: every other scaffold flag is rejected, and the manifest is not updated. Use it only for an example the user requested, then follow the configuration instructions printed by the command.
+
+## Verify
+
+The scaffold writes one file, `functions/NAME/index.ts` (or `index.js`). Only `.json` manifests are edited in place; for `.ts`, `.js`, and `.mjs` manifests the command prints a resource definition that still needs to be added by hand.
+
+Run the Function locally with a payload that matches the handler before deployment:
+
+```sh
+npx @sanity/cli functions test process-order --file payload.json --json
+npx @sanity/cli blueprints plan --json
+```

package/skills/functions-dev.md

@@ -0,0 +1,21 @@
+# `npx @sanity/cli functions dev`
+
+Start the local web emulator for interactive Function development. The command keeps running until interrupted.
+
+## Start the emulator
+
+Use the default host and port:
+
+```sh
+npx @sanity/cli functions dev
+```
+
+The emulator is available at `http://localhost:8080`. Choose another loopback port when needed:
+
+```sh
+npx @sanity/cli functions dev --host 127.0.0.1 --port 3333 --timeout 60
+```
+
+Port 8974 is not available: the emulator's WebSocket server binds it. `--timeout` sets the execution limit in seconds for every Function, taking precedence over each Function's configured `timeout` (default 10 seconds). Bind to a non-loopback interface only when network access is requested and exposing the development server is acceptable.
+
+Run this command in a persistent terminal, report the URL, and stop the process when development is complete. For one bounded invocation without a web server, use `functions test`.

package/skills/functions-env-add.md

@@ -0,0 +1,29 @@
+# `npx @sanity/cli functions env add`
+
+Set or replace one environment variable on a deployed Function. The command writes to the Functions API and does not redeploy the Stack.
+
+Run from the Blueprint directory or a subdirectory; the manifest is required even though the command only touches remote state.
+
+## Confirm the target
+
+Resolve the deployed Function name and Stack before changing remote state. Use `functions env list` to inspect existing keys when replacing a value was not explicitly requested.
+
+Set a non-secret value:
+
+```sh
+npx @sanity/cli functions env add process-order API_URL https://api.example.com/
+```
+
+Override the locally configured Stack with `--stack NAME_OR_ID`.
+
+## Protect secret values
+
+The value is a positional command argument and may be visible in shell history, process inspection, or agent tool transcripts. Do not run the command with a secret until the user has approved both the target and the handling method.
+
+Do not use `--json` or `--trace` for secrets: the JSON result contains the value, and trace output prints the request body. Never paste a secret value into source files, logs, issue comments, or an assistant response.
+
+After setting the variable, verify only its key:
+
+```sh
+npx @sanity/cli functions env list process-order --json
+```

package/skills/functions-env-list.md

@@ -0,0 +1,21 @@
+# `npx @sanity/cli functions env list`
+
+List the environment-variable keys configured on one deployed Function. Values are not returned.
+
+Run from the Blueprint directory or a subdirectory; the manifest is required even though the command only touches remote state.
+
+## Run
+
+Use the locally configured Stack:
+
+```sh
+npx @sanity/cli functions env list process-order --json
+```
+
+Query another Stack:
+
+```sh
+npx @sanity/cli functions env list process-order --stack NAME_OR_ID --json
+```
+
+The JSON result contains the Function `name` and an `envvars` array of keys. Match the Function name and Stack before using the result to add, replace, or remove a variable.

package/skills/functions-env-remove.md

@@ -0,0 +1,22 @@
+# `npx @sanity/cli functions env remove`
+
+Delete one environment variable from a deployed Function. The command does not ask for confirmation and does not redeploy the Stack.
+
+Run from the Blueprint directory or a subdirectory; the manifest is required even though the command only touches remote state.
+
+## Required checks
+
+1. Obtain authorization to remove the key.
+2. Resolve the exact Function and Stack.
+3. Run `functions env list` and confirm that the key is present.
+4. Check whether the Function still requires the variable.
+
+## Remove
+
+```sh
+npx @sanity/cli functions env remove process-order LEGACY_API_URL --json
+```
+
+Override the locally configured Stack with `--stack NAME_OR_ID`.
+
+The JSON result contains the Function name and removed key, not the old value. If the value may be needed again, arrange a user-approved backup before removal; this command cannot retrieve it.