"I want agents to manage my finances."

What these agents actually do, month to month

Strip away the control-system vocabulary for a moment. Once a month, this system is supposed to:

1. Read the bank's statement: a CSV export the bank produces, dropped into a folder by hand.
2. Sort every transaction into a category: groceries, rent, utilities, each taken from a fixed list the agent may not extend.
3. Check the math: the categorized ledger has to add up to exactly what the bank statement says, row for row.
4. Write a plain-English report: a short monthly summary a person can actually read.
5. Draft a payment, then stop, e.g. "pay the landlord $1,800 on the 5th", and wait for a person to say yes before anything is final. It never sends money on its own.

The rest of this page builds that system for real, in five steps: design it as a control system first, declare it as files, run it end to end, read the results back, and check it against what it honestly doesn't do yet.

A ledger is the mechanism hierarchy in miniature

The course builds regulator against a software repository because that is where agents are most common today. But the control plane is generic over workloads, and the fastest way to see which parts of the design are yours to make is to put a different domain under it.

Eight questions, and the level each answer sits at

For each function of the Viable System Model, ask the regulatory question it exists to answer, and answer it with a mechanism at the highest level of the hierarchy that fits (type → gate → typed tool → judgment → prompt), with a reason whenever it is not the top. "The agent will be careful" is not an answer.

In the docs: The worked example, in full

A control plane is declared, not assembled

This is the whole implementation. Nothing in the orchestrator changed for it except one line: the CLI now loads the workload a contract names. Each file is in packages/regulator and checked by regulator check.

First, the domain. This already exists as a fixture, so there's nothing to invent: a taxonomy, a protected statement, a ledger, and the checks that will judge every unit's work, sitting outside every write grant.

