Presentation

---
name: presentation
description: "Present to the owner: each kind of message, its parts in order, the pictures, the pages and the message command. Apply to every message that the chief sends to the owner in sage mode: a progress note, a question, a report, a catch-up, a design, and the other kinds below."
license: MIT
metadata:
  source: "the owner's approved formats (the example pages of T984 and the settled catch-up, question and report, 11 Nov 2026), the text formats research (T998), the picture research (T999) and the display research (T1000)"
---

<!-- Generated by scripts/build.mjs from the sources; edit the source, then run npm run build. -->

# Present to the owner

Each message to the owner has one kind, and each kind has a fixed shape. The owner reads results after time away, often on a narrow screen. So a message names its kind first, says the news in its title, and ends with what you need. Write the text at 80% of Simplified Technical English, with sage's dictionary words.

## The cold-read test

Before you send a message, read it as the owner would after a week away, with no other context. Rewrite it until each answer is yes:

- Does the first line name the kind, and does the title say the news or the question?
- Does each part say one thing, fully, in words that a new reader knows? Say fewer things, each in full.
- Does the text name each piece of work by its name, not by an id? Ids go only in the Ref line.
- Does each time figure say agent time or human time, with its basis and a range?
- Is sample or simulated data labelled as such?
- Does the last part say what you need from the owner, or say "nothing"?

## Rules for every message

- **The first line** is the kind's head, for example `QUESTION` or `INCIDENT · Resolved`. The checks read the kind from it.
- **Where this is**: release › milestone or single task › step, for example "Release 1.0 › milestone 5, Sage feel › step: review". Leave out the release when the logbook has none.
- **State words**: a task, a milestone or a release is not started, waiting, needs you, in progress, done or stopped. Use these six words, not the tool's states.
- **A heading for each part**: start each part with a `### <label>` heading line, such as `### Where this is`, with a blank line before and after it. Never write a part's label as a bold line: it looks like one more progress line. Bold inside the text is still allowed for a word that needs it.
- **One blank line** between the parts. A table becomes numbered rows, with one line for each column.
- **Progress lines stay plain**: between tool calls, write one plain sentence, such as "Starting the lead for the new words now." No heading, no bold, no list.
- **A rule before the message**: when the turn had progress lines, start the final message with a `---` line and a blank line, so that the message is separate from them. The checks read the kind from the first line after the rule.
- **No raw ids** (a task, run, gate, milestone, chief, finding or pull request number) in the text or in a picture. Put them in one last line: `Ref: T12 · PR 40`.
- **Large choices only**: "Judged by" and "The bad side of my pick" go in a question only when the choice is large.

## Pictures

Draw each picture as fixed-width text first. The page draws its image from the same text, so the two cannot differ.

- At most 46 columns, or 66 on a long page. Only single-width characters. Known limit: a terminal with an East Asian wide setting draws box marks two columns wide.
- Boxes: rounded (╭ ╮ ╰ ╯) for a part, double (╔ ╗ ╚ ╝) for the part in focus, dashed (┄ ┆) for a group. Close every box: the checks name each box that does not close.
- Arrows: a line (│ ─) and one head (▼ ▲ ▶ ◀). Each arrow goes one way and has a label.
- No tree marks (├ └ ┬ ┴ ┼). Draw boxes inside boxes.
- Each picture has a title and a key. The key also names what the picture leaves out.
- An architecture picture shows one zoom, at most 6 boxes, and a [type] for each part. A state chart groups the states in dashed boxes, one for each state word. Both are usually pictures inside another kind.

## Pages

A message with a picture, and a message too long for the chat, get a page: one file in the task's pages folder that holds the whole message, with each picture as an image. The message names it in a Page block: `Page · <title>`, then the board's link to the page (`http://127.0.0.1:43123/pages/<logbook>/<task>/<file>`), then its file path. The owner clicks the link: it opens the page from the board, in the Claude desktop app, in the Codex app and from a terminal. When the board does not run, the owner opens the path. Do not send a page with Claude's file tool: it sends a copy through Anthropic's servers. A long message holds only its main point and the Page block; the page holds the rest.

A page loads nothing and runs only its own switch. Known limit: a page that the owner opens can still send its own content out through a link or a change of address.

## The message command

For a message with a picture, a long message, or any message where the shape matters, write it as JSON and let the state tool render it:

1. Make a temp folder, and write the JSON in it, for example `mkdir -p /tmp/sage-message`, then `cat > /tmp/sage-message/T12.json <<'EOF'` … `EOF`.
2. Run `sage message <task> --file /tmp/sage-message/T12.json`. In Codex, call the `message` tool with the task and the message.
3. Send the text that it prints, word for word, after a `---` line when the turn had progress lines. It ends with the Page block when the message has a page.

