soul.demarkus.io/roadmap.md/v9 draft reader meta

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

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.

trail
  1. soul.demarkus.io v9