===============
LIBRARY RULES
===============
From library maintainers:
- Use @bilig/headless WorkPaper for service-side formula workflows that need explicit cell edits, recalculation, readback, and JSON persistence.
- Prefer the file-backed bilig-workpaper-mcp server when an agent needs deterministic workbook operations through MCP tools.
- Use https://bilig.proompteng.ai/mcp for stateless Streamable HTTP MCP discovery or connector smoke tests; use file-backed stdio when edits must persist to a project WorkPaper JSON file.
- Verify WorkPaper edits with read-before-write, set_cell_contents, calculated readback, and export_workpaper_document before claiming success.
- Do not use Bilig as a replacement for native Excel macros, desktop Office automation, or rich spreadsheet UI formatting.

### Install and Run Quickstart Example

Source: https://github.com/proompteng/bilig/blob/main/docs/production-adoption-checklist-headless-workpaper.md

Installs the @bilig/headless package and runs a quickstart TypeScript example. Ensure the package version is pinned and verify the output signals.

```sh
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quickstart.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx quickstart.ts
```

--------------------------------

### Setup and Run XLSX Recalculation Example

Source: https://github.com/proompteng/bilig/blob/main/docs/excel-file-calculation-engine-node.md

Clone the repository, navigate to the example directory, install dependencies, and run the script to execute the XLSX recalculation proof.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig/examples/xlsx-recalculation-node
npm install
npm start
```

--------------------------------

### Clone and Install Bilig Example

Source: https://github.com/proompteng/bilig/blob/main/docs/openai-responses-workpaper-tool-call.md

Clone the bilig repository and install dependencies for the headless-workpaper example. This setup is required to run the provided agent script.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:openai-responses
```

--------------------------------

### Install and Run Examples

Source: https://github.com/proompteng/bilig/blob/main/examples/serverless-workpaper-api/README.md

Commands to install dependencies and run various example scripts for the serverless workpaper API.

```sh
npm install
npm run test
npm run quote-approval-api
npm run next-route-handler
npm run next-server-action
npm run next-server-action-formdata
npm run next-server-action-validation
npm run framework-adapters
npm run persistence-adapters
```

--------------------------------

### Install and Run XLSX Recalculation Example

Source: https://github.com/proompteng/bilig/blob/main/examples/xlsx-recalculation-node/README.md

Instructions to set up and execute the XLSX recalculation example. Navigate to the example directory, install dependencies, and run the script.

```sh
cd examples/xlsx-recalculation-node
npm install
npm start
```

--------------------------------

### Install Dependencies and Fetch Example

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

This command sequence sets up a new Node.js project, installs necessary dependencies including @bilig/headless, and downloads the example TypeScript file.

```sh
mkdir bilig-quote-approval
cd bilig-quote-approval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quote-approval-api.ts \
  https://raw.githubusercontent.com/proompteng/bilig/main/examples/serverless-workpaper-api/quote-approval-api.ts
```

--------------------------------

### Install and Snapshot Diff for Headless Example

Source: https://github.com/proompteng/bilig/blob/main/docs/new-contributor-guide.md

Install dependencies for the headless example and run a snapshot diff. Use this for docs-only or example-only starter issues.

```bash
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run snapshot-diff
```

--------------------------------

### Project Setup with npm

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Initializes a new Node.js project, configures it for ES Modules, sets a start script for TSX, and installs necessary dependencies including @bilig/headless, tsx, typescript, and @types/node.

```sh
mkdir bilig-serverless-workpaper
cd bilig-serverless-workpaper
npm init -y
npm pkg set type=module
npm pkg set scripts.start="tsx route.ts"
npm install @bilig/headless
npm install --save-dev tsx typescript @types/node
```

--------------------------------

### Install and Run Headless Workpaper Example

Source: https://github.com/proompteng/bilig/blob/main/docs/agent-spreadsheet-tool-call-loop.md

