@sanity/runtime-cli 17.4.0 → 17.6.0-blueprinit.g77b7a64

package/dist/utils/types.d.ts

@@ -1,4 +1,4 @@
-import { type BlueprintCorsOriginResource, type BlueprintDatasetResource, type BlueprintDocumentFunctionResource, type BlueprintDocumentWebhookResource, type BlueprintMediaLibraryAssetFunctionResource, type BlueprintProjectResource, type BlueprintResource, type BlueprintRobotResource, type BlueprintRoleResource, type BlueprintScheduledFunctionResource, type BlueprintStudioResource, type BlueprintSyncTagInvalidateFunctionResource } from '@sanity/blueprints';
+import { type BlueprintCorsOriginResource, type BlueprintDatasetResource, type BlueprintDocumentFunctionResource, type BlueprintDocumentWebhookResource, type BlueprintDurableFunctionResource, type BlueprintMediaLibraryAssetFunctionResource, type BlueprintProjectResource, type BlueprintPubSubFunctionResource, type BlueprintResource, type BlueprintRobotResource, type BlueprintRoleResource, type BlueprintScheduledFunctionResource, type BlueprintStudioResource, type BlueprintSyncTagInvalidateFunctionResource } from '@sanity/blueprints';
 export type ScopeType = 'organization' | 'project';
 /** Result utility type */
 export type Result<T, E = string> = {
@@ -15,7 +15,11 @@ export interface ActionResponse {
 }
 /** @internal */
 export type FunctionGroqResource = BlueprintDocumentFunctionResource | BlueprintMediaLibraryAssetFunctionResource;
-export type FunctionResource = FunctionGroqResource | BlueprintScheduledFunctionResource | BlueprintSyncTagInvalidateFunctionResource;
+export type FunctionResource = FunctionGroqResource | BlueprintPubSubFunctionResource | BlueprintScheduledFunctionResource | BlueprintSyncTagInvalidateFunctionResource | BlueprintDurableFunctionResource;
+/** Function resources that declare an `event`; PubSub functions are triggered by other functions */
+export type EventFunctionResource = Exclude<FunctionResource, BlueprintPubSubFunctionResource>;
+/** The `event` of any function resource that declares one */
+export type FunctionResourceEvent = EventFunctionResource['event'];
 /** Resource types that carry a deployable asset (have src: string) */
 export type AssetResource = FunctionResource | BlueprintStudioResource;
 /** @internal */
@@ -36,6 +40,7 @@ export interface DeployedResource extends BlueprintResourceRecord {
     externalId: string;
 }
 export declare function isLocalFunctionResource(r: BlueprintResource): r is FunctionResource;
+export declare function hasEventSource(r: FunctionResource): r is EventFunctionResource;
 export declare function isScheduleEvent(e: unknown): e is BlueprintScheduledFunctionResource['event'];
 export declare function isCorsOriginResource(r: unknown): r is BlueprintCorsOriginResource;
 export declare function isProjectResource(r: unknown): r is BlueprintProjectResource;
@@ -43,6 +48,7 @@ export declare function isRobotResource(r: unknown): r is BlueprintRobotResource
 export declare function isRoleResource(r: unknown): r is BlueprintRoleResource;
 export declare function isDatasetResource(r: unknown): r is BlueprintDatasetResource;
 export declare function isStudioResource(r: BlueprintResource): r is BlueprintStudioResource;
+export declare function isDurableFunctionResource(r: unknown): r is BlueprintDurableFunctionResource;
 export declare function isAssetResource(r: BlueprintResource): r is AssetResource;
 export declare function isWebhookResource(r: unknown): r is BlueprintDocumentWebhookResource;
 interface StackBase {

package/dist/utils/types.js

@@ -1,8 +1,11 @@
-import { validateCorsOrigin, validateDataset, validateDocumentWebhook, validateProject, validateRobot, validateRole, } from '@sanity/blueprints';
-import { SANITY_FUNCTION_PREFIX, SANITY_STUDIO } from '../constants.js';
+import { validateCorsOrigin, validateDataset, validateDocumentWebhook, validateDurableFunction, validateProject, validateRobot, validateRole, } from '@sanity/blueprints';
+import { SANITY_FUNCTION_PREFIX, SANITY_FUNCTION_PUBSUB, SANITY_STUDIO } from '../constants.js';
 export function isLocalFunctionResource(r) {
     return r.type.startsWith(SANITY_FUNCTION_PREFIX);
 }
+export function hasEventSource(r) {
+    return r.type !== SANITY_FUNCTION_PUBSUB;
+}
 // type narrowing with predicate functions
 export function isScheduleEvent(e) {
     return e !== null && typeof e === 'object' && ('hour' in e || 'expression' in e);
@@ -25,6 +28,9 @@ export function isDatasetResource(r) {
 export function isStudioResource(r) {
     return r.type === SANITY_STUDIO;
 }
+export function isDurableFunctionResource(r) {
+    return validateDurableFunction(r).length === 0;
+}
 export function isAssetResource(r) {
     return isLocalFunctionResource(r) || isStudioResource(r);
 }

package/oclif.manifest.json

@@ -1,5 +1,134 @@
 {
   "commands": {
+    "init": {
+      "aliases": [],
+      "args": {},
+      "description": "Scaffolds a Blueprint, Studio, and starter function around an existing Sanity project.\n\nThis hidden command is an experiment; its interface and generated files are not stable.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --yes",
+        "<%= config.bin %> <%= command.id %> --project-id <id> --dataset <name> --yes"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "path": {
+          "aliases": [
+            "blueprint-path"
+          ],
+          "char": "p",
+          "description": "Path to a Blueprint file or directory containing one",
+          "env": "SANITY_BLUEPRINT_PATH",
+          "hidden": true,
+          "name": "path",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "trace": {
+          "description": "Trace output",
+          "hidden": true,
+          "name": "trace",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "validate-resources": {
+          "description": "Validate resources",
+          "hidden": true,
+          "name": "validate-resources",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "hidden": true,
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "llms": {
+          "aliases": [
+            "skill"
+          ],
+          "description": "Show agent-oriented guidance for this command",
+          "hidden": true,
+          "name": "llms",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "organization-id": {
+          "aliases": [
+            "organization",
+            "organizationId",
+            "org"
+          ],
+          "description": "Organization to use when the account has several",
+          "name": "organization-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-id": {
+          "aliases": [
+            "project",
+            "projectId"
+          ],
+          "description": "Project to use when the organization has several",
+          "name": "project-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dataset": {
+          "description": "Dataset to attach",
+          "name": "dataset",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "stack-name": {
+          "description": "Name for the new organization-scoped Stack",
+          "name": "stack-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "studio-name": {
+          "description": "Name and hosted slug for the Studio resource",
+          "name": "studio-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hidden": true,
+      "hiddenAliases": [],
+      "id": "init",
+      "pluginAlias": "@sanity/runtime-cli",
+      "pluginName": "@sanity/runtime-cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Experimental blueprints-first project init",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "init.js"
+      ]
+    },
     "blueprints:add": {
       "aliases": [],
       "args": {
@@ -148,6 +277,7 @@
             "media-library-asset-create",
             "media-library-asset-delete",
             "media-library-asset-update",
+            "pub-sub",
             "scheduled-function",
             "sync-tag-invalidate"
           ],
@@ -373,7 +503,7 @@
     "blueprints:deploy": {
       "aliases": [],
       "args": {},
-      "description": "Applies your local Blueprint to the remote Stack, creating, updating, or removing resources as needed. This is the primary command for applying infrastructure changes.\n\nBefore deploying, run 'blueprints plan' to preview changes. After deployment, use 'blueprints info' to verify Stack status or 'blueprints logs' to monitor activity.\n\nUse --no-wait to queue the deployment and return immediately without waiting for completion.\n\nUse --fn-installer to force which package manager to use when deploying functions.\n\nSet SANITY_ASSET_TIMEOUT (seconds) to override the 60-second timeout for processing resource assets.\n\nExit codes: 0 deployed, 2 deployment failed, 75 deployment accepted but completion could not be confirmed (rerun 'blueprints info' to check).",
+      "description": "Applies your local Blueprint to the remote Stack, creating, updating, or removing resources as needed. This is the primary command for applying infrastructure changes.\n\nBefore deploying, run 'blueprints plan' to preview changes. After deployment, use 'blueprints info' to verify Stack status or 'blueprints logs' to monitor activity.\n\nUse --no-wait to queue the deployment and return immediately without waiting for completion.\n\nUse --fn-installer to force which package manager to use when deploying functions.\n\nSet SANITY_ASSET_TIMEOUT (seconds) to override the 180-second timeout for processing resource assets.\n\nSet SANITY_ASSET_CONCURRENCY to override how many resource assets are processed at once (default 4).\n\nExit codes: 0 deployed, 2 deployment failed, 75 deployment accepted but completion could not be confirmed (rerun 'blueprints info' to check).",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
         "<%= config.bin %> <%= command.id %> --message \"Enable staging dataset\"",
@@ -629,9 +759,7 @@
           "type": "option"
         },
         "force": {
-          "aliases": [
-            "f"
-          ],
+          "char": "f",
           "description": "Force Stack destruction (skip confirmation)",
           "name": "force",
           "allowNo": false,
@@ -781,8 +909,8 @@
           "type": "boolean"
         },
         "verbose": {
-          "description": "Verbose output",
-          "hidden": true,
+          "char": "v",
+          "description": "Show resource and external IDs",
           "name": "verbose",
           "allowNo": false,
           "type": "boolean"
@@ -855,7 +983,7 @@
           "name": "dir"
         }
       },
-      "description": "A Blueprint is your local infrastructure-as-code configuration that defines Sanity resources (datasets, functions, etc.). A Stack is the remote deployment target where your Blueprint is applied.\n[NOTE: Currently, accounts are limited to three (3) Stacks per project scope.]\n\nThis is typically the first command you run in a new project. It creates a local Blueprint manifest file (sanity.blueprint.ts, .js, or .json) and provisions a new remote Stack.\nAdditionally, a Blueprint configuration file is created in .sanity/ containing the scope and Stack IDs. This is .gitignored by default.\n\nAfter initialization, use 'blueprints plan' to preview changes, then 'blueprints deploy' to apply them.\n\nRunning without a directory prompts to confirm the current directory. Run 'blueprints init .' to initialize in the current directory without a prompt.",
+      "description": "A Blueprint is your local infrastructure-as-code configuration that defines Sanity resources (datasets, functions, etc.). A Stack is the remote deployment target where your Blueprint is applied.\n\nThis is typically the first command you run in a new project. It creates a local Blueprint manifest file (sanity.blueprint.ts, .js, or .json) and provisions a new remote Stack.\nAdditionally, a Blueprint configuration file is created in .sanity/ containing the scope and Stack IDs. A .gitignore covering node_modules, .env, and Function build output is created or updated; the .sanity/ config itself is not ignored.\n\nAfter initialization, use 'blueprints plan' to preview changes, then 'blueprints deploy' to apply them.\n\nRunning without a directory prompts to confirm the current directory. Run 'blueprints init .' to initialize in the current directory without a prompt.",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
         "<%= config.bin %> <%= command.id %> .",
@@ -1132,6 +1260,9 @@
           ],
           "char": "w",
           "description": "Watch for new Stack logs",
+          "exclusive": [
+            "json"
+          ],
           "name": "watch",
           "allowNo": false,
           "type": "boolean"
@@ -1768,11 +1899,12 @@
           "description": "Example to use for the Function",
           "exclusive": [
             "name",
-            "fn-type",
+            "type",
             "language",
             "javascript",
-            "fn-helpers",
-            "fn-installer"
+            "helpers",
+            "installer",
+            "install"
           ],
           "name": "example",
           "hasDynamicHelp": false,
@@ -1803,6 +1935,7 @@
             "media-library-asset-create",
             "media-library-asset-delete",
             "media-library-asset-update",
+            "pub-sub",
             "scheduled-function",
             "sync-tag-invalidate"
           ],
@@ -1856,9 +1989,9 @@
         },
         "install": {
           "char": "i",
-          "description": "Shortcut for --fn-installer npm",
+          "description": "Shortcut for --installer npm",
           "exclusive": [
-            "fn-installer"
+            "installer"
           ],
           "name": "install",
           "allowNo": false,
@@ -2024,9 +2157,9 @@
     "functions:dev": {
       "aliases": [],
       "args": {},
-      "description": "Runs a local, web-based development server to test your functions before deploying.\n\nOpen the emulator in your browser to interactively test your functions with the payload editor.\n\nOptionally, set the host and port with the --host and --port flags. Function timeout can be configured with the --timeout flag.\n\nTo invoke a function with the CLI, use 'functions test'.",
+      "description": "Runs a local, web-based development server to test your functions before deploying.\n\nOpen the emulator in your browser to interactively test your functions with the payload editor.\n\nOptionally, set the host and port with the --host and --port flags. Port 8974 is reserved for the emulator's live-reload WebSocket server. Function timeout can be configured with the --timeout flag.\n\nTo invoke a function with the CLI, use 'functions test'.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --host 127.0.0.1 --port 8974",
+        "<%= config.bin %> <%= command.id %> --host 127.0.0.1 --port 3333",
         "<%= config.bin %> <%= command.id %> --timeout 60"
       ],
       "flags": {
@@ -2410,6 +2543,9 @@
           ],
           "char": "w",
           "description": "Watch for new logs (streaming mode)",
+          "exclusive": [
+            "json"
+          ],
           "name": "watch",
           "allowNo": false,
           "type": "boolean"
@@ -3120,5 +3256,5 @@
       ]
     }
   },
-  "version": "17.4.0"
+  "version": "17.6.0-blueprinit.g77b7a64"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanity/runtime-cli",
   "description": "Sanity's Runtime CLI for Blueprints and Functions",
-  "version": "17.4.0",
+  "version": "17.6.0-blueprinit.g77b7a64",
   "author": "Sanity Runtime Team",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,8 @@
   "files": [
     "./bin",
     "./dist",
+    "./SKILL.md",
+    "./skills",
     "./oclif.manifest.json"
   ],
   "bin": {
@@ -48,7 +50,7 @@
     "lint:fix": "npm run lint:write",
     "prepare": "npm run build",
     "postpack": "shx rm -f oclif.manifest.json",
-    "test": "vitest run && npm run test:depmgmt && npm run lint",
+    "test": "npm run typecheck && vitest run && npm run test:depmgmt && npm run lint",
     "test:depmgmt": "vitest run --config ./test-depmgmt/vitest.config.ts",
     "test:coverage": "vitest run --coverage --coverage.include \"runtime-cli/src/**/*\"",
     "test:scenarios": "vitest run test/scenarios",
@@ -63,19 +65,20 @@
     "@architect/hydrate": "~6.0.2",
     "@architect/inventory": "~6.1.0",
     "@inquirer/prompts": "^8.5.2",
-    "@oclif/core": "^4.13.2",
-    "@oclif/plugin-help": "^6.2.55",
+    "@oclif/core": "^4.13.3",
+    "@oclif/plugin-help": "^6.2.56",
     "@sanity-labs/design-tokens": "^0.0.2-alpha.2",
-    "@sanity/blueprints": "^0.23.1",
+    "@sanity-labs/oclif-plugin-skills-flag": "^0.2.1",
+    "@sanity/blueprints": "^0.23.4",
     "@sanity/blueprints-parser": "^0.4.0",
     "@sanity/cli-build": "^5.1.0",
-    "@sanity/cli-core": "^2.7.1",
-    "@sanity/client": "^7.26.0",
+    "@sanity/cli-core": "^2.8.1",
+    "@sanity/client": "^7.26.2",
     "adm-zip": "^0.6.0",
     "array-treeify": "^0.1.5",
     "cardinal": "^2.1.1",
     "empathic": "^2.0.1",
-    "eventsource": "^4.1.0",
+    "eventsource": "^4.1.1",
     "groq-js": "^2.0.0",
     "jiti": "^2.7.0",
     "mime-types": "^3.0.2",
@@ -84,12 +87,12 @@
     "strip-ansi": "^7.2.0",
     "tar-fs": "^3.1.3",
     "tar-stream": "^3.2.0",
-    "vite": "^8.1.5",
-    "ws": "^8.21.1",
+    "vite": "^8.2.1",
+    "ws": "^8.21.3",
     "xdg-basedir": "^5.1.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.6",
+    "@biomejs/biome": "2.5.7",
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/state": "^6.7.1",
     "@enhance/store": "^1.0.2",
@@ -97,7 +100,7 @@
     "@oclif/test": "^4.1.21",
     "@playwright/test": "^1.62.1",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@sanity/functions": "^1.5.0",
+    "@sanity/functions": "^1.6.0",
     "@types/adm-zip": "^0.5.8",
     "@types/cardinal": "^2.1.1",
     "@types/mime-types": "^3.0.1",
@@ -108,10 +111,10 @@
     "@vitest/coverage-v8": "4.1.10",
     "codemirror": "^6.0.2",
     "mentoss": "^0.13.0",
-    "oclif": "^4.23.29",
+    "oclif": "^4.23.30",
     "pretty-bytes": "^7.1.1",
     "pretty-ms": "^9.3.0",
-    "rollup": "^4.62.3",
+    "rollup": "^4.62.4",
     "shx": "^0.4.0",
     "typescript": "^7.0.2",
     "vitest": "4.1.10"
@@ -121,7 +124,8 @@
     "dirname": "sanity-run",
     "commands": "./dist/commands",
     "plugins": [
-      "@oclif/plugin-help"
+      "@oclif/plugin-help",
+      "@sanity-labs/oclif-plugin-skills-flag"
     ],
     "topicSeparator": " ",
     "topics": {
@@ -133,6 +137,16 @@
       }
     }
   },
+  "oclif-plugin-skills-flag": {
+    "flag": "skill",
+    "aliases": [
+      "agent",
+      "llm",
+      "llms",
+      "skills"
+    ],
+    "directory": "skills"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": false

package/skills/_functions-build.md

@@ -0,0 +1,23 @@
+# `npx @sanity/cli functions build`
+
+Build local Functions into zip archives. This command is hidden from generated help; use it when archive artifacts are explicitly needed, not as a required step before `blueprints deploy`.
+
+## Build
+
+Build every local Function in the Blueprint:
+
+```sh
+npx @sanity/cli functions build --json
+```
+
+Build one Function into a chosen directory:
+
+```sh
+npx @sanity/cli functions build process-order --out-dir artifacts/functions --json
+```
+
+Without `--out-dir`, archives are written to `.build/` beside the Blueprint manifest. An existing archive with the same Function name is replaced.
+
+The JSON result contains `built`, `errors`, and `outDir`. A run can succeed when some Functions build and others fail, so inspect `errors` even when the exit code is zero. If every build fails, the command exits with an error.
+
+The `.gitignore` written by `blueprints init` covers `functions/**/.build/`, not the top-level `.build/` these archives land in, so exclude the output directory before committing.

package/skills/_functions-list.md

@@ -0,0 +1,28 @@
+# `npx @sanity/cli functions list`
+
+List Functions deployed in a project or organization scope. This command is hidden from generated help. Results cover the whole scope rather than one Stack; use `blueprints info` for the resources of a single Stack.
+
+## Run
+
+Use the locally configured scope:
+
+```sh
+npx @sanity/cli functions list --json
+```
+
+Select a scope explicitly when working outside a local Blueprint:
+
+```sh
+npx @sanity/cli functions list --project-id PROJECT_ID --json
+npx @sanity/cli functions list --organization-id ORGANIZATION_ID --json
+```
+
+The two flags are mutually exclusive. No Blueprint manifest is required: the scope resolves from those flags, from `SANITY_PROJECT_ID` or `SANITY_ORGANIZATION_ID`, or from `.sanity/blueprint.config.json`, and the command fails with `Missing scope` when none of them do. The scope is sent with the request, so a project and its organization return different sets: scheduled Functions are organization-scoped, every other type is project-scoped.
+
+## Read the result
+
+The JSON result contains `functions`, `scopeType`, and `scopeId`. Each entry carries `id`, `name`, `displayName`, `type`, `runtime`, `status`, `memory`, `storage`, `timeout`, `resourceType`, `resourceId`, `url`, `createdAt`, and `updatedAt`. An empty scope still emits `{"functions": []}` and exits `0`, so check the array length rather than the exit code.
+
+Default output is one line per Function with its name, ID, type, and last update time. `--verbose` (`-v`) instead prints the type, update time, memory, timeout, and event rule of each.
+
+Treat this as an inspection command. `functions logs`, `functions env add`, and `functions env remove` address a Function by its Blueprint resource name resolved through the deployed Stack, not by the `id` shown here.

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.