Authoring Grammar

Musewoods authoring starts with ordinary Markdown structure and a small amount of explicit field grammar. A ## heading establishes a section, ### creates a nested block, and #### creates an item where the active motif expects one. Recognized **Key:** value fields are consumed by the motif or field model; unsupported render names and structurally impossible shapes fail validation rather than being silently ignored. Where the grammar permits inference, Musewoods may resolve a motif from authored shape so authors do not have to repeat presentation metadata that the structure already makes obvious.

The governing idea is semantic reuse. A motif names an editorial, analytical, or navigational responsibility — framing a proposition, carrying evidence, showing sequence, comparing alternatives, or opening controlled interaction — rather than the page that first happened to need that treatment. This keeps the vocabulary portable and makes renderer changes possible without rewriting content around page-specific CSS.

Vertical rhythm follows the same rule. Authors create paragraph boundaries with ordinary Markdown blank lines; they do not add empty paragraphs, <br>, or spacer content to control layout. The renderer and CSS own paragraph spacing, object spacing, and motif transitions, and those are different responsibilities rather than one universal gap.

This page is a decision guide and specimen map, not a substitute for the machine-generated vocabulary reference. The exhaustive Story contract remains docs/storyboard-vocabulary.md, generated from the registry by npm run docs:vocabulary. The grouped sections below explain why motif families exist, show representative live specimens, and keep the remaining reference forms close enough to the production examples that an author can move from intent to valid source without guessing.

The Motif Families

Structure & Framing

Shapes an argument can sit inside: a two-column callout, a framed exhibit, a panel, or subordinate context in the margin.

Bounded editorial structures

Narrative Openers & Voice

Patterns for beginning a movement, establishing tone, and lifting language out of running prose without fragmenting the narrative.

Openings, emphasis, and voice

Editorial Argument

Structured argumentative moves such as summary maps, proof surfaces, comparisons, sequences, and compact figures.

Claims, evidence, and comparison

Long-Form & Reference Collections

Patterns for essays, channels, references, rosters, timelines, ledgers, and other repeated material whose order and labeling matter.

Repeated reference structures

Navigation & Interaction

Patterns where a reader's selection changes the visible interpretation or provides a bounded next step without turning the page into an application.

Deliberate reader-controlled state

Shared Cross-Field Motifs

Editorial and analytical contracts implemented once and hosted by Stories, Journals, and Groves without forking their behavior.

Shared semantics, field-native voice

Structure & Framing — Live

Purpose

A two-column composition — prose in the wide column, a short nested block in the narrow one.

Authoring

### Two Voices
**Render:** callout
**Treatment:** editorial-callout
**Title:** A callout places an argument beside its terms.
A callout is a two-column composition.

#### Terms
**Render:** chips
Signal · Pattern · Evidence

Live Result

A callout places an argument beside its terms.

A callout is a two-column composition: prose in the wider column, a short nested block — most often chips — in the narrower one.

Signal · Pattern · Evidence

Contract & Implementation

`**Treatment:** takeaway` is only valid on `callout`; otherwise unconstrained.

lib/render/motifs.mjs
components/render/Motifs.tsx

Structure & Framing — Reference

The rest of this family

A section rendered inside another act, separated by a rule rather than a new full-bleed ground.

## A Note On Method
**Render:** interlude
**Within:** narrative

### Aside Head
**Render:** subhead
**Title:** Why the spine is validated one-to-one.

An editorial frame around one sourced analytical motif, referenced by `**Source:**` rather than duplicated.

### Figure 1
**Render:** exhibit
**Title:** Framed comparison
**Source:** comparison-source
**Caption:** Exposure by governance surface.

Bounded editorial prose for one proposition that should read as an intact unit — no list, no fragmentation.

### One Proposition
**Render:** frame
A frame is bounded editorial prose for a single proposition.

The act's main statement: a label, a title, a premise, and prose, allowed to be the most prominent thing on the page.

### The Weight
**Render:** panel
**Label:** The turn
**Title:** A panel carries the weight of its act.
**Premise:** Where an aside is quiet, a panel is the statement.

A ruled mini-argument beside the main column — a label, a title, a line or two, never the weight of the act.

### Aside
**Render:** aside
**Label:** Why this matters
**Title:** Shape inference keeps the Markdown quiet.

