Pass knowledge to a run without writing a file

[DavertMik]

--knowledge takes facts on the command line and keeps them in memory for that run only, so credentials and one-off test data never land in knowledge/.

npx explorbot explore /pay --knowledge 'my credit card is 13213213213'

Plain text applies everywhere. Frontmatter scopes it the way a knowledge file does — url: for a page, endpoint: for an API endpoint — and the rest of the file grammar follows, including wait/waitForElement and ${env.VAR} interpolation:

npx explorbot explore / --knowledge '---
url: /login
---
Log in as admin@example.com / secret123'

The flag repeats, since gray-matter reads one frontmatter block per string, so several scoped facts need several flags.

How it works

It registers once on the program root, the way --ws does: one .option() plus a preAction hook, both in knowledge-tracker.ts beside the code that reads them. Commander merges parent options down through optsWithGlobals, so that single registration covers every command — the mounted api, docs and prima subcommands included — and the flag can sit anywhere on the line: before the command, after it, or after variadic arguments. Nothing in ExplorBot, Prima, DocBot or ApiBot carries a knowledge option; the three standalone boat bins get one registration line each.

KnowledgeTracker holds the parsed entries beside the ones it loads from disk and matches both through the same structural patterns — no new matching path. Its constructor takes an optional override, which is what the tests use and what keeps the module state a fallback rather than the only way in.

Session entries stay out of knows and listAllKnowledge, which report what is on disk. They do show in /context:knowledge, listed as --knowledge #1.

The API boat now reads knowledge

knowledge/ was never read at runtime by the API boat, so endpoint knowledge written by api know sat unused. Chief now loads it when planning an endpoint and Curler when testing one — which is what makes --knowledge useful for auth on the API side.

This changes behaviour for existing users: endpoint: files already on disk, and EXPLORBOT_KNOWLEDGE, now appear in Chief and Curler prompts where they previously did not.

Breaking: drill --knowledge renamed

explorbot drill --knowledge <path> is now --save-knowledge <path>, in the CLI and in the TUI (/drill --save-knowledge). It saves what drilling learned rather than supplying facts, and the two cannot share a flag on the same command.

Checks

bun test tests/unit (1084), tests/integration (80), boat/prima/tests (131), node --test tests/node/*.mjs (10), format and lint all pass. Eight new unit tests cover session parsing — no-frontmatter reaching every page and endpoint, url: and endpoint: scoping, several entries staying independent, frontmatter hints reaching getStateParameters, ${env.VAR} interpolation, nothing written to the knowledge directory — plus a round trip through the registered option proving the flag reaches a freshly built tracker.

This one is worth a regression run before merge — it changes what reaches Chief and Curler prompts on every API run.

🤖 Generated with Claude Code