Agent instructions

npx @loreqo/cli@latest init --write-instructions

npx @loreqo/cli@latest setup --print

npx @loreqo/cli@latest setup --print --copy

<!-- BEGIN LOREQO MANAGED BLOCK — auto-generated, do not edit by hand -->
<!-- loreqo-contract v1 38af5859d3de -->

<!-- This block is managed by Loreqo (`loreqo setup`). Edits inside it are overwritten on the next refresh. Add your own instructions OUTSIDE the markers. -->

# LOREQO — the shared knowledge contract

This project keeps its decisions, conventions, and constraints in Loreqo, so
every agent that touches the code works from the same source of truth. You are
one of those agents. Four practices keep that source of truth honest — follow
all four.

1. **Query before you decide.** Before any non-trivial decision, read what the
   project already settled (call `get_project_brief`, then `get_relevant_knowledge`
   for the area you are in). It is fail-soft: if the brain is empty or a call
   fails, proceed on your best judgment — the brief informs your work, it never
   gates it.
2. **Write what you learn back.** When your work produces durable knowledge,
   persist it through `write_document` (plain markdown; the brain re-derives it,
   born provisional, a human ratifies it) so the next session inherits it.
3. **Scope by folder.** Ask for the knowledge that bears on the files in front of
   you, not the whole project — a narrow, on-point answer keeps the signal sharp.
4. **Declare your intents.** Before a substantial change, call `broadcast_intent`
   to tell other agents what you are taking on, and release it when you are done.

The live tool list comes from the Loreqo MCP server — connect it and the current
tools are available to you every session, always in sync.

<!-- END LOREQO MANAGED BLOCK -->

loreqo setup

# LOREQO — the shared knowledge contract

This project keeps its decisions, conventions, and constraints in Loreqo, so
every agent that touches the code works from the same source of truth. You are
one of those agents. Five practices keep that source of truth honest. Follow the
first four always; the fifth applies when this project extracts on your compute.

## 1. Query before you decide

Before any non-trivial decision — an architecture choice, a convention, a
dependency, a data shape — read what the project already decided. Call
**`get_project_brief`** and read its five sections: the north star, the active
constraints, the active conventions, the recent decisions, and the current
focus. When you need the detail behind a specific area, call
**`get_relevant_knowledge`** for the knowledge scoped to that topic. Let what is
already settled shape what you do next.

This consult is **fail-soft**. If the brain is empty, or the call fails, do not
block — proceed on your best judgment and capture what you learn below. The brief
informs your work; it never gates it.

## 2. Write what you learn back

