# 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 row of kit cards within your native search results: themed
bundles of complementary products composed from your real catalog for the
shopper's search term, with quick-filter chips to narrow the set. By default the cards are
styled to read as your own content — no box around them, no "✨ Poneva-kit" header — though
the branded module look is still available (see [Appearance](#appearance)). The band never
modifies, reorders, or hides your native search results — it only adds a row among them, a few
products down by default (you choose how far). 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.

Every kit card opens into a contents drawer listing each product with its image, title,
price, a link to the real product page, and its own buy button. Newly generated kits can
also label products with the role each plays in the kit — for example the cleansing step
and the serum step in a skincare routine — written in your store's language. A product
without a role label (including every kit generated before roles existed) simply shows
none. A product that is out of stock says so; in-stock rows stay quiet.

## Two ways a kit is triggered

A kit can fire on either of two signals, and both reuse the same generate → review → go-live
lifecycle described below:

- **Search terms.** The classic trigger: the kit shows when a shopper searches a term you
  put live (for example, `halsont`). The term is both the trigger and the seed for what goes
  into the kit.
- **Category pages.** The kit shows when the shopper lands on a category page whose URL
  matches a pattern you configure — for example `https://www.apotea.se/halsont*`. End the
  pattern with `*` to match every page under that prefix; without `*` it matches that exact
  page. Here the trigger is the page URL, so you give the kit a separate **title** (for
  example, `Sömn Problem`) that seeds what goes into it, exactly the way a search term does.
  Use this when your shoppers browse to a category instead of searching for it.

## How you control it from the dashboard

Everything is managed under the **Agentic Kits** capability, set up in two clear steps.

### Step 1 — Your kits

This is where kits come from. When you have no kits yet, the setup opens with the
real-catalog path:

- **Generate kits from your catalog.** Add the search terms kits should target, then
  "Generate kits" composes bundles from your real catalog for each term. Terms are your
  allow-list — kits only ever appear for terms you put live. You can add an optional
  guidance note (for example, "lean premium, max three products per kit") that steers
  every generation in the batch.
- **Add category pages.** Alongside the search-term box, an **Add category** form takes a
  page-URL pattern (where the kit shows, for example `https://www.apotea.se/halsont*`) and a
  title (what the kit is about, for example `Sömn Problem`), plus an **optional AI
  description** that steers what the AI generates for that category (audience, tone,
  constraints — the same idea as the guidance on search terms, but saved per category).
  Category triggers join the same review queue and the same Generate / Approve / Live
  controls as search terms — the only difference is what makes them fire.

Once you have kits, the same step shows the review queue:

- **Each term shows a live status chip** — New, Queued, Generating, Failed, Ready, Live,
  or Paused — and the queue updates itself while generation runs.
- **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.
- **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.

### Step 2 — Where & when kits show

This is where kits land. You point the band at your real search-results page and confirm
where it appears against a **live placement preview** — your own results page, with the band
sitting exactly where shoppers would see it.

- **Search results path.** The page on your site that shows search results — for example
  `/search` or `/sok`. The kit band mounts within those results, a few products down. When
  we can detect the page, we lead with a recommended default you can apply in one click.
- **Search query parameter.** The URL parameter your results page reads the term from.
  Most stores use `q` (the default); change it only if yours differs.
- **Live placement preview.** Below the controls you see a snapshot of your real
  search-results page with the band already injected. As you change **"show the kit after
  this many products,"** the band repositions in the preview immediately — it slides into the
  results after that many product cards, with no fetch and no page reload, so you can dial in
  the spot by eye. Switch the preview between **desktop and mobile** to confirm both widths,
  since results grids reflow differently on a phone.
- **Refresh.** The preview renders a captured snapshot of your results page, so it stays fast
  and consistent. A small **freshness line** tells you when that snapshot was captured; if
  your page has changed since, **Refresh** re-captures it so the preview matches your live
  store again.
- **In your results.** Choose how far down the results the band appears, and whether a kit
  that can't load falls back to your normal results (so shoppers never see an empty space).
- **Advanced — pin to an element.** By default the band finds your results automatically.
  Only set a CSS selector if you want the band pinned to one specific results container.

If a real results page can't be derived (for example, you haven't set a search path yet),
the preview honestly says so and gives you a copy-paste link instead of guessing a page
that might not show results.

**How we know the position holds.** The placement isn't taken on trust. When your agent
learns your search page, it injects the band on the real results page in a headed browser,
drives it through each "after N products" position across desktop and mobile widths, and
records structural proof that the band landed exactly that many product cards down in your
real results grid. That proof — plus the captured results-page snapshot the live preview
renders — is what backs the preview you see here, so the position you pick is the position
shoppers get.

**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

By default the band renders in its **native** style: the kit cards sit directly in your
results with no tinted shell and no header, styled to read as your own content — each card
about twice the width of one of your product cards, with squared-off corners, an
underlined title, and a buy-the-whole-kit button at the same scale as your native
controls. When your results grid can be measured, each kit card sizes itself to span
exactly two of your product-card columns, gutter included, so the row tiles cleanly into
your grid; when it can't, a responsive fallback width applies. The band also renders in
your storefront's own font and colors, picked up when your agent learned your site.

The branded look is still available as the **module** style: a tinted band shell with a
"✨ Poneva-kit" header. Stores that had already set a band background or a module title
keep the module style automatically — those options belong to the shell — so nothing
changes until you switch.

Appearance is configured from the **Design** section of the Agentic Kits capability, and
publishes fail-closed like everything else — an unset or invalid value falls back to the
built-in design rather than serving something broken:

- **Band style** — native (the default) or module, as above.
- **Accent color** — the buy buttons and other kit accents, in both styles.
- **Kit-tag colors** — background and text of the "Kit · N produkter" tag on each card;
  the kit's theme tag borrows the same border color while keeping its own quiet text.
- **Band background** — the module shell's tint (module style only).
- **Module title** — the module header's text (module style only).

The preview uses your own generated or approved kits when they exist.

To give you something real to look at the moment your store is set up, Poneva also seeds a
single **example kit set** — built from your own catalog, for one representative search
term — as soon as discovery finalizes the core catalog tools. It is clearly labelled as an
example ("how your kits will look"), it is **never shown to your shoppers**, and it never
counts as live: you stay in full control of which terms go live in Step 1. If your store
has no catalog data to ground an example, the preview simply stays empty rather than
showing another store's sample products.

## 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).

### Pinning where the band appears

By default the band mounts within the first results container Poneva finds on the page
(using a generic set of structural anchors), after the number of products set by "show the
kit after this many products" — falling back to above the container when it can't count
product cards there. If your search page has an unusual layout — or you want the band in a
specific spot — you can pin its placement two ways:

- **A page anchor.** Add an empty `<div data-skaii-agentic-anchor></div>` wherever you want
  the band to mount; Poneva mounts at that spot before falling back to anything generic.
- **A results selector.** Tell Poneva a CSS selector for your native results container (the
  results-page path and search query parameter go alongside it). Poneva can record this from
  discovery, or you can supply it — the band then targets that container directly.

Both are structural pointers to where results live on the page; neither changes your
markup. One caveat worth flagging up front: if your site sends a strict
`Content-Security-Policy`, the Poneva runtime and the band's styles may be blocked until a
developer allow-lists Poneva's origin in your CSP. That is usually a one-line change, but
it does need someone with access to your CSP config.