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

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

Client:
- Offline mode
- Bookmarks/favorites
- Tab support

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