@bilig/workpaper 0.38.2 → 0.39.0

package/AGENTS.md

@@ -0,0 +1,58 @@
+# Bilig Agent Instructions
+
+Use this file when an AI coding agent, MCP client, or tool host needs workbook formulas without opening Excel, LibreOffice, Google Sheets, or a screenshot grid.
+
+## Discovery Order
+
+1. Read `https://proompteng.github.io/bilig/llms.txt` for the compact map.
+2. Read `https://proompteng.github.io/bilig/llms-full.txt` when you need enough context to implement a workflow without searching the whole site.
+3. Read `https://proompteng.github.io/bilig/skill.txt` when your agent supports skill manifests.
+4. 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
+hosted endpoint origin can read the same-origin server card at
+`https://bilig.proompteng.ai/.well-known/mcp/server-card.json`. Local agents that need writable project files should
+still prefer the file-backed stdio command below.
+
+## Default Decision
+
+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.
+
+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.
+
+## Required Proof
+
+Before reporting success, return a compact proof object with:
+
+- `editedCell`
+- `before`
+- `after`
+- `afterRestore`
+- `persistedDocumentBytes`
+- `verified`
+- `limitations`
+
+Do not claim success from a write call alone. The proof is computed readback plus persisted state.
+
+## Fast Commands
+
+```sh
+npm exec --package @bilig/workpaper@0.39.0 -- bilig-agent-challenge
+npm exec --package @bilig/workpaper@0.39.0 -- bilig-mcp-challenge
+npm exec --package @bilig/workpaper@0.39.0 -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable
+npm exec --package @bilig/workpaper@0.39.0 -- bilig-formula-clinic ./reduced.xlsx --cells "Summary!B7,Inputs!B2"
+```
+
+Claude Desktop users can install the released MCPB bundle from:
+
+- https://github.com/proompteng/bilig/releases/download/libraries-v0.39.0/bilig-workpaper.mcpb
+- https://github.com/proompteng/bilig/releases/download/libraries-v0.39.0/bilig-workpaper.mcpb.sha256
+
+## Direct TypeScript
+
+Use `WorkPaper.buildFromSheets()` for hand-authored models, `setCellContents()` for edits, `getCellDisplayValue()` for readback, and `exportWorkPaperDocument()` plus `serializeWorkPaperDocument()` for persistence proof.
+
+## Boundaries
+
+Keep Excel, LibreOffice, Microsoft Graph, or an oracle harness in the loop when the workbook depends on macros, pivots, charts, external links, unsupported functions, locale-specific Excel behavior, or exact desktop UI behavior.

package/README.md

@@ -2,16 +2,97 @@
 
 Scoped Bilig WorkPaper runtime for Node.js services, agent tools, and server-side spreadsheet formulas.
 
+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,
+serverless route, test, or coding-agent tool.
+
+`@bilig/workpaper` is the canonical scoped npm entrypoint. The unscoped
+`bilig-workpaper` package remains published as a compatibility and search alias.
+
+## Install
+
 ```sh
 npm install @bilig/workpaper
 ```
 
+## Use A WorkPaper In Node
+
+```ts
+import { WorkPaper } from '@bilig/workpaper'
+
+const workbook = WorkPaper.buildFromSheets({
+  Inputs: [
+    ['Metric', 'Value'],
+    ['Units', 40],
+    ['Price', 1200],
+  ],
+  Summary: [
+    ['Metric', 'Value'],
+    ['Revenue', '=Inputs!B2*Inputs!B3'],
+  ],
+})
+
+const inputs = workbook.getSheetId('Inputs')
+const summary = workbook.getSheetId('Summary')
+
+if (inputs === undefined || summary === undefined) {
+  throw new Error('Expected sheets to exist')
+}
+
+workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 48)
+workbook.setCellContents({ sheet: inputs, row: 2, col: 1 }, 1500)
+
+console.log(workbook.getCellValue({ sheet: summary, row: 1, col: 1 }))
+console.log(workbook.exportSnapshot())
+
+workbook.dispose()
+```
+
+## Prove The Agent Loop Without Cloning
+
+The package ships proof commands for coding agents and service evaluators:
+
+```sh
+npm exec --package @bilig/workpaper -- bilig-agent-challenge
+npm exec --package @bilig/workpaper -- bilig-mcp-challenge
+npm exec --package @bilig/workpaper -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable
+```
+
+The challenge commands edit one input, recalculate dependent formulas, export
+WorkPaper JSON, restore it, and print a `verified: true` proof object.
+
+## XLSX Import And Export
+
 ```ts
 import { WorkPaper } from '@bilig/workpaper'
 import { exportXlsx, importXlsx } from '@bilig/workpaper/xlsx'
 ```
 
