The Brief
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:
scripto brief <id>It prints the premise plus every note grouped by kind, with full bodies — one call, fully oriented.
Write to the Brief
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-premisescripto 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?"scripto note list <id>
scripto note get <id> <anchor>
scripto note set <id> <anchor> --title "…" --clear-url
scripto note rm <id> <anchor>Notes are addressed by anchor (a unique prefix of the note id), exactly like sections.
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.
Next
- GET …/brief and the notes endpoints — the HTTP surface.
- The ordered-sections model — the body the Brief is about.