PLAN-notes-sync.md

Plan: Bidirectional JDex ↔ Apple Notes Sync

Date: 2026-03-24 Status: Draft Scope: jd-cli — configurable JDex backend, Apple Notes sync, zero naming

---

Goals

1. Bidirectional sync between .jd-index.yaml and Apple Notes
2. Configurable JDex backend (yaml, markdown, or future backends)
3. Configurable standard zero names
4. Apple Notes folder structure mirrors JD areas/categories

Config additions to .jd.yaml

jdex:
  backend: yaml                  # yaml | markdown
  path: .jd-index.yaml          # for yaml backend

notes:
  enabled: true
  backend: apple-notes           # apple-notes | obsidian | none
  sync:
    enabled: true
    direction: bidirectional     # push | pull | bidirectional
    auto: false                  # true = sync on every jd mv/create
  filter:
    exclude_zeros: true          # skip .00-.09 standard zero IDs
    exclude_status: [archived]
    include_categories: all      # or [26, 43, 61] for specific cats
  folders:
    style: area                  # area = "20-29 People", category = nested "20-29 People/26 Jen & Divorce"

standard_zeros:
  ids:
    '00':
      purpose: jdex
      name: JDex for category {category}    # configurable
    '01':
      purpose: inbox
      name: Inbox for category {category}   # configurable
    # ... etc
  categories:
    x0:
      purpose: area-meta
      name: Management of area {area_range}  # FIX: currently says "Meta - {area}"

Sync logic

Push (YAML → Apple Notes)

For each YAML entry matching the filter:

1. Determine target folder: area-level (20-29 People) or category-level
2. Ensure folder exists in Apple Notes (create if missing)
3. Check if note with title XX.YY Title exists
4. If missing: create note with metadata body (Location, Status, etc.)
5. If exists: update title if changed (rename via JXA)

Pull (Apple Notes → YAML)

For each Apple Note in JD-named folders:

1. Parse the note title for JD ID (XX.YY)
2. Find the matching YAML entry
3. Read the note's plain text content
4. Store in YAML entry's notes field (plain text snapshot)
5. If no YAML entry exists: warn (orphan note in Apple Notes)

Conflict resolution

• Title mismatch: YAML wins (it's the registry)
• Content: Apple Notes wins (it's where humans write)
• ID existence: YAML wins (jd mv/create/delete manage IDs)

CLI commands

jd notes sync              # bidirectional sync per config
jd notes sync --push       # YAML → Apple Notes only
jd notes sync --pull       # Apple Notes → YAML only
jd notes sync --dry-run    # show what would change
jd notes sync --category 26  # sync one category only

Existing commands continue to work:

jd notes create XX.YY      # create note in Apple Notes + YAML
jd notes open XX.YY        # open in Notes.app
jd notes scan              # compare state

Implementation steps

1. Config schema — add jdex and notes sections to config parser
2. Backend selection — get_jdex() reads jdex.backend from config
3. Fix standard zero names — categories.x0.name template; rename command respects config
4. Sync engine — johnnydecimal/sync/notes.py with push/pull/conflict logic
5. CLI wiring — jd notes sync command with options
6. Tests — mock Apple Notes JXA calls; test push/pull/conflict scenarios

Dependencies

• apple-notes-py for JXA read/write (or use jd-cli's own johnnydecimal/notes.py)
• Existing YamlJDexBackend for YAML read/write

Open questions

• Should jd mv auto-sync (rename note when ID renumbers)? Probably yes if notes.sync.auto: true.
• Should jd notes sync be a plugin or core? Core for now.
• Should we store Apple Notes note ID (CoreData UUID) in YAML for reliable matching? Title-based matching is fragile if user renames note.