Arenas and the Research panel

An arena is an adversarial cluster of research agents. One run turns a topic into a sourced, fact-checked outline: gather agents search the live web for the topic (and, once an outline takes shape, one more per named subject in it), a reader fetches the pages behind every source, a direction agent proposes competing theses, a synthesis agent writes the outline gated on a ledger of figures each tied to the page that reports it, and a verifier argues every claim in that outline against the sources and the web, correcting what it can and flagging the rest.

This is what used to be called the research agent. It is the first step of Auto-Pen, it is the post editor's Research panel, it has its own page under Primitives → Arenas, and it is callable from your own code. All four are the same engine.

From a post

1. Give the post a title. The panel's start button is disabled without one.
2. Open Research in the right column.
3. Optionally add Sources (URLs to read first), Mandatory Topics (sections the outline must cover), pick Outline detail (Barebones or Fleshed out), and switch on Direction check-in if you want to choose the angle yourself. Brand mention (Off, Subtle, or Woven) sets how much the piece names your company; it applies here and when Auto-Pen writes the post, and defaults to the collection's Auto-Pen setting.
4. Press Research & outline (after a finished run the button reads Research again). The panel shows Researching your topic… with the phase it's in: Planning research, Searching the web, Reading sources, Setting the direction, Drafting the outline, Fact-checking the outline. Stop & dismiss ends it at any point.
5. If the check-in is on, the run pauses at Pick the article's direction: choose one of the angles, or write your own under Or describe your own direction…, then press Continue with this direction. Skip (let the agent decide) hands the choice back.

When it's done

Outline ready. The outline is already in your editor; the panel says how many sources it read and, if you chose one, the direction. The sources themselves go on file: the Publish panel's Paper trail card lists the ones the finished article uses (KB-211), and when the collection's template asks for a list of sources, the article ends with a Sources checked section naming each page and the date it was read.

From there, run Auto-Pen: it skips Research, because the post now has content, and the kernel writes from the outline.

The Arenas page

Primitives → Arenas has two views, the same pair the Shredders page has.

• Studio: run an arena on any topic without attaching it to a post. You get the outline, the sources, the stat ledger, the direction and the paper trail back on the run itself.
• Endpoints: named, callable research configurations. An arena carries standing defaults (depth, direction gate, search provider, whether to fact-check, brand mention, the positioning the agents weigh, names never to mention, domains never to cite) and its own URL. Anything you leave out of an arena's defaults inherits your organization's own Context at run time, which is exactly what research did before it had a door.

Your organization's default arena, "Letterstory", is created the first time you run one and carries no defaults, so it always inherits Context.

Each endpoint card also shows its versioned Arena file: save a new version, pin the one runs use, or accept an offered one. Over the API: get_arena_file, save_arena_file, list_arena_versions, pin_arena_version, accept_arena_offer.

From your own code

run_arena takes a topic and returns a run id. Poll it with get_arena_run; answer a direction gate with submit_arena_direction; stop one with cancel_arena_run.

letterstory arena run --topic "payroll software for ten-person firms" --source https://example.com/report --gate
letterstory arena run-status <run-id>

Pass article_id (CLI --article) to make it a hosted run: the outline is written into that post, which is what the Research panel does. Omit it and everything comes back on the run.

Every run records two things worth reading:

• constraints: what it actually ran with, including which parts of the positioning you declared and which it inherited from your organization.
• verification: six checks read back after the fact. sourced (at least one source with a real page behind it), read (pages were fetched), grounded (figures tied to a source), direction (a thesis was decided, and by whom), shape (every required section planned), fact_checked (the verify pass ran to completion). A check that did not apply reads skipped, never as a pass.

The full door-and-endpoint pattern, which arenas share with kernels, shredders and collections, is in KB-407.

Fact-checking

The outline is checked against the pages the run actually read, not just the search results, and a claim the sources can't settle gets a live web search of its own. The check never blocks the outline: if a run is short on time the panel says Fact-check skipped: out of time this run and the outline arrives anyway, and the run's fact_checked check reads skipped with the reason. Auto-Pen runs the same checks again on the written draft (KB-301).

Giving it sources

Up to 20 URLs to read first and up to 40 section titles it must cover, on the panel (Sources, Mandatory Topics), over the API (source_urls, must_include), or on the CLI (--source, --must-include). Naming a template instead fills both for you.

What a run costs

Your organization gets 50 arena runs on the house. Only runs you ask for directly count: a run Auto-Pen, the cadence or a phantom starts on your behalf is recorded but not billed. A run that errors or is cancelled is free. get_arena_run_balance (CLI arena balance) shows granted, used and available.

Locks

An arena run can't start while Auto-Pen owns the post, and a second hosted run on the same post is refused. The panel tells you which is the case. Standalone runs have no such lock.