# Poneva Storefront AI — full documentation > All pages of https://poneva.com/docs concatenated in reading order. Each page is > also served individually as markdown at https://poneva.com/docs/.md. --- # Storefront AI overview > What Storefront AI is — one script tag plus capabilities you turn on individually from the Poneva dashboard. Storefront AI is Poneva's agentic-commerce layer for your store: one script tag, plus a set of capabilities you turn on individually from your dashboard. Two shopper-facing capabilities are live today — the **[Shopping Assistant](./shopping-assistant.md)**, a chat panel grounded in your real catalog, and **[Agentic Kits](./agentic-kits.md)**, curated product bundles rendered directly on your search pages. Everything is configured and published from the Poneva dashboard; beyond the one-line install there is no theme rework, no catalog feed, and no custom code required. > **A note on identifiers.** Some literal API surfaces — the embed URL, data attributes, > and JavaScript entry points — still carry the platform's former product name, `skaii`. > They are stable, supported surfaces; use them exactly as written in these docs. ## Where to go next - [Quick start: install](./quick-start.md) — the one-line embed snippet and what happens once it is on your site. - [Shopping Assistant](./shopping-assistant.md) — the chat panel: settings, behavior, and placement. - [Agentic Kits](./agentic-kits.md) — the kit band on your search pages and the dashboard lifecycle that controls it. - [How serving behaves](./serving-behavior.md) — the fail-closed guarantees behind everything shoppers see. - [Integration contract & APIs](./integration-contract.md) — for engineering teams that want precise control. - [Agents & MCP](./agents-mcp.md) — operating the platform from an AI agent. - [Roadmap](./roadmap.md) and [Support](./support.md). --- # Quick start — install the embed > Install the Poneva embed with one script tag — loader behavior, install detection, and previewing before going live. Your install snippet lives in the dashboard under **Integration → Install & health**, with your store id already filled in. It looks like this: ```html ``` Paste it into your storefront's `` (or your tag manager). That is the entire install — the same snippet powers every capability you later turn on. ## What happens once it's on your site - **The loader is silent and safe.** It loads asynchronously, never blocks page render, and never throws errors into your site. It fetches your store's published configuration from Poneva and only renders something when your Storefront AI is ready **and** the widget is switched on in your dashboard. Until then, shoppers see your unchanged site. - **Install detection is automatic.** The snippet reports a lightweight heartbeat, so within about a minute the dashboard's Install & health page flips from "Not detected yet" to "Live on your store". The same page shows a per-capability runtime health breakdown, so you can see exactly what is ready before anything goes live. - **The Shopping Assistant appears when you turn it on.** Shoppers get a launcher that opens a chat panel; the assistant answers from your real catalog and shows live product cards, with add-to-cart on supported stores. See [Shopping Assistant](./shopping-assistant.md) for the settings. ## Preview before going live Once your store is ready, opening any page on your site with `?skaii_preview=1` appended to the URL shows you the widget even while it is still switched off for shoppers. The widget on/off toggle, the snippet, and placement options also live under **Shopping Assistant → Settings → Install & placement**. --- # Shopping Assistant > The chat panel grounded in your real catalog — settings, behavior, and placement. The Shopping Assistant is a chat panel grounded in your real catalog. When you turn it on, shoppers get a launcher that opens a chat panel; the assistant answers from your real catalog and shows live product cards, with add-to-cart on supported stores. ## Settings Greeting, example prompts, logo, theme, placement, and the on/off switch are all dashboard settings; changes apply on the next page load with no redeploy. ## Install & placement The widget on/off toggle, the embed snippet, and placement options live under **Shopping Assistant → Settings → Install & placement**. The same snippet from the [quick start](./quick-start.md) powers the assistant — there is nothing extra to install. ## Preview before going live Once your store is ready, opening any page on your site with `?skaii_preview=1` appended to the URL shows you the widget even while it is still switched off for shoppers. Until you switch it on, shoppers see your unchanged site. --- # Agentic Kits on your search pages > Curated product bundles on your search pages — the kit band and the dashboard lifecycle that controls it. Agentic Kits renders a "✨ Poneva-kit" band above the native results on your search pages: themed bundles of complementary products composed from your real catalog for the shopper's search term, with quick-filter chips to narrow the set. The band never modifies, reorders, or hides your native search results — it only adds a row above them. When there is nothing live to show for a term, nothing renders at all. The band also survives in-page (SPA) searches: when the shopper searches again, it updates in place for the new term. ## How you control it from the dashboard Everything is managed under the **Agentic Kits** capability: 1. **Choose terms.** In the Review queue, add the search terms kits should target. Terms are your allow-list — kits only ever appear for terms you put live. 2. **Generate.** "Generate kits" composes bundles from your real catalog for each term. You can add an optional guidance note (for example, "lean premium, max three products per kit") that steers every generation in the batch. Each term shows a live status chip — New, Queued, Generating, Failed, Ready, Live, or Paused — and the queue updates itself while generation runs. 3. **Review on two axes.** **Approve** lives on each kit and means "this content is good". **Live** lives on each term and means "shoppers may see this term". Both must be true before a kit serves. Bulk actions ("Approve all & go live", "Go live") cover the common path, and a "Pause all kits" switch stops serving everywhere instantly. 4. **Preview on your site.** From any term, "Preview on your site" opens your real search page with the candidate kits rendered exactly as shoppers would see them — visible only to you, before anything is approved or live. Preview visits never count in your analytics. 5. **Publish.** Kits appear on your storefront only for stores that have published the capability. The capability page shows **Live** exactly when at least one term is serving. ## Appearance The band uses Poneva's built-in design with your product imagery and prices. Its appearance — the band's title, accent color, and background — is configurable from the **Design** section of the Agentic Kits capability, which shows a live preview of the band beside the controls. ## For engineering teams The band ships inside the same Poneva runtime the embed script loads; Poneva enables and wires it for your store as part of Agentic Kits onboarding, so most teams never touch anything beyond this page. For precise placement control and the wire contract, see [Integration contract & APIs](./integration-contract.md). --- # How serving behaves > Fail-closed guarantees, the 24-hour freshness window, and automatic stock repair for live kits. Serving is fail-closed end to end: if a surface isn't published, a term isn't live, or anything errors, shoppers get your native experience — never a degraded or fabricated one. ## Freshness Served kits come from a fast serving layer, and every product in a live kit is re-verified against your live store within 24 hours; a kit is never served past that freshness window. ## Stock repair When a product goes out of stock, the kit is automatically repaired — fitting replacement products are selected from your catalog while the kit's copy stays untouched and is safety-re-checked — or pulled from serving if no fit exists, with the change surfaced in your Review queue. ## Dashboard actions Dashboard actions (go live, pause, approve) take effect immediately. --- # Integration contract & APIs > The documented integration surfaces for engineering teams — placement anchor, wire contract, and failure modes. The kit band ships inside the same Poneva runtime the embed script loads; Poneva enables and wires it for your store as part of Agentic Kits onboarding, so most teams never touch this page. For teams that want precise control, the documented surfaces are below. This page is also where future raw-API exposure for power users will land — see the [roadmap](./roadmap.md). ## Placement The band reads the shopper's search term structurally from the page URL (common query parameters such as `q`, `query`, `search`, or a configured one) and mounts above your results container. It resolves its anchor in this order: your configured selectors, then an element carrying the `data-skaii-agentic-anchor` attribute, then conservative structural fallbacks. Adding `data-skaii-agentic-anchor` to your search results container is the simplest way to pin exact placement. ## The wire contract The band calls one public, rate-limited endpoint: ``` POST https://poneva.com/storefront/search { "demo_id": "", "query": "", "session_id": "" } ``` The response is `{ base, plan, rendering }`. When nothing should render for the term (surface not published, term not live, no servable kits), `base` is `null` and the page stays native. Otherwise `rendering` carries the kits and recommendations to display, plus optional quick-filter chips. A chip click re-queries the same session via `POST /storefront/search/filter` with `{ "session_id": ..., "filter_id": ... }` — a constrained re-run within the current term, never a new search. ## Failure modes Every failure mode — network error, missing anchor, unpublished surface, empty term — fails closed to your native experience. --- # For agents and automation — MCP > Operate the Poneva platform from an AI agent over the Model Context Protocol. The Poneva platform is agent-operable over the Model Context Protocol: an AI agent can drive the same platform actions a human drives in the dashboard, authenticated as your account and bounded by the same permissions. ## Connecting The MCP server runs over Streamable HTTP at `https://poneva.com/mcp`, authorized via OAuth 2.0 Device Authorization (RFC 8628). Discovery surfaces for agents: - **Server card** — [https://poneva.com/.well-known/mcp.json](https://poneva.com/.well-known/mcp.json) carries the endpoint, authorization endpoints, and the full tool list. - **Agent-readable overview** — [https://poneva.com/llms.txt](https://poneva.com/llms.txt) describes the platform and each tool in plain text, and maps every page of this documentation with its one-line summary. It also points agents at the State of Agentic Commerce reference page and machine-readable JSON snapshot. - **Raw markdown docs** — every page of this documentation is also served as plain markdown: append `.md` to its URL (this page is `/docs/agents-mcp.md`). The full corpus in one response: [https://poneva.com/llms-full.txt](https://poneva.com/llms-full.txt). ## Configuration through tools For programmatic configuration, the `update_assistant` tool changes assistant settings through the same validated path as the dashboard. --- # On the roadmap — not yet available > Directions we are actively designing — not yet available, and not a commitment to a date. These are directions we are actively designing. None of them is available today, and nothing in this section is a commitment to a date. ## Merchant-owned UI through a browser API A documented window-level JavaScript API so headless and composable storefronts can build their own components on top of Poneva's retrieval and assistant intelligence, instead of using the managed widget. Today the managed embed is the supported integration. ## Managed placement slots Named anchor points you place in your theme so Poneva renders its surfaces (launcher, panel, search band) into exact positions you choose. Today the embed manages placement automatically, and the kit band supports the single `data-skaii-agentic-anchor` placement attribute described in the [integration contract](./integration-contract.md#placement). ## An install-prompt generator for coding agents A platform tool that emits a ready-made, mode-specific prompt your coding agent (Claude, Codex) can execute to perform the theme edits for you. Today the install is a single copy-paste snippet, so most stores don't need one. --- # Support > How to reach Poneva support about your integration. Questions about your integration, or something not behaving as described in these docs? Contact Poneva support through your onboarding contact — include your store's domain and, for search-page issues, the search term you were testing.