[papelipe]

Q	A
Branch?	main
Bug fix?	no
New feature?	yes
BC breaks?	no
Fixed tickets	#...

Adds a vector-ranking skill covering Discovery vector ranking, and refreshes the Discovery query reference, which had drifted from the served schema.

Why its own skill

Vector ranking spans two APIs — vocabularies and item taste are authored on Core, ranking happens on Discovery — so splitting it across query and mutation would have left the flow without a single narrative. It also has a modelling dimension (designing a vocabulary) closer to taxonomy than to either, and its trigger vocabulary ("personalization", "more like this", "boost by margin", "recommendations") would never have matched query.

What's in it

File	Covers
SKILL.md	Capability detection, the two APIs, five concepts, the pipeline, choosing a query path, failure modes
references/vocabulary-authoring.md	Vocabulary design, positional weights, upsertVocabulary, setItemTaste, key validation, publish, ignite, verification
references/ranking-signals.md	The five rankBy signals, per-tenant field enums, normalization, multi-value collapse, rankScore/rankExplain, rerank window
references/personalization.md	context.userTaste, magnitude, sourcing the shopper vector, blending, nearestTo

query and mutation get ## Related skills pointers, and mutation/references/core-api.md gains a Vector Ranking Mutations section so the Core calls are findable from where they live.

Verified against the API, not just the docs

Everything was checked by introspecting the live Core API and a ranking-enabled Discovery tenant. That surfaced several things the documentation omits or states loosely:

• RankExplainEntry carries index — without it you cannot tell two fieldBoost terms apart.
• fieldBoost.field is the TenantRankByField enum (NUMBER/DATE filterable attributes, facet fields excluded), not "any numeric field". Guessing a field name fails validation.
• igniteDiscoApi takes stacks, and vectors are only built with stacks: opensearch. Omitting it rebuilds the index without vectors and raises no error, so it is documented as a required step and as its own row in the failure-mode table.
• IgnitionBulkTaskResult and SetItemTasteResult both include ExperimentalFeaturesNotAvailableError, which appears in neither doc version.
• Under rerank, cursor pagination falls back to offset, and a skip past the rerank window returns nothing.

The skill leads with capability detection: rankBy, context and nearestTo are absent from a tenant's Discovery schema until ranking is enabled, so referencing them is a GraphQL validation error rather than an unranked result. That is the failure an agent is most likely to hit, so it is the first section rather than a footnote.

Where the two public doc pages contradict each other on how sorting composes with ranking, the skill says so and declines to assert either reading.

Discovery reference refresh

query/references/discovery-api.md was missing autocomplete, options.fuzzy, sorting, filter operators, profiling, pathResolutionMethod and priceRange, and did not mention that the schema is generated per tenant. All added.

Notes for the reviewer

• No code changes needed — both the MCP server (virtual:skills) and the docs site discover skills from the filesystem. Plugin version bumped 3.5.0 → 3.6.0 and the README list updated.
• Markdown formatted with the repo's own oxfmt; query/ and mutation/ are back to formatted-clean as they were on main.
• make codeclean's type-check/lint and make tests were not run locally — bun was unavailable in the authoring environment. No TypeScript is touched, so CI should be green, but that is unverified from my side.
• Pre-existing and left alone: mass-operations/* and permissions/SKILL.md are not oxfmt-clean on main, and three relative links are broken (js-api-client ×2, query/references/core-api.md ×1). Happy to fix either in a separate PR.

🤖 Generated with Claude Code