@bilig/workpaper 0.164.1 → 0.164.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/AGENTS.md +1 -1
  2. package/README.md +49 -55
  3. package/SKILL.md +11 -12
  4. package/package.json +6 -10
  5. package/server.json +2 -2
package/AGENTS.md CHANGED
@@ -55,7 +55,7 @@ still prefer the file-backed stdio command below.
55
55
 
56
56
  ## Default Decision
57
57
 
58
- Use Bilig when the task is workbook-shaped business logic: pricing, budget checks, payout models, import validation, forecasts, agent tools, or route handlers that need formula readback.
58
+ Use Bilig when the task is workbook-shaped business logic: pricing, budget checks, payout models, import validation, forecasts, tool integrations, or route handlers that need formula readback.
59
59
 
60
60
  Do not start with UI automation when the workbook can be represented as WorkPaper state. Screenshots are useful for human review; they are not formula truth.
61
61
 
package/README.md CHANGED
@@ -1,10 +1,11 @@
1
1
  # @bilig/workpaper
2
2
 
3
- Bilig WorkPaper is an API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.
3
+ Bilig WorkPaper is an API, CLI evaluator, and optional MCP server for
4
+ workbook-shaped business logic in Node.js.
4
5
 
5
6
  Use this when business logic is easiest to review as workbook cells and
6
7
  formulas, but the calculation needs to run in a backend service, queue worker,
7
- serverless route, test, or coding-agent tool.
8
+ serverless route, test, or tool.
8
9
 
9
10
  `@bilig/workpaper` is the canonical scoped npm entrypoint. The unscoped
10
11
  `bilig-workpaper` package remains published as a compatibility and search alias.
@@ -19,24 +20,23 @@ npm install @bilig/workpaper
19
20
 
20
21
  Pick the door that matches the state you own:
21
22
 
22
- | Door | Run first | What it proves |
23
- | -------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
24
- | Unsure / agent handoff | `npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json` | compact decision card before the agent opens Excel, Sheets, or a browser grid. |
25
- | Node service or test | `npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json` | edit input, recalculate output, persist JSON, restore, and return `verified: true`. |
26
- | Coding agent or MCP client | `npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json` | tool discovery, cell mutation, formula readback, JSON export, restart proof, and `verified: true`. |
27
- | New project | `npm create @bilig/workpaper@latest pricing-agent -- --agent` | a starter with `AGENTS.md`, MCP config, and `npm run agent:verify` wired to the same proof loop. |
23
+ | Door | Run first | What it proves |
24
+ | ----------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
25
+ | Node service or test | `npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json` | edit input, recalculate output, persist JSON, restore, and return `verified: true`. |
26
+ | New project | `npm create @bilig/workpaper@latest pricing-workpaper` | a starter wired to the same WorkPaper proof loop. |
27
+ | Tool host or MCP client | `npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json` | tool discovery, cell mutation, formula readback, JSON export, restart proof, and `verified: true`. |
28
+ | Unsure which proof fits | `npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json` | compact routing card with proof commands, evidence fields, and public links. |
28
29
 
29
- `bilig-agent-start --json` is intentionally small. It gives an agent the
30
- workbook-vs-XLSX decision card, first proof commands, required evidence fields,
31
- expected MCP tools, and public discovery links without asking it to read the
32
- whole site.
30
+ `bilig-agent-start --json` is intentionally small. It prints first proof
31
+ commands, required evidence fields, expected MCP tools, and public discovery
32
+ links without asking a tool host to read the whole site.
33
33
 
34
34
  ## What Success Looks Like
35
35
 
36
- Run the agent proof without cloning the repo:
36
+ Run the service proof without cloning the repo:
37
37
 
38
38
  ```sh
39
- npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario revenue-plan --json
39
+ npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json
40
40
  ```
41
41
 
42
42
  The useful output is not a write-call status. It is readback proof:
