feat(skills): add vector-ranking skill

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
             "name": "use-crystallize",
             "source": "./use-crystallize",
             "description": "Everything you need to use Crystallize with your agent, skills, agents, commands, hooks and MCP servers.",
-            "version": "3.5.0",
+            "version": "3.6.0",
             "category": "commerce",
             "tags": [
                 "commerce",

README.md

@@ -8,7 +8,7 @@ This repo contains three sub-projects:
 
 | Project        | Path                                       | Description                                                                                                       |
 | -------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| **Skills**     | `use-crystallize/skills/`                  | Markdown-based skill modules for AI agents (query, mutation, content-model, pricing, permissions, etc.)           |
+| **Skills**     | `use-crystallize/skills/`                  | Markdown-based skill modules for AI agents (query, mutation, content-model, pricing, vector-ranking, etc.)        |
 | **MCP Server** | `use-crystallize/mcp-servers/crystallize/` | Cloudflare Workers MCP server providing authenticated access to Crystallize APIs                                  |
 | **Docs**       | `docs/`                                    | Astro Starlight documentation site deployed to [crystallizeapi.github.io/ai](https://crystallizeapi.github.io/ai) |
 
@@ -57,7 +57,7 @@ bun type-check      # TypeScript type checking
 
 Skills are plain markdown files in `use-crystallize/skills/` — no build step required. Each skill has a `SKILL.md` with YAML frontmatter and an optional `references/` directory with supporting docs.
 
-Available skills: `content-model`, `data-creation`, `information-architecture`, `js-api-client`, `mass-operations`, `mutation`, `permissions`, `plugins`, `pricing`, `query`, `taxonomy` — the directory itself is the authoritative list.
+Available skills: `content-model`, `data-creation`, `information-architecture`, `js-api-client`, `mass-operations`, `mutation`, `permissions`, `plugins`, `pricing`, `query`, `taxonomy`, `vector-ranking` — the directory itself is the authoritative list.
 
 ## Using the Claude Plugin
 

use-crystallize/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "use-crystallize",
-    "version": "3.5.0",
+    "version": "3.6.0",
     "description": "Everything you need to use Crystallize with your agent, skills, agents, commands, hooks and MCP servers.",
     "author": {
         "name": "Crystallize",

use-crystallize/skills/mutation/SKILL.md

@@ -191,3 +191,9 @@ If the user is working in a JS/TS project, prefer generating code using `@crysta
 - [Core API Mutations](references/core-api.md) - Item CRUD, variants, components, customers, publish/unpublish, delete, media uploads
 - [Shop API Cart Mutations](references/shop-api-mutations.md) - Cart hydration, item management, checkout flow, cart lifecycle
 - [Shop API Order Mutations](references/shop-api-order-mutations.md) - Order creation (from cart or direct), payments, pipelines, metadata
+
+## Related skills
+
+[[query]] covers reads across the same APIs. For bulk writes that would otherwise hit rate limits, use
+[[mass-operations]]. Vector ranking has its own Core API mutations — `upsertVocabulary`, `setItemTaste`
+and `igniteDiscoApi` — documented in [[vector-ranking]].

use-crystallize/skills/mutation/references/core-api.md

@@ -13,6 +13,7 @@ See [SKILL.md](../SKILL.md) for endpoint URLs and authentication headers.
 - [Order Mutations](#order-mutations) - Update order metadata
 - [Media & Images](#media--images) - Upload images for items and variants
 - [Flow Mutations](#flow-mutations) - Manage item workflows
+- [Vector Ranking Mutations](#vector-ranking-mutations) - Vocabularies, item taste, re-indexing
 - [Error Handling](#error-handling)
 
 ---
@@ -555,6 +556,70 @@ mutation SetFlowStage {
 
 ---
 
+## Vector Ranking Mutations
+
+Discovery's vector ranking is authored entirely on the Core API. Four calls, in this order:
+
+| Mutation                                          | Notes                                                                                                                          |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `upsertVocabulary(input: UpsertVocabularyInput!)` | **Full replace**, not a patch — omitted dimensions are dropped                                                                 |
+| `setItemTaste(input: SetItemTasteInput!)`         | One item, one language, one vocabulary. Writes the **draft**                                                                   |
+| `publishItems(ids: [ID!]!, language: String!)`    | The indexer reads the published version — skipping this fails silently                                                         |
+| `igniteDiscoApi(stacks: opensearch)`              | Async; poll `bulkTask(id:)` until `complete`, then allow propagation. `stacks: opensearch` is required for vectors to be built |
+
+```graphql
+mutation UpsertVocabulary($input: UpsertVocabularyInput!) {
+    upsertVocabulary(input: $input) {
+        name
+        dimensions {
+            id
+            weight
+        }
+        lastUpdated
+    }
+}
+
+mutation SetItemTaste($input: SetItemTasteInput!) {
+    setItemTaste(input: $input) {
+        __typename
+        ... on Product {
+            id
+        }
+        ... on BasicError {
+            errorName
+            message
+        }
+    }
+}
+
+mutation Index {
+    igniteDiscoApi(stacks: opensearch) {
+        __typename
+        ... on BulkTaskIgnition {
+            id
+            type
+            status
+            createdAt
+        }
+        ... on BasicError {
+            errorName
+            message
+        }
+    }
+}
+```
+
+All three results are unions whose error members implement `BasicError`, so a single fragment covers
+every failure and `errorName` identifies it. `setItemTaste` and `igniteDiscoApi` can both return
+`ExperimentalFeaturesNotAvailableError`, which means vectors are not enabled for the tenant.
+
+Read back with `vocabulary(name:)` and `item(id:, language:) { taste { vocabulary entries { key weight } } }`.
+
+**Re-run `igniteDiscoApi` after every change to vocabularies or taste entries** — an unindexed change
+has no effect and raises no error. Omitting `stacks: opensearch` likewise fails silently: the index
+rebuilds, but without vectors. Full guidance, including vocabulary design, positional weights and
+key validation, is in the [[vector-ranking]] skill.
+
 ## Error Handling
 
 The Core API uses union return types. Always handle potential errors:

use-crystallize/skills/query/SKILL.md

@@ -26,6 +26,8 @@ Before writing queries, understand the context. Ask clarifying questions:
 - Know the exact path? Need strong consistency? → **Catalogue API**
 - Admin interface? Orders, customers, shapes? → **Core API**
 - Cart/checkout operations? → **Shop API**
+- Need results _ordered_ by relevance rules, personalization, or similarity? → **Discovery API** with
+  `rankBy` / `context` / `nearestTo` — see [[vector-ranking]]
 
 ## How It Works
 
@@ -114,7 +116,9 @@ The Discovery API is the primary API for frontend development. It supports:
 - Faceted navigation
 - Sorting and cursor-based pagination
 
-The Discovery API has two entry points: `search` for full-text queries with facets, and `browse` for shape-typed access where each shape becomes its own query type.
+The Discovery API has three entry points: `search` for full-text queries across all shapes, `browse` for shape-typed access where each shape becomes its own query type, and `autocomplete` for type-ahead on `name`. A fourth query, `topics`, walks the topic map.
+
+**The Discovery schema is generated per tenant** from its shapes and index settings — filter, facet and sort fields differ between tenants, and ranking arguments exist only on tenants served for ranking. Introspect rather than assume.
 
 > **Note**: The Discovery API uses lowercase type names in inline fragments (`... on product`, `... on category`) because types are derived from your shape identifiers. You can still use it for interface (`... on Product`, `... on Folder`).
 
@@ -226,11 +230,18 @@ query {
 5. **Handle async updates** - Discovery API may have sub-second delay for recently published content
 6. **Protect APIs in production** - Configure authentication for sensitive data
 7. **Use Core API for complex filters** - Only Core API supports filtering orders by customer, SKU, payment provider
+8. **Detect the Discovery schema, don't hardcode it** - Filter/sort/facet fields and the ranking arguments are tenant-generated; introspect before building a query
 
 ## References
 
 - [Core API Queries Reference](references/core-api.md) - Items, customers, orders, shapes with advanced filtering
-- [Discovery API Reference](references/discovery-api.md) - Detailed search, filter, and faceting documentation
+- [Discovery API Reference](references/discovery-api.md) - Search, browse, autocomplete, filters, facets, sorting, fuzzy matching, pagination and profiling
 - [Catalogue API Reference](references/catalogue-api.md) - Path-based query documentation
 - [Shop API Queries Reference](references/shop-api-queries.md) - Cart and checkout query documentation (`/cart` endpoint)
 - [Shop API Order Queries Reference](references/shop-api-order-queries.md) - Order queries by ID or customer (`/order` endpoint)
+
+## Related skills
+
+Reading is only half of it — [[mutation]] covers writes across the same APIs, and [[js-api-client]]
+wraps all of them for JS/TS. For ranking Discovery results by relevance rules, a shopper's taste, or
+similarity to another item, use [[vector-ranking]].