Marlin/roadmap.md

Here’s a slimmed-down, re-organized roadmap that groups related work into bigger milestones, highlights key deliverables (including a “demo” command and grep-style context snippets), and stages integrations for maximal developer velocity:

Phase / Sprint	Timeline	Focus & Rationale	Key Deliverables
Sprint α: Bedrock & Metadata Domains	2025-Q2 (now–6/01)	Stabilize core schema, migrations, CI, and introduce the first metadata domains with discoverability.	- CI: cargo test + SQL migration dry-run coverage - Migrations:

• links(src,dst,type)
• collections(name)+collection_files
• views(name,query)
  - CLI stubs for marlin link|unlink|list|backlinks, marlin coll, marlin view
  - marlin demo command that walks you through a mini-drive-by tutorial of link/coll/view flows | | Epic 1: Scale & Reliability | 2025-Q2 | Prototype “dirty-row” FTS to avoid per-row triggers, benchmark at 100 k files, and shore up CI for edge cases. | - Dirty-flag + scan --dirty reindex only changed rows
  - Replace per-row triggers with periodic FTS rebuild
  - End-to-end benchmarks on ~100 k files
  - CI tests for dirty-scan edge-cases | | Epic 2: Live Mode & Self-Pruning Backups | 2025-Q2 | Automate continuous indexing & backup hygiene so Marlin “just works” in a real workspace. | - marlin watch [dir] via notify crate (create/modify/delete/rename)
  - backup --prune <N> flag + post-scan auto-prune to latest N
  - Daily/pr-merge auto-prune automation in CI | | Phase 3: Content FTS & Annotations | 2025-Q3 | Go beyond metadata—index file bodies, provide grep-style context, and add annotation support. | - New files.content column + migration
  - Extend files_fts to include content and emit context snippets (-C style)
  - annotations table + FTS triggers
  - CLI: marlin annotate add|list | | Phase 4: Versioning & Deduplication | 2025-Q3 | Enable history, diffs, and duplicate detection with content hashing. | - Compute & store files.hash (SHA256)
  - scan --rehash to refresh hashes
  - CLI: marlin version diff <file> to show changes between revisions | | Phase 5: Tag Aliases & Semantic Enhancements | 2025-Q3 | Tame tag sprawl and seed AI-powered suggestions via embeddings. | - Enforce canonical_id on tags; CLI: marlin tag alias add|ls|rm
  - embeddings table + scan --embed to generate vectors
  - CLI: marlin tag suggest, marlin summary <file>, marlin similarity scan | | Phase 6: Search DSL v2 & Smart Views | 2025-Q4 | Offer a robust query grammar and “virtual folders” powered by views. | - Swap ad-hoc parser for a nom-based grammar with AND, OR, parentheses, wildcards…
  - CLI: marlin view save|list|exec with aliases and pagination | | Phase 7: Structured Workflows | 2025-Q4 | Unlock full task, state, reminder & event workflows directly on files. | - templates + template_fields + validation engine
  - CLI:
• marlin state set|transitions add|state log
• marlin task scan|task list
• marlin remind set <file> <ts> "<msg>"
• marlin event add <file> <date> "<desc>" + marlin timeline | | Phase 8: Lightweight Integrations | 2026-Q1 | Surface Marlin inside your editor/terminal before diving into a full GUI. | - VSCode & terminal UI extension: file-tree sidebar showing tags/attrs/links/annotations | | Phase 9: Dolphin Sidebar Plugin (MVP) | 2026-Q1 | Prototype a read-only Qt sidebar for Linux file managers—peek metadata without leaving your file browser. | - Qt plugin showing tags, attributes, links, and annotations alongside files | | Phase 10: Full Edit UI & Multi-Device Sync | 2026-Q2 | Ship an in-place metadata editor and optional sync layer for distributed workflows. | - Tag & view editors, task/reminder/event dialogs in GUI
  - Choose/implement sync backend (rqlite, Litestream or custom) for optional read-only remote mounts |

---

Why this order?

1. Lock down core schema & domains (links, collections, views) with a “demo” helper so users can explore right away.
2. Scale & CI unlocks safe indexing at volume, then
3. Live mode & auto-prune keep your index fresh without manual steps.
4. Content FTS + annotations builds on an efficient, reliable plumbing layer—you’ll love grep-style context snippets.
5. Versioning & semantic layers ride atop a stable full-text index and annotation system.
6. Advanced queries & workflows expand power users’ toolsets before branching into GUIs and sync.

This grouping ensures every new layer rests on a solid, tested foundation—maximizing both developer speed and user delight.