TL;DR: Users don’t read documentation, they --help, get lost, and ask a colleague. go-tool-base ships the docs inside the binary and gives the tool two ways to surface them: a docs command that’s a proper TUI browser — sidebar, search, rich markdown — and docs ask, which answers natural-language questions using only that embedded documentation as context. The corpus is closed and small, which is exactly why the answers stay honest.

Nobody reads the manual

Here’s the actual lifecycle of a user meeting your CLI tool. They run it. It doesn’t do quite what they expected. They run it with --help. They get a wall of monospaced flag descriptions. They skim it, don’t find the thing, and either give up or go and ask a human who already knows.

The documentation might be excellent. It might answer their exact question in full. It doesn’t matter, because it’s on a website, in another window, behind a search box, and the user is here, in the terminal, mid-task. The docs lost not on quality but on location. They weren’t where the work was.

go-tool-base’s answer starts with a decision about location: the documentation gets embedded into the binary itself. Your docs/ folder ships inside the tool, the same way its default config does. Wherever the tool is installed, the docs are right there with it, no network, no browser. That embedding is what makes everything else possible, and there are two things built on top of it.

A browser, in the terminal

The first is the docs command, and it is not --help with extra steps. It launches a proper Terminal User Interface, built on Bubble Tea.

It has a sidebar, structured from the project’s own zensical.toml or mkdocs.yml, so the docs are a navigable tree rather than one flat scroll. Markdown renders with real formatting through Glamour — colour, tables, lists, headings — instead of collapsing to monospaced text. There’s live search across every page, regex included.

Compared with man and --help, the difference isn’t a nicer coat of paint. man gives you linear scrolling and grep; this gives you a structured tree, rich rendering and real search. It’s the documentation experience a modern developer expects, except it followed the tool into the terminal instead of demanding the user leave.

A documentation assistant that won’t make things up

The second thing built on the embedded docs is the one I find genuinely transformative: docs ask.

The user doesn’t navigate anything. They ask:

mytool docs ask "how do I point this at a self-hosted server?"

and get a direct, specific answer. Under the hood, the framework collates the tool’s embedded markdown and hands it to the configured AI provider — Claude, OpenAI, Gemini, Claude Local, any OpenAI-compatible endpoint — as the context for the question.

Now, “an AI answers questions about my tool” should immediately make you nervous, and the correct thing to be nervous about is hallucination. An AI that confidently invents a flag that doesn’t exist, or describes behaviour the tool doesn’t have, is worse than no assistant at all, because the user trusts it.

This is where embedding the docs pays off a second time, and it’s why I keep stressing that the corpus is closed. The model is instructed to answer only from the tool’s actual documentation, and the context it’s given is exactly that documentation and nothing else. It isn’t drawing on a vague memory of similar tools from its training. It’s answering from this tool’s real, shipped, version-matched docs. The corpus is small, closed, and authoritative, which is the combination that keeps the answers grounded. “Zero hallucination by design” isn’t a slogan about the model. It’s a property of bounding what the model is allowed to look at.

There’s a nice second-order effect, too. The answer is always about the version of the tool the user actually has, because the docs were embedded into that build. No mismatch between a website documenting the latest release and the slightly older binary on the user’s machine.

The upshot

Documentation usually loses to --help not on quality but on location — it’s in a browser, and the user is in the terminal. go-tool-base embeds the docs into the binary and surfaces them two ways: a docs command that’s a real TUI browser with a sidebar, rich markdown and search, and docs ask, which answers natural-language questions using the embedded docs as context.

Because that context is the tool’s own closed, shipped documentation and the model is told to use nothing else, the assistant stays grounded — and it’s always describing the exact version the user is holding. The fix for unread documentation was never to write more of it. It was to put it where the work happens and let it answer back.