README.md — folio

1# Folio

A markdown-native knowledge and project management system, exposed as an MCP server. Folio stores all state as structured markdown files — human-readable, git-committable, and programmatically queryable.

5Built with [Sigil](https://codeberg.org/sigil/sigil).

7## Install

9```bash

10sigil app install codeberg:sigil/folio \

11 --mcp \

12 --env FOLIO_ROOT=~/folio

13```

This installs the `folio` binary, registers it as a user-level MCP server, and points it at `~/folio` as the data directory. The folio directory will be created on first run.

17To install for a specific project instead (registers in the project's `.mcp.json`):

19```bash

20cd ~/my-project

21sigil app install codeberg:sigil/folio \

22 --mcp \

23 --mcp-scope project \

24 --env FOLIO_ROOT=./folio

25```

27Or add to `.mcp.json` manually:

29```json

30{

31 "mcpServers": {

32 "folio": {

33 "command": "folio",

34 "env": {

35 "FOLIO_ROOT": "./folio"

36 }

37 }

38 }

39}

40```

42## What it does

Folio gives AI agents structured access to tasks, projects, and notes through MCP tools. The agent gets clean operations; you get readable markdown files with clean git diffs.

46### Tasks

48Checkbox items with inline metadata:

50```markdown

51- [ ] Add contact lookup tool {id: t-a3f2, priority: high, due: 2026-03-20}

52- [x] Fix reply identity selection {id: t-b1c4, completed: 2026-03-13}

53```

55### Projects

57One markdown file per project in `projects/`, with YAML frontmatter, a task list, and a reverse-chronological log:

59```markdown

60---

61status: active

62goal: Add contact management and improve search

63area: development

64last-updated: 2026-03-13

65---

67# Bureau v2

69## Tasks

71- [ ] Add contact lookup tool {id: t-a3f2, priority: high, due: 2026-03-20}

72- [ ] Improve search result ranking {id: t-b1c4, priority: medium}

74## Log

76### 2026-03-13

78Fixed identity selection for replies. Bureau now auto-detects the

79correct sending identity from the original email's To field.

80```

82### Notes

84Atomic reference notes in `notes/` with `[[crosslinks]]` between them:

86```markdown

87---

88tags:

89 - fastmail

90 - jmap

91created: 2026-03-12

92last-updated: 2026-03-13

93---

95# Fastmail JMAP Quirks

97Fastmail rejects the `#draft` back-reference key in `onSuccessUpdateEmail`.

99## Related

100

101- [[caldav-discovery]] - CalDAV has similar redirect issues

102- [[bureau-send-pipeline]] - Where these quirks manifest

103```

104

105

Notes support subdirectories for organization: `procedures/`, `contacts/`, `preferences/`, etc. Crosslinks resolve across both notes and projects.

106

107### Inbox

108

109A single `inbox.md` for capturing items before they're triaged into projects.

110

111## Directory structure

112

113```

114folio/

115├── inbox.md

116├── projects/

117│ ├── bureau-v2.md

118│ └── sigil-gc.md

119├── notes/

120│ ├── fastmail-jmap-quirks.md

121│ ├── procedures/

122│ │ └── email-triage.md

123│ └── contacts/

124│ └── alice.md

125└── archive/

126 ├── projects/

127 └── notes/

128```

129

130## MCP Tools

131

132### Overview

133

134| Tool | Description |

135|------|-------------|

136| `folio/status` | Dashboard: inbox count, overdue tasks, stale projects, orphaned notes |

137

138### Tasks

139

140| Tool | Description |

141|------|-------------|

142| `folio/tasks` | Query tasks across all projects and inbox with filters |

143| `folio/task-add` | Add a task to a project or inbox |

144| `folio/task-complete` | Mark a task as done |

145| `folio/task-update` | Update task metadata (priority, due, tags, waiting) |

146| `folio/task-move` | Move a task between projects or to inbox |

147

148A task's id is stable: moving it between the inbox and a project, or between

149projects, preserves the id it already had.

150

151### Bulk operations

152

153Triaging a full inbox one call at a time is slow enough that nobody does it

154routinely, which is how an inbox goes months without being triaged.

155

156| Tool | Description |

157|------|-------------|

158| `folio/task-move-batch` | Move many tasks at once, with a result line per id |

159| `folio/task-complete-batch` | Mark many tasks done by id list |

160| `folio/task-sweep` | Remove completed tasks from projects |

161| `folio/inbox-sweep` | Remove completed items from the inbox |

162

163`folio/task-move-batch` takes either one shared target or per-id targets, so a

164single call can fan out across many projects:

165

166```json

167{"ids": ["t-a3f2", "t-b1c4"], "project": "bureau-v2"}

168

169{"moves": [{"id": "t-a3f2", "project": "bureau-v2"},

170 {"id": "t-b1c4", "project": "sigil-gc"},

171 {"id": "t-c5d6"}]}

172```

173

174An entry with no `project` moves that task to the inbox. Every id gets its own

175result line, so a partial failure is visible rather than swallowed.

176

177### Inbox

178

179| Tool | Description |

180|------|-------------|

181| `folio/inbox` | List all inbox items |

182| `folio/inbox-add` | Add an item to the inbox |

183| `folio/inbox-triage` | Move an inbox item to a project |

184

185> **Keep inbox captures to a single line.** An item whose text contains

186> newlines is currently written in a shape folio cannot read back: the

187> `{id: ...}` metadata lands on the item's last line, the parser sees only the

188> first, and the item becomes invisible to every tool while a phantom

189> one-line duplicate takes its place. For anything longer, create a note and

190> reference it from a one-line inbox item. See the Known issues section of

191> CHANGELOG.md.

192

193### Projects

194

195| Tool | Description |

196|------|-------------|

197| `folio/projects` | List projects with task counts |

198| `folio/project-info` | Full project details: tasks and log entries |

199| `folio/project-create` | Create a new project |

200| `folio/project-log` | Add a dated log entry to a project |

201| `folio/project-archive` | Archive a completed project |

202| `folio/project-clean` | Move completed tasks to the project log |

203

204### Notes

205

206| Tool | Description |

207|------|-------------|

208| `folio/notes` | Search notes by text or tag |

209| `folio/note-read` | Read a note's full content |

210| `folio/note-create` | Create a new note |

211| `folio/note-edit` | Replace a note's content |

212| `folio/note-links` | Show outgoing links and backlinks |

213| `folio/note-rename` | Rename a note and update all crosslinks |

214

215## Development

216

217Requires [Sigil](https://codeberg.org/sigil/sigil) v0.9.0+.

218

219```bash

220# Install dependencies

221sigil deps install

222

223# Build

224sigil build

225

226# Test

227sigil test

228

229# Run locally

230FOLIO_ROOT=/tmp/folio ./build/dev/bin/folio

231

232# Build release bundle (standalone binary)

233sigil build --config release

234FOLIO_ROOT=/tmp/folio ./build/release/bin/folio

235```

236

237## License

238

239BSD-3-Clause