diff --git a/README.md b/README.md
index cc5bad0..65bbfa0 100644
--- a/README.md
+++ b/README.md
@@ -142,6 +142,8 @@ Two gitignored files sourced by `.bashrc`, auto-bootstrapped from examples on fi
 
 ## td — markdown todo time tracking
 
+> Quick reference: [`docs/task-time-tracking.md`](docs/task-time-tracking.md)
+
 Track time on markdown todos identified by a block-ref `^tid-*`. Data lives in `time.csv` at the vault root.
 
 ### Surfaces
diff --git a/docs/task-time-tracking.md b/docs/task-time-tracking.md
new file mode 100644
index 0000000..1eb2986
--- /dev/null
+++ b/docs/task-time-tracking.md
@@ -0,0 +1,61 @@
+# Task & Time Tracking Cheat Sheet
+
+Plain-text todo + time tracking over the `~/hc_notes` Obsidian vault.
+All three surfaces (script, bashrc, nvim) live under `~/setup_env/dotfiles/` via symlinks — edit in dotfiles, changes go live.
+
+## Todo-grepping aliases (`~/.bashrc`)
+
+Search open todos across the vault (`- [ ]` open, `- [x]` done, `- [~]` cancelled):
+
+| Alias  | Does                                                        |
+| ------ | ----------------------------------------------------------- |
+| `td`   | All open todos                                              |
+| `tdp`  | Prioritized only (🔼 medium or ⏫ high)                      |
+| `tdtp` | Top priority only (⏫)                                       |
+| `tdo`  | fzf-pick any open todo → open in nvim at that line          |
+| `tdop` | fzf-pick a *prioritized* todo → open in nvim at that line   |
+
+## Time-tracking shell functions (`~/.bashrc`)
+
+Wrappers around the `td` script. They use `command td` because `td` alone is aliased to `rg` above — **don't remove `command`**.
+
+| Function                                  | Runs        | Purpose                                          |
+| ----------------------------------------- | ----------- | ------------------------------------------------ |
+| `tstart <tid> [--file PATH] [--desc TEXT]`| `td start`  | Start a timer on a task                          |
+| `tstop`                                   | `td stop`   | Stop the open timer                              |
+| `treport [FILTER]`                        | `td report` | Show logged time                                 |
+| `tweek [--since DATE]`                    | `td week`   | Weekly task log from git history + `time.csv`    |
+
+## The `td` script
+
+`~/.local/bin/td` → `~/setup_env/dotfiles/bin/td` (Python 3, stdlib only).
+
+Subcommands: `start <tid> [--file PATH] [--desc TEXT]`, `stop`, `report [FILTER]`, `current`, `tidgen`, `week [--since DATE]`.
+
+- **Storage:** CSV at `$TD_LOG` (default `./time.csv`, cwd-scoped).
+  Columns: `started_at,stopped_at,tid,file,description`. One row per entry; `stop` fills `stopped_at` on the open row.
+- **`td week`:** scans `git log -p --reverse --no-renames` from cwd, pairs `-`/`+` task-line diffs within each commit by `^tid-*` to classify events (`done` / `new` / `done+new` / `reopen`), then joins with `time.csv` for per-tid duration. Default range = Monday 00:00 of current week. Commit time = event time (git is source of truth).
+
+## Nvim integration
+
+Lives in `~/setup_env/dotfiles/nvim/{td.lua,td_mappings.lua}` → `~/.config/nvim/lua/`.
+Pulled in by a single `require "td_mappings"` line in `~/.config/nvim/lua/mappings.lua`.
+
+| Keymap        | Command                  | Action                                                                                       |
+| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
+| `<leader>ts`  | `:TdStart`               | Start timer on current task line; auto-generates a `^tid-*` block ref if missing, then starts |
+| `<leader>tp`  | `:TdStop`                | Stop the timer                                                                               |
+| `<leader>tr`  | `:TdReport`              | Report in a floating window (`q` / `<Esc>` to close)                                          |
+| `<leader>tw`  | `:TdWeek [--since DATE]` | Weekly git-derived task log in a floating window                                             |
+
+- `:TdStart` only acts on lines matching `- [.]`. Auto-tid format: `tid-YYYYMMDD-HHMMSS`.
+- Finds vault root by walking up from the buffer file for `time.csv` or `.obsidian/`; falls back to nvim cwd. CSV is written at the vault root regardless of buffer depth.
+- Passes `--file` (relative to vault root) and `--desc` (task text, stripped of checkbox + block ref) to `td`, avoiding the rg-lookup fallback.
+
+## Task metadata conventions (Obsidian-Tasks)
+
+`➕ YYYY-MM-DD` created · `📅 YYYY-MM-DD` due · `⏫` high priority · `🔼` medium · plus `#Tag` and `[[WikiLink]]`.
+
+## Known limitation
+
+NvChad defers `mappings.lua` via `vim.schedule`, so `:TdStart` etc. aren't available inside `-c` args on headless invocations. Interactive use is unaffected.