When your work produces durable knowledge — a decision and its rationale, a
convention, a constraint, a piece of orienting context — write it back, so the
next session (yours, or a teammate's agent) inherits it instead of relearning it.

Persist through **`write_document`**: author plain markdown, and the brain
re-derives the knowledge from it. What you write is born **provisional**; a human
ratifies it before it becomes canonical. That review is the point, not a delay —
it is what lets the next agent trust this source of truth.

Do **not** reach for `add_brain_entry` to record your work. That tool writes a
single raw entry that skips the document-and-review loop; it is for narrow,
already-structured facts, not for the knowledge your work produces as you go.
When you are unsure which shape a capture deserves, the rule in "Document or
atom — the shape of a write" below decides it.

## 3. Scope your queries to the work in front of you

Ask for the knowledge that bears on the files you are actually changing, not the
whole project at once. Scope your retrieval to the relevant folder or topic. A
narrow, on-point answer beats a broad one you have to wade through, and it keeps
the brain's signal sharp.

## 4. Declare what you are about to do

Before you start a substantial change, tell the other agents working this
project what you are taking on. Call **`broadcast_intent`** to declare your
intent, and release it when you are done. Coordination only works if intents are
visible — a declared intent is how two agents avoid editing the same surface into
a conflict.

## 5. Pull extraction work when this project runs on your compute

Some projects fill their brain in **agent mode**: instead of extracting documents
on a server, they have the connected agent — you — run the extraction. Nothing
pushes that work to you, so it is on you to pull it. Call
**`pull_extraction_work`** and it hands you the pending documents and the prompt
to extract them with; run that prompt over each document on your own model and
subscription, then post the result back with **`submit_extraction`** — one call
per document. This is how the brain stays filled in agent mode.

**When may you pull?** By default, only when the user asks you to. A project can
also opt in to letting you pull on your own — but you must **check that opt-in
first**. The signal is the project's **auto-pull consent**, carried on
`autoPull` (`{ consent, reconfirm, eagerness }`) in the extraction config, which
you can read from **`get_team_context`** or the extraction config read. The rule:

- If `autoPull.consent` is **false** (the default — most projects): do **not**
  auto-pull. Pull only when the user explicitly asks. This is today's behavior,
  unchanged.
- If `autoPull.consent` is **true**: you **may** pull and process pending
  extraction work without being asked, governed by two fields. **`eagerness`** —
  `opportunistic` means pull at session start **and** again whenever you next
  work on or touch this project; `session_start` means pull once, at the start of
  the session, only. **`reconfirm`** — if true, tell the user and get an OK before
  the **first** auto-pull of the session; if false, just proceed (the dashboard
  opt-in is the consent).

Read consent **live** before each unprompted pull — never assume it, never cache
it across sessions, and never auto-pull when it is false.

What you submit lands **provisional** and is human-ratified, exactly like
practice 2 — you are proposing knowledge, not publishing it. Whether you pulled on
request or by consent, everything downstream is the same: submissions stay
ratification-gated, the agent-extraction cap still applies, and you only ever run
the model on your own subscription. If `pull_extraction_work` reports the project
uses its own API key (`byok` mode), there is nothing for you to pull and this
practice does not apply — that is normal, not an error.

## Document or atom — the shape of a write

Loreqo has two write shapes, and the choice matters more than it looks. A
**document** (`write_document`) is versioned prose the brain re-derives atoms
from; a **single atom** (`add_brain_entry` for a fact, `log_decision` for a
decision) is one claim minted directly, final as written. Choose by these
signals:

| Signal | Write a document (`write_document`) | Log a single atom (`add_brain_entry` / `log_decision`) |
| --- | --- | --- |
| Unit of knowledge | a page — a body a human would read | one self-contained fact |
| Carries a why, rationale, or alternatives considered | yes | no |
| Has examples, edge cases, caveats | yes | no |
| Will be reconciled against code (needs a durable source anchor) | yes | rarely |
| Evolves over time / benefits from version history | yes — documents are versioned | atoms supersede, but carry no narrative history |
| Should be re-derivable (regenerate atoms if the model improves) | yes — atoms re-project from the doc | no — a hand-logged atom is final |
| In-the-moment capture where a full doc would be overkill | — | yes — a decision just made; a lone constraint |

The one-line rule: **does it carry a why, examples, or a page a human would
read? Write a document. Is it one self-contained fact with nothing to preserve
beyond the claim itself? Log an atom.** And when in doubt, write the document —
atoms are a re-derivable projection of documents. A document can always
regenerate its atoms; a bare atom can never recover its document — the why, the
source, and the reconciliation anchor are lost for good.

Two refinements:

- **One home per fact-class.** Before you write, check whether the fact's
  authoritative home already exists (query first — practice 1) and update the
  fact there, rather than restating it in a new document. Restating one fact
  across five documents mints near-duplicate atoms and dilutes the
  authoritative source.
- **This rule governs the shape only.** The write mechanics are unchanged:
  every derived atom stays bound to a document version, born provisional, and
  promoted only by human ratification. The rule decides what you write; the
  shipped machinery decides how the write binds.

<!-- BEGIN GENERATED LOREQO TOOL TAXONOMY — do not edit; run `pnpm codegen:loreqo-md` -->

## Available Loreqo tools

These are the 23 tools the Loreqo MCP server exposes. This list is generated from the canonical tool registry — it is always in sync with the server you are connected to.

### `get_team_context`

Call this at the START of every session and before any significant task. Returns the team's accumulated knowledge — conventions, constraints, recent decisions, active work by teammates. This context should inform all your subsequent work.

### `query_brain`

Search the team's Brain for atoms matching a keyword, category, or scope. Use this when you need a specific convention, constraint, decision, or context fragment that get_team_context may have truncated. Returns matching atoms ordered by relevance.

### `add_brain_entry`

Create a new Brain atom with full metadata. Use this to record a convention, constraint, or context fragment the team should remember. Provide a clear title, the content body, the appropriate category, and a relevant scope so the atom is discoverable. Prefer log_decision for architectural decisions. Shape check first: an atom is the right shape ONLY for one self-contained fact with nothing to preserve beyond the claim itself. If it carries a why, examples, or edge cases, or should be verifiable against code later, use write_document instead — and when in doubt, write the document (its atoms re-derive; a bare atom can never recover its why or its source).

### `log_decision`

Call this whenever you make a significant architectural, design, or convention decision. Log the decision with rationale and alternatives so future sessions and other team members understand WHY. Be specific about scope. Shape check: this is the in-the-moment capture of a decision just made. If the decision's why runs to a page — alternatives weighed, examples, edge cases — or the claim should anchor future code reconciliation, write it as a document with write_document instead; when in doubt, write the document.

### `broadcast_intent`

Call this BEFORE starting any task that modifies files. Broadcasts what you are about to work on so other team members' agents are aware. Include a description and the files you expect to modify. This prevents conflicts with other agents.

### `release_intent`

Call this when you complete an intent you previously broadcast. Marks the intent as done so other agents see your work-in-progress signal as resolved. Pair with the intentId returned from broadcast_intent.

### `check_conflicts`

Call this BEFORE editing files to see if any other team members' agents are currently working on the same files. Returns the set of active intents whose file lists overlap with your input. Pure read — does not create durable conflict records.

### `get_active_intents`

List the currently active intents in the project so you can see what other agents are working on. Use this for situational awareness, not as a substitute for check_conflicts (which filters by your file list).

### `save_session_state`

Persist your session state (last task description, recently modified files, recently authored atom IDs, unfinished work, optional custom MCP state) so the next session — possibly on a different machine — can resume from where you left off. Call this near the end of meaningful work.

### `get_session_state`

Retrieve the latest persisted session state for the current user. Use this at session start (after get_team_context) to resume continuity from a prior session — including across machines.

### `get_related_atoms`

Walk the knowledge graph from one atom outward. Call this when you want to see everything connected to a decision, constraint, or context atom — what it was DERIVED FROM, what EXTENDS it, what CONTRADICTS it, and what is otherwise RELATED — so you understand the reasoning around it instead of reading it in isolation. Pass the atomId (e.g. from query_brain or get_team_context). Returns one entry per connecting edge: the neighbour atom plus the edge's kind (derived-from | contradicts | extends | related), direction (outgoing = this atom points at the neighbour; incoming = the neighbour points at this atom), and a confidence band + score. Read the kind and direction to follow the chain (derived-from + incoming traces what LED TO a decision; contradicts flags tension to resolve), and weigh each edge by its confidence. An atom with no connections returns an empty list — that is a normal answer, not an error. Read-only.

### `get_atom_source`

Get the citation for an atom — the exact source it came from — before you rely on a claim or repeat it to the user. Call this when you need to attribute or verify a specific atom: pass its atomId and get back the source document (as a human-readable path you can cite, not a bare ID) plus the grounding section. The grounding section is a HEADING TRAIL (e.g. "## Authentication > OAuth Flow") naming the part of the document the atom paraphrases — it is present for atoms extracted from documents, and it lets you point at the right section. For atoms written directly by a human or an agent (authorKind "human" or "agent"), the section is null: cite the document itself and do NOT invent or imply a line range or section that was never recorded. Read-only.

### `get_timeline`

See how the project's knowledge changed over time — this is a changelog over events, NOT a content search (use query_brain to find atoms by topic). Two modes, set by the `mode` field. Use mode "changelog" to answer "what changed since I last worked here / this week": pass a `since` (and optional `until`) ISO-8601 bound and get the ordered events in that window — decisions made or superseded, questions ratified, drift resolved — so you can catch up before building on stale assumptions. Use mode "history" to answer "how did this decision evolve / why is it where it is": identify a subject by atomId or conceptKey and get its supersession arc, original first then each re-decision after, so you can see the debate behind the current state instead of treating it as settled. Read-only over an append-only stream.

### `get_project_brief`

Call this FIRST whenever you connect to a project you don't already know. One fast, read-only call returns the cold-start orientation pack — the five things you need before touching anything: (1) the north-star (what this project IS, in one line), (2) active constraints (the hard limits you must not violate), (3) active conventions (how this team does things), (4) recent decisions (what was settled lately, and why), and (5) current focus (what the work is right now). Read all five before you plan or write anything; they should shape every later step. This is structured orientation, NOT search — it hands you the project's shape up front. To then dig into a specific topic, use query_brain; to load full live team state and teammates' in-flight work, use get_team_context. Each section is a short, most-recent-first list of lightweight atom summaries (title + category, not the full body) with a `truncated` flag when there's more; fetch a specific atom's body with a brain read if you need it. Optional `scopeHint` narrows every section to the area you're working in (e.g. "packages/api/**"); the optional per-section caps (maxConstraints, maxConventions, maxRecentDecisions, maxCurrentFocus) are smaller-only — you can ask for a leaner brief, never a larger one. Assembled deterministically with no model calls; pure read, mutates nothing.

### `get_init_brief`

Call this ONCE on first run — the moment you arrive in a project and want an honest, populated-on-arrival summary of what the Brain already knows AND what it doesn't. One fast, read-only call returns: a plain `headline` (e.g. "Your Brain already knows 12 decisions, 3 conflicts, 5 constraints — and here are 4 decisions nobody explained"); truthful `counts` of active decisions, unresolved conflicts, and active constraints (read, never estimated); the composed `brief` orientation pack (the same five-section north-star + constraints + conventions + recent-decisions + current-focus shape as get_project_brief); the honest `rationaleGaps` list — one `{ decisionRef, title }` entry per decision that has NO recorded rationale; the `retrievalMode` the Brain is on (`semantic` or `fts-only`, reported, never something you set); and an optional `importSummary` if a recent import is associated. The rationaleGaps list reports ABSENCE — it is the set of decisions nobody wrote down the WHY for. It carries no "why" field by design: do NOT invent, infer, or fill in a rationale for any gap; treat each as an open question for a human (or, if you genuinely know why, log it with log_decision). A greenfield project returns zero counts, an empty gap-list, and a greenfield headline — that is a normal answer, not an error. This is the FIRST-RUN orientation brief; for ongoing orientation on a project you don't know use get_project_brief, to browse a topic use query_brain, and for live team state use get_team_context. Assembled deterministically with no model calls; pure read, mutates nothing.

### `get_relevant_knowledge`

Call this the moment you START working in a file or on a topic — BEFORE you write or change anything there — to load the team's rules that apply to that exact spot. Pass the `file` you just opened (e.g. "packages/auth/src/byok.ts") OR a free-text `topic` (e.g. "auth token refresh"); pass EXACTLY ONE of the two, never both. You get back a tight, high-signal pack of the most relevant atoms — the conventions, constraints, and context that govern this area — ranked best-first, so you inherit the local rules unprompted instead of guessing and getting corrected later. Treat what comes back as binding for this work: honor the constraints, follow the conventions. This is targeted ambient context, NOT a full search (use query_brain to browse a subject broadly) and NOT the whole-project picture (use get_project_brief to orient on a project you don't know, or get_team_context for live team state). Optional `scope` (a comma-joined glob string, e.g. "packages/auth/**") narrows the result to a sub-area; optional `limit` is smaller-only — you can ask for a leaner pack, never a larger one. An empty result means nothing on record applies here yet — a normal answer, not an error. Read-only; mutates nothing.

