From c69a3957c8ad094247b7f69cabfbd7589522e22d Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Tue, 24 Feb 2026 15:20:18 -0500
Subject: [PATCH] docs: add README

Problem: repo had no documentation for users.

Solution: add README covering usage, configuration, inline
metadata syntax, Google Calendar sync, mappings, and data
format.
---
 README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b178317
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+# todo.nvim
+
+Edit tasks like text. `:w` saves them.
+
+A buffer-centric task manager for Neovim. Tasks live in a plain buffer — add
+with `o`, delete with `dd`, reorder with `dd`/`p`, rename by editing. Write the
+buffer and the diff is computed against a JSON store. No UI chrome, no floating
+windows, no abstractions between you and your tasks.
+
+## How it works
+
+```
+School
+  ! Read chapter 5                             Feb 28
+  Submit homework                              Feb 25
+
+Errands
+  Buy groceries                                Mar 01
+  Clean apartment
+```
+
+Category headers sit at column 0. Tasks are indented below them. `!` marks
+priority. Due dates appear as right-aligned virtual text. Done tasks get
+strikethrough. Everything you see is editable buffer text — the IDs are
+concealed, and metadata is parsed from inline syntax on save.
+
+## Install
+
+```
+luarocks install todo.nvim
+```
+
+**lazy.nvim:**
+
+```lua
+{ 'barrettruth/todo.nvim' }
+```
+
+Requires Neovim 0.10+. No external dependencies for local use. Google Calendar
+sync requires `curl` and `openssl`.
+
+## Usage
+
+`:Todo` opens the task buffer. From there, it's just vim:
+
+| Key       | Action                          |
+| --------- | ------------------------------- |
+| `o` / `O` | Add a new task                  |
+| `dd`      | Delete a task (on `:w`)         |
+| `p`       | Paste (duplicates get new IDs)  |
+| `:w`      | Save all changes                |
+| `<CR>`    | Toggle complete (immediate)     |
+| `<Tab>`   | Switch category / priority view |
+| `g?`      | Show keybind help               |
+
+### Inline metadata
+
+Type metadata tokens at the end of a task line before saving:
+
+```
+Buy milk due:2026-03-15 cat:Errands
+```
+
+On `:w`, the date and category are extracted. The description becomes `Buy milk`,
+the due date renders as virtual text, and the task moves under the `Errands`
+header.
+
+### Quick add
+
+```vim
+:Todo add Buy groceries due:2026-03-15
+:Todo add School: Submit homework
+```
+
+### Archive
+
+```vim
+:Todo archive      " purge done tasks older than 30 days
+:Todo archive 7    " purge done tasks older than 7 days
+```
+
+## Configuration
+
+No `setup()` call required. Set `vim.g.todo` before the plugin loads:
+
+```lua
+vim.g.todo = {
+  data_path = vim.fn.stdpath('data') .. '/todo/tasks.json',
+  default_view = 'category',  -- 'category' or 'priority'
+  default_category = 'Inbox',
+  date_format = '%b %d',      -- strftime format for virtual text
+  date_syntax = 'due',        -- inline token name (e.g. 'by' for by:2026-03-15)
+}
+```
+
+All fields are optional. Absent keys use the defaults shown above.
+
+## Google Calendar sync
+
+One-way push of tasks with due dates to a dedicated Google Calendar as all-day
+events.
+
+```lua
+vim.g.todo = {
+  gcal = {
+    calendar = 'Tasks',
+    credentials_path = '/path/to/client_secret.json',
+  },
+}
+```
+
+```vim
+:Todo sync
+```
+
+On first run, a browser window opens for OAuth consent. The refresh token is
+stored at `stdpath('data')/todo/gcal_tokens.json`. Completed or deleted tasks
+have their calendar events removed. Due date changes update events in place.
+
+## Mappings
+
+The plugin defines `<Plug>` mappings for custom keybinds:
+
+```lua
+vim.keymap.set('n', '<leader>t', '<Plug>(todo-open)')
+vim.keymap.set('n', '<leader>T', '<Plug>(todo-toggle)')
+```
+
+| Plug mapping           | Action                |
+| ---------------------- | --------------------- |
+| `<Plug>(todo-open)`    | Open task buffer      |
+| `<Plug>(todo-toggle)`  | Toggle complete       |
+| `<Plug>(todo-view)`    | Switch view           |
+| `<Plug>(todo-priority)`| Toggle priority flag  |
+| `<Plug>(todo-date)`    | Prompt for due date   |
+
+## Data format
+
+Tasks are stored as JSON at `stdpath('data')/todo/tasks.json`. The schema is
+versioned and forward-compatible — unknown fields are preserved on round-trip.
+
+## Documentation
+
+```vim
+:checkhealth todo
+```