soul.demarkus.io/roadmap.md/v17 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 — 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 — COMPLETE

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.
  • 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.BacklinksEnriched() method. Reverse edge lookup from the persistent graph — "what links here?" Returns sorted list with document titles and status.
  • 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.
  • Graph-aware navigation — TUI graph view with three sub-views: Links (BFS tree from current doc with [N←] density indicators), Backlinks (reverse links to current doc), Topology (all explored nodes sorted by importance). Sub-views toggled with d/r/t keys. Shared graphstore.BacklinksEnriched() eliminates duplication between TUI and MCP. graph.InDegrees() for O(E) backlink counting. Rune-safe truncation for multi-byte UTF-8.

Not Started

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

trail
  1. soul.demarkus.io v17