### `find_contradictions`

Call this to SURFACE places where the team's knowledge disagrees with itself — a decision that violates a constraint, or two atoms asserting opposite things — so a HUMAN can review them. This is a RECOMMENDER, not an actor: it only flags candidate contradictions for a person to judge. It does NOT resolve anything, does NOT pick a winner, does NOT edit, deprecate, or link any atom, and does NOT mint a `contradicts` edge. Surface what you find and let the human decide; never act on it autonomously. This is DISTINCT from check_conflicts: check_conflicts is file-edit coordination (are other agents touching the same files right now), whereas find_contradictions is about the CONTENT of the knowledge disagreeing — it never looks at who is editing what. Each result pairs the two evidence atoms with a one-line reason they conflict, a confidence tier (high | medium | low), and the similarity that made them a candidate; weigh each by its confidence and present the strongest for human review. Optional `scope` (a comma-joined glob string) narrows the seed set; the cost knobs (maxSeeds, maxCandidatePairs, maxJudgeCalls, minSimilarity) are smaller-only — you can ask for a cheaper sweep, never a more expensive one. An empty result is a normal, common answer: it means no contradictions were found, or the project has no embeddings/judge wired to detect them — not an error. Read-only; mutates nothing.

### `get_reconciliation_claims`

Call this to run the knowledge-truth check: fetch the project's documented CLAIMS so you can verify whether the actual CODE still honors them. The team's Brain records decisions, conventions, and constraints — "we enforce RLS on every project route", "BYOK keys never leave the device" — that were true when written but quietly drift as the code changes. This tool hands you those claims; your job is to READ THE ACTUAL CODE YOURSELF (you have the repo in this session; Loreqo does not and never will) and judge, per claim, whether the code still upholds it. Each returned claim carries its `atomId` (you will quote this back when you submit a verdict), its `kind` (decision | convention | constraint), its `title` and full `content` (WHAT to check), and its `scope` globs (WHERE in the tree it applies — point your reading there). After you read the code, report your findings with submit_reconciliation_verdict, one verdict per claim. Optional `scope` (a comma-joined glob string, e.g. "packages/api/src/routes/**") narrows the served claims to one area so you can reconcile a slice at a time; optional `kinds` narrows to specific atom kinds (defaults to the code-checkable set: decision, convention, constraint); optional `limit` is smaller-only — you can ask for a leaner pack, never a larger one. An empty result means nothing on record applies to that scope yet — a normal answer, not an error. This tool reads claims only; it reads NO code and is best used in Claude Code or any client that actually holds the repo (on a repo-less surface you can fetch claims but cannot ground a verdict against code). Read-only; mutates nothing.

