Get started
QuoxCLIGuidesProofEvidence

Every guide now starts with a conversation

A Quox guide should show you can just ask Quox. The commands stay, but as an option, never a prerequisite. 152 of 165 guides now open with a real conversation, and the 13 that do not are waiting for a real reason.

Adam Cowles18 November 20264 min read
Two glowing chat bubbles in cyan and violet joined by a thin light trail to a stack of glass terminal windows, the front one marked with a green tick, on dark navy

On 18 November we set a rule for every Quox guide: it should show that you can just ask Quox. The commands stay on the page, but they are optional, never something you have to learn before you can get anything done.

A rule like that is easy to fake. Anyone can open a guide with a tidy chat that nobody ever ran. So it comes with a condition: the conversation on the page has to be a real one, replayed from a run that passed.

Where we started

First we counted. Of the 165 guides on quox.ai/cli, 132 already led with a real conversation: an Ask Quox section that replays a proven chat turn. The other 33 did not. They opened with commands, which suits someone who already knows the tool and asks a lot of someone who does not.

Then we made the rule hold. A new build check, check:conversation, fails any new guide that does not carry a proven conversation. The 33 older pages sit on a list of exceptions, and that list can only shrink. A page can leave it. Nothing new can join it.

Nineteen more overnight

Overnight, 19 of the 33 gained a real conversation. Each one is replayed from a proof run that passed in a separate scratch organisation, a test organisation with its own sample data, and each answer was checked against the command's own output.

Three of them: keep your contacts tidy, ask your brain why and see what changed in your search traffic. Each opens with Ask Quox, the question a person would type and what Quox answered. Do it yourself, the commands, comes after.

That takes the count to 152 of 165.

The 13 that are left

Thirteen guides still open with commands. We could have written a plausible chat for each by hand. We did not, for three kinds of reason.

Some need a product fix first. One guide covers splitting a long note into parts. In chat, Quox could not preview the split, so it guessed how many parts there would be. Worse, a page passed a check while giving that wrong count. We removed that test before it landed, because a check that passes a wrong answer is not a check.

Some need a cleaner scratch environment. Their answers showed internal test fixture names, the labels of our own sample data. That is not something to put in front of a reader as if it were their world, so those runs wait until the fixtures are tidied.

Some need things the scratch organisation does not have. It has no servers to manage and no X account to post from, so those guides have nothing real to ask about there yet.

A guess is never published

The rule underneath all of this is short. A conversation appears on a guide only if a real run passed. Where we do not have that run, the page keeps its commands and waits. A guess dressed up as a chat is never published.

That is also why the list of 13 matters more than the 152. Each page left on it names something to fix, in the product or in the place we test it. Published proof runs live on the Evidence Explorer.

What this does not prove

  • This is Quox checking itself. The proof runs were made by our own proof engine, not by an independent auditor.
  • A scratch organisation is not yours. A passing run shows what Quox answered there, against that sample data. Your data is different, which is why the commands stay on the page for you to check.