Subordinate context anchored in source order, placed in the margin on wide screens and inline on narrow ones.

### The Systems Layer
**Render:** sidecar
**Side:** right
**Title:** Sidecars ride alongside their paragraph.

A compact continuation to one deeper place — a label, a title, a link, and a short note.

### Onward
**Render:** explore
**Label:** Keep reading
**Title:** Editorial is next
**Href:** #editorial

Narrative Openers & Voice — Live

Purpose

Lifts one phrase out of the running prose for emphasis, sharing the same type scale as `thesis`.

Authoring

> A pull-quote lifts one phrase out of the prose for emphasis.

Live Result

A pull-quote lifts one phrase out of the prose for emphasis, using the shared quote type scale.

Contract & Implementation

A single blockquote; no required fields.

lib/render/motifs.mjs
components/render/Motifs.tsx

Narrative Openers & Voice — Reference

The rest of this family

The universal fallback: any section falls to it when nothing tells the renderer a more specific shape.

### Generic Block
**Render:** block
**Title:** A universal block still displays fields and body copy.

The standfirst opener — a claim, a working question, and a lede paragraph.

## Standfirst
**Render:** brief
**Claim:** Stories tell.
**Question:** What does a Story motif look like when the real renderer draws it?

The Story's H1 opener — overline, headline, deck, and a read-on link.

## Opening
**Render:** cover
**Overline:** Field Manual
**Headline:** One vocabulary, drawn by shape

A top-level act: anchored, full-bleed ground, holds its own blocks and any interludes.

## Narrative
**Render:** chapter
**Anchor:** narrative

Opens an act with a movement number, a kicker, a title, and a deck.

### Head
**Render:** title-block
**Number:** 01
**Kicker:** Narrative motifs
**Title:** The Story sets a scene and holds a line.

The same parts as title-block, one register down, for an interlude or a nested act.

### Sub
**Render:** subhead
**Number:** 2.1
**Title:** A subhead opens a section one level down.

Ordinary body copy at reading measure — the default shape a section falls to when it carries paragraphs alone.

### Body
**Render:** prose
Body copy sits at reading measure.

The opening paragraph of an act, with a drop cap — the same job as `lead`, one register more formal.

### Intro
**Render:** lede
The opening paragraph of an act can take a drop cap.

Sets opening prose large without the drop cap, for an act that begins mid-thought.

### Second Voice
**Render:** lead
A lead sets its opening prose large without the drop cap.

A compact inline sequence of terms, set apart by a rule.

### Keyline
**Render:** keyline
Signal · Pattern · Evidence · Provenance

A ruled quote shell — the same type scale as `pull-quote`, given a rule and more gravity.

### Declared
**Render:** thesis
> A thesis is a ruled quote shell.

Editorial Argument — Live

Purpose

An executive argument map — two to eight titled moves, each with an optional number and note. Never navigation.

Authoring

### Argument Map
**Render:** summary
**Title:** Three moves
A summary is an executive argument map.

#### 01
**Title:** State the signal
**Note:** What should the reader notice first.

Live Result

Three moves

A summary is an executive argument map: two to eight titled moves, each with optional number and note. It is never navigation.

State the signal
What should the reader notice first.
Show the pattern
Where the structure is.
Make it inspectable
The evidence a reader can check.

Contract & Implementation

2–8 items; each item needs a title.

lib/render/motifs.mjs
components/render/Motifs.tsx

Editorial Argument — Reference

The rest of this family

A claim paired with concrete evidence — value, label, context, and credit.

### One Proof
**Render:** evidence
**Value:** 100%
**Label:** of specimens on this page rendered by the production pipeline

An editorial comparison across 2–4 declared columns.

### Comparison
**Render:** analysis-grid
**Columns:** Story | Grove

#### Voice
**Title:** Voice
**Story:** First person, narrative.
**Grove:** Institutional, place-making.

A ruled row of a short title and one line about it, repeated.

### Notes
**Render:** note-list

#### First
**Title:** Title plus explanation
**Note:** A ruled row of a short title and a line about it.

A row of figures — a value and a label per item.

### Figures
**Render:** stat-band

#### Motifs
**Value:** 51
**Label:** public Story motifs

Peer objects — a bounded set of equal-weight ideas, distinct from a sidecar's subordinate context.

### Two Ideas
**Render:** editorial-cards