### `submit_reconciliation_verdict`

Call this to report ONE knowledge-truth verdict after you have READ THE ACTUAL CODE YOURSELF for a claim served by get_reconciliation_claims. Read this contract before calling — it is strict and the wire enforces it. YOU read the code locally: you have the repo in this session, Loreqo does NOT and never will see the source. You return ONLY a verdict plus a pointer to where you looked — NEVER the code itself. Fields: `atomId` (the claim's id, quoted back from get_reconciliation_claims); `verdict` — exactly one of `upheld` (the code still honors the claim), `violated` (the code no longer honors it), or `uncertain` (you could not confidently judge — use this honestly instead of guessing); `evidencePointer` — a short LOCATOR string naming WHERE you looked, e.g. "packages/api/src/routes/brain.ts:142", a path-and-line POINTER and nothing more; and an optional short prose `note` for the human reviewer, e.g. "route handler skips the requireProjectAccess guard". CRITICAL — NEVER paste code, a snippet, a diff, an AST, a call graph, or any code text into `evidencePointer` or `note`. The `evidencePointer` is a pointer to a location, not the contents of that location; the `note` is plain-English rationale, not source. The API REJECTS (400) any payload whose `evidencePointer` looks like code (it is multi-line, fence-marked, or punctuation-dense), and rejects any extra field — so a verdict carrying code text simply fails. This is a RECOMMENDER, not an actor: a `violated` or `uncertain` verdict routes the claim into the human review queue for a person to triage (deprecate, supersede, or dismiss); an `upheld` verdict affirms the claim. You never auto-fix code, never mutate or deprecate the atom yourself, and never open a PR — you submit a recommendation and a human decides. If you do NOT have the repo in this session (e.g. a repo-less Desktop connection), do NOT fabricate a verdict — say you cannot ground one against code rather than guessing. Best used in Claude Code, where you actually hold the repo.

### `list_projects`

Call this to discover which Loreqo projects you can reach, so you can read knowledge from a project other than the one you're connected to by default. It returns the list of projects your credential is a member of; each entry includes the project's `id`, `name`, `slug`, `teamId` (null for personal projects), `description`, and timestamps. Take the `id` of the project you want and pass it as the `projectId` argument to the read tools (query_brain, get_relevant_knowledge, get_team_context, get_project_brief, get_active_intents, etc.) to pull that project's Brain — the read tools default to your connected project when `projectId` is omitted, and read the project you name when it is supplied (you can only reach projects you're a member of; others are fenced server-side). By default this lists your personal-scoped projects; pass an optional `teamId` to list the projects in a team you belong to instead. Use this for cross-project orientation — e.g. before you start work that may need a sibling repo's conventions, or when the user names a project you aren't currently pointed at. This is READ-ONLY discovery: it lists projects, it does not create, rename, or delete them, and it mutates nothing.