Installs dependencies and runs the headless workpaper agent tool call loop example.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:tool-call
```

--------------------------------

### Set up Node.js project for quote approval

Source: https://github.com/proompteng/bilig/blob/main/docs/formula-workbooks-node-services-agent-tools.md

Initialize a Node.js project, install dependencies, and download an example API script. This setup is for running a quote approval proof-of-concept.

```sh
mkdir bilig-quote-approval
cd bilig-quote-approval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quote-approval-api.ts \
  https://raw.githubusercontent.com/proompteng/bilig/main/examples/serverless-workpaper-api/quote-approval-api.ts
npx tsx quote-approval-api.ts
```

--------------------------------

### Install and run @bilig/headless quickstart

Source: https://github.com/proompteng/bilig/blob/main/docs/headless-spreadsheet-engine-node-services-agents.md

Installs the @bilig/headless package and runs a quickstart script to verify its functionality. This is the shortest package sanity check for Node.js environments.

```sh
mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quickstart.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx quickstart.ts
```

--------------------------------

### Install and Run File Transcript Example

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-workpaper-tool-server.md

Install dependencies for the headless-workpaper example and run the agent:mcp-file-transcript script to demonstrate file-backed MCP operations and transcript logging.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
```

```sh
pnpm --dir examples/headless-workpaper run agent:mcp-file-transcript
```

--------------------------------

### End-to-End Proof with Maintained Example

Source: https://github.com/proompteng/bilig/blob/main/docs/hyperformula-alternative-headless-workpaper.md

Use this snippet for an end-to-end proof of concept. It clones the bilig repository and runs the headless workpaper example, including installation, starting the example, and verifying the agent.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run start
pnpm --dir examples/headless-workpaper run agent:verify
```

--------------------------------

### Run Headless WorkPaper Example

Source: https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md

Install dependencies and run the headless WorkPaper example.

```bash
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run start
```

--------------------------------

### Install and Run Server Action FormData Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Installs dependencies and runs the Next.js server action example that handles form data for the WorkPaper API.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-server-action-formdata
```

--------------------------------

### Install and Run Serverless Workpaper API Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Installs dependencies and runs various commands for the serverless workpaper API example. Use 'quote-approval-api' for production-shaped proof.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
```

```sh
pnpm --dir examples/serverless-workpaper-api run quote-approval-api
```

```sh
pnpm --dir examples/serverless-workpaper-api run next-route-handler
```

```sh
pnpm --dir examples/serverless-workpaper-api run next-server-action
```

```sh
pnpm --dir examples/serverless-workpaper-api run next-server-action-formdata
```

```sh
pnpm --dir examples/serverless-workpaper-api run framework-adapters
```

```sh
pnpm --dir examples/serverless-workpaper-api run persistence-adapters
```

--------------------------------

### Install Hosted Demo with Smithery

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Use this command to install the hosted demo of Bilig WorkPaper using the Smithery tool. This is a convenient way for Smithery users to get started.

```bash
npx -y smithery mcp add gkonushev/bilig-workpaper
```

--------------------------------

### Install and Run Next.js Route Handler Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Commands to install dependencies and run the Next.js route handler example or its focused test.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-route-handler
# or the focused example test
pnpm --dir examples/serverless-workpaper-api run test
```

--------------------------------

### Local Development Setup Commands

Source: https://github.com/proompteng/bilig/blob/main/README.md

Commands to install dependencies and start local development servers for the Bilig project. Ensure Node.js version 24+ and pnpm@10.32.1 are installed.

```shell
pnpm install
pnpm dev:web
pnpm dev:web-local
pnpm dev:sync
```

--------------------------------

### Install and Run Server Action Validation Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Installs dependencies and runs the Next.js server action validation example for the WorkPaper API.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-server-action-validation
```

--------------------------------

### Install and Run Serverless Workpaper API Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Installs dependencies and runs the Next.js server action example for the WorkPaper API.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-server-action
```

--------------------------------

### Run Persistence Roundtrip Example

Source: https://github.com/proompteng/bilig/blob/main/docs/persisting-formula-backed-workpaper-documents-in-node.md

