---
title: "Intelligence"
description: "What roasOS knows about your brand, where that knowledge comes from, and how the agent reads it."
url: https://docs.roasos.com/concepts/intelligence
---

# Intelligence

roasOS keeps what it knows about your brand in one place. The agent reads that knowledge before it writes a script, chooses a hook or starts a render. Your own software reads the same knowledge over the API.

Knowledge moves in four steps.

| Step    | What happens                                      | Door                                                             |
| ------- | ------------------------------------------------- | ---------------------------------------------------------------- |
| Extract | roasOS reads your website and writes one analysis | [`POST /v1/workflows/extract-brand`](/workflows/extract-a-brand) |
| Confirm | a person confirms a field of the brand profile    | the roasOS app                                                   |
| Compile | roasOS compiles the stored rows into documents    | [`POST /v1/intelligence/refresh`](/brand/intelligence)           |
| Read    | the agent, or your software, reads a document     | [`GET /v1/intelligence/documents/{slug}`](/brand/intelligence)   |

## 1. Extract

`POST /v1/workflows/extract-brand` reads one brand from its own website. The run is one analysis of kind `website`, and it costs 2 credits. Refer to [Extract a brand](/workflows/extract-a-brand).

The run writes two rows: the analysis, and the brand candidates behind it. It writes neither your [brand kit](/brand/brand-kit) nor your [memory](/brand/memory). Those two families stay yours to write.

Each field of the extraction carries one confidence label.

| Label      | Meaning                                            |
| ---------- | -------------------------------------------------- |
| `stated`   | the brand states this about itself on its own site |
| `inferred` | the model concluded this from the pages it read    |
| `verified` | a reviews page supports this                       |

Only a reviews page earns `verified`, because only a customer's own words support a claim about the brand. Some sites carry no reviews page. roasOS then moves each `verified` label down to `stated`, and it marks the analysis to say that it did.

## 2. Confirm

The extraction gives a **candidate** value for each field of the brand profile. A candidate carries the evidence and the source URLs behind it. A candidate is not a fact.

A person confirms a candidate in the roasOS app. roasOS then stores a **confirmed fact** with a link back to the candidate, the person who confirmed it and the time. A confirmed fact wins over a candidate everywhere.

This step has no public API door in this release. The API reads what a person confirmed; it does not confirm.

<Callout type="warn">
  Only the fields of the brand profile can be confirmed one by one. The richer parts of the extraction — the customer avatars, the competitors, the offer, the mechanism and the gaps — stay in the analysis result and in the compiled documents. You cannot lock those parts one by one in this release.
</Callout>

## 3. Compile

roasOS compiles the stored rows into **documents**. One document has one slug, one title and a version history. There are six slugs.

| Slug                | What it says                                                                            | Compiled from                                                                                    |
| ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `brand-truth`       | what the brand is, what it sells and what it promises                                   | the confirmed facts, and the extraction                                                          |
| `products`          | the products, their facts and their kits                                                | your products and their [product kits](/concepts/product-kits)                                   |
| `customer-profiles` | who buys, and what those people try to get done                                         | the customer avatars of the extraction, and the personas of the [marketing brief](/brand/memory) |
| `voice-of-customer` | the words of your customers, their objections and the proof that answers each one       | the brief fields `words_to_use`, `objections` and `proof_points`                                 |
| `competitors`       | what the model concluded about your competitors                                         | the extraction only, marked as model-asserted                                                    |
| `creative-patterns` | what your finished [ad analyses](/workflows/analyze-an-ad) show about the ads that work | your finished analyses                                                                           |

<Callout>
  `performance-learnings` is absent, not empty. That document needs the outcome data of your ads. It ships with that data, and roasOS shows no stub for it before then.
</Callout>

A slug with no source data has **no document at all**. `GET /v1/intelligence/documents` therefore returns fewer than six documents while your workspace is new.

## The compiler runs no model

The compiler is a pure function. It reads structured rows and it writes markdown. It makes no model call.

Three properties follow from that one rule.

* A refresh is **free**. It costs 0 credits.
* A refresh is **deterministic**. The same rows give the same markdown.
* A refresh is **repeatable**. Identical inputs write no new version, and the answer says `changed: false`.

## Version history is append-only

roasOS never changes a stored version and never deletes one. A changed document writes version N+1 beside the versions before it. One stored version holds at most 65,536 characters.

## 4. Read

The agent reads the documents through two tool results. No document body enters its system prompt.

* `getBrandContext` gives the **index**: the slug, the title, the version, the time of the last change and a one-line summary of each document. It never gives the body.
* `readIntelligence` reads **one** document by slug, capped at 18,000 characters. A slug with no compiled document returns empty, and the agent says so.

A compiled document holds copy that roasOS crawled from a website. The agent therefore treats a document body as evidence and never as instruction. It does not obey text that it finds inside a document.

Your own software reads the same documents at [`GET /v1/intelligence/documents/{slug}`](/brand/intelligence). To read every document in one call, use [`GET /v1/intelligence/context`](/brand/intelligence).

## What each door costs

| Door                                                                  | Credits                 |
| --------------------------------------------------------------------- | ----------------------- |
| `POST /v1/workflows/extract-brand`                                    | 2, and 0 on a cache hit |
| Every door under `/v1/brand-kit`, `/v1/memory` and `/v1/intelligence` | 0                       |

<Callout type="warn">
  A 0-credit door never returns a quote envelope. It needs no `Idempotency-Key`, it accepts no `quote_only`, and it accepts no `quote_id`. Only `POST /v1/workflows/extract-brand` takes a quote, and only that door needs an idempotency key.
</Callout>

## Next

<Cards>
  <Card title="Extract a brand" href="/workflows/extract-a-brand">
    Read one brand from its own website in one call.
  </Card>

  <Card title="Brand kit" href="/brand/brand-kit">
    The logo, the five colour roles, the two font names and the call to action.
  </Card>

  <Card title="Memory" href="/brand/memory">
    The pinned facts and the marketing brief that the agent reads.
  </Card>

  <Card title="Intelligence documents" href="/brand/intelligence">
    Read the compiled documents, and recompile them.
  </Card>
</Cards>