Summary

Epic: shuttle notion — sync tasks between an existing Notion database and local markdown (data/tasks/).

Local repository is the source of truth. Shuttle never creates databases, views, formulas, or board layout.

CLI convention (local-centric)

Hidden legacy: download / upload, and older export / import.

Configuration

notion:
  database_id: your-database-id
  task_directory: data/tasks
  cleanup_before_deploy: false
  properties:
    title: Name
    status: Status
    priority: Priority
    tags: Tags
    id: ID
    created: Created
    updated: Updated

Auth: NOTION_TOKEN (integration token). Never commit tokens.

Local task format

One file per task: data/tasks/{id}.md — YAML frontmatter + # Description / # Notes / # Checklist.

Current scaffold (shipped)

• CLI: ingest / deploy / sync / cleanup with token + database_id validation
• Hidden legacy aliases (download, upload, export, import)
• shuttle/services/notion_sync.py stubs (NotImplementedError)
• data/tasks/.gitkeep
• Scripts: scripts/notion/ingest.sh, deploy.sh, sync.sh, cleanup.sh
• docs/notion.md, README section
• Real Notion API (children below)

Child issues

• 03.1 — Notion ingest (board → data/tasks markdown) #20 — Notion ingest (board → data/tasks/ markdown)
• 03.2 — Notion deploy (data/tasks → board) #21 — Notion deploy (data/tasks/ → board)
• 03.3 — Notion cleanup (archive pages) #22 — Notion cleanup (archive all pages)
• 03.4 — Notion auth, mapping, and automation #23 — Auth, property mapping, automation workflow
• 03.5 — Notion sync (ingest + deploy) #31 — Notion sync (ingest + deploy orchestration)

Non-goals

Database creation, views, filters, formulas, relations, bidirectional sync (v1).

Definition of done (epic)

• Ingest/deploy/cleanup work against real Notion API
• CLI verbs match local-centric convention
• Deterministic, Git-friendly markdown output
• Property mapping configurable in YAML
• Integration tests with mocked HTTP

Execution

Close children #20–#23; link PRs to this epic.