#### Signal
**Label:** First move
**Title:** Tell the reader what to notice

An ordered conceptual progression, one step per item.

### Steps
**Render:** sequence

#### 01
**Number:** 01
**Title:** Author writes Markdown

A portable Musewoods Chart as a narrative exhibit — the shared D3 engine at a Story safe area.

### Trend
**Render:** chart
**Chart:** diverging-bar
**Title:** Delegated authority, by actor

Long-Form & Reference Collections — Live

Purpose

Long-form entries: number, label, title, premise, body, and a closing question — one entry at a time.

Authoring

### Essay Set
**Render:** essays

#### 01
**Number:** 01
**Title:** Long-form entries carry their own premise and question.
**Premise:** essays is for reasoning that needs room.
**Question:** When does a note need to become an essay?

Live Result

Essay

Long-form entries carry their own premise and question.

essays is for reasoning that needs room — a title, a premise, body prose, and a closing question.

QuestionWhen does a note need to become an essay?

An essays collection is the motif for that longer form, one entry at a time.

Contract & Implementation

Each item needs at least a title; premise and question are optional.

lib/render/motifs.mjs
components/render/Motifs.tsx

Long-Form & Reference Collections — Reference

The rest of this family

Ruled entries for outward publication — the only motif Living Content latest-link enrichment attaches to.

### Channels
**Render:** channels

#### Newsletter
**Name:** The dispatch
**Href:** https://example.com/feed

Numbered references — an unclamped title link over a muted metadata line.

### References
**Render:** bibliography

#### 01
**Title:** Musewoods Platform Design Specification
**Href:** /docs/musewoods-platform-design-specification
**Meta:** Internal · current

A ruled, numbered register — quieter than roster, keyed by the item's own name.

### Contributors
**Render:** roll

#### Parser
**Name:** lib/storyboard-parser.mjs

Ruled steps: a short label beside one passage.

### Walkthrough
**Render:** walkthrough

#### Step 1
**Label:** Discover
The field's discover module walks the content root.

Repeated items, each rendering its own fields, prose, and children — items are items only when each carries copy of its own.

### Roster
**Render:** roster

#### Alpha
**Title:** Roster item
A roster repeats items.

Tall ruled rows with an index column: the item's key, its timeframe, then the passage.

### Stack
**Render:** stack

#### One
**Title:** Stacked row
**Timeframe:** Phase I

Ruled rows keyed by a timeframe in the left column.

### Timeline
**Render:** timeline

#### Then
**Title:** A dated row
**Timeframe:** 2024

Dense structured information — a Markdown table, or ruled register rows.

### Ledger
**Render:** ledger

| Register | Record |
|---|---|
| Grammar | The registry is the contract |

Exactly two short title-plus-note cards, side by side.

### Pair
**Render:** duo

#### Left
**Title:** A duo card
**Note:** Two-column grid of short cards.

A row of titled links.

### Links
**Render:** link-row

#### Guide
**Title:** Field Manual
**Href:** /groves/musewoods-field-manual

A compact inline row of short terms.

### Terms
**Render:** chips
Signal · Pattern · Evidence · Provenance

A short numbered run of steps, quieter than sequence.

### Run
**Render:** rail

1. Discover the file
2. Parse to a node tree

Navigation & Interaction — Live

Purpose

A `switcher` whose tabs render as a ruled two-column index rather than pills — for tab labels worth reading as a list.

Authoring

### Indexed Choice
**Render:** switch-index
**Default:** result

#### source
**Number:** 01
**Title:** Source

#### result
**Number:** 02
**Title:** Result

Live Result

Result

Panel behaviour is identical to switcher; only the tab presentation differs.

Contract & Implementation

`**Default:**` must match an item key; behaviour is identical to `switcher`, only the tab presentation differs.

lib/render/motifs.mjs
components/render/Motifs.tsx

Navigation & Interaction — Reference

The rest of this family

A tab strip plus one open panel, keyed on the item's name — never its position — so a saved tab still resolves after a reorder.

### Interpretations
**Render:** switcher
**Default:** narrative

#### narrative
**Short Title:** Narrative
**Full Title:** Read as a story

The same switcher behaviour, tabs laid out as an even board of equal cells — best for a small number of substantial choices.

### Board Choice
**Render:** switch-board
**Default:** wide

