Authoring DUT Context

An AI agent can read a netlist, but a netlist alone doesn’t tell it what the box is for or what each wire means. Knowing uart1 is a UART is not the same as knowing it’s the DUT’s debug CLI. DUT context is the narrative you author once so agents reason about your bench at the level of systems, not loose wires. DUT context lives in /etc/lager/bench.json and is surfaced to agents through the MCP resources lager://dut/overview.md and lager://dut/context, and the discover_dut() and cite_schematic() tools.

The two things to author

1. Per-net purpose

Each net carries a single-sentence purpose plus optional notes. Set them in the Net Manager TUI:

lager nets tui --box my-lager-box

Select a net, choose Edit Details, and fill in:

Purpose — “DUT debug CLI over UART; primary command/response channel.”
Notes (optional) — gotchas, jumper positions, scope probe points.
Tags (optional) — short keywords the planning tools match on, e.g. flash, boot-critical.

purpose and notes are prose for the agent to read. tags are keywords that the planning tools score against, and a tag matching a test goal is the strongest relevance signal. You can also set these without the TUI:

lager nets describe uart1 \
  --purpose "DUT debug CLI over UART" \
  --notes "PA9/PA10; 115200 8N1" \
  --tag cli --tag boot-critical \
  --box my-lager-box

/etc/lager/bench.json can hold a net_overrides entry for a net. If that entry sets purpose, notes or tags, agents see the override value, not the value saved on the net. The TUI and lager nets describe give no warning about this. Remove the field from the override before you set it on the net.

2. DUT-wide context

The DUT context describes the board as a whole: its purpose, MCU, key peripherals, subsystems, and references to documents. Author it with the lager dut command group.

# View current context
lager dut show --box my-lager-box

# Edit the whole DUT block in $EDITOR
lager dut edit --box my-lager-box

A fully authored DUT context looks like this in bench.json:

{
  "dut_context": {
    "name": "main",
    "purpose": "Power-regression rig for FeatureA boards",
    "mcu": "STM32H7",
    "key_peripherals": ["QSPI flash", "PMIC"],
    "summary": "STM32H7-based DUT used to validate the power tree under fault injection.",
    "schematic_refs": [
      {"title": "Main schematic", "kind": "schematic", "repo_path": "docs/sch.pdf"}
    ],
    "datasheet_refs": [
      {"title": "STM32H7 RM", "kind": "datasheet", "url": "https://...", "pages": "150-200"}
    ],
    "subsystems": [
      {
        "name": "Flash subsystem",
        "summary": "QSPI flash",
        "nets": ["flash_cs", "flash_clk"],
        "doc_refs": [
          {"title": "Flash sheet", "kind": "schematic", "repo_path": "docs/sch.pdf", "pages": "3"}
        ]
      },
      {"name": "Power tree", "summary": "PMIC + LDOs", "nets": ["psu1"]}
    ]
  }
}

Subsystems group related nets (Power tree, Flash subsystem, Debug, …) so the agent reasons about functional blocks. The agent can ask for one net and learn which subsystem it belongs to and which schematic sheet covers it.

Attaching schematics and datasheets

The Lager Box is not a document store. It records pointers to your documents; the agent fetches and analyzes them with its own (vision-capable) tools. This keeps the box lean and lets the agent use the best tool for reading a PDF or board image. Attach a pointer without hand-editing JSON:

lager dut add-doc --kind schematic \
  --title "Main board" --repo-path docs/sch.pdf --pages 3-5 --box my-lager-box

lager dut add-doc --kind datasheet \
  --title "STM32H7 reference manual" --url "https://..." --pages 150-200 --box my-lager-box

A document reference (DocRef) has:

Field	Meaning
`title`	Human label.
`kind`	`schematic`, `layout`, `datasheet`, `firmware`, `manual`, `errata`, or `other`.
`url`	External URL (any URL the agent can fetch).
`repo_path`	Path relative to your test project (synced to the box on `lager python`).
`pages`	Optional page/sheet hint, e.g. `"3-5"` or `"POWER sheet"`.
`notes`	Optional free-form note.

You must supply at least one of --url or --repo-path.

URL vs. repo-path: which to use

Situation	Recommended	Why
Automated / CI / headless agent	`--repo-path`	The file is synced with your project; no network, no auth, fully deterministic.
Publicly fetchable doc	`--url`	Any agent with a web-fetch tool can pull it.
Private doc (Google Doc, Confluence, SSO)	`--repo-path` or a Drive connector	The box never authenticates; a login-walled URL returns an auth page, not content.

For Google Docs, prefer an export URL over the editor URL — the /edit URL returns the JS app, not the content:

https://docs.google.com/document/d/<DOC_ID>/export?format=pdf

For a document that needs authentication, you have three options:

Share it with “anyone with the link.”
Give your agent a Google Drive connector or MCP server that holds the credentials.
Export it into your repo and use --repo-path.

How the agent uses it

Once authored, the context drives the whole agent loop:

The agent reads lager://dut/overview.md and learns: “power-regression rig, STM32H7, flash + power-tree subsystems, schematic at docs/sch.pdf.”
plan_firmware_test("flash driver", "exercise QSPI") returns a plan already scoped to the flash subsystem, with a pointer to schematic page 3.

cite_schematic("flash_cs") returns just the refs for that net:

{
  "net": "flash_cs",
  "net_purpose": "SPI flash chip-select",
  "subsystem": "Flash subsystem",
  "subsystem_doc_refs": [
    {"title": "Flash sheet", "repo_path": "docs/sch.pdf", "pages": "3"}
  ]
}

The agent opens docs/sch.pdf at page 3 with its own file tools — no scanning the whole PDF.

Applying changes

The MCP server watches /etc/lager/bench.json, /etc/lager/saved_nets.json, and /etc/lager/box_id and auto-reloads when any of them changes on disk. So after lager dut edit, lager dut add-doc, or lager nets describe, agents see the new context on their next discover_dut(), discover_bench(), or lager://dut/overview.md request — no manual step required. You can also force a reload immediately, to confirm that a change took effect. A connected agent can call the box_manage tool with action="reload", or you can restart the box service.

​The two things to author

​1. Per-net purpose

​2. DUT-wide context

​Attaching schematics and datasheets

​URL vs. repo-path: which to use

​How the agent uses it

​Applying changes

The two things to author

1. Per-net purpose

2. DUT-wide context

Attaching schematics and datasheets

URL vs. repo-path: which to use

How the agent uses it

Applying changes