# Introduction
Folio Board is the project board that lives in your repository, powered by
[Folio](https://pguijas.github.io/folio/): one Markdown file per card,
versioned in git, read and edited the same way by people and coding agents,
and published with the rest of your documentation.
## Built for agents first
A card is a file an agent reads and edits like any other file in the checkout.
The `SKILL.md` beside the board teaches it the protocol, and the CLI checks
each change and can record it as one narrow commit. People work the same files,
from the CLI, an editor, code review or the kanban.
`board.yaml` declares the columns and their limits, each file in `cards/` is
one card, and `agents.yaml` tells the CLI where the board is.
> **Check:** the tree above reads as if the board shared the code's branch.
> It does not have to: `init` creates a separate `board` branch by default,
> `kanban.ref` publishes a board from another branch through a managed
> worktree ([Boards on another branch](/docs/reference/formats#boards-on-another-branch)),
> and a board in another repository is an idea (`board.store`, read by
> nothing yet). This section and its tree need rewriting to say where a board
> can live.
Folio Board orchestrates none of the agents you already use, such as Codex
and Claude Code: each reads the same cards and follows the same protocol.
## Powered by Folio
The board runs on Folio, the documentation engine. One `kanban:` section in
`docs.yaml` puts the board on your docs site, and the site brings the rest.
- **[One site with your docs](/docs/quickstart#optional-visual-canvas)**: The kanban is a page of your Folio site, built and deployed with it, on the site's theme.
- **[Folio components in cards](/docs/reference/board-component#folio-components-in-card-descriptions)**: Card descriptions render tabs, callouts, diagrams and your own registered components.
- **[Milestones on the roadmap](/roadmap)**: A card's milestone resolves against the site's roadmap phases, and each release links to its cards.
- **[A landing at the root](/docs/quickstart#a-landing-page-at-the-site-root)**: One key puts Folio Board's own page at the site root, with the install command and the roadmap.
**Folio is optional**
Board commands need no site, server, Node.js runtime or Docs build. Without a
`kanban:` section the canvas stays inert, and the board is files and a CLI.
## Deployed the way you need
The files in git are always the source of truth. The board reaches its
readers in more than one way:
- **[Static](/docs/deployment#static-the-board-as-a-published-page)**: A read-only kanban published with your docs. A drag stages a move and exports the commands. Ships.
- **[Local](/docs/guides/live)**: A board server on loopback, and the same page edits cards, one commit per save. Ships.
- **[Hosted](/docs/deployment/deploy)**: The kanban on GitHub Pages and the server on Render: a team edits from the browser, each under their own name. Ships.
## The canvas
The board below is live: it is the example board this site publishes, rendered
by the `KanbanBoard` component from the files in the tabs under it. The full
canvas, with filters and the card reader, is at [/kanban](/kanban).
**The example board, embedded in this page**
```mdx
```
### docs.yaml
```yaml
kanban:
source: fixtures/board/board
landing: true
routes:
public: "/board"
docs: false
```
### board.yaml
```yaml
title: "Fixture Board"
icons:
docs: "📘"
columns:
- id: ideas
title: Ideas
- id: in-progress
title: In progress
limit: 2
- id: done
title: Done
```
### cards/write-the-adapter.md
```markdown
---
title: Write the adapter
status: in-progress
type: feature
size: m
assignee: [ana, bo]
track: rust
parent: plan-the-release
created: 2026-09-05
milestone: "0.1"
order: 10
artifacts:
- doc: report.md
label: Design report
- pr: 42
- url: https://example.com/spec
---
Port the render adapter, one module at a time.
## Acceptance criteria
- [ ] data modules match
- [ ] pages match
## Trail
- 2026-09-05 @bo (abc1234): started the port
```
### cards/ship-the-alpha.md
```markdown
---
title: Ship the alpha
status: done
blocked_by: [write-the-adapter]
created: 2026-09-10
milestone: "0.9"
---
Cut the tag once the adapter lands.
## Comments
- 2026-09-11 @ana: waiting on the adapter.
## Trail
- 2026-09-10 @ana: card created
```
**The canvas never becomes the source of truth**
On a static board, a staged move is exported as a `folio-agents board move`
command, reviewed, and committed to the board branch. On a live board, the
server writes the card file and commits it.
### The card
On the public canvas, clicking a card extends one continuous workspace:
filters, canvas, card, then artifact. Later context opens farther right when
space permits and continues below otherwise. Hairline separators resize each
surface by pointer or keyboard, `Esc` unwinds one level, and the URL restores
the selected card and artifact. Readable artifacts can use native full screen.
Docs embeds keep the modal treatment. The permanent id remains the Markdown
filename, not its screen position.
### Filtering
The canvas accepts one shareable `?q=` expression. Spaces mean AND, commas mean
OR, and a leading minus excludes a term. Fields such as `status`, `priority`,
`tag`, `milestone`, and `assignee` narrow the same board without creating a
second source of truth.
Use the bookmark beside the query to save a named filter, such as
“Review 0.6” for `status:in-review milestone:0.6`. The popup opens, renames
and removes filters. They stay in this browser, separated by board and
signed-in account. Selecting one applies its query to the same shareable URL;
changing the query leaves the saved version intact. No cards change.
### Moving a card
Drag a card or choose a destination in its dialog. On a static board the move
stays in local browser storage until **Export moves** produces the
corresponding `folio-agents board move` commands. **Reset to source** discards
staged moves.
On a live board the drop is the commit: the server writes `status:` and commits
`board: -> `, and **Undo** moves the card back with a second
commit. [Edit the board in the browser](/docs/guides/live) lists every edit a live card
takes.
## What ships today
- **[A cardfile board](/docs/reference/formats)**: board.yaml plus one Markdown file per card, with stable ids, WIP limits and deterministic ordering.
- **[The board CLI](/docs/reference/cli)**: Validated commands to add, move, update, comment on and attach to cards, each optionally one narrow commit.
- **[SKILL.md](/docs/guides/agents)**: The protocol any agent reads before it touches the board, written into the repository by init.
- **[The board server](/docs/reference/api)**: An optional loopback server through which the published kanban edits cards, one commit per save.
`folio-agents board` is the board command of the `folio-agents` binary, which
is Folio Docs' CLI with the board mounted on it. Folio Docs' own `folio` has no
board command; the two install side by side.
## Where to go next
- **[Quickstart](/docs/quickstart)**: Install, board init and daily use.
- **[Guides](/docs/guides)**: The agent session protocol and live editing.
- **[Deployment](/docs/deployment)**: Static, local and the hosted options.
- **[Reference](/docs/reference)**: The CLI, the Board API, the file formats and the kanban component.