# Intelligence

> What a Space knows: documents, references, characters, styles, palettes and templates, @ mentions, the Intelligence tab, a reference's page, and publishing versions.

A Space keeps what you know about the work as well as the work itself: briefs, scripts, guidelines, characters, styles, colour palettes and prompt templates. The Assistant finds what's relevant, reads it when it needs it, and uses it to make work that stays consistent. You don't have to set anything up first. Bring what you have, and the Assistant helps you turn it into knowledge you can reuse.

It's all under a Space's **Intelligence** tab (see [The Intelligence tab](#the-intelligence-tab)). Scripts and storyboards have [their own page](/create/storyboards/), and so do [skills and workflows](/create/skills-and-workflows/).

## Documents

Documents are Markdown, kept in the Space's library like its images and videos: in folders, in Trash for 30 days when deleted, and seen by whoever can see the Space.

- **New → New document** in a Space's library, or in a Canvas's library panel, starts one in the folder you're in, named "Untitled", and opens it with its name ready to type over.
- **Upload asset** also takes Markdown (`.md`) and Word (`.docx`) files. Markdown becomes a document you can edit. A Word file is kept exactly as it was, as the source to extract from.
- Open a document to edit it. It has three views:
    - **Visual** (where it opens): edit it as it reads. The toolbar has bold, italic, code, links, headings, lists, checklists, quotes, code blocks and dividers. On a phone, or in a narrow window, it shows bold, italic, links, a heading, lists and checklists, and the rest are under **More formatting** (**⋯**). Markdown shortcuts work as you type (\`# \` for a heading, \`- \` for a list, \`[ ] \` for a checklist item, \`> \` for a quote, \`\`\`\` \`\`\` \`\`\`\` for code), as do ⌘B, ⌘I, ⌘E, ⌘K, ⌘Z and ⇧⌘Z;
    - **Source:** the Markdown as written;
    - **Split:** the source beside how it reads (not on a phone).
- Nothing is lost between views. Anything the visual view doesn't edit (tables, pictures, footnotes, raw HTML) is shown exactly as written, and edited in the source. Parts you don't change in the visual view stay exactly as they were. Only what you change is rewritten.
- **Checklists** are list items with a box: click the box to tick it. They're kept as `- [ ]` and `- [x]` in the Markdown.
- Click the document's name at the top to rename it.
- It saves as you stop typing. The top of the document always says how saving is going: **Saving…**, **Saved** (point at it to see when), **Couldn't save** with **Retry**, or **Offline**, when what you type is kept on your device until you're back online.
- If you leave the document while a change can't be saved (saving is failing, you're offline, or it changed elsewhere), it asks first: **Stay**, or **Leave anyway**, which keeps your text on your device to offer back next time. Leaving with a change still to save saves it first, without asking.
- If it changed somewhere else meanwhile, it says so and keeps your text rather than saving over theirs: **Copy your text** copies it, and **Load latest** replaces it with the saved version.
- If it's moved to Trash somewhere else while it's open, it stops saving and says so. Anything you hadn't saved is kept on your device: restore the document and open it again to recover it.
- **If you lose your connection,** what you type is kept on your device. It's saved when you're back online, and if you close the page first, opening the document again offers to restore it.
- The **⋯** menu at the top has **Download .md**, which saves it as a `.md` file, and **Move to Trash** (with **Undo**).
- In the library, a document's card shows its first lines, and the Kind filter's **Document** shows only documents. **Duplicate** makes a copy beside it, named "… copy": if its front matter has an `id`, the copy gets the next free number (`jax-2`). A document that defines a reference keeps its collection in the copy: its pictures and videos (with their roles, descriptions and whether they're approved or inspiration), its supporting documents and what it depends on, linked to the same Assets and references, which aren't copied. The original doesn't change, and the copy has no published versions until you publish it.
- Opened from a Canvas's library panel (double-click a document, or choose **Open**), the header's breadcrumb shows the Canvas's name before the document's: choose it to go back to that Canvas, on the Page you were on, where you were looking, with the library panel open as you left it. Opened from a Space's library, it shows **Assets**, which goes back to the library as you left it.

A document can start with **front matter**: fields between `---` lines at the top, such as `type: character` and `id: jax`. They're shown as properties and kept as you wrote them. `type` says what it is, and `id` names it: you mention it as its type then its id, so `type: character` with `id: jax` is `@character-jax`, and `type: vehicle` with `id: explorer` is `@vehicle-explorer`. An `id` that already starts with its type isn't repeated (`type: style` with `id: style-isometric` is `@style-isometric`), and a plain document (`type: document`, or no type) is mentioned by its `id` alone. Without an `id`, a document is named from its title when it's made, and keeps that name. Any type works, including your own; a type alone never makes anything run.

### Asking the Assistant about a document

An open document has the Composer floating over it, talking in the document's own conversation: the same one each time you open it. Ask about it ("what's missing from this brief?") and the Assistant reads it as it is now before answering. It also knows the Space's references, so `@` works as anywhere else in the Space. Nothing is made from a document's page: to make an image or a video, ask in the Space or on a Canvas.

Ask for a change ("tighten the second section", "add a shot after shot 3 for the forklift") and it proposes an edit for you to review. The edit shows what it removes and what it adds, line by line. Nothing changes until you choose:

- **Apply** saves the edit as the document's next version, and the editor shows it straight away.
- **Discard** leaves the document as it is.

If the document changed after the Assistant read it, whether you typed or someone else saved, Apply doesn't save over it. The edit says the document changed since, and **Ask again** writes a request for it in the Composer, to send when you're ready: the Assistant reads the document again and makes the edit from it as it is now. A very long document can be asked about, but it's too long for the Assistant to edit whole.

Only people who can edit a document see the Composer on it. Replies are paid for from your usage, like any other reply in the Space.

## References and @

Everything a Space knows can be named with `@`: documents, scripts, scenes, shots, pictures, characters, styles, palettes and templates. Type `@` in the Composer to choose one from a list of the Space's references, with its type and title to tell similar names apart. Arrows move through the list, Enter or Tab picks one, and Escape closes it. What you pick is highlighted in the text, and one Backspace (or Delete before it) removes it whole.

- **Each `@` name belongs to one reference in its Space.** A document whose type and `id` give a name another reference already has, even one in Trash, isn't made, imported or saved. It says, for example, "@character-jax already exists in this Space. Choose a different ID." When you're editing, your text stays in the editor, unsaved, until you change the `id`. Titles don't have to be unique.
- A reference keeps its identity when you rename or move its document, or change its title, so earlier messages and generations still point at the right thing.
- Changing a document's `id` or `type` changes the name it's mentioned by. The old name still finds it, in earlier messages and when you type it again, unless another reference now has that name: a current name always wins.
- What you choose with `@` is given to the Assistant as the whole reference, for that message, at the version you name (its latest published one unless you write `@v2` or `@draft`):
    - **its primary document first,** always, and in full within a generous limit;
    - **its supporting documents,** listed by title with their size and first line. The Assistant opens one when your question needs it, as that version pinned it. They add context and never override the primary: where they disagree, the primary wins;
    - **its pictures and videos,** with their roles, and **what it depends on,** at the versions pinned.

  It also reads other references when it needs them, and a root document named **README** as the Space's entry point.

- **Pictures are chosen for what you ask.** Approved pictures come first, and one whose role or description your words mention leads: "a front view of @character-jax" puts a picture with the role **Front view** first. Any role works this way, including your own. Inspiration pictures are used only when what you ask is about them, and only as inspiration, never as what the character looks like. Videos are never sent with an image. [Consistent shots](/create/storyboards/#consistent-shots) choose pictures the same way, and how an image was made records each picture's roles and whether it was approved.
- An image the Assistant proposes or makes for a message naming a character, style, product or place is made with that reference's **current** pictures. They come after the images you attached, which keep their numbers: in "@character-jax skydiving over the landscape in Image 1", Image 1 is the image you attached, never one of Jax's pictures. The card shows the attached images as Image 1, Image 2… and the reference's pictures under its name. If the model takes fewer images than that, your attached images are kept and the card says how many of the reference's pictures were left out.
- Asking for a change to an image ("regenerate it", "make the sky darker") keeps the pictures it was made with. Name the reference again (for example after changing its pictures) and its current pictures are used instead.
- Beneath a reply, **Used:** lists the references it was given. Each opens.
- What a document says is information for the Assistant, never instructions to it. It can't approve anything paid or change how the Assistant behaves.

## Characters, styles, palettes and templates

### From your own pictures

Choose one or more images in a Space's Assets, or on a Canvas, and choose **Add to Intelligence…**. Add them as:

- **Image:** each picture becomes a reference of its own, such as `@logo`. A picture that already is one keeps the name it has;
- **Character**, **Style**, **Product** or **Place:** one document with the pictures linked. It's named `@character-worker`, `@style-isometric` and so on, and has headings ready for its rules (for a character: what must stay the same, and what may vary);
- **Colour palette** (named the same way, such as `@colour-palette-brand-colours`): the main colours are read from the pictures, in your browser, with their names and how much of the pictures each covers. Rename them, change a colour's value (written exactly as `#RRGGBB`), **Add colour** for one the pictures don't show, and remove any you don't want. They're saved exactly. Reading colours is free, and the same pictures always give the same colours. If a picture's colours can't be read, it says so, with **Try again**.

  **Import colours from CSS or tokens…** takes pasted CSS custom properties (`--safety-red: #E52329;`) or design-token JSON. Its colours are proposed for you to keep or leave out before they join the palette. Anything it couldn't use is listed with why, such as a colour written as `rgb(…)` or one with transparency: a palette keeps solid `#RRGGBB` colours, never converted or guessed.

You can change the name it's mentioned by before adding it. Nothing is saved until you choose **Add**. If another reference already has that name, or adding fails, it says so and you can try again.

### From scratch

In the Intelligence tab, **New** makes a **Character**, **Style**, **Product**, **Place**, **Colour palette**, **Prompt template** or **Document** and opens it in the document editor. Each starts with the front matter that makes it what it is (`type`, its `id` and its `title`) and headings to write under: a character's what must stay the same and what may vary, a style's rules, a palette's colours as `- name: #RRGGBB` lines, and a prompt template's questions and its prompt (see [Prompt templates](#prompt-templates)). Its `id` starts as `new`, so a new character is `@character-new`. If that's taken, the next free number is written into its `id` (`new-2`, so `@character-new-2`). Change its `id` to name it as you'll mention it.

### Prompt templates

A prompt template is a prompt you use again and again with different answers. It declares the questions it asks in its front matter, and writes `{{name}}` in its prompt where each answer goes:

\`\`\`markdown
---
type: prompt-template
id: product-shot
title: Product shot
medium: image
variables:

    - name: product
    question: Which product?
    kind: reference
    - name: surface
    question: What does it stand on?
    kind: choice
    options: [marble, sand, linen]
    default: marble
---

# Product shot

## Prompt

A studio photograph of {{product}} on {{surface}}, in soft daylight.
\`\`\`

- Each question has a `name`, the `question` to ask and a `kind`: `text`, `choice` (with its `options`), `number`, or `reference` (an `@` reference from the Space, such as a product, a character or an image). A `default` fills it to start with; a question with no default must be answered.
- Its prompt is the text under `## Prompt`. Without that heading, it's the whole document under its title.
- `medium` is `image` (the default) or `video`.
- A `{{name}}` that isn't one of its questions, or a choice without options, is said on its page, and it can't be used until it's fixed.

**Using one.** Write `@prompt-template-product-shot` in the Composer in Ask and send it, or choose **Use** on its page. Its questions appear as a card in the Assistant (full screen on a phone), with each default filled in and your last answers offered. A preview shows the prompt as your answers fill it. Choose **Make** and it's made, like any image or video you ask for. Write what you want with it ("@prompt-template-product-shot for the blue mug on sand") and the Assistant fills in the answers from your words for you to check.

A reference you give as an answer is written into the prompt by its title, and its pictures are sent with it. The card stays after it's made: change the answers and choose **Make again** for another.

**Steps.** A template can make more than one thing, in order: a scene, then variations of it, then a video of it. Write each step under its own `## Step:` heading instead of `## Prompt`, and use `{{steps.name.output}}` where a step uses the picture an earlier one made:

\`\`\`markdown

## Step: Scene

A studio scene with {{product}} on {{surface}}.

## Step: Variations

Three variations of {{steps.scene.output}}, each in a different colour.

## Step: Turntable (video)

{{steps.scene.output}} turning slowly on its plinth.
\`\`\`

- A step's name is its title in lowercase, with hyphens for spaces: `## Step: Make variations` is `{{steps.make-variations.output}}`.
- A step makes the template's `medium` unless its heading says `(image)`, `(video)`, `(text)`, or audio's job: `(voice-over)`, `(sound effect)` or `(music)`.
- An earlier step's picture is sent with the step, and its place in the prompt is written as `Image 1` (then `Image 2`, in the order the prompt uses them). A later step can use a picture or text, but not a video or audio.
- A template has at most 6 steps. A step that uses a step that doesn't come before it, or has no prompt, is said on its page.

**Steps that write text.** A step whose heading says `(text)` writes text instead of making a picture: a description of the scene, a caption, a shot list. Where a later step uses `{{steps.name.output}}`, the text it wrote is put into that step's prompt:

\`\`\`markdown

## Step: Scene (text)

Describe, in two sentences, a calm studio scene for {{product}}.

## Step: Picture

{{steps.scene.output}} Photographed in soft light.
\`\`\`

- The Assistant's model writes the text (OpenAI's, or Claude where OpenAI isn't available). Only the step's prompt is sent, without pictures, so a text step can use an earlier step's text but not its picture.
- Writing it is charged to your usage, like asking the Assistant. Before it is written, the most it could cost is set aside: well under a cent. Then you're charged for what it actually used. If it fails, you're charged nothing, and you can choose **Write** again. If your usage can't cover it, the card says so and nothing is written.
- At most 2,000 characters of what it writes are used in later prompts.

**Steps that make audio.** A step whose heading says `(voice-over)`, `(sound effect)` or `(music)` makes that kind of sound (see [Making audio](/create/audio/)). Its prompt is the words to speak for a voice-over, or a description of the sound or the music. Audio is made from words alone, so it can use an earlier step's text, but not its picture; and no later step can use the sound it makes. It's made with the job's settings in the Composer (a voice, a length), or the model's defaults:

\`\`\`markdown

## Step: Script (text)

A two-sentence welcome to {{place}}, warm and unhurried.

## Step: Narration (voice-over)

{{steps.script.output}}

## Step: Ambience (sound effect)

Soft wind and distant birds at {{place}}.
\`\`\`

**Make** makes or writes the first step. The card then lists the steps, with what each has made and the text each has written, and offers the next one (**Make Variations**, or **Write Caption** for a text step) once the step it uses is made. Each step is made or written only when you choose it. An image, video or sound costs what it costs, like anything you make; a text step costs what writing it costs. The template's page lists its steps with a preview of each prompt, with `[Scene text]` where an earlier step's text will go.

**Which version.** Using a template uses its latest published version, or its draft if it has never been published. If you can change it and its draft differs, **Try the draft** uses the draft instead, marked **Draft**. Each time it's made is kept as a run of the template, with its answers and the version it used.

A template that declares no questions and has no `## Prompt` or steps is read by the Assistant as knowledge, as before: the consistent-scene skill reads its objective and requirements.

### Your own types

A Space isn't limited to these types. Write any `type:` in a document's front matter and, once it's saved, that's a type of the Space's own:

\`\`\`yaml
---
type: vehicle
id: explorer
title: The Explorer
---
\`\`\`

It's mentioned as `@vehicle-explorer`.

- Your types appear under **This Space's types** in **New**, so the next Vehicle starts with `type: vehicle` already written. They group, filter and search in the Intelligence tab like any other, and work with `@`, the Assistant, versions and sharing in the same way.
- Case and spacing don't matter: `Vehicle`, `vehicle` and  `VEHICLE ` are one type. A name made of several words becomes one with hyphens (`Motion principles `is `motion-principles`, shown as "Motion principles").
- A type belongs to its Space, and lasts as long as a document of that type is in it.
- A type never lets a document do anything. Only a skill or a workflow can run, and only once it passes its checks (see [Skills and workflows](/create/skills-and-workflows/)).

### The Intelligence tab

A Space's page has three tabs: **Work**, **Assets** and **Intelligence**. Intelligence shows everything the Space can name with `@` in one grid, newest first: characters, styles, colour palettes, products, places, prompt templates, images, scripts, shot lists, scenes, shots and documents, each card naming its type. Search by name, `@` or type, or pick a type, your own types included, to show only that one.

Each reference is a card: its first picture (a palette's colours, or its type's icon), its title, its `@` name, its type and how many items it holds. A published one shows its version, such as **v2**, with a dot while it has unpublished changes. If the Space has a document called **README** at the top of its Assets, it's shown first as **Start here**, with its first lines, until you search or pick a type.

A picture opens in the Image Editor. Anything else opens its own page (see [A reference's page](#a-references-page)). If the tab or a reference can't be loaded, it says so, with **Try again**.

Each entry's **⋯** menu (or right-click) opens it. A document can be moved to **Trash** from there, with **Undo**, and its reference goes with it. An image reference can be **removed from Intelligence**: the image itself stays in Assets. Scenes and shots are part of their script, so they're changed by editing or extracting the script again, and a reference with published versions can't be removed, because what was made with it depends on them.

### A reference's page

A reference's page shows everything it holds, using the full width. **Intelligence** in the header's breadcrumb, or your browser's Back, returns to the Intelligence tab. At the top of the page are its picture, title, type and `@` name (click it to copy). At the top right are:

- **Where it stands:** **Draft** before it's first published, **v2** when it's up to date, or **v2 · 3 changes** with unpublished changes. Click it for its version history.
- **Publish…** or **Review changes**, when there's something to publish.
- **+ Add**.
- **⋯**, with **Version history**, **Copy @name** and **Move to Trash**.

The page has three sections:

- **Media:** its approved pictures and videos, in order. The first is its cover, shown large, and all of them are used when it's named. Drag pictures into a new order, or use **Move earlier** and **Move later** in a picture's **⋯** menu. Click one to open it in the Image or Video Editor. The editor's close button says **Back to Jax** and returns here, as does **Jax** in the header's breadcrumb. **Remove** unlinks it, with **Undo**: the image stays in the Space. **Inspiration** follows: pictures and videos linked for context only, such as moodboards and early sketches. They never define the reference until you choose **Make canonical**. A small amber dot marks anything changed since the latest version.
- **Documents:** the primary document, which defines it (its type, `id`, title and style), then any supporting documents. Supporting documents add context, such as a backstory or wardrobe notes, and never override the primary. **New document** makes one and opens it. A supporting document's **⋯** menu has **Make primary…** and **Remove**; the document stays in the Space. **Make primary…** moves the type, `id`, title and style into it, and the old primary becomes a supporting document. Its `@` name stays the same, and published versions don't change. If either document changed since you opened the page, it says so, reads them again and asks you to confirm again.
- **Relationships:** the style it's drawn in and the other references it depends on, such as the place a character belongs to. Each opens its own page. Dependencies are pinned at their latest published version when you publish, so publish them first.

**+ Add** adds pictures or video from the Space, an upload from your computer, a new or existing document, or another reference it depends on. Pictures and videos you add here are approved by default. Choose **Inspiration** in the picker to add them for context only. Uploads go into the Space's Assets and are added as approved. You can also drop pictures or videos onto a reference's page, or paste a copied image there, to upload and add them in one step. Nothing is moved or copied: each Asset stays where it's filed, and one picture can belong to several references.

**Roles:** each picture or video can have a role, such as **Identity**, **Front view** or **Motion**, and a short description. Point at it and click **Add role** under it, choose a suggestion or type a new name, which becomes a suggestion for the whole Space. Roles and descriptions are optional, and there's nothing to set up.

Approving a picture, moving one to inspiration, a new role, reordering, a document edited or linked and a dependency added are all **unpublished changes**: what you make keeps using the published version until you publish again. Someone who can only view the Space sees the page without any of these controls. A scene or shot shows its pictures, and is changed in its script.

A reference's **⋯** menu, at the top of its page or on its card, can move a document's reference to **Trash** (with **Undo**) or remove an image reference from Intelligence, as described above.

### With the Assistant

Ask the Assistant to make one from what you have:

- "Create a character reference from these", with pictures attached;
- "Extract the brand colours from this CSS" (or from design tokens, or a document; from a picture, its colours are suggestions). Anything it couldn't read is listed on the proposal, each with why;
- "Use this as our isometric style";
- "Save this as a prompt template".

It drafts the reference as a document and shows it to you. **Save to Space** keeps it; until then nothing changes. The Assistant never changes a saved standard by itself, only suggests changes for you to make.

The Assistant can look at a reference's own pictures, so you never need to attach them again. Ask "update the description of @product-the-lakes-boundless from its bottle pictures" and it looks at up to four of them (the ones that fit what you asked, by their roles), compares them with its text, and proposes an update for you to review, naming any picture that looks out of date. Nothing changes until you apply it.

To give pictures to one you already have, such as a character you wrote before you had pictures of it, select the image on a Canvas (or attach it, or open it in the Image Editor) and say "add this image to @character-worker". The Assistant links it straight away, because you asked, and says how many pictures it has now. A picture it already has isn't added twice. Remove any on its page.

### Publishing versions

Improve a character over time without losing what worked. A character, style, product or place is a draft until you publish it: open its page from the Intelligence tab and choose **Publish…**. Once it's published, **Review changes** shows exactly what changed since: the primary document line by line, supporting documents, media (with an edited picture's before), roles and relationships. Describe the version if you like, then choose **Publish v2**. **Ask the Assistant to check** asks it to compare the media with the text and suggest updates instead.

- A published version keeps its text, its pictures exactly as they were (later edits to an image don't touch it), its supporting documents, every picture and video with its role and whether it was approved or inspiration, its style, the versions of what it depends on, and its links. It never changes. Open **Version history** to see what each version pinned.
- Once something is published, everything that uses it gets its latest published version. Your later edits wait in the draft, counted as changes beside its version, until you publish again, so work in progress never leaks into what you make.
- Earlier versions are kept. Use one on purpose by writing its number: `@character-jax@v1`. Try your unpublished changes with `@character-jax@draft`.
- "How this was made" under an image says which version it used, and when a newer one exists. **Run again** uses the newest; the image itself never changes.

### A character's style

A character's identity and how it's drawn stay separate. To draw a character in the same style every time, name the style in its front matter:

\`\`\`yaml
style: style-anime
style\_rule: required   # or preferred
style\_version: 2       # optional
\`\`\`

- **Required:** it's always drawn in that style unless you name another style for that one request. **Preferred:** it's drawn in that style unless you ask for a different look.
- Publishing the character pins the style's version: `style_version` if you give one, otherwise the style's latest published version. Publish the style first.
- When the style is improved and published again, the character keeps the version it pinned, and its page says a newer style version exists. Publish the character again to adopt it.
- Naming another style in a request (or choosing one for a shot) uses that style just for that image. The character's own style is unchanged. The image's **How this was made** names the style it used, and **Run again** keeps it.

### When pictures and text drift apart

Edit one of a character's pictures, say to change its hair from brown to yellow, and its text and other pictures are out of date. Its page notices: its version shows how many changes there are, and **Review changes** shows them (pictures edited, added, removed, approved or moved to inspiration, roles, its text, its supporting documents, what it depends on, and a newer version of its style or of something it depends on).

**Ask the Assistant to check**, in **Review changes**, puts a message in the Space's Assistant, on the reference's page, with the changed pictures and the others attached. It's offered for any of those changes, including a picture removed or the style assignment changed, since its text may still describe them; a newer version of its style or of what it depends on alone is adopted by publishing again. If you send it, the Assistant compares them and proposes an update: revised text, what it changes, and which other pictures now look out of date, and why. Nothing changes until you choose **Apply to draft**, which works only if the draft hasn't changed since. **Remove** unlinks an out-of-date picture from the draft; the image stays in the Space. Nothing is ever regenerated, replaced or published for you: when the draft is right, publish the next version.
