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). As an MCP client to the broker it reuses the broker's existing session model — the same path Claude Code's MCP SDK already takes; no new session design.
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.

Identity model

Access is organization-scoped: the library card is your org identity via the broker's OIDC (e.g. GCP org). No anonymous public tier for now — you need a card to enter your org's universe. The exact card-issuance UX is deliberately left open; the firm decision is the scope (per-organization), not the mechanism. Consequence: the org login is the turnstile, so it lands in Phase 1, not later.

Phases

Phase 0 — Foundation spike

Repo, stack, and one doc on screen end-to-end. De-risks transport + rendering + CORS + MCP session handling before any UI investment. Stays auth-free by pointing at a local/dev world (or a public doc if one exists), so OAuth is deferred to Phase 1.

New repo latebit-io/demarkus-library; CI, license, README.
BFF skeleton: one endpoint proxying FETCH of a doc to JSON.
SPA skeleton: render that doc's markdown.
Exit: a real demarkus doc renders in a browser via the BFF.

Phase 1 — Library card + reading room

Org login is the turnstile; then browse and read the org's universe. Read-only.

Library card: broker OAuth (auth-code + PKCE + DCR), org-scoped; cookie session to the SPA; tokens BFF-only. Login/logout.
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: an org member logs in, browses, searches, reads, and traces citations across the org's universe.

Phase 2 — Restricted collections (within-org)

Finer-grained access on top of "you're in the org."

Per-path read-auth respected: locked collections shown, unlocked when the token permits.
Per-user surface: home, recently read, bookmarks.
Exit: a user sees only the collections their token permits within their org.

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

Transport: Go BFF over the broker MCP gateway. (Alt considered: SPA-direct MCP — rejected for token exposure + clunky UI consumption.)
Auth: organization-scoped OIDC (e.g. GCP org); no anonymous public tier for now. 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).

Resolved (2026-06-10)

Library card: scope it to organizations (per-org OIDC, e.g. GCP org). Issuance UX deferred; scope is the firm part. No anonymous public tier — auth becomes the Phase 1 turnstile.
World enumeration: the root hub is the world directory for v1. Caveat: it is hand-maintained, so an unlisted world is invisible; add a broker enumeration endpoint later only if the hub drifts.
MCP session model: same as the broker — the BFF is an MCP client over the broker's existing session path (the route Claude Code's SDK already uses). No new session design.

Open / still to confirm

Whether the broker exposes any anonymous-readable surface at all (only affects whether the Phase 0 spike can hit the broker directly vs a local dev world).

Naming

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