> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The agent org

> Five deployed agents, one lane each, one graph each. What each may do, what none of them may do, and the rule that keeps the deployed set honest.

# The agent org

GreatBook runs **five** agents.
Each is one LangGraph state machine with one lane, and the boundaries between them are structural rather than conventional.

The organising principle is worth stating before the table: **an agent's authority is a property of its code, not of its prompt.**
The Auditor cannot write because its database sessions are read-only.
The Typewriter cannot post because nothing in its package imports anything that can.
No system prompt is load-bearing for any of it.

<Note>
  The merged MCP staged-domain adapters do not expand an agent graph's authority.
  They are separate server-owned commit boundaries for exact W3 Matching decisions, Typewriter approval/submission, adjustment decisions, fiscal-period transitions and workflow resume.
  Each rechecks the verified human, organization, target version and canonical service contract; there is no generic agent action dispatcher.
</Note>

## The five

<CardGroup cols={2}>
  <Card title="The Clerk" icon="inbox" href="/greatbook/agents/clerk">
    Documents in.
    Classify against 146 types, extract, resolve masters, validate, flag, queue for review.
    **Writes to the queue, never to the ledger.**
  </Card>

  <Card title="The Bookkeeper" icon="pen-line" href="/greatbook/agents/bookkeeper">
    One approved document to one balanced journal entry, behind a human posting gate.
    **The only agent on the write path.**
  </Card>

  <Card title="The Auditor" icon="magnifying-glass" href="/greatbook/agents/auditor">
    Continuous assurance over the book of record: seven check families, a nightly sweep, a durable exception register.
    **Strictly read-only, enforced by the database.**
  </Card>

  <Card title="The Accountant" icon="calendar-check" href="/greatbook/agents/accountant">
    Period close, adjusting entries and statutory reporting.
    **Proposes; never posts.**
  </Card>

  <Card title="The Typewriter" icon="file-pen" href="/greatbook/agents/typewriter">
    Words and lists in, schema-conformant document proposals out.
    **Propose-only, with no write path at all.**
  </Card>
</CardGroup>

## What each one may do

| Agent      | Reads                                                                                                   | Writes                                             | Pauses for a human                             | Can reach the ledger             |
| ---------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------- | -------------------------------- |
| Clerk      | registry, SOPs, masters, the queue                                                                      | `intake_queue`, at exactly two points              | no                                             | no                               |
| Bookkeeper | the ACTIVE intake row it re-reads itself                                                                | **the ledger**, through the single writer          | **yes**, `interrupt_before=["post"]`           | **yes, and only this one**       |
| Auditor    | the GL, on a [provably read-only session](/greatbook/agents/auditor#read-only-enforced-by-the-database) | nothing. The database refuses                      | no                                             | no                               |
| Accountant | the GL, on the Auditor's same read-only channel                                                         | nothing                                            | no, the pause lives on the Bookkeeper's thread | only by proposing into that gate |
| Typewriter | the document catalog                                                                                    | nothing. No database session exists in the package | no                                             | no                               |

## The lanes

```mermaid theme={null}
flowchart TD
  U["a person"] -->|"words, a list"| TW["Typewriter<br/>propose"]
  U -->|"a file"| CK["Clerk<br/>classify · extract · flag"]
  TW -->|"the human saves, signs, submits"| CK
  CK --> Q["intake_queue<br/>pending / flagged"]
  Q --> G1{"Gate 1 · intake approver"}
  G1 --> BK["Bookkeeper<br/>ingest · match · propose"]
  BK --> G2{"Gate 2 · posting checker"}
  G2 --> LS["LedgerService<br/>the single writer"]
  LS --> GL[("the general ledger")]
  GL --> AU["Auditor<br/>read-only assurance"]
  GL --> AC["Accountant<br/>close · statutory"]
  AC -.->|"an adjusting entry, staged"| G2
```

On the document lane, two humans answer two different questions and neither gate can be skipped from inside an agent.
An Accountant adjustment joins only at the posting gate under its own named-human, proposer-not-checker control.

## The deployed set, and the rule that keeps it honest

The five served graphs are declared in **two files**, and only one of them is read at runtime.

| File                                              | Role                                    |
| ------------------------------------------------- | --------------------------------------- |
| `langgraph.deploy.json`                           | the declaration                         |
| the deploy image's `LANGSERVE_GRAPHS` environment | what the platform server actually loads |

<Warning>
  When they disagree, the graph is simply **absent** from the assistant list with **nothing failing anywhere**.
  No error, no log line, no failed healthcheck.
  That is how the Accountant once shipped unserved while the repository said it was deployed.
</Warning>

So `agents/tests/test_served_graphs.py` **pins the two files equal and imports every declared entrypoint**.
The build goes red if they drift.

Changing the set needs an image rebuild, not an environment override.

A sixth graph would also need an eval: `test_every_served_graph_is_graded` reads the deploy manifest and requires each served graph to be bound in the eval registry, so adding one without grading it turns the build red.

<Note>
  A development manifest also exists and lists more graphs, including a folded-in extraction agent whose capability now lives inside the Clerk's registry-driven pipeline.
  Those are not deployed.
  The deploy manifest is the authority for what is actually served.
</Note>

## What they share

The agents share canonical contracts where agreement matters: the document registry, SOP access, model path, validation shapes and separation-of-duties rules.
They deliberately do **not** share one database authority: Typewriter has no database session, Auditor and Accountant use the separately proven read-only channel, and workflow agents receive only the storage paths their lane needs.

<CardGroup cols={2}>
  <Card title="The shared substrate" icon="layer-group" href="/greatbook/agents/substrate">
    Which common contracts exist, which agents use them, and why database authority stays lane-specific.
  </Card>

  <Card title="The SOP store" icon="book" href="/greatbook/agents/sops">
    Nine Git-bound SOP datasets, per-agent read grants, and rulebooks generated from the code that enforces them.
  </Card>

  <Card title="Where the business logic lives" icon="git-compare" href="/greatbook/agents/sop-vs-code">
    The dividing line between agent judgment, which is editable knowledge, and rules with ledger consequences, which are code.
  </Card>

  <Card title="Guardrails and refusals" icon="hand" href="/greatbook/agents/guardrails">
    Deterministic scope gates, canned declines, and the sandbox an untrusted document is read inside.
  </Card>
</CardGroup>

## Related

* [How it fits together](/greatbook/architecture) - where the agents sit in the stack
* [Tracing a run](/greatbook/agents/tracing) - what a run looks like, span by span
* [Two gates, three people](/greatbook/capabilities/maker-checker) - the human side of the money path
* [Capability map](/greatbook/capabilities/index) - the mechanisms these agents drive