Lettuce Documentation

Welcome to Lettuce — a native macOS Markdown vault with first-class support for AI agents. This is the same documentation that ships with the app — the Lettuce Docs section pinned at the bottom of the sidebar — and that’s published at https://lettuce.drbaher.com/docs/.

Getting started

• Getting started/01 Install - download the DMG, what gets installed, where files live

• Getting started/02 Your first vault - pick a folder, create a note, save

• Getting started/03 Your first agent connection - pair Claude Desktop / Code with Lettuce

• Getting started/04 App tour - sidebar, editor, inspector, command palette

• Getting started/05 Keyboard shortcuts - every binding worth memorising

• Getting started/06 Migrating from another app - bring notes over from Obsidian, Bear, Notion, Evernote, Apple Notes, and more

• Getting started/07 Lettuce on iPhone (preview) - companion iOS app + connecting to your Mac

Core concepts

• Core concepts/01 Vault structure - what a vault is, what’s tracked, what isn’t

• Core concepts/02 The .lettuce directory - order.json, triggers.yml, schedules.yml, proposals/

• Core concepts/03 Frontmatter - YAML keys Lettuce recognises

• Core concepts/04 Wikilinks, backlinks, and the graph - [[name]], the link index, the graph view

• Core concepts/05 Tags - #tag syntax, nested tags, tag pages

• Core concepts/06 Callouts - > [!note], > [!warning], custom callouts

• Core concepts/07 Footnotes - [^1] syntax and rendering

• Core concepts/08 Mermaid and KaTeX - diagrams and math

