`visualization`

A visualization of a work system. The kind in use today is board — a Kanban-style board defined with the Board DSL and rendered live.

Serialized type: visualization

Frontmatter

Field	Required	Format	Meaning
`type`	yes	`visualization`	Entity type
`visualization-type`	yes	`board`	The kind of visualization (the `<base>-type` discriminator)
`title`	no	string	Board title
`visualization-of` / `visualization_of`	no	wikilink	The work system this board renders

Plus the shared optionals from conventions.

Relationships

visualization-of — the work system the board belongs to.

Body — the `board` DSL

The body holds one ```dwsd.board fenced block. The board DSL is plain YAML — every modifier is a spelled-out key, there is no inline sugar (no #status suffix, no [wip] brackets, no bare-modifier line). A viewer that recognizes the dwsd.board fence id renders it live; in plain Markdown the same block still reads as a YAML document.

Board header fields (all optional):

Field	Shape	Meaning
`title`	string	The board name (the shared document header; the old `board:` key is retired — a hard error)
`flightlevel`	`FL1` \| `FL2` \| `FL3`	The band the board sits in
`timebox`	string (e.g. `5d`)	The cadence/timebox
`aging`	string (e.g. `3d`)	Board-level aging duration
`tags`	string list	Descriptive category chips (rendered visibly; no color)
`agreements`	string \| string list	Working agreements — inline rule, or `[[wikilink]]` to an entity
`interactions`	string \| string list	Meeting / interaction pointers
`columns`	list	The columns (see below)
`lanes`	list	The swimlanes (see below)
`groups`	list	Group blocks banding columns together (see below)

Columns — each entry is a bare name (- Backlog) or an object:

name — the column name.
status-category — one of to-do in-progress done waiting assess (sets the header tint). There is no blocked — a stuck column is waiting.
wip — a number (the max) or [min, max].
aging — duration string, e.g. 3d. max-returns — escalation threshold.
check — a Definition-of-Done string. tags — descriptive chips.
agreements / interactions — inside-out declarations on the column (see below).
split — { direction?: horizontal, of: [ {name, status-category?, wip?, …} ] }.
group — back-reference to a group (a string, or a path array for nested groups).

Lanes — each entry is a bare name (a named lane) or an object with name, an explicit type (named | assignee | expedite), and optional wip (a single number binds both min and max), status-category, tags, agreements, interactions, and lane-local columns / groups. Lanes are not bound to a flight-item-type; a “swimlane per item type” is just a named lane named after the type.

Groups — each entry is an object with a required name and any of columns, lanes and groups (its children, by kind), plus optional agreements, interactions, tags and status-category (a lozenge on the group band, from the same closed set as columns). Groups nest at most three deep. The word groups: means something different at each scope: at board level it bands board columns; at lane level it is part of the lane’s children; inside a group it holds sub-groups.

Locators into a group. A group that only bands columns is flattened: its columns become board columns that remember their group, so col:Name reaches them directly. A group that hosts lanes is a real container and appears in the path, e.g. group:Delivery/lane:Bob/col:Review. Inside a lane the same holds: lane:Feature/group:Preparation/col:Program Backlog. A lane:L/col:C path that meets a board-wide column resolves to that lane × column cell — write the path, the cell is what the resolver returns.

Inside-out / outside-in. A board node can reach outward with inline agreements: / interactions: (the inside-out direction — terse relationships that live and die with the board). External entities (an interaction/agreement/meeting file) point into a board position with a locator in their interaction-of: / agreement-of: (the outside-in direction). Both render through one surface; when both target the same position they blend with a provenance badge.

Example

---
type: visualization
visualization-type: board
title: "3P FL2 Coordination"
visualization-of: "[[3P]]"
---

```dwsd.board
title: 3P FL2 Coordination
flightlevel: FL2
agreements:
  - "[[Team Working Agreements]]"
  - "WIP per lane: 3"
columns:
  - Backlog
  - name: Selected
    status-category: to-do
  - name: In-Progress
    wip: 3
    status-category: in-progress
    agreements:
      - "Pull only when a slot frees up"
  - name: Review
    status-category: assess
  - name: Done
    status-category: done
```

Reading it

The question: how does work move through this work system, and what applies at which column?
Look first: visualization-of, then the dwsd.board fence: columns left to right, with their status-category, wip and check.
Go next: up via visualization-of to the work system; the [[…]] entries in inline agreements: / interactions: to their files.
Backlinks: the interactions, agreements and AI agents whose locator names this board (outside-in), including rows of meeting tables; the flight routes that bind a band to it in bound-to:.
Pictured in: the board itself. Inside-out and outside-in anchors render on the same surface; where both meet one position they blend with a provenance badge.

Notes

board is the only visualization kind so far; the type is general enough to host other view kinds later via additional visualization-type values.
The parser is tolerant: unknown or malformed fields produce a board.* diagnostic and a clamp/skip rather than an error.

Like what you see? → Start — build your own org folder in ~2 min

# `visualization`

> A visualization of a work system. The kind in use today is **`board`** — a
> Kanban-style board defined with the Board DSL and rendered live.

**Serialized `type`:** `visualization`

## Frontmatter

| Field | Required | Format | Meaning |
|---|---|---|---|
| `type` | yes | `visualization` | Entity type |
| `visualization-type` | yes | `board` | The kind of visualization (the `<base>-type` discriminator) |
| `title` | no | string | Board title |
| `visualization-of` / `visualization_of` | no | wikilink | The work system this board renders |

Plus the shared optionals from [conventions](../conventions.md).

## Relationships

- **`visualization-of`** — the work system the board belongs to.

## Body — the `board` DSL

The body holds one ```` ```dwsd.board ```` fenced block. The board DSL is **plain YAML** —
every modifier is a spelled-out key, there is **no inline sugar** (no `#status` suffix, no
`[wip]` brackets, no bare-modifier line). A viewer that recognizes the `dwsd.board` fence id
renders it live; in plain Markdown the same block still reads as a YAML document.

