soul.demarkus.io:6309/demarkus-library/roadmap.md/v12 draft reader meta

demarkus-library — Roadmap & Resume

Pick-up-where-we-left-off doc. Authoritative plan is /plans/universe-library.md; the Reading Room redesign lives in /plans/reading-room.md (invariants locked in ADR 0005). Build model: Opus 4.8 default, Fable 5 for load-bearing design.

Where we are (2026-06-12 end of day — v0.1.2 on main)

main HEAD 1f68dac. Library is in the cluster (Fritz installed 2026-06-12). Released: v0.1.0 (deploy/CI), v0.1.1 (chroma/alerts/emoji), v0.1.2 (mermaid/KaTeX islands). Reading Room redesign designed + locked (ADR 0005) — spatial trails, Tufte pane, catalog/graph-as-pane, no search box. Details in journal 2026-06-12.

  • Phase 0 foundation spike · Phase 1a reading room (stacks, card catalog, editions, link rewriting, htmx fragment-vs-page).
  • Phase 1b — library card: DONE. Broker confidential web clients (demarkus 117e2a6) · oauth client (PKCE S256, Basic auth with §2.3.1 escaping) · server-side sessions + single-flight refresh · ctx threading on ports · broker MCP WorldGateway with per-reader pooled sessions (1 request per read; fixed the live 429s) · login turnstile (/login, /login/start, /auth/callback, /logout; HX-Redirect for htmx) · composition-root swap DEMARKUS_TRANSPORT=quic|broker · native TLS serving for local e2e (mkcert + hosts-file recipe in journal 2026-06-11). E2e verified live.
  • Multi-world floor + federation (fc4277c): (world, path) addressing, /w/<world>/... routes, federated composite gateway — knowledge-system names via broker, host[:port] via direct QUIC (DEMARKUS_FEDERATION, default true, strict parse). Read token never leaves home host (test-pinned). Cross-world mark:// links clickable; root hub = the floor.
  • Deploy manifests + CI/release — DONE, v0.1.0 (PR #10): goreleaser-pro, COPY-only distroless Dockerfile, helm chart (replicaCount 1 + Recreate — in-memory sessions), hardened workflows (SHA-pinned actions, scoped tokens, concurrency, main-ref guard, tag rollback). Module paths on latebit-io (client v0.12.40 + protocol v0.7.13, no replaces). Library installed in-cluster; library-web client secret was rotated (hash-only storage — plaintext lost as designed).
  • Rendering — DONE end to end (PRs #11 v0.1.1 + #12 v0.1.2): chroma classes-mode highlighting (allowlist built from chroma.StandardTypes; generated chroma.css light/dark) · GFM alerts (gm-alert-callouts, emoji icons, light-dark() palette) · goldmark-emoji · mermaid 11.15.0 + KaTeX 0.17.0 islands (ADR 0003 concessions recorded; ~3.7MB vendored; lazy failure-aware loader islands.js, re-scans on htmx:afterSettle; degrades to source). Scratch test card: /demarkus-library/scratch/rendering-demo.md.
  • Reading Room — DESIGNED, ADR 0005 accepted (2026-06-12): spatial trail (stack-in-URL, truncate-and-append, panes/spines), Tufte column + working margin (status trust badge, tags, provenance, parsed-frontmatter properties, sidenotes via footnote transform), catalog-as-pane (search box removed; lookup stays one click away inside the trail), graph-as-pane ("add into context, not break out"), rendered-HTML cache required (rate limit). Phasing R1→R2→R3 below.

How to resume

cd ~/latebit/demarkus-library && go test ./... && go build -o /tmp/dl ./cmd/demarkus-library
# quic mode (no auth, soul world):
PORT=8080 DEMARKUS_INSECURE=true DEMARKUS_HOST=soul.demarkus.io \
  DEMARKUS_AUTH=<token from .mcp.json> /tmp/dl
# broker mode: env per config.go (BROKER_URL, CLIENT_ID/SECRET, REDIRECT_URI,
# WORLD=root, TLS_CERT/KEY for local https) — full recipe in journal 2026-06-11.
# chart checks:
helm lint deploy/helm/demarkus-library && helm unittest deploy/helm/demarkus-library

File map (hexagonal — ADR 0002)

  • internal/core/{domain,port,service} — entities, ports (ctx+world on every method), Read/Browse/History/Search
  • internal/adapter/inbound/web — Echo handlers/routes (/w/:world/...), auth turnstile, session pkg, templates (page/content/login), links.go, static/ (htmx, islands.js, generated chroma.css, vendor/ mermaid+katex)
  • internal/adapter/outbound/{world,broker,federated,oauth,markdown} — direct QUIC (token→home only), MCP pool, shape-router, broker OAuth, goldmark (chroma/alerts/emoji/passthrough + bluemonday allowlists)
  • internal/adapter/bearer — ctx token contract between middleware & gateway
  • cmd/demarkus-library — composition root, AppConfig, brokerAuth shim
  • deploy/helm/demarkus-library — chart · .goreleaser.yml + Dockerfile at root · .github/workflows/{ci,release}.yml

Next sessions — queued work

1. Reading Room R1 — the Tufte pane (per ADR 0005 / plans/reading-room.md)

Single-doc redesign: 60ch column + ~250px margin, pinned metadata block (status badge from metadata tag axis w/ frontmatter fallback, tags, provenance), parsed-frontmatter properties (replace strip-and-discard), sidenote transform (footnote syntax → margin spans), booktabs tables, off-white/off-black, remove nav search box, add tag pages (lookup-backed). Ships alone — the look + trust model.

2. Reading Room R2 — the trail engine

Stack URL (/t/... path segments, cap 10), canvas + panes + spines, truncate/dedup/focus, active-link highlight, rendered-HTML cache keyed (world, path, version) — HARD REQUIREMENT (rate-limit math in plan), scroll-into-view snippet, overscroll-behavior-x. Catalog-as-pane.

3. Universe view research (alongside R1/R2)

What a special universe-scale graph view looks like — graph-as-pane at max zoom = the floor/pane zero. Research rendering approaches (likely the pre-agreed canvas island), zoom/aggregation at scale. Needs broker mark_worlds tool (demarkus repo — authorizedWorlds(cfg, claims) exists in authz.go; tool surface in mcp_tools_list.go/mcp_gateway.go, exploration started). Record findings in plans/reading-room.md before building.

4. Reading Room R3 — previews + backlinks + graph pane

Hover preview cards (htmx fragments, one component both directions), backlinks margin block (data source decision: broker graph persistence vs library-side crawl), graph neighborhood pane.

5. Phase 2 — restricted collections (per /plans/universe-library.md)

Per-world/per-path authorization surfaced in the reading room. Depends on broker-side authz semantics — re-read the plan + broker authz.go first.

Maybe / observed

  • Semver quirk: PaulHatch minor_pattern: "feat:" is substring — feat(scope): bumps PATCH not minor. Fix via regex /^feat(\(.+\))?:/ in library + demarkus workflows if desired.
  • Broker rate-limit drop (60/30 → 30/15) on demarkus-knowledge-system-deploy branch fix/broker-rate-limit-down — status unknown, confirm merged/synced.

Standing deferred

  • Find + fix publishers that wrote metadata fences into bodies (R1's friendly-frontmatter rendering reduces the harm; source fix still open).
  • Shared session store (or sticky sessions) → unlock replicaCount > 1 + RollingUpdate + PDB in the chart.
  • Adopt demarkus's strict .golangci.yml (18 issues to clean first).
  • Phase 3 cataloging desk (writes, CodeMirror island) · Phase 4 AI librarian (SSE) · Phase 5 public face.

History (condensed — details in journals + ADRs)

  • 2026-06-10: Phases 0 + 1a built and merged (PRs #1–2).
  • 2026-06-11: Phase 1b planned (plan, ADR 0004) and fully shipped (PRs #3–#9); floor + federation; frontmatter strip. Key endpoint facts: token = /device/token, authorize = /oauth/authorize, /mcp always bearer-gated, no refresh rotation. Gotchas in debugging.md.
  • 2026-06-12: v0.1.0 deploy/CI (PR #10) · latebit-io module migration · in-cluster install + client-secret rotation · broker rate-limit drop prepped · v0.1.1 chroma/alerts/emoji (PR #11) · v0.1.2 mermaid/KaTeX islands (PR #12, ADR 0003 updated) · Reading Room designed + ADR 0005 (journal).

Git / process notes

  • Work on feature/* / fix/* branches. Never auto-commit — Fritz commits and opens PRs; CodeRabbit reviews via .coderabbit.yaml (static/vendor/** excluded from review — vendored payloads).
  • PR scopes: domain, port, service, web, world, markdown, cmd, view, deps, ci, broker, auth, session, oauth, federated, deploy, docker, helm.
trail
  1. soul.demarkus.io:6309 v12