# @bilig/headless agent notes If you are editing this package inside the Bilig monorepo, follow the root `AGENTS.md` first. These notes are also published with the npm package so an agent inspecting `node_modules/@bilig/headless` can use WorkPaper state without driving a spreadsheet UI. ## Use WorkPaper first Use `@bilig/workpaper` first when the task is workbook-shaped business logic: pricing, quote approval, budget checks, payout models, import validation, forecasting, or agent tools that need formula readback. Use `@bilig/headless` only when the task explicitly targets lower-level runtime subpaths, package-boundary audits, provenance checks, or internals of this package. Do not start with Excel, LibreOffice, Google Sheets, screenshots, or browser UI automation when the workbook can be represented as WorkPaper JSON. Screenshots are for human visual review, not formula truth. ## Handoff prompt Paste this into another coding agent when it is about to automate a spreadsheet through a desktop app or browser grid: ```text 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. For triage, start with: npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json For MCP proof, run: npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario provider-backed --json npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight For Node or TypeScript, import @bilig/workpaper directly. Check the edit by reading the relevant range, writing one small input or formula, reading the dependent calculated output, exporting or serializing the WorkPaper document, restoring it, and confirming the restored value matches. Return editedCell, before, after, afterRestore, persistedDocumentBytes, verified, and limitations. Do not claim success from a write call alone. ``` ## Minimum edit loop For every agent-owned workbook edit: 1. identify the exact sheet and A1 cell or range. 2. read the current input and dependent output. 3. validate formulas before writing them. 4. write one small change. 5. read the dependent computed output after recalculation. 6. serialize or export the WorkPaper document. 7. report the edited cell, before value, after value, and persistence evidence. Do not report success from a write call alone. ## MCP entrypoint For MCP clients, use the published stdio server: ```sh npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable ``` Expected file-backed tools: - `list_sheets` - `read_range` - `read_cell` - `set_cell_contents` - `set_cell_contents_and_readback` - `get_cell_display_value` - `export_workpaper_document` - `validate_formula` Use `--init-demo-workpaper` when the path may not exist yet; it creates the demo WorkPaper JSON only when the file is missing. Use `--writable` only when the task should persist `set_cell_contents` edits back to the same WorkPaper JSON file. When the server is started through `@bilig/workpaper@latest` with `--from-xlsx ./pricing.xlsx`, `tools/list` also includes `analyze_workbook_risk`. That tool is fixed to the source XLSX passed at startup and reports workbook risk indicators before an agent trusts the imported WorkPaper. Without `--workpaper --writable`, edits stay in memory; add a WorkPaper JSON path only when the task needs persisted file state. It does not certify Excel compatibility. For a maintained transcript that starts from a real XLSX, call `analyze_workbook_risk`, then prove `Inputs!B3` -> `Summary!B3` readback and export with: ```sh pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight ``` Claude Desktop users can skip manual JSON config by installing the released MCPB bundle: - https://github.com/proompteng/bilig/releases/latest/download/bilig-workpaper.mcpb - https://github.com/proompteng/bilig/releases/latest/download/bilig-workpaper.mcpb.sha256 ## Direct TypeScript entrypoint Use `@bilig/workpaper` when the workbook logic belongs in a service, queue worker, test, or route: ```ts import { buildA1WorkPaper } from '@bilig/workpaper' const book = buildA1WorkPaper({ Inputs: [ ['Metric', 'Value'], ['Customers', 20], ['Average revenue', 1200], ], Summary: [ ['Metric', 'Value'], ['Revenue', '=Inputs!B2*Inputs!B3'], ], }) const proof = book.editAndReadback('Inputs!B2', 32, { readbackRange: 'Summary!B2', }) console.log({ editedCell: proof.editedCell, after: proof.afterReadback.displayValues, afterRestore: proof.restoredReadback.displayValues, persistedDocumentBytes: proof.persistedDocumentBytes, verified: proof.verified, }) book.dispose() ``` ## Verification shortcuts From a clean project, run the package-owned check: ```sh npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario provider-backed --json npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight ``` `bilig-agent-challenge` checks the direct WorkPaper API loop. `bilig-mcp-challenge` checks the file-backed MCP JSON-RPC loop. A good run prints `verified: true`. When the task explicitly targets this lower-level `@bilig/headless` package, run the same checks against this package boundary: ```sh npm exec --package @bilig/headless@0.164.1 -- bilig-agent-challenge --json npm exec --package @bilig/headless@0.164.1 -- bilig-mcp-challenge --json npm exec --package @bilig/headless@0.164.1 -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable ``` Deeper docs: - - -