fix: correct buggy example code in skills, standardize CLI command form (#55)

madikarizma · runeb · Copilot · web-flow · commit fc0e709f61be · 2026-07-28T12:51:15.000-07:00
* fix: correct buggy example code in skill references Several reference examples contain code an agent would copy verbatim but that doesn't behave as intended: content-experimentation-best-practices/references/cms-integration.md - assignVariant drew Math.random() * 100 without normalizing against the sum of variant weights, so weights that don't total 100 skew the split - it reused a cached cookie value without checking it's still a valid variant, leaving users bucketed to removed/renamed IDs - it assumed a non-empty variants array (variants[length - 1] throws on []) - the GROQ example filtered experimentVariants only by experiment status, so the first running experiment won regardless of the user's assignment; now scoped by experimentId plus the assigned variantId sanity-best-practices/references/migration-html-import.md - the custom <a> deserializer returned a top-level _type: 'link' block; htmlToBlocks expects an __annotation with a markDef and children from next(), matching portable-text-conversion/rules/html-to-pt.md sanity-best-practices/references/functions.md - the auto-tag function listened on create/update and wrote to tags with no guard, re-triggering itself in a loop; added !defined(tags) to the filter, mirroring the recursion guard in the translation example * fix: more buggy example code in skill references Second batch of fixes from automated review (Cursor Bugbot): - cms-integration.md: the assignVariant fallback returned the last variant without calling setCookie, so visitors who hit that path (stale/invalid cookie, zero total weight) were re-bucketed on every request; persist it - functions.md: the step-by-step 'Creating a Function' tutorial filtered on _type == "post" while its handler patches the same document — add the !defined(firstPublished) recursion guard the file itself prescribes - angular.md: the Transfer State snippet had literal '+' diff markers pasted in, making it invalid TypeScript; strip them and hoist the imports * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * fix: address Copilot review findings in skill examples - migration-html-import: guard `el.tagName` with optional chaining so the custom rules fall through for non-element nodes (text nodes) instead of throwing, matching portable-text-conversion/rules/html-to-pt.md. - angular: widen the TransferState key to `ClientReturn<Query> | null` so `get(key, null)` type-checks against Angular's `get<T>(key: StateKey<T>, defaultValue: T): T`. * fix: guard null href/src in htmlToBlocks deserializer examples `getAttribute` returns null for a missing attribute, so the examples could emit `href: null` markDefs and the literal string `image@null` — the latter only fails later at asset-upload time, with no pointer back to the bad node. Both rules now read the attribute once and fall through when it is absent, so the surrounding text is still deserialized by the default handling. Applies the same fix to portable-text-conversion/rules/html-to-pt.md, which carried the identical `image@null` bug. * docs: scope _sanityAsset examples to the NDJSON import path `_sanityAsset` is resolved by the CLI importer, which fetches each `image@<url>` and swaps in a real asset reference. The mutation API does not interpret it, so the same blocks written via @sanity/client, `sanity exec`, or `defineMigration` are stored verbatim, leaving an image field with no `asset` reference. Neither example said so, and migration-html-import.md labelled the directive "Upload image separately, store reference" — a description of the client-upload path it is not. It then went on to demonstrate `defineMigration`, the very path where the directive is inert. Name the supported path at both call sites, add a note pointing at the upload-first alternative, and flag the constraint in the `defineMigration` section. Refs: https://www.sanity.io/docs/content-lake/importing-data * docs: use canonical plural CLI topics throughout The skills used both forms: `sanity dataset import` / `schema deploy` / `migration run` alongside `blueprints *` / `functions *`. Standardize on the plural form. Plural is the canonical topic in @sanity/cli 7.x — registered in oclif.config.js and backed by dist/commands/<topic>/, so oclif dispatches it directly. Singular resolves only by missing oclif lookup and landing in the command_not_found hook, which rewrites it via topicAliases. That shim works today and is silent, but it is a compatibility path, and it is not what the docs show. Covers dataset -> datasets, schema -> schemas, migration -> migrations. `blueprints` and `functions` were already plural. --------- Co-authored-by: Rune Botten <rbotten@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
diff --git a/AGENTS.md b/AGENTS.md
@@ -9,8 +9,8 @@ This is a Sanity-powered project. Use the Knowledge Router below to find Sanity
 npx sanity@latest mcp configure  # Configure MCP for your AI editor
 
 # Schema & Types
-npx sanity schema deploy     # Deploy schema to Content Lake for MCP/editor access
-npx sanity schema extract    # Extract schema for TypeGen
+npx sanity schemas deploy     # Deploy schema to Content Lake for MCP/editor access
+npx sanity schemas extract    # Extract schema for TypeGen
 npx sanity typegen generate  # Generate TypeScript types
 
 # Development
diff --git a/commands/deploy-schema.md b/commands/deploy-schema.md
@@ -18,7 +18,7 @@ Schema deployment is **required** for:
 ## Deployment Command
 
 ```bash
-npx sanity schema deploy
+npx sanity schemas deploy
 ```
 
 ## What I'll Do
@@ -29,7 +29,7 @@ npx sanity schema deploy
    - Warn about removed fields with data
 
 2. **Deploy**
-   - Run `npx sanity schema deploy`
+   - Run `npx sanity schemas deploy`
    - Confirm success
 
 3. **Post-Deploy Verification**
diff --git a/commands/typegen.md b/commands/typegen.md
@@ -12,7 +12,7 @@ I'll help you generate TypeScript types from your Sanity schema.
 ```bash
 npm run typegen
 # or
-npx sanity schema extract && npx sanity typegen generate
+npx sanity schemas extract && npx sanity typegen generate
 ```
 
 ## What I'll Do
diff --git a/skills/content-experimentation-best-practices/references/cms-integration.md b/skills/content-experimentation-best-practices/references/cms-integration.md
@@ -133,33 +133,60 @@ defineField({
 ### 3. Frontend Assignment
 
 ```typescript
-// Middleware or server-side
-function assignVariant(experimentId: string, variants: Variant[]): string {
-  // Check for existing assignment in cookie
+// Middleware or server-side. Returns the assigned variant id, or null when the
+// experiment has no variants to assign.
+function assignVariant(experimentId: string, variants: Variant[]): string | null {
+  if (variants.length === 0) return null
+
+  // Reuse an existing assignment, but only if it's still a valid variant.
+  // After variants are renamed or removed, drop the stale cookie and reassign,
+  // otherwise users stay bucketed to IDs that no longer exist.
   const cookieKey = `exp_${experimentId}`
   const existing = getCookie(cookieKey)
-  if (existing) return existing
-  
-  // Random assignment based on weights
-  const rand = Math.random() * 100
+  if (existing && variants.some(v => v.id === existing)) return existing
+
+  // Random assignment based on weights. Normalize against the total weight so
+  // splits work even when weights don't sum to 100 (otherwise draws above the
+  // sum skew to the fallback).
+  const totalWeight = variants.reduce((sum, v) => sum + v.weight, 0)
+  if (totalWeight <= 0) {
+    const fallback = variants[0]
+    setCookie(cookieKey, fallback.id, { maxAge: 30 * 24 * 60 * 60 })
+    return fallback.id
+  }
+  const rand = Math.random() * totalWeight
   let cumulative = 0
   for (const variant of variants) {
     cumulative += variant.weight
-    if (rand <= cumulative) {
+    if (rand < cumulative) {
       setCookie(cookieKey, variant.id, { maxAge: 30 * 24 * 60 * 60 })
       return variant.id
     }
   }
-  return variants[0].id
+  // Fall back to the last variant to absorb any floating-point remainder, and
+  // persist it like any other assignment so the visitor stays bucketed.
+  const fallback = variants[variants.length - 1]
+  setCookie(cookieKey, fallback.id, { maxAge: 30 * 24 * 60 * 60 })
+  return fallback.id
 }
 ```
 
 ### 4. Query with Variant
 
+Resolve **one** experiment's assignment at a time, passing both its
+`experimentId` and the `variantId` returned by `assignVariant`. Match on both:
+variant IDs like `control` repeat across experiments, so filtering on
+`variantId` alone could pick a different running experiment's row. For a page
+running several experiments, resolve each one separately and merge the results.
+
 ```groq
 *[_type == "page" && slug.current == $slug][0]{
   ...,
-  "experiment": experimentVariants[experimentId->status == "running"][0]{
+  "experiment": experimentVariants[
+    experimentId->_id == $experimentId &&
+    experimentId->status == "running" &&
+    variantId == $variantId
+  ][0]{
     experimentId->{name, _id},
     variantId,
     headline
diff --git a/skills/portable-text-conversion/rules/html-to-pt.md b/skills/portable-text-conversion/rules/html-to-pt.md
@@ -114,14 +114,19 @@ const blocks = htmlToBlocks(html, blockContentType, {
       deserialize(el, next, block) {
         if (el.tagName?.toLowerCase() !== 'img') return undefined
 
+        const src = el.getAttribute('src')
+        if (!src) return undefined // skip sourceless images, not `image@null`
+
         return block({
           _type: 'image',
           asset: {
             _type: 'reference',
             _ref: '', // Upload image separately, set ref after
           },
           alt: el.getAttribute('alt') || '',
-          _sanityAsset: `image@${el.getAttribute('src')}`, // for migration tooling
+          // Resolved by `sanity datasets import` only. On client/mutation-API
+          // write paths, upload the asset first and set `asset._ref` instead.
+          _sanityAsset: `image@${src}`,
         })
       },
     },
@@ -233,7 +238,7 @@ export default defineMigration({
 })
 ```
 
-Run with: `sanity migration run import-wordpress-posts --no-dry-run`
+Run with: `sanity migrations run import-wordpress-posts --no-dry-run`
 
 ## Reference
 
diff --git a/skills/sanity-best-practices/references/angular.md b/skills/sanity-best-practices/references/angular.md
@@ -442,39 +442,40 @@ Key considerations for Sanity + Angular SSR:
 Angular's built-in HTTP Transfer Cache does not cover `@sanity/client` requests. Without manual transfer, the client re-fetches every query during hydration. Add `TransferState` to the service from Section 2:
 
 ```typescript
-+ async function hashQuery(query: string, params?: QueryParams): Promise<string> {
-+   const input = query + JSON.stringify(params ?? {})
-+   const buffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input))
-+   return Array.from(new Uint8Array(buffer), b => b.toString(16).padStart(2, '0')).join('')
-+ }
-
-import { Injectable, inject } from '@angular/core'
-+ import { isPlatformBrowser, isPlatformServer } from '@angular/common'
-+ import { PLATFORM_ID, makeStateKey, TransferState } from '@angular/core'
+import { Injectable, inject, PLATFORM_ID, makeStateKey, TransferState } from '@angular/core'
+import { isPlatformBrowser, isPlatformServer } from '@angular/common'
 import { createClient, type ClientReturn, type QueryParams, type SanityClient } from '@sanity/client'
 
+async function hashQuery(query: string, params?: QueryParams): Promise<string> {
+  const input = query + JSON.stringify(params ?? {})
+  const buffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input))
+  return Array.from(new Uint8Array(buffer), b => b.toString(16).padStart(2, '0')).join('')
+}
+
 export class SanityService {
   private client: SanityClient
-+  private transferState = inject(TransferState)
-+  private platformId = inject(PLATFORM_ID)
+  private transferState = inject(TransferState)
+  private platformId = inject(PLATFORM_ID)
 
   async fetch<Query extends string>(query: Query, params?: QueryParams): Promise<ClientReturn<Query>> {
-+    const key = makeStateKey<ClientReturn<Query>>(await hashQuery(query, params))
-+
-+    if (isPlatformBrowser(this.platformId)) {
-+      const cached = this.transferState.get(key, null)
-+      if (cached !== null) {
-+        this.transferState.remove(key)
-+        return cached
-+      }
-+    }
-+
+    // The key type includes `null` so `get(key, null)` type-checks against
+    // Angular's `get<T>(key: StateKey<T>, defaultValue: T): T` signature.
+    const key = makeStateKey<ClientReturn<Query> | null>(await hashQuery(query, params))
+
+    if (isPlatformBrowser(this.platformId)) {
+      const cached = this.transferState.get(key, null)
+      if (cached !== null) {
+        this.transferState.remove(key)
+        return cached
+      }
+    }
+
     const result = await this.client.fetch(query, params)
-+
-+    if (isPlatformServer(this.platformId)) {
-+      this.transferState.set(key, result)
-+    }
-+
+
+    if (isPlatformServer(this.platformId)) {
+      this.transferState.set(key, result)
+    }
+
     return result
   }
 }
diff --git a/skills/sanity-best-practices/references/functions.md b/skills/sanity-best-practices/references/functions.md
@@ -94,7 +94,10 @@ export default defineBlueprint({
       name: 'my-function',
       event: {
         on: ['create', 'update'],
-        filter: '_type == "post"',
+        // The handler patches the same document, which emits another update
+        // event. Guard with !defined(firstPublished) so the function stops
+        // matching once it has run — see "Recursion control" below.
+        filter: '_type == "post" && !defined(firstPublished)',
       },
     }),
   ],
@@ -460,7 +463,10 @@ defineDocumentFunction({
   name: 'auto-tag',
   event: {
     on: ['create', 'update'],
-    filter: "_type == 'post'",
+    // Only fire while tags are missing. The handler writes to `tags`, which
+    // emits another `update` event — without this guard the function would
+    // re-trigger itself in a loop. Once tags exist, the filter stops matching.
+    filter: "_type == 'post' && !defined(tags)",
     projection: '{_id, title, body}',
   },
 })
diff --git a/skills/sanity-best-practices/references/get-started.md b/skills/sanity-best-practices/references/get-started.md
@@ -97,7 +97,7 @@ export const post = defineType({
 **Required before Phase 2:**
 
 ```bash
-npx sanity schema deploy
+npx sanity schemas deploy
 ```
 
 This uploads your schema to the Content Lake so MCP tools can work with it.
@@ -137,7 +137,7 @@ Tool: create_documents
 Documents: [{ type: "post", content: { title: "Getting started with Sanity", body: [] } }]
 ```
 
-**If MCP content tools cannot see new types or fields:** Remind them to run `npx sanity schema deploy` first.
+**If MCP content tools cannot see new types or fields:** Remind them to run `npx sanity schemas deploy` first.
 
 ### MCP Setup (If Not Configured)
 
@@ -385,7 +385,7 @@ Just ask about any of these!"
 ```bash
 npx sanity@latest mcp configure  # Configure MCP for your editor
 npx sanity dev                   # Start Studio locally
-npx sanity schema deploy         # Deploy schema for MCP/editor access
+npx sanity schemas deploy         # Deploy schema for MCP/editor access
 npx sanity deploy                # Deploy Studio to Sanity hosting
 npx sanity manage                # Open project settings
 npm run typegen                  # Generate TypeScript types
diff --git a/skills/sanity-best-practices/references/migration-html-import.md b/skills/sanity-best-practices/references/migration-html-import.md
@@ -37,21 +37,35 @@ const blocks = htmlToBlocks(htmlString, blockContentType, {
   rules: [
     {
       deserialize(el, next, block) {
-        // Custom link handling
-        if (el.tagName.toLowerCase() === 'a') {
+        // Custom link handling — links are inline annotations, not blocks.
+        // Return an `__annotation` with a `markDef`, and recurse into the
+        // child nodes via `next()` so the link text is preserved.
+        if (el.tagName?.toLowerCase() === 'a') {
+          const href = el.getAttribute('href')
+          // An anchor with no `href` (named anchors, JS-driven links) isn't a
+          // link. Fall through so the text survives without a dangling markDef.
+          if (!href) return undefined
           return {
-            _type: 'link',
-            href: el.getAttribute('href'),
-            blank: el.getAttribute('target') === '_blank'
+            _type: '__annotation',
+            markDef: {
+              _type: 'link',
+              href,
+              blank: el.getAttribute('target') === '_blank'
+            },
+            children: next(el.childNodes)
           }
         }
-        // Custom image handling
-        if (el.tagName.toLowerCase() === 'img') {
-          return {
+        // Custom image handling — block-level types are wrapped with `block()`
+        if (el.tagName?.toLowerCase() === 'img') {
+          const src = el.getAttribute('src')
+          // Skip sourceless images rather than emitting `image@null`, which
+          // the importer reports as a failed asset with no pointer to the node.
+          if (!src) return undefined
+          return block({
             _type: 'image',
-            // Upload image separately, store reference
-            _sanityAsset: `image@${el.getAttribute('src')}`
-          }
+            // NDJSON + `sanity datasets import` only — see the note below.
+            _sanityAsset: `image@${src}`
+          })
         }
         return undefined  // Fall through to default handling
       }
@@ -60,6 +74,14 @@ const blocks = htmlToBlocks(htmlString, blockContentType, {
 })
 ```
 
+> **`_sanityAsset` is only resolved by `sanity datasets import`.** The NDJSON
+> importer fetches each `image@<url>` and swaps in a real asset reference. The
+> mutation API does not interpret the directive, so the same blocks written
+> through `@sanity/client`, `sanity exec`, or `defineMigration` are stored
+> verbatim — leaving an image field with a stray `_sanityAsset` string and no
+> `asset` reference. On those paths, upload the image first and emit an asset
+> reference instead, as in [Image Upload](#image-upload) below.
+
 ### Pre-Processing HTML
 
 Clean HTML before conversion:
@@ -105,7 +127,9 @@ async function uploadImage(client, imageUrl) {
 
 ### Using in a Migration
 
-Wrap this in `defineMigration` for controlled imports:
+Wrap this in `defineMigration` for controlled imports. This path writes through
+the mutation API, so any custom rules used here must emit uploaded asset
+references rather than `_sanityAsset` directives:
 
 ```typescript
 // migrations/import-wordpress-posts/index.ts
@@ -136,6 +160,6 @@ export default defineMigration({
 
 Let Sanity generate document IDs for ordinary imported content. Add schema fields for legacy identifiers or slugs, then use GROQ lookups against those fields when you need to rerun an import, patch existing documents, or create references between imported records. Set `_id` directly only for singleton documents.
 
-Run with: `sanity migration run import-wordpress-posts --no-dry-run`
+Run with: `sanity migrations run import-wordpress-posts --no-dry-run`
 
 Reference: [Schema and Content Migrations](https://www.sanity.io/docs/content-lake/schema-and-content-migrations)
diff --git a/skills/sanity-best-practices/references/schema.md b/skills/sanity-best-practices/references/schema.md
@@ -313,10 +313,10 @@ export default defineMigration({
 
 ```bash
 # Dry run first (default)
-sanity migration run rename-oldTitle-to-newTitle
+sanity migrations run rename-oldTitle-to-newTitle
 
 # Execute when ready
-sanity migration run rename-oldTitle-to-newTitle --no-dry-run
+sanity migrations run rename-oldTitle-to-newTitle --no-dry-run
 ```
 
 **Phase 3: Remove** — Once `oldTitle` is undefined for all documents, delete the field definition.
diff --git a/skills/sanity-best-practices/references/typegen.md b/skills/sanity-best-practices/references/typegen.md
@@ -29,7 +29,7 @@ Run the extract + generate cycle whenever schema or queries change:
 2.  **Generate:** Scans your codebase for GROQ queries and generates TypeScript types.
 
 ```bash
-npx sanity schema extract && npx sanity typegen generate
+npx sanity schemas extract && npx sanity typegen generate
 ```
 
 ### Watch Mode (for separate frontends)
@@ -45,7 +45,7 @@ For manual workflows, implement a single script:
 **package.json:**
 ```json
 "scripts": {
-  "typegen": "sanity schema extract && sanity typegen generate"
+  "typegen": "sanity schemas extract && sanity typegen generate"
 }
 ```
 
@@ -147,7 +147,7 @@ export default function Author({ data }: { data: AUTHOR_QUERYResult }) {
 Use `--enforce-required-fields` during extraction to translate `validation: rule => rule.required()` into non-optional types:
 
 ```bash
-npx sanity schema extract --enforce-required-fields
+npx sanity schemas extract --enforce-required-fields
 npx sanity typegen generate
 ```
 
diff --git a/skills/sanity-migration/SKILL.md b/skills/sanity-migration/SKILL.md
@@ -35,7 +35,7 @@ For implementation or planning tasks, produce these artifacts or explain why the
 ## Defaults
 
 - Use stable document IDs derived from source IDs, slugs, paths, or hashes.
-- Use `createOrReplace`, `createIfNotExists`, or `sanity dataset import --replace` so reruns converge.
+- Use `createOrReplace`, `createIfNotExists`, or `sanity datasets import --replace` so reruns converge.
 - Snapshot extracted source data to disk before transforming it.
 - Import or create referenced documents before documents that reference them.
 - Convert rich text to Portable Text instead of storing raw HTML or Markdown strings.
diff --git a/skills/sanity-migration/references/contentful.md b/skills/sanity-migration/references/contentful.md
@@ -49,7 +49,7 @@ Typical workflow:
 npm create sanity@latest -- --template clean --create-project "Migrated Contentful" --dataset production --output-path ./migrate
 npx contentful-to-sanity@latest -s <space-id> -t <management-token> -a <delivery-token> ./migrate
 cd ./migrate
-npx sanity dataset import ./dataset.ndjson production
+npx sanity datasets import ./dataset.ndjson production
 ```
 
 If the generated Studio imports schemas from `./schemas`, update it to use the generated schema export from `./schema` as instructed by the package output.
diff --git a/skills/sanity-migration/references/general.md b/skills/sanity-migration/references/general.md
diff --git a/skills/sanity-migration/references/markdown.md b/skills/sanity-migration/references/markdown.md