#### narrow
**Number:** 01
**Title:** Narrow

A closing call to one deliberate next place — a label, a title, and a return link.

### Close
**Render:** invite
**Label:** End of specimen
**Title:** Back to the Guide
**Return Link Href:** /groves/musewoods-field-manual

Shared Cross-Field Motifs — Live

feature-band, quote-panel, and reel (editorial) plus lens, matrix, and drilldown (analytical) are one semantic contract each, shared verbatim by Stories, Journals, and Groves. The field owns only spacing, width, and accent — never the behaviour. See Architecture & Validation for how the shared layer is structured.

Feature Band

Purpose

A wide image band pairing a title and body with a link — one shared model, rendered natively in each field.

Authoring

**Image:** /images/viewgraphs/lab-panoramic.svg
**Alt:** A wide abstract editorial study.
**Title:** The shared layer landed across three fields
**Body:** One normalized model, one renderer.

Live Result

The shared layer landed across three fields

One normalized model, one renderer.

Contract & Implementation

Requires an image; title, body, and link are optional.

lib/motifs/feature-band.mjs
components/motifs/FeatureBand.tsx

Quote Panel

Purpose

Gives a whole voice room to speak — an attributed or unattributed composed quotation.

Authoring

**Quote:** A quote-panel gives a whole voice room to speak.
**Attribution:** The shared motif layer
**Role:** lib/motifs

Live Result

A quote-panel gives a whole voice room to speak.

The shared motif layerlib/motifs

Contract & Implementation

`**Quote:**` is required; Attribution, Role, Avatar, Source, and Href are optional.

lib/motifs/quote-panel.mjs
components/motifs/QuotePanel.tsx

From A Single Artifact To A Sequence

feature-band and quote-panel each compose one editorial moment. reel changes the unit of reading: it lets several authored images, or canonical Viewgraph frames, unfold as one bounded sequence without turning the page into a gallery application.

Reel

Purpose

A manual or autoplaying image sequence — or, in `Kind: viewgraph` mode, a live Viewgraph frame sequence.

Authoring

**Kind:** images

#### 01
**Image:** /images/viewgraphs/lab-architecture.svg
**Alt:** A layered architecture study.
**Caption:** Where it started.

Live Result

Where it started.

Contract & Implementation

`Kind: images` needs at least one frame with an image; `Kind: viewgraph` resolves a real Viewgraph by slug.

lib/motifs/reel.mjs
components/motifs/Reel.tsx

From Editorial To Analytical

feature-band, quote-panel, and reel above form the shared editorial family. lens, matrix, and drilldown below form the shared analytical family: a compact vocabulary for moving from interpretation to structured evidence without turning every analytical section into a chart.

Lens

Purpose

The same analytical object, read through 2–3 authored interpretations without changing the underlying object.

Authoring

**Default:** authority

#### authority
**Label:** Authority
Who may act, and how far.

#### exposure
**Label:** Exposure
What is at stake if they act.

Live Result

Who may act, and how far.

Contract & Implementation

2–3 panels; every panel labelled and non-empty; `**Default:**` must resolve.

lib/analytics/lens.mjs
components/analytics/Lens.tsx

Matrix

Purpose

Categorical or ordinal state across two dimensions — a semantic evidence surface, not a spreadsheet.

Authoring

**Columns:** Sense | Act
**Scale:** presence

#### copilot
**Label:** Copilot
**Cells:** full | absent

Live Result

Live specimen — 1 rows by 2 columns.

	full	absent

fullpartialabsent

Contract & Implementation

`**Columns:**` required; a scale or `**States:**` declares the vocabulary; every row needs one cell per column.

lib/analytics/matrix.mjs
components/analytics/Matrix.tsx

From Pattern To Inspectable Evidence

lens changes the authored interpretation and matrix exposes categorical structure. drilldown takes the next step: it preserves a compact overview while placing the evidence for an individual case one deliberate action away.

Drilldown

Purpose

Every item expandable — title, summary, and detail; one row open at a time.

Authoring

#### copilot
**Title:** Copilot
**Summary:** Assisted, human-triggered.
Detail: bounded to one task, no autonomous initiation.

Live Result

Assisted, human-triggered.

Contract & Implementation

Every item needs a Title, a Summary, and detail content.