@@ -44,39 +44,33 @@ The useful output is not a write-call status. It is readback proof:
44
44
  ```json
45
45
  {
46
46
  "schemaVersion": "bilig-evaluator.v1",
47
- "door": "agent-mcp",
47
+ "door": "workpaper-service",
48
48
  "verified": true,
49
49
  "packageVersions": {
50
50
  "@bilig/workpaper": "0.163.0"
51
51
  },
52
52
  "evidence": {
53
- "scenario": "revenue-plan",
54
- "editedCell": "Deals!C2",
55
- "readbackRange": "Summary!B2:B8",
56
- "after": {
57
- "totalRevenue": 36900,
58
- "westCustomers": 38
59
- },
60
- "checks": {
61
- "totalRevenueRecalculated": true,
62
- "sumifReadbackChanged": true,
63
- "xlookupReadbackStable": true,
64
- "filterSpillUpdated": true,
65
- "persistedToDisk": true,
66
- "restartReadbackMatchesAfter": true
67
- }
53
+ "editedCell": "Inputs!B2",
54
+ "dependentCell": "Summary!B2",
55
+ "before": 24000,
56
+ "after": 38400,
57
+ "afterRestore": 38400,
58
+ "persistedDocumentBytes": 999
68
59
  }
69
60
  }
70
61
  ```
71
62
 
72
- If that is the contract your service or agent needed, star the repo so you can
73
- find it again: <https://github.com/proompteng/bilig/stargazers>. Watch releases
74
- if this is close to production: <https://github.com/proompteng/bilig/subscription>.
63
+ If this is close to production, watch releases and review the public limits:
64
+ <https://github.com/proompteng/bilig/subscription>.
75
65
 
76
- For a richer agent check, add `--scenario revenue-plan` to the `agent-mcp`
66
+ For a richer tool check, add `--scenario revenue-plan` to the `agent-mcp`
77
67
  evaluator. It proves `SUM`, `SUMIF`, `XLOOKUP`, `FILTER`, a named expression,
78
68
  JSON persistence, and restart readback.
79
69
 
70
+ ```sh
71
+ npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario revenue-plan --json
72
+ ```
73
+
80
74
  If the workbook has provider-backed formulas such as `IMPORTRANGE`, run
81
75
  `npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario provider-backed --json`.
82
76
  That proves the formula fails closed with an adapter diagnostic, then verifies a
@@ -88,13 +82,13 @@ If one of those matches your workflow, keep Bilig nearby:
88
82
  Framework examples live in the repo instead of this first screen. Start with
89
83
  the closest runtime:
90
84
 
91
- - Agent tools: Vercel AI SDK, LangGraph, LangChain MCP adapters, Open WebUI,
85
+ - Tool runtimes: Vercel AI SDK, LangGraph, LangChain MCP adapters, Open WebUI,
92
86
  FastMCP, Agno, Pydantic AI, smolagents.
93
87
  - Workflow engines: Trigger.dev, Inngest, Temporal, Airflow, Dagster, Kestra,
94
88
  Prefect, Windmill.
95
89
  - Low-code and data tools: n8n, Pipedream, Directus, Airbyte, Meltano.
96
- - Existing `.xlsx` files: use `@bilig/xlsx-formula-recalc` for stale formula
97
- caches and exported workbook readback.
90
+ - Existing `.xlsx` files: use `@bilig/xlsx-formula-recalc` for saved-file
91
+ recalculation and exported workbook readback.
98
92
 
99
93
  ## Searchable Example Guides
100
94
 
@@ -234,17 +228,17 @@ npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./
234
228
 
235
229
  The challenge commands edit one input, recalculate dependent formulas, export
236
230
  WorkPaper JSON, restore it, and print a `verified: true` proof object.
237
- Use `--from-xlsx` when the agent already has an XLSX file: Bilig imports it once
231
+ Use `--from-xlsx` when the tool host already has an XLSX file: Bilig imports it once
238
232
  into an in-memory MCP server by default, or into persisted WorkPaper JSON when
239
233
  `--workpaper --writable` is also supplied. That XLSX-backed MCP path also lists
