soul.demarkus.io:6309/plans/universe-library.md/v1 draft reader meta

Universe Library — Plan

The web front-end for a demarkus universe: a reading room over a broker-fronted knowledge system. Renders the library metaphor demarkus already has (bookshelf server, librarian agent, LOOKUP card catalog, worlds-as-collections) into a human-facing web app, so a newcomer can browse a universe and have the architecture explain itself. Lives in its own repo on its own release cadence, like the Obsidian plugin.

Why

Every demarkus surface today is agent- or terminal-facing (CLI, TUI, MCP, Obsidian, the Claude Code plugins); the one third-party GUI (Caztor) is view-only FETCH. There is no human-facing web view — the real barrier to understanding demarkus. A universe library lowers that barrier by being self-explanatory: walk in, browse the stacks, search the catalog, watch the librarian work.

Non-goals (hard)

  • Not a Notion clone. No block model, no relational databases/views, no live multiplayer co-editing — each fights the dumb-server / whole-doc-immutable-version core.
  • Editing is a cataloging desk: whole-doc PUBLISH to a new edition (version). Concurrency via the existing conflict-aware merge, not OT/CRDT.
  • Metaphor is information architecture, not skeuomorphic chrome. No bookshelf textures, no page-flip animation.

Architecture

A browser cannot speak QUIC/Mark. Go through the broker, which already terminates HTTPS, owns identity (OIDC + auth-code/PKCE/DCR), and proxies the 14-tool MCP surface to worlds.

Browser SPA  --REST + cookie-->  BFF (Go)  --MCP / HTTPS-->  Broker  --QUIC-->  Worlds
 React/TS                        REST-over-MCP adapter,      identity,          bookshelves
 markdown render                 OAuth session, catalog cache world routing
  • SPA: React + TypeScript + Vite. Markdown via remark/react-markdown + GFM. Pure presentation; holds no tokens.
  • BFF (Go): keeps the project in-family and can later share the protocol package if we ever go direct-QUIC. Owns the human OAuth session (tokens never reach the browser — the XSS boundary), projects clean REST over the broker's MCP JSON-RPC, caches the LOOKUP catalog. A thin adapter, not a second brain — the librarian principle still holds (intelligence stays at the edge/agent).
  • Why BFF over SPA-direct-MCP: tokens off the client; clean REST instead of MCP JSON-RPC in UI code; CORS controlled; server-side render of public docs later for shareable links.

Phases

Phase 0 — Foundation spike

Repo, stack, and one doc on screen end-to-end through the broker. De-risks transport + rendering + CORS + MCP session handling before any UI investment.

  • New repo latebit-io/demarkus-library; CI, license, README.
  • BFF skeleton: one endpoint proxying FETCH of a public doc from the broker MCP gateway to JSON.
  • SPA skeleton: render that doc's markdown.
  • Exit: a real knowledge.demarkus.io doc renders in a browser via the BFF.
  • Resolve the open questions below (public-read? world-list source? MCP session model).

Phase 1 — The reading room (read-only, public)

Browse and read a universe's public collections. No auth yet.

  • World list / floor directory from the root hub.
  • Stacks: per-world LIST path tree, navigable.
  • Document view: rendered GFM; rewrite mark://<world>/<path> links to in-app navigation.
  • Card catalog: LOOKUP search UI (subject to ranked table to click-through).
  • Editions: VERSIONS panel; view a historical version.
  • Citations: backlinks panel (mark_backlinks); a lightweight "cited by" list (defer force-directed graph viz).
  • Exit: a visitor browses, searches, reads, and traces citations across a universe's public docs.

Phase 2 — Library cards (auth + restricted collections)

  • BFF owns broker OAuth (auth-code + PKCE + DCR); cookie session to the SPA; tokens BFF-only.
  • Login/logout ("get a library card").
  • Per-path read-auth respected: locked collections shown, unlocked on auth.
  • Per-user surface: home, recently read, bookmarks.
  • Exit: a logged-in user reads the private collections their token permits; anonymous users see only public.

Phase 3 — The cataloging desk (writes)

  • Whole-doc markdown editor; PUBLISH on save to a new edition.
  • Conflict-aware merge surfaced in the UI (existing diff3) on concurrent edits.
  • Create new document; archive (deaccession) soft-delete.
  • Metadata/cataloging editor: title + tags + importance (feeds LOOKUP — cataloging literally improves the catalog).
  • Exit: a librarian creates, edits, re-catalogs, and archives docs from the browser; whole-doc, version-per-save.

Phase 4 — The AI librarian (the differentiator)

  • Embedded assistant driving the same MCP tools (LOOKUP/FETCH/graph/VERSIONS) to answer natural-language questions, summarize a wing, trace citations.
  • Streaming chat; visible tool-call trace — watch the librarian work the catalog.
  • Claude via the API with the broker MCP surface wired as tools (MCP connector / tool use).
  • Lands here because it needs a furnished building to work in.
  • Exit: "where's our deploy runbook?" returns the doc with its catalog reasoning shown.

Phase 5 — Public face & polish

  • Universe home as front-of-house: featured collections, recent acquisitions (recent publishes), most-cited.
  • Server-side render / prerender of public doc URLs — shareable links that render, with OpenGraph cards. The adoption payoff: a shared link explains demarkus on open.
  • Catalog caching, accessibility, mobile reading, theming.

Cross-cutting decisions (recommended, confirm in Phase 0)

  • Transport: Go BFF over the broker MCP gateway. (Alt considered: SPA-direct MCP — rejected for token exposure + clunky UI consumption.)
  • Auth boundary: tokens in the BFF only; the SPA holds a cookie session.
  • Graph viz: backlinks list first; force-directed graph deferred past v1.
  • Repo: standalone latebit-io/demarkus-library, own cadence (mirrors obsidian-demarkus).

Open questions — resolve in Phase 0

  1. Public reads: does the broker MCP gateway serve unauthenticated FETCH/LIST/LOOKUP for public paths, or is a token always required? If always-token, Phase 1 needs a read-only service identity, or auth moves up from Phase 2.
  2. World enumeration: how does the BFF learn a universe's worlds — a broker endpoint, mark_discover/mark_index, or solely the root hub document? Determines the floor-directory source.
  3. MCP session model from a stateless BFF: per-request vs pooled streamable-HTTP sessions against the gateway.

Naming

Repo demarkus-library (working). Product-name candidates: Athenaeum, Stacks, the Reading Room, or literal "demarkus Library". TBD — not load-bearing.

trail
  1. soul.demarkus.io:6309 v1