Quickstart

Folio Board is complete without a documentation site. The board is a set of files in git and the CLI is its validator and editor.

Install

There is no packaged release yet: both binaries install from source. REPOSITORY is Folio Board’s git URL. The build fetches Folio Docs from its public repository.


# the CLI and the canvas
CARGO_NET_GIT_FETCH_WITH_CLI=true cargo install --locked \
  --git "$REPOSITORY" folio-board --bin folio-agents
# the board server, only to edit the board from the browser
CARGO_NET_GIT_FETCH_WITH_CLI=true cargo install --locked \
  --git "$REPOSITORY" folio-board-server

Folio Docs’ own folio has no board command; the two install side by side.

Start a board


cd your-repository
folio-agents board init
folio-agents board add "Ship the first release"
folio-agents board check

init creates a board branch by default, switches to it, and writes:

your-repository

agents.yaml

board

├── board.yaml

├── SKILL.md

└── cards

├── read-me-first.md

└── _TEMPLATE.md

agents.yaml points the CLI at the board.
board.yaml declares the columns and WIP limits.
Each Markdown file in cards/ is one card. Its status field chooses the column, so unrelated card moves do not contend for one YAML list.
SKILL.md is the repository-owned operating protocol for coding agents.

Work it every day


folio-agents board
folio-agents board move ship-the-first-release in-progress --commit
folio-agents board trail ship-the-first-release --note "release checks pass" --ref abc1234 --commit
folio-agents board move ship-the-first-release done --commit

init refuses rather than overwrites

It stops when the board directory exists, when agents.yaml already has a board: section, when the directory is not a git repository (run git init, or pass --no-branch), or when the branch exists. Use --no-branch only when planning and implementation deliberately share a history. Use --commit to create the initial board: init commit.

Check the board in CI

Run folio-agents board check in CI and before pushing board changes. It checks the same cardfile rules used by every write command.

Optional visual canvas

The browser board is optional; the board commands never need it. It ships in the folio-agents binary built above, so there is nothing more to install. A kanban: section in the Docs project’s docs.yaml activates it.


kanban:
  source: board
  routes:
    public: true
    docs: false


kanban:
  ref: board
  sources:
    docs: folio-docs/board
    agents: folio-agents/board
  routes:
    public: true
    docs: false

Folio creates a detached worktree for the ref without merging the board into the code checkout. Each sources key becomes an independent canvas. A local branch is used when available; CI fetches the branch from origin before creating the worktree.

folio-agents serve now exposes /kanban/; folio-agents build includes the same canvas in the static export. Dragging only stages moves in the browser and exports reviewed folio-agents board move commands. It never writes the repository remotely. To edit the board from the page instead, add kanban.api and run the board server: Edit the board in the browser.

A landing page at the site root

kanban.landing: true puts Folio Board’s own page at /: a hero with the source installation command, three points and the roadmap. This site serves it at the site root.


kanban:
  source: board
  landing: true
  routes:
    public: true      # the kanban at /kanban; the landing links to it

The value is true or false; anything else fails the build.
Without the key, the build writes no page, no component and no file for it.
The roadmap section reads the site’s roadmap: block, the phases a card’s milestone: resolves against, and each release links to its cards. A site without roadmap: drops the section.
The root has one owner. The build refuses the key beside a Docs landing: section and with routes.public: /.

Operating a board

The session protocol an agent follows.

CLI reference

Every command, what it writes and its commit.

Board formats

The card schema and the validation rules.