# Enad docs full agent guidance

Generated: 2026-04-25T12:40:51.965Z

Use this bundle when an agent needs the full guidance set. Use /docs.zip for a downloadable archive. Exact SDK/API facts remain authoritative in SDK package reference and API/OpenAPI reference.

## Route readiness

- Start, SDKs, APIs, Search, Media, Events, Integrations, Agent guides, Reference, and Blog routes are present.
- Use route guides for orientation and the matching SDK, API, Search, Media, Events, or package reference for exact names, fields, and behavior.
- Use /ai/manifest.json when a tool needs structured route and version-track metadata.

---

# Agent guides

URL: https://docsv3.enad.io/ai
Kind: guide
Authority: guidance
Domains: ai, docs
Copy-paste safe: guidance-only

# Agent guides

Use this section when an agent needs the right Enad starting point. It covers SDK work, storefront UI, APIs, Search, Media, Events, and version tracks.

## Give agents the right context

- <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a>: short agent index with the safest starting points. Use this first for route choice.
- <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a>: broader agent bundle. Use this when a task spans several Enad areas.
- <a href="/docs.zip" target="_blank" rel="noreferrer"><code>/docs.zip</code></a>: downloadable markdown archive for local grep, embeddings, or offline agent ingestion.
- <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a>: structured route, package-track, version, and copy guidance.
- <a href="/.well-known/agent-skills/index.json" target="_blank" rel="noreferrer"><code>/.well-known/agent-skills/index.json</code></a>: skill discovery for tools that install docs skills.
- [Agent files manifest](/ai/manifest): route and version browser for people reviewing agent inputs.

## Choose one route first

Start with the narrowest agent route that matches the job. Use broader context only when the task spans multiple domains.

For safe context loading, start with [Agent quickstart](/ai/agent-quickstart). It explains which files to give an agent first and which references own exact facts.

For MCP setup, use [MCP server](/ai/mcp-server). It covers the hosted endpoint, Codex connector expectations, OAuth discovery, scopes, app context, and preview/apply workflow.

For app registration metadata, use [Enad app auth.md](/ai/enad-app-authmd). For file selection, use [Agent files](/ai/artifacts) or [Agent files manifest](/ai/manifest).

For prompt shape, use [Prompt recipes](/ai/prompts). For React storefront work, start with [React SDK agent guide](/ai/react-sdk/latest), then narrow to discovery, theming, icons, or commerce handoff routes.

For server-side SDK work, use [TypeScript SDK agent guide](/ai/ts-sdk/latest). For API, OpenAPI, Search GraphQL, Media, or Events routing, use [API and Search agent guide](/ai/apis/latest).

If a task crosses several areas, start with <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> for route choice.

Use <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> only when broader context is needed. Then move to the narrowest route.

## Public docs routes

Use these public routes when connecting packages, prompts, or tooling:

- [React SDK](/react-sdk/latest).
- [React SDK setup](/react-sdk/latest/setup).
- [React product listing and search](/react-sdk/latest/guides/product-listing-search).
- [TypeScript SDK](/ts-sdk/latest).
- [Search GraphQL latest](/search/latest).
- [Search GraphQL reference latest](/reference/search-graphql/latest).
- [APIs](/apis).
- [MCP server](/ai/mcp-server).
- [Media](/media).
- [Events](/events).
- [Integrations](/integrations).
- [Agent guides](/ai).

## Theme and playground usage

Agents should use public consumer surfaces only:

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";
```

Do not copy playground internals into applications. Use providers, theme helpers, generated CSS, documented component-set names, and the public playground export flow.

---

# Agent quickstart

URL: https://docsv3.enad.io/ai/agent-quickstart
Kind: quickstart
Authority: guidance
Domains: ai, docs
Copy-paste safe: prompt-safe

# Agent quickstart

Use this guide when you are asking an agent to work with Enad docs, SDKs, APIs, Search, Media, Events, or theme setup.

## Give the agent these files first

1. <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> for the short routing index. Use it to choose the first route and avoid loading unrelated docs.
2. <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> when the task spans multiple Enad domains or the agent cannot browse route-by-route.
3. <a href="/docs.zip" target="_blank" rel="noreferrer"><code>/docs.zip</code></a> when the agent or tool needs local markdown files for grep, embeddings, or offline ingestion.
4. <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> when the agent or tool can consume structured route data, version tracks, and copy-paste guidance.
5. The reference named by the relevant docs page when exact exports, props, operations, package versions, or API fields matter.

Use the smallest context that can answer the routing question, then add exact reference pages only for reference details.

## Tell the agent the exact reference boundary

Copy these instructions into agent prompts:

- Use Enad docs for route selection.
- Do not invent exact facts from prose.
- Use the owning reference for SDK exports, props, API fields, Search schema, Media fields, event payloads, or package versions.
- Keep live playground internals inside the playground.

## Choose the right agent route

Build storefront UI with [React SDK agent guide](/ai/react-sdk/latest), then verify exact props in [React SDK](/react-sdk/latest).

Call APIs from server code with [TypeScript SDK agent guide](/ai/ts-sdk/latest), then verify methods, types, and versions in [TypeScript SDK](/ts-sdk/latest).

Work with Search through [API and Search agent guide](/ai/apis/latest), then use [Search GraphQL latest](/search/latest). Keep app, market, store-group, and locale context explicit.

Use [API and Search agent guide](/ai/apis/latest) for HTTP APIs and OpenAPI-backed endpoint details. Verify endpoint fields and operations in API/OpenAPI reference before writing code.

Connect or use MCP through [MCP server](/ai/mcp-server). For Codex, use the Enad App or connector OAuth flow when available; raw remote MCP config is not the complete protected-tool setup. Keep app context explicit and route writes through preview/apply.

Use [Media](/media) for Media or DAM concepts. Verify asset schemas and upload contracts in the relevant API reference.

Use [Events](/events) and [Integrations](/integrations) for event or integration work. Preserve delivery boundaries and verify payload fields in Event catalog.

Restore a theme from the playground with [React SDK agent guide](/ai/react-sdk/latest) and [Prompt recipes](/ai/prompts). Use public provider/theme surfaces and keep playground internals in the playground.

## Safe operating rules

- Keep `docs.enad.io` and production `sdk.enad.io` routing unchanged until launch readiness work explicitly changes them.
- Treat agent files as routing guidance, not as endpoint, schema, package, or prop truth.
- Use SDK package reference as the package boundary; do not depend on package README prose for exact facts.
- Prefer public imports from `@enadhq/enad-react-sdk` and `@enadhq/enad-react-sdk/client/theme` when React examples are needed.
- Keep live playground runtime, editor, and export behavior in the playground.
- Record compatibility needs for old `/llms*` URLs instead of deleting or silently replacing them.

## Minimal prompt skeleton

```text
You are working with Enad docs. Start from /llms.txt and /ai/manifest.json. Use /docs.zip when local markdown ingestion or grep is useful. Use /llms-full.txt only when the task spans domains or you need the complete docs bundle. Use Enad docs for guidance and route selection. Use SDK package reference, API/OpenAPI reference, Search reference, or the Event catalog for exact SDK exports, component props, API fields, Search schema details, event payloads, Media contracts, and package versions. Keep docsv3.enad.io and sdk.enad.io production routing unchanged unless the task explicitly says this is a launch-readiness phase.

