@nowline/cli 0.8.5 → 0.9.0

package/man/nowline.5

@@ -42,11 +42,11 @@ files.
 .It
 .Sy config
 section (optional). Rendering configuration: styles, defaults,
-scale, calendar, symbols.
+scale, calendar, symbols, non-working and working days.
 .It
 .Sy roadmap
 section (required). Content: persons, teams, anchors, labels, sizes,
-statuses, swimlanes, items, milestones, footnotes.
+statuses, waves, swimlanes, items, milestones, footnotes.
 .El
 .Pp
 .Sy config
@@ -163,14 +163,16 @@ The included file's
 .Sy style ,
 .Sy symbol ,
 .Sy default ,
+.Sy calendar ,
+.Sy non-working ,
 and
-.Sy calendar
+.Sy working
 declarations.
 .It Sy Roadmap
 The included file's
 .Sy roadmap
 declaration plus all its content (persons, teams, anchors, labels,
-sizes, statuses, swimlanes, items, milestones, footnotes).
+sizes, statuses, waves, swimlanes, items, milestones, footnotes).
 .El
 .Pp
 .Sy config:
@@ -182,6 +184,12 @@ On collision, the
 .Em parent wins
 and the parser emits a warning identifying the shadowed definition
 and source file.
+A
+.Sy non-working
+or
+.Sy working
+declaration collides only with a parent declaration of the same keyword
+and name; an unnamed one never collides and always merges.
 .It Sy ignore
 Child config is dropped entirely.
 If child roadmap content is merged, it resolves styles from the
@@ -258,6 +266,38 @@ line; this is an explicit exception to the
 merge behaviour because
 .Sy start:
 defines the shared timeline baseline.
+.Pp
+Waves never merge.
+For any include whose
+.Sy roadmap:
+mode is not
+.Sy ignore ,
+if the child declares a
+.Sy roadmap ,
+has swimlanes, or declares waves, the parent and child must declare
+the same waves: the same ids, in the same order, with the same
+resolved start floors.
+Floors are compared by the date they resolve to, so
+.Sy after:fy-budget
+and
+.Sy after:2026-02-02
+agree when the anchor is on that date.
+A mismatch in either direction is the error
+.Sy NL.E0202 ,
+reported on the parent's
+.Sy include
+line; two files with no waves pass.
+Waves are barriers across the whole canvas, so a silently shadowed
+wave list would move every lane's columns.
+When ids, order and floors agree, a differing title,
+.Sy style: ,
+.Sy labels: ,
+.Sy link: ,
+or description is the warning
+.Sy NL.W0701
+and the parent's definition is used.
+A vocabulary-only child (persons, teams, labels, sizes, statuses,
+anchors; no roadmap, no swimlanes, no waves) does not take part.
 .Sh CONFIG SECTION
 The optional
 .Sy config
@@ -265,14 +305,16 @@ section marker appears before
 .Sy roadmap .
 Config keywords sit at the top level (not indented under the
 marker) and define rendering vocabulary, defaults, axis settings,
-day arithmetic, and custom symbols.
+day arithmetic, non-working days, and custom symbols.
 .Pp
-Five config keywords:
+Seven config keywords:
 .Sy scale ,
 .Sy style ,
 .Sy symbol ,
 .Sy default ,
-.Sy calendar .
+.Sy calendar ,
+.Sy non-working ,
+.Sy working .
 Every config entry is optional; if
 .Sy config
 is omitted, all built-in defaults apply.
@@ -370,6 +412,13 @@ Banned, by entity type:
 .Sy date , link , description .
 .It Sy default footnote
 .Sy on , link , description .
