# Authoring defaults Read once before writing a fresh candidate. An existing frozen candidate going straight to `finalize` needs this only if repair changes its authorship. ## Composition and meaning For Architecture, default to a system overview led by the main user journey unless the user asks for a narrower mechanism, module map, or deployment topology. Group cooperating roles in accurately named subsystems when that still explains the requested interaction. Separate roles when grouping would hide control ownership, a trust or persistence boundary, lifecycle behavior, or another distinction the reader asked about. Keep secondary and opt-in capabilities in concise sourced notes unless their path matters to the requested question. Name a deliberately narrower scope in the title. Preserve every requested responsibility, relationship direction, protocol, and behavior-changing condition. Show approval, authorization, and state-transition gates on the affected node or relationship; a card alone cannot qualify an otherwise unconditional arrow. Keep source evidence with each asserted claim. Boundaries express real isolation, ownership, runtime, or persistence facts. Cards answer additional reader questions; they do not replace required topology. There is no node, edge, source, card, or boundary quota. If an authored overview needs regrouping after failure, use [Composition repair](authoring-contract.md#composition-repair); user-supplied or agreed topology remains fixed. Relationship labels carry meaning. Give them clear space and preserve action, protocol, direction, async behavior, or cross-boundary meaning. Where the mode schema permits an absent label, omit it only when both endpoints already fully imply it; a collision calls for spacing or routing repair. See [Label repair](authoring-contract.md#label-repair) when measured evidence reports a collision. ## Layout and routing Place Architecture nodes by their actual connections before assigning coordinates; the router cannot rearrange boxes, so placement decides whether lines stay straight. Classify each relationship first, then place: - **Main path**: the reader's main journey, neighbors adjacent in reading order. Let a medium path step through meaningful rows instead of making a shallow horizontal strip. - **Branch or store**: directly above or below the node that owns, reads, or writes it, centered on that node so the edge is one straight segment. Keep all stores and branches of one row on the same side of it. - **Return** (back to an earlier main-path node): put its source on the side of the main path with no branches or stores, so it runs through an empty corridor instead of crossing them. - **Second entrance** into a node that already has an incoming edge: place the new source so it reaches that node from another side, usually directly below or above it. - **Fan-out**: a side with k relationships needs at least `32 + 14 × (k − 1)`px (four need 74px). Spread a hub's counterparts over two or three sides, or enlarge the hub. Center a parent on its children and align a child with its only parent. Before writing positions, trace each non-main relationship: its straight or one-bend corridor must not pass another node or cross another relationship. If it does, move the endpoint that is off the main path. Start the main actor and its first connected step together near the canvas origin (about `[40, 40]`, not `[200, 200]`); use content rows for vertical rhythm. Empty top/left margin from a high origin wastes canvas and drops fill without improving readability. Omit `meta.viewBox` for a fresh Architecture so the Reader measures intrinsic height. Keep supplied fixed geometry authoritative. Start with automatic routes and endpoint sides. Pin a side only for a necessary branch, return, or supplied geometry. For a fresh Architecture, leave adjacent request/reply directions automatic when no required side constraint prevents parallel straight lines; preserve supplied side pins. Reserve `via`, `channelX`, `channelY`, and label coordinates for measured defects. Before writing positions, budget every labeled edge between side-by-side boxes, on the main path or not, at `6.5px × ASCII units + 21px` of clear gap, counting CJK as two units; use its own label length, not a row-wide fixed gap. A boundary frame is the padded box around all of its members: place members as one compact axis-aligned cluster (no empty bay that lets a non-member sit inside the padded frame) and keep every non-member, especially an external actor, outside that box. Keep an Architecture canvas within 1240px wide, or 1790px when it is at least 1.55 times as wide as tall; past that its 8px relationship labels drop below the desktop floor. Size Architecture sublabels for their preferred 9px text at `5.4px × text units + 8px`, with CJK counting twice; keep supporting copy concise without dropping required facts. Do not trade readability or meaning for fewer crossings. The [Geometry reference](authoring-contract.md#executable-geometry-rules) has measured spacing, port, canvas, and route rules for a diagnosed layout problem. ## Evidence and schema For a real repository, follow [Repository authoring](repository-authoring.md) while inspecting source. Freeze its credential-free origin and 40-character commit in `meta.repository`, attach inspected repository-relative `sources` to each key semantic node, and pass `--repo-root` to the first `finalize`. Each reference proves only the fact visible at that location. Follow material relationships and conditions to their actual source; do not reuse a startup citation as protocol or persistence evidence. Examples show field shape, not legal values or source facts. They are finished showcases, so their optional presentation fields (`meta.subtitle`, `meta.viewBox`, `meta.column_fit`, `via`, `labelAt`) are not defaults; these defaults win. Read the mode schema and shared definition before adding a field, enum, or constrained text. In particular, inspect Architecture boundary kinds. Keep longer evidence in a card while retaining the fact. See [Schema lookup](authoring-contract.md#schema-lookup) for details. ## Presentation and modes Motion is enabled automatically. Omit `meta.animation`; use the Viewer’s Live/Still button to pause or resume playback. Use one primary authored language from the user's choice or the request/conversation. Set `meta.locale`; `en`, `zh-CN`, `zh-TW`, `es`, `ko`, and `ar` select a bundled Viewer catalog with nothing further. For other languages, supply `meta.translations` with reusable UI translations, or disclose the fixed Viewer UI and `` English fallback. Keep exact product, code, protocol, command, API, and environment names while localizing surrounding explanation. See [Language consistency](authoring-contract.md#language-consistency) for bilingual cases. Omit `meta.visual_preset` for classic, `meta.subtitle` for a title-only header, `meta.legend` for truthful auto, and `meta.engineering_profile` for an ordinary system overview. Explicit styles and a subtitle require a user request. Use legend or deployment ownership under the [legend](authoring-contract.md#legend-contract) or [engineering profile](authoring-contract.md#engineering-profile-default) contracts. Branding is optional and explicit when a node names a real product; [Brand marks](brand-marks.md) gives lookup and capture rules for that branch. Never let a badge replace semantic type, label, or relationship facts. Set required `meta.output` to a portable POSIX-relative `.html` path within the working directory; see [Output path contracts](delivery-contract.md#output-path-contracts) for native path exceptions. For a fresh Workflow use schema v2 and omit `meta.viewBox` so the compiler measures the real footprint; do not add empty canvas just to satisfy a viewport ratio. Preserve supplied fixed geometry and v1 sources. In an unpinned draft, omit node `width`: a node starts at 92px and grows to fit its label, sublabel and tag up to 200px. Explicit canvases and absolute route or label pins retain the previous geometry contract. Use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail. For a fresh Sequence omit `meta.viewBox` and `meta.column_fit`: automatic height fits the timeline (no 760px floor), 2–3 short-label participants pack below 920px when labels fit, and the canvas still widens for crowded labels up to its readable width; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. Describe a participant's internal action in a note on its surrounding real cross-participant message, preserving its meaning and order; Sequence self-message loops are not supported. For fresh placement, budget vertical space for that note before placing the next message: 28px is the basic spacing for messages without notes, not a note budget. A note extends below its message; allow at least 44px for one rendered line, 55px for two, or 66px for three before the next message sharing that space (for example, a three-line note at y=200 needs the next message at y=266 or later). Wrapping depends on the final lane width, so leave more room for longer notes and preserve every note's meaning rather than deleting it. These gaps do not guarantee clearance from segment titles, other notes or activations. Supplied fixed y values remain authoritative; in an agent-authored fresh draft, adjust later messages, segment bounds and activation bounds together as needed, preserving order and meaning, and use `sequence/note-overlap` evidence for repairs within those constraints. For a fresh Dataflow start with the stage/row grid of 2 to 5 stages and rows 0 to 4, and follow the canonical [Dataflow canvas and showcase defaults](authoring-contract.md#dataflow). Adjacent stage centres sit 215px apart and default nodes are 112px wide, leaving about 100px between them, so keep a flow label within about 17 text units, counting CJK as two, and move further detail into a card; add dimensions or route controls for supplied geometry or a measured constraint. For Dataflow lineage, work backward from every requested output to the values its producer actually consumes. A transformation that combines a raw payload with derived configuration receives a separate labelled input for each; each upstream node may forward only values it actually outputs. Use `database` for an evidenced storage endpoint, naming the file or store. Represent a computed in-memory result through its producing `backend` operation and name the resulting fields in its label or sublabel. Dataflow requires a non-empty `label` on every flow. Choose `variant` by the meaning its default legend tells the reader: omitted/`default` is ordinary data flow, `emphasis` is primary data, `security` is policy/PII, and `dashed` is async batch. Use `default` for an ordinary dependency, return or fallback; use `security` or `dashed` only when the source supports that meaning. If the user requests a different visual convention, give the affected `meta.legend.entries..label` wording that truthfully describes every flow using that variant, following the [legend contract](authoring-contract.md#legend-contract). For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Preserve each exit's label, note and variant; [eligible equivalent exits](../renderers/lifecycle/README.md#layout) share routing automatically. Keep transition labels short; a recoverable failure needs a real transition back. For Class omit `meta.viewBox` and keep the grid to three columns, or four only while types stay near the 180px default width: long members grow a type toward `layout.typeMaxW` (300px), and every extra column widens the canvas and shrinks all text toward the readability floor, so add rows instead. `layout.gapX` and `layout.typeMaxW` are the width controls. For a repository or directory Tree set `layout.direction: "right"`; keep the default `"down"` for a shallow, balanced breakdown. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail. `finalize` performs the browser gate. Keep the complete drawing comfortably readable on desktop, with zero horizontal overflow. Use meaningful vertical rows and intrinsic-height page scroll when necessary. The 6px projected-text check is a failure floor; at 1440px, aim for ordinary context text around 7.5px or larger. See [Automated browser evidence](delivery-contract.md#automated-browser-evidence) when viewport evidence fails.