content-diagram git:20260917.c2e02c8A

Immutable. This exact content never changes and is served at /api/v1/blob/0d03309d008675ba.

---
name: content-diagram
description: Compose an editable Tin diagram with clear hierarchy, lanes, and return paths.
---

# Content diagram

Produce one editable Mermaid `.mmd` source file. Tin supplies packaged Geist fonts, semantic colors,
measured wrapping, spacing, and open arrowheads. You own the meaning and the composition.

Read relevant project documents when the brief names them, or when they are needed to understand
the request. Use the pinned checkout, not live web research. Record only the paths you actually
used in `source_paths` in your final structured response. If evidence is incomplete, depict what
is known and label uncertainty; never fill gaps with guessed architecture.

## Render, inspect, repair

After writing the candidate, Tin renders it using the actual product renderer and packaged fonts
in both themes, then gives you the resulting images in a follow-up turn. You can also run
`node /opt/tin-lite/diagram/scripts/check_diagram.mjs check <candidate> --out /tmp/diagram-preview`
yourself. This is offline; do not install tools or fetch fonts, URLs, or reference images.

On the first response, set `accepted=false` and `inspected_sha256=""`. A grammar pass is not a
visual review. In the inspection turn, look at both overviews and use the image viewer on any
natural-scale detail tiles provided. Check legibility, hierarchy, path order, and semantic fidelity.
Tin also supplies advisory geometry measurements: canvas dimensions, fit scale in a fixed
1200 by 800 viewport, bends, crossings, short jogs, route length/detours, consecutive-axis drift,
and imbalance among equivalent branches. These are clues for inspection, not pass targets.
A lower bend count can still be worse if the diagram becomes much taller or the reader loses
the main story. Compare overview and natural-scale details; preserve all required facts.
If repairs are needed, edit the source and again return accepted=false and an empty inspection
hash. There are at most two repaired candidates. Do not remove required facts to make a check
pass. Accept only the exact source hash whose rendered images you inspected and found clear.

Previews and diagnostics belong only in the temporary directory. The only project artifact is
the declared `.mmd`. A separate final Tin check validates the exact saved bytes again, including
when recovering a checkpoint. This does not publish content; the founder still reviews the result.

## Plan before drawing

1. Identify what the reader should follow: a sequence, ownership boundary, assembly, state
   transition, parallel lanes, or a consolidation loop. Preserve actual relationships; never
   invent an arrow merely to fill a gap or make an informational item connected.
   Establish the main sequence, its real entry, any actual terminal outcomes, equivalent
   alternatives, and feedback from the brief or evidence. A cycle need not have an entry or
   terminal. Do not guess a happy path from labels, indegree, or the longest graph path.
2. Sketch the major regions in reading order. A small sequence can stay flat. A larger diagram
   should have a few deliberate rows or columns, with related components inside a frame and
   participants or phases in named lanes. Use invisible layout groups only to arrange content.
3. Follow the requested overall direction. Inside a composition, choose each group's direction
   independently. Fold a long progression from an LR row into an RL row below it; use TD columns
   for stacked components and BT for a deliberate upward progression. Avoid an enormous single
   strip, arbitrary wrapping, or a row per node.
4. Put strongly connected items near one another. Separate setup, action, durable evidence, and
   feedback when that clarifies the story. Give feedback a return path; do not reverse the main
   progression just because a later node sends a signal to an earlier one.
   Keep consecutive steps on a common axis where possible. Center equivalent branches around
   their split/merge, balancing visible whitespace after card sizes differ. Use existing ordered
   layout groups to express this; unequal conditional branches need not be symmetric. Let an
   established terminal finish the local reading direction; multiple outcomes may share a band.
   Keep return paths beside the progression. Avoid an extra row for every node and do not merge
   distinct paths into a visual junction that implies a new dependency.
5. Write a short name and one useful fact per node. Names identify; facts explain. Keep long
   narrative, disclaimers, and repeated edge descriptions out of the boxes. An edge label should
   clarify a relationship that its endpoints do not already explain.
