@bilig/workpaper 0.161.0 → 0.164.1

package/AGENTS.md

@@ -25,13 +25,27 @@ Use this file when an AI coding agent, MCP client, or tool host needs workbook f
    `.claude/commands/bilig-workpaper-proof.md`.
 10. If you are using OpenCode, use `opencode.jsonc` and
     `.opencode/agents/bilig-workpaper.md`.
-11. If you are using Cursor, Windsurf/Cascade, Cline, or Continue, use
+11. If you are using Aider, load `CONVENTIONS.md` through
+    `.aider.conf.yml`.
+12. If you are using OpenHands, read `AGENTS.md`, then the project skill at
+    `.agents/skills/bilig-workpaper/SKILL.md`; add the local MCP server with
+    `https://proompteng.github.io/bilig/openhands-workpaper-mcp.html`.
+13. If you are using Goose, start from the local recipe at
+    `examples/goose-workpaper-mcp/recipe.yaml` and the proof guide at
+    `https://proompteng.github.io/bilig/goose-workpaper-mcp.html`.
+14. If you are using Cursor, Kiro, Trae, Qodo IDE, Zed, Windsurf/Cascade, Cline, or Continue, use
     `.cursor/rules/bilig-workpaper.mdc` or
+    `.kiro/steering/bilig-workpaper.md`,
+    `.trae/rules/bilig-workpaper.md` with `.trae/mcp.json`,
+    `https://proompteng.github.io/bilig/qodo-workpaper-mcp.html` for Qodo Agentic Tools MCP JSON,
+    `.zed/settings.json`,
     `.devin/rules/bilig-workpaper.md`,
     `.windsurf/rules/bilig-workpaper.md`,
     `.clinerules/bilig-workpaper.md`, or
-    `.continue/rules/bilig-workpaper.md`.
-12. Start the MCP server or import `@bilig/workpaper` directly.
+    `.continue/rules/bilig-workpaper.md`. Continue Agent mode can also use
+    `.continue/mcpServers/bilig-workpaper.yaml` for the project-local
+    file-backed WorkPaper MCP server.
+15. Start the MCP server or import `@bilig/workpaper` directly.
 
 Remote MCP clients that support Streamable HTTP can smoke-test the stateless
 demo endpoint at `https://bilig.proompteng.ai/mcp`. Directory scanners that inspect the
@@ -72,6 +86,7 @@ npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --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
 npm exec --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells "Summary!B7,Inputs!B2"
 ```
 
@@ -82,7 +97,11 @@ Claude Desktop users can install the released MCPB bundle from:
 
 ## Direct TypeScript
 
-Use `WorkPaper.buildFromSheets()` for hand-authored models, `setCellContents()` for edits, `getCellDisplayValue()` for readback, and `exportWorkPaperDocument()` plus `serializeWorkPaperDocument()` for persistence proof.
+Use `buildA1WorkPaper()` for hand-authored models. Prefer
+`book.set("Inputs!B2", value)`, `book.display("Summary!B2")`, and
+`book.editAndReadback("Inputs!B2", value, { readbackRange: "Summary!B2" })`
+before reaching for lower-level sheet ids or zero-based `{ row, col }`
+addresses.
 
 ## Boundaries
 

package/README.md

@@ -1,7 +1,6 @@
 # @bilig/workpaper
 
-WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas
-in Node.js services and agents.
+Bilig WorkPaper is an API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.
 
 Use this when business logic is easiest to review as workbook cells and
 formulas, but the calculation needs to run in a backend service, queue worker,
@@ -48,7 +47,7 @@ The useful output is not a write-call status. It is readback proof:
   "door": "agent-mcp",
   "verified": true,
   "packageVersions": {
-    "@bilig/workpaper": "0.153.0"
+    "@bilig/workpaper": "0.163.0"
   },
   "evidence": {
     "scenario": "revenue-plan",
@@ -127,9 +126,9 @@ not the first-run path:
 ## Use A WorkPaper In Node
 
 ```ts
-import { WorkPaper } from '@bilig/workpaper'
+import { buildA1WorkPaper } from '@bilig/workpaper'
 
