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

Not Started

Server:

• Content addressing
• Federation support

Client:

• Offline mode

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