240
234
  `analyze_workbook_risk`, a read-only tool fixed to the source workbook passed at
241
- startup. It reports workbook risk indicators before an agent trusts the imported
235
+ startup. It reports workbook risk indicators before a workflow trusts the imported
242
236
  WorkPaper and does not certify Excel compatibility.
243
237
 
244
- ## Agent Adoption Kit
238
+ ## Tool Host WorkPaper Handoff
245
239
 
246
- When another coding agent is about to solve a spreadsheet task by opening Excel,
247
- LibreOffice, Google Sheets, or a screenshot grid, hand it the adoption kit
240
+ When a tool host is about to solve a spreadsheet task by opening Excel,
241
+ LibreOffice, Google Sheets, or a screenshot grid, hand it the WorkPaper checklist
248
242
  instead:
249
243
 
250
244
  ```sh
@@ -253,16 +247,16 @@ npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
253
247
  npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
254
248
  ```
255
249
 
256
- The kit gives the agent one path: install the instructions, run the no-key
257
- agent evaluator, paste a workbook edit task, and require computed readback plus
250
+ The kit gives the host one path: install the instructions, run the no-key MCP
251
+ evaluator, paste a workbook edit task, and require computed readback plus
258
252
  persisted state before reporting success. Use `bilig-mcp-challenge --json` only
259
253
  when debugging the lower-level MCP transcript.
260
254
 
261
255
  Docs: <https://proompteng.github.io/bilig/agent-adoption-kit.html>
262
256
 
263
- ## Agent Workflow Builders
257
+ ## Workflow Builders
264
258
 
265
- Use the local formula-readback server when an agent workflow platform should
259
+ Use the local formula-readback server when a workflow platform should
266
260
  orchestrate the task but Bilig should own workbook state:
267
261
 
268
262
  ```sh
@@ -323,10 +317,10 @@ Use `@bilig/xlsx-formula-recalc` when you only need to edit and recalculate
323
317
  XLSX files. Use `@bilig/exceljs-formula-recalc` when you already use ExcelJS
324
318
  and need recalculated formula results after changing inputs.
325
319
 
326
- ## Agent Commands And Optional MCP
320
+ ## Tool Commands And Optional MCP
327
321
 
328
- The npm tarball exposes the same CLI entrypoints through the canonical scoped package, so agents
329
- can install one focused package and still get the MCP stdio server:
322
+ The npm tarball exposes the same CLI entrypoints through the canonical scoped package, so tool
323
+ hosts can install one focused package and still get the MCP stdio server:
330
324
 
331
325
  ```ts
332
326
  import { createWorkPaperMcpServer } from '@bilig/workpaper/mcp'
@@ -342,21 +336,21 @@ npm create @bilig/workpaper@latest pricing-agent -- --agent
342
336
  ## Scope
343
337
 
344
338
  Bilig is not a desktop Excel clone. It is a formula workbook runtime for
345
- service-owned calculations, JSON persistence, XLSX import/export, and
346
- agent-readable readback. Unsupported Excel functions, external workbook links,
339
+ service-owned calculations, JSON persistence, XLSX import/export, and verified
340
+ readback. Unsupported Excel functions, external workbook links,
347
341
  macros, and volatile functions may need review.
348
342
 
349
343
  ## After The Proof
350
344
 
351
- If the starter or challenge output gives you `verified: true` for the service
352
- or agent workflow you need, star or bookmark Bilig so the WorkPaper runtime is
353
- easy to find again: <https://github.com/proompteng/bilig/stargazers>.
345
+ If the starter or challenge output matches your service or tool workflow,
346
+ keep the repository nearby for release notes and public limits:
347
+ <https://github.com/proompteng/bilig>.
354
348
 
355
349
  Watch releases if this is close to a production path:
356
350
  <https://github.com/proompteng/bilig/subscription>.
357
351
 
358
352
  If the model is close but blocked by a formula, import/export, persistence,