lib/analytics/drilldown.mjs
components/analytics/Drilldown.tsx

Journal-Native Markers — Live

Purpose

A banded Markdown table — the one supported Journal table treatment.

Authoring

> [!table-banded]
> | Motif | Field |
> |---|---|
> | highlight | Journal |

Live Result

Publishing field	Structural parser	Field registry and notes
Stories	`parseStoryboard`	`lib/render/motifs.mjs` — motif registry, treatments, and the field spacing adapter
Journals	`parseMarkdownDocument`	`lib/journal/sidecars.mjs` — the editorial-marker promotion pass, including this `[!table-banded]` treatment
Viewgraphs	`loadViewgraphsFromPath`	`lib/viewgraphs/model.mjs` — fixed 1600×900 logical geometry, its own Mermaid theme
Groves	`parseGrovePage`	`lib/groves/motifs.mjs` — native motifs plus the live-specimen Developer Guide infrastructure

Contract & Implementation

A `[!table-banded]` marker wraps an ordinary Markdown table; no other table treatment is supported.

lib/journal/sidecars.mjs
components/render/ContentBlocks.tsx

Journal-Native Markers — Reference

The rest of the Journal-only markers

Marginal content on the left, with an optional accent variant (`-red`, `-green`, `-blue`).

> [!sidecar-left]
> A note in the margin, anchored in source order.

The same contract, on the right.

> [!sidecar-right]
> A note in the margin, anchored in source order.

A callout marking one passage as worth a second look.

> [!highlight]
> A short passage the Journal wants the reader to notice.

A small bounded set of cards inside Journal flow.

> [!cards]
> #### First
> A short card.

Grove-Native Motifs

Motif	Job	Live on
`threshold`	Opening identity, proposition, atmosphere	Grove Runtime
`statement`	One idea, strong spatial authority	This page, Start Here
`artifact`	An object dominates the section	Grove Runtime
`evidence`	Claim plus concrete evidence	Architecture & Validation
`sequence`	Ordered conceptual progression	Architecture & Validation
`passage`	Movement through states	Grove Runtime
`field`	Landscape of related domains	This page, Publishing Fields
`constellation`	Relationships among concepts	Architecture & Validation
`ledger`	Dense structured information	This table
`outcomes`	A small number of high-value quantities	Extending Musewoods
`voices`	People and perspectives	Grove Runtime
`origin`	Long-form origin prose, never fragmented	Start Here
`principles`	Named enduring commitments	Extending Musewoods
`portal`	Deliberate navigation, not CTA buttons	Start Here
`grow`	The living, editorial edge	Grove Runtime, Publishing Fields
`collection`	Existing content, referenced not copied	Grove Runtime

Reference Matrix

Public authoring surfaces, at a glance

Reference Matrix — 3 rows by 2 columns.

	full	full
	full	full
	full	full

fullpartialabsent

Current counts belong to System Health; this Matrix tracks whether each public authoring surface is both explained and exercised.

Ground Is Metadata, Not A Motif

Story Ground belongs on the metadata section
A Story may choose one of the governed Ground values at the page boundary. The field is optional; omission resolves to soil. Ground is not a section motif, not a per-movement treatment, and not browser dark mode.
```
## Meta

**Render:** metadata

**Title:** Example Story
**Canonical:** https://musewoods.com/example-story
**Ground:** forest-floor
```
Grove Ground belongs in `manifest.yaml`
A Grove declares the same environmental choice as ground.mode. The shared vocabulary is the same, but the authoring location follows the local-site contract rather than Story metadata. Components consume semantic tokens; they do not branch into a second component tree merely because the resolved Ground is Forest Floor.
```
ground:
  mode: forest-floor
```
Viewgraph surface remains a separate contract
Viewgraphs may vary their visual surface through the Viewgraph model, but that is not another spelling of Story/Grove Ground. Embedded Viewgraph frames reassert their own canonical presentation tokens so a surrounding Forest Floor Story or Grove cannot accidentally re-tone the frame.

Navigation Source Grammars Are Not Motif Grammar