-const workbook = WorkPaper.buildFromSheets({
+const book = buildA1WorkPaper({
   Inputs: [
     ['Metric', 'Value'],
     ['Units', 40],
@@ -141,44 +140,29 @@ const workbook = WorkPaper.buildFromSheets({
   ],
 })
 
-function cell(address: string) {
-  const parsed = workbook.simpleCellAddressFromString(address)
-
-  if (parsed === undefined) {
-    throw new Error(`Unknown cell: ${address}`)
-  }
-
-  return parsed
-}
-
-function setCell(address: string, value: string | number | boolean | null) {
-  workbook.setCellContents(cell(address), value)
-}
-
-function displayAt(address: string) {
-  return workbook.getCellDisplayValue(cell(address))
-}
-
-const before = displayAt('Summary!B2')
-
-setCell('Inputs!B2', 48)
-setCell('Inputs!B3', 1500)
-
-const after = displayAt('Summary!B2')
-const document = workbook.exportSnapshot()
+const proof = book.editAndReadback('Inputs!B2', 48, {
+  readbackRange: 'Summary!B2',
+})
 
 console.log({
-  editedCells: ['Inputs!B2', 'Inputs!B3'],
-  readCell: 'Summary!B2',
-  before,
-  after,
-  persistedDocumentBytes: JSON.stringify(document).length,
-  verified: after === '72000',
+  editedCell: proof.editedCell,
+  before: proof.beforeReadback.displayValues,
+  after: proof.afterReadback.displayValues,
+  afterRestore: proof.restoredReadback.displayValues,
+  persistedDocumentBytes: proof.persistedDocumentBytes,
+  verified: proof.verified,
 })
 
-workbook.dispose()
+book.dispose()
 ```
 
+Use `book.set('Inputs!B2', 48)`, `book.setMany({ 'Inputs!B3': 1500 })`,
+`book.readMany(['Inputs!B2', 'Summary!B2'])`, `book.display('Summary!B2')`,
+and `book.saveJson()` when you do not need the full proof object. Use
+`book.editManyAndReadback()` when several inputs should commit as one atomic
+proof with typed readback comparison, formula diagnostics, persistence, and
+restore checks.
+
 ## Use WorkPaper Tools With The Vercel AI SDK
 
 Install the AI SDK and Zod in the application that owns the agent loop:

package/SKILL.md

@@ -119,6 +119,12 @@ 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 XLSX preflight transcript, run
+`pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight`.
+It requires `analyze_workbook_risk`, `set_cell_contents_and_readback`,
+`export_workpaper_document`, `Inputs!B3`, `Summary!B3`, `60000 -> 96000`,
+and `verified: true`.
+
 After a write, always read the dependent output cell and export the WorkPaper
 document. If the listed tool set includes `set_cell_contents_and_readback`,
 prefer it for stateless clients because the edit and dependent readback happen
@@ -142,9 +148,9 @@ stdio command when the workflow must persist a project WorkPaper JSON file.
 Use `@bilig/workpaper` directly when workbook logic belongs in a service, queue worker, test, or route:
 
 ```ts
-import { WorkPaper, exportWorkPaperDocument, serializeWorkPaperDocument } from '@bilig/workpaper'
+import { buildA1WorkPaper } from '@bilig/workpaper'
 
-const workbook = WorkPaper.buildFromSheets({
+const book = buildA1WorkPaper({
   Inputs: [
     ['Metric', 'Value'],
     ['Customers', 20],
@@ -156,17 +162,19 @@ const workbook = WorkPaper.buildFromSheets({
   ],
 })
 
-const inputs = workbook.getSheetId('Inputs')
-const summary = workbook.getSheetId('Summary')
-if (inputs === undefined || summary === undefined) {
-  throw new Error('Workbook is missing required sheets')
-}
+const proof = book.editAndReadback('Inputs!B2', 32, {
+  readbackRange: 'Summary!B2',
+})
 
-workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32)
-const revenue = workbook.getCellDisplayValue({ sheet: summary, row: 1, col: 1 })
-const saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }))
+console.log({
+  editedCell: proof.editedCell,
+  after: proof.afterReadback.displayValues,
+  afterRestore: proof.restoredReadback.displayValues,
+  persistedDocumentBytes: proof.persistedDocumentBytes,
+  verified: proof.verified,
+})
 
-console.log({ revenue, savedBytes: saved.length })
+book.dispose()
 ```
 
 ## XLSX Formula Clinic
@@ -213,6 +221,7 @@ If any readback step fails, report the blocker instead of claiming the workbook
 - MCP server guide: https://proompteng.github.io/bilig/mcp-workpaper-tool-server.html
 - OpenHands MCP setup: https://proompteng.github.io/bilig/openhands-workpaper-mcp.html
 - OpenCode MCP setup: https://proompteng.github.io/bilig/opencode-workpaper-mcp.html
+- Goose MCP recipe: https://proompteng.github.io/bilig/goose-workpaper-mcp.html
 - Open WebUI tool setup: https://proompteng.github.io/bilig/open-webui-workpaper-mcp.html
 - LobeHub MCP setup: https://proompteng.github.io/bilig/lobehub-workpaper-mcp.html
 - AnythingLLM MCP setup: https://proompteng.github.io/bilig/anythingllm-workpaper-mcp.html

package/bin/bilig-evaluate.js

@@ -1,4 +1,2 @@
 #!/usr/bin/env node
-const { runBiligEvaluatorCli } = await import('@bilig/xlsx-formula-recalc/evaluator')
-
-process.exitCode = runBiligEvaluatorCli(process.argv.slice(2))
+await import('../dist/evaluator-bin.js')

package/dist/evaluator-bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/evaluator-bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runBiligEvaluatorCli } from './evaluator.js';
+process.exitCode = await runBiligEvaluatorCli(process.argv.slice(2));
+//# sourceMappingURL=evaluator-bin.js.map

package/dist/evaluator-bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator-bin.js","sourceRoot":"","sources":["../src/evaluator-bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAErD,OAAO,CAAC,QAAQ,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/evaluator.d.ts

@@ -0,0 +1,2 @@
+export { biligEvaluatorSchemaVersion, buildBiligEvaluatorProof, listBiligEvaluatorDoors, runBiligEvaluatorCli } from 'bilig-workpaper';
+export type { BiligEvaluatorCliContext, BiligEvaluatorDoor, BiligEvaluatorDoorSummary, BiligEvaluatorEvidence, BiligEvaluatorProof, BiligEvaluatorScenario, } from 'bilig-workpaper';

package/dist/evaluator.js

@@ -0,0 +1,2 @@
+export { biligEvaluatorSchemaVersion, buildBiligEvaluatorProof, listBiligEvaluatorDoors, runBiligEvaluatorCli } from 'bilig-workpaper';
+//# sourceMappingURL=evaluator.js.map

package/dist/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../src/evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA"}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@bilig/workpaper",
-  "version": "0.161.0",
-  "description": "WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.",
+  "version": "0.164.1",
+  "description": "Bilig WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.",
   "keywords": [
     "agent-tools",
     "ai-agents",
     "bilig",
+    "bilig-workpaper",
     "excel-formulas",
     "formula-engine",
     "headless-spreadsheet",
@@ -25,6 +26,7 @@
     "spreadsheet-formulas",
     "workbook",
     "workbook-agent",
+    "workbook-api",
     "workpaper",
     "xlsx"
   ],
@@ -76,6 +78,11 @@
       "import": "./dist/mcp.js",
       "default": "./dist/mcp.js"
     },
+    "./evaluator": {
+      "types": "./dist/evaluator.d.ts",
+      "import": "./dist/evaluator.js",
+      "default": "./dist/evaluator.js"
+    },
     "./xlsx": {
       "types": "./dist/xlsx.d.ts",
       "import": "./dist/xlsx.js",
@@ -89,9 +96,9 @@
     "build": "pnpm --dir ../.. --filter bilig-workpaper build && rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@bilig/headless": "0.161.0",
-    "@bilig/xlsx-formula-recalc": "0.161.0",
-    "bilig-workpaper": "0.161.0"
+    "@bilig/headless": "0.164.1",
+    "@bilig/xlsx-formula-recalc": "0.164.1",
+    "bilig-workpaper": "0.164.1"
   },
   "devDependencies": {
     "ai": "6.0.195",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.proompteng/bilig-workpaper",
   "title": "Bilig WorkPaper",
   "description": "Formula readback, input edits, JSON persistence, and workbook risk preflight for agents.",
-  "version": "0.161.0",
+  "version": "0.164.1",
   "repository": {
     "url": "https://github.com/proompteng/bilig",
     "source": "github"
@@ -18,7 +18,7 @@
     {
       "registryType": "npm",
       "identifier": "@bilig/workpaper",
-      "version": "0.161.0",
+      "version": "0.164.1",
       "transport": {
         "type": "stdio"
       }