359
- framework, MCP, or package-boundary gap, open the smallest adoption blocker:
353
+ framework, MCP, or package-boundary gap, open the smallest implementation gap:
360
354
  <https://github.com/proompteng/bilig/discussions/new?category=general>.
361
355
 
362
356
  Full docs: <https://proompteng.github.io/bilig/>
package/SKILL.md CHANGED
@@ -1,12 +1,12 @@
1
1
  ---
2
2
  name: bilig-workpaper
3
3
  version: 0.1.0
4
- description: Use @bilig/workpaper WorkPaper state for workbook formulas, agent spreadsheet tools, MCP file-backed or remote demo editing, and XLSX formula bug reports without driving spreadsheet UI.
4
+ description: Use @bilig/workpaper WorkPaper state for workbook formulas, MCP editing, and tool integrations without driving spreadsheet UI.
5
5
  tags:
6
- - ai-agents
6
+ - agents
7
7
  - spreadsheet-automation
8
8
  - formulas
9
- - xlsx
9
+ - workpaper
10
10
  - mcp
11
11
  - typescript
12
12
  ---
@@ -24,7 +24,7 @@ Trigger this skill for tasks involving:
24
24
  - quote, budget, payout, pricing, import-validation, or forecast models;
25
25
  - agent spreadsheet tools that need deterministic cell addresses;
26
26
  - MCP clients that can run a stdio server or call a Streamable HTTP endpoint;
27
- - reduced XLSX formula bugs that need a local report.
27
+ - reduced formula/import bugs that need a local report.
28
28
 
29
29
  Do not trigger it for manual spreadsheet editing, Office macros, VBA, pivots, charts, COM automation, or exact Excel desktop behavior unless the user explicitly asks to compare Bilig against an Excel oracle.
30
30
 
@@ -114,7 +114,7 @@ treat its returned `tools` array as the source of truth for the currently publis
114
114
  When the server is started through `@bilig/workpaper@latest` with
115
115
  `--from-xlsx ./pricing.xlsx`, `tools/list` also includes
116
116
  `analyze_workbook_risk`. That tool is fixed to the source XLSX passed at
117
- startup and reports workbook risk indicators before an agent trusts the imported
117
+ startup and reports workbook risk indicators before a workflow trusts the imported
118
118
  WorkPaper. Without `--workpaper --writable`, edits stay in memory; add a
119
119
  WorkPaper JSON path only when the task needs persisted file state. It does not
120
120
  certify Excel compatibility.