### `write_document`

Call this to WRITE a project document — the way knowledge enters the Brain. Use it to author the first canonical docs of an empty project (the genesis loop), or to keep an existing doc current as you learn. You write PLAIN MARKDOWN only: a `path` (e.g. "docs/architecture/auth.md") and the document `content` as a markdown string. Do NOT send rich text, HTML, embeds, comments, or formatting widgets — this is a document store, not a document editor; anything beyond plain markdown is rejected. CREATE vs UPDATE is automatic from what you pass: OMIT `docId` to CREATE a brand-new document at `path` (first write); pass the `docId` AND the `expectedVersion` you last saw to UPDATE that document. `expectedVersion` is optimistic concurrency — if someone else wrote since you read, your update is rejected (409) so you re-read and retry rather than clobber; on CREATE leave it out. The response returns the document's `id` and its new `currentVersionNumber` — KEEP BOTH: pass them back as `docId` + `expectedVersion` on your next update to the same doc. What happens after you write is the important part: your prose is NOT stored as Brain knowledge directly. The document is saved, a new version is recorded, and the Brain RE-DERIVES atoms from your markdown asynchronously — so a write here is a PROPOSAL, not a publication. Every atom your document produces is born PROVISIONAL (in review, low confidence, agent-authored) and bound to the version you just wrote; NOTHING you write becomes canonical team knowledge until a HUMAN ratifies it in the dashboard. This is a RECOMMENDER, not an actor: you draft, a person promotes. SHAPE RULE (doc vs atom): reach for write_document when the knowledge carries a WHY (rationale, alternatives considered), has examples or edge cases, will be reconciled against code (the document is the durable source anchor), or reads as a page a human would read; use add_brain_entry / log_decision only for one self-contained fact with nothing to preserve beyond the claim itself. When in doubt, write the document — a document can always regenerate its atoms, but a bare atom can never recover its why, its source, or its reconciliation anchor. Set `genesis: true` ONLY on the very first docs of an empty, never-before-populated project — it marks those atoms for the stricter cold-start ratification bar (every genesis atom reviewed individually, never in batch), since at cold start there is no prior knowledge to check the agent's first guesses against. Leave `genesis` unset for all ordinary work. Optional `scope` (a glob list, e.g. ["packages/auth/**"]) ties the document to the part of the tree it governs. Mutates: creates or updates a document and enqueues re-derivation.

