# demarkus-library — Roadmap & Resume

Pick-up-where-we-left-off doc. Authoritative plan is
[/plans/universe-library.md](/plans/universe-library.md); this tracks status and
the queued work. Build model: Opus 4.8 default, Fable 5 for load-bearing
transport/auth/concurrency design.

## Where we are (2026-06-12, PR #10 merged)

`main` HEAD f5c8c06 — **v0.1.0 released**: CI + Release workflows green,
tag/GitHub release created, multi-arch image at
`ghcr.io/latebit-io/demarkus-library:0.1.0`, chart at
`oci://ghcr.io/latebit-io/charts/demarkus-library --version 0.1.0`
(version==appVersion==image tag, verified). 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). **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.
- **Frontmatter strip** in markdown adapter (render-side mitigation).
- **Deploy manifests + CI/release — DONE, v0.1.0 shipped** (PR #10): root
  `.goreleaser.yml` (single-module `v` tags, goreleaser-pro `~> v2`,
  `archives.ids`) · COPY-only distroless Dockerfile · helm chart
  `deploy/helm/demarkus-library` mirroring broker chart conventions
  (replicaCount 1 + Recreate — in-memory sessions; trim-aware render-time
  validate; cleartext-vs-existingSecretRef client secret; pod-level
  automountServiceAccountToken:false; NetworkPolicy with same-namespace
  ingress + DNS/443/UDP-6309 egress; 24 helm-unittest tests) ·
  `.github/workflows/` ci.yml + release.yml (SHA-pinned actions, read-only
  default token, release-job-only write scopes, non-cancelling concurrency,
  main-ref guard on publish, chart lint/unittest gating release, tag
  rollback on failure) · **module paths migrated to latebit-io** (demarkus
  `15cc18b`; library requires client v0.12.40 + protocol v0.7.13, replaces
  dropped; library's own module renamed too) · errcheck cleanup · 13
  CodeRabbit findings addressed (11 inline + 2 outside-diff).

## 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: 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
# install in-cluster:
helm install library oci://ghcr.io/latebit-io/charts/demarkus-library --version 0.1.0 \
  --set library.broker.url=... --set library.broker.clientID=... \
  --set library.broker.existingSecretRef.name=... --set library.broker.redirectURI=... \
  --set library.broker.world=root --set ingress.enabled=true --set ingress.host=...
```

### 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, links.go (cross-world rewriting)
- `internal/adapter/outbound/{world,broker,federated,oauth,markdown}` —
  direct QUIC (token→home only), MCP pool, shape-router, broker OAuth, goldmark
- `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. In-cluster install (deploy item 1 wrap-up)
Chart + image are published. Remaining: register the library's webClients
entry in the broker chart values (clientID, sha256 of secret, redirect URI),
create the operator-managed client-secret Secret, install with broker URL /
world / ingress host / cert-manager issuer.

### 2. Broker rate limit back down (deploy-side, demarkus repo)
`rateLimit.tokens` was raised to 60/min burst 30 during the 429 incident.
Reads are now 1 request each (session pool) — drop to ~30/min burst ~15 in
the broker AppSet values.

### 3. Rendering upgrades (full split in [debt.md](/demarkus-library/debt.md))
Order: (a) chroma syntax highlighting via goldmark-highlighting — server-side,
zero JS, biggest visible win; bluemonday must allow chroma spans/classes.
(b) GFM alerts + emoji extensions. (c) Later, islands: mermaid.js + KaTeX,
vendored, degradable (ADR 0003 concessions).

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

### Standing deferred
- Backlinks / "cited by" (needs graph crawl; viz deferred).
- `mark_worlds` enumeration tool on broker → generated floor page.
- Find + fix publishers that wrote metadata fences into bodies (strip is
  render-side mitigation only).
- 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) — broker loopback
  finding, device flow rejected, confidential web client chosen) 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: Deploy manifests + CI/release shipped as v0.1.0 (PR #10);
  module paths migrated to latebit-io (demarkus `15cc18b` + library)
  ([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`.
- PR scopes: domain, port, service, web, world, markdown, cmd, view, deps,
  ci, broker, auth, session, oauth, federated, deploy, docker, helm.