The command refuses a message that is not in its kind's shape, and names each problem: fix them and run it again. Write a short message with no picture by hand, in the same shape: the checks read the text in the same way.

The JSON: `{ "kind", "title", "blocks": [ … ], "ref" }`, and `"status"` for an incident. A long message adds `"long": { "title", "main" }`: the title and the main point for the chat. Each block has its type in `t`:

| Block | Fields | Text form |
| --- | --- | --- |
| `field` | `label`, `text` | `### Label`, a blank line, then the text in its own letter case: start a sentence with a capital |
| `p` | `text` | a paragraph, anywhere |
| `section` | `label`, `body` (blocks) | `### Label`, a blank line, then its blocks; a section inside a section gets `####`, and a field inside it is a line `- Label: text`, because only a part gets a heading |
| `list` | `items`, `ordered` | `- item` or `1. item` |
| `table` | `head`, `rows`, `pick` (the row of your pick, from 0), `caption` | numbered rows; your pick is row 0 and says "(my pick)"; on the page of a question or a confirm, a list too |
| `picture` | `title`, `lines` or `frame`, `key` | the title, the lines in a fence, the key |
| `toggle` | `after`, `today`: each a list of `{ title, lines }` | the pictures after the change; the page adds a Today switch |
| `changes` | `rows` of `{ where, today, after, why }` | numbered rows; for changes without a screen |
| `steps` | `items` of `{ text, cmd, see }` | numbered steps, each command in a fence |
| `code` | `lines` | the lines in a fence |
| `page` | `title`, `task`, `file`: a file in that task's pages folder that the board serves (a web page, PDF, picture, Markdown or text file, at most 3 parts deep and 16 MiB) | the Page block: the title, the link, the path |

A catch-up's picture is a `frame`: boxes inside boxes that the command lays out and gives their state words. Each box is `{ "box": "release" | "milestone" | "task" | "group", "name", "items": [ boxes or lines of text ] }`. A task gives its recorded `state` (for example `"reviewing"`), and may give `waits` (what it waits for) and `needs` (the owner's question). A milestone may give its state (`"proposed"`, or `"done"`, which the boxes inside it must agree with); its word and a release's word come from the boxes inside them, and the tasks inside a group count too. A group gives its `word`, and so does a box whose items are only lines of text. Any box may give a `note` for its first line. Exactly one box is `"here": true`: the double box, the task that runs now.

In the text of a field, a list or a cell, `**bold**` and a code span show on the page. The chat text shows bold words without their marks, and keeps a code span's backticks: a word in code, such as a chip name, is not an id.

## Ask with the question tool

Ask a `question` or a `confirm` with the host's question tool when the session has one and the card rule allows it: the owner picks an option on a card, the choice card. Else send the text form of the kind.

Use the tool only for a choice that is the owner's: product direction, or an act that cannot be undone. Never use it for reversible work: decide that, and report it.

**The card rule.** Use the card only when both are true. Else send the text form.

- **No lead or other background run of yours runs.** Claude's card holds your turn until the owner answers. While it waits, the reports of background runs wait too, and the gate's default never applies. The text form keeps your turn free, so reports keep arriving and the default can apply. Approval prompts that must not block work, such as GitHub's and Slack's, are a message with a default and a timeout for the same reason.
- **The batch fits the card:** at most 4 questions, each with at most 4 options. A gate with more options, or a batch of more questions, goes in the text form.