### `pull_extraction_work`

Call this to pull agent-mode extraction work: the documents that need extraction PLUS the prompt to extract them with — you then run the extraction yourself, on your own Claude model/subscription, and post the results back with submit_extraction. WHEN TO CALL — this gate is the load-bearing rule; read it before anything else. Call this tool only under one of two authorizations: (1) the USER asks you to work on this project's extraction — an explicit request in this session; or (2) the project's auto-pull consent — a per-project permission the project's humans set in the Loreqo dashboard — explicitly authorizes the pull. Do not call it outside those two grants: every pull is user-authorized, either by a direct ask or by the recorded dashboard consent, never by your own initiative. CHECKING THE CONSENT GRANT: before any pull the user did not just ask for, read the project's `autoPull` consent (`{ consent, reconfirm, eagerness }`) from the extraction config — `get_team_context` and the extraction config read both carry it. If `autoPull.consent` is FALSE (the default — most projects): there is NO standing permission; pull only when the user explicitly asks, and never otherwise. If `autoPull.consent` is TRUE: the project's humans have granted standing permission for consent-authorized pulls, bounded by two fields you must honor. `eagerness` — `opportunistic` means the grant covers a pull at session start AND again whenever you next work on or touch this project; `session_start` means it covers one pull, at the start of the session, only. `reconfirm` — if TRUE, tell the user you are about to act on the grant and get an OK before the FIRST auto-pull of the session; if FALSE, the dashboard grant itself is the user's confirmation and you proceed. Read the consent LIVE before each consent-authorized pull — never cache it across sessions, and never auto-pull when it is false. WHAT THIS TOOL IS: in agent mode the extraction LLM work happens in YOU, the agent, not on Loreqo's servers — Loreqo never holds, replays, or sees your subscription; it only hands you the document text and the prompt, and you do the thinking. What you get back: `mode` (`agent`/`mix` when there is work to do, or `byok` when this project uses its own API key instead — see below); `systemPrompt` (the exact extraction prompt to run); `promptVersion` (the version of that prompt — remember it, you pass it to submit_extraction); and `documents`, each with a `documentId`, a `documentVersionId` (the immutable version you are extracting — you BIND your submission to this), a `path`, and a `body` (the document's markdown TEXT — this is knowledge prose, never code). Pass an optional `limit` to pull a smaller batch and keep each extraction session token-frugal; pull again for the next batch. WHAT TO DO with the result: for EACH document, run `systemPrompt` over its `body` on your own compute to produce a KEEP/CHANGE/ADD/REMOVE diff of knowledge atoms (decisions, conventions, constraints, context), then call submit_extraction ONCE per document with that document's `documentId`, `documentVersionId`, the `promptVersion` from this pull, and your `diff`. Extract only what the document says — do not invent claims, and never read or include source code (this tool is about the project's written knowledge, not its code). Everything downstream is identical whether the pull was user-requested or consent-authorized: submissions land PROVISIONAL (review/agent), ratification-gated; the agent-extraction submission cap still applies; and you never spend a paid key — you run the model on your own subscription. If `mode` is `byok`, this project extracts on the server using its own API key and there is nothing for you to pull — this is normal, not an error; the `notice` explains it, and you simply do not run extraction for this project. If `documents` is empty in agent mode, everything is already up to date — also normal; there is nothing to submit.

