Initial commit

SPEC.md

@@ -0,0 +1,715 @@
+# markdown-to-caldav — Implementation Specification
+
+**Status:** Implemented · **Date:** 2026-07-31 · **Target runtime:** Python 3.14, Radicale 3.7.7
+
+---
+
+## 1. Overview
+
+`markdown-to-caldav` exposes the TODO checkboxes scattered through a directory of markdown notes
+(a [zk](https://github.com/zk-org/zk) or Obsidian vault) as a **CalDAV task server**. Standard
+CalDAV clients — DAVx⁵ + Tasks.org, jtx Board, Thunderbird — discover the vault as one or more task
+lists, display the tasks with their nesting and priorities, and can check them off. Completing a
+task in the client rewrites the corresponding `- [ ]` to `- [x]` in the original markdown file.
+
+The markdown files remain the single source of truth. There is no separate task database that can
+drift; the sidecar index (§6) is a derived cache that can be deleted and rebuilt at any time.
+
+### 1.1 Design goals
+
+1. **The vault is authoritative.** Every task the server serves is a line in a file. Nothing exists
+   only in the server.
+2. **Notes stay human-first.** No IDs, no metadata blocks, no reformatting injected into the
+   markdown. A file edited by the server must remain something you'd be happy to open in vim.
+3. **Bidirectional, promptly.** Vim edits appear in the client within seconds; client edits appear
+   in the file immediately.
+4. **Never corrupt notes.** A bug, a crash, or a misbehaving client must not be able to mangle a
+   file. Concurrent edits are detected and rejected, not merged blindly.
+
+### 1.2 Architecture
+
+Radicale provides the protocol layer; we provide a storage plugin that presents markdown as
+calendar collections of `VTODO` items.
+
+```
+CalDAV client (Tasks.org / jtx Board / Thunderbird)
+        │  HTTP: PROPFIND, REPORT, PUT, DELETE
+        ▼
+Radicale 3.7.7          ← WebDAV/CalDAV verbs, XML, auth, sync-collection, client quirks
+        │  BaseStorage / BaseCollection API
+        ▼
+mdcaldav.storage:Storage        ← this project
+        ├── parser.py     markdown → task tree (exact byte spans)
+        ├── ical.py       task ⇄ VTODO text
+        ├── index.py      SQLite sidecar: stable UIDs, sync generations
+        ├── writer.py     surgical, atomic markdown edits
+        └── watcher.py    filesystem watch → incremental rescan
+        ▼
+~/notes/**/*.md
+```
+
+**Why a Radicale plugin rather than a standalone server.** CalDAV client compatibility is the
+dominant risk in a project like this — `sync-collection` REPORT, ETag semantics, `calendar-query`
+filtering, and a long tail of per-client quirks. Radicale has absorbed that work over a decade. We
+write the markdown↔VTODO mapping (the part that is actually novel) and inherit the rest.
+
+**License consequence:** Radicale is GPLv3. Running as an in-process plugin makes any distribution
+of this project GPL-encumbered. Acceptable for a personal tool; stated here so it is not a surprise.
+
+---
+
+## 2. Source format
+
+### 2.1 Task line grammar
+
+```
+<indent><bullet><space>[<state>]<space>(<priority><space>)?<title>(<inline-meta>)*
+```
+
+| Element | Accepted |
+|---|---|
+| `indent` | spaces or tabs; tab width configurable (default 4) |
+| `bullet` | `-`, `*`, `+` |
+| `state` | see §2.2 |
+| `priority` | `[#A]`, `[#B]`, `[#C]` — org-mode placement, immediately after the checkbox |
+| `title` | free text to end of line, minus trailing inline-meta |
+| `inline-meta` | `#tag` → `CATEGORIES`; optional due syntax (§2.5) |
+
+Example exercising every element:
+
+```markdown
+- [ ] [#A] Ship the release #work @due(2026-08-04)
+```
+
+### 2.2 States
+
+Default state map (configurable via `[tasks].states`):
+
+| Marker | `STATUS` |
+|---|---|
+| `[ ]` | `NEEDS-ACTION` |
+| `[x]`, `[X]` | `COMPLETED` |
+| `[/]`, `[>]` | `IN-PROCESS` |
+| `[-]` | `CANCELLED` |
+
+Unrecognized markers (`[?]`, `[!]`) are treated as `NEEDS-ACTION` and the original character is
+preserved on write-back, so third-party checkbox conventions survive a round trip.
+
+### 2.3 Structure: tasks, descriptions, and group nodes
+
+Nesting is determined by indentation. Each bullet is classified by two questions: does it have a
+checkbox, and does it have any checkbox descendants?
+
+| Has checkbox | Has checkbox descendants | Classification |
+|---|---|---|
+| yes | — | **Task** |
+| no | no | **Description** — appended to the nearest ancestor task's `DESCRIPTION`; dropped if there is no ancestor task |
+| no | yes | **Group node** — not a task; its text is appended to `group_path`, and its checkbox children re-parent to the nearest ancestor **task** (or become roots) |
+
+This three-way rule is what makes real vaults work. Each case below occurs routinely in daily-note
+style vaults and is covered by a fixture in `tests/fixtures/vault/`.
+
+**Description:**
+```markdown
+- [x] Order the cover crop
+  - Arrived on the 12th, invoice is in the binder
+```
+→ one task, `SUMMARY:Order the cover crop`,
+`DESCRIPTION:Arrived on the 12th, invoice is in the binder`.
+
+**Group node:**
+```markdown
+- set up the cold frame
+  - [x] Cut the polycarbonate
+  - [ ] Hinge the lid
+```
+→ two root tasks (`Cut the polycarbonate`, `Hinge the lid`), each with `CATEGORIES` including
+`set up the cold frame`. The plain parent is *not* a task — it has no checkbox and cannot be
+completed — but its text is preserved as context.
+
+**Neither:**
+```markdown
+### Retrospective
+
+- Start the tomatoes earlier next year
+- Buy fewer squash varieties
+```
+→ no tasks, and no description attached to anything, because no ancestor task exists.
+
+### 2.4 Context: headings and frontmatter
+
+- ATX headings (`#`…`######`) maintain a `heading_path` stack. Checkboxes are collected under **any**
+  heading, not only `## TODO` — daily notes routinely carry tasks under topic headings such as
+  `## Greenhouse repairs` alongside a `## Notes` section that has none.
+- YAML frontmatter delimited by `---` at the top of the file is parsed for `tags` (→ `CATEGORIES`)
+  and `date`. It is never treated as content.
+
+### 2.5 Optional due dates
+
+Off by default. When `[tasks].due_syntax` is configured, the listed patterns are stripped from the
+title and mapped to `DUE`. Suggested patterns: `📅 %Y-%m-%d` (Obsidian Tasks), `@due(%Y-%m-%d)`.
+A daily note's frontmatter `date` may optionally seed `DUE` via `[tasks].daily_note_due`.
+
+### 2.6 Exclusions
+
+Content that must **never** yield a task:
+
+- fenced code blocks (``` and `~~~`), including a `- [ ]` inside a shell snippet
+- indented code blocks (4+ spaces beyond list context)
+- YAML frontmatter
+- paths matching `[vault].exclude`
+
+Path patterns use real glob semantics (`globs.py`), **not** `fnmatch`: `**/` means zero or
+more segments and `*` does not cross `/`. With `fnmatch`, `**/*.md` fails to match a
+top-level `README.md` while `*.tmp` wrongly matches `a/b.tmp` — both wrong on a real vault.
+
+Filtering is applied to **targeted rescans as well as full scans**. The watcher rescans
+individual paths, so an unfiltered targeted rescan would index excluded files the moment
+something wrote to them.
+
+Default exclusions cover `.git/**`, `.zk/**`, `.obsidian/**`, `assets/**`, and Syncthing's
+artefacts (§9.5).
+
+### 2.6.1 Syncthing-backed vaults
+
+A Syncthing folder contains three classes of file that must never be parsed:
+
+| Path | Contents | Consequence if indexed |
+|---|---|---|
+| `.stversions/**` | **complete historical copies of notes** | every task duplicated once per retained version |
+| `**/*.sync-conflict-*` | whole duplicate notes from conflicting edits | entire files duplicated |
+| `**/.syncthing.*`, `**/~syncthing~*` | partial in-flight writes | torn tasks |
+
+`.stversions/` is the severe one: with versioning enabled it multiplies the entire task
+list by the retention depth.
+
+Conflict files are excluded rather than merged — a conflict is a human decision. `doctor`
+reports any present so they are not silently forgotten.
+
+Write-back is compatible with Syncthing because edits are atomic (`os.replace`), so
+Syncthing always observes a complete file. The residual risk is a genuine concurrent edit
+on two devices, which Syncthing resolves by producing a conflict file; the task is not
+lost, but the losing edit waits in that file.
+
+### 2.7 Parser implementation note
+
+The parser is a **hand-rolled line scanner**, not markdown-it-py or a CommonMark AST.
+
+Rationale: write-back requires exact byte spans for the checkbox marker, the priority token, and the
+title, so an edit can touch only those bytes (§7). AST libraries either discard source spans or give
+line-level maps that are too coarse to edit surgically. We also only need a small subset of markdown
+(lists, headings, fences, frontmatter). The tradeoff is that exotic CommonMark constructs — lists
+inside block quotes, lazy continuation lines — are out of scope; §2.6 exclusions and a fixture suite
+of real files cover what actually occurs.
+
+---
+
+## 3. Data model
+
+```python
+@dataclass
+class Source:
+    rel_path: str          # vault-relative, POSIX separators
+    line_no: int           # 0-based
+    line_span: tuple[int, int]      # byte offsets of the full line
+    marker_span: tuple[int, int]    # byte offsets of the state char inside [ ]
+    title_span: tuple[int, int]     # byte offsets of the title text
+    prio_span: tuple[int, int] | None
+    indent: str            # verbatim leading whitespace
+    bullet: str            # '-', '*', '+'
+
+@dataclass
+class Task:
+    uid: str
+    title: str
+    status: Status                 # NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED
+    raw_marker: str                # verbatim char, for lossless round trip
+    priority: int | None           # 1..9, RFC 5545
+    description: str | None
+    due: date | None
+    categories: list[str]
+    parent_uid: str | None
+    children: list[str]
+    heading_path: tuple[str, ...]
+    group_path: tuple[str, ...]
+    sibling_index: int
+    depth: int
+    source: Source
+    content_hash: str              # blake2b of the normalized line
+```
+
+---
+
+## 4. iCalendar mapping
+
+Each task becomes one `VTODO` in its own `.ics` resource, href `<uid>.ics`.
+
+| Markdown | VTODO property |
+|---|---|
+| title | `SUMMARY` |
+| `[ ]` | `STATUS:NEEDS-ACTION` |
+| `[x]` | `STATUS:COMPLETED` + `PERCENT-COMPLETE:100` + `COMPLETED` |
+| `[/]` | `STATUS:IN-PROCESS` |
+| `[-]` | `STATUS:CANCELLED` |
+| `[#A]` / `[#B]` / `[#C]` | `PRIORITY:1` / `5` / `9` |
+| description sub-bullets | `DESCRIPTION` (newline-joined) |
+| indentation | `RELATED-TO;RELTYPE=PARENT:<parent uid>` |
+| `heading_path` + `group_path` + tags | `CATEGORIES` |
+| due syntax (§2.5) | `DUE;VALUE=DATE` |
+| sidecar UID | `UID` |
+| — | `X-MD-SOURCE-FILE`, `X-MD-SOURCE-LINE` |
+
+Priority mapping follows RFC 5545 §3.8.1.9, which defines 1–4 as high, 5 as medium, 6–9 as low;
+`A→1, B→5, C→9` places each org priority in the centre of its band. Inbound values are mapped back
+by band, so a client sending `PRIORITY:3` yields `[#A]`.
+
+### 4.1 Timestamps
+
+`COMPLETED` has no markdown representation. Resolution order:
+
+1. the timestamp recorded in the sidecar when the server observed the `[ ]`→`[x]` transition;
+2. otherwise the file's mtime (for checkboxes already complete at first index);
+3. if neither is available, omit the property.
+
+`LAST-MODIFIED` and `DTSTAMP` derive from the source file's mtime.
+
+### 4.2 Nesting caveat
+
+`RELATED-TO;RELTYPE=PARENT` is the RFC 5545 mechanism for subtasks. jtx Board and Tasks.org render
+the hierarchy. **Thunderbird ignores `RELATED-TO`** and will show a flat list of every task — the
+tasks are all present and completable, just not indented. Document this in the README rather than
+working around it.
+
+### 4.3 Generation
+
+We emit iCalendar **text** and hand it to `radicale.item.Item(text=...)`, which accepts a raw string
+and parses lazily with vobject. This avoids a second iCalendar library as a dependency — vobject
+arrives with Radicale.
+
+---
+
+## 5. Collections
+
+`[collections].group_by` selects a strategy:
+
+| Value | Collections produced |
+|---|---|
+| `directory` *(default)* | one per directory at `depth` (default 1): `daily`, `work`, `zets` |
+| `file` | one per markdown file |
+| `heading` | one per top-level heading across the vault |
+| `tag` | one per frontmatter tag |
+| `single` | one collection for the whole vault |
+
+Strategy interface:
+
+```python
+class GroupingStrategy(Protocol):
+    def collection_for(self, task: Task) -> str: ...   # returns collection href
+    def display_name(self, href: str) -> str: ...
+```
+
+Collection hrefs are slugified and stable. A task whose file moves between collections is treated as
+a delete from the old collection and a create in the new one — CalDAV has no cross-collection move
+that clients handle reliably.
+
+Each collection reports `tag = "VCALENDAR"` and advertises `VTODO` in
+`supported-calendar-component-set`, so clients present it as a task list rather than a calendar.
+
+---
+
+## 6. Identity and the sidecar index
+
+The central problem: a `VTODO` needs a `UID` that is stable across arbitrary vim edits, but markdown
+carries no identifiers and we have committed to not writing any into the notes.
+
+### 6.1 Schema
+
+SQLite at `[index].db` (default `~/.cache/markdown-to-caldav/index.db`):
+
+```sql
+CREATE TABLE meta (schema_version INT, generation INT);
+
+CREATE TABLE files (
+  rel_path TEXT PRIMARY KEY, mtime REAL, size INT, hash TEXT, last_scan_gen INT);
+
+CREATE TABLE tasks (
+  uid TEXT PRIMARY KEY,
+  collection TEXT, rel_path TEXT,
+  heading_path TEXT, group_path TEXT,
+  sibling_index INT, depth INT,
+  title_norm TEXT, content_hash TEXT,
+  status TEXT, completed_at TEXT,
+  parent_uid TEXT,
+  first_seen_gen INT, last_modified_gen INT, deleted_gen INT);
+
+CREATE INDEX tasks_lookup ON tasks(rel_path, heading_path, title_norm);
+CREATE INDEX tasks_sync   ON tasks(last_modified_gen);
+```
+
+`title_norm` is the title lowercased, whitespace-collapsed, and stripped of inline meta.
+
+### 6.2 Matching algorithm
+
+On rescan of a file, each parsed task is matched against surviving rows **for that file first**:
+
+1. **Exact** — `(rel_path, heading_path, group_path, title_norm)` matches → reuse UID.
+   Survives reordering and status changes, the overwhelmingly common case.
+2. **Positional** — `(rel_path, heading_path, depth, sibling_index)` matches and title similarity
+   ≥ `[index].similarity_threshold` (default 0.75, via `rapidfuzz`) → reuse UID.
+   Survives an in-place retitle.
+3. **Cross-file move** — considered **only** when the previous occurrence disappeared in this same
+   scan *and* the match is unique vault-wide → reuse UID.
+4. No match → mint a new UID (`uuid4`).
+5. A row not seen this scan → tombstone: set `deleted_gen`, retain for the sync window (§6.3).
+
+Ambiguity within one file+heading (two identical titles) is resolved by `sibling_index`.
+
+### 6.3 Why rule 3 is guarded
+
+Carry-forward is a normal habit in daily notes: an unfinished task gets copied into the next day's
+file while the previous day's copy stays put as a record. The fixtures model this with
+`Water the seedlings`, which appears in three consecutive daily notes. These are deliberate copies,
+not moves. Matching on title alone across files would collapse them into one task and make
+completing Wednesday's item silently tick Monday's.
+
+The disappearance requirement is standard rename detection: a task is only considered *moved* if it
+is no longer where it was. If both copies exist, both keep their own identity.
+
+### 6.4 Rebuild
+
+The index is a cache. Deleting the database and rescanning is always safe; the cost is that every
+UID is regenerated, so clients see a full replacement of their task list. `mdcaldav doctor` reports
+index/vault divergence without modifying anything.
+
+---
+
+## 7. Write-back
+
+### 7.1 Supported operations
+
+| Operation | Edit performed |
+|---|---|
+| status change | rewrite **only** the state character inside `[ ]` (`marker_span`) |
+| retitle | replace `title_span`; indent, bullet, checkbox, priority and inline meta preserved |
+| priority set/clear | insert, replace, or remove the `[#X]` token at `prio_span` |
+| description change | replace the contiguous non-checkbox child-bullet block at the child indent |
+| create | append under `[write].inbox_heading` in the **collection's** inbox, creating file/heading if absent |
+| delete | remove the task line and its description lines; subtree per `[write].delete_children` |
+
+`[write].delete_children` ∈ `cascade` (default — remove the whole subtree, matching client
+expectations), `orphan` (promote children one level), `reject` (return 409 if the task has children).
+
+### 7.2 Safety invariants
+
+These are the load-bearing requirements of the whole project.
+
+1. **Atomic replacement.** Write to a temp file in the same directory, `fsync`, then `os.replace`.
+   File mode and ownership are preserved. A crash mid-write leaves the original intact.
+2. **Byte-identical elsewhere.** Every line the operation does not target must be unchanged, byte
+   for byte. No reflow, no trailing-whitespace stripping, no indent normalization, no line-ending
+   conversion. Final-newline presence is preserved exactly.
+3. **Conflict detection before write**, in two layers:
+   - *Client staleness* is Radicale's job: it checks `If-Match` against the item's ETag and returns
+     **412 Precondition Failed** before `upload()` is ever called. Since our ETag derives from the
+     task's content hash, any external edit to that task invalidates the client's cached copy.
+   - *Stale spans* are ours: byte offsets captured at parse time are meaningless once the file
+     changes. Before every write the writer compares the file's hash to what `files` recorded and
+     reparses if it differs, so an edit is only ever applied through freshly computed offsets. If
+     the task's UID no longer resolves after that reparse, the write is refused rather than guessed.
+
+   Note that an in-place retitle is *not* a conflict — identity rule 2 (§6.2) says it is the same
+   task, so the write lands on the renamed line. A vim edit is never silently overwritten, but it is
+   also not treated as a different task just because its text moved.
+4. **Locking.** Radicale's `acquire_lock("w")` serializes writers process-wide; an additional
+   per-file lock guards the read-modify-write cycle.
+5. **Optional backups.** When `[write].backup_dir` is set, the original is copied there once before
+   the first modification of each file per run.
+
+Under directory grouping the inbox resolves **per collection**: a task created in `daily` is
+appended to `daily/inbox.md`, not to a vault-root `inbox.md`. Otherwise the new task would be
+assigned to a different collection and disappear from the list the client just created it in.
+
+### 7.3 Inbound PUT handling
+
+1. Parse the submitted `.ics`.
+2. Resolve `UID` → sidecar row → file and line. Unknown UID plus `[write].allow_create` → create in
+   the collection's inbox; unknown UID without it → 403.
+3. On create, **adopt the client's UID** rather than minting one, so the item remains at the href the
+   client PUT to. The sidecar row is renamed to that UID after the file is reindexed.
+4. Diff submitted properties against the task's current state; compute the minimal set of edits.
+5. Apply under lock (§7.2); bump the generation; return the new ETag.
+
+Priority is compared by *band*, not by exact value: a client sending `PRIORITY:3` against a task
+already marked `[#A]` is not a change, so the markdown is left alone.
+
+Properties we do not model (`RRULE`, `VALARM`, `GEO`, …) are ignored on input rather than rejected,
+so a client that always round-trips its full object does not fail. This is stated in §11 as a
+non-goal, and `mdcaldav doctor` warns when ignored properties are seen.
+
+---
+
+## 8. Change detection
+
+**Freshness comes from the read path.** Every `discover`, `get_all`, `get_multi` and `sync` first
+calls `refresh_if_stale()`, which stats the vault and reparses only files whose mtime/size no longer
+match the index. Because CalDAV has no server push — clients poll — this alone guarantees that an
+edit made in vim is visible on the client's next sync.
+
+**Watching is therefore an optimization, not a correctness mechanism.** A `watchdog` observer with
+~300 ms debounce moves rescan cost off the request path, which matters for large vaults. It is
+enabled by `mdcaldav serve` (disable with `--no-watch`) and off by default elsewhere, so embedding
+the storage plugin never silently spawns threads. `[vault].poll_interval` selects polling instead of
+inotify, for network mounts.
+
+Each rescan batch increments `meta.generation`.
+
+### 8.1 Sync tokens
+
+Radicale's `BaseCollection.sync(old_token)` returns `(new_token, changed_hrefs)`.
+
+- Token format: `http://mdcaldav.local/ns/sync/<generation>`.
+- Changed set: tasks with `last_modified_gen > old_gen`, plus tombstones with
+  `deleted_gen > old_gen`.
+- Tombstones are pruned after `[index].tombstone_retention` generations (default 1000). A token
+  older than the retained window causes `sync()` to raise `ValueError`, which is Radicale's
+  documented signal for "force a full resync" — the correct behavior, not an error to suppress.
+
+---
+
+## 9. Radicale integration
+
+### 9.1 Plugin contract
+
+Radicale loads storage via `utils.load_plugin(..., "storage", "Storage", BaseStorage, config)`,
+which imports the configured module and fetches the attribute **`Storage`**. So `mdcaldav/storage.py`
+must define `class Storage(BaseStorage)`. (Radicale 2.x required a class named `Collection`; that
+guidance is stale and does not apply to 3.x.)
+
+Radicale validates its own configuration schema and **rejects unknown keys**, so the vault config
+cannot ride along inside `[storage]`. It is supplied out of band: `mdcaldav.storage.set_config(cfg)`
+before the plugin is instantiated (what the CLI does), or `MDCALDAV_CONFIG=/path/config.toml` in the
+environment.
+
+```ini
+[storage]
+type = mdcaldav.storage
+
+[auth]
+type = htpasswd
+htpasswd_filename = ~/.config/markdown-to-caldav/users
+htpasswd_encryption = bcrypt
+
+[server]
+hosts = localhost:5232
+```
+
+### 9.2 Methods to implement
+
+Verified against Radicale 3.7.7:
+
+```python
+class Storage(BaseStorage):
+    def discover(self, path, depth="0", child_context_manager=None,
+                 user_groups=set()) -> Iterable[CollectionOrItem]
+    def move(self, item, to_collection, to_href) -> None
+    def create_collection(self, href, items=None, props=None
+                          ) -> tuple[BaseCollection, dict, list]
+    @contextmanager
+    def acquire_lock(self, mode, user="", *args, **kwargs) -> Iterator[None]
+    def verify(self) -> bool
+
+class Collection(BaseCollection):
+    path, owner, tag, etag, last_modified, is_principal   # properties
+    def get_multi(self, hrefs) -> Iterable[tuple[str, Item | None]]
+    def get_all(self) -> Iterable[Item]
+    def get_filtered(self, filters) -> Iterable[tuple[Item, bool]]
+    def has_uid(self, uid) -> bool
+    def upload(self, href, item) -> tuple[Item, Item | None]
+    def delete(self, href=None) -> None
+    def get_meta(self, key=None); def set_meta(self, props)
+    def sync(self, old_token="") -> tuple[str, Iterable[str]]
+    def serialize(self, vcf_to_ics=False, ShareActions={}) -> str
+```
+
+`get_filtered` may return `(item, False)` to let Radicale apply the filter itself; we do this
+initially and optimize `calendar-query` server-side only if profiling warrants it.
+
+`set_meta` on a markdown-backed collection has nowhere durable to write client-set properties
+(display name, colour). These are held in memory keyed by collection href, so a client that renames
+a list does not fail — but the rename does not touch the vault and does not survive a restart.
+
+**The principal follows the authenticated user.** Collections are served under whatever principal
+the client authenticated as (`/tyler/daily/`, not a hardcoded `/vault/daily/`), so hrefs stay inside
+the principal's namespace as clients expect. The vault itself is single-user; the principal name is
+presentational.
+
+---
+
+### 9.3 One backend per process
+
+`[storage] type` is a single global option and `Application` holds exactly one `BaseStorage`
+instance; Radicale has no per-collection storage routing. Consequences:
+
+- This plugin **cannot be added to an existing Radicale instance**. Setting `type` would make it
+  serve every path, and collections held by `multifilesystem` would stop resolving.
+- Deployment is therefore always a **second instance**, presented either on its own port or under a
+  reverse-proxy sub-path via `[server] script_name`.
+
+### 9.3.1 Reverse proxying at a sub-path
+
+Radicale strips `script_name` from the incoming URI itself (from `[server] script_name` or
+the `X-Script-Name` / `SCRIPT_NAME` variables) and re-adds it when generating hrefs.
+
+The proxy must therefore pass the **full** path through, prefix included. Stripping it at
+the proxy — `proxy_pass http://host:port/;` with a trailing slash in nginx, or Caddy's
+`handle_path` — makes Radicale emit hrefs without the prefix, and clients then walk to
+collection URLs that do not exist. Use nginx `proxy_pass` without a trailing slash, or
+Caddy's `handle`, and set `X-Script-Name`.
+
+### 9.4 Root collection path
+
+`discover("/")` must yield a collection whose `path` is `""`. Radicale filters out any item whose
+path does not match the request, so a root item reporting a non-empty path is silently dropped from
+the multistatus — which breaks `current-user-principal` and leaves clients unable to discover
+anything. This fails only when authentication is enabled, so it must be covered by an explicit test
+(§12, test 12) rather than left to client-library behaviour.
+
+## 10. Configuration
+
+`~/.config/markdown-to-caldav/config.toml`:
+
+```toml
+[vault]
+path = "~/notes"
+include = ["**/*.md"]
+exclude = [".git/**", ".zk/**", ".obsidian/**", "assets/**"]
+tab_width = 4
+watch = false                # `serve` enables this; freshness never depends on it
+# poll_interval = 2.0        # set to use polling instead of inotify
+
+[collections]
+group_by = "directory"       # directory | file | heading | tag | single
+depth = 1
+
+[tasks]
+states = { " " = "NEEDS-ACTION", "x" = "COMPLETED", "/" = "IN-PROCESS", "-" = "CANCELLED" }
+priority_map = { A = 1, B = 5, C = 9 }
+due_syntax = []              # e.g. ["@due(%Y-%m-%d)", "📅 %Y-%m-%d"]
+
+[write]
+allow_create = true
+allow_delete = true
+inbox = "inbox.md"
+inbox_heading = "## Inbox"
+delete_children = "cascade"  # cascade | orphan | reject
+# backup_dir = "~/.local/share/markdown-to-caldav/backups"
+
+[index]
+db = "~/.cache/markdown-to-caldav/index.db"
+similarity_threshold = 0.75
+tombstone_retention = 1000
+```
+
+### 10.1 CLI
+
+| Command | Purpose |
+|---|---|
+| `mdcaldav serve` | run Radicale with this storage plugin |
+| `mdcaldav scan` | index the vault and print the task tree; no server, no writes |
+| `mdcaldav doctor` | report parse warnings, index divergence, ambiguous identities, ignored properties |
+
+`scan` is the primary debugging tool: it answers "what does the server think my notes say?" without
+involving a client.
+
+---
+
+## 11. Non-goals
+
+Explicitly out of scope for v1:
+
+- recurrence (`RRULE`) and alarms (`VALARM`)
+- `VEVENT` / calendar sync; this is a task server only
+- multi-user vaults, per-user views, sharing
+- org-mode `.org` files (the *format* of org priorities is borrowed; the file format is not)
+- timezone-aware scheduling beyond whole-date `DUE`
+- conflict *merging* — conflicts are detected and rejected (§7.2), never auto-resolved
+
+---
+
+## 12. Testing strategy
+
+| # | Test | Asserts |
+|---|---|---|
+| 1 | Fixture parse | Real vault files in `tests/fixtures/vault/` produce exact expected task trees, covering description bullets, group nodes, note-only bullets, non-`## TODO` headings, 5-level nesting |
+| 2 | Round-trip invariant | parse → serialize with no mutation → file is byte-identical |
+| 3 | Surgical write | Toggling one task produces a **one-line** diff and nothing else |
+| 4 | Identity: reorder | Moving a task within a file preserves its UID |
+| 5 | Identity: retitle | Editing a title in place preserves its UID |
+| 6 | Identity: carry-forward | The same title in three daily notes keeps **three distinct** UIDs; completing one does not affect the others |
+| 7 | Identity: true move | A task that disappears from A and appears in B keeps its UID |
+| 8 | Conflict | Edit the file behind the server, then PUT → 412, file unchanged |
+| 9 | Code fence | `- [ ]` inside a fenced block yields no task |
+| 10 | CalDAV integration | Radicale in-process + `caldav` client: discover collections, REPORT, PUT a completion, assert the markdown changed and the ETag advanced |
+| 11 | Sync token | Stale token raises `ValueError`; fresh token returns only changed hrefs |
+| 12 | Root PROPFIND | `/` reports `current-user-principal`, guarding the §9.4 discovery failure |
+
+Fixtures in `tests/fixtures/vault/` are **synthetic** — invented content that reproduces the
+structural cases (group nodes, description bullets, carry-forward duplicates, five-level nesting,
+code blocks). Never commit real notes into this repository; the test suite must be safe to share and
+must not depend on anyone's private content.
+
+### 12.1 Manual client checklist
+
+Point a client at a **throwaway copy** of a vault, never at live notes, until write-back is trusted.
+
+- [ ] DAVx⁵ discovers the collections; Tasks.org lists tasks with correct nesting and priority
+- [ ] Completing on the phone rewrites `[ ]`→`[x]` in the file, and only that
+- [ ] Editing in vim surfaces in the client after a sync
+- [ ] jtx Board renders subtasks
+- [ ] Thunderbird lists tasks flat (expected, §4.2) and completion still round-trips
+
+---
+
+## 13. Repository layout
+
+```
+markdown-to-caldav/
+├── SPEC.md
+├── README.md
+├── pyproject.toml
+├── src/mdcaldav/
+│   ├── config.py        # TOML load + validation
+│   ├── model.py         # Task, Source, Status
+│   ├── parser.py        # markdown → task tree, byte spans
+│   ├── ical.py          # Task ⇄ VTODO text
+│   ├── collections.py   # grouping strategies
+│   ├── index.py         # SQLite sidecar, identity matching, generations
+│   ├── writer.py        # surgical atomic edits
+│   ├── watcher.py       # watchdog + debounce
+│   ├── storage.py       # Radicale Storage / Collection
+│   └── cli.py           # serve | scan | doctor
+└── tests/
+    ├── fixtures/vault/  # real notes
+    └── test_*.py
+```
+
+**Dependencies:** `radicale>=3.7`, `watchdog`, `rapidfuzz`. Dev: `pytest`, `caldav`.
+`tomllib` and `sqlite3` are stdlib. `vobject` arrives with Radicale; no separate iCalendar library.
+
+---
+
+## 14. Build order
+
+Each step is independently testable; the CalDAV layer came last deliberately, so the risky parsing
+and identity work was proven before any protocol code existed.
+
+1. ✅ `model.py`, `config.py`
+2. ✅ `parser.py` + fixtures + tests 1, 2, 9 — the foundation
+3. ✅ `ical.py` + mapping tests
+4. ✅ `index.py` + identity tests 4–7 — the subtlest logic in the project
+5. ✅ `writer.py` + tests 3, 8
+6. ✅ `collections.py`, `watcher.py`
+7. ✅ `storage.py` + tests 10, 11
+8. ✅ `cli.py`, README
+
+Remaining: systemd unit, and the manual client checklist in §12.1 against real clients.