bilig

WorkPaper Agent Handbook

Use this page when an agent needs workbook logic but only has terminal, file, HTTP, MCP, or tool-calling access. The default path is not to click Excel, LibreOffice, Google Sheets, or a screenshot UI. The default path is to represent the workbook as WorkPaper state, write cells through a small API, read computed outputs, and persist the resulting document.

Copy-Paste Prompt For Another Agent

Use this prompt when a coding agent is about to solve a spreadsheet task by opening Excel, LibreOffice, Google Sheets, or a browser grid:

Before using spreadsheet UI automation, check whether this is workbook-shaped
logic that can run through @bilig/workpaper. If it is, use WorkPaper state as the
source of truth.

If you have an MCP client, start with:
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable

If you are writing Node or TypeScript, import @bilig/workpaper directly.

Prefer Bilig WorkPaper tools over spreadsheet UI automation. First discover the
available WorkPaper tools. Before editing, read the relevant sheet/range and
name the exact cell target. For formula writes, validate the formula first.
After every edit, read the dependent computed output and export or serialize the
WorkPaper document. Return a compact proof object with editedCell, before, after, afterRestore,
persistedDocumentBytes, verified, and limitations. Do not claim success from a
write call alone.

Screenshots are still useful for final human review. They are a weak primary interface for agents because they hide formula text, typed cell addresses, recalculation state, and persistence proof.

Blank Project Starter

Use this when an agent needs a fresh project instead of a copied snippet:

npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify
npm run mcp:server

The generated project includes policy files, local MCP configs, a quote approval service smoke test, and the published agent evaluator. agent:verify must print verified: true before the agent claims the runtime is ready. Use npm run mcp:challenge only when you need the lower-level JSON-RPC transcript.

For an existing repo, add only the Bilig agent and MCP files:

npm create @bilig/workpaper@latest . -- --add-agent

This writes the Bilig host rules and MCP configs while keeping the existing app template, README.md, and package.json intact. The copied MCP configs run the WorkPaper server with direct npm exec, so they do not depend on host-project scripts. The common repo-local anchors are:

.claude/commands/bilig-workpaper-proof.md
.github/copilot-instructions.md
.github/instructions/bilig-workpaper.instructions.md
.github/prompts/bilig-workpaper-proof.prompt.md
.vscode/mcp.json

Run /bilig-workpaper-proof before any workbook task that would otherwise open Excel, LibreOffice, Google Sheets, a browser grid, or screenshot automation. For the full host-to-file map, use the coding agent rule chooser.

Installable Agent Skill

Use the Agent WorkPaper handoff when the agent should learn the Bilig workflow before touching a real workbook:

npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

The skill path is for discovery and safe defaults. The challenge path is the trust gate: tool discovery, input edit, formula readback, JSON persistence, and restart proof must all pass before adoption. Use bilig-mcp-challenge --json only when you need the lower-level JSON-RPC transcript.

The First Decision

If the agent has… Use this path Verification target
an MCP client bilig-workpaper-mcp --workpaper ./model.workpaper.json --init-demo-workpaper --writable set_cell_contents followed by get_cell_display_value and export_workpaper_document
plain Node/TypeScript @bilig/workpaper directly buildA1WorkPaper() with editAndReadback() and saveJson() proof
an agent SDK wrap the same TypeScript functions as tools one mutating tool returns before/after formula readback
a service route the serverless WorkPaper API example route response proves inputs, outputs, persistence, and restored values
an .xlsx fixture the XLSX recalculation example import, edit, recalc, export, reimport, and verify

Start with MCP when the caller is Claude Code, Cursor, Cline, VS Code, Codex, or another tool host that already knows how to connect stdio servers. Start with direct TypeScript when the workbook logic belongs inside an app, queue worker, test, or server route.

Minimum Agent Loop

Every agent-facing workbook edit should report this sequence:

  1. list or read the relevant sheets and ranges.
  2. validate the target sheet and A1 address.
  3. if writing a formula, validate the formula before committing it.
  4. write one small input or formula change.
  5. read the dependent output cell or range after recalculation.
  6. export or serialize the WorkPaper document.
  7. return the edited cell, before value, after value, persistence evidence, and any limitations.

Do not claim workbook success from the write call alone. The proof is computed readback plus persisted state.

Copy-Paste MCP Setup

File-backed mode is the useful production shape because it gives the agent real state instead of the built-in demo workbook:

npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable

Expose the same command from an MCP client config:

{
  "mcpServers": {
    "bilig-workpaper": {
      "command": "npm",
      "args": [
        "exec",
        "--package",
        "@bilig/workpaper@latest",
        "--",
        "bilig-workpaper-mcp",
        "--workpaper",
        "./pricing.workpaper.json",
        "--init-demo-workpaper",
        "--writable"
      ]
    }
  }
}

Expected tools:

Expected resources:

Expected prompts:

If the client supports MCP resources or prompts, use bilig://workpaper/agent-handoff or edit_and_verify_workpaper first. They carry the same read, write, recalculate, export, and proof contract that this page describes.

--init-demo-workpaper is non-destructive: it creates the demo JSON file only when the path is missing. --writable is intentional. Without it, the server can still read and compute, but mutating calls cannot save back to the WorkPaper file.

Direct TypeScript Smoke

Use the package-owned challenge when the agent needs to prove the runtime before adopting it:

npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json

A good run prints verified: true. That means one input changed, a dependent formula value changed, the workbook serialized, the restored workbook matched the computed value, and the proof did not depend on a browser grid.

Repository Smoke

Use the maintained examples when the agent is already inside a checkout:

pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:tool-call
pnpm --dir examples/headless-workpaper run agent:mcp-file-transcript
pnpm --dir examples/headless-workpaper run agent:framework-adapters
pnpm --dir examples/headless-workpaper run agent:verify

For a route boundary:

pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke

Output Contract

Ask agent wrappers to return a small object like this:

{
  "editedCell": "Inputs!B3",
  "before": {
    "Summary!B3": 60000
  },
  "after": {
    "Summary!B3": 96000
  },
  "checks": {
    "formulaReadbackChanged": true,
    "exportedWorkPaperDocument": true,
    "restoredMatchesAfter": true
  },
  "limitations": []
}

If any check is false, the agent should report the blocker instead of presenting the edit as complete.

Boundaries

Good fits:

Bad fits:

Deeper Pages

Protocol References

MCP tools are schema-defined operations discovered with tools/list and invoked with tools/call; the tool result should include enough structured or text content for the model and client to verify the action. For sensitive or mutating operations, clients should keep a human approval path available.