Task: <describe the Enad SDK/API/Search/Media/Events/theme job>
```

---

# API route guide

URL: https://docsv3.enad.io/ai/apis/latest
Kind: api-guide
Applies to: api-management, api-integrations, api-shopper, api-auth, api-dam, api-media, api-search-graphql, api-events
Version: latest
Authority: guidance
Domains: api, search, graphql, events, media
Exact facts: API endpoint paths, methods, parameters, request bodies, responses, GraphQL fields, generated documents, fragment fields, and event payload facts require OpenAPI, GraphQL schema, package reference, or event catalog sources.
Copy-paste safe: guidance-only

# API route guide

Choose the Enad API, Search, Events, Media, or MCP surface from the job, then open the narrowest page that can verify the detail you need.

## Pick the route first

| Job | Open first |
| --- | --- |
| Storefront discovery, facets, autocomplete, or GraphiQL | [Search GraphQL latest](/search/latest). |
| Search schema fields, operation variables, enum values, or fragments | [Search GraphQL reference latest](/reference/search-graphql/latest). |
| REST method, path, auth, query, body, or response shape | The operation page for the matching API. |
| Webhook delivery, receiver behavior, event names, or payload schema IDs | [Events latest](/events/latest) and [Event catalog](/events/catalog). |
| DAM reads, asset records, or Image Proxy URL building | [Media](/media) or [DAM guide](/media/dam/latest). |
| MCP connection, scopes, context, capability discovery, or preview/apply tools | [MCP server](/ai/mcp-server). |
| Shopper-facing React composition | [React product listing and search](/react-sdk/latest/guides/product-listing-search). |

## Choose where work belongs

| Surface | Use it for | Check |
| --- | --- | --- |
| Management API | Trusted merchant administration and server-side writes. | Management reference. |
| Auth API | Customer identity and account-context state. | Auth reference. |
| Shopper API | Existing public REST catalog reads. Prefer Search for new discovery work. | Shopper reference. |
| Public asset library | Public `dam.enad.io` folder, media-search, and shareable-link reads. | DAM public-read reference. |
| Management DAM | Authenticated folder administration and shareable-link management. | Management DAM reference. |
| Integrations API | Connector records, setup checks, stats, and sync jobs. | Integrations reference. |
| Search GraphQL | App-scoped discovery queries, generated documents, and SDK Search helpers. | Search GraphQL reference and package docs. |
| Events | Webhook routing plus cataloged event names and schemas. | Event catalog. |
| Media/Image Proxy | CDN delivery, transformation parameters, and asset workflow routing. | Media guide and asset references. |

## REST request routing

For a REST API task:

1. Identify the matching API and operation.
2. Check the operation page or API spec before writing request/response code.
3. Keep auth, app context, locale, and runtime placement explicit.
4. Treat guide examples as routing help until a reference confirms the fields.

| Job | Use | Verify before shipping |
| --- | --- | --- |
| Trusted catalog, merchandising, orders, organizations, channels, warehouses, tax, DAM administration, or bulk writes | Management API | Management operation page. |
| Connector records, setup verification, stats, and sync jobs | Integrations API | Integrations operation page. |
| Existing public REST catalog reads | Shopper API | Deprecated REST compatibility reads only. Prefer Search GraphQL for new storefront discovery. |
| Customer identity, sessions, account-owned commerce state, attributes, files, users, or organisations | Auth API | Auth operation page. |
| Public folders, media search, facets, or shareable-link reads | Public asset-library API | DAM public-read operation page using `dam.enad.io` `app_id` routes. |

Management calls run with team/app context and a bearer token for the selected app. Keep them server-side. Auth calls are app-scoped before they act on identity or account state. Shopper REST covers existing public-read catalog compatibility; prefer Search GraphQL for new discovery, listing, facets, autocomplete, category, collection, and redirect work.

Use Management DAM for trusted folder administration, media placement, roles, operator search, and shareable-link administration. Use public asset-library routes only for folder, media, facet, and share-token reads through `dam.enad.io` app routes.

## Events and media boundary

For connector setup, use the [partner and AI guides](/integrations#partner-and-ai-guides). For storefront cache refresh, use [Revalidate](/integrations/revalidate) and its [Admin setup guide](/integrations/revalidate/admin). Read [Product and market status](/start/concepts/product-status) and [Merchant users](/start/concepts/merchant-users) when routing publication or customer-identity work.

Use [Events latest](/events/latest) for webhook delivery, receiver design, retry behavior, delivery states, custom-header authentication, and webhook `enabled_events` values. Use [Event catalog](/events/catalog) for exact event type strings, envelopes, schema IDs, and payload fields. Revalidation payload examples are compatibility guidance, not the Event catalog's webhook schema.

Use [Integrations](/integrations) and [Integrations reference](/reference/integrations) for connector records, setup checks, sync jobs, sync status, and sync stop behavior. Keep connector configuration separate from webhook delivery.

Use [Media](/media) to choose between DAM reads, asset records, and Image Proxy request-building. Media CDN transformations, validation ranges, response classes, delete cleanup behavior, and cache-purge requests are documented behavior. Cache-key construction, cache retention, edge freshness timing, purge completion timing, and every-edge invalidation are not public contracts.

## MCP architecture boundary

Treat MCP as an orchestration and policy layer over Enad platform contracts. Do not use MCP as a shortcut around endpoint, schema, package, Search, or event references.

Use [MCP server](/ai/mcp-server) for hosted endpoint setup, OAuth discovery, public docs tools, delegated bearer authentication, supported scopes, context switching, capability discovery, and preview/apply behavior.

## MCP write routing

Use MCP for governed changes after you know which API surface owns the resource.

| Work | First route | Verify exact contract |
| --- | --- | --- |
| Catalog metadata, taxonomy, attributes, relationships, markets, store groups, schedules, channels, redirects, or static listings | `search_capabilities` with `catalog`, `routing`, or `merchandising` namespaces | Management reference and the matching concept page. |
| Variant lifecycle, variant groups, base prices, warehouse stock, warehouses, or bundles | `search_capabilities` with `catalog` or `commerce` namespaces | [Products, variants, variant groups, prices, and stock](/start/concepts/products-variants-prices-and-stock), [Variant groups](/start/concepts/variant-groups), bundle references, and warehouse references. |
| DAM folders, shareable links, media placement, media metadata, upload URL generation, or media deletion | `search_capabilities` with `media` namespace | [Media](/media), [Asset library reads and DAM administration](/media/dam/latest), and DAM/media references. |
| Identity, organisations, customer-owned carts, wishlists, saved carts, customer files, roles, customer groups, or orders | `search_capabilities` with `identity` or `customer` namespaces | Auth, Management, customer-group, order, cart, wishlist, organisation, user, and merchant-user references. |

Capability status is the execution gate. Only `implemented` capabilities with concrete preview/apply tool names are executable write workflows. `descriptor-only`, `deferred`, `blocked`, and `out-of-scope` entries are discovery or proof-gate metadata.

MCP input fields are tool-input bounds, not raw REST request bodies. REST/OpenAPI reference remains endpoint truth for paths, fields, limits, status codes, and response shapes. Destructive or approval-backed changes need the MCP preview/apply lifecycle and post-apply verification through the owning read surface.

## Search GraphQL boundary

Use [Search GraphQL latest](/search/latest) for app-scoped Search GraphQL, GraphiQL, query shape, category or collection targeting, facets, autocomplete, Search documents, or Search-backed SDK behavior. For exact schema, operation, and fragment truth, open [Search GraphQL reference latest](/reference/search-graphql/latest), `/graphql/search-schema.graphql`, or `/graphql/search-documents.graphql`.

Keep app, market, store-group, and locale context explicit. Do not copy Search GraphQL filter objects into Shopper REST query strings. Package-provided Search work should start with `@enadhq/enad-ts-sdk/search` and `createSearchClient()`. Generated documents and types remain available when no named convenience method exists.

For shopper-facing PLP/search composition, open [React product listing and search](/react-sdk/latest/guides/product-listing-search).

## Prompt skeleton

```text
Choose the Enad API, Search, Events, Media, or MCP surface from the job. Verify exact endpoints in API/OpenAPI references, Search fields in Search reference, and event payloads in the Event catalog. Keep app, market, store-group, locale, auth, and runtime placement explicit. Use @enadhq/enad-ts-sdk/search and createSearchClient() for package-backed Search work when those helpers fit.
```

---

# Agent files

URL: https://docsv3.enad.io/ai/artifacts
Kind: agent-file-guide
Authority: guidance
Domains: ai, docs
Copy-paste safe: guidance-only

# Agent files

Start here when a person, tool, or agent needs to choose the right Enad file before opening SDK, API, Search, Media, Events, or integration docs.

## Choose the file

Use <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> for short route selection and the smallest safe starting points. Do not use it for full SDK or API detail.

Use <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> when the task spans multiple Enad areas. Do not use it as exact package, endpoint, or GraphQL field truth.

Use <a href="/docs.zip" target="_blank" rel="noreferrer"><code>/docs.zip</code></a> when a tool needs the generated agent files and public AI guidance pages as a local markdown archive for grep, embeddings, or offline ingestion.

Use <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> for structured route data, version tracks, and copy guidance. Do not treat it as a replacement for package docs, OpenAPI, Search reference, or event catalog.

Use <a href="/.well-known/agent-skills/index.json" target="_blank" rel="noreferrer"><code>/.well-known/agent-skills/index.json</code></a> when an agent runtime can install a docs skill through discovery. Legacy clients can read <a href="/.well-known/skills/index.json" target="_blank" rel="noreferrer"><code>/.well-known/skills/index.json</code></a>.

Start with the smallest file that answers the routing question. Move to the larger bundle only when the task spans multiple domains.

## What agents can rely on

The public agent files are routing aids. They include:

- stable docs routes that help agents choose the right surface.
- version-track data for supported packages and APIs.
- reference hints for SDK packages, APIs, OpenAPI specs, and Search.
- copy guidance for quoting, summarizing, and verifying before coding.
- a downloadable archive and discoverable docs skill for tools that work best from local context.

## What agents must still verify

These files do not replace the references that own exact behavior. Before writing code, verify package exports, component props, and hook signatures in package reference.

For API or Search work, verify endpoint fields, GraphQL fragments, and event payloads in the owning reference. Playground-only runtime behavior stays in the playground.

## Contract scope

Use agent files to choose the route. Use the matching reference to verify exact facts.

| Question | Trust this source |
| --- | --- |
| Which docs route should an agent open first? | `/llms.txt`, `/llms-full.txt`, `/docs.zip`, or `/ai/manifest.json` |
| Which React or TypeScript package track does `latest` describe? | `/ai/manifest.json` and the version-track page |
| What is the exact SDK export, prop, hook, helper signature, or runtime behavior? | SDK package reference |
| What is the exact REST path, request field, response field, or auth rule? | API reference and OpenAPI inputs |
| What is the exact Search operation, variable, fragment, or generated type? | Search reference and package reference |
| What belongs to the live runtime sandbox? | the playground and `https://sdk.enad.io/sandbox` |