Trailhead v2 has its own semantic parser boundary
musewoods.trailhead/v2 is not authored by registering another Story or Grove **Render:** motif. Its source grammar owns Encounters, semantic roles, intent, transitions, routes, relationships, targets, significance, and optional compatible rendering hints. The current authoring contract is therefore semantic before visual: enter, orient, begin, notice, guide, choose, dwell, discover, question, connect, and return state why an encounter exists, while the renderer decides how that role is expressed. See Trailheads.
Trailhead v1 remains a compatibility grammar
The older Resonance source generation still has its own parser boundary and normalizes its compact or heading-shaped source into the four-role Path model entry, deepen, see, and follow. That compatibility lane should not be used to smuggle v2 semantics into v1 or to redefine Trailheads around the circulation-era Path vocabulary. New semantic journeys use v2.
Trailmap YAML is graph authoring, not Grove authoring
A v9 Trailmap is authored as canonical YAML rooted at trailmap: and normalizes into a graph of Horizons, Regions, Nodes, Edges, Trails, provenance, and projection hints. Its node types and edge kinds are Navigation System vocabulary, not Grove fragments and not Story motifs. A fenced Trailmap example inside this Guide is documentation; it does not become a live Trailmap merely because the surrounding Grove can render YAML as code.
Geometry belongs to projection
Authors state Trailhead journey semantics and Trailmap topology. They do not use Grove motifs to draw Trailhead spines, place Trailmap Waymarkers, size map clusters, or hard-code connector geometry. The Trailhead renderer owns its journey presentation; the Trailmap projection owns deterministic woodland layout, region gravity, Waymarker interaction, active-Trail emphasis, responsive behavior, and reduced-motion behavior where motion exists.
Canonical sources remain authoritative
Trailheads and Trailmaps may reference Stories, Journals, Viewgraphs, and Groves, but neither navigation grammar creates a second canonical body for the referenced object. Hooks, summaries, and Waymarker context explain why an object matters in the current journey or field. Deep reading resolves to the source of record, and the navigation surface must remain intelligible even when the Explorer chooses not to open that source.
Fenced navigation examples remain documentation
A Trailhead Markdown excerpt or Trailmap YAML excerpt inside a fenced block explains source grammar; it does not count as a live Story/Grove motif specimen and should not be added to the Story/Grove coverage ledger. Navigation parser, normalization, validation, projection, and interaction coverage belongs to the Trailhead and Trailmap test surfaces, while this Field Manual documents the public contracts contributors need to preserve.

Coverage

tests/developer-guide-coverage.test.mjs compares the Guide coverage ledger with the live capability model in both directions. The important rule is that a renderable capability earns live coverage only from a production **Render:**/**Chart:** directive or an explicitly registered live specimen; a fenced source example by itself is documentation, not execution.

That distinction keeps this page useful as a reference without confusing code samples with regression evidence. Public Story and Journal capabilities can be covered through their dedicated production specimens, while Grove-native capabilities can point to real renders inside this Guide. System Health then reports the current registry counts and whether those coverage relationships still hold.

Authoring Grammar

The Motif Families

Structure & Framing

Narrative Openers & Voice

Editorial Argument

Long-Form & Reference Collections

Navigation & Interaction

Shared Cross-Field Motifs

Structure & Framing — Live

A callout places an argument beside its terms.

Structure & Framing — Reference

interlude+

exhibit+

frame+

panel+

aside+

sidecar+

explore+

Narrative Openers & Voice — Live

Narrative Openers & Voice — Reference

block+

brief+

cover+

chapter+

title-block+

subhead+

prose+

lede+

lead+

keyline+

thesis+

Editorial Argument — Live

Three moves

State the signal

Show the pattern

Make it inspectable

Editorial Argument — Reference

evidence+

analysis-grid+

note-list+

stat-band+

editorial-cards+

sequence+

chart+

Long-Form & Reference Collections — Live

Long-form entries carry their own premise and question.

Long-Form & Reference Collections — Reference

channels+

bibliography+

roll+

walkthrough+

roster+

stack+

timeline+

ledger+

duo+

link-row+

chips+

rail+

Navigation & Interaction — Live

Result

Navigation & Interaction — Reference

switcher+

switch-board+

invite+

Shared Cross-Field Motifs — Live

Feature Band

Quote Panel

From A Single Artifact To A Sequence

Reel

From Editorial To Analytical

Lens

Matrix

From Pattern To Inspectable Evidence

Drilldown

Copilot+

Journal-Native Markers — Live

Journal-Native Markers — Reference

sidecar-left+

sidecar-right+