# 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.

```bash
# 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

```bash
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:

- `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

```bash
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.

### Board in the checkout

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

### Board on its own branch

```yaml
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](/docs/guides/live).

## 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](/).

```yaml
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: /`.

## Next

- **[Operating a board](/docs/guides/agents)**: The session protocol an agent follows.

- **[CLI reference](/docs/reference/cli)**: Every command, what it writes and its commit.

- **[Board formats](/docs/reference/formats)**: The card schema and the validation rules.