Instructions to install dependencies and run the persistence roundtrip example from the examples directory. This verifies formula preservation and recalculation after a save/restore cycle.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run persistence
```

--------------------------------

### Install and Run Headless Example with npm

Source: https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/README.md

Installs dependencies and runs the headless workpaper example when the folder is outside the monorepo using npm.

```sh
npm install
```

```sh
npm start
```

--------------------------------

### Clone and Run MCP Example

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-workpaper-tool-server.md

Clone the repository, install dependencies, and run the MCP tools agent example. This is a dependency-free way to test the server.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:mcp-tools
```

--------------------------------

### Reproduce Stack Overflow Example

Source: https://github.com/proompteng/bilig/blob/main/docs/exceljs-formula-recalculation-node.md

Clone the repository, install dependencies for a specific example, and run a script to reproduce a scenario demonstrating ExcelJS formula recalculation for a Stack Overflow question.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
npm --prefix examples/recalc-bridge-workflows install
npm --prefix examples/recalc-bridge-workflows run so:exceljs-44199441
```

--------------------------------

### Install and Run Headless Workpaper Agent

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-spreadsheet-server-directory.md

Install dependencies for the headless workpaper example and then run the agent. This is useful for local development and testing.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:mcp-tools
```

--------------------------------

### Run XLSX Proof Example

Source: https://github.com/proompteng/bilig/blob/main/docs/exceljs-shared-formula-recalculation-node.md

Clone the Bilig repository, navigate to the xlsx-recalculation-node example, install dependencies, and run the smoke test to verify the full recalculation loop.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig/examples/xlsx-recalculation-node
pnpm install
pnpm run smoke
```

--------------------------------

### Run Headless WorkPaper Agent Handbook Example

Source: https://github.com/proompteng/bilig/blob/main/README.md

Initiate the headless WorkPaper agent handbook example. This is a starting point if an agent requires workbook tools.

```bash
npm run agent:openai-agents-sdk
```

```bash
npm run agent:framework-adapters
```

```bash
npm run agent:mcp-tools
```

```bash
npm run agent:mcp-transcript
```

```bash
npm run agent:mcp-file-transcript
```

```bash
npm run agent:mcp-stdio
```

```bash
npm exec --package @bilig/headless@0.39.0 -- bilig-workpaper-mcp
```

--------------------------------

### Run Agent Examples

Source: https://github.com/proompteng/bilig/blob/main/README.md

Installs dependencies and runs agent-related examples using pnpm. These examples focus on agent verification, tool calls, and interactions with AI SDKs.

```sh
pnpm --dir examples/headless-workpaper run agent:verify
pnpm --dir examples/headless-workpaper run agent:tool-call
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk
pnpm --dir examples/headless-workpaper run agent:openai-responses
pnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-text
pnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-text
pnpm --dir examples/headless-workpaper run agent:framework-adapters
pnpm --dir examples/headless-workpaper run agent:mcp-tools
pnpm --dir examples/headless-workpaper run agent:mcp-file-transcript
pnpm --dir examples/headless-workpaper run agent:mcp-stdio
```

--------------------------------

### Clone and Run Bilig Repository Examples

Source: https://github.com/proompteng/bilig/blob/main/docs/llms.txt

Commands to clone the Bilig repository, install dependencies for the headless workpaper example, and run various agent-related scripts.

```sh
git clone https://github.com/proompteng/bilig.git
pnpm --dir bilig/examples/headless-workpaper install --ignore-workspace
pnpm --dir bilig/examples/headless-workpaper run start
pnpm --dir bilig/examples/headless-workpaper run agent:tool-call
pnpm --dir bilig/examples/headless-workpaper run agent:openai-agents-sdk
pnpm --dir bilig/examples/headless-workpaper run agent:openai-responses
pnpm --dir bilig/examples/headless-workpaper run agent:ai-sdk-generate-text
pnpm --dir bilig/examples/headless-workpaper run agent:ai-sdk-stream-text
pnpm --dir bilig/examples/headless-workpaper run agent:framework-adapters
pnpm --dir bilig/examples/headless-workpaper run agent:verify
```

--------------------------------

### Clone and Install Project Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/crewai-workpaper-spreadsheet-tool.md

Clone the bilig repository and install dependencies for the headless-workpaper example. This is a prerequisite for running the agent framework adapters.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
```

--------------------------------

### Run Quote Approval API Example

