# 2026-07-24

## Durable docs brought current with the last week of merges

Fritz flagged that the knowledge base lagged the repo. Journals were current through 07-23 but the durable docs had not absorbed them:

- /roadmap.md (v63): two new DONE sections. "Five-Minute Appliance & Install Hardening" (PRs #267, #269 install-stack.sh, #270 library HTTPS :443, #271 self-dial probe, #272 cert renewal re-run fix, plus the droplet migration ops note) and "Markdown-Only Content Contract" (PR #273). Also: scope section now notes the contract is enforced, plugin section updated to v0.13.5 current with the #264-#275 pin-bump entries, v0.13.0 join URLs marked shipped (#261), docs-hygiene entry for the website refresh (07-23 pages branch).
- /architecture.md (v17): new "Markdown-Only Content Contract" design decision under Key Design Decisions, recording the layer split (handler owns the .md rule, store owns the UTF-8 invariant via ValidateBody in both backends plus conformance case, MCP owns render refusal, transport stays byte-faithful) and the two invariants (UTF-8 concatenation, lowercase-only .md).

The org knowledge system (knowledge.demarkus.io) needed nothing: its worlds are the mortgage demo content, not demarkus development docs.

## Pins bumped and soul droplet upgraded

Deploy repo pins updated on branch chore/bump-pins-markdown-contract (Fritz committed): worlds 0.20.0 to 0.22.0 (markdown-only contract), broker 0.12.4 to 0.14.3, agent 0.21.3 to 0.24.0, library 0.22.0 to 0.23.0. Comment convention in the applicationsets kept (one "why" line per version, checked against the actual git ranges).

soul.demarkus.io droplet upgraded by pushing the repo's current install.sh over scp (GitHub raw was flaky; releases downloaded fine) and re-running `install.sh --domain soul.demarkus.io --root /srv/soul --with-library`. Server 0.21.0 to 0.22.0, client/tools binaries to 0.24.0/0.14.3, kept tokens/config/certs honored, self-dial OK, library restarted on :443. First live re-run exercising the #272 renewal-hook idempotency: "Certbot renewal cron already configured / already restarts the library" both correct. Contract verified live: mark_publish to /contract-check.png returned bad-request, no version created. The known sshd MaxStartups bot churn caused one connection reset; a retry loop around scp handled it.

Gap carried forward: the broker gateway has no UTF-8 render guard (#273 only guarded local demarkus-mcp); needs a monorepo issue.

Broker render-guard gap filed as monorepo issue #276 (low urgency: worlds at 0.22.0 close the ingress; the guard is the backstop for hand-written store bytes and pre-0.22.0 worlds behind a broker).

## Knowledge system rolled (2026-07-25)

Deploy PR #120 merged with all four pins (title omits library but 0.23.0 is on main). Argo synced; verified end to end with the same probe used on the droplet: mark_publish of /contract-check.png against mark://root/ returned bad-request from the world server (after satisfying the client-side policy gate so the request actually reached the wire). Both demarkus surfaces now enforce the markdown-only contract; #276 (broker render guard) is the remaining tail.

## Broker render guard implemented (#276, branch fix/broker-render-guard, 2026-07-25)

Hoisted the #273 binary guard into the shared render package: `mdoutline.BinaryBody` (UTF-8 predicate) and `mdoutline.NonMarkdownNotice` (notice text), the same one-copy-not-a-mirror move as fetchdedup. demarkus-mcp's three sites now call the shared helpers (private binaryBody/nonMarkdownNotice deleted, notice text moved verbatim so the existing #273 tests double as regression proof). Broker gateway gained the guard at its three render sites, placed identically to the local client: handleMarkFetch (before the anchor slice, mode: binary, force never bypasses), handleMarkExplore (before the outline builder), readResource (text/plain notice). Tests mirror the local ones (fetch notice, force-still-notice, explore no-outline, resource MIME + text) plus a table test on the new mdoutline helpers. All suites green, pre-commit clean. Correction to the issue text discovered while reading the shipped code: #273's guard never had a force=true raw-bytes bypass in mark_fetch ("force bypasses the size gate, never the binary gate"), so the broker mirrors always-notice.

## #276 shipped and deployed (2026-07-25)

PR #277 merged; broker pin bumped to 0.14.5 in the deploy repo (PR #121) and Argo rolled it. Verified: pod on `ghcr.io/latebit-io/demarkus-broker:0.14.5`, 1/1 ready, gateway listening, and live `mark_fetch` + `mark_explore` through the broker render normally.

Two process lessons from the tail of this work:

CI pin-bump chain converges, contrary to first appearance. Merging a bump PR that touches `provision.go` cuts a tools release (the file lives under `tools/`), which dispatches another bump. It terminates at two PRs because the bump script reads its current-tools signal from the bootstrap `TOOLS_VERSION`, never from `fallbackToolsVersion`, and only writes `fallbackToolsVersion` when server or client also moved. So the second bump is bootstraps-only, touches no `tools/` file, and triggers nothing. Same shape ran twice: #274 to #275, and #277 to #278 to #279. Cost is one junk tools patch release per cycle. Inherent to `provision.go` holding the server and client pins inside a released module; not fixable in the script.

Branching with a remote-tracking start point sets the wrong upstream. `git switch -c <branch> origin/main` records `origin/main` as the upstream, so with `push.default=simple` a bare `git push` is refused for the name mismatch, and git's first suggested remedy (`git push origin HEAD:main`) would push straight to main, violating the branch-per-change rule. Use `git switch -c <branch>` (or `--no-track`) and `git push -u origin HEAD`.

## Related documents

- [Roadmap](/roadmap.md): brought current with these merges
- [Architecture](/architecture.md): records the markdown-only content contract split
- [Five minute appliance](/plans/five-minute-appliance.md): install hardening rolled onto the droplet
- [2026-07-23 journal](/journal/2026-07-23.md): where the content contract work began