Local sync file

Link the board to a Markdown file on this computer. Two-way updates, nothing uploaded.

1. What it does

The header Sync file button links the board to a .md file on your machine:

• Checks, new tasks, and renames in the browser are written back after about 1.5 seconds
• Edits from you, a script, or an agent merge into the board when you return to the tab
• Done states only merge forward: the file can check items off, but will not uncheck what you already completed in the UI
• Todos that exist only on the board are kept and written into the file; per-project > note lines (agent commit records) are preserved

2. Requirements

• Chrome, Edge, Brave, or other Chromium browsers. Safari / Firefox do not support the File System Access API
• Brave users: the API is off by default. Open brave://flags/#file-system-access-api, set it to Enabled, relaunch — otherwise only merge-from-file works, not auto write-back
• Open the site over https or localhost (file:// will not work)
• Keep the file in a stable folder, e.g. ~/monoboards/boards.md — not the Downloads folder

3. Get started

1. Click Sync file in the header. The first click shows a short explanation
2. Create a new sync file: pick a location (suggested name boards.md); the current board is written immediately
3. Choose an existing file: pick a previous Markdown export or an agent-maintained file; the board merges first, then write-back starts
4. Authorize once. After that, open or focus the tab to sync. A red button means permission expired — click once to re-grant
5. Right-click the button to unlink (the file is not deleted)

4. Re-link (when read fails)

If you see “Failed to read the sync file”, the saved link in the browser is stale. Follow these steps:

1. Permission expired (red button): left-click Sync file again and allow read/write
2. Read failed: right-click Sync file → confirm unlink
3. Left-click Sync file → Choose an existing file → pick your boards.md again
4. When switching browsers (Chrome ↔ Brave), pick the same file again in the new browser — links are not shared
5. If the .md is gone: use header Export for backup, then Create a new sync file

5. Optional: update via an AI / agent

No extra script to download. Give your coding agent the path to the sync file (e.g. ~/monoboards/boards.md) and have it edit that Markdown directly. Switch back to this tab afterwards to merge.

Format — the name after ## must match the project name on the board exactly:

## My project
> abc123 feat: what this commit did (2026-08-31 12:00)
- [x] Finished task
- [ ] Open task

After each commit, ask the agent to mark finished items - [x], add new ones as - [ ], and write the commit as a > note. Indent sub-tasks with two spaces.

6. Limits

• Write-back keeps project names, todo/sub-task text, checkboxes, and > notes. Due dates, labels, and card colors stay in browser localStorage only
• Do not thrash the same file from two editors at once — last writer wins. The site re-reads notes, then overwrites the whole file
• This does not replace cross-device sync