## Practical selection rule

1. Use <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> to pick the smallest relevant docs route.
2. Use <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> when a tool needs route data or version-track context.
3. Use <a href="/docs.zip" target="_blank" rel="noreferrer"><code>/docs.zip</code></a> when a tool needs local markdown files.
4. Use <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> only when the task crosses multiple Enad domains.
5. Before writing exact code, jump from the chosen docs route to the owning package, OpenAPI, or Search reference.

## Related routes

- [Agent guides](/ai)
- [Agent quickstart](/ai/agent-quickstart)
- [React SDK agent guide](/ai/react-sdk/latest)
- [TypeScript SDK agent guide](/ai/ts-sdk/latest)
- [Prompt recipes](/ai/prompts)

---

# Enad app auth.md

URL: https://docsv3.enad.io/ai/enad-app-authmd
Kind: integration-guide
Authority: guidance
Domains: ai, auth, docs
Copy-paste safe: guidance-only

# Enad app auth.md

Register through `auth.md` when an agent or operator needs a scoped credential for one Enad app context.

Keep the registration scope narrow: discover the resource, register with an existing app-user email, complete the OTP claim, use the returned scoped API key, and restart discovery on `401`.

## Live discovery

On `app.enad.io`, fetch `/auth.md`, `/.well-known/oauth-protected-resource`, and `/.well-known/oauth-authorization-server`. Discovery is origin-relative, so use the same origin for metadata, registration, claim completion, and later API calls.

If a protected route returns `401`, read the `WWW-Authenticate` header. Follow its `resource_metadata` value instead of guessing the next step.

## What v1 supports

The current Enad app `auth.md` flow exposes one bounded registration path:

- The identity type is `identity_assertion`.
- The assertion type is `verified_email`.
- The credential type is `api_key`.
- Each registration names one app context through `context.team_slug` and `context.app_slug`.
- A `401` from a previously issued credential means restart discovery.

This v1 flow is email-claimed and user-bound. Use the email address of an existing Enad app user for the target context.

## Supported v1 scopes

Enad grants scopes from the matched user's existing app permissions only. A scope is returned only when the matched role has the full permission set behind that scope. The v1 scope set is:

- `assets.read`
- `assets.write`
- `products.read`
- `products.write`

Do not assume broader tenant-admin or system-wide access. If the user does not already hold the required app permissions, registration will not mint those scopes.

## Registration flow

Use this order every time. Discover against the live origin, create a pending registration, complete the user-present OTP step, then store the returned credential with its expiry.

1. Discover the resource metadata. Fetch both metadata routes before registration; the protected-resource document identifies the resource and scopes, while the authorization-server document advertises `agent_auth`, the register URI, the claim URI, and the public `auth.md` document.

```http
GET https://app.enad.io/.well-known/oauth-protected-resource
GET https://app.enad.io/.well-known/oauth-authorization-server
```

2. Create a pending registration. Call the register endpoint with the user's verified email, the requested credential type, and the explicit team/app context:

```http
POST https://app.enad.io/agent/auth
Content-Type: application/json
```

```json
{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com",
  "requested_credential_type": "api_key",
  "context": {
    "team_slug": "enadhq",
    "app_slug": "demo-storefront"
  }
}
```

A successful registration returns `registration_id`, `registration_type: "email-verification"`, `claim_token`, `claim_token_expires`, `claim_url`, and `post_claim_scopes`.

No credential is issued yet. Enad emails the user a claim link for the hosted OTP step.

3. Complete the OTP claim. Ask the user to open the claim email, read the six-digit OTP, and provide that code to the agent or operator. Then complete the claim:

```http
POST https://app.enad.io/agent/auth/claim/complete
Content-Type: application/json
```

```json
{
  "claim_token": "clm_...",
  "otp": "123456"
}
```

A successful claim returns `status: "claimed"`, `credential_type: "api_key"`, the `credential`, `credential_expires`, and granted `scopes`. Store the credential and expiry together before making API calls.

4. Use the credential. Present the returned API key as a bearer token:

```http
Authorization: Bearer <credential>
```

If a previously working credential starts returning `401`, drop it and restart from discovery instead of retrying with stale state.

## Failure and retry guidance

Use these error outcomes to choose the next step:

| Code | Meaning | Next step |
| --- | --- | --- |
| `invalid_request` | The request body does not match the v1 schema. | Rebuild the request from the schema shown above. |
| `missing_app_access` | The email does not match an existing user in the requested app context, or the matched user has no v1 scopes available. | Ask for a different app context or an existing app-user email with the required permissions. |
| `unsupported_credential_type` | The request asked for something other than `api_key`. | Retry with `api_key`. |
| `claim_not_required` | The caller tried to start an anonymous or separate claim step. | Use `POST /agent/auth`; the v1 email-verification flow sends the claim email during registration. |
| `invalid_claim_token` | The claim token is missing, invalid, or unknown. | Restart at registration. |
| `otp_invalid` | The six-digit code did not match. | Ask the user to re-read the OTP and retry. |
| `otp_expired` | The OTP timed out. | Restart at registration for a fresh email. |
| `claim_expired` | The whole registration expired. | Restart at registration. |
| `previously_claimed` | The claim was already completed. | Restart registration if a fresh key is needed. |
| `rate_limited` | Too many registration attempts came from the same IP. | Back off and retry later. |
| `email_delivery_unavailable` | The claim-email delivery path is not configured for the environment. | Treat the environment as unavailable for public registration until delivery is configured. |

## Operator usage example

Use this flow when an operator needs to connect to one Enad app on a user's behalf:

1. Fetch `auth.md` or follow the `401` discovery hint.
2. Read the protected-resource metadata and authorization-server metadata.
3. Register with the user's verified email plus the target `team_slug` and `app_slug`.
4. Wait for the user to complete the email step and provide the OTP.
5. Complete the claim and store the scoped API key with its expiry.
6. Use that key for the narrow Enad operations the user actually allowed.
7. If Enad later returns `401`, discard the key and restart the flow instead of silently reusing stale credentials.

## Boundaries

Keep these constraints explicit:

- v1 supports `api_key` credentials only.
- The user must already exist in the requested app context.
- Scopes come from existing Enad app permissions, not from free-form agent requests.
- Anonymous-start claims are not part of this v1 flow.
- Agents do not call a dedicated public revoke endpoint in this v1 flow.

Operators can inspect resulting registrations inside Enad and revoke the issued API key through the normal product surfaces after sign-in.

## Related routes

- [Agent guides](/ai)
- [Agent quickstart](/ai/agent-quickstart)
- [Integrations](/integrations)

---

# Agent files manifest

URL: https://docsv3.enad.io/ai/manifest
Kind: manifest-browser
Authority: guidance
Domains: ai, docs, manifest
Copy-paste safe: guidance-only

# Agent files manifest

Start here when you want to inspect the files and route guides an agent can load before handing off Enad work. The panel above links to the public agent files and shows which route guides are available.

Use it when an agent or maintainer needs to answer:

- Which agent route is the narrowest safe starting point?
- Which agent file should a client request first?
- Which version track applies to package, API, Search, Media, Events, or integration work?
- Which Enad area should the agent open next?

## Agent usage

For most agent tasks, start with <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a>. Reach for <a href="/docs.zip" target="_blank" rel="noreferrer"><code>/docs.zip</code></a> when a tool needs local markdown files. Use <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> when the task spans several Enad areas. Load <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> when the agent needs structured route data.

Agents should use this human route for inspection, <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> for structured ingestion, and <a href="/.well-known/agent-skills/index.json" target="_blank" rel="noreferrer"><code>/.well-known/agent-skills/index.json</code></a> for skill discovery.

---

# MCP server

URL: https://docsv3.enad.io/ai/mcp-server
Kind: mcp-guide
Authority: guidance
Domains: ai, mcp, api, media, search
Exact facts: MCP transport, OAuth discovery, scope names, public docs tools, context tools, and mutation lifecycle guidance are current server guidance. Exact API contracts still belong to generated API, Search, Media, and Events references.
Copy-paste safe: guidance-only

# MCP server

Use the Enad MCP server when an agent needs live Enad context, docs routing, Search-backed storefront data, DAM metadata, or governed catalog and media changes.

## Connect

Connect an MCP-capable client over Streamable HTTP:

```text
https://mcp.enad.io/mcp
```

For the public Worker endpoint, send `initialize`, `tools/list`, and tool calls with `POST /mcp`. Use `HEAD /mcp` only as a discovery probe; it returns the OAuth challenge in `WWW-Authenticate`. `GET /mcp` and `DELETE /mcp` return `405` with `Allow: POST`, so do not model hosted clients around long-lived session reads.

Use the hosted custom domain for normal client setup. Public client examples should point at `https://mcp.enad.io/mcp`.

OAuth discovery lives at:

- `/.well-known/oauth-protected-resource/mcp`
- `/.well-known/oauth-authorization-server/mcp`
- `/.well-known/openid-configuration/mcp`

The protected-resource document advertises the `/mcp` resource, the matching issuer, supported scopes, default scope, public tools, and the auth note. The authorization metadata exposes the authorization-code grant, refresh tokens, and device codes. It also includes dynamic client registration, PKCE `S256`, token endpoint auth methods, and the device authorization endpoint.

Read the issuer, authorization endpoint, token endpoint, device authorization endpoint, and registration endpoint from the metadata for the MCP endpoint you are connecting to. Do not hard-code issuer or token URLs from examples, logs, or screenshots; those values can move independently of the stable `https://mcp.enad.io/mcp` resource URL.

Hosted metadata currently advertises `docs.search` and `docs.get_route_guidance` as public tools, `catalog:read` as the default delegated scope, and `shopper:read`, customer read/lookup/admin/share scopes, and `dam:read` as optional delegated scopes.

## Codex setup

For Codex, use the Enad App or connector OAuth flow when it is available. That path lets Codex open the browser handoff, store and refresh the delegated token, then retry protected tools after approval.

Raw remote MCP configuration can still check endpoint metadata and public docs tools:

```toml
[mcp_servers.enad]
url = "https://mcp.enad.io/mcp"
```

Treat that snippet as a reachability check. It is not the complete protected-tool setup. Without the connector-owned OAuth provider, protected calls can fail with an authentication challenge instead of opening Codex's approval button.

Ready means all of these are true:

1. The client reads protected-resource metadata from the MCP endpoint.
2. The connector UI or connection prompt opens Enad OAuth approval.
3. Browser approval completes in the matching app environment.
4. Codex returns with a cached delegated token.
5. A protected read tool such as `auth_get_current` or `context_get_current` succeeds.

## Start without signing in

Use public routing tools before any account read or change. They work without OAuth or a bearer token, and they should still work as anonymous docs lookups when the client has an expired token cached.

| Display name | Callable model-safe name |
| --- | --- |
| `docs.search` | `docs_search` |
| `docs.get_route_guidance` | `docs_get_route_guidance` |

## Sign in for protected tools

Protected tool families use delegated bearer authentication. Let the MCP client follow OAuth discovery instead of pasting tokens manually.

The default scope is:

- `catalog:read`

Optional scopes are:

- `shopper:read`
- `customers:read`
- `customers:lookup`
- `customers:admin`
- `customers:share`
- `dam:read`

Keep delegated scopes read-oriented. The hosted OAuth metadata does not advertise a broad catalog write scope. Catalog and media changes use preview, browser approval, apply when needed, then audit. Approved catalog proposals receive a one-time downstream grant instead of a long-lived delegated write scope.

When auth is missing, expired, or inactive, the server returns an OAuth challenge and status that tells the client to connect or reconnect.

Do not stop at `initialize` or `tools/list`. Those calls can succeed while protected tools still need OAuth. Verify readiness with browser approval and a protected read call.

Public docs tool calls are intentionally more forgiving than protected tools. If a client has a stale or inactive bearer token cached, docs lookup should still behave as anonymous unless the result requires protected account context.

## Choose the active app context

After sign-in, inspect the actor and active app:

| Tool | Use it for |
| --- | --- |
| `auth_get_current` | See the actor, delegated policy, team, and app. |
| `auth_get_write_access_instructions` | Read the write-access sequence for the authenticated mode. |
| `context_get_current` | Check the active team and app. |
| `context_set_active` | Switch to another allowed team/app pair for the session. |

Keep the team and app explicit before catalog, media, DAM, customer, or order work. That context determines which downstream data each protected tool may read or change.

## Find and run capabilities

Capability discovery should be the first step before choosing a workflow:

- `search_capabilities` finds read, draft, dry-run, and write capabilities.
- `execute_capability` runs read and draft capabilities.

Use the model-safe names returned by `tools/list` when you call tools. Display names such as `changes.preview` and `changes.apply` may appear in descriptions, but the callable tool names are `changes_preview` and `changes_apply`.

Use `search_capabilities` as a precise registry query instead of a keyword search. Filter by:

- `query` for natural-language or exact capability-id matching
- `namespace` such as `search`, `catalog`, `commerce`, `media`, `routing`, `merchandising`, `identity`, or `customer`
- `mode`: `read`, `draft`, `dryRun`, or `write`
- mutation `status`, `riskTier`, and `phase`
- `limit` up to 200 results

Set `includeInputFields: true` to expose accepted top-level input names. Set `includeDetails: true` to expose mutation details such as status, risk tier, phase, preview tool, approval flow, permission group, and tags.

For a source-derived snapshot of current mutation routing descriptors, use [MCP capability catalog](/reference/mcp/capabilities). The catalog mirrors dry-run mutation descriptors that discovery can expose with details; it is not a live `tools/list` replacement.

Capability status controls what an agent may do next:

| Status | What it means | Agent behavior |
| --- | --- | --- |
| `implemented` | The capability has the routed lifecycle metadata needed for the current tool path. | Use the returned mode, preview tool, approval flow, risk tier, and permission group to choose the next call. |
| `descriptor-only` | The server exposes a proof gate or future workflow shape, but the write path is not executable yet. | Do not call it as a write. Use it only to explain that the workflow is implementation-pending or to route to implemented alternatives. |
| `deferred` | The workflow is intentionally not part of the current execution path. | Do not attempt execution; route to references or another implemented capability. |
| `blocked` | The workflow is known but cannot run yet because requirements, policy, or safety gates are incomplete. | Treat it as unavailable until the capability status changes. |
| `out-of-scope` | The current API inventory does not expose a writable surface for that family. | Route to references or an implemented alternative. |

For write work, require `status: "implemented"` and a concrete `previewTool` before routing through `changes_preview` and browser approval. Descriptor-only capabilities can still have schemas and input fields; those fields describe the proof gate, not an executable API request.

Implemented mutation families cover bounded catalog metadata and relationships, merchandising, variants, variant groups, stock, pricing, warehouses, bundles, DAM, media-control, and media-delete workflows.

Some high-risk families can appear as descriptor-only proof gates. Examples include identity, customer-owned data, smart listings, broad product lifecycle, broad order, and raw upload. Treat those as non-executable until discovery returns an implemented preview/apply route.

Capability discovery returns the execution state for each write workflow. Use that returned status to route the next call: implemented capabilities can use their preview/apply tools, while descriptor-only, deferred, blocked, and out-of-scope entries are not executable write paths. Shopper and standalone DAM reads should not be treated as write surfaces; DAM writes route through Management-owned DAM capabilities when discovery returns an implemented workflow.

Use `identity` and `customer` namespace searches to inspect proof-gate status for account, organisation, wishlist, saved-cart, customer-file, role, and customer-group workflows. Do not execute those families unless discovery returns `status: "implemented"` with concrete preview and apply tools.

`execute_capability` validates params against the discovered capability schema, but only for read and draft modes. Dry-run and write capabilities are intentionally blocked from `execute_capability`; use the preview/apply lifecycle for those changes.

If capability discovery or execution returns a documentation reminder, follow it before continuing. The server tracks whether docs were consulted in the session and may suggest `docs.get_route_guidance` or `docs.search` with a focused query before catalog reads or writes.

## Change data safely

Use this lifecycle for catalog and media changes:

1. Resolve the active context with `auth_get_current` or `context_get_current`.
2. Find the matching capability with `search_capabilities`.
3. Validate or preview the change with `validate_catalog_change` or `changes_preview`.
4. Review the returned change set, proposal, approval metadata, and impact summary.
5. Complete the browser approval step when the preview returns an approval URL or approval request.
6. Poll the proposal, changed resource, or audit trail after browser approval.
7. Call `changes_apply` only when the workflow still needs an explicit apply call.
8. Read `audit_get` after apply and verify the changed resource through the owning API or read tool.

For proposal-backed workflows, browser approval can complete the write and is normally the apply step when the proposal includes both an approval request and a one-time write grant. Enad Auth sends the approval decision back to MCP with the request id, status, actor, and decision time. MCP then matches the request to the stored proposal, redeems the grant for short-lived catalog write access, and applies the supported workflow.

Callback auto-apply is intentionally narrow. The callback accepts `pending`, `approved`, `denied`, `expired`, and `consumed` statuses. Unknown request ids are treated as best-effort no-ops, non-approved statuses only update proposal state, and unsupported workflows are not applied by the callback path. Supported callback auto-apply covers tag-name, tag-name batch, and DAM image-attribute batch proposals after the approval grant is redeemed. Other approved workflows can still require `changes_apply` or a later implemented apply path. After browser approval, poll the proposal, changed resource, or audit trail before assuming a second `changes_apply` call is required.

Approval URLs are one-time request artifacts. Generate a fresh request from the same environment as the MCP endpoint instead of reusing a saved link. Keep the Enad Auth issuer, app approval page, callback origin, and shared service secrets in that environment too. Mixed environments can make the browser page unable to load the request or post the decision back to the right service.

