# demarkus-library — Roadmap & Resume

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

## Where we are (2026-06-12 late — v0.1.2 on main, R1 on branch)

`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). ADR 0005 accepted. **Reading Room R1 (the
Tufte pane) BUILT on `feature/reading-room-r1`, acceptance VERIFIED in both
transports** — staged, awaiting Fritz's commit/PR. Details in
[journal 2026-06-12](/demarkus-library/journal/2026-06-12.md).

- **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; env saved at
  `~/.config/demarkus-library/dev.env`, **client id `library-web-dev`** —
  dedicated dev client registered 2026-06-12 after the prod rotation
  stranded the old creds). **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
  (v2 now also exercises sidenotes + frontmatter properties + status axis).
- **Reading Room R1 — the Tufte pane: BUILT + ACCEPTED** (2026-06-12, branch
  `feature/reading-room-r1`): 60ch column + 250px margin (Charter serif,
  off-white/off-black, booktabs tables) · pinned margin metadata (status
  badge — metadata `status:` tag axis → frontmatter fallback → draft; tag
  links; provenance; parsed-frontmatter properties; `mark://` + raw-source
  escape) · sidenote goldmark extension (footnote syntax → margin spans;
  multi-paragraph/multi-ref degrade to footnotes) · `WorldGateway.Lookup`
  filter arg + lookup-backed tag pages `/w/:world/tags/:tag` · raw route
  `/w/:world/raw/*` (text/plain) · **nav search box removed** (decision 5) ·
  authoring contract (decision 13) published at
  `mark://soul.demarkus.io/.well-known/library/authoring.md` (+ repo
  `docs/authoring-contract.md`). **Acceptance verified live in BOTH
  transports (decision 16)**: quic against soul.demarkus.io; broker via
  full login through broker.knowledge.demarkus.io with the new
  `library-web-dev` client (Fritz click-through 2026-06-12).

## How to resume

```sh
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: source ~/.config/demarkus-library/dev.env && /tmp/dl
# (full recipe in journal 2026-06-11; OAuth endpoints live on
#  broker.knowledge.demarkus.io — the bare domain 404s /oauth/authorize)
# 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/Tag/Raw
- `internal/adapter/inbound/web` — Echo handlers/routes (`/w/:world/...` incl.
  tags + raw), 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/sidenotes/frontmatter +
  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`
- `docs/authoring-contract.md` — source of the in-universe authoring contract

## Next sessions — queued work

### 0. R1 tail
Fritz: commit/PR `feature/reading-room-r1` (staged, accepted both
transports). Visual polish round (spacing, dark mode, sticky-meta vs long
sidenotes) by eyeball — fold findings into the PR or a fix branch.

### 1. 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. Trail
format documentation ships with R2 (decision 14).

### 2. Universe view research (alongside 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.

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

### 4. 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](/demarkus-library/plans/phase-1b-web-sso.md),
  [ADR 0004](/demarkus-library/adr/0004-broker-web-sso.md)) 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](/demarkus-library/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 ·
  **R1 Tufte pane built on `feature/reading-room-r1` + accepted in both
  transports** (sidenotes, margin trust signals, tag pages, raw escape, no
  search box, authoring contract in-universe; `library-web-dev` broker
  client registered for local e2e)
  ([journal](/demarkus-library/journal/2026-06-12.md)).

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