> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prodexlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configurations
> Saved per-order walks through a configuration template: identity containers with chains of immutable revisions.
## Overview
A **configuration** is a saved walk through one [Configuration Template](/product/configuration-templates) for one real-world order, quote, or build slot. It's the output of a [Configurator](/product/configurator) run: the selections, material assignments, and resolved parts list that turn the template's possibility space into a concrete bill of materials for that order.
Configurations live on the **Configurator** page, grouped under the template they were walked from.
## Configuration vs. Revisions
A configuration is a two-level artifact:
* The **configuration** itself carries **identity only** — a name and description. Its purpose is to group all the revisions for one order under one identifier you recognize (*"Heavy-Duty Quote"*, *"Job 12345"*).
* Every state-bearing fact — selections, material assignments, resolved parts list, per-revision notes — lives on a child **revision** keyed by `revision_number`.
The configuration's *active state* is the revision with the highest `revision_number`. Older revisions stay in place unchanged; the revision chain is the audit trail.
## What a Revision Carries
| Field | Notes |
| ------------------------ | ------------------------------------------------------------------------------------ |
| `slug` | Stable identifier for the revision. Descriptive: `v1-baseline`, `rev-3-hardtop-swap` |
| `revision_number` | Integer ≥ 1, monotonic per configuration, immutable once set |
| `revision_notes` | One-line delta vs. the prior revision. Empty on revision 1 |
| `selections[]` | Per option class: which options were chosen |
| `material_assignments[]` | Per material: which attribute values were pinned, from where, and why |
### Selections
Each entry carries `option_class_id`, `chosen_option_ids[]`, and free `notes`. Cardinality is enforced by the class's `selection_type`: `select_one` must land exactly one option, `select_at_least_one` at least one, `select_many` zero or more.
### Material assignments
Each entry carries:
* `material_id` — the stable key from the template tree
* `attribute_values[]` — the pinned values, expressed as `VariantCondition` entries (the same typed union [BOM variant conditions](/product/bom#variant-conditions) use: `boolean`, `discrete_text`, `discrete_number`, `range`). Prefer fully-pinned conditions — a range on a revision usually means a decision is unresolved.
* `source` — **where the value came from**: an ERP part reference, *"customer order PDF line 3"*, a mapping-file row
* `notes` — **why the decision was made**: justification and edge cases
`source`, `notes`, and `revision_notes` carry three different kinds of provenance — where the value came from, why the decision was made, and what changed in this revision. An empty `source` is not a schema error — the state script won't block on it — but it is an audit-trail gap: treat it like an unverified assumption, since an assignment no one can trace can't be evaluated at reconfiguration time.
### Resolved parts list
The Configurator computes a flat parts list from the current selections and material assignments — every material reachable given the option choices, with its pinned attribute values. This is the concrete parts list the configuration produces for the order.
### Phase
A revision moves through four phases as it's walked: `pending` → `selecting_options` → `assigning_materials` → `completed`. The phase is **derived** from the revision's current state — it is not a field you set by hand. See [Configurator](/product/configurator#phases-and-the-state-script) for the full phase model.
## Creating a Configuration
Configurations are created by running the [Configurator](/product/configurator) against a template:
1. Open the template.
2. Create a new configuration under it, named for the order or customer.
3. Gather the order source — order PDF, ERP export, pasted text — to ground selections against. These are cited on each assignment's `source` field rather than attached to the configuration itself.
4. [Dexter](/product/ai-assistant) walks the option tree one confirmed decision at a time, then pins material attributes, source-batched against your grounded inputs.
5. On completion, the resolved parts list is final for this revision.
## Reading a Completed Configuration
Open the configuration and view its highest-numbered revision:
* The **selections** made per option class
* The **material assignments** with their `source`, `notes`, and pinned attribute values
* The **resolved parts list** — every material in scope with its concrete attribute values
* The **revision notes** — what changed vs. the prior revision
Earlier revisions remain available; open any one to see the state at that point in time.
## Reconfiguring
When a completed configuration needs to change — the customer revised the order, a sourced value turned out wrong, a template edit cascaded into the selection set — the Configurator forks a **new revision**:
1. Read the latest revision.
2. Create a new revision with a descriptive slug (`rev-3-hardtop-swap`), `revision_number + 1`, and a `revision_notes` line naming the delta.
3. Carry forward every selection and assignment that isn't changing.
4. Remove the entries that are changing; they become the open frontier the Configurator walks.
5. Resolve any new stale entries or errors, then walk to `completed`.
Existing revisions are never edited. `revision_number` is immutable, and the version chain is implicit in the numbering — there is no parent pointer.
This is advisory, not a product rule: forking is always valid regardless of how much changes. But as a rule of thumb, if a reconfiguration would remove most of the entries, a fresh configuration under the same template is often a cleaner walk than carrying a nearly-empty revision forward.
## Downstream Use
A completed revision's resolved parts list is the handoff point to whatever comes next:
* **Quotes and customer-facing documents** — export the resolved parts list as the confirmed bill for the order.
* **Planning demand** — configurations do **not** auto-create demand orders. Feeding a revision into a [planning run](/product/planning-runs) is a distinct step: either manual (add the [demand order](/product/demand-and-supply) against the SKU) or [pipeline-mediated](/product/templates) (a pipeline that reads the resolved materials and writes the demand).
* **Simulation** — [simulation models](/product/simulation-overview) reference entities through model nodes, not revisions. If a configuration's material set needs to drive a simulation input, wire it through a pipeline.
## Limits and Caveats
* **Configurations are per-template.** A configuration can't move between templates; reconfiguring against a different template means a fresh configuration under that template.
* **`revision_number` is immutable once set.** To change a completed revision, create a new revision — there is no in-place edit.
* **Name revision slugs for what changed.** Slugs like `rev-1`, `rev-2` add no information; `revision_number` handles ordering on its own.
* **Mid-run template edits are global.** They're gated by ask-confirm and appended to the template's `revision_log`, but every other configuration against the same template sees the update on its next state-script call.
* **Stale entries are dropped deterministically**; errors with exactly one valid repair are applied directly, and anything ambiguous becomes a user decision through the ask-confirm loop.
* **Nothing downstream is automatic.** Completing a revision hands you a parts list; it does not commit demand, allocate supply, or schedule production.