folio

folio turns your coding agent into the librarian of a knowledge library: fast, good-looking HTML pages and Markdown records that live inside any project (lab notes, study notes, a project's docs) or stand on their own. Every document has one genre, and the genre fixes its job, its voice, its format and its checks. Documents link to each other like a Zettelkasten, and maps give a reader the way in.

You do not run folio yourself. You install it by handing your agent a setup prompt, and from then on you ask in plain words: "add a concept for X", "tidy the maps", "go through my comments", "build the site". The agent follows folio's seven skills, calls the folio command, and runs the gate before every commit. folio is the method and the checks that keep an agent-written library honest and consistent, plus the shell that makes it pleasant to read.

Install

Paste this into your coding agent, in the project where the library should live:

Install folio here: run `uv tool install folio-kb` (or `pipx install folio-kb`), then `folio init`, then read .agents/skills/set-up/SKILL.md and follow it.

The agent asks you at most three questions in one message (what the library is for, where it lives, which packs to switch on), creates the library and leaves the gate passing. A longer version of the prompt is in SETUP.md. folio needs Python 3.10 or later.

What a library looks like

A library is a folder with a folio.yaml. It can be a project's docs/, a notes folder, or a whole repository.

docs/
  folio.yaml            the charter: name, purpose, reader, packs, home maps
  content/
    index.html          the home page
    concepts/<slug>/    one folder per genre
    maps/
    journal/2026/       one Markdown file per entry
  assets/               figures, refs.bib, data
  .folio/               generated indices, committed and checked
.agents/skills/         the seven skills, at the project root

Each document keeps its facts in metadata and its prose in the body. The shell draws the header and the link panels from the metadata and the generated indices, so nothing is written twice.

Pages are plain HTML in git, readable with no build step. folio serve shows them locally with search, link previews, concept popovers, light and dark themes, and a comment panel; folio export writes a static site.

Hover a link to preview the document it points to; hover a concept to read its definition without leaving the page. Readers can also comment on any rendered page, and the agent answers on the page itself.

Genres and packs

A pack is switched on in the charter and rewrites nothing. A library can override a genre, add a variant for a second audience, or add genres, workflows and packs of its own.

The seven skills

The gate

folio check     # every problem in one pass; changes nothing; exit 0 only when there is no error

It runs offline, and CI runs the same command. It checks that every link resolves, every document meets its genre's card, no placeholder is left, records that must never change have not changed, nothing is orphaned, one fact keeps one home, and the generated indices are current.

Learn more

• Documentation: pierg.github.io/folio. It is itself a folio library, kept in docs/, with a guide, the concepts, and a worked example from each pack.
• The specification: docs/spec/. model.md is the contract the rest builds on; when anything disagrees with it, it wins.
• Contributing: CONTRIBUTING.md. Changes: CHANGELOG.md.

License

MIT. See LICENSE.