Hosted approval callbacks need both a public callback origin and a callback secret. Public hosted operation uses the hosted MCP origin with the matching Enad Auth issuer and app approval page. The callback secret configured in Enad Auth must match the MCP server secret; do not expose either secret in docs, prompts, logs, or browser URLs.

## Public docs versus exact contracts

MCP helps agents choose and operate against Enad surfaces. It does not replace the owning contracts:

- API paths, methods, request bodies, and responses stay in API references and OpenAPI specs.
- Search schema, operations, fragments, variables, and nullability stay in Search reference.
- Media upload, metadata, relationship, delete, and DAM endpoint details stay in Media and DAM references.
- Event names, envelope fields, and payload schema IDs stay in the Event catalog.

Use MCP docs tools for routing, use read tools for live context, and use references before writing code that depends on exact fields.

## Operator deployment boundaries

Operator service setup is not the public Codex connector setup. Public docs should keep the hosted endpoint, OAuth discovery, connector handoff, and safe tool workflow clear without publishing local service environment variables.

For hosted operation, keep every connection on one deployment. Match these values:

- Enad API base URL
- Enad Auth issuer and approval page
- MCP callback origin
- callback and approval-decision secrets

Keep each connection in one environment. Use matching MCP endpoint, Auth issuer, app approval page, callback origin, and shared secrets. A mixed setup can break browser approval. It can also post the decision back to the wrong service.

Public setup should not depend on local development modes, direct-apply bypasses, tool-decision shortcuts, or header-based local auth. Use the hosted connector and OAuth flow for protected tools.

## Related docs

Continue with [Agent quickstart](/ai/agent-quickstart), [API, Search, and Events agent guide](/ai/apis/latest), [Media](/media), or [Enad app auth.md](/ai/enad-app-authmd).

---

# Prompt recipes

URL: https://docsv3.enad.io/ai/prompts
Kind: prompt-recipes
Authority: guidance
Domains: ai, react-sdk, ts-sdk, api, search, media, events, theming
Copy-paste safe: prompt-safe

# Prompt recipes

Keep agents focused. Stay specific. Replace the placeholders with the actual task, then keep SDK exports, API fields, Search schema, Media contracts, and event payloads tied to their references.

## General routing prompt

```text
Read /llms.txt first.
Check /ai/manifest.json for safety hints.
Name the smallest Enad surface for this task before writing code.
Use references for exact fields, exports, versions, and payloads.
```

Use this prompt before the surface is clear. After routing, switch to the narrower recipe that matches the work.

## React SDK component work

```text
Build <surface> with documented React SDK exports.
Name the component family and public import path before code.
Keep EnadProvider and theme boundaries on documented public surfaces.
```

Use this for component choice and imports. Use the storefront recipe when the task is page-level composition.

## Storefront composition

```text
Use docs and /llms-full.txt to route this storefront task.
Name the primary domain, then produce a small plan.
Do not copy playground route internals into the app.
Verify exact props, hooks, Search fields, and package versions in references.
```

Use this when the page shape is the main question. Use a commerce or Search prompt when data ownership is the hard part.

## TypeScript SDK API work

```text
Use docs plus SDK package reference for exact @enadhq/enad-ts-sdk APIs.
For <API> from <runtime>, name the SDK/client boundary.
Keep required context explicit.
Check API reference or OpenAPI before writing code.
Distinguish core API tuple responses from Search client results.
```

Use this when the task mixes SDK helpers with API behavior. Keep exact exports in package reference and exact endpoints in API reference.

## Search GraphQL work

```text
Use Enad Search guidance with app, market, store-group, and locale explicit.
Route React work to React SDK Search guidance, and route query-model work to Search GraphQL reference.
Do not invent operations, variables, fragments, or schema fields.
Prefer Search GraphQL for new discovery, filters, facets, autocomplete, and product-result composition.
```

Use this when storefront discovery or Search data shape is the core problem. Keep React composition separate from query contracts.

## Media and DAM work

```text
Use /llms.txt and Media docs to choose Media, public asset-library reads, or Management DAM administration, then verify uploads, schemas, transformations, and fields in API reference.
Do not collapse the DAM route families: public asset-library reads use dam.enad.io app_id GET routes; administration uses Management /api/v1/{team_slug}/{app_slug}/dam/... routes.
For MCP media-control or media-delete, keep REST references as endpoint truth, route changes through preview/apply, and require no-rollback acknowledgement before destructive deletion.
```

Use this when the task touches assets, folders, transformations, or governed media changes. It keeps route choice, reference checks, and destructive-change safeguards in the same prompt.

For MCP media-control or media-delete work, keep REST references as endpoint truth and route changes through preview/apply. For destructive media deletion, require explicit no-rollback acknowledgement before preview.

## MCP server work

Use this when the agent needs to connect to the hosted MCP server or choose tools safely. The prompt keeps setup, discovery, capability selection, approval, and verification in one workflow.

```text
Use /ai/mcp-server for Enad MCP setup and first-call workflow.
Connect with Streamable HTTP and let the client follow OAuth discovery.
Call docs.search/docs_search or docs.get_route_guidance/docs_get_route_guidance before domain-specific tools.
Keep team/app context explicit.
Use search_capabilities with namespace, mode, status, includeInputFields, and includeDetails before selecting a capability.
Execute only read or draft capabilities through execute_capability.
Route dry-run and write capabilities through changes_preview, browser approval when required, changes_apply when the capability status is implemented and the workflow needs it, audit_get, and a post-change read.
Do not execute descriptor-only, deferred, blocked, or out-of-scope capabilities.
For proposal-backed workflows, browser approval can complete the write, so poll proposal, resource, or audit state before assuming another apply call is needed.
Generate fresh approval links from the same environment as the MCP endpoint.
Use API, Search, Media, DAM, or Events references for exact contracts.
```

## MCP catalog and merchandising mutation work

Use this when the change affects catalog or merchandising data through MCP.

Use /ai/apis/latest and /ai/mcp-server before changing Enad catalog, merchandising, variant, stock, pricing, DAM, or media data through MCP.

Find capabilities with search_capabilities using the right namespace, mode dryRun, status implemented, includeInputFields, and includeDetails.

```text
Use /ai/apis/latest and /ai/mcp-server before changing Enad catalog, merchandising, variant, stock, pricing, DAM, or media data through MCP.
Find capabilities with search_capabilities using the right namespace, mode dryRun, status implemented, includeInputFields, and includeDetails.
If the returned capability is descriptor-only, deferred, blocked, or out-of-scope, stop and explain that it is not executable.
For implemented workflows, keep entity IDs and slugs explicit.
Preserve destructive acknowledgements when required.
Preview through changes_preview.
Complete browser approval when required.
Apply through changes_apply only when the workflow still needs it.
Read audit_get and verify with the owning API or read tool.
Use API reference pages for endpoint fields and response contracts.
```

## MCP variant stock work

Use this for stock quantity changes through MCP. It keeps stock writes separate from product, variant, and purchase-policy decisions.

```text
Use /ai/apis/latest and /start/concepts/products-variants-prices-and-stock before changing stock through MCP.
Find commerce stock capabilities with search_capabilities using namespace commerce, mode dryRun, includeInputFields, and includeDetails.
Use Variants reference pages for exact REST endpoint contracts.
For MCP variant-stock writes, provide a reason, keep productId, variantId, and warehouseSlug explicit, require noRollbackAcknowledged for stock deletes, use only explicit-partial bulk mode, and route set/delete or bulk set/delete through changes_preview, browser approval when required, changes_apply, audit_get, and a post-apply read.
Do not execute stock delta adjustment as a write unless the capability is no longer descriptor-only.
```

## MCP bundle-control work

Use this for bundle groups, bundles, bundle rules, and bundle availability. It keeps destructive acknowledgements and store-group market context explicit.

```text
Use /ai/apis/latest and /start/concepts/product-bundles-and-bundle-groups before changing bundle data through MCP.
Find commerce bundle capabilities with search_capabilities using namespace commerce, mode dryRun, includeInputFields, and includeDetails.
Use Product Bundle Groups, Product Bundles, and Bundle Rules reference pages for exact REST endpoint contracts.
For MCP bundle-control writes, keep bundleGroupId, bundleId, ruleId, marketSlug, storeGroupSlug, and productIds explicit when the operation needs them.
Require noRollbackAcknowledged for deletes and removals, do not mix fixed and relative discount payloads, and route bundle group, product bundle, bundle rule, or bundle availability changes through changes_preview, browser approval when required, changes_apply, audit_get, and a post-apply read.
```

## MCP warehouse-control work

Use this for warehouse records and warehouse-market links. Use variant-stock workflows instead when the value being changed is inventory quantity.

```text
Use /ai/apis/latest and /start/concepts/store-groups-and-markets before changing warehouse data through MCP.
Find commerce warehouse capabilities with search_capabilities using namespace commerce, mode dryRun, includeInputFields, and includeDetails.
Use Warehouses reference pages for exact REST endpoint contracts.
For MCP warehouse-control writes, keep warehouseSlug and marketSlug explicit when the operation needs them, use warehouse slugs that are lowercase alphanumeric with hyphen or underscore separators, require noRollbackAcknowledged for warehouse delete and market remove, and route warehouse create/update/delete or warehouse market add/remove through changes_preview, browser approval when required, changes_apply, audit_get, and a post-apply read.
Do not use warehouse-control for variant stock quantity changes; use variant-stock workflows instead.
```

