> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchandising Simulator

> Compare how your Merchandising Agent would answer the same brief under different posture, pricing, and rule choices — through the real engine, without touching your live setup.

The Merchandising Simulator answers the question every seller asks before a
real brief is on the line: **"what changes if we hold price versus close
quickly?"** It runs your baseline configuration and up to three declared
changes against the same frozen brief, through the same merchandising engine
that answers live buyers, and shows you the decisions side by side.

## What a simulation is

A simulation starts from a **scenario**: a pinned brief plus a frozen snapshot
of your configuration, captured by the platform at that moment. The brief can
come from three places:

* a **sample Display brief** the platform provides, so you can test whether
  your current inventory fits that brief before anything real is at stake;
* **one of your own** — paste or describe a brief to your assistant;
* a **brief you actually received**, cloned from your demand history.

You can also bind a new scenario or revision to one active modular inventory
source. In that mode, every considered bundle, offered product, and recorded
execution must trace to that source. The Page shows the frozen source name and
ID plus counts for included and excluded inventory. Missing, ambiguous, and
different-source lineage is excluded rather than replaced with Storefront-wide
inventory. Scenarios created without a source selection keep the existing
all-Storefront behavior.

Each scenario holds a **baseline** — your configuration exactly as captured,
with no changes — and up to three **variants**, each declaring what it changes:
a negotiation posture, a price adjustment, a different rate card, bundle
inclusion/exclusion rules, or a product cap.

## What a run shows

Running a variant executes it through the real merchandising engine and
records a canonical decision record — the same record shape your live demand
produces. Each card shows:

* the **products the engine offered, with their CPMs**;
* a **delta against the baseline run**: how many products moved, exactly which
  products dropped or joined the plan, and the declared price change;
* the **engine's posture** (distinct from anything you declared) and its
  reasoning;
* the recorded **Brief Acceptance decision**: definitely on policy, needs
  human approval, or definitely not on policy. A human-approval result keeps
  otherwise eligible products in the simulation while making clear that a
  transaction cannot proceed automatically;
* for a withheld run, **why no offer was produced** — for example, an
  acceptance-policy decline — alongside what the baseline offered.

Run variants one at a time, or run every remaining variant with one action.
Reruns append to the evidence; earlier runs are never rewritten.

## What a simulation is not

* **It never predicts a buyer.** A run shows what your agent would offer — it
  cannot claim what a buyer would accept, negotiate, or book.
* **It never touches your live setup.** Rate cards, rules, policies, products,
  proposals, and media buys are untouched by any run. Overrides live and die
  inside the simulation.
* **It never leaks into your analytics.** Simulation runs are excluded from
  Brief History, seller analytics, learning, and attribution.

## Replay windows

The frozen inputs behind a scenario are kept for **30 days**. After that, the
scenario's evidence remains readable — every run and decision record stays —
but new runs need a fresh revision captured from your current configuration.
Ask your assistant to capture one; the earlier revision's evidence is kept
alongside it.

## Getting started

The current sample asks for premium US Display inventory. It always uses your
Storefront's current inventory and configuration; it does not add synthetic
Display inventory. If your Storefront does not sell Display, an all-decline
comparison is the expected, honest result—not evidence that the Simulator is
broken. Start from one of your own briefs or an observed brief for a useful
channel match.

For a Storefront with Display inventory, ask your assistant:

> Create a simulation from the sample publisher brief

Then open the Merchandising Simulator, run the baseline and variants, and
compare. For any other channel, use your own brief or clone one from demand
history and try the change you've been debating.