6. Read every path forward and backward. Check every branch, cancellation, wait, and return.
   Group membership must reflect a real boundary or a clearly named editorial lane. Decorative
   frames should not imply a service or ownership boundary that does not exist.
   Inspect composition from both ends: can better grouping remove long detours, and can a local
   alignment remove a zigzag without disturbing the whole? Prefer fewer purposeful regions and
   short nearby connections. If a dense source still needs many crossings or a tiny overview,
   revise its hierarchy within the repair budget instead of accepting it just because it renders.

## Node vocabulary

- `step`: Tin or the workflow performs work.
- `surface`: a provider, interface, or compute surface.
- `store`: durable state or evidence; the only cylinder shape.
- `wait`: elapsed time or an event wait without running compute.
- `gate`: a human decision; do not use it just to color an ordinary failure orange.
- `receipt`: evidence that an effect or result exists.
- `ghost`: a cancelled, excluded, or unentered action.

Solid edges represent ordinary flow. Signal edges represent an event that wakes, interrupts,
or changes another path. Connect leaf nodes, including across group boundaries. A frame is a
container, not an executable step. Distinct informational items may belong to a composition
without a fictitious causal edge.

## Exact source grammar

First line is `graph LR` or `graph TD`, matching the overall `direction` input. IDs begin with a
lowercase letter and contain only lowercase letters, digits, and underscores. All IDs are unique.

- Node: `work["Do the work<br/>One bounded activity"]:::step`
- Store: `wiki[("Project wiki<br/>Durable memory")]:::store`
- Call: `work --> wiki` or `work -->|commit result| wiki`
- Signal: `reply -.->|cancel future touches| pending`
- Only the seven node classes above. Every node has at most one `<br/>`; Tin wraps the two
  logical text fields itself. Do not manually break text to imitate screenshot line lengths.
- Text cannot contain ampersands, straight quotes, backticks, braces, angle brackets, pipes,
  semicolons, or newlines (except the single supported `<br/>` separator).
- No arbitrary HTML, styles, class definitions, scripts, links, icons, or Mermaid directives.
- All edge declarations follow all node and group declarations, outside groups. No duplicate
  ordered pair of endpoints. Self-loops are supported only in a composition.

A flat diagram has 2–8 connected nodes, 1–12 edges, names up to 32 characters, facts up to 48,
and edge labels up to 40. Use this compact form whenever it expresses the whole relationship.

A composition starts with `%% tin:composition` immediately after its graph header. It has
2–32 nodes, 1–48 edges, and 1–16 groups nested at most four levels. Names and group labels are
at most 80 characters; facts 240; edge labels 96. These are ceilings, not writing targets.
Every item appears exactly once in the hierarchy. A group is never empty.

```text
graph TD
  %% tin:composition
  subgraph prepare["Prepare"]
    direction LR
    %% tin:group lane
    ask["Founder ask"]:::step
    draft["Draft<br/>Use project evidence"]:::step
  end
  subgraph deliver["Review and retain"]
    direction RL
    %% tin:group lane
    review["Needs you<br/>Review the draft"]:::gate
    wiki[("Project wiki<br/>Approved result")]:::store
  end
  ask --> draft
  draft --> review
  review --> wiki
  review -.->|request changes| draft
```

`subgraph id["Label"]` opens a group and `end` closes it. Set `direction LR`, `RL`, `TD`, or `BT`
and `%% tin:group frame`, `lane`, or `layout` before its children. `frame` draws a named
container. `lane` draws a section heading. `layout` arranges children without a frame or heading;
it may use `subgraph id` without a label. Those two `tin:` comment forms are the only comments
allowed. Use explicit group kind and direction so the layout intention stays reviewable.

Before finishing, check the grammar, hierarchy, node meanings, all endpoints, and the intended
reading order. Preserve factual uncertainty and distinguish a historical reference from current
implementation. The renderer provides a visual preview; source and the ASCII hierarchy/connection
view remain available when editing. Write only the declared `.mmd` artifact.