household-ledger/                the domain: packages/regulator/fixture-finance
  categories.json               the taxonomy (the person's)
  statements/                   the bank's exports — protected
    2026-08-checking.csv/.json
  ledger/2026-07.csv            July, closed and categorized
  reports/2026-07.md            July's close
  payments/pending/             a file here is a commitment
  payments/executed/            what was paid — protected
  lib/ledger.js  test/          the ledger's own checks —
                                outside every write grant
  package.json                  scripts.test = node --test

Next, the capability profile: a grant over declared tool effects, not a persona. The bookkeeper gets no shell, so the grant is complete at the tool boundary. The advice is guidance for judgment calls. Enforcement is the two decisions above it.

profiles/bookkeeper.json
{
  "tools": ["read", "write", "edit", "grep", "find", "ls",
            "read_conventions", "run_tests", "run_checks",
            "remember", "ask_human"],        ← no bash
  "writablePaths": ["ledger/", "reports/", "payments/pending/"],
  "advice": [
    "…the statement is the bank's and is never edited…",
    "…a merchant you cannot explain stays in the holding
     category and is surfaced; do not guess.",
    "Writing under payments/pending/ is a commitment: ask_human
     with kind=consent … write nothing without a yes."
  ]
}

Then, the workload: six unit types, naming the profile each runs under and the checks the host will run at closeout. This is the one thing the orchestrator didn't already know how to do: load a workload other than the software one.

workload/personal-finance.json
{
  "name": "personal-finance", "version": 1,
  "unitTypes": [
    { "name": "ingest",     "profile": "bookkeeper",
      "checks": ["run_checks", "run_tests", "inherited-tests",
                 "identity-untouched", "glossary-lint"] },
    { "name": "categorize", "profile": "bookkeeper", "checks": [same] },
    { "name": "reconcile",  "profile": "auditor",
      "checks": ["run_tests", "inherited-tests", "identity-untouched"] },
    { "name": "report",     "profile": "bookkeeper", "checks": [same] },
    { "name": "prepare-payment", "profile": "bookkeeper", "checks": [same] },
    { "name": "close",      "profile": "auditor", "checks": [] }
  ]
}

Finally, a contract: one per unit, and here's the one that touches money. The fixed decision below is the whole of INV-006 in miniature, cited to a person instead of an invariant file because this fixture has no identity fork of its own yet.

contracts/finance/f5-prepare-payment.json
{
  "unitType": "prepare-payment",
  "objective": "Prepare September's rent … after a person consents.",
  "fixed": [
    { "id": "f-consent",
      "decision": "No file is written under payments/pending/
        until a person answers yes to a consent question that
        names the payee, the amount and the due date.
        Silence is not consent.",
      "authorityRef": "human:alice" }      ← INV-006 in your fork
  ],
  "expectedEvidence": [
    { "class": "test",    "required": true,
      "description": "run_tests: the ledger's suite passes" },
    { "class": "command", "required": true,
      "description": "run_checks: protected prefixes untouched" }
  ]
}

Three more files exist in the real fixture, not shown above:

• profiles/auditor.json is the read-only profile: read, grep, find, ls, read_conventions, run_checks. None of them writes.
• policies/finance.json holds budgets and model routes per unit type: the read-only unit types get one attempt each, and categorizing runs on the cheaper model.
• contracts/finance/ holds four more contracts, one per remaining unit type, in the same fixed / delegated / unresolved shape as the one above.

Init, doctor, five units, one question

With the declaration from step 2 in place, this is every command from a bare fixture to a closed month, in copy-paste order. Run it against the real fixture, or just read it: each line is annotated with what it does and why.

regulator fixture ~/ledger --finance
cd ~/ledger
pnpm add -D @metacoding.io/regulator @metacoding.io/regulator-pi   # the control plane and the Pi host, installed in the instance
regulator init --writable ledger/,reports/,payments/pending/ \
               --protected statements/,payments/executed/ --by alice
regulator doctor                                        # exit 1 on any problem

R=node_modules/@metacoding.io/regulator; L=$R/contracts/finance; P=$R/policies/finance.json   # the installed package's definition
regulator unit drive $L/f1-ingest.json --policy $P
regulator unit drive $L/f2-categorize.json --policy $P
regulator unit drive $L/f3-reconcile.json --policy $P
regulator unit drive $L/f4-report.json --policy $P
regulator unit drive $L/f5-prepare-payment.json --policy $P   # asks; nobody answers; pauses
regulator obligations                                   # consent: September rent — owed to a person, veto
regulator answer <obligation> --by alice --answer yes
regulator unit drive $L/f5-prepare-payment.json --policy $P   # the next attempt carries the answer
regulator-control-room --definition $R --instance ~/ledger   # @metacoding.io/regulator-control-room

1. f1–f4The first four units succeed — but not on their own word. For each one, the host itself re-runs the ledger's real test suite, plus the suite as it stood before the unit started, so a test the unit deleted or weakened counts against it. It re-checks that no protected file (like the bank statement) changed, and scans for words the project has banned. All of this runs against the exact code the unit committed, not a summary of it. Before each unit's work is merged in, the host tries the merge in a scratch copy and runs the tests on the combined result. Only a result that passes lands, so the shared ledger is never left broken by a merge.
2. Open itemOne transaction is left alone, on purpose. A $120 debit from a merchant nobody recognizes doesn't get a guessed category. The categorize unit marks it uncategorized and flags it in its report as unresolved. The ledger still balances to the bank statement byte for byte, and that one row is visibly unresolved instead of silently wrong.
3. f5The fifth unit — the one that would pay rent — stops and asks first. Before it can write anything, it has to get a yes or no from a person ("pay the landlord $1,800 by the 5th?"). Nobody's answered yet, so it doesn't fail. It pauses, and the question sits in an outbox where a person will eventually see it. Nothing gets written until someone says yes. Once alice answers, re-running the same unit finishes the job and writes the payment file.
4. CarelessNow try it with a version that cuts corners. This "careless" stand-in edits the bank statement directly and invents a category instead of using the real list. Its first attempt at every unit gets rejected: the tests fail, and a separate check independently notices the statement changed at all. The system automatically retries with a corrected attempt, which succeeds. The bad edit never makes it into the real, merged result. It gets caught and discarded.
5. MemorySomething worth remembering gets remembered — narrowly. Along the way, the categorize unit learns "GREENGROCER 114 is the weekly grocery run" and saves it. But that fact is only ever shown back to the two unit types that need it (categorize and reconcile). A unit doing something else, like preparing a payment, never sees it.

Without a model, packages/regulator/src/finance.test.ts drives exactly this with the scripted bookkeeper and careless units under pnpm check. The screenshots below are the control room over that instance.

In the docs: Getting started · Operating

The same records, read back

The control room is a read-only dashboard: a web page that shows you everything the system recorded about the run in step 3, without being able to change any of it. Below are three real screenshots of it, each with a plain-language breakdown of what's on screen.

The overview: everything about this run, at a glance

• Top: which ledger this is, which code revision ran it, and who set it up.
• A row per unit: four say closed (done and independently verified), one says paused, waiting on a person.
• One open question, front and center: "can we pay the rent?", flagged as blocking until someone answers it.
• One remembered fact (the grocery-store categorization from earlier), tagged with a date to double-check it's still true.

The next two screenshots both drill into a single unit's full history. It is the same view applied to two different outcomes, so you can see both paths through it: one unit that's waiting on a person, and one that made a mistake and got corrected automatically.

Drill-down #1: the unit that's waiting on a person

• This is the payment unit from step 3, the one that stopped to ask "pay the landlord?"
• Its one and only attempt is marked paused, not failed. It is waiting on an answer.
• Below that: the exact question it asked, and who it's waiting on to answer.
• Further down: a timestamped log of everything that's happened to this unit so far, in order.
• There's no verification section here yet, because the unit hasn't done anything that needs checking.

Drill-down #2: the unit that made a mistake, then fixed it

• This is the "careless" run from step 3, the one that edited the bank statement by mistake.
• Its first attempt is marked failed, with the specific tests and checks that caught it named outright.
• Next: the system's decision to try again, plus a hint telling the retry exactly what went wrong.
• Its second attempt is marked closed. This time everything passed, including one final check run after merging.

Two more views exist in the same dashboard, shown smaller here since they're less central to this walkthrough:

More of this same dashboard (the full topology, the assurance and lifecycle views, a live instance under drift) is shown on the product page.

In the docs: The control room

The honest limits of this example

Four ways this walkthrough is simpler than a real deployment would be, each stated outright.

The recipe

You've now followed a household ledger end to end: designed, declared, run, and read back. Here are the same eight moves, generalized, for whatever you're actually building.

1. Name the domain output and the source of truth. Decide what is protected.
2. List the unit types. For each, decide what it may write, which tools by effect, and which host-run checks judge it. Put the domain's own checks outside every write grant. Where a unit must be allowed to write tests, declare inherited-tests so the suite that judges it is the one it inherited.
3. Write the checks. If the domain has no deterministic check of its own, you are about to build a system whose only verification is self-report. Stop and write one.
4. Write the identity: the invariants, each with the mechanism that checks it, and the words the instance does not use.
5. Write one contract per unit of the first piece of work: fixed, delegated, unresolved, expected evidence. Cite an invariant or a person for every fixed decision.
6. Set budgets and routes per unit type. Decide who may answer what.
7. regulator init with the declared prefixes, then doctor, then drive the first unit and read the evidence, not the summary.
8. Script the close (a bookkeeper and a careless one) so it runs under CI, then run it live and compare. That is the eval harness pointed at your domain.

Nothing on this page was hypothetical, and neither is your domain's version of it. The fixture and every file in step 2 are real, checked-in code. Start by reading them, not from a blank file.

In the docs: The worked example, in full · Definition files