1. Park each question with `sage gate add` first.
2. Send a short chat message: the kind's parts, except the title and the answers, which go on the card, and the Ref line last. The card can hide the chat, so the message has no head line: the card is the question.
3. Call the tool. Put the whole batch in one call, the most important question first.
4. Record the answer with `gate answer`: the gate's own option number, or the owner's own words (the tool's Other) as `--other-hex`. Find the number by the option's label in the gate, never by its place on the card or in the text form: both put your pick first, and the gate keeps its own order.

The owner's rules for the chat message and the text form (12 Nov 2026), because the parts ran together and a table made long answers hard to read. Then the owner asked for clearer labels, because a bold label looked like one more progress line, so each label is now a heading:

1. **Separate segments.** Give each part a `###` heading line, such as `### Where this is` or `### If you do not answer`, with a blank line before and after it, and its text under it. Keep each part to one or two short sentences.
2. **No tables for answers or explanations.** On the card, the long text goes in the option's description. In the text form, the answers are a short numbered list, with what happens next and the cost under each answer. Use a table only for short, uniform data, such as numbers or dates.
3. **The same rules with no tool.** The text form has the same headings and the same list of answers, your pick first. `sage message` prints it so, and the message check notes a bold label, a label in the line, a table of answers or a pick that is not answer 1.

| Part of the question | On the card |
| --- | --- |
| The title | The question text. It stands alone: it names the items that it asks about. |
| A short name of the topic | The header chip, at most 12 characters. |
| Each answer | One option. Its label is the answer, in 1 to 5 words. |
| Your pick | The first option, with "(Recommended)" at the end of its label. In the text form, it is answer 1, with "(my pick)". |
| What happens next, and the cost | The option's description. |
| If you do not answer | Not on the card: it stays in the chat message. |

Each host has its tool:

- **Claude Code:** `AskUserQuestion`, with 1 to 4 questions a call and 2 to 4 options a question. The tool adds Other. It waits for the answer, so the card rule applies.
- **Codex:** `request_user_input_async`, when your tools have it. An option is one line with no description, so write it as "label: what happens next, cost". The tool returns at once, and the answer comes as the owner's next message. Codex's `request_user_input` works only in Plan mode: do not use it.
- **No tool:** send the kind's text form, with the rules above.

### Before and after

SAMPLE CONTENT: a shorter copy of an approved question of 11 Nov 2026.

**Before:** the parts run together, and a table holds the long answers.

```text
QUESTION

Should pages reach you only by a link to your Mac? Where this is: Release 1.0 › single task: one way to show visuals › step: investigate. What you approve: how pages reach you in the Claude app. The one real choice in it: a page inside the chat, or a page that never leaves your Mac. If you do not answer: the build uses my pick. Needed by: before the page link build starts. After you answer: I say in one line what I recorded.

| Answer | What happens next | Cost |
| --- | --- | --- |
| Link only (my pick) | Every page comes as a link and a path, in Claude and in Codex. No copy leaves your Mac. | None: it is part of the planned page link work. |
| Keep the file tool too | Some pages open inside the Claude chat. A copy of each goes through Anthropic's servers. | Small: one more rule for the chief. |
```

**After, with the tool:** first the chat message, in segments. The turn had progress lines, so the message starts with a rule.

```text
---

### Where this is

Release 1.0 › single task: one way to show visuals › step: investigate

### What you approve

How pages reach you in the Claude app.

### The one real choice in it

A page inside the chat, or a page that never leaves your Mac.

### If you do not answer

The build uses my pick.

### Needed by

Before the page link build starts.

### After you answer

I say in one line what I recorded.
```

Then the card. In Claude Code:

```json
{ "questions": [{
  "question": "Should pages reach you only by a link to your Mac?",
  "header": "Pages",
  "multiSelect": false,
  "options": [
    { "label": "Link only (Recommended)",
      "description": "Every page comes as a link and a path, in Claude and in Codex. No copy leaves your Mac. Cost: none, it is part of the planned page link work." },
    { "label": "Keep the file tool too",
      "description": "Some pages open inside the Claude chat. A copy of each goes through Anthropic's servers. Cost: small, one more rule for the chief." }
  ] }] }
```

In Codex, the same question with one line for each option:

```text
Link only (Recommended): every page comes as a link and a path; no copy leaves your Mac. Cost: none.
Keep the file tool too: some pages open inside the Claude chat; a copy goes through Anthropic's servers. Cost: small.
```

**After, with no tool:** the text form, as `sage message` prints it.

```text
QUESTION

Should pages reach you only by a link to your
Mac?

### Where this is

Release 1.0 › single task: one way to show
visuals › step: investigate

### What you approve

How pages reach you in the Claude app.

### The one real choice in it

A page inside the chat, or a page that never
leaves your Mac.

1. Link only (my pick)
   - What happens next: Every page comes as a
     link and a path, in Claude and in Codex.
     No copy leaves your Mac.
   - Cost: None: it is part of the planned
     page link work.

2. Keep the file tool too
   - What happens next: Some pages open inside
     the Claude chat. A copy of each goes
     through Anthropic's servers.
   - Cost: Small: one more rule for the chief.

### If you do not answer

The build uses my pick.

### Needed by

Before the page link build starts.

### After you answer

I say in one line what I recorded.
```

## The kinds

A playbook (a file in `core/references/playbooks/` in the plugin's folder) names the kind of each moment where the owner answers, for example `question` for the case table of an undecided case. Use the kind that the playbook names.

Each kind: its `kind` in the JSON, its head (the first line), when to send it, and its parts in order after the title. A part in [brackets] is optional; a paragraph may stand anywhere. The last part of the text is the Ref line, when the message has ids to give.

| Kind | Head | When | Parts, in order |
| --- | --- | --- | --- |
| `progress` | `PROGRESS` | While a task runs: one short note when it moves to a new step, with nothing for the owner to do. | Where this is · [Since my last note] · What changed · Next · [Cost so far] · What I need from you |
| `question` | `QUESTION` | When work waits for the owner's choice. The title is the question. Ask it on the choice card when the card rule above allows it, else in this text form. Each part starts with a ### heading on its own line. The answers are a numbered list, never a table. | Where this is · What you approve · The one real choice in it · the answers, a numbered list (Answer, What happens next, Cost; your pick marked) · If you do not answer · Needed by · [Judged by] · [The bad side of my pick] · After you answer · [a Page block] |
| `report` | `REPORT` | When work ends: a pull request merged, or a study concluded. The title says what happened and what it needs. The table of the pieces of work goes under its own ### What changed heading. | Where this is · [Why this change] · [a picture, any number] · a table (Piece of work, What changes for you, How I know it works, Cost, You must act) · What I did not check · Weak points · What you need to do · [a Page block] |
| `request understood` | `REQUEST UNDERSTOOD` | Right after the owner asks for new work, before agents spend hours on it. It starts on its defaults unless the owner corrects it. | Your words · What I understood · Read back (costly if wrong) · In · Out · Appetite · [Unsure, with my default] · If you say nothing |
| `explainer` | `EXPLAINER` | When the owner asks what a part of sage is, or a message uses a word that is new to the owner. The title is “About …”. | What it is · Why it exists · A real example · [a picture, any number] · [Like, and where the likeness stops] · [What it is not] · [New words] · [a Page block] |
| `incident` | `INCIDENT` | When an agent did what it must not do, or sage told the owner something that proved wrong. The status is Investigating, Identified, Monitoring or Resolved. | Where this is · What happened · [What I told you, and what is true] · What it changed for you · What I did · Why it could happen · Has it happened before · What stops it next time · What you need to do · Next update |
| `design` | `DESIGN FOR APPROVAL` | When a design is ready for approval, before any build. Before and after: one picture of the result with each change tagged and a Today switch, or a change table for changes without a screen. | Where this is · [Try it] · [a Page block] · How you will use it · [a picture, any number] · [a toggle] · [a change table] · [Key] · [Why each change matters] · Goals · Non-goals · The choices, and the options I dropped · [Why we might not do this] · Safety and cost · Open questions · What you approve |
| `architecture` | `ARCHITECTURE` | When the owner asks how something is built. Usually a picture inside a design or a question: one zoom in each picture, at most 6 boxes, a [type] for each part, labelled one-way arrows, a key that names what is left out. | a picture, one or more · What changes for you · What I need from you · [a Page block] |
| `state chart` | `STATE CHART` | When the owner needs to know how one thing moves from state to state. Usually a picture inside another kind: groups as dashed boxes, about 8 to 13 states, a key that names the rest. | a picture · [a table] · What I need from you · [a Page block] |
| `catch-up` | `CATCH-UP` | When the owner comes back after time away, or asks where the work is: boxes inside boxes (release › milestone › task), each with its state word, the current task in a double box. | a picture · Each box · Since · What changed · If this happens · What I need from you |
| `estimate` | `ESTIMATE` | Before work starts, when the owner asks how long or how much, or when a cost changes a choice. The title is the number, with its unit and range. | What it covers · a table · [a picture, any number] · Basis · How sure · [What would change it] · [So far] · [Your time] · What I need from you |
| `steps for you` | `STEPS FOR YOU` | When only the owner can do something: an install, an update, a setting, a sign-in. A warning goes before the steps it is about. | When · Why · numbered steps · How you know it worked · Your time · If a step fails |
| `confirm` | `CONFIRM` | Just before an act that cannot be undone: a delete, a publish, a message to other people. The title names the act and says that it cannot be undone. Ask it on the choice card too when the card rule above allows it, else in its text form, with a ### heading for each part. | What I will do · a table · What stays · If you say yes · If you say no, or nothing |
| `lesson kept` | `LESSON KEPT` | When a mistake teaches sage something: the lesson once, and where it now lives. | What happened · [a picture, any number] · The lesson · Has it happened before · a table (Where the lesson lives now, What it holds, State) · What changes for you · What I need from you |