-`@bilig/workpaper` is the canonical scoped package. The unscoped
-`bilig-workpaper` package remains published as a compatibility and search alias.
+Use `@bilig/xlsx-formula-recalc` when you only need to edit and recalculate
+XLSX files. Use `@bilig/exceljs-formula-recalc` when you already use ExcelJS
+and need recalculated formula results after changing inputs.
+
+## Agent Commands And Optional MCP
+
+The npm tarball exposes the same CLI entrypoints as `@bilig/headless`, so agents
+can install one focused package and still get the MCP stdio server:
+
+```ts
+import { createWorkPaperMcpServer } from '@bilig/workpaper/mcp'
+```
+
+For a runnable starter project with `AGENTS.md`, MCP client config, and an
+`agent:verify` script:
+
+```sh
+npm create @bilig/workpaper@latest pricing-agent -- --agent
+```
+
+## Scope
+
+Bilig is not a desktop Excel clone. It is a formula workbook runtime for
+service-owned calculations, JSON persistence, XLSX import/export, and
+agent-readable readback. Unsupported Excel functions, external workbook links,
+macros, and volatile functions may need review.
 
 Full docs: <https://proompteng.github.io/bilig/>

package/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: bilig-workpaper
+version: 0.1.0
+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.
+tags:
+  - ai-agents
+  - spreadsheet-automation
+  - formulas
+  - xlsx
+  - mcp
+  - typescript
+---
+
+# Bilig WorkPaper Agent Skill
+
+Use this skill when an agent needs spreadsheet-style formulas but the work should run through files, terminal commands, TypeScript, HTTP routes, or MCP tools instead of Excel UI automation.
+
+## When To Trigger
+
+Trigger this skill for tasks involving:
+
+- workbook-shaped business logic in Node.js services;
+- formula readback after writing cells;
+- quote, budget, payout, pricing, import-validation, or forecast models;
+- agent spreadsheet tools that need deterministic cell addresses;
+- MCP clients that can run a stdio server or call a Streamable HTTP endpoint;
+- reduced XLSX formula bugs that need a paste-ready report.
+
+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.
+
+## Command Safety
+
+Do not build shell commands by concatenating user text. Treat the commands below as literal templates, validate workbook paths before use, and reject values containing newlines, backticks, `$(`, `;`, `&`, `|`, `<`, or `>`. Prefer MCP client `command` plus `args` arrays or direct TypeScript calls when inserting user-provided paths or cell references.
+
+## First Choice: MCP
+
+Use MCP when the host can run a stdio server or call a Streamable HTTP server.
+Configure stdio as an argument array, not a shell-concatenated string:
+
+Before wiring a client, an agent can prove the direct WorkPaper loop with:
+
+```json
+{
+  "command": "npm",
+  "args": ["exec", "--package", "@bilig/workpaper@0.39.0", "--", "bilig-agent-challenge"]
+}
+```
+
+For the actual file-backed MCP path, run the package-owned challenge first:
+
+```json
+{
+  "command": "npm",
+  "args": ["exec", "--package", "@bilig/workpaper@0.39.0", "--", "bilig-mcp-challenge"]
+}
+```
+
+```json
+{
+  "command": "npm",
+  "args": [
+    "exec",
+    "--package",
+    "@bilig/workpaper@0.39.0",
+    "--",
+    "bilig-workpaper-mcp",
+    "--workpaper",
+    "./pricing.workpaper.json",
+    "--init-demo-workpaper",
+    "--writable"
+  ]
+}
+```
+
+The useful file-backed tools are:
+
+- `list_sheets`
+- `read_range`
+- `read_cell`
+- `set_cell_contents`
+- `get_cell_display_value`
+- `export_workpaper_document`
+- `validate_formula`
+
+After a write, always read the dependent output cell and export the WorkPaper document.
+
+For remote MCP clients, use the stateless demo endpoint when the client supports
+Streamable HTTP:
+
+```text
+https://bilig.proompteng.ai/mcp
+https://bilig.proompteng.ai/mcp/workpaper
+```
+
+The remote endpoint is request-local and does not write user files. Use it for
+connector smoke tests, tool discovery, and agent onboarding; use the file-backed
+stdio command when the workflow must persist a project WorkPaper JSON file.
+
+## Second Choice: Direct TypeScript
+
+Use `@bilig/workpaper` directly when workbook logic belongs in a service, queue worker, test, or route:
+
+```ts
+import { WorkPaper, exportWorkPaperDocument, serializeWorkPaperDocument } from '@bilig/workpaper'
+
+const workbook = WorkPaper.buildFromSheets({
+  Inputs: [
+    ['Metric', 'Value'],
+    ['Customers', 20],
+    ['Average revenue', 1200],
+  ],
+  Summary: [
+    ['Metric', 'Value'],
+    ['Revenue', '=Inputs!B2*Inputs!B3'],
+  ],
+})
+
+const inputs = workbook.getSheetId('Inputs')
+const summary = workbook.getSheetId('Summary')
+if (inputs === undefined || summary === undefined) {
+  throw new Error('Workbook is missing required sheets')
+}
+
+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({ revenue, savedBytes: saved.length })
+```
+
+## XLSX Formula Clinic
+
+When the user has a reduced XLSX formula/import bug, generate a local report through an argument array:
+
+```json
+{
+  "command": "npm",
+  "args": ["exec", "--package", "@bilig/workpaper@0.39.0", "--", "bilig-formula-clinic", "./reduced.xlsx", "--cells", "Summary!B7,Inputs!B2"]
+}
+```
+
+The report is local. It does not upload workbook contents. Ask for a reduced public fixture rather than private customer spreadsheets.
+
+## Required Verification
+
+Return proof, not vibes. A successful agent response should include:
+
+- the exact edited sheet and A1 cell;
+- before values for relevant inputs and dependent outputs;
+- after values read from the recalculated workbook;
+- persistence evidence from serialized or exported WorkPaper state;
+- restore or reimport proof when file boundaries matter;
+- limitations for unsupported formulas or Excel-only features.
+
+If any proof step fails, report the blocker instead of claiming the workbook was updated.
+
+## Reference URLs
+
+- Compact docs map: https://proompteng.github.io/bilig/llms.txt
+- Full agent context: https://proompteng.github.io/bilig/llms-full.txt
+- Agent handbook: https://proompteng.github.io/bilig/headless-workpaper-agent-handbook.html
+- Agent workbook challenge: https://proompteng.github.io/bilig/agent-workbook-challenge.html
+- MCP server guide: https://proompteng.github.io/bilig/mcp-workpaper-tool-server.html
+- XLSX formula clinic: https://proompteng.github.io/bilig/formula-bug-clinic.html
+- Compatibility limits: https://proompteng.github.io/bilig/where-bilig-is-not-excel-compatible-yet.html
+- Repository: https://github.com/proompteng/bilig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/workpaper",
-  "version": "0.38.2",
+  "version": "0.39.0",
   "description": "Scoped Bilig WorkPaper runtime for Node.js services, agent tools, and server-side spreadsheet formulas.",
   "keywords": [
     "agent-tools",
@@ -40,6 +40,8 @@
   },
   "files": [
     "dist",
+    "AGENTS.md",
+    "SKILL.md",
     "README.md",
     "LICENSE"
   ],
@@ -68,8 +70,8 @@
     "build": "pnpm --dir ../.. --filter bilig-workpaper build && rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@bilig/headless": "0.38.2",
-    "bilig-workpaper": "0.38.2"
+    "@bilig/headless": "0.39.0",
+    "bilig-workpaper": "0.39.0"
   },
   "engines": {
     "node": ">=22.0.0"