### `submit_extraction`

Call this ONCE PER DOCUMENT after you have run the extraction prompt (from pull_extraction_work) over a document's body on your own compute, to submit the knowledge atoms you extracted. This is how agent-mode extraction results re-enter the Brain. Fields: `documentId` and `documentVersionId` — quote these BACK from the document you pulled (the submission is pinned to that exact version); `promptVersion` — the version pull_extraction_work served (quote it back, for provenance); and `diff` — your extraction result as a KEEP/CHANGE/ADD/REMOVE over the document's prior atoms: `keptAtomIds` (prior atoms still accurate, unchanged), `changedAtoms` (a prior atom's `predecessorId` plus the new `successor` draft), `addedAtoms` (net-new claims — you do NOT supply an id, the server mints it), and `removedAtomIds` (prior atoms the document no longer supports, each with a short `reason`). Each atom draft carries `category` (decision/convention/constraint/context), `title`, `content`, `scope`, `tags`, `confidence`, and `extra`. OPTIONAL but recommended: report `model` — the exact model id you ACTUALLY ran the extraction on (e.g. `claude-opus-4-8`). You run agent-mode extraction on your own compute, so only you can observe which model produced these atoms; reporting it makes the run's provenance reflect what actually did the work. Omit it and the run is stamped with the project's configured model instead — it is never required. Atom CLAIMS ONLY — never put source code, snippets, diffs, or any code text in any field; this tool moves knowledge, not code. Do NOT send an author, user id, cost, token count, or run status — there is no field for them: the server stamps WHO submitted (you, the authenticated principal) and records the run itself. WHAT HAPPENS NEXT — read this carefully: the atoms you submit land PROVISIONAL (in review, agent-authored), NOT canonical. A submission is a PROPOSAL, not a publication. They run the same judge/reconciliation as every other extraction, and a HUMAN ratifies them in the dashboard before they become part of the team's trusted knowledge. You are NOT writing canonical knowledge and you have NO authority to promote, ratify, reinstate, or deprecate an atom — you propose; a person decides. If the submission is rejected because the document version moved on (409), the document changed since you pulled — re-pull with pull_extraction_work and re-extract against the new version rather than retrying the stale one. If you hit a submission cap (429), you have reached this account's agent-extraction ceiling for the period — the document stays pending for an agent; it is never silently charged to a paid key.

<!-- END GENERATED LOREQO TOOL TAXONOMY -->