@@ -177,9 +177,9 @@ console.log({
177
177
  book.dispose()
178
178
  ```
179
179
 
180
- ## XLSX Formula Clinic
180
+ ## Formula Clinic
181
181
 
182
- When the user has a reduced XLSX formula/import bug, generate a local report through an argument array:
182
+ When the user has a reduced workbook formula/import bug, generate a local report through an argument array:
183
183
 
184
184
  ```json
185
185
  {
@@ -201,7 +201,7 @@ The report is local. It does not upload workbook contents. Ask for a reduced pub
201
201
 
202
202
  ## Required Verification
203
203
 
204
- Return readback, not vibes. A successful agent response should include:
204
+ Return readback, not a write-only claim. A successful agent response should include:
205
205
 
206
206
  - the exact edited sheet and A1 cell;
207
207
  - before values for relevant inputs and dependent outputs;
@@ -215,8 +215,8 @@ If any readback step fails, report the blocker instead of claiming the workbook
215
215
  ## Reference URLs
216
216
 
217
217
  - Compact docs map: https://proompteng.github.io/bilig/llms.txt
218
- - Full agent context: https://proompteng.github.io/bilig/llms-full.txt
219
- - Agent handbook: https://proompteng.github.io/bilig/headless-workpaper-agent-handbook.html
218
+ - Full host context: https://proompteng.github.io/bilig/llms-full.txt
219
+ - Host handbook: https://proompteng.github.io/bilig/headless-workpaper-agent-handbook.html
220
220
  - Agent workbook challenge: https://proompteng.github.io/bilig/agent-workbook-challenge.html
221
221
  - MCP server guide: https://proompteng.github.io/bilig/mcp-workpaper-tool-server.html
222
222
  - OpenHands MCP setup: https://proompteng.github.io/bilig/openhands-workpaper-mcp.html
@@ -241,7 +241,6 @@ If any readback step fails, report the blocker instead of claiming the workbook
241
241
  - Dagster asset: https://proompteng.github.io/bilig/dagster-workpaper-asset.html
242
242
  - Kestra Node flow: https://proompteng.github.io/bilig/kestra-workpaper-flow.html
243
243
  - Prefect flow: https://proompteng.github.io/bilig/prefect-workpaper-flow.html
244
- - XLSX formula clinic: https://proompteng.github.io/bilig/formula-bug-clinic.html
245
- - Stale XLSX fixture command: npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor ./reduced.xlsx --json
244
+ - Formula clinic: https://proompteng.github.io/bilig/formula-bug-clinic.html
246
245
  - Compatibility limits: https://proompteng.github.io/bilig/where-bilig-is-not-excel-compatible-yet.html
247
246
  - Repository: https://github.com/proompteng/bilig
package/package.json CHANGED
@@ -1,10 +1,8 @@
1
1
  {
2
2
  "name": "@bilig/workpaper",
3
- "version": "0.164.1",
4
- "description": "Bilig WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.",
3
+ "version": "0.164.2",
4
+ "description": "Run workbook-shaped business rules in Node services: edit inputs, recalculate formulas, read outputs, and save WorkPaper JSON.",
5
5
  "keywords": [
6
- "agent-tools",
7
- "ai-agents",
8
6
  "bilig",
9
7
  "bilig-workpaper",
10
8
  "excel-formulas",
@@ -19,18 +17,16 @@
19
17
  "server-side-formula-engine",
20
18
  "server-side-spreadsheet",
21
19
  "spreadsheet",
22
- "spreadsheet-agent",
23
20
  "spreadsheet-automation",
24
21
  "spreadsheet-engine",
25
22
  "spreadsheet-formula-engine",
26
23
  "spreadsheet-formulas",
27
24
  "workbook",
28
- "workbook-agent",
29
25
  "workbook-api",
30
26
  "workpaper",
31
27
  "xlsx"
32
28
  ],
33
- "homepage": "https://proompteng.github.io/bilig/agent-framework-workbook-tools.html",
29
+ "homepage": "https://proompteng.github.io/bilig/",
34
30
  "bugs": {
35
31
  "url": "https://github.com/proompteng/bilig/issues"
36
32
  },
@@ -96,9 +92,9 @@
96
92
  "build": "pnpm --dir ../.. --filter bilig-workpaper build && rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
97
93
  },
98
94
  "dependencies": {
99
- "@bilig/headless": "0.164.1",
100
- "@bilig/xlsx-formula-recalc": "0.164.1",
101
- "bilig-workpaper": "0.164.1"
95
+ "@bilig/headless": "0.164.2",
96
+ "@bilig/xlsx-formula-recalc": "0.164.2",
97
+ "bilig-workpaper": "0.164.2"
102
98
  },
103
99
  "devDependencies": {
104
100
  "ai": "6.0.195",
package/server.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "name": "io.github.proompteng/bilig-workpaper",
4
4
  "title": "Bilig WorkPaper",
5
5
  "description": "Formula readback, input edits, JSON persistence, and workbook risk preflight for agents.",
6
- "version": "0.164.1",
6
+ "version": "0.164.2",
7
7
  "repository": {
8
8
  "url": "https://github.com/proompteng/bilig",
9
9
  "source": "github"
@@ -18,7 +18,7 @@
18
18
  {
19
19
  "registryType": "npm",
20
20
  "identifier": "@bilig/workpaper",
21
- "version": "0.164.1",
21
+ "version": "0.164.2",
22
22
  "transport": {
23
23
  "type": "stdio"
24
24
  }