mdBoard

Configuration

The board is configured by mdboard.toml at the repository root. mdboard init writes a working preset and prompts for the human-owned choices.

This reference describes the 1.0 alpha configuration.

Minimal configuration

mdboard = "1.0.00"
schema = 2

[git]
remote = "origin"
stable = "stable"
nightly = "nightly"
upstream = "upstream"

[limits]
roadmap = 5

[approval]
mode = "chat"

[meetings]
consortium = "weekly"
release = "biweekly"

[costs]
subscription = "unspecified payment model"
eur_per_million_tokens = 4.96

Configuration is limited to branches, the roadmap limit, approval, meetings, costs and plugins.

init writes mdboard = "1.0.00" and schema = 2. The schema number is the contract to check; the display version is informational.

[git]

Key Meaning
remote Default remote for fetch/status operations
stable Released branch
nightly Integration branch for accepted upstream iterations
upstream The one active working branch

The three branch names must be non-empty and distinct. The agent writes only upstream; the owner merges upstream → nightly and releases nightly → stable.

[limits]

Key Meaning Default
roadmap Maximum number of batches in the roadmap 5

The roadmap limit must be greater than zero. A temporary override is stored in .mdboard/roadmap-override.md:

limit: 8
reason: "Release crunch for CSV export"
approved_by: owner
expires_at: 2026-11-01T00:00:00Z

An expired override fails check until the owner renews or clears it.

[approval]

[approval]
mode = "chat"

chat is the v1 mode: the agent records the human’s statement and authorised_by in the event. It is an audit convention, not cryptographic proof. See Security.

[meetings]

[meetings]
consortium = "weekly"
release = "biweekly"
Value Meaning
weekly Fixed weekly cadence
biweekly Every two weeks
monthly Fixed monthly cadence
on-demand No fixed cadence; gates appear when triggered

The consortium meeting is the fixed pitch/roadmap review. The release meeting is the fixed nightly → stable train. Breakdown clarification, handover review and recovery are on-demand records.

[costs]

[costs]
subscription = "unspecified payment model"
eur_per_million_tokens = 4.96
Key Meaning Default
subscription Label shown beside cost estimates unspecified payment model
eur_per_million_tokens Blended EUR cost for one million tokens 4.96

The rate is blended across input and output for the expected usage mix. It is not a plain average. See Estimation and cost for examples and the blended-rate guidance.

Actors

.mdboard/actors.toml:

[actors.owner]
kind = "human"
display_name = "Owner"
roles = ["owner"]

[actors.member]
kind = "human"
display_name = "Product member"
roles = ["member"]

[actors.agent]
kind = "agent"
display_name = "Coding agent"
roles = ["agent"]
  • owner — final human authority and branch operations.
  • member — spark, refine, pitch, review.
  • agent — the one writer and operator.

Do not configure two concurrent agent writers on one upstream iteration.

Roadmap override

.mdboard/roadmap-override.md is owner-only. It carries limit, reason, approved_by and expires_at. The effective roadmap limit is the override while active, otherwise [limits].roadmap.

Validation

Ask the agent to run:

mdboard check

Typical configuration failures:

  • branch names empty or duplicated;
  • roadmap limit zero;
  • cost subscription empty;
  • negative or non-finite token rate;
  • an expired roadmap override;
  • a missing or invalid actor.

Changing configuration

Most changes are human-owned:

  1. ask the agent what the change affects;
  2. edit mdboard.toml or use the init/override command;
  3. run mdboard check and regenerate the views;
  4. commit the change on upstream.

Do not edit generated views to “fix” a configuration problem.

Next