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