## MCP static-listing-control work

Use this for governed changes to curated static listings. Do not use it for Smart Listing rules, Search ranking, product edits, or variant edits.

```text
Use /ai/apis/latest and /start/concepts/redirects-relations-and-listings before changing curated static listings through MCP.
Find merchandising static listing capabilities with search_capabilities using namespace merchandising, mode dryRun, includeInputFields, and includeDetails.
Use Static Listings reference pages for exact REST endpoint contracts.
For MCP static-listing-control writes, keep listingId explicit for update/delete, use slugs that are lowercase alphanumeric with hyphen or underscore separators, provide 1-100 variantIds for create/update, require noRollbackAcknowledged for delete, and route static listing create/update/delete through changes_preview, browser approval when required, changes_apply, audit_get, and a post-apply read.
Do not use static-listing-control for Smart Listing rules, Search ranking, product edits, or variant edits.
```

## Events and Integrations work

Use this when the task touches webhook delivery, receiver behavior, or integration routing. Keep event names and payload fields tied to the catalog.

```text
Use the Events and Integrations routes for webhook delivery, retry behavior, and integration guidance. Use /events/catalog for exact event type strings, base event envelope fields, payload schema IDs, and top-level payload field summaries. Treat the configured custom auth header pair as the current receiver-authentication surface unless webhook settings or delivery references explicitly define more. Do not invent signature headers, timestamp headers, replay-window checks, retry headers, or payload-derived signing rules. Verify nested payload details and API details in schemas or references before writing code.
```

## Theme restoration from playground

Use this when moving a reviewed playground theme into an app. Keep provider placement and theme hash usage on documented SDK surfaces.

```text
Use public Enad theme surfaces only. Keep EnadProvider at the app root and wrap the themed subtree with EnadThemeProvider from @enadhq/enad-react-sdk/client/theme. If the playground export includes rich runtime theme data, prefer const themeHash = "..." plus <EnadThemeProvider hash={themeHash}>. Use componentSet="..." directly only for structural-set-only setup. Do not copy live playground internals or routes into the app.
```

## Theme debugging

Use this when theme output differs between playground and app runtime. Check hash, component set, token overrides, and stylesheet import in that order.

```text
Debug Enad theme restoration in this order: verify the same hash is passed through, check whether an explicit componentSet prop overrides the hash, check whether explicit tokens override decoded values, then confirm the SDK stylesheet is imported so component-set selectors exist. Remember: componentSet is structural; token overrides change CSS variables.
```

## API reference review

Use this when reviewing a docs change that might move exact endpoint facts into prose. Keep API fields and contract details in the reference layer.

```text
Use the current API and Reference routes to find endpoint details. Keep endpoint fields in reference pages, and use conceptual guides only for workflow explanation.
```

---

# React SDK agent guide

URL: https://docsv3.enad.io/ai/react-sdk/latest
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.9.3
Version range: >=1.9.0 <1.10.0
Authority: guidance
Domains: react-sdk, storefront, commerce, search, theming
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require SDK package reference for this track.
Copy-paste safe: guidance-only

# React SDK agent guide

Start here when an agent needs to work with `@enadhq/enad-react-sdk`. Use the route selection below before changing provider setup, storefront composition, Search runtime behavior, or theme restoration.

## Choose the React agent route first

Use this authored page as the broad React SDK entrypoint when the task spans provider setup, storefront composition, Search runtime boundaries, or theme/runtime handoff.

Choose a narrower route first when possible:

- Go to [React SDK discovery and imports](/ai/react-sdk/latest/discovery) before choosing component families or public import surfaces.
- Go to [React SDK theme and icons](/ai/react-sdk/latest/theme-and-icons) for theme hashes, component sets, icon/runtime boundaries, or playground restoration.
- Go to [React SDK commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff) when the job crosses shopper UI, Search GraphQL, pricing display, or purchase-adjacent behavior.
- Go to [Product listing and search](/react-sdk/latest/guides/product-listing-search) for shopper-facing search composition and [Search GraphQL latest](/search/latest) for query-model truth.

Start here to route the work. Use package reference for exact exports, props, hooks, helper signatures, and runtime behavior before writing code.

## Contract scope

- Use this page for routing, composition guidance, and safe examples.
- Use SDK package reference for exact exports, prop names, hook signatures, Search mapping helpers, and runtime behavior.
- Do not copy code from live playground internals into consumer apps.
- Keep live sandbox/editor/export behavior in the playground.

## Focused agent routes

Use the smallest React SDK agent page that matches the job:

- [React SDK discovery and imports](/ai/react-sdk/latest/discovery) - choose the right component family and public import surface before writing code.
- [React SDK theme and icons](/ai/react-sdk/latest/theme-and-icons) - preserve provider nesting, theme hashes, component sets, and runtime icon boundaries.
- [React SDK commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff) - keep shopper UI composition separate from Search GraphQL and purchase-side contract truth.

## Provider setup

`EnadProvider` is the root SDK runtime provider. It owns SDK-wide setup such as React Query, icon registration, locale, component resolver wiring, app-wide component-set selection, optional cart wiring, and optional client/Search configuration.

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";

export function AppShell({ children }: { children: React.ReactNode }) {
  return <EnadProvider>{children}</EnadProvider>;
}
```

Pass `componentSet` to `EnadProvider` for an app-wide structural set. Add `EnadThemeProvider` inside the provider when a subtree needs playground hash restoration, scoped token overrides, or a nested theme boundary.

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";

export function AppShell({ children }: { children: React.ReactNode }) {
  return <EnadProvider componentSet="editorial">{children}</EnadProvider>;
}
```

## Search runtime rules

Use [Product listing and search](/react-sdk/latest/guides/product-listing-search) for PLP, search-results, autocomplete, and connected Search component composition. Apply these rules before writing code:

- Keep query/data responsibility separate from UI composition.
- Keep market, store group, and locale together in provider-backed Search runtime configuration.
- `graphql.storeGroupSlug` can override `groupId` for Search context.
- `mapSearchProductToProductCard()` accepts `storeGroupSlug` so mapped cards can prefer the intended store-group price.
- Use package reference for exact hook, helper, and component props before writing code.
- Do not move cart, checkout, or purchase side effects into presentational Search cards.

## Runtime theming rules

- Correct nesting is `EnadProvider` outside and `EnadThemeProvider` around any scoped themed subtree.
- Runtime precedence is explicit `EnadThemeProvider` props, then decoded hash values, then SDK defaults.
- `componentSet` is structural. It changes the UI language through `data-component-set`; it is not only a color preset.
- Token overrides change CSS variables. Keep token changes separate from component-set changes in explanations and examples.
- Playground share URLs and export snippets can carry both token state and `componentSet`.
- Prefer `hash={themeHash}` when restoring rich playground state.
- Use `EnadProvider componentSet="..."` when the setup is app-wide structural-set only and there is no richer hash state to restore.
- `enad-theme` generates CSS blocks. It does not replace `EnadThemeProvider` for runtime behavior.

## Theme restoration example

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";

const themeHash = "paste-playground-theme-hash-here";

