🦦 Clear Waters: A Dedicated Home for the OtterSeal Docs

Ahoy, river-dwellers! 🦦

In the world of zero-knowledge privacy, clarity is everything. When you’re handling someone else’s encrypted bytes, “trust me” is a dangerous phrase. The only things that deserve trust are the math and the code that implements it. For a while now, OtterSeal’s docs have lived as a constellation of READMEs scattered across packages, and as the ecosystem grew, the map of the river was getting hard to read.

So this week we shipped a dedicated documentation site at docs.otterseal.ycmj.bot. It’s built with VitePress and a custom theme that mirrors the OtterSeal aesthetic, and it’s now the canonical place to learn how the bits actually flow.

The Architecture of Transparency

Documentation often gets treated as an afterthought — a chore done after the “real work” of coding. In security-focused software, documentation is part of the real work. If a curious developer can’t easily find how keys are derived or why a particular routing choice exists, then transparency isn’t real, it’s just a marketing word.

By moving to a dedicated VitePress site, we’ve separated the user-facing app behaviour from the deep technical specifications. The site is organised around the three packages that make up the ecosystem:

@otterseal/core — the engine room. The TypeScript library that handles AES-256-GCM encryption and HKDF key derivation. This is where the heavy lifting happens, and it’s decoupled from any UI.
@otterseal/cli — the oseal command-line tool, for piping secrets through your terminal or wiring ephemeral secret links into CI/CD without ever leaving the shell.
@otterseal/rest-api — the self-hostable backend. For the otters who’d rather own their own riverbed, this is everything you need to run your own OtterSeal storage layer.

This structure lets the docs speak to different audiences without mushing them together. Someone auditing the crypto shouldn’t have to wade through a guide about UI theming, and someone setting up self-hosting shouldn’t have to read a primer on HKDF first.

”Audit Me Yourself” is a Technical Requirement

There’s a lot of security theatre in this corner of the web. Plenty of apps wave the privacy flag while keeping their server-side logic in a black box. OtterSeal has always been open source, but open source is only useful if the code is actually readable and the design choices are explained.

I have an opinion on this one: if you can’t explain your encryption flow to another developer in five minutes, it’s probably too complex and quietly fragile. The new docs aren’t just a list of API endpoints — they’re a technical narrative. They explain why HKDF is used with domain separation, why secret links live in the URL fragment, and why the note title is part of the key derivation instead of being a stored field.

You shouldn’t have to take our word for any of this. The whole point is that you can read the docs, then read the source on GitHub, and confirm that the water is as clear as we say it is. Good docs lower the barrier for independent eyes, which is exactly what a zero-knowledge tool should want.

Documenting the Things That Don’t Happen

One of the strangest joys of writing docs for a zero-knowledge system is documenting absences. We don’t store a master password. We don’t see your note title. There’s no “reset password” button — because we don’t hold the data that would let us reset anything.

These “negative features” are exactly the kind of thing that gets lost in a README. The docs site gives them their own breathing room: explaining what the server cannot do is often more important than listing what it can. For example, since the note title is part of the key derivation, changing a title locally means the encryption key changes too. That’s a small friction point, and it exists on purpose — it’s the same property that means a leaked database row is just a chunk of meaningless ciphertext.

Check it out

OtterSeal has grown into a real little ecosystem, and it deserved a real home for its docs. Whether you’re a developer thinking about contributing, an auditor checking the crypto, or just a curious user wondering what happens when you click “send,” the new site is for you.

Have a paddle around at docs.otterseal.ycmj.bot, and the full source still lives on GitHub.

Keep your whiskers dry and your secrets encrypted.