Source: https://github.com/proompteng/bilig/blob/main/docs/submit-workbook-fixture.md

Installs dependencies and runs the quote approval API example for service workflows. This serves as a starting point for testing service-related fixtures.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run quote-approval-api
```

--------------------------------

### Setup Project and Install Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/csv-shaped-workpaper-input-recipe.md

Initializes a new Node.js project, sets it to use ES modules, and installs the necessary Bilig Headless library along with TypeScript development tools.

```sh
mkdir bilig-csv-shaped-input
cd bilig-csv-shaped-input
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install --save-dev tsx typescript
```

--------------------------------

### Clone and Install Dependencies for WorkPaper Agent

Source: https://github.com/proompteng/bilig/blob/main/docs/cloudflare-agents-workpaper-spreadsheet-tool.md

Clone the bilig repository and install necessary dependencies for the headless workpaper example. This setup is required before running the agent framework adapters.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:framework-adapters
```

--------------------------------

### Local API Server and cURL Examples

Source: https://github.com/proompteng/bilig/blob/main/docs/create-bilig-workpaper.md

Start the local development server and use cURL to interact with the quote approval API. This includes testing the GET endpoint and making a POST request with sample data.

```bash
npm run dev
curl http://localhost:8788/api/quote/approval
curl -X POST http://localhost:8788/api/quote/approval \
  -H 'content-type: application/json' \
  -d '{"units":40,"listPrice":1200,"discount":0.05,"unitCost":760,"minimumMargin":0.3}'
```

--------------------------------

### Clone and Run Full Repo Example

Source: https://github.com/proompteng/bilig/blob/main/docs/create-bilig-workpaper.md

Clone the Bilig repository and run the serverless-workpaper-api example. This demonstrates a more comprehensive use case.

```bash
git clone --depth 1 https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke
```

--------------------------------

### Runnable Service Storage Adapters Example

Source: https://github.com/proompteng/bilig/blob/main/docs/persisting-formula-backed-workpaper-documents-in-node.md

Instructions to install dependencies and run the persistence adapters example, which tests WorkPaper persistence with various Node.js storage solutions like Postgres, SQLite, Redis, and object storage.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run persistence-adapters
```

--------------------------------

### Setup @bilig/headless for Evaluation

Source: https://github.com/proompteng/bilig/blob/main/docs/why-agents-need-workbook-apis.md

Follow these steps to set up a Node.js project, install the necessary packages, download an evaluation script, and run it to test the @bilig/headless package.

```sh
mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo eval.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx eval.ts
```

--------------------------------

### Run Framework Adapter Smoke Test

Source: https://github.com/proompteng/bilig/blob/main/docs/node-framework-workpaper-adapters.md

Clone the repository, navigate to the example directory, install dependencies, and run the framework adapters test to verify integration.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run framework-adapters
```

--------------------------------

### Install and Run Bilig Proof Script

Source: https://github.com/proompteng/bilig/blob/main/docs/dev-to-workbook-apis-post.md

Steps to set up a Node.js project, install the @bilig/headless package, and run a TypeScript evaluation script.

```sh
mkdir bilig-workpaper-eval
cd bilig-workpaper-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo eval.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx eval.ts
```

--------------------------------

### Install Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/building-a-revenue-model-with-headless-workpaper.md

Installs project dependencies for the headless-workpaper example using pnpm, ignoring workspace configurations.

```bash
pnpm --dir examples/headless-workpaper install --ignore-workspace
```

--------------------------------

### Run Wider Proof from Repo Checkout

Source: https://github.com/proompteng/bilig/blob/main/docs/quote-approval-workpaper-api.md

Commands to install dependencies and run tests for framework and persistence adapters from the serverless-workpaper-api example directory.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run test
pnpm --dir examples/serverless-workpaper-api run framework-adapters
pnpm --dir examples/serverless-workpaper-api run persistence-adapters
```

--------------------------------

### Install and Test Serverless Workpaper API

Source: https://github.com/proompteng/bilig/blob/main/docs/node-framework-workpaper-adapters.md

Installs dependencies and runs tests for the serverless Workpaper API example.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run test
```