export function StorefrontShell({ children }: { children: React.ReactNode }) {
  return (
    <EnadProvider>
      <EnadThemeProvider hash={themeHash}>{children}</EnadThemeProvider>
    </EnadProvider>
  );
}
```

If the restored app does not match the playground, debug in this order:

1. Verify the same `hash` is passed through.
2. Check whether explicit `componentSet` overrides the hash value.
3. Check whether explicit `tokens` override decoded token values.
4. Confirm the SDK stylesheet is imported so component-set selectors exist.

## Component work

Route broad React SDK questions before implementing.

- For component choice, start with Discovery.
- For public child parts, use Compound composition.
- For header, footer, and page shell work, use Layout.
- For hero, gallery, and content blocks, use Storefront.
- For price, variant, and cart flow work, use Commerce.
- For products, facets, and autocomplete queries, use Search.
- For component sets or theme hashes, use Theme.

When exact component props matter, inspect package reference. Do not invent props from prose.

## Docs React SDK route guide

Use these docs routes before falling back to the live playground:

- [React SDK latest](/react-sdk/latest) - public landing page for route selection, Search runtime facts, and package reference guidance.
- [React SDK discovery and imports](/ai/react-sdk/latest/discovery) - package-aware route selection for component families and public imports.
- [React SDK theme and icons](/ai/react-sdk/latest/theme-and-icons) - theme restoration, component sets, and icon/runtime boundaries.
- [React SDK commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff) - cross-surface routing for PLP, Search, pricing, and purchase-adjacent work.
- [React SDK setup](/react-sdk/latest/setup) - provider, stylesheet, and runtime setup order.
- [First React SDK app](/react-sdk/latest/guides/first-app) - smallest useful provider/theme shell and first-page checklist.
- [Theme from playground](/react-sdk/latest/guides/theme-from-playground) - restore playground theme hashes while preserving provider and precedence rules.
- [Storefront page guide](/react-sdk/latest/guides/storefront-page) - compose layout chrome, storefront sections, and app-owned routing/data boundaries.
- [Product listing and search](/react-sdk/latest/guides/product-listing-search) - compose PLP/search UI while keeping Search GraphQL truth in schema/generated sources.
- [Product detail page](/react-sdk/latest/guides/product-detail-page) - compose PDP media, price, variant, and purchase-adjacent UI without assigning cart/checkout side effects to presentational components.
- [React SDK troubleshooting](/start/troubleshooting) - symptom-based recovery for stylesheet, provider, theme, search, API, and agent-file issues.
- [React SDK theming](/react-sdk/latest/theming) - `EnadThemeProvider`, component sets, theme hashes, and runtime precedence.
- [Component resolver](/react-sdk/latest/resolver) - resolver-backed primitives, component sets, and custom component override boundaries.
- [React SDK components](/react-sdk/latest/components) - component docs grouped by Base UI, Layout, Storefront, and Commerce.
- [Base UI components](/react-sdk/latest/components/base-ui) - low-level resolver-backed primitives.
- [Layout components](/react-sdk/latest/components/layout) - Header, Footer, navigation, promotion, and shell components.
- [Storefront components](/react-sdk/latest/components/storefront) - editorial, merchandising, media, and content blocks.
- [Commerce components](/react-sdk/latest/components/commerce) - shopper decision, product, cart, search, and checkout-adjacent surfaces.
- [React SDK playground](/react-sdk/latest/playground) - boundary between docs guidance and the live sandbox/runtime lab.

The authored guides keep JavaScript and TypeScript snippets to confirmed public imports: `@enadhq/enad-react-sdk`, `@enadhq/enad-react-sdk/client/theme`, and the stylesheet path when setup requires it. When exact component, hook, Search GraphQL, or child-part imports matter, inspect package reference instead of inventing imports from prose.

Component pages help choose and compose SDK surfaces. When exact props or child parts matter, inspect package reference.

## Playground bridge

Use [Playground](/playground) for runtime experimentation, theme export, and live-data sandboxing. Use docs for instructions, package-aware routing, and agent-file guidance. The route guide keeps runtime playground routes in the playground while long-form component docs live in docs.

---

# React SDK agent commerce and Search handoff

URL: https://docsv3.enad.io/ai/react-sdk/latest/commerce-search-handoff
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.9.3
Version range: >=1.9.0 <1.10.0
Authority: guidance
Domains: react-sdk, commerce, search, ts-sdk
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require SDK package reference for this track.
Copy-paste safe: guidance-only

# React SDK agent commerce and Search handoff

Start here when a task crosses shopper-facing React UI, Search GraphQL data, pricing display, or purchase-adjacent behavior.

## Keep the ownership split explicit

Search query shape, variables, generated documents, fragments, and types start at [Search GraphQL latest](/search/latest). Keep exact query truth in the Search reference and package reference.

Server-side Search usage starts at [TypeScript SDK latest](/ts-sdk/latest) and [/ai/ts-sdk/latest](/ai/ts-sdk/latest). Keep exact helper behavior in the `@enadhq/enad-ts-sdk/search` reference.

Shopper-facing PLP, autocomplete, filters, result cards, and Search UI composition start at [Product listing and search](/react-sdk/latest/guides/product-listing-search). Keep exact component and helper exports in React SDK package reference.

PDP display composition starts at [Product detail page](/react-sdk/latest/guides/product-detail-page). Keep purchase-adjacent effects in app-owned handlers and API reference.

The React SDK is the composition layer. Search GraphQL and API references remain the contract layer.

## Current handoff rules to preserve

- Provider-backed Search runtime keeps market, store group, and locale together.
- `graphql.storeGroupSlug` can override `groupId` for Search context.
- `mapSearchProductToProductCard()` accepts `storeGroupSlug` so mapped cards can prefer the intended store-group price.
- Product cards and Search UI should display normalized data; they should not silently own cart or checkout side effects.
- Exact Search fields, filter names, fragment coverage, and generated types must come from Search reference, not prose memory.

## Practical agent workflow

1. Decide whether the question is mostly about contract truth or mostly about shopper UI.
2. If contract truth is the problem, start at [Search latest](/search/latest) or the relevant API reference before touching React composition.
3. If shopper UI is the problem, start at [Product listing and search](/react-sdk/latest/guides/product-listing-search) or [Commerce components](/react-sdk/latest/components/commerce).
4. Carry market, store group, locale, and any `warehouseSlug` context through the whole flow.
5. Keep cart, checkout, and other write-side effects in app-owned handlers after the display layer has done its job.

## Common mistakes

Do not let an agent invent Search fields, fragment members, or helper signatures from prose.

Do not treat a Search product card as the place to mutate cart or checkout state. Keep market, store group, and locale together when debugging price or availability mismatches.

Do not move server-side Search loading into browser-only UI code without checking runtime placement. Keep React composition questions separate from OpenAPI or GraphQL schema questions.

## Related routes

- [Search GraphQL latest](/search/latest)
- [React SDK setup](/react-sdk/latest/setup)
- [Product listing and search](/react-sdk/latest/guides/product-listing-search)
- [Commerce components](/react-sdk/latest/components/commerce)
- [TypeScript SDK latest](/ts-sdk/latest)
- [React SDK agent discovery and imports](/ai/react-sdk/latest/discovery)

---

# React SDK discovery and imports

URL: https://docsv3.enad.io/ai/react-sdk/latest/discovery
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.9.3
Version range: >=1.9.0 <1.10.0
Authority: guidance
Domains: react-sdk, storefront, components, theming
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require SDK package reference for this track.
Copy-paste safe: guidance-only

# React SDK discovery and imports

Start here when an agent needs to choose the right React SDK route, component family, or public import surface before writing code.

## Contract scope

- Use React SDK guides for route selection, component-family framing, and safe setup order.
- Use SDK package reference for exact exports, props, hooks, child parts, and helper signatures.
- Do not invent deep import paths from prose.
- Do not copy playground route internals into an app just because a playground example exists.

## Start with the documented public import surfaces

Use these confirmed setup imports directly:

```tsx
import "@enadhq/enad-react-sdk/styles.css";
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";
```

For grouped public barrels, documented storefront refinements, and the few retained deep exceptions, start with [Import surfaces](/react-sdk/latest/guides/import-surfaces) before guessing a path.

Treat everything beyond these setup imports as package-reference truth. When an agent needs a component, hook, helper, or child-part import, it should inspect package reference before writing code.

## Route by job

| Job | Start here | Why |
| --- | --- | --- |
| Root setup and provider order | [React SDK setup](/react-sdk/latest/setup) | Confirms stylesheet, `EnadProvider`, and `EnadThemeProvider` placement. |
| Choose a grouped public entry point or documented exception | [Import surfaces](/react-sdk/latest/guides/import-surfaces) | Keeps root setup imports, grouped barrels, and retained deep seams clear. |
| Build login, signup, password-reset, sign-out, or current-user UI | [Account and auth UI](/react-sdk/latest/guides/account-and-auth-ui) | Keeps the public `client/user` surface aligned with runtime-adapter and Auth API boundaries. |
| Find the right component family | [React SDK components](/react-sdk/latest/components) | Groups the public docs by Base UI, Layout, Storefront, and Commerce. |
| Build shell chrome | [Storefront page guide](/react-sdk/latest/guides/storefront-page) and [Layout components](/react-sdk/latest/components/layout) | Keeps header, footer, navigation, and app-owned routing boundaries clear. |
| Build shopper-facing listing or search UI | [Product listing and search](/react-sdk/latest/guides/product-listing-search) | Separates Search GraphQL truth from React composition. |
| Build PDP or purchase-adjacent UI | [Product detail page](/react-sdk/latest/guides/product-detail-page) | Keeps display composition separate from cart and checkout side effects. |
| Apply theme hashes or component sets | [React SDK theming](/react-sdk/latest/theming) and [Theme from playground](/react-sdk/latest/guides/theme-from-playground) | Explains provider nesting, precedence, and playground handoff. |
| Feed an agent workflow | [React SDK agent guide](/ai/react-sdk/latest) | Gives route selection plus package-boundary rules. |

## Discovery workflow for agents

1. Name the job first: setup, imports, auth/account, layout, storefront, commerce, Search, or theming.
2. Open the matching guide before guessing an import.
3. If the question is import-path selection, check [Import surfaces](/react-sdk/latest/guides/import-surfaces) before inventing a deeper path.
4. Verify the exact component or helper export in package reference.
5. Write the smallest example that stays on documented public package imports.
6. If the example depends on live Search, cart, client, or auth/session wiring, keep that integration at the app boundary rather than burying it inside presentational components.

## Red flags

Stop and re-route before memory replaces package reference.

Common signs include inventing a component, hook, or deep import path from memory. Re-route when an agent treats prose as a prop reference, copies playground wiring into an app, mixes Search contract questions into component selection, or moves cart behavior into a product-display card because the UI surface looks convenient.

## Related routes

- [React SDK latest](/react-sdk/latest)
- [Import surfaces](/react-sdk/latest/guides/import-surfaces)
- [Account and auth UI](/react-sdk/latest/guides/account-and-auth-ui)
- [React SDK agent guide](/ai/react-sdk/latest)
- [React SDK theme and icons](/ai/react-sdk/latest/theme-and-icons)
- [React SDK commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff)
- [Agent files](/ai/artifacts)

---

# React SDK agent theme and icons

URL: https://docsv3.enad.io/ai/react-sdk/latest/theme-and-icons
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.9.3
Version range: >=1.9.0 <1.10.0
Authority: guidance
Domains: react-sdk, theming, playground
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require SDK package reference for this track.
Copy-paste safe: guidance-only

# React SDK agent theme and icons

Start here when an agent needs to restore a playground theme, choose a component set, talk about icon behavior, or explain which runtime boundary owns theme state.

## Provider and runtime boundary

Keep these roles separate:

- `EnadProvider` is the root SDK runtime provider.
- `EnadProvider componentSet={...}` owns app-wide structural set selection.
- `EnadThemeProvider` belongs inside `EnadProvider` when a subtree needs scoped theme state.
- The root provider owns SDK-wide runtime setup such as icon registration and shared client/runtime wiring.
- The theme provider owns scoped token overrides and restored theme hashes.

Use the confirmed public imports only:

```tsx
import "@enadhq/enad-react-sdk/styles.css";
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";
```

When exact icon APIs, icon names, provider options, or theme prop names matter, inspect package reference before writing code.

## Theme restoration rules

- Correct nesting is `EnadProvider` outside and `EnadThemeProvider` around any scoped themed subtree.
- Runtime precedence is explicit `EnadThemeProvider` props, then decoded hash values, then SDK defaults.
- `componentSet` is structural. It changes the resolver-backed UI family, not only colors.
- Token overrides change CSS-variable state and should stay conceptually separate from `componentSet` decisions.
- Use `hash={themeHash}` when restoring richer playground state.
- Use `EnadProvider componentSet="..."` when the app only needs the structural family.

## Playground boundary

Use the React SDK guides to choose provider boundaries. Use the playground to validate the live result.

- The playground owns runtime editing, share URLs, and export flows.
- React SDK guides cover route selection, provider guidance, and package-aware wording.
- `enad-theme` CSS output or exported snippets do not replace `EnadThemeProvider` for runtime restoration.
- Do not copy sandbox-only helpers or route code into a consumer app.

## Icon guidance for agents

Keep icon wiring at the SDK runtime boundary. Use package reference for exact icon registry APIs.

Use this rule:

1. Keep icon setup discussion at the `EnadProvider` boundary.
2. Verify exact icon helpers, option names, or override APIs in package reference.
3. Keep theme state concerns in `EnadThemeProvider` rather than mixing them into icon guesses.

## Troubleshooting order

If a restored app does not match the playground or icon behavior looks wrong, check in this order:

1. `@enadhq/enad-react-sdk/styles.css` is imported once.
2. `EnadThemeProvider`, when used, is nested inside `EnadProvider`.
3. The same `hash` or app-wide `componentSet` used in the playground is being restored.
4. Explicit props are not overriding the intended hash values.
5. Exact icon/runtime APIs were taken from package reference instead of prose memory.

## Related routes

- [React SDK theming](/react-sdk/latest/theming)
- [Theme from playground](/react-sdk/latest/guides/theme-from-playground)
- [Playground](/playground)
- [React SDK agent discovery and imports](/ai/react-sdk/latest/discovery)
- [Agent files](/ai/artifacts)

---

# TypeScript SDK agent guide

URL: https://docsv3.enad.io/ai/ts-sdk/latest
Kind: package-guide
Track: package-ts-sdk
Applies to: package-ts-sdk
Package: @enadhq/enad-ts-sdk
Version: 0.21.3
Version range: >=0.21.0 <0.22.0
Authority: guidance
Domains: ts-sdk, api, search
Exact facts: Exact TypeScript SDK exports, method signatures, generated types, package versions, and runtime behavior require SDK package reference for this track.
Copy-paste safe: guidance-only

# TypeScript SDK agent guide

Use this guide when your task involves `@enadhq/enad-ts-sdk`, `@enadhq/enad-ts-sdk/search`, or the boundary between SDK usage and direct API calls.

## Choose the TypeScript route first

Start here when you need to route package usage, Search helpers, root helpers, and API boundary questions.

Choose a narrower route first when possible:

- Go to [Product listing helpers](/ts-sdk/latest/guides/product-listing-helpers) for listing URL state or REST listing query shaping.
- Go to [Search GraphQL latest](/search/latest) when the task is primarily Search query shape, generated documents, facets, autocomplete, or targeting.
- Go to API reference or OpenAPI-backed routes before writing exact request, response, auth, or parameter code.
- Go to [React SDK agent guide](/ai/react-sdk/latest) when the real job is provider-backed React composition rather than TypeScript package usage.

Use this page to choose the right SDK, API, Search, or helper surface. Check package reference for exact exports, helper signatures, Search documents, and method behavior before writing code.

## Exact reference boundary

- Use docs for setup guidance and surface choice.
- Use TypeScript SDK package reference for exact exports, method signatures, generated types, Search documents, and package behavior.
- Use API reference or OpenAPI specs for endpoint fields.
- Do not hand-author endpoint, GraphQL operation, or fragment truth from memory.

## Safe agent workflow

1. Identify the API, SDK surface, or Search operation the task needs.
2. Check whether the task is SDK usage, direct API usage, Search GraphQL usage, or root-helper usage.
3. Use this guide for boundaries and setup framing.
4. If the task is listing URL state or REST listing query shaping, open [Product listing helpers](/ts-sdk/latest/guides/product-listing-helpers) before inventing app-local utilities.
5. Inspect current package reference when exact signatures matter.
6. Keep auth, app context, market, store group, locale, and runtime placement explicit.

## Search workflow

For Search-specific tasks, start with [Search GraphQL latest](/search/latest) and keep app, market, store-group, and locale context explicit.

Current package behavior:

- `@enadhq/enad-ts-sdk/search` exposes the lower-level Search GraphQL surface.
- `createSearchClient()` is the package-supported Search client entry point.
- `createSearchClient()` needs `appId`, `marketSlug`, `storeGroupSlug`, and `locale`; pass `baseUrl`, `fetch`, or headers only when the runtime needs explicit transport setup.
- Named `SearchClient` methods cover products, product cards, product by slug/SKU, facets, brands, series, category browsing, category lookup by ID or URI, collection browsing, collection lookup by ID or URI, redirects, variants, completions, and product slugs.
- Search helpers return data or throw `SearchClientError` for configuration, HTTP, JSON, GraphQL, or missing-data failures. Do not tuple-destructure Search helper results.
- Brand and series work can use named `searchBrands()` and `searchSeries()` helpers; generated brand and series documents remain available for lower-level execution.
- Product lookup, product slug, and variant helpers default to active records unless a supported `onlyActive` request value overrides that default.
- Keep `warehouseSlug` as a top-level product/facet query variable, not as a `ProductFilter` field.

## Root helper reminder

`@enadhq/enad-ts-sdk` exposes root-package helpers in addition to generated clients and the lower-level Search package. Use [Product listing helpers](/ts-sdk/latest/guides/product-listing-helpers) for listing query options and URL state. The root package also exposes `resolveProductPrice()`, `normalizeVariantStockSignal()`, and `orderProductsBySlugs()`.

The listing helper guide covers names such as `toProductQueryOptions()`, `ProductListingQueryOptions`, `parseProductListingUrlState()`, `serializeProductListingUrlState()`, and `toggleProductFilterValue()`.

Treat helper signatures and return types as package reference truth. Treat tuple-style SDK responses as `[data, error]` on the core Enad API client surface, and keep `normalizeVariantStockSignal()` limited to stock-only variant facts instead of purchase or UI policy.

## Prompt boundary

```text
Use docs for Enad TypeScript SDK routing, but inspect package reference for exact exports, SearchClient methods, generated documents, helper signatures, and method behavior. Use @enadhq/enad-ts-sdk/search and createSearchClient() for package-backed Search GraphQL usage. Search helpers return data or throw SearchClientError; core Enad API client methods use tuple-style [data, error] responses. Use the root package helper guide for listing URL state or REST listing query shaping. Do not invent request fields, response fields, GraphQL fragment fields, or convenience methods. If endpoint truth matters, check API reference or OpenAPI reference.
```

## API usage checklist

- Which Enad app or tenant context does the call need?
- Which API owns the resource?
- Is this a server-side call, browser call, or build-time data fetch?
- Which auth token or credential boundary applies?
- Is there an OpenAPI spec or reference entry for the endpoint?
- Does the React SDK already provide a safer provider-backed surface for the same job?

## Versioning boundary

Docs versioning tracks package versions, not whole-site versions. Use the `latest` agent guide for current package guidance and preserved package-version routes when they exist.
