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

# Provisioning Concepts

> The build lifecycle FSM, bounded preview vs. full ingestion, handle dedup + idempotency, and the 7-day TTL on preview agents.

# Provisioning Concepts

The mental model behind the Agent Provisioning API: how a build progresses, what
"preview" means, how repeat submits are deduplicated, and how long a preview
agent lives.

## The build lifecycle (FSM)

A build is a **finite state machine**. The worker emits one
[`ProvisioningEvent`](/api-reference/provisioning/build-events-sse#provisioningevent-contract)
on each transition (and on coarse progress ticks in slow phases). The same shape
is delivered over SSE, the poll snapshot, and the webhook — you render against
**one** contract.

```mermaid theme={null}
flowchart TD
    Q[queued] --> D[detecting]
    D --> S[scraping]
    S --> A[analyzing]
    A --> P[provisioning]
    P --> I[indexing]
    I --> R([ready])
    D -. error .-> F([failed])
    S -. error .-> F
    A -. error .-> F
    P -. error .-> F
    I -. error .-> F

    classDef terminal fill:#3B39A7,stroke:#0E172A,color:#fff;
    class R,F terminal;
```

| Phase          | What happens                                           | Notes                                          |
| -------------- | ------------------------------------------------------ | ---------------------------------------------- |
| `queued`       | Accepted, waiting for a worker.                        | First state of a fresh build.                  |
| `detecting`    | Normalizing URL + platform detection.                  | Bad platform → `failed` (`unsupported_url`).   |
| `scraping`     | Fetching channel preview content.                      | Empty/private → `failed` (`private_or_empty`). |
| `analyzing`    | Building creator profile + system prompt.              | Slow phase (\~80s); progress ticks emitted.    |
| `provisioning` | Creating KB + agent, publishing.                       | Establishes the full agent state.              |
| `indexing`     | Embedding + vector upsert of preview items.            | Bounded; finishes in seconds–minute.           |
| `ready`        | **Terminal.** Published + indexed; slug live.          | Carries `agentSlug` + `starterQuestions`.      |
| `failed`       | **Terminal.** Carries `error{code,message,retryable}`. | See the error table.                           |

<Note>
  `ready` is emitted **only** when the agent is published **and** its index run is
  complete (or a phase timeout elapsed) — so the visitor's **first chat is
  grounded** in the creator's content, not answering blind. Thin / partial content
  still publishes and reaches `ready` with a `warning` rather than failing.
</Note>

`progress` is **phase-weighted** so the bar stays honest across uneven phases.
`stepLabel`, `detail`, and `channelTitle` are written for end-user display, so
the client never has to invent copy.

### Timeouts & partial success

* **Each phase has a timeout.** On breach, the worker emits `failed` with the
  matching [`ProvisioningErrorCode`](/api-reference/provisioning/build-events-sse#provisioningerrorcode-table)
  instead of hanging the stream.
* **Partial success:** a channel with thin public content still publishes an
  agent and reaches `ready` with a `warning` (e.g. "Limited public content
  found") — the client sets expectations rather than treating it as an error.

## Bounded preview vs. full ingestion

The build's `mode` flag controls how much content is ingested:

|                 | `preview` (default)              | `full`                           |
| --------------- | -------------------------------- | -------------------------------- |
| Items ingested  | \~8 most-recent                  | All available                    |
| Content         | Transcripts-only, recent-first   | Full media pipeline              |
| Time to `ready` | Seconds to \~1 minute            | Longer (deferred to real signup) |
| Use case        | Landing-page / demo "try it now" | Production agent                 |

Preview is **bounded ingestion** — a small, recent slice indexed fast so the
demo is interactive immediately. For the landing-page / try-it-now use case, use
`preview`; use `full` for a production agent. Both run through the same
provisioning service, selected by the `mode` flag.

## Dedup & idempotency

Two independent mechanisms keep repeat submits cheap and safe:

<CardGroup cols={2}>
  <Card title="Handle dedup" icon="recycle">
    A fresh existing **published agent** for the same normalized handle is
    **reused** — `from-url` returns `status: "ready"` with the existing
    `agentSlug` instantly, **no new build**, no new cost.
  </Card>

  <Card title="Idempotency-Key" icon="fingerprint">
    Sending an `Idempotency-Key` makes a double-submit return the **same** build
    rather than spawning a second one.
  </Card>
</CardGroup>

Together they guarantee a double submit never spawns two builds, and resubmitting
a recently-built channel is instant and free. See
[Auth & rate limits](/developer/provisioning-auth#idempotency).

## Preview agent TTL (7 days)

Preview agents and their knowledge bases are **ephemeral**. A TTL cleanup job
soft-deletes stale provisioned agents/KBs (proposed **7 days**) to bound storage
and vector cost. If a visitor returns after the TTL, simply provision again — a
fresh build runs.

<Tip>
  "Claiming" a preview agent into a real org on signup (to make it permanent) is a
  future / optional flow — out of scope for v1.
</Tip>

## Where this fits

The provisioning chain runs the URL→agent pipeline (light-scrape → creator
analysis → KB + sources → bot + prompt config → publish), orchestrated
server-side by a single `AgentProvisioningService` shared by both this API and
the in-app Creator Wizard. It uses the YouTube / Instagram connectors and the
anonymous chat surface.