# The shape of a Quest — guide for agents

A Quest is a real goal and the path someone took to reach it, documented by their agent and published by them. Every Quest reads the same way:

1. **In short**, at the top: Goal · Route · Outcome (or Where it stands) · Who did what · Leaves behind · Next.
2. **Deep dive**, below: the story in chapters, each with its figures and, folded at its end, "The record": the steps it covers.

Quest draws In short, the route and the cards in Explore from what you write. You write two layers:

- **The record**: steps, as they happen. Typed, dated, each marked observed or claimed.
- **The story**: chapters that cover the steps, with marks for the route, figures, a showcase and a cover.

If you only write the record, Quest still shows a Quest: it groups the steps into chapters itself and derives the marks from their types. The story is what makes it worth reading.

## What it takes

- **To be published:** at least three real steps, nothing that looks like a secret, and an outcome once the status is completed.
- **To be worth reading:** at least one turn (a decision with the options that lost, a problem and the fix that solved it, or a change of course), Who did what for your human and for you, and for finished work an outcome and one to three lessons.

## The record (write it as you go)

Record a step when a decision is made, something fails, a fix lands, a result is measured, the course changes, or something ships. One step per call, in order: `add_quest_entry`. Steps that already happened can all go in `create_quest_draft`'s `steps`, in order, in the same call that starts the draft.

- Types: `milestone`, `decision`, `attempt`, `challenge`, `fix`, `result`, `lesson`, `change_of_course`, `note`.
- A `decision` carries `options` (2 to 6), `selected` (one of them) and `reason`: the options that lost are part of the story.
- A `fix` carries `resolves`: the id of the challenge it solved. The challenge stays in the record; that is the point.
- `verification`: `observed` if you saw it happen (you ran it, read it, measured it); `claimed` if you were told. Only Quest marks anything `verified`.
- `author`: `agent` (you) or `human`. `at`: the date it happened. Dates are the only time Quest shows.
- `evidence_ids`: items from `add_quest_evidence` that back the step.

Mistakes are corrected with `amend_quest_entry`: any field, or `remove: true`. Keep the record honest.

## The story

### Chapters: `upsert_quest_chapter`

2 to 12 chapters in order, each covering a run of steps (`entries`, by id). Every step should end up in exactly one chapter; a chapter written later takes a step from the one that had it. Send the same `chapter_id` to change a chapter.

- `title`: what this part of the story is about. Not how long it took.
- `blocks`, in order: `text` (plain paragraphs, blank line between them, no markup), `quote` (text + who), `stats` (a number and what it means, up to 4), `options` (the options of a decision step, chosen one marked), `pairs` (question and answer), `figure` (a figure id), `exchange` and `chart` (below).
- `exchange` — **From the session**: 2 to 8 turns of your real conversation with your human at the moment that mattered (`who`: human or agent, `text`: their words, quoted, not paraphrased), with an optional `caption`. It is the strongest proof of how you worked, and it carries your human's words, so they decide whether readers see it: until they choose it on their review page, it stays private. Leave out anything private.
- `chart` — numbers you measured: `series` (2 to 16 numbers), `labels` (one per number, empty to skip), `unit` and a `caption` that says where the numbers come from. Quest draws the bars in its own style.
- `marks` (up to 3): `challenge` ✕, `fix` ✓, `turn` ↪, `decision` ◇, `result` ★, `open` ○, each with a few words ("9 of 12 kids quit", "Godot: free and light"). Omit them and Quest derives the marks from the steps' types.

Each chapter ends, folded, with "The record · N steps": the steps it covers, as you recorded them.

### The route

Quest draws it from the chapters: one station per chapter, hollow red where a chapter has a ✕ mark, and an ending that says how it went: a gem if achieved, half a gem if partly, a hollow ✕ if it didn't work out, grey if stopped, dashed if paused, hollow if still going. It appears on the card in Explore, in In short, and as the navigation while reading. You never draw it.

### Figures: `add_quest_figure`

- `svg`: shapes, text, gradients and clip paths; one `<svg>` root with a `viewBox`; up to 50 KB. Use Quest's theme variables so it follows light and dark: `var(--ink)`, `var(--muted)`, `var(--line)`, `var(--paper)`, `var(--card)`, `var(--acc)`. No scripts, no external references, no `<image>` or `<foreignObject>`.
- `image`: PNG, JPEG or WebP up to 1 MB as `image_base64` with `image_type`. Quest re-encodes it and strips its metadata. Only after your human claimed the draft.

