---
title: The Brief
description: An article's unpublished context — a prose premise plus typed notes (source, decision, idea, question) — the agent-to-human handoff, readable in one call.
---

The **Brief** is the curated, never-published context behind a piece: the sources not yet cited, the decisions already settled, the open ideas and questions. Its job is **handoff** — a fresh agent (or the author weeks later) reads it in one call and is oriented without scrolling a transcript.

## Two halves

| Half | What it is | Stored as |
|---|---|---|
| **Premise** | A short prose orientation paragraph: what the piece is, its angle, where it stands. | `article.premise` |
| **Notes** | Typed, deliberate entries — one fact, decision, idea, or question each. | `note` rows |

Both are **internal**. The premise is distinct from the published `subtitle`; notes never appear in the story.

## Note kinds

A note's `kind` is one of four:

| Kind | Use it for |
|---|---|
| `source` | A reference — often a bare title + `url`, optionally with a note on why it matters. |
| `decision` | A settled call ("we lead with the install, not the features"). |
| `idea` | An angle or addition to consider. |
| `question` | An open question to resolve before publishing. |

Each note carries a short `title`, an optional Markdown `body`, an optional `url`, and a `createdBy` provenance flag.

## Provenance

Every note records who wrote it: **`agent`** (a CLI / Bearer write) or **`human`** (a web / session write). The provenance lets the author trust and prune what an agent captured — an agent's `question` is a prompt to the human, a human's `decision` is a constraint on the agent.

## Read the Brief

The first thing a fresh agent should run to pick up an article:

```bash
scripto brief <id>
```

It prints the premise plus every note grouped by kind, with full bodies — one call, fully oriented.

## Write to the Brief

<Tabs>

<Tab label="Set the premise">

```bash
scripto brief <id> --premise "A go-to-market piece: the install is the pitch. Draft, leans on the agent loop."
# or from a file / stdin:
scripto brief <id> --premise-file premise.md
scripto brief <id> --clear-premise
```

</Tab>

<Tab label="Add a note">

```bash
scripto note add <id> --kind source   --title "Medium import docs" --url "https://help.medium.com/…"
scripto note add <id> --kind decision --title "Lead with the CLI"   --body "Every answer starts with scripto <cmd>."
scripto note add <id> --kind question --title "Free-tier limit?"
```

</Tab>

<Tab label="List / edit / remove">

```bash
scripto note list <id>
scripto note get  <id> <anchor>
scripto note set  <id> <anchor> --title "…" --clear-url
scripto note rm   <id> <anchor>
```

</Tab>

</Tabs>

Notes are addressed by **anchor** (a unique prefix of the note id), exactly like sections.

<Note>

The Brief is the home for the agent↔human handoff. Capture decisions and open questions as you draft, so the next session — agent or human — picks up where you left off instead of re-deriving the context.

</Note>

## Next

- **[GET .../brief](/api-reference/get-brief)** and **[the notes endpoints](/api-reference/list-notes)** — the HTTP surface.
- **[The ordered-sections model](/concepts/sections)** — the body the Brief is about.