# 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 — IN PROGRESS

### 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)

### Not Started
Server:
- Content addressing
- Federation support

Client:
- Offline mode
- MCP `mark_append` auto-resolve `expected_version` — make it optional in the MCP tool layer; when omitted, tool internally calls VERSIONS to get the current version before appending. Protocol and client library stay unchanged. Does NOT apply to `mark_publish` (publish requires the agent to have read the document first).

## Phase 4: The Information Graph — SKETCHED

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.

Key ideas:
- **The Demarkus Hub pattern** — a server whose sole purpose is linking to content on other demarkus servers. No original content, just curated `mark://` links organized by topic. A librarian, not a library. Anyone can run a hub — no central registry. Hubs link to other hubs, creating a navigable hierarchy of curated knowledge. Because they're demarkus servers, they get versioned history, capability-based auth, and immutable audit trails for free. Agent manifests on hubs describe what the hub covers and seed graph expansion.
- **Cross-server graph crawling** — crawler already works across servers; make the graph persistent and incremental
- **Backlinks** — client-side backlink index from crawled graph; "what links here?" as a navigation primitive
- **Graph-aware navigation** — TUI shows explored topology, graph proximity for related docs
- **Graph as content** — the crawled graph is itself a markdown document with `mark://` links; export it, publish it to a demarkus server, others fetch and import it; versioned graph = history of how the network evolved; same link extraction the crawler uses can reconstruct the topology from a graph document
- **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.

## What I Think Should Come Next

The immediate next increment should be something concrete from Phase 3 or the early foundations of Phase 4. Candidates:
- **Content addressing** — fetch by hash, enabling distributed caching
- **Persistent graph** — client remembers crawled graph across sessions (foundation for Phase 4)
- **Graph export/import** — publish crawled graph as markdown to a demarkus server, fetch others' graphs
- **Backlink index** — built from crawled data, no server changes

But Fritz decides the direction.

## 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