# Roadmap

Where demarkus has been and where it's going.

## Phase 1: MVP (Read-Only) — COMPLETE

Everything shipped:
- QUIC server serving markdown files
- FETCH, LIST, VERSIONS verbs
- TUI client with Bubble Tea + Glamour
- Link following, navigation history
- Document graph visualization
- CLI client with all verbs
- MCP integration for LLM agent access
- Docker multi-arch images
- GoReleaser CI/CD with per-module versioning
- Conditional fetch (if-none-match, if-modified-since)
- SIGHUP certificate reload

## Phase 2: Publish Operations — COMPLETE

Done:
- PUBLISH verb with version creation
- ARCHIVE verb
- APPEND verb — sends only new content, server handles concatenation
- Capability-based auth (token generation, SHA-256 hashes, path/op scoping)
- Versioned store with symlinks and hash chain
- Document editing via $EDITOR
- Client-side token management
- Conflict resolution (optimistic concurrency with expected-version)
- No-op on duplicate content
- Structured logging with slog (replaced console logging)
- Protocol-level size limits (1 MiB body, 64KB frontmatter)
- Audit logging with token_label on all write operations
- Usability audit: documentation accuracy, CLI help, install script cleanup, CI lint

Phase 2 is fully complete. No remaining items.

## Phase 3: Agent-Native & Advanced Features — COMPLETE

Done:
- Agent manifest discovery (`/.well-known/agent-manifest.md`)
  - Convention spec: markdown document at well-known path, no server changes needed
  - `WellKnownManifestPath` constant in protocol module
  - `mark_discover` MCP tool — fetches manifest from connected server
  - `demarkus info` CLI subcommand — fetches and displays manifest
  - Spec doc at `docs/site/reference/agent-manifest.md`
  - First live manifest published on demarkus-soul
  - Directory listing for servers (auto-generated when no index.md)
- Bookmarks/favorites
  - Markdown-backed store at `~/.mark/bookmarks.md`
  - TUI: `b` toggle, `B` view, `Esc` exit, star indicator in status bar
  - CLI: `bookmark add/remove/list` subcommands
  - MCP: not exposed (local-only feature)
- MCP `mark_append` auto-resolve `expected_version`
  - `expected_version` is now optional in `mark_append` — when omitted or 0, the tool calls VERSIONS to get the current version automatically
  - Optimistic concurrency still enforced — the server always receives an `expected_version`
  - Introduced `markClient` interface for handler testability
  - Tests cover auto-resolve (happy path), not-found, explicit version, negative version, no token
  - Does NOT apply to `mark_publish` (publish requires the agent to have read the document first)
- Content-addressed fetch
  - FETCH responses include `content-hash: sha256-<64hex>` — SHA-256 of the stripped body
  - `FETCH /sha256-<64hex>` retrieves documents by content hash from any server that has them
  - In-memory hash index (`map[string]string`) built on startup, updated on writes/archives
  - Current versions only, archived docs excluded
  - No new verbs — FETCH handles it via path pattern detection
  - Foundation for distributed mirroring and caching
- Federation via MCP tools
  - `mark_index` — crawls a source server, collects content hashes, publishes index to a hub
  - `mark_resolve` — resolves content by SHA-256 hash using a hub index document
  - `client/internal/index` package — Parse, Build, Merge for markdown hash index documents
  - Manifest check enforced by tool, `force` override, `dry_run` mode, 1000 doc cap

### Deferred
- Offline mode (client) — moved to backlog, not blocking anything

## Phase 4: The Information Graph — IN PROGRESS

Discovery through linking, not searching. Information is findable because it's connected — servers link to each other through documents, clients and agents traverse the graph.

### Done
- **The Demarkus Hub pattern** — live at `mark://hub.demarkus.io`. A server whose sole purpose is linking to content on other demarkus servers. No original content, just curated `mark://` links organized by topic. CI auto-publishes from Git repo. See [github.com/latebit-io/demarkus-hub](https://github.com/latebit-io/demarkus-hub).
- **Persistent graph store** — `client/internal/graphstore` package. Graph stored as JSON at `~/.mark/graph.json` with nodes (documents), edges (links), etags, and crawl timestamps. Atomic writes, schema versioning, incremental merge.
- **Shared `CrawlAndPersist`** — unified crawl + merge + save method on `*Store`, nil-safe. All three clients (CLI, TUI, MCP) share the same code path. `EtagFetcher` adapter collects etags during crawl.
- **Backlinks** — `mark_backlinks` MCP tool and `Store.Backlinks()` method. Reverse edge lookup from the persistent graph — "what links here?" Returns sorted list with document titles.
- **Graph seeding from store** — TUI graph view loads instantly from stored graph while crawl runs in background.
- **Graph as content** — export the persistent graph as a publishable markdown document. `Store.Export()` renders nodes as markdown table rows with `mark://` links, edges as a separate table. `ParseExport()` parses it back. CLI: `demarkus graph export [-o file.md]`. MCP: `mark_graph_export` tool. Crawling the exported doc naturally discovers the topology — no special import needed. Cell escaping handles pipes and backslashes in titles.

### Not Started
- **Graph-aware navigation** — TUI shows explored topology, graph proximity for related docs
- **Agent discovery** — agents crawl the graph to build knowledge maps; share and merge published graph documents to accelerate discovery

No new verbs needed. FETCH reads content, LIST enumerates, links connect. The protocol already has the primitives.

See DESIGN.md Phase 4 section for full sketch.

## Verb Set — Complete

The protocol verb set is finalized at 6 verbs: FETCH, LIST, VERSIONS, PUBLISH, APPEND, ARCHIVE. SEARCH was removed from the spec — full-text search is better handled as an external tool built on top of the existing primitives (LIST + FETCH) rather than as a protocol-level concern.

## Distribution & Package Management — PLANNED

Homebrew tap for easier installation, especially on macOS and Linux developers.

**What it takes:**
1. Create public `latebit/homebrew-demarkus` tap repo
2. Add formula for `demarkus-client` (CLI + TUI) — pull pre-built binaries from GitHub releases
3. Formula needs SHA256 checksums for each architecture
4. Update README with Homebrew install instructions
5. Test installation on macOS and Linux

**Notes:**
- Server is better deployed via Docker, keep Homebrew focused on the client
- Start with tap (owned by us), not Homebrew Core (requires upstream submission)
- User installs: `brew tap latebit/homebrew-demarkus && brew install demarkus-client`
- Already have GoReleaser CI/CD and multi-arch builds — just need packaging

## Build Targets

Supported platforms: macOS, Linux, Windows (WSL only — runs Linux binaries). Native Windows builds removed from GoReleaser configs.