• Core concepts/09 Block IDs and references - ^block-id, [[note#^id]]

• Core concepts/10 Tasks and to-dos - checkboxes, tasks blocks, the dashboard, quick add

• Core concepts/11 Calendar and meetings - mirror your calendar, meeting prep, the Today note

• Core concepts/12 Backups and version history - snapshot .zips, Git history, per-note versions

• Core concepts/13 Templates - Insert Template, placeholders, the starter pack

• Core concepts/14 AI actions - the ⌘⇧K palette, built-ins, your own custom actions

LLM wiki

• LLM wiki/01 The pattern - the LLM-maintained, compounding knowledge base: three layers + ingest/query/lint

• LLM wiki/02 Worked example - building one end to end with the real commands and MCP tools

Working with AI agents

• Agent reference/01 Overview - what agents can do in Lettuce, the trust model

• Agent reference/02 MCP transport - how the JSON-RPC channel is wired up

• Agent reference/03 Authentication - vault tokens, scoped keys, propose-only mode

• Agent reference/04 Read tools - list_notes, read_note, search, read_outline, link_graph, list_attachments, read_attachment, lint, lint_semantic, suggest_tags

• Agent reference/05 Write tools - write_note, patch_section, apply_edits, file_page, move_note, delete_note

• Agent reference/06 Suggestion tools - list_my_proposals, withdraw_proposal, complete_directive

• Agent reference/07 Concurrency and soft-locks - what happens when two agents touch the same note

• Agent reference/08 Errors and rate limits - error shapes, retry guidance

• Agent reference/09 AGENTS.md - onboarding agents to your vault’s conventions

• Agent reference/10 REST API - the same surface over HTTP, with curl examples

• Agent reference/11 Agent inbox and edit timeline - what changed while you were away, and reverting it

Vault automation

• Vault automation/01 Triggers - fire actions on note events (created, saved, tagged, …)

• Vault automation/02 Schedules - cron-like recurring agent runs

• Vault automation/03 Testing automations - dry-run, replay, log inspection

• Vault automation/04 Sample patterns - daily digests, inbox processors, link healers

• Vault automation/05 Plain-English automations - describe an automation in plain English

Suggestions mode

• Suggestions mode/01 Overview - what propose-only looks like, why use it

• Suggestions mode/02 Onboarding - switching an existing agent to propose-only

• Suggestions mode/03 The proposals UI - review, accept, reject, diff

• Suggestions mode/04 Staleness and conflicts - what happens when the base note changes

• Suggestions mode/05 Multi-agent queues - many agents proposing into one vault

• Suggestions mode/06 Withdraw and ownership - agents managing their own proposals

Publishing

• Publishing/01 Publishing a note - published: true, where it lands

• Publishing/02 The static site - what gets generated, theming

• Publishing/03 Deploying - GitHub Pages, Vercel, plain S3

• Publishing/04 Export to PDF, Word, and ePub - one note or a whole group as a single document

CLI cookbook

• CLI cookbook/00 Overview - the lettuce binary, conventions, global flags

• CLI cookbook/01 lettuce serve - run the local MCP/REST server

• CLI cookbook/02 lettuce render - render a single .md to HTML

• CLI cookbook/03 lettuce publish - build the static site from your vault

• CLI cookbook/04 lettuce deploy - push the built site to gh-pages

• CLI cookbook/05 lettuce serve-site - preview the published site locally

• CLI cookbook/06 lettuce docs - manage the in-app documentation vault

• CLI cookbook/07 lettuce wiki - scaffold an LLM wiki (init [--agents])

• CLI cookbook/08 lettuce keys - manage API keys and vault tokens

• CLI cookbook/09 lettuce mcp - inspect/test the MCP tool surface from the shell (curl)

• CLI cookbook/10 lettuce search - full-text search (phrase / OR / NOT operators)

• CLI cookbook/11 lettuce export - exporting & sharing notes (via publish)

• CLI cookbook/12 lettuce import - migrate notes in from another app

• CLI cookbook/13 lettuce directive-worker - headless worker that answers [!ai] directives

• CLI cookbook/14 lettuce backup and restore - snapshots, retention, safe restore

• CLI cookbook/15 lettuce digest and process-inbox - run the morning digest and inbox pass on demand

AI providers

• AI providers/01 Anthropic Claude - the recommended default

• AI providers/02 OpenAI - GPT-4/5 family, function calling

• AI providers/03 Google Gemini - Gemini models

• AI providers/04 OpenAI-compatible and local models - Ollama, LM Studio, vLLM

• AI providers/05 Claude Code (subscription) - your Claude plan, no API key

Recipes

• Recipes/01 Daily triage agent - sort the inbox at 7am

• Recipes/02 Research assistant - fetch and summarise URLs into notes

• Recipes/03 Tag curator - keep the tag namespace clean

• Recipes/04 Meeting capture - turn raw transcripts into structured notes

• Recipes/05 Reading list ingest - capture from RSS / Pocket / Instapaper

• Recipes/06 Project status tracker - weekly rollups across project notes

• Recipes/07 Book notes - structured book summaries with quote extraction

• Recipes/08 Code journal - daily engineering log

• Recipes/09 Weekly review - GTD-style review built from frontmatter

• Recipes/10 Customer support KB - turn tickets into shareable docs

• Recipes/11 Personal CRM - relationships, last-touched, follow-ups

• Recipes/12 Learning in public - TIL stream that auto-publishes

• Recipes/13 Save Claude’s work into your vault - file notes and HTML artifacts from chat

• LLM wiki/01 The pattern - scaffold, connect an agent, ingest, and let the vault compound

Troubleshooting

• Troubleshooting/01 Agent edits not appearing - most common cause is suggestions mode

• Troubleshooting/02 Proposals tab is empty - check the agent token’s scope

• Troubleshooting/03 Publish failed - git credentials, gh-pages branch, file size

• Troubleshooting/04 Keychain reset - clearing stuck tokens and API keys

• Troubleshooting/05 Notarization and Gatekeeper - when macOS blocks the app

• Troubleshooting/06 Can’t reach your Mac - iPhone Mac Tools show offline

For developers

• For developers/01 Building from source - SwiftPM, Xcode, the run.sh script

• For developers/02 Test suite tour - what each target covers

• For developers/03 Contributing - branch hygiene, commit style

• For developers/04 Architecture map - modules, dependency direction

• For developers/05 Renderer internals - how Markdown becomes HTML

• For developers/06 Writing a new MCP tool - end-to-end walkthrough