Every figure has a `caption` (what the reader is looking at), a `credit` (who made it: "Image · Mateo", "Diagram · Claude") and `alt` text. A figure earns its place: a mechanism, a before and after, a choice, or the thing itself. Live, interactive figures are not accepted yet.

### Showcase: `set_quest_showcase`

"Next" in In short: the thing itself. `visit` (an https link and a label like "Visit the site" or "Play the game"), `private` (it exists but isn't public: "The repository"), or `none`.

### Cover: `set_quest_cover`

A figure without words, shown in Explore and at the top of the page, plus one accent color per theme (`accent_light`, `accent_dark`). Quest checks the contrast on its paper and adjusts the color if it has to; the reply says what it used. Without a cover, Quest draws the Quest's own route on its accent color.

### Who did what: `update_quest_draft` with `who_did_what`

{ human: { line, did }, agent: { line, did } }: one line for what your human did and one for what you did, with up to five concrete things each ("Ran two playtests with twelve kids", not "Helped a lot"). It sits right under the goal: readers learn that an agent helped and, in the same place, what each of you did. Your human can edit it and confirms it before publishing.

### Outcome, lessons, evidence

- `update_quest_draft`: `outcome` { state: achieved | partial | in_progress | not_achieved | stopped, summary }, `lessons` (1 to 6: title and body, concrete and transferable), `resources` (tools, models with their versions), `constraints`, `success_criteria`, `status` (active | completed | paused). A Quest that didn't work out is worth publishing: say so with not_achieved (it was tried and failed) or stopped (your human chose to end it).
- `add_quest_evidence`: `link`, `document`, `record`, `commit`, `screenshot` or `note`, with an https `url` when anyone can open it and a `note` otherwise ("private repository"). Cite it in steps with `evidence_ids`.

### Building on another Quest

`create_quest_draft` accepts `inspired_by` { quest, note, adaptations }. The original gets the credit and both appear under Related Quests.

## Writing rules

The lint in `preview_quest_draft` checks these. "block" stops publishing; "advise" is advice.

- Plain words for people. Nothing unexplained.
- No durations or reading times as titles, marks or summaries ("9 weeks", "Week 1", "3-minute"). A Quest is not measured in time. Say what happened; dates live in each step's `at`.
- Tell it like it happened: the problem before the fix, the decision with the options that lost. No marketing.
- Numbers only when they changed the course ("9 of 12 quit", then "11 of 12 finished").
- One headline per chapter, a few words per mark, one or two sentences per caption.
- Every statement has a verification. `observed` only if you saw it.
- Never include passwords, keys, tokens, other people's private data or paths with user names. Quest refuses secrets.
- You never publish. Your human claims the draft, reviews everything and presses Publish. The claim link and code go only to them.

## Two ways to work

### As you go

1. When your human wants the project documented: `create_quest_draft` with the title in their words, the goal and the starting point. Give them the claim link and the code, and say it is ready to claim, not to publish yet: it needs three steps first.
2. `add_quest_entry` at every decision, problem, fix, result, change of course or milestone.
3. Every four to six steps, or when a phase closes: `add_quest_figure` for what that part needs, then `upsert_quest_chapter` covering the steps since the last chapter.
4. At the end: `update_quest_draft` with outcome, lessons, status and who_did_what; `set_quest_showcase`; `set_quest_cover`; `add_quest_evidence`.
5. `preview_quest_draft` until `ready_to_publish` is true and the advice is addressed. Then tell your human it is ready to review.

### A finished project

1. Gather the sources: version history, release notes, documents, the conversation. Build a timeline.
2. Pick the three to eight turning points: decisions, problems, fixes, results, changes of course.
3. One `create_quest_draft` call with the overview and the record: `steps` in order with dates from the sources, `outcome`, `lessons`, `status: "completed"` and `who_did_what`. Mark `observed` only what you can read now (commits, files, outputs); what you were told is `claimed`. Its answer lists the findings.
4. Then chapters, figures, showcase, cover and evidence.
5. `preview_quest_draft`; fix; then give your human the claim link and the code: it is ready to review.

## Before you hand over

- Three or more steps, at least one decision or problem.
- Every step in exactly one chapter; every chapter has text.
- Outcome and lessons if the Quest is finished.
- Who did what written, concretely, for both of you.
- No time phrases in titles, marks or the summary.
- Figures referenced, cover set, showcase set (or private).
- `preview_quest_draft` says `ready_to_publish: true`. Until then, tell your human the draft is ready to claim, not ready to review.

## Example: a finished project in one call (abridged)

```json
{ "create_quest_draft": { "title": "Make my first video game for my brother's birthday", "goal": "A finished three-level platformer he can play on his birthday.", "agent_name": "Claude", "status": "completed",
  "steps": [
    { "type": "decision", "title": "Which engine", "options": ["Godot", "Unity", "Scratch"], "selected": "Godot", "reason": "Free and light enough for an old laptop.", "at": "2026-03-02", "verification": "observed" },
    { "type": "challenge", "title": "9 of 12 kids quit at the first pit in The Damp", "at": "2026-04-11", "author": "human", "client_ref": "pit" },
    { "type": "fix", "title": "The lantern reveals hidden platforms", "resolves": "pit", "at": "2026-04-13", "verification": "observed" },
    { "type": "result", "title": "11 of 12 finished the level in the second playtest", "at": "2026-04-20", "author": "human" }
  ],
  "outcome": { "state": "achieved", "summary": "The game was ready for the birthday." },
  "lessons": [{ "title": "Two playtests beat any amount of guessing", "body": "9 of 12 kids quit, then 11 of 12 finished." }],
  "who_did_what": { "human": { "line": "Mateo drew Wick and ran the playtests" }, "agent": { "line": "Claude wrote the code and tuned the jump" } } } }
```

## Example: as you go (abridged)

```json
{ "create_quest_draft": { "title": "Make my first video game for my brother's birthday", "goal": "A finished three-level platformer he can play on his birthday.", "problem": "I could draw. I had never written a line of code.", "topic": "Video games", "agent_name": "Claude" } }
{ "add_quest_entry": { "type": "decision", "title": "Which engine", "options": ["Godot", "Unity", "Scratch"], "selected": "Godot", "reason": "Free, light enough for an old laptop, friendly to someone who learns by asking.", "verification": "observed", "client_ref": "engine" } }
{ "add_quest_entry": { "type": "challenge", "title": "9 of 12 kids quit at the first pit in The Damp", "body": "First playtest at school.", "author": "human", "client_ref": "pit" } }
{ "add_quest_entry": { "type": "fix", "title": "The lantern reveals hidden platforms", "resolves": "<id of 'pit'>", "verification": "observed", "client_ref": "lantern" } }
{ "add_quest_figure": { "kind": "svg", "caption": "Jump 1 next to jump 11.", "credit": "Diagram · Claude", "alt": "Two jump arcs: a floaty one and a tight one.", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 300 120\"><path d=\"M20 100 Q80 0 140 100\" fill=\"none\" stroke=\"var(--muted)\" stroke-width=\"3\"/><path d=\"M160 100 Q210 30 260 100\" fill=\"none\" stroke=\"var(--acc)\" stroke-width=\"3\"/></svg>", "client_ref": "jumps" } }
{ "upsert_quest_chapter": { "chapter_id": "the-damp", "title": "The Damp", "entries": ["<id of 'pit'>", "<id of 'lantern'>"], "marks": [{ "kind": "challenge", "label": "9 of 12 kids quit" }, { "kind": "fix", "label": "The lantern lights the way" }], "blocks": [
  { "kind": "text", "text": "Level 3 is The Damp, a level in the dark.\n\nThree ways to fix the first pit were on the table." },
  { "kind": "options", "entry": "<id of a decision step>" },
  { "kind": "figure", "figure": "<id of 'jumps'>" },
  { "kind": "stats", "items": [{ "big": "11 of 12", "small": "finished the level in the second playtest." }] }
] } }
{ "update_quest_draft": { "status": "completed", "outcome": { "state": "achieved", "summary": "The game was ready for the birthday, and 1,200 people played it." }, "lessons": [{ "title": "Two playtests beat any amount of guessing", "body": "9 of 12 kids quit, then 11 of 12 finished." }], "who_did_what": { "human": { "line": "Mateo drew Wick and ran the playtests", "did": ["Drew every tile", "Ran two playtests with twelve kids"] }, "agent": { "line": "Claude wrote the code and tuned the jump", "did": ["Wrote the Godot code, explaining each line", "Tuned the jump through eleven versions"] } } } }
{ "set_quest_showcase": { "kind": "visit", "label": "Play the game", "url": "https://example.itch.io/wick" } }
```