+.It Sy every default line
+.Sy wave
+\(em sequencing creates invisible dependencies, and there is no
+.Sy default wave .
+In a roadmap with waves it is an error; in a roadmap without waves
+it is ignored with the warning
+.Sy NL.W0702 .
 .El
 .Pp
 Raw style properties
@@ -461,7 +510,7 @@ Engineering working-day arithmetic.
 Calendar-day arithmetic with weekends.
 .Sy days-per-week:7 ,
 .Sy days-per-month:30 ,
-.Sy days-per-quarter:90 ,
+.Sy days-per-quarter:91 ,
 .Sy days-per-year:365 .
 .It Sy calendar:custom
 Author-supplied values via the
@@ -506,6 +555,166 @@ is
 .Sy 260d ,
 not
 .Sy 12 \(mu 22d = 264d .
+.Ss non-working and working \(em declarations
+A
+.Sy non-working
+declaration takes days out of the schedule: weekends, holidays,
+closures.
+A
+.Sy working
+declaration puts days back, for a crunch Saturday or a make-up day.
+Both are config keywords and share one shape:
+.Bd -literal -offset indent
+config
+
+non-working weekend "Weekend" every:[fri, sat]
+non-working new-year "New Year's Day" date:2027-01-01
+non-working summit "Company summit" start:2026-09-14 end:2026-09-16
+non-working fridays every:fri start:2026-07-01 end:2026-08-31
+working crunch "Crunch Saturday" date:2026-01-10
+.Ed
+.Pp
+The id and the title are both optional.
+Durations count working days only, so an item that spans a non-working
+day ends later, and an item that spans a working exception ends
+sooner.
+The chart labels a dated declaration that has a title
+.Po
+.Sy date:
+or
+.Sy start:
+with
+.Sy end:
+and no
+.Sy every:
+.Pc
+with its title and the number of working days it removes, for example
+.Dq Thanksgiving \[u00B7] 2d .
+Under
+.Sy hide
+the label sits on a cut line at the seam, and under
+.Sy show
+at the left edge of the shaded band.
+A dated
+.Sy working
+declaration with a title is labelled at the days it turns from
+non-working to working, with its title and the number of days it adds,
+for example
+.Dq Crunch Saturday \[u00B7] +1d ,
+and with no cut line in either view; a weekday make-up day inside a
+dated closure counts.
+A title on a recurrence is not drawn.
+A declaration takes these properties:
+.Bl -tag -width "every:"
+.It Sy date:
+One ISO date or a list of dates.
+.It Sy start:
+One ISO date, inclusive: the first day of a range, or the day a
+recurrence begins.
+.It Sy end:
+One ISO date, inclusive: the last day of a range, or the day a
+recurrence stops.
+It must not be before
+.Sy start: .
+.It Sy every:
+One weekday or a list of
+.Sy sun , mon , tue , wed , thu , fri , sat .
+A weekly recurrence.
+.El
+.Pp
+A declaration is exactly one of three shapes:
+.Sy date:
+alone; a range of
+.Sy start:
+and
+.Sy end:
+without
+.Sy every: ;
+or
+.Sy every:
+with optional
+.Sy start:
+and
+.Sy end:
+bounds.
+With neither bound a recurrence is open-ended and holds in every week.
+.Pp
+On a given day the most specific declaration decides, and
+.Sy working
+wins a tie:
+.Bl -enum -offset indent -compact
+.It
+a dated declaration, a
+.Sy date:
+list or a range;
+.It
+a bounded recurrence;
+.It
+the open-ended week.
+.El
+.Pp
+Order never matters: the same declarations in any order, in the file
+or in includes, give the same schedule.
+.Sy calendar:business
+supplies a
+.Sy non-working weekend
+declaration for Saturday and Sunday.
+A
+.Sy non-working
+declaration named
+.Sy weekend
+replaces it, for any preset, so a Friday and Saturday week needs no
+custom calendar; any other name adds to the preset.
+.Pp
+The open-ended week must keep a working day, and
+.Sy days-per-week
+should agree with the weekdays it leaves working
+.Pq see Sx VALIDATION .
+A declaration whose value or shape is malformed is skipped when the
+calendar is built.
+Under
+.Sy config:isolate
+the child's declarations stay in its region and have no effect on the
+chart yet: the region is laid out on the host's calendar.
+The validator reads only its own file, so a declaration in an include
+is not counted by the open-ended week checks.
+.Ss non-working: \(em day display
+Under
+.Sy calendar:business
+the weekend is non-working: durations count working days only, and the
+chart either hides those days or draws them.
+The display is a roadmap-only style key, set on the
+.Sy default roadmap
+line (raw style keys are not allowed on the
+.Sy roadmap
+line itself):
+.Bd -literal -offset indent
+config
+
+default roadmap non-working:show
+.Ed
+.Bl -tag -width "show"
+.It Sy hide Pq default
+Non-working days take no width; each run collapses to a seam.
+.It Sy show
+Non-working days are drawn at full width and shaded.
+A bar paints across a weekend but ends at the end of its last working day,
+so the gap between chained bars shows.
+.El
+.Pp
+The display never changes the schedule, so Mermaid, MS Project, and XLSX
+output is the same in both views.
+It can also be chosen at render time; the first of these wins: the
+.Fl -non-working
+option (or the equivalent option on another surface), the file's
+.Sy default roadmap non-working:
+key, then
+.Sy hide .
+Under
+.Sy calendar:full
+and
+.Sy calendar:custom
+there are no non-working days and the key has no effect.
 .Sh ROADMAP SECTION
 The
 .Sy roadmap
@@ -555,18 +764,33 @@ resolved relative to the
 .Pa .nowline
 file's directory.
 Forward slashes on all platforms; only local paths are accepted.
+The logo draws left of the title inside the header card, vertically
+centered, and is embedded in the output (SVG inline, raster as a
+base64 data URI).
 Asset resolution happens at render time, not parse time \(em a file
 referencing a missing logo is still a valid document.
+A missing, unsupported or unreadable logo is a warning and the chart
+renders as if no logo were declared; under
+.Fl -strict
+it is an error.
 .It Sy logo-size:
 Size preset
 .Pq Sy xs | sm | md | lg | xl ,
 default
 .Sy md .
+Sets the drawn logo height (18, 24, 36, 48 or 72 px); the width follows
+the logo's own aspect ratio, so a larger or smaller source is scaled to
+fill the same slot.
+A logo wider than 160 px at that height scales down to fit.
+A logo taller than the title and author grows the header card;
+.Sy xl
+also grows the 72 px band of
+.Sy header-position:above .
 .El
 .Pp
-Twelve roadmap-section keywords:
+Thirteen roadmap-section keywords:
 .Sy swimlane , item , parallel , group ,
-.Sy person , team , anchor , label , size , status , milestone ,
+.Sy person , team , anchor , label , size , status , wave , milestone ,
 .Sy footnote .
 Each follows the universal
 .Sy [id] ["title"] [key:value...]
@@ -663,15 +887,25 @@ swimlane platform
 .Pp
 A
 .Sy group
-with
-.Sy style: ,
-.Sy labels: ,
-or other visual properties renders with a visible bounding box
-plus a small title chiclet.
+is drawn above and around its items, never beside them: a header
+(its title over a bracket spanning exactly its dates) over a body
+shaded with its
+.Sy bg ,
+padded above and below.
+.Sy style:
+changes only the colours.
 A
+.Sy parallel
+is drawn the same way, its tracks stacked in its body.
+In a roadmap with waves, a
 .Sy group
-with no styling is purely structural \(em it only governs
-sequencing and inner row growth, with no visible artifact.
+with no title, no
+.Sy style: ,
+and no
+.Sy labels:
+that carries
+.Sy wave:
+draws nothing; it only assigns membership.
 .Ss anchor \(em named date on the timeline
 .Bd -literal -offset indent
 anchor kickoff date:2026-01-06
@@ -780,6 +1014,119 @@ overrides.
 .Pp
 .Sy status
 declarations must precede any entity that references them.
+.Ss wave \(em barrier across every swimlane
+.Bd -literal -offset indent
+wave id ["title"] [after:anchor|milestone|date] \e
+    [style:...] [labels:...] [link:...]
+.Ed
+.Pp
+A
+.Sy wave
+is a strict, sequential barrier that spans every swimlane:
+.Em no item in wave k+1 starts before every item in wave k has ended .
+A wave opens for every lane at the instant the previous wave's
+slowest member ends, so lanes that finish early wait at the boundary.
+Waves are declared once, in order, in the roadmap section, and
+declaration order is time order.
+Work joins a wave with the
+.Sy wave:
+property on an
+.Sy item ,
+.Sy group ,
+or
+.Sy parallel .
+.Bd -literal -offset indent
+wave discover "Discover"
+wave build "Build"
+wave launch "Launch" after:fy-budget
+
+swimlane web "Web"
+  item research "UX research" duration:2w wave:discover
+  group wave:build
+    item checkout "Checkout v2" duration:3w
+    item a11y "Accessibility pass" duration:1w
+  item launch-page "Launch page" duration:1w wave:launch
+swimlane ops "Ops"
+  item on-call "On-call and KTLO" duration:10w
+
+milestone beta "Beta" after:build
+.Ed
+.Pp
+A
+.Sy wave
+line accepts:
+.Bl -tag -width "style:"
+.It Sy id
+Required
+.Pq Sy NL.E1100 .
+Joins the single shared identifier namespace.
+.It Sy title
+Optional.
+The strip label; falls back to the id.
+.It Sy after:
+Optional start floor.
+The wave cannot open before the latest of its elements.
+Each element must be an anchor id, the id of a milestone that has
+.Sy date: ,
+or an ISO date (at most one date); any other kind of entity is
+.Sy NL.E1106 .
+A gap between one wave's end and the next wave's floor is allowed.
+.It Sy style:
+Wave colours: the style's
+.Sy bg
+opts the wave into a column tint,
+.Sy fg
+colours its boundary line,
+.Sy text
+its strip label, and
+.Sy border
+sets the boundary dash.
+.It Sy labels: , link: , description
+Carried in the model, JSON and XLSX export, and LSP hover; not painted.
+.El
+.Pp
+Keys not allowed on a
+.Sy wave :
+.Sy before: , date: , start: , length: , duration: , size: ,
+.Sy capacity: , remaining: , wave:
+.Pq Sy NL.E1105 .
+A wave's span comes from its items.
+To give a wave a deadline, add a dated milestone
+.Sy after:<wave> ;
+it turns red when the wave runs late.
+.Pp
+Items without an effective wave are
+.Em background work :
+on-call, support, ongoing maintenance.
+A barrier never holds background work back and its own end never
+extends a wave, but it still follows lane order and its own
+.Sy after: .
+Background work is drawn hatched.
+.Pp
+A wave id is a valid
+.Sy after: ,
+.Sy before: ,
+and
+.Sy on:
+target.
+.Sy after:<wave>
+starts no earlier than the end of that wave, and a floating
+.Sy milestone after:<wave>
+sits on the wave's closing boundary.
+.Sy before:<wave>
+should finish before the wave's start (soft, like every
+.Sy before: ) .
+.Sy on:<wave>
+attaches a footnote to the wave.
+Wave references draw no dependency arrow.
+.Pp
+A roadmap
+.Qq has waves
+when it declares at least one wave with a valid id.
+In a roadmap without waves every
+.Sy wave:
+key is ignored with the warning
+.Sy NL.W0702 .
 .Ss milestone \(em achievement marker
 .Bd -literal -offset indent
 milestone v1-ga "v1 GA" date:2026-06-30
@@ -809,7 +1156,7 @@ footnote capacity-risk "Team capacity risk" on:[mobile, platform]
 .Pp
 .Sy on:
 is required and references one or more identifiers (item,
-swimlane, anchor, milestone, person, team).
+swimlane, anchor, milestone, wave, person, team).
 Use bracket notation for multiples:
 .Sy on:[id1, id2] .
 Footnotes are numbered sequentially by document order; a
@@ -871,7 +1218,7 @@ and the
 sub-directive.
 .Sh UNIVERSAL PROPERTIES
 These properties are valid on every entity type: items, swimlanes,
-parallel blocks, groups, milestones, anchors, persons, teams,
+parallel blocks, groups, milestones, anchors, waves, persons, teams,
 labels, sizes, statuses, footnotes.
 .Bl -tag -width "description"
 .It Sy labels:
@@ -908,7 +1255,8 @@ Raw style properties
 .Sy bg , Sy fg , Sy text , Sy border , Sy icon , Sy shadow ,
 .Sy font , Sy weight , Sy italic , Sy text-size , Sy padding ,
 .Sy spacing , Sy header-height , Sy corner-radius , Sy bracket ,
-.Sy capacity-icon , Sy timeline-position , Sy minor-grid
+.Sy header-position , Sy capacity-icon , Sy timeline-position ,
+.Sy minor-grid , Sy non-working
 .Pc
 may only appear in
 .Sy style
@@ -921,6 +1269,8 @@ lines \(em both of which live in
 and
 .Sy before
 are also valid on swimlanes, parallel blocks, and groups.
+.Sy wave
+is also valid on parallel blocks and groups, but not on swimlanes.
 The rest are item-only.
 .Bl -tag -width "remaining"
 .It Sy status:
@@ -945,12 +1295,30 @@ Identifier or bracketed list.
 The entity starts after the referenced entity finishes.
 .Sy after:[a, b]
 starts after the latest finisher.
-Accepts item, milestone, anchor, parallel, or group ids.
+Accepts item, milestone, anchor, parallel, group, or wave ids.
 .It Sy before:
 Identifier or bracketed list.
 The entity must finish before the referenced entity starts.
 .Sy before:[a, b]
 finishes before the earliest starter.
+.It Sy wave:
+Wave id.
+Exactly one declared
+.Sy wave
+.Pq Sy wave:build ;
+an item belongs to at most one wave.
+The effective wave of an item is its own value, else that of its
+nearest enclosing
+.Sy group
+or
+.Sy parallel
+that carries one; a swimlane never contributes.
+A descendant may repeat its container's value but not differ from it
+.Pq Sy NL.E1102 .
+A block without
+.Sy wave:
+may hold children in different waves.
+Only meaningful in a roadmap with waves.
 .It Sy size:
 Size alias.
 .Sy size:l
@@ -1197,11 +1565,33 @@ Default varies by entity.
 .It Sy header-height
 .Sy none | xs | sm | md Pq default | lg | xl .
 Roadmap-only.
+Height of the timeline date strip: 16, 20, 24, 32 or 40 px from
+.Sy xs
+to
+.Sy xl ,
+with the date labels kept vertically centred.
+It sizes the top strip and the mirrored bottom strip alike.
+.Sy none
+removes every date strip, including the ones
+.Sy timeline-position
+asks for; with
+.Sy bottom
+or
+.Sy both
+that draws the warning
+.Sy NL.W0704 .
 .It Sy corner-radius
 .Sy none | xs | sm | md | lg | xl | full .
 .It Sy bracket
-.Sy none Pq default | solid | dashed .
-Parallel-only.
+.Sy none | solid | dashed .
+The header bracket over a group's or parallel's dates:
+.Sy solid
+by default on a group,
+.Sy dashed
+on a parallel;
+.Sy none
+hides it.
+Containers only.
 .It Sy capacity-icon
 Glyph used as the suffix to capacity numbers.
 Built-in identifiers:
@@ -1217,6 +1607,16 @@ Built-in identifiers:
 Custom: any
 .Sy symbol
 id; inline: a double-quoted Unicode literal.
+.It Sy header-position
+.Sy beside Pq default | above .
+Roadmap-only.
+Where the roadmap header card (title and author) sits:
+.Sy beside
+puts it in a column left of the chart, 120 to 240 px wide, with the
+title wrapping to fit;
+.Sy above
+puts it in a full-width 72 px band above the chart, which then spans
+the whole canvas width.
 .It Sy timeline-position
 .Sy top Pq default | bottom | both .
 Roadmap-only.
@@ -1228,6 +1628,21 @@ Roadmap-only.
 When
 .Sy true ,
 draws faint dotted grid lines at every tick boundary.
+.It Sy non-working
+.Sy hide Pq default | show .
+Roadmap-only; set it on
+.Sy default roadmap .
+Under a calendar that has non-working days
+.Pq Sy calendar:business ,
+.Sy hide
+collapses them to a seam and
+.Sy show
+draws each run at full width as a shaded band that bars paint across.
+The
+.Fl -non-working
+option of
+.Xr nowline 1
+and its equivalent on every other surface override it.
 .El
 .Pp
 Built-in icon names are rendered from a curated SVG library
@@ -1275,7 +1690,7 @@ Identifiers match
 letters, digits, underscores, and dashes, starting with a letter
 or underscore.
 They must be unique across the merged result (the file and all
-its includes); items, parallel blocks, groups, anchors, persons,
+its includes); items, parallel blocks, groups, anchors, waves, persons,
 teams, milestones, footnotes share one namespace.
 .Pp
 Idiomatic Nowline uses kebab-case but
@@ -1306,7 +1721,7 @@ and
 .Sy before:
 each accept a single identifier or a bracketed list.
 References may target items, milestones, anchors, parallel
-blocks, or groups.
+blocks, groups, or waves.
 .Bl -bullet -offset indent -compact
 .It
 .Sy after:id
@@ -1326,6 +1741,17 @@ referenced entities finish (i.e. after the latest of them).
 \(em finishes before the
 .Em earliest
 of the referenced entities starts.
+.It
+.Sy after:wave
+\(em starts no earlier than the
+.Em end
+of the wave.
+.Sy before:wave
+\(em should finish before the
+.Em start
+of the wave.
+.Sy on:wave
+\(em attaches a footnote to the wave.
 .El
 .Pp
 Circular dependencies across the full graph (including every
@@ -1371,7 +1797,8 @@ declaration per file (subject to
 mode).
 .It
 All identifiers are unique across the merged result.
-Parent wins on collision, with a warning.
+Parent wins on collision, with a warning (waves excepted; see
+.Sx INCLUDES ) .
 .It
 Every entity must have at least an identifier or a title (or
 both).
@@ -1400,8 +1827,9 @@ line.
 .It
 .Sy label ,
 .Sy size ,
+.Sy status ,
 and
-.Sy status
+.Sy wave
 declarations must appear in the roadmap section.
 Placing them before
 .Sy roadmap
@@ -1418,12 +1846,13 @@ and
 must resolve to declared identifiers within the merged scope.
 .It
 A
-.Sy size:
+.Sy size: ,
+.Sy status: ,
 or
-.Sy status:
+.Sy wave:
 reference must resolve to a declaration that appears
 .Em earlier in the file
-(or in an earlier include).
+(or in an earlier include; waves are never contributed by includes).
 Forward references are an error.
 .It
 No circular dependencies in
@@ -1480,6 +1909,39 @@ fraction, or
 When both numeric thresholds are set,
 .Sy warn-at \(<= over-at .
 .It
+Style values, in a
+.Sy style
+block or on a
+.Sy default
+line:
+.Sy bg: , fg: ,
+and
+.Sy text:
+take a named color, a hex value, or
+.Sy none
+.Pq Sy NL.E0801 ;
+a key with a fixed set of values, such as
+.Sy border: , shadow: ,
+or
+.Sy font: ,
+takes one of them
+.Pq Sy NL.E0802 .
+A key in a
+.Sy style
+block that is not a style property is
+.Sy NL.E0803 .
+.It
+A raw style property
+.Pq Sy bg: , Sy icon: , Sy capacity-icon: , No ...
+on an entity in the roadmap section is
+.Sy NL.E0804 ;
+declare a named
+.Sy style
+in
+.Sy config
+and reference it with
+.Sy style:id .
+.It
 .Sy capacity-icon:
 value must be a built-in identifier
 .Po
@@ -1491,6 +1953,56 @@ declaration in scope, or a double-quoted Unicode literal.
 Same contract for
 .Sy icon: .
 .It
+.Sy non-working:
+value must be
+.Sy hide
+or
+.Sy show ,
+on
+.Sy default roadmap
+and in a
+.Sy style
+block.
+Any other value is
+.Sy NL.E0800
+(one error per value).
+.It
+The roadmap-only style keys
+.Sy header-height , header-position , timeline-position ,
+.Sy minor-grid ,
+and
+.Sy non-working
+take effect only on
+.Sy default roadmap
+(or in a
+.Sy style
+block the roadmap references).
+On any other
+.Sy default
+line they are ignored with the warning
+.Sy NL.W0703 .
+.Sy style
+blocks are not checked.
+.It
+When the roadmap's style sets
+.Sy header-height:none
+together with
+.Sy timeline-position:bottom
+or
+.Sy both ,
+no date strip is drawn at all, which draws the warning
+.Sy NL.W0704 .
+The style resolves from
+.Sy default roadmap ,
+then the style of each label on the
+.Sy roadmap
+line (the first label winning), then its own
+.Sy style: ,
+a later key winning.
+Only styles and labels declared in the same file are read; a
+.Sy style:
+or label from an include leaves the check silent.
+.It
 .Sy remaining:
 is either a percentage
 .Pq Sy 0% \(en Sy 100%
@@ -1519,6 +2031,60 @@ When
 all four
 .Sy days-per-*
 entries are required and must be positive integers.
+.It
+A
+.Sy non-working
+or
+.Sy working
+declaration is one of three shapes: a lone
+.Sy date: ;
+.Sy start:
+and
+.Sy end:
+without
+.Sy every: ;
+or
+.Sy every:
+with optional bounds
+.Pq Sy NL.E0900 .
+Its only keys are
+.Sy date: , start: , end: ,
+and
+.Sy every:
+.Pq Sy NL.E0901 ,
+and
+.Sy start:
+and
+.Sy end:
+take one date each
+.Pq Sy NL.E0902 .
+.It
+Every date on a calendar declaration is a real calendar day
+.Pq Sy NL.E0405 ,
+and
+.Sy end:
+is not before
+.Sy start:
+.Pq Sy NL.E0903 .
+.It
+.Sy every:
+values are weekday names
+.Pq Sy NL.E0904
+and each appears at most once
+.Pq Sy NL.E0905 .
+.It
+The open-ended week keeps at least one working weekday
+.Pq Sy NL.E0906 .
+.Sy days-per-week
+agrees with the weekdays it leaves working; a mismatch is the warning
+.Sy NL.W0705 .
+.It
+A declaration id is unique within its keyword in one file
+.Pq Sy NL.E0907 .
+.Sy non-working
+and
+.Sy working
+do not share a namespace.
 .El
 .Ss Roadmap start property
 .Bl -bullet -offset indent -compact
@@ -1612,7 +2178,112 @@ both absent or both present with identical values.
 A mismatch is an error reported on the parent's
 .Sy include
 line.
+.It
+For any
+.Sy include
+whose
+.Sy roadmap:
+mode is not
+.Sy ignore ,
+a participating child (one that declares a roadmap, swimlanes, or
+waves) must declare the same waves, in the same order, with the same
+resolved start floors, as the parent
+.Pq Sy NL.E0202 .
+A differing title or other presentation is the warning
+.Sy NL.W0701 .
+.It
+On
+.Sy config:merge ,
+a
+.Sy non-working
+or
+.Sy working
+declaration collides only with a parent declaration of the same keyword
+and name, and the parent wins with a warning; unnamed declarations
+never collide.
 .El
+.Ss Waves
+These rules apply to files that use
+.Sy wave
+or
+.Sy wave: .
+Each has a stable diagnostic code.
+.Bl -tag -width "NL.E1100" -offset indent -compact
+.It Sy NL.E1100
+A
+.Sy wave
+declaration has no identifier.
+.It Sy NL.E1101
+A
+.Sy wave:
+value is not exactly one wave declared earlier: a list of two or
+more, an undeclared id, a forward reference, or an id of another
+kind.
+.It Sy NL.E1102
+A descendant's
+.Sy wave:
+differs from its container's.
+.It Sy NL.E1103
+The wave order cannot be realized: some work would have to start at
+or after the end of its own wave, because of lane order, a
+.Sy parallel
+join, or an
+.Sy after:
+that names the item's own wave, a later wave, or work in a later wave
+(directly or through a chain of other work).
+.It Sy NL.E1104
+.Sy wave:
+on a swimlane, a milestone, or any entity other than item, group,
+or parallel.
+.It Sy NL.E1105
+A key that is not allowed on a wave
+.Po
+.Sy before: , date: , start: , length: , duration: , size: ,
+.Sy capacity: , remaining: , wave:
+.Pc .
+.It Sy NL.E1106
+A wave's
+.Sy after:
+names something other than an anchor, a dated milestone, or one ISO
+date.
+.It Sy NL.W1100
+A
+.Sy before:
+that the wave structure guarantees can never be met.
+.It Sy NL.W1101
+An
+.Sy after:
+or
+.Sy before:
+that layout ignores in a roadmap with waves: a forward reference, a
+reference to the enclosing group or parallel, or a reference to a
+floating milestone.
+.It Sy NL.W0702
+.Sy wave:
+(including on a
+.Sy default
+line) in a roadmap that declares no waves; the key is ignored.
+.El
+.Pp
+Include agreement is
+.Sy NL.E0202
+and
+.Sy NL.W0701
+(see
+.Sx INCLUDES ) .
+Layout adds four insights:
+.Sy NL.W1002
+(the barrier solver did not settle),
+.Sy NL.I1006
+(waves with no items),
+.Sy NL.I1007
+(a wave overruns a dated milestone whose
+.Sy after:
+names it), and
+.Sy NL.I1008
+(an item whose
+.Sy after:
+date falls on a non-working day starts on the next working day).
 .Ss Parallel and group
 .Bl -bullet -offset indent -compact
 .It
@@ -1655,22 +2326,45 @@ A
 that sets a banned property
 .Pq see Sx CONFIG SECTION
 is an error.
+.It
+.Sy wave
+is banned on every
+.Sy default <entity>
+line: an error when the roadmap has waves, the warning
+.Sy NL.W0702
+when it has none.
 .El
 .Ss Symbols
 .Bl -bullet -offset indent -compact
 .It
 Every
 .Sy symbol
-declaration must specify a non-empty
-.Sy unicode:"<string>" .
+declaration must specify
+.Sy unicode:"<string>"
+.Pq Sy NL.E0806 ,
+and it must be non-empty
+.Pq Sy NL.E0807 .
 .It
 .Sy ascii: ,
 if present, must be a quoted string of length \(<= 3 ASCII
-characters.
+characters
+.Pq Sy NL.E0808 .
 .It
 A
 .Sy symbol
-id must not shadow a built-in icon name.
+takes only
+.Sy unicode: , ascii: , link: ,
+and
+.Sy description: ;
+any other property is
+.Sy NL.E0809 .
+.It
+A
+.Sy symbol
+id must not shadow a built-in icon name
+.Pq Sy NL.E0805
+and must be unique in the file
+.Pq Sy NL.E0810 .
 .It
 A
 .Sy symbol
@@ -1678,8 +2372,10 @@ reference
 .Pq Sy icon:NAME or Sy capacity-icon:NAME
 must resolve to a built-in or an earlier
 .Sy symbol
-declaration.
-Forward references are an error.
+declaration
+.Pq Sy NL.E0811 .
+Forward references are an error
+.Pq Sy NL.E0812 .
 .El
 .Sh EXAMPLES
 A complete
@@ -1766,6 +2462,38 @@ footnote "Vendor dependency" on:audit-log
 footnote capacity-risk "Team capacity risk" on:[mobile, platform]
   description "Mobile team is down to 2 engineers through Q2."
 .Ed
+.Pp
+A compact roadmap with waves:
+.Bd -literal -offset indent
+nowline v1
+
+roadmap checkout-relaunch "Checkout relaunch" \e
+    start:2026-01-05 scale:1w calendar:full
+
+wave foundations "Foundations"
+wave build "Build"
+wave launch "Launch"
+
+swimlane platform "Platform"
+  item auth "Auth service split" duration:4w wave:foundations
+  item payments-api "Payments API v2" duration:8w wave:build
+  item rate-limits "Rate limits" duration:2w wave:launch
+
+swimlane web "Web"
+  item ux-research "Checkout UX research" duration:2w \e
+    wave:foundations
+  group wave:build
+    item checkout-v2 "Checkout v2" duration:4w
+    item a11y "Accessibility pass" duration:2w
+  item launch-page "Launch page" duration:2w wave:launch
+
+// No wave: background work, never held by a barrier.
+swimlane ops "Ops"
+  item on-call "On-call and KTLO" duration:18w
+
+milestone beta "Beta" after:build
+milestone ga "GA" after:launch
+.Ed
 .Sh SEE ALSO
 .Xr nowline 1
 .Pq Sy man 1 nowline