docs(simulation): Understanding Simulation (concept)

src/pages/docs/simulation/concepts/understanding-simulation.mdx

@@ -0,0 +1,51 @@
+---
+title: "Understanding Simulation"
+description: "How a simulation is assembled from three pieces, and where it fits"
+---
+
+
+## What a simulation is
+
+A **simulation** runs your agent against simulated users so you catch its failures in a test instead of in production. The simulated user plays out a situation, your agent responds, and the whole conversation is scored, in voice or in chat. Run it before you ship, and again after every change, and you have a repeatable read on whether the agent is getting better or worse.
+
+## The three components
+
+Every simulation is assembled from three pieces. The [agent](/docs/simulation/concepts/agent-definitions) is who is tested, the [scenario](/docs/simulation/concepts/scenarios) is what happens, and the [persona](/docs/simulation/concepts/personas) is who is talking. A run brings the three together and executes them.
+
+<div style={{ display: 'flex', justifyContent: 'center', margin: '1.5rem 0' }}>
+  <svg width="240" height="240" viewBox="0 0 200 200" role="img" aria-label="A simulation is assembled from three equal pieces: Agent, Scenario, and Persona.">
+    <path d="M100,100 L100,10 A90,90 0 0,1 177.94,145 Z" fill="#2f2f2f" stroke="#ffffff" strokeWidth="1.5" />
+    <path d="M100,100 L177.94,145 A90,90 0 0,1 22.06,145 Z" fill="#2f2f2f" stroke="#ffffff" strokeWidth="1.5" />
+    <path d="M100,100 L22.06,145 A90,90 0 0,1 100,10 Z" fill="#2f2f2f" stroke="#ffffff" strokeWidth="1.5" />
+    <text x="151.96" y="66" textAnchor="middle" fill="#ffffff" fontSize="13" fontWeight="700">Agent</text>
+    <text x="151.96" y="80" textAnchor="middle" fill="#cccccc" fontSize="10">who's tested</text>
+    <text x="100" y="156" textAnchor="middle" fill="#ffffff" fontSize="13" fontWeight="700">Scenario</text>
+    <text x="100" y="170" textAnchor="middle" fill="#cccccc" fontSize="10">what happens</text>
+    <text x="48.04" y="66" textAnchor="middle" fill="#ffffff" fontSize="13" fontWeight="700">Persona</text>
+    <text x="48.04" y="80" textAnchor="middle" fill="#cccccc" fontSize="10">who's talking</text>
+  </svg>
+</div>
+
+Hold this shape and the rest of Simulation is detail: each of the three pieces has its own page, and everything else is how you run them and read what comes back.
+
+## One loop, walked once
+
+Take a support agent. You point Simulation at it, write a **refund request** scenario, and pick a **frustrated caller** persona. You run it, and a resolution eval fails: the agent quotes the wrong refund window. You shorten the prompt and add the policy, then run the same scenario and persona again. This time it passes, and you have proof the fix worked, not a hunch.
+
+## Where Simulation fits
+
+Simulation is the pre-production counterpart to [Observe](/docs/observe): Observe watches real traffic, Simulation rehearses it. It scores calls with the same templates as [Evaluation](/docs/evaluation), so a bar means the same thing in a test and in production. [Replay](/docs/simulation/concepts/replay) bridges the two by turning a real conversation into a scenario, and when a run exposes a weakness, [optimization](/docs/simulation/concepts/optimization) improves the agent automatically.
+
+## Keep exploring
+
+<CardGroup cols={3}>
+  <Card title="Agent definitions & versions" icon="robot" href="/docs/simulation/concepts/agent-definitions">
+    The agent under test, and how versions track changes
+  </Card>
+  <Card title="Scenarios" icon="list-check" href="/docs/simulation/concepts/scenarios">
+    The test cases that decide what happens
+  </Card>
+  <Card title="Personas" icon="users" href="/docs/simulation/concepts/personas">
+    The simulated customer your agent faces
+  </Card>
+</CardGroup>