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

1. 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.
2. 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.
3. 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.