Refinery
The Logbook answers what happened. The Refinery answers what it meant, and it does that by putting a fresh agent in front of the record with a specific question and a stated depth.
The unit is a book: a set of archived sessions you picked, linked together, that runs can be dispatched over.
The process, end to end
Drawing the diagram…
A book grows rather than being made once: the chevron beside Send to Refinery targets an existing book, and the book's linked-sessions panel leads back to the Logbook to add more.
The start view and a book
The start view fits the window: each list scrolls inside its own panel, so a long history never pushes the rest off screen. Under the bar is a line of agent chips, one per Refinery agent, with what it asks in its tooltip; a chip, like Catalog in the bar, leads to where they are edited. Below sit Books and Runs, side by side on a wide window. The search in the bar filters the books by title and directory, and Enter opens the top match. Each book shows how many sessions it holds and a trail of dots for its latest runs. The runs span every book, newest first under day headers, each led by its title and with the way into its sessions. A run without a title is named by its goal, or by its agent. The counts in the Runs header (preparing, handed off, failed) double as a filter.
A book shows its runs beside the sessions it links. On a book that has never been run, the run form is already open, in the wide column with the Start button always in view. After that, New run in the bar opens it, and it closes again once a run has started. It keeps your choices for the next run, except the title and the goal, which belong to the run that took them. A book with many linked sessions gets a filter over them.
Filling in the form from a sentence
The run form opens on a prompt box that runs on mechabedo's Fast tier, shown in the box with its model. Say what the run is for - "why did the token refresh keep failing, keep it short" - and it picks the agent and the focus level, writes a title and a goal, and sets anything else you named, such as a loadout or Implement directly. The fields it changed are marked for a moment.
It only fills in the form. Read it, change what you want, and start the run yourself. Without a model on the Fast tier the box is disabled; set one under Loadouts.
From the chat and AgentDeck
You can also ask for the Refinery in words, in the chat or in an AgentDeck session: "find my sessions about the login bug and have the debugger trajectory agent read them". The Refinery's tools do that:
- a search over past sessions by title, project and directory, over messages by their text, and over existing books, answered with a link to each hit;
- the catalog of agents, focus levels and personalities;
- creating a book from the sessions it found, with a run on it if you asked for one;
- starting a run on a book that already exists.
Nothing is created unless you asked. A write carries your own words from the conversation, and the model is told to show you what it found first. If a session, an agent or a focus level it names does not exist, nothing is created and the reply says which one.
The tools are the Refinery category of a kit. The chat's Pro kit and the harness Plus kit carry it, and the chat's and the harness's Lean kits do not until you switch it on in Enhance.
The preparing pass
Step 5 above is a mechabedo session of its own, and it is the part worth understanding, because it is why a Refinery run is not a template.
The agents' questions are standing questions - the same for every book. A prepared brief names the errors, the files and the dead ends this record actually contains, so the harness starts from evidence rather than from a question.
| Fact | Detail |
|---|---|
| What it gets | The agent's question, the focus level, the voice, the goal, and the harness and directory the work is going to |
| What it can read | search_logs and read_log over this run's exports; for an interview agent, also read_file, git_history and git_show over the book's directory |
| What it returns | The prompt. Nothing else |
| What it runs on | mechabedo's own Think tier |
| Where it lands | The archive, filed under harness mechabedo, so how a run was briefed is readable long afterwards |
Where the record is and where the document goes are never asked of it. Those two sections are written after the composed body, because a brief is a judgment and a path is a fact - and a paraphrased path is how an agent writes into the repository it was asked to read.
It degrades rather than stopping
With no model on the Think tier the pass falls back to the template brief - the plain concatenation this used to be - and says so on the run row and in its own session, naming the settings page. A Refinery that stopped working when a credential went missing would be worse than one that briefs generically.
The five shipped agents
| Agent | The question it asks of the record |
|---|---|
| Debugger trajectory | Where the recorded debugging went, and the trajectory to take instead from the same error |
| Nitpicker nous | What is worth improving, as enhancement tasks ready to hand off as one list or split per agent |
| Documentation ingestor | Whether the documentation matches what the sessions actually did |
| Fathom extend | What new feature the touched scope could grow, as a plan you hand off later |
| Grasp | An interview probing how well you know your own system |
Four of them are document agents: the run ends in a written report. Grasp is an interview agent, and it is a different thing: its preparing pass reads the git history to pick a topic, then the session asks you one question at a time on the ordinary question card in AgentDeck. The interview itself is the transcript, and the interviewer writes a report when it is done.
Nitpicker nous is written as a second pass. Its brief tells it to read earlier audit documents in the book's own directory and build on them, so its natural place is after an initial audit of the same book. Nothing enforces that order; a first run still works from the transcripts alone.
Focus is depth, never subject
Four levels, and they modulate how deep the answer goes without changing what it is about.
| Level | A document run | An interview run |
|---|---|---|
compress | The shortest true account | A handful of questions |
annotate | The transcript's own order, a note per step | One question per facet |
detailed | Full prose with file references | The full topic |
extensive | Dead ends, cross-references and open questions | A cross-examination |
Each level carries a written budget as well as a directive, so the pass is briefed in 150 words at compress and up to 1500 at extensive.
Because it is depth alone, this vocabulary is not the Refinery's alone. /fork on a session's prompt line names a focus level to compress that conversation into a handover, and /prompts focus <id> recalls the directive itself into a prompt line. A level written for one reads correctly in the other, which is the point of keeping it depth.
Report, or implement
A document run defaults to report or plan only, with the working directory left unchanged.
Implement directly is an explicit per-run opt-in: the handoff derives a plan, implements it without waiting for plan approval, and verifies the scoped changes. That authorization overrides the report-only instruction in the agent itself. It does not change tool permissions or safety confirmations, and an interview agent cannot use it at all.
Writing your own
Both lists are shipped code with whatever you have written merged over them by id, yours winning. Saving over a shipped id writes an override; deleting your override is the reset.
The editor is on the Enhance page, as two destinations beside the personality roster: Focus levels and Refinery agents.