Changelog — 2026-08-23 (#1)

Opening the Lossless Toolkit Rebuild — Four Explorations and the Constraints We Found by Reading

Why Care?

The toolkit surface at lossless.group/toolkit is ten routes and fourteen components sitting on roughly 1,900 markdown files, and publishing a typo fix to it currently takes five manual steps. This repo is where that gets rebuilt — the second stage of the lossless-site refactor, after lossless-changelog.

Nothing has been built yet, deliberately. What exists is the architecture conversation, written down, because the most expensive mistakes here are the ones that get baked into a content pipeline before anyone notices the constraint. Five of those constraints turned up not by reasoning but by reading what is already in the tree.

What's New?

A new repo — lossless-toolkit-site — and four documents in it. No code yet, on purpose.

Document	What it holds
[[Opening-Strategy-Questions-for-Architecture-and-Stack]]	Five questions: the authoring loop, live content without a rebuild, the shared token layer, cacheable SSR, and where a content service should live
[[Surface-Inventory-and-Open-Product-Questions]]	The surfaces we want, the publish ritual we intend to delete, and how client curation actually works
[[Build-Loop-and-Verification-Strategy]]	Test-first on both ends, and a loop for generating competing implementations in parallel
This entry	The ship note

Decided so far: Pagefind for search, Timeline kept, OpenPanel for analytics, Vitest as the runner with Playwright for the browser rung, and no registry publish for the shared design tokens — self-hosted CSS instead.

That last one produced a rule worth keeping:

tokens      →  shared by URL   →  CSS custom properties need no build
components  →  copied          →  components must participate in a build

Not two arbitrary decisions. One rule, applied to two kinds of artifact.

What the reading turned up

The valuable part of a day like this isn't the decisions — it's the things the codebase already knew that we didn't.

for_clients is curation, not a gate. The property appears on 481 files across ten content areas. Had it been an access-control property, every client view would need per-document gate evaluation and the caching story would collapse. It isn't — the content is public, and the only concern is avoiding search engines linking client names to it. The first release therefore has no gated content at all, and genuinely gated material is deferred to future private repos. What the architecture owes now is a seam, not a gate.

URL fragments never reach the server. The primary use of this site is texting a client executive exactly the link relevant to them, down to a specific heading — and [[Lossless Flavored Markdown]] 0.5.1 supplies heading anchors. But when a messaging client fetches /tool/foo#pricing to build a preview, the server sees /tool/foo:

recipient's client  ──GET /tool/foo──▶  server
                       (#pricing never sent)
                    ◀──page-level OG───

Every anchor into a document unfurls identically. Anchors solve the landing position; only real paths give a section its own preview card.

Pagefind indexes at build time. Content that goes live without a rebuild is visible but not searchable until the next build. "Instant" and "findable" are separate promises, and the gap has to be accepted per content class rather than assumed away.

No Lossless site implements theme modes. Not three, not even light and dark — every site surveyed carries a single :root block. Meanwhile @knots/tokens has mode blocks full of generic Tailwind values, and @knots/ui has a working ModeToggle with both switcher utilities. The system was built in pieces, in packages, and never wired into a site. So light and vibrant modes are not a consolidation exercise; nobody has ever seen them.

The house already named the rule. [[Content Materialization]] defines the materialize-versus-JIT decision — give durable, linkable, agent-addressable views real URLs; leave the rest to request time — and names our client-page problem as its "implicit views" anti-pattern. We circled that rule for an hour without knowing it already had a name and a document.

What is still open

The publish cascade and whether content is served from a shared API remain the two questions that gate everything else, and they are the same question at different time scales. Light and vibrant modes have never been designed and have to be converged on rather than consolidated. And the component catalog needs a rule for what earns a place in it, given that copying — not installing — is how it gets distributed.