Folio Development Guide

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

Build

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

sigil build --redirects dev-redirects.sgl

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

Test

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

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

Run

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

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

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

{
  "mcpServers": {
    "folio": {
      "command": "./build/dev/bin/folio",
      "env": {
        "FOLIO_ROOT": "/home/daviwil/folio"
      }
    }
  }
}

Architecture

• (folio store) -- Folio root directory management and file discovery
• (folio frontmatter) -- YAML frontmatter read/write via (sigil yaml)
• (folio task) -- Task struct, parsing - [ ] text {key: val} lines
• (folio id) -- Short task ID generation (t-xxxx)
• (folio inbox) -- Inbox read/add/remove operations
• (folio tools) -- MCP tool schemas, handlers, registration
• (folio main) -- Entry point: reads FOLIO_ROOT, starts MCP server

Conventions

• Task metadata uses {key: val, key: val} suffix -- commas separate fields
• Tags are space-separated within metadata (not comma-separated, since commas are the field separator)
• Task IDs are t- followed by 4 random hex chars, stored in metadata as id: t-xxxx
• Frontmatter uses full YAML via (sigil yaml), not the markdown parser's simple frontmatter
• All file writes bump the last-updated frontmatter field to today's date