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

# Ground in real records and documents

> Start scenarios from real records in your data, and generate documents that look like your real ones.

By default, the suite invents the records and documents its scenarios use. When realism matters, you can ground them in your own material: real records that scenarios start from, and real example documents that generated documents are modeled on.

| You want | Run |
| - | - |
| Each scenario to start from a real record, such as the account or ticket the user has open | `/upload-scenario-bundle` |
| Generated invoices, forms, tickets or reports to look like your real ones | `/upload-doc-examples` |

Run either after `/simulation-scan-agent` and before `/simulation-generate-suite`. Also see `/ground-scenarios` in [Ground in production traces](https://docs.plurai.ai/guides/ground-in-production-traces.md#not-sure-which-lane), which routes records and conversations for you.

## Start scenarios from real records

```bash theme={null}
/upload-scenario-bundle
```

Use this when a scenario's starting point (the current page, the selected record, the active account) must refer to a real item in your agent's data. For a large pool of records, a [knowledge corpus](https://docs.plurai.ai/guides/knowledge-base.md) can be a better fit.

**1. You choose the records**

The plugin confirms where your data is and asks how many scenarios you want and which slice of the data. A small, representative subset is recommended: 5–10 records that span the meaningful differences (type, value band, status). It then shows you the records it picked to confirm.

**2. One folder per scenario**

Each record gets a folder in `plurai_sim/scenario_bundle/`.

**3. The bundle is uploaded**

The SDK packs the folders into one archive and uploads it. If this is your first upload, the plugin asks whether to anonymize first.

The bundle layout:

```text theme={null}
plurai_sim/scenario_bundle/
  BUNDLE.md                  # optional: an overview of the set
  record_3900043/
    record.json              # the exact real record (JSON or YAML)
    agent_context.json       # recommended: the record mapped into your agent's context
    ROLES.md                 # required: how each field maps, and what not to invent
```

Every folder needs `ROLES.md` and at least one record file. Values in `agent_context.json` take precedence over generated ones. Folder names can't contain `/` or `\`.

You get **Scenario bundle ready** with the set's ID. Then run `/simulation-generate-suite`: each scenario is generated from one folder.

* Records guide generation; they are not copied byte for byte. After the suite builds, the plugin checks that each scenario's record ID exists in your real data and its fields match.
* The bundle applies to the next suite build. A clone of your repo has the bundle's ID but not the local setting that applies it, so its builds skip the bundle and say so.
* A new upload always creates a new set. Rebuilding asks you to confirm before it deletes the old one.

## Model documents on real examples

```bash theme={null}
/upload-doc-examples
```

Use this whenever your scenarios involve a document your agent reads, produces or refers to: an invoice, form, ticket, report, statement, PDF or image. It isn't only for document-extraction agents. The scan asks whether scenarios should include realistic documents; if you said yes, upload examples so they are modeled on real ones rather than generated from a description.

Organize examples by family, one folder each:

```text theme={null}
examples/
  invoice_standard/
    FAMILY.md                # required: name, type, fields, typical content
    example_001.txt
    example_002.txt
  invoice_international/
    FAMILY.md
    example_001.txt
  receipt_retail/
    FAMILY.md
    example_receipt.txt
```

The plugin asks for the folder's path and confirms it. A family without `FAMILY.md` or without examples stops the upload, and nothing is sent. You get a summary such as "Doc example set ready … 3 families · 12 files stored", and the next suite build uses them automatically.

## Files and IDs

| File | What it is |
| - | - |
| `plurai_sim/.scenario_bundle_id` | The record bundle's ID. Committed. |
| `plurai_sim/.doc_examples_set_id` | The document example set's ID. Committed. With [environments](https://docs.plurai.ai/guides/environments.md), it is also recorded in the active environment's manifest. |
| `plurai_sim/scenario_bundle/`, `plurai_sim/doc_examples/` | Local copies of the material. Gitignored. |

## What gets uploaded

Only the records and documents you selected are uploaded, as one archive per upload, after you approve the command. Every upload is recorded in `.plurai/uploads/audit.log`. Uploaded sets stay until you delete them: ask in chat to "delete this set". See [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md).

## Next steps

> [card] [Build the suite](https://docs.plurai.ai/guides/build-the-suite.md)
>
> Generate scenarios from your records and documents.

> [card] [Ground in production traces](https://docs.plurai.ai/guides/ground-in-production-traces.md)
>
> Continue real conversations instead.

> [card] [Knowledge base](https://docs.plurai.ai/guides/knowledge-base.md)
>
> Ground answers in a full corpus.

> [card] [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md)
>
> Anonymization and retention.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.