**Board header fields** (all optional):

| Field | Shape | Meaning |
|---|---|---|
| `title` | string | The board name (the shared document header; the old `board:` key is retired — a hard error) |
| `flightlevel` | `FL1` \| `FL2` \| `FL3` | The band the board sits in |
| `timebox` | string (e.g. `5d`) | The cadence/timebox |
| `aging` | string (e.g. `3d`) | Board-level aging duration |
| `tags` | string list | Descriptive category chips (rendered visibly; no color) |
| `agreements` | string \| string list | Working agreements — inline rule, or `[[wikilink]]` to an entity |
| `interactions` | string \| string list | Meeting / interaction pointers |
| `columns` | list | The columns (see below) |
| `lanes` | list | The swimlanes (see below) |
| `groups` | list | Group blocks banding columns together (see below) |

**Columns** — each entry is a bare name (`- Backlog`) or an object:

- `name` — the column name.
- `status-category` — one of `to-do` `in-progress` `done` `waiting` `assess` (sets the
  header tint). There is **no `blocked`** — a stuck column is `waiting`.
- `wip` — a number (the **max**) or `[min, max]`.
- `aging` — duration string, e.g. `3d`. `max-returns` — escalation threshold.
- `check` — a Definition-of-Done string. `tags` — descriptive chips.
- `agreements` / `interactions` — **inside-out** declarations on the column (see below).
- `split` — `{ direction?: horizontal, of: [ {name, status-category?, wip?, …} ] }`.
- `group` — back-reference to a group (a string, or a path array for nested groups).

**Lanes** — each entry is a bare name (a `named` lane) or an object with `name`, an explicit
`type` (`named` \| `assignee` \| `expedite`), and optional `wip` (a single number binds
**both** min and max), `status-category`, `tags`, `agreements`, `interactions`, and
lane-local `columns` / `groups`. Lanes are **not** bound to a flight-item-type; a
"swimlane per item type" is just a `named` lane named after the type.

**Groups** — each entry is an object with a required `name` and any of `columns`,
`lanes` and `groups` (its children, by kind), plus optional `agreements`, `interactions`,
`tags` and `status-category` (a lozenge on the group band, from the same closed set as
columns). Groups nest at most **three** deep. The word `groups:` means something different
at each scope: at **board level** it bands board columns; at **lane level** it is part of
the lane's children; inside a **group** it holds sub-groups.

**Locators into a group.** A group that only bands columns is flattened: its columns
become board columns that remember their group, so `col:Name` reaches them directly. A
group that hosts lanes is a real container and appears in the path, e.g.
`group:Delivery/lane:Bob/col:Review`. Inside a lane the same holds:
`lane:Feature/group:Preparation/col:Program Backlog`. A `lane:L/col:C` path that meets a
board-wide column resolves to that lane × column cell — write the path, the cell is what
the resolver returns.

**Inside-out / outside-in.** A board node can reach *outward* with inline `agreements:` /
`interactions:` (the **inside-out** direction — terse relationships that live and die with
the board). External entities (an interaction/agreement/meeting file) point *into* a board
position with a [locator](../conventions.md) in their `interaction-of:` / `agreement-of:`
(the **outside-in** direction). Both render through one surface; when both target the same
position they blend with a provenance badge.

## Example

````markdown
---
type: visualization
visualization-type: board
title: "3P FL2 Coordination"
visualization-of: "[[3P]]"
---

```dwsd.board
title: 3P FL2 Coordination
flightlevel: FL2
agreements:
  - "[[Team Working Agreements]]"
  - "WIP per lane: 3"
columns:
  - Backlog
  - name: Selected
    status-category: to-do
  - name: In-Progress
    wip: 3
    status-category: in-progress
    agreements:
      - "Pull only when a slot frees up"
  - name: Review
    status-category: assess
  - name: Done
    status-category: done
```
````

## Reading it

- **The question:** how does work move through this work system, and what applies at which
  column?
- **Look first:** `visualization-of`, then the `dwsd.board` fence: columns left to right,
  with their `status-category`, `wip` and `check`.
- **Go next:** up via `visualization-of` to the work system; the `[[…]]` entries in inline
  `agreements:` / `interactions:` to their files.
- **Backlinks:** the interactions, agreements and AI agents whose locator names this board
  (outside-in), including rows of meeting tables; the flight routes
  that bind a band to it in `bound-to:`.
- **Pictured in:** the board itself. Inside-out and outside-in anchors render on the same
  surface; where both meet one position they blend with a provenance badge.

## Notes

- `board` is the only visualization kind so far; the type is general enough to host other
  view kinds later via additional `visualization-type` values.
- The parser is tolerant: unknown or malformed fields produce a `board.*` diagnostic and a
  clamp/skip rather than an error.

visualization