demarkus-library

Sub-project hub for demarkus-library — the web front-end ("Universe Library") for a demarkus universe: a server-rendered Go + htmx reading room over a broker-fronted knowledge system. Standalone repo latebit-io/demarkus-library, own release cadence (mirrors obsidian-demarkus).

All durable knowledge about this project lives under /demarkus-library/. This hub is the discovery backstop — keep it current.

Source of truth

• Plan — Universe Library — the authoritative plan (architecture, identity model, phases 0–5, build-model strategy, resolved decisions, open questions). Fetch this first in any new session.

Sections

• Architecture — app structure, transport, MCP-client/session model, render pipeline (TBD)
• Decisions (ADRs) — one file per decision at adr/<NNNN>-<title>.md
  • ADR 0001 — Echo + bulwarkauth-style layout
• Patterns — Go + htmx + goldmark idioms, conventions (TBD)
• Debugging — bugs, gotchas, investigations (TBD)
• Roadmap / status — phase progress, what's in flight (TBD)
• Debt — technical debt, deferred work (TBD)
• Journal — session notes, one file per day at journal/<YYYY-MM-DD>.md
  • 2026-06-10 — Phase 0 shipped

Status

• Phase 0 — Foundation spike: DONE (2026-06-10). A real demarkus doc renders server-side in a browser. Echo v5.1.1 app (bulwarkauth layout, ADR 0001) reads a world over QUIC via the real demarkus fetch client, renders markdown through goldmark + bluemonday, serves HTML. Routes: / (default doc), /d/<path>, /health. Unit tests green. Verified live against soul.demarkus.io:6309.
• Phase 1 — Library card + reading room: next. Broker OAuth (org-scoped) + world directory, LIST tree, LOOKUP catalog, VERSIONS, backlinks. First sub-step: swap the direct-QUIC fetch client for an MCP client over the broker + OAuth session.

Repo layout (Phase 0)

• cmd/demarkus-library/ — entry point (main.go) + env config (config.go).
• api/health/, api/reading/ — Echo handlers + routes per domain.
• internal/library/ — the librarian service: FETCH over QUIC + goldmark/bluemonday render.
• internal/view/ — echo.Renderer over embedded html/template.
• replace directives point demarkus client/protocol at local ../demarkus.

Open questions

• Does the broker expose any anonymous-readable surface? Decides whether Phase 1 hits the broker directly vs a dev world for unauthenticated reads. (See plan.) Not blocking — Phase 0 read a world directly over QUIC.

Stack (decided)

Server-rendered Go (Echo v5 + html/template + htmx), goldmark + bluemonday for markdown→sanitized HTML, MCP client over the broker MCP gateway (Phase 1+), org-scoped OIDC (auth-code/PKCE/DCR), tokens server-side only. Single Go binary, no Node build. Go 1.26.4. Build on Opus 4.8 by default; Fable 5 as the escalation valve.