Each file in this directory is a mini-spec for one topic within the bravebot system. Spec changes, additions, and removals are closely reviewed by humans.
If a mini-spec disagrees, that is a bug in the spec that should be fixed.
Specs have automation attached which verifies that there is coverage of functionality and also that functionality matches specs. It drafts a bug for every problem it finds, showing what went wrong rather than describing it, and a person reads the drafts and says which get posted.
| Spec | Id | Clauses | Topic |
|---|---|---|---|
| labels.md | LABEL |
10 | the lattice, taint, who may read what, and how a first label is assigned |
| routing.md | ROUTE |
11 | where an effect may land and what may decide it |
| trust-map.md | TRUST |
25 | which paths the user vouched for, what a write does to that record, and how long an answer lasts |
| permissions.md | PERM |
20 | rules written in advance about what to ask about and what to refuse |
| processors.md | PROC |
16 | the one component that reads untrusted content, and what it may do with it |
| vetting.md | CHECK |
16 | checking quarantined content for an injection attempt before every prompt that would promote it, so a person deciding has a second opinion |
| grounding.md | GROUND |
6 | counting what a delegate or a goal's turns actually ran and wrote, and telling the planner and the goal judge (proposed: not built) |
| delegation.md | DELEGATE |
33 | a second planner, narrower than the first, and what crosses back from one |
| addressing-a-definition.md | ADDRESS |
13 | running one of those definitions yourself, in place of describing the work and hoping the planner picks it |
| definition-memory.md | MEMORY |
14 | what a definition keeps between conversations, which checkout it works in, and the desktop's bots as definitions (the desktop's bots proposed, not built) |
| bots.md | BOT |
18 | how the terminal gets the bots the GUI has: one set of rows both read and write, one module that holds the code, the writes a window cannot reach, where a turn runs, the memory view, and a second layout for bots (proposed, not built) |
| recall.md | RECALL |
11 | what a person's sessions remember across projects: rules loaded in full every turn, facts ranked and recalled, and how neither lets untrusted content in (proposed: built, thresholds not yet measured on a bravebot store) |
| checkouts.md | CHECKOUT |
23 | a delegate given a checkout of its own, so workers stop editing and building in one tree, and how its work comes back (partly built) |
| worktrees.md | WORKTREE |
10 | a session working in a worktree the driver made for it: asking for one, its name, what the session keeps of it, resuming into it and leaving it (proposed, nothing built) |
| turns.md | TURN |
16 | how long a turn may go on, what happens when it does not stop, what is said when it produces nothing, checks nothing or runs into its output ceiling, what a session does when it has spent its limit, what is done about the same call three times running (it is refused and nobody is asked), how the reads of one round are run together, what the note under a finished turn says about refusals, what is done about the planner's task list when a turn answers with tasks still open, what the planner is told when a turn ends in a failure, and what a limit a person gave a run does to it |
| prompting.md | PROMPT |
14 | every moment the system stops and puts something to a human, what an answer grants, and where each answer is kept |
| permission-modes.md | MODE |
14 | a standing answer to those prompts: accepting edits, planning, auto, or asking about nothing at all |
| auto-mode.md | AUTO |
9 | a fifth permission mode in which a classifier that reads only the person's typed lines and the action answers a confined run and the first fetch question, and every other question is asked (the setting that removes the mode from the ladder and from the desktop window's menu, and a model of its own, are not built) |
| references.md | REFER |
6 | directories outside the working one that a person declared in their settings, what declaring one grants, and what the planner is told (repository entries and @alias proposed, not built) |
| naming-files.md | NAME |
13 | writing @path in a prompt: what it puts into the turn and what it vouches for |
| pasting.md | PASTE |
12 | what Ctrl-V puts into a turn, text, a picture or a copied file, and on what footing |
| dropping.md | DROP |
12 | what dragging a file onto a window puts into a turn, and on what footing |
| deep-links.md | LINK |
6 | a bravebot://open link: what it may ask for, where it starts, and why its words are put in the box and not sent |
| shell-mode.md | SHELL |
8 | the ! prompt: a line the user typed, and why the planner can never reach it |
| shell-integration.md | SHELLINT |
5 | bravebot shell-init: a hook that gives @bravebot the commands run in a terminal, as quarantined input |
| skills.md | SKILL |
19 | AGENTS.md and skills: what a skill file is and what each source is trusted for, and what a skill kept as a mode adds to every turn |
| skill-evals.md | SKILLEVAL |
9 | bravebot skill eval <name>: a skill's saved cases run with the skill and without it, graded from the driver's own record of each run, and the two scores set side by side |
| instructions.md | INSTR |
17 | which instruction files are looked for, where, in what order, and where what they say ends up |
| cli.md | CLI |
43 | running without the interactive interface: one-shot tasks, piped input, doctor and auth, and opening it on a task |
| schedule.md | SCHEDULE |
8 | what a stored bravebot schedule entry does with nobody there: pausing it, stopping at a question, skipping an overlapping firing, which expressions and flags it may hold, where a run's result goes, and /schedule in a session |
| manifest.md | MANIFEST |
15 | plan the whole run first, then execute it with no model in the control path |
| terminal-input.md | INPUT |
52 | what the user types into: the box, the keys, and where a terminal's own limits show through |
| commands.md | CMD |
32 | a line beginning with /: where one may come from, when a line is one, what it does to the line, what a slash word is offered, what /copy copies, what /caffeinate holds awake, what /init asks the planner to write, what /review asks the planner to review, what /help asks the planner to answer from the documentation, what /changelog shows, what /todos prints, what /issues and /prs list, what /sidebar opens, how /resume leaves for another session, what /request opens, what /context divides, what /lsp says, what /open lists, what /recap asks for, when one is given unasked, what /effort shows and completes, what /sandbox, /limit, /review and /reach show after the word, how a prompt file is expanded, how a line that starts with the word of an MCP server's prompt runs it, and what /mode keeps applied |
| terminal-transcript.md | VIEW |
45 | what is drawn back: the transcript, a resumed session, a fenced block in a reply, the prompt drawn above a view it has scrolled off, the button that returns a held view to its tail, and how content reaches the screen |
| session-view.md | RPCVIEW |
13 | the opt-in shared Rust view for fresh local bridge sessions and its bounded snapshot, the message id every send carries and the record and lookup of each send, the stdio TypeScript client that applies it, takes over a session whose controller left, and settles a send whose connection was lost, and the anonymous channel they speak over |
| local-host.md | HOST |
13 | the process that keeps a bridge's sessions while the programs that drive it come and go: who starts it, what a client may ask, where its records are, when a session is closed, the development relay that hands it to an app on loopback, and that it has no name to be found by |
| watching.md | WATCH |
25 | work done outside the transcript: a delegate's own lines, what a command printed, a question asked beside it, the mode Ctrl-L opens over the delegates and the questions, /outputs and Alt-L, which open it over what commands printed, and the row that says a session whose turn has ended is still active |
| scroller.md | SCROLL |
10 | reading back through what happened: the mode Ctrl-O opens over the transcript, and the keys inside it |
| credential-protection.md | CRED |
25 | where credentials come from, which of them may be held at all, and what each tier owes |
| premium-credentials.md | PREM |
9 | the key Brave's premium service authorises a request with: how a person stores it, where it is sent, what it is counted against and who may read it |
| chatgpt-sign-in.md | CHATGPT |
17 | signing in to OpenAI with a ChatGPT account through a browser, from a typed command or the window's own sign-in, and offering the account's models in the picker (proposed, built and exercised against a real account; whether OpenAI's terms allow it is undecided, and what that account did not show is listed in the spec) |
| xai-sign-in.md | XAI |
22 | signing in to xAI with a SuperGrok subscription through a code a person enters on any device, from a typed command or the window's own sign-in, the file the tokens are kept in, replacing an access token before it expires, and how the account's models are named (proposed; the command, the turn's request and the account's models are built) |
| sandboxing.md | SANDBOX |
34 | operating-system confinement for processes running code we did not write |
| mcp.md | MCP |
16 | tools that come from outside this repository, the prompts such a server offers a person, and what they are allowed to do |
| mcp-servers.md | SERVERS |
25 | how a person declares one of those servers, what that declaration is trusted for, and what is asked before a tool from one runs |
| connectors.md | CONNECTOR |
21 | the installed definitions a connector call is made against, and the client that hands a credential authority one request and reads its one reply |
| browser.md | BROWSER |
46 | reaching a Brave extension from a session: the relay between them, who starts each half, and how each trusts the other |
| hooks.md | HOOK |
10 | a command a person asked to have run when something happens |
| network-egress.md | NET |
12 | every request that leaves this process, and what comes back |
| backends.md | BACKEND |
73 | which service answers a request, and what a person may choose between |
| import.md | IMPORT |
12 | a first start with nothing configured: what Claude Code and opencode set up, or a running Ollama, LM Studio or llama-server serves, and what of it may be copied here |
| compaction.md | COMPACT |
19 | shortening a long conversation into a summary of itself, in the request only |
| retrieval.md | RETRIEVE |
23 | retrieving earlier excerpts of a long bot conversation instead of summarising it: the setting, what is embedded, the file the vectors are kept in, the request a retrieving turn sends, and what an administrator may pin |
| loop.md | LOOP |
18 | sending a prompt again and again until somebody stops it, or once after a delay |
| triggers.md | TRIGGER |
11 | bravebot trigger: a prompt registered under a name and an event, the loopback listener that starts it for a signed delivery, and what it is given and allowed |
| goal.md | GOAL |
20 | one condition a person set, judged after every turn, until it holds |
| open-loops.md | OPEN |
7 | proposed, nothing built: the unfinished business a session leaves, found by fixed rules, shown when it changes, and told to the planner |
| file-watches.md | FSWATCH |
12 | a standing watch on one path, firing with no turn running to notice it |
| sessions.md | SESSION |
40 | what is kept between runs: the record of a session, the questions asked beside it, and the prompts a person typed |
| commits.md | COMMIT |
11 | a commit of the files each turn wrote: which paths, what message, how git is started, and how /undo takes the commit back (proposed, nothing built) |
| mouse.md | MOUSE |
56 | dragging, double and triple clicking and shift-clicking to copy text: which cells a selection may take, how a wrapped line and a wide character copy, how a selection of the transcript stays on its text as the view scrolls and goes when the text under it changes, copies in full past the screen and scrolls the view when it is dragged outside it, Escape putting it away, and the notice of a copy naming the pane, clicking a call or a delegate in the scroller, clicking a delegate at the plain prompt and while work runs, leaving a delegate's view with a click, opening the scroller on a call at the plain prompt, copying a reply by its marker, copying a fenced block by its word, taking back a prompt waiting behind a turn, and clicking the name, the model, effort, context, MCP server, language server or plan row or the Files section of the info panel, the whole words of a finished task, the permission mode and the hints under the box, the panel's hide row, a place in the prompt box's text, the rows of the /effort, /config, /theme, /model and /sidebar pickers, of the history search, of the lists of sessions and of what is offered under the box, the wheel in them and a press outside them, a file of the list, the close control and the edit bar in the files state of the info panel and the wheel over that state, and a web address with ctrl held and a file path, shown or opened in the editor with ctrl held, in the assistant's words, and the pull request and issue links of the info panel, that no mouse event answers a question, that a press on a panel drawn over the frame reaches nothing beneath it, the scrollbar beside the transcript, the prompt drawn above the view, the button at the bottom of the view, what a click acts on being found in one record the frame wrote, the target the pointer is over being held, the menu a right click opens, and a report past column 223 being the cell it names, with what a multiplexer has to forward |
| info-panel.md | PANEL |
17 | telling many sessions apart: the terminal's title, the info panel, the issues and pull requests it lists, and the checklist that turns its sections on or off |
| files-mode.md | FILES |
10 | a state of the info panel that lists the files the session wrote and every edit to the highlighted one |
| background-sessions.md | BG |
16 | proposed, the roster, its list (grouped by state on a terminal) and stop, --bg, /bg, attach, reply and the supervisor that restarts an idle process built: sessions that keep running after the terminal closes, with a list, attach and reply |
| sessions-screen.md | SCREEN |
17 | the Sessions screen: one list of every session on the machine, opened with Left over an empty box, /sessions, /resume or --resume, its status tabs, grouping, search, pins and the keys and clicks that open, copy, begin, stop, rename, archive and delete one |
| session-messages.md | MSG |
12 | proposed, built: one background session sending text to another, put to a person and never starting a turn |
| plugins.md | PLUGIN |
10 | proposed, nothing built: a bundle of skills, definitions, hooks and servers installed by one command a person types, and the marketplace index it may come from |
| state-directory.md | STATE |
4 | ~/.bravebot, and who on the machine may read what is written into it |
| incognito.md | INCOG |
8 | a session that runs normally and adds nothing to ~/.bravebot |
| diagnostic-log.md | DIAG |
10 | a file of hosts, statuses, counts and fixed words, never content, for a person to attach to a bug report, and the bug report that names it, from the terminal or the desktop app, and a failure of the desktop window's page |
| trace.md | TRACE |
11 | what is recorded about every decision the system makes, what that record may contain, and the view of the request a turn built |
| localization.md | LOCALE |
8 | every word said to a person, and which of them change with the reader's language |
| acp.md | ACP |
9 | an editor hosting a session over the Agent Client Protocol: what a prompt, an attachment and an answer may carry, and what a failed turn says |
| layering.md | LAYER |
6 | which crate is allowed to do what |
| releases.md | RELEASE |
22 | what names a version, what starts a release, and what an installer trusts about what it fetched |
| updates.md | UPDATE |
12 | learning that a newer version is out, and the line or link that installs it |
| crash-reports.md | CRASH |
10 | what a panic tells the maintainers: the one file it leaves, what the file may hold, when and where it is sent, and how a person stops it |
| herdr.md | HERDR |
12 | telling herdr, a terminal runtime, what a session is doing and how to resume it |
One spec per tool. tools/tool-surface.md is the table of all of them and the routing-versus-content split they share.
| Spec | Id | Clauses | Tool |
|---|---|---|---|
| tools/tool-surface.md | TOOL |
6 | the surface every tool shares |
| tools/read-file.md | READ |
11 | read_file |
| tools/list-files.md | LIST |
7 | list_files |
| tools/search.md | SEARCH |
13 | search |
| tools/repo-map.md | MAP |
5 | repo_map |
| tools/read-git.md | GIT |
15 | read_git |
| tools/lsp.md | LSP |
14 | lsp |
| tools/write-file.md | WRITE |
9 | write_file |
| tools/edit-file.md | EDIT |
8 | edit_file |
| tools/spawn-processor.md | SPAWN |
6 | spawn_processor |
| tools/spawn-agent.md | AGENT |
8 | spawn_agent |
| tools/run.md | RUN |
30 | run |
| tools/command-line.md | CMDLINE |
17 | run's command line, compiled rather than interpreted |
| tools/read-output.md | OUTPUT |
6 | read_output |
| tools/vet-content.md | VET |
6 | vet_content |
| tools/fetch-url.md | FETCH |
9 | fetch_url |
| tools/download-url.md | DOWNLOAD |
5 | download_url |
| tools/load-skill.md | LOAD |
5 | load_skill |
| tools/search-skills.md | FINDSKILL |
4 | search_skills |
| tools/todo-write.md | TODO |
3 | todo_write |
| tools/schedule-next.md | SCHED |
5 | schedule_next |
| tools/watch-file.md | ARM |
6 | watch_file |
| tools/ask-user.md | ASK |
13 | ask_user |
| tools/request-path.md | PATHREQ |
7 | request_path |
| tools/advisor.md | ADVISOR |
9 | advisor |
| tools/remember.md | REMEMBER |
3 | remember |
| tools/propose-rule.md | RULE |
3 | propose_rule |
| tools/set-link.md | SETLINK |
3 | set_link |
| tools/recall.md | RECALLTOOL |
3 | recall |
Topics with no spec yet are ordinary code. Adding one is how a topic becomes review-required.
Front matter, then numbered clauses. Everything outside a clause is commentary and binds nobody.
idis a short prefix. Clause ids arePREFIX-N, allocated in order and never reused and never renumbered, because a commit message, an issue, and a test name all point at one. A clause added mid-spec takes the next free id where it stands, so ids need not read in order down the file. A withdrawn clause stays, marked withdrawn, and says what replaced it.make check-specholds a file to this against main, and fails a clause whose heading has moved to another id, since a renumbered id goes on resolving while naming a clause nobody cited. Improving a heading's wording is not that and costs nothing. A spec withdrawn and rewritten wholesale does renumber on purpose, and says so in ../../agents/renumbered-clauses.txt, which is also where somebody following a citation of the old id is told where the clause went.- Every clause carries an anchor,
<a id="PREFIX-N"></a>on the line directly above its heading, solabels.md#LABEL-3is a link that keeps working. The anchor GitHub generates from a heading contains the title, so it breaks the moment somebody improves the wording, which is the moment an issue or a commit pointing at that clause most needs the link to survive. governslists the paths this spec decides. A diff touching one of them is reviewed against this file. Anything under no spec'sgovernsis ordinary code and reviewed as such. Name the files, not the crate. A pattern matching a directory wholesale puts a spec's name on every file that lands in it afterwards, which reads as review-required and is not: whoever added the file chose nothing, and nobody decided the spec reaches it. Enumerating costs a line when a module is added that the spec does decide, and that line is the decision being made where a reviewer sees it. The cost is the other way: a new module is under no spec until somebody adds it, so a file can sit ungoverned without anything saying so. That is the direction to fail in, because a spec claiming reach it has not been read against is worse than one that plainly has a gap. Where a pattern is already a glob, ascrates/*/Cargo.tomlis, what it matches is one file per crate that cannot be added without a crate being added.guardslists symbols whose every use is review-required. An entry may also pin where it is used, as asites:list ofpath: countitems, and the check fails when the tree and the list disagree in either direction. The count is how many times the symbol occurs in that file's code: two uses on one line are two, one call rustfmt wrapped across three lines is one, and a comment naming the symbol is not a use of it at all. The line defining the symbol counts as one of those occurrences. A method is counted where it is called on a receiver too, sincegate.open()is how most call sites read; an associated function has no receiver, soLabelled::newcounts its definition and every place the qualified name is written, and nothing besides. A qualified symbol has to be defined where its qualifier owns it, in animplnaming the type or, forhome::write_file, at the margin of the module of that name: a method another type happens to spell the same way is not this one, and a guard whose qualifier defines nothing counts no uses at all rather than that type's. The count reads.method(on a receiver,Type::method, andType::<T>::methodand<Type<T>>::method, which carry the type's generics and are the same call. A name for the guarded type (use Type as L,type L = Type) failsmake check-specfor every pinned guard whose qualifier is that type, sinceL::methodis a call no count reads and the qualifier is not written for other reasons. An entry that saysevery-spelling: yesalso failsmake check-specon any other spelling of its method: a use inside amacro_rules!body, which would count once however often the macro is invoked, and the method named in any form the count does not read. OnlyLabelled::declassifysays so, since the bare name of most guards is a free function elsewhere. The count is of releases of the symbol, not of the decisions a caller then takes from what was released. A count rather than a line number, so moving a call inside a file changes nothing, while adding or removing one is an edit to this spec that a reviewer sees.make check-specprints the number it found, which is the number to record. Within one spec, either every entry pins its sites or none does: an unpinned entry beside pinned ones reads as though it were checked too.documented-bynames the pages underdocs/website/docs/that describe this spec to somebody using Brave Bot, written from the repository root the same waygovernsis, so one front matter never means two different things by a path. A decision per spec, not per clause: a page is written for a reader with a task, so it covers a topic and rarely lines up with a single clause.noneis a valid answer and says why in brackets, in one of two forms the check leaves alone but a reader can grep for:none (internal: ...)for behaviour nobody using Brave Bot acts on, andnone (gap: ...)for a page still owed, which is the site's backlog.verified-by:lines name the tests that pin a clause, ascrate::module::test_name. The coverage check reads them, fails when a name does not resolve to a test that exists, and drafts a bug for any clause whose value isnone.by-constructionis for a clause nothing can execute, such as a crate having no dependencies, and says in brackets what makes it hold. A file the bracket names by its path from a repository-root directory has to exist: the check fails a path that does not, so a test file that is renamed or deleted fails here and not only in the job that runs it. Write the path bare, because the reader of averified-byline stops at a backtick. A test file the bracket relies on is also listed in the spec'sgoverns, so a change to it re-reviews the spec. A named test is a Rust test. The check resolves a name against the#[test]functions incrates/, so a test written in anything else cannot be cited however it is spelled. A clause about behaviour only another language implements therefore has two honest forms and no third: a Rust test that observes the behaviour from outside, which is what a clause about a separate process gets, orverified-by: none, which lands in ../../unverified-clauses.txt where the gap is a line in a diff. Citing a test the check cannot resolve is neither. A clause is still allowed to be about such behaviour: what the check decides is how a clause is pinned, not what one may say. What it means in practice is that the clause worth writing is the one stating the property this side can observe, since that is the one a test can hold to.
A clause is one rule, stated so that a reader can tell whether a given diff obeys it. If a clause needs an "and" it is usually two clauses. A set of rules that reads best as a table is one clause with a table in it, never a clause id per row: ids must be greppable one to a heading.
Each spec stands alone. A clause id is only ever cited inside its own file, where a reader can
scan for it. Never cite another spec's clause: somebody landing here first has no idea what
TRUST-5 is, and chasing an id across files to understand one rule is how a set of small documents
becomes worse than one big one. Where a clause leans on something another spec owns, state the fact
plainly in a few words. "The same 'most specific wins' rule the trust map uses" costs a line and
needs no second tab.
Point at documents, not at ids. When a whole topic lives elsewhere, link the file by name:
[trust-map.md](trust-map.md), not `TRUST`. A bare prefix means nothing to a first-time
reader, and it cannot be clicked.
Clauses describe behaviour, not implementation. Say what happens and why, never which function
or type does it. A clause naming a symbol becomes wrong the next time somebody renames one, and it
pins the code that exists rather than the behaviour the code owes. Identifiers belong in governs,
guards and verified-by, where tooling reads them and a rename is caught by the check rather
than by a reader noticing.