CLAUDE.md — folio

1# Folio Development Guide

Markdown-native knowledge and project management system exposed as an MCP server. All state stored as structured markdown files.

5## Build

7Uses `sigil build` with `--redirects` to resolve dependencies from the local sigil workspace:

9```bash

10sigil build --redirects dev-redirects.sgl

11```

The `dev-redirects.sgl` file maps Sigil ecosystem dependencies to the local sigil worktree. Without it, the build fetches from remote repos.

15## Test

17Build first, then run tests with `-L build/dev/lib` so the test runner finds compiled modules:

19```bash

20sigil build --redirects dev-redirects.sgl

21sigil -L build/dev/lib test --redirects dev-redirects.sgl

22```

24## Run

26The MCP server reads `FOLIO_ROOT` to find the folio data directory:

28```bash

29FOLIO_ROOT=~/folio ./build/dev/bin/folio

30```

32For Claude Code integration, add to `.mcp.json`:

34```json

35{

36 "mcpServers": {

37 "folio": {

38 "command": "./build/dev/bin/folio",

39 "env": {

40 "FOLIO_ROOT": "/home/daviwil/folio"

41 }

42 }

43 }

44}

45```

47## Architecture

49- `(folio store)` -- Folio root directory management and file discovery

50- `(folio frontmatter)` -- YAML frontmatter read/write via `(sigil yaml)`

51- `(folio task)` -- Task struct, parsing `- [ ] text {key: val}` lines

52- `(folio id)` -- Short task ID generation (`t-xxxx`)

53- `(folio inbox)` -- Inbox read/add/remove operations

54- `(folio tools)` -- MCP tool schemas, handlers, registration

55- `(folio main)` -- Entry point: reads FOLIO_ROOT, starts MCP server

57## Conventions

59- Task metadata uses `{key: val, key: val}` suffix -- commas separate fields

60- Tags are space-separated within metadata (not comma-separated, since commas are the field separator)

61- Task IDs are `t-` followed by 4 random hex chars, stored in metadata as `id: t-xxxx`

62- Frontmatter uses full YAML via `(sigil yaml)`, not the markdown parser's simple frontmatter

63- All file writes bump the `last-updated` frontmatter field to today's date