# 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-13 — R1 + R2 MERGED)

`main` HEAD 11732ed (**R2 merged, PR #14**; R1 was PR #13). Library is in
the cluster (running pre-R1 v0.1.2 until the next release/rollout).
Released: v0.1.0 (deploy/CI), v0.1.1 (chroma/alerts/emoji), v0.1.2
(mermaid/KaTeX islands); **R1+R2 on main, not yet released**. Both phases
accepted live in BOTH transports (decision 16). 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 · GFM alerts · goldmark-emoji · mermaid + KaTeX
  islands (lazy failure-aware islands.js; degrades to source). Scratch test
  card: /demarkus-library/scratch/rendering-demo.md (v2 exercises sidenotes
  + frontmatter properties + status axis).
- **Reading Room R1 — the Tufte pane: MERGED (PR #13), accepted both
  transports.** 60ch column + 250px margin · pinned margin trust signals
  (status badge: metadata `status:` tag axis → frontmatter fallback →
  draft; tags; provenance; parsed-frontmatter properties; `mark://` +
  raw-source escape) · sidenote goldmark extension (footnote syntax →
  margin spans; multi-paragraph/multi-ref degrade) · lookup-backed tag
  pages + `WorldGateway.Lookup` filter · `/w/:world/raw/*` · search box
  removed · authoring contract published
  (`mark://soul.demarkus.io/.well-known/library/authoring.md`). CodeRabbit
  round hardened the frontmatter strip (fence must parse as YAML mapping).
- **Reading Room R2 — the trail engine: MERGED (PR #14), accepted both
  transports** (build decisions in plans/reading-room.md §"R2 build
  decisions"):
  - Trail URL `/t/<pane>/~/<pane>?focus=i` — pane chunk = /w/ route tail
    (`<world>/d/<path>` | `<world>/tags/<tag>` | trailing slash listing),
    `~` reserved separator, raw slashes, cap 10 (parse 400s; click drops
    oldest). Pure codec + click algebra (truncate/append, dedup→focus,
    spine→focus) in web/trail.go.
  - Rendered-document cache (decision 9): port.DocumentCache + LRU adapter;
    Read/Browse/Tag cachePut; ReadCached/BrowseCached/TagCached read
    through. **Focused-live policy: every click costs exactly 1 world
    read** — focused pane fetched live, parents cached.
  - Canvas: spines (vertical title + badge) / body-only parent (sidenotes
    hidden) / focused full Tufte pane (only it gets the margin). Tombstone
    spine for unreadable unfocused panes (stale shared trails survive).
    trailizeLinks post-process: /w/ hrefs → post-click trail URLs;
    active-link class marks the open link (the breadcrumb). `/` 302s to
    the default one-pane trail; /w/ remains permalinks + escapes.
    overscroll-behavior-x; scroll-focused-into-view rides islands.js
    (named ADR 0005 concession).
  - Trail format spec (decision 14) published:
    `mark://soul.demarkus.io/.well-known/library/trails.md` + repo
    docs/trail-format.md.
  - CodeRabbit note for posterity: its "wg.Go doesn't compile" finding was
    stale-knowledge (`sync.WaitGroup.Go` is stdlib since Go 1.25) —
    rebutted on-thread rather than "fixed".

## 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.
#  If the bind fails: an older run may hold :8443 — lsof -ti :8443.)
# 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 + *Cached variants,
  DocumentCache port
- `internal/adapter/inbound/web` — Echo handlers/routes (`/t/*` canvas,
  `/w/:world/...` permalinks incl. tags + raw), trail codec/click algebra
  (trail.go) + trailize pass (trail_links.go) + canvas handlers, auth
  turnstile, session pkg, templates (page/content/canvas/login; shared
  head/nav/doc-meta), links.go, static/ (htmx, islands.js incl. focused-pane
  scroll, chroma.css, vendor/)
- `internal/adapter/outbound/{world,broker,federated,oauth,markdown,cache}` —
  direct QUIC (token→home only), MCP pool, shape-router, broker OAuth,
  goldmark (chroma/alerts/emoji/passthrough/sidenotes/frontmatter +
  bluemonday allowlists), LRU document cache
- `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 + trail-format.md (sources of the
  in-universe `/.well-known/library/` docs)

## Next sessions — queued work

### 0. Release + polish tail
- Cut a release with R1+R2 and roll the cluster (mind the PaulHatch semver
  quirk below — `feat(scope):` bumps PATCH; decide if these deserve a real
  minor bump via a plain `feat:` commit or the regex fix).
- Visual polish round by eyeball (pane widths/gaps, spine legibility, dark
  mode, canvas scroll feel, sticky-meta vs long sidenote docs).

### 1. Universe view research (next build item)
What a special universe-scale graph view looks like — graph-as-pane at max
zoom = the floor/pane zero. Research rendering approaches (likely ADR
0003's 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.

### 2. 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 (continues the trail —
decision 4). Librarian-consumes-trail (decision 15) lands with Phase 4.

### 3. 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 — note the R2 document cache is also per-pod (fine at
  replicaCount 1; revisit together).
- Adopt demarkus's strict `.golangci.yml` (18 issues to clean first).
- Phase 3 cataloging desk (writes, CodeMirror island) · Phase 4 AI librarian
  (SSE; joins the canvas as a pane, trail = its context) · 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 · v0.1.1 chroma/alerts/emoji
  (PR #11) · v0.1.2 mermaid/KaTeX islands (PR #12) · Reading Room designed
  + ADR 0005 · **R1 Tufte pane merged (PR #13)** · **R2 trail engine merged
  (PR #14)** — both accepted live in both transports; authoring contract +
  trail format published 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.