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

# Concepts

> The five primitives that make up a Canvas template — and how they fit together.

Canvas has five concepts. Once you understand them, the editor and the API both become obvious.

## Template

A **template** is a Canvas — a piece of reusable prompt logic. Each template has:

* A **name** and **description** — surfaced to agents in `list_templates` so they can pick the right one.
* A **key** — a stable identifier (`user-templates/my-deal-readout`, `drafts/follow-up`, or one of Deal Brain's system keys like `daily-brief`). Agents call templates by key.
* A **body** — the structured content, written as blocks and variable tokens.
* A **scope** — who can see it.
* A **status** — whether it's published.

You can think of a template as a typed function: variables are its inputs, blocks describe how to render, and the agent invocation is the call.

## Block

A **block** is a structural element inside a template body. Canvas supports the blocks you'd expect from any rich editor:

| Block                         | When to use                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------ |
| Paragraph                     | Default. Free prose.                                                           |
| Heading (H1–H3)               | Section the output.                                                            |
| Bulleted list / Numbered list | Enumerate items. Lists support nesting and auto-format on `enter`/`backspace`. |
| Blockquote                    | Pull-quote or callout.                                                         |
| Horizontal rule               | Visual section break.                                                          |

Every block has a drag handle on the left edge. Drag to reorder. Press `enter` to add a block below; `backspace` at the start of an empty block to merge with the one above.

<Note>
  HTML insertion (paste-from-web with formatting) is intentionally disabled in the current Canvas release pending a security review. Plain-text paste works as expected.
</Note>

## Variable token

A **variable token** is an inline placeholder. Type `#` anywhere in the editor to open the picker. Variables come in two flavors:

<CardGroup cols={2}>
  <Card title="Data variable" icon="database">
    A value pulled from your Deal Brain data layer at render time. Examples: `opportunity name`, `account name`, `current stage`, `last meeting summary`, any custom field you've defined.

    Renders inline as a blue chip in the editor. At render time the chip is replaced with the live value.
  </Card>

  <Card title="Instruction variable" icon="comment-dots">
    A model directive — not data. Examples: *"Write 3–5 sentences in a confident tone"*, *"Do not invent participants not present in the transcript"*, *"Limit to bullet points; no prose."*

    Renders as a chip with an instruction icon. At render time the chip becomes a hidden directive to the LLM, not literal output.
  </Card>
</CardGroup>

See [Variables](/canvas/variables) for the full catalog and authoring patterns.

## Scope

A template's **scope** controls who can see and call it. There are three scopes, in precedence order:

<Steps>
  <Step title="System (Preset)">
    Authored and maintained by Deal Brain. Shipped to every workspace. Read-only — you can clone a System template into your Organization or User scope to customize it, but you can't edit the System version directly.

    Examples: `daily-brief`, `meeting-debrief`, `draft-follow-up`.
  </Step>

  <Step title="Organization (Team)">
    Authored by anyone in your organization. Visible to everyone in the org. Used to standardize how the team writes briefs, debriefs, and outbound — *"every AE in our org uses this readout template."*

    An Organization template with the same key as a System template **overrides** the System version for everyone in the org.
  </Step>

  <Step title="User (Personal)">
    Authored by an individual, visible only to that individual. Use this for personal experimentation, drafts, and "my own way" templates.

    A User template with the same key as an Organization or System template **overrides** the higher-scope version for that user only.
  </Step>
</Steps>

**Precedence:** User > Organization > System. When an agent calls `generate_template` by key, Deal Brain resolves the most-specific scope visible to that user.

## Status

A template's **status** controls whether it's discoverable and callable:

| Status   | What it means                                                                                               |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| `Draft`  | Author-only. Invisible to `list_templates`. Cannot be rendered by agents. Use draft while you're iterating. |
| `Active` | Published. Visible to `list_templates` and callable by `generate_template`.                                 |

Switching from Active to Draft removes the template from agent discovery without deleting it — useful for temporarily pulling something while you fix it.

## How they fit together

A complete template combines all five:

```
Template:        "Opportunity readout (3-paragraph)"
Key:             user-templates/opportunity-readout-3p
Scope:           User
Status:          Active
Body (blocks):
  ─ Paragraph: "Deal: {{opportunity name}} with {{account name}}, stage {{current stage}}."
  ─ Paragraph: "{{instruction: Summarize the last meeting in 2 sentences.}}"
  ─ Paragraph: "{{instruction: List next-step action items as a bulleted list.}}"
```

When an agent calls `generate_template({ key: "user-templates/opportunity-readout-3p", opportunityId: "..." })`, Deal Brain:

1. Resolves the template (User > Org > System scope precedence).
2. Verifies it's `Active`.
3. Binds the opportunity to the `data` variables.
4. Returns the system prompt plus the rendered body, ready to send to the model.

Next, see how each piece works in detail:

<CardGroup cols={2}>
  <Card title="Variables, deep dive" icon="brackets-curly" href="/canvas/variables">
    Data variables, instruction variables, and the catalog.
  </Card>

  <Card title="Publishing & scope" icon="globe" href="/canvas/publishing">
    The Draft → Active workflow and how scope precedence resolves.
  </Card>
</CardGroup>