@bilig/workpaper 0.153.0 → 0.155.0

package/AGENTS.md

@@ -22,10 +22,10 @@ Use this file when an AI coding agent, MCP client, or tool host needs workbook f
    explicit formula-proof command from
    `.claude/commands/bilig-workpaper-proof.md`.
 10. If you are using Cursor, Windsurf/Cascade, Cline, or Continue, use
-   `.cursor/rules/bilig-workpaper.mdc` or
-   `.windsurf/rules/bilig-workpaper.md`,
-   `.clinerules/bilig-workpaper.md`, or
-   `.continue/rules/bilig-workpaper.md`.
+    `.cursor/rules/bilig-workpaper.mdc` or
+    `.windsurf/rules/bilig-workpaper.md`,
+    `.clinerules/bilig-workpaper.md`, or
+    `.continue/rules/bilig-workpaper.md`.
 11. Start the MCP server or import `@bilig/workpaper` directly.
 
 Remote MCP clients that support Streamable HTTP can smoke-test the stateless
@@ -57,6 +57,7 @@ Do not claim success from a write call alone. The proof is computed readback plu
 ## Fast Commands
 
 ```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

package/README.md

@@ -22,10 +22,58 @@ Pick the door that matches the state you own:
 
 | Door                       | Run first                                                                                            | What it proves                                                                                     |
 | -------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| 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.                     |
 | 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`.                |
 | 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`. |
 | 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.   |
 
+`bilig-agent-start --json` is intentionally small. It gives an agent the
+workbook-vs-XLSX decision card, first proof commands, required evidence fields,
+expected MCP tools, and public discovery links without asking it to read the
+whole site.
+
+## What Success Looks Like
+
+Run the agent proof without cloning the repo:
+
+```sh
+npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario revenue-plan --json
+```
+
+The useful output is not a write-call status. It is readback proof:
+
+```json
+{
+  "schemaVersion": "bilig-evaluator.v1",
+  "door": "agent-mcp",
+  "verified": true,
+  "packageVersions": {
+    "@bilig/workpaper": "0.153.0"
+  },
+  "evidence": {
+    "scenario": "revenue-plan",
+    "editedCell": "Deals!C2",
+    "readbackRange": "Summary!B2:B8",
+    "after": {
+      "totalRevenue": 36900,
+      "westCustomers": 38
+    },
+    "checks": {
+      "totalRevenueRecalculated": true,
+      "sumifReadbackChanged": true,
+      "xlookupReadbackStable": true,
+      "filterSpillUpdated": true,
+      "persistedToDisk": true,
+      "restartReadbackMatchesAfter": true
+    }
+  }
+}
+```
+
+If that is the contract your service or agent needed, star the repo so you can
+find it again: <https://github.com/proompteng/bilig/stargazers>. Watch releases
+if this is close to production: <https://github.com/proompteng/bilig/subscription>.
+
 For a richer agent check, add `--scenario revenue-plan` to the `agent-mcp`
 evaluator. It proves `SUM`, `SUMIF`, `XLOOKUP`, `FILTER`, a named expression,
 JSON persistence, and restart readback.
@@ -36,14 +84,13 @@ That proves the formula fails closed with an adapter diagnostic, then verifies a
 local synthetic adapter readback. It does not call Google Sheets.
 
 If one of those matches your workflow, keep Bilig nearby:
-<https://github.com/proompteng/bilig>. Watch releases if this is close to a
-production dependency: <https://github.com/proompteng/bilig/subscription>.
+<https://github.com/proompteng/bilig>.
 
 Framework examples live in the repo instead of this first screen. Start with
 the closest runtime:
 
 - Agent tools: Vercel AI SDK, LangGraph, LangChain MCP adapters, Open WebUI,
-  FastMCP, smolagents.
+  FastMCP, Agno, Pydantic AI, smolagents.
 - Workflow engines: Trigger.dev, Inngest, Temporal, Airflow, Dagster, Kestra,
   Prefect, Windmill.
 - Low-code and data tools: n8n, Pipedream, Directus, Airbyte, Meltano.
@@ -71,6 +118,8 @@ not the first-run path:
 | Flowise formula readback                                | <https://proompteng.github.io/bilig/flowise-workpaper-formula-readback.html>   |
 | Pipedream formula readback                              | <https://proompteng.github.io/bilig/pipedream-workpaper-formula-readback.html> |
 | FastMCP Python client for hosted and local stdio checks | <https://proompteng.github.io/bilig/fastmcp-workpaper-client.html>             |
+| Agno MCPTools workbook readback                         | <https://proompteng.github.io/bilig/agno-workpaper-mcp.html>                   |
+| Pydantic AI MCPToolset typed readback                   | <https://proompteng.github.io/bilig/pydantic-ai-workpaper-mcp.html>            |
 | Hugging Face smolagents tool                            | <https://proompteng.github.io/bilig/smolagents-workpaper-tool.html>            |
 | Hugging Face Gradio MCP Space                           | <https://proompteng.github.io/bilig/huggingface-workpaper-space.html>          |
 

package/SKILL.md

@@ -32,6 +32,18 @@ Do not trigger it for manual spreadsheet editing, Office macros, VBA, pivots, ch
 
 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 Check: Agent Triage
+
+Before wiring a client or opening a spreadsheet UI, print the compact decision
+card:
+
+```json
+{
+  "command": "npm",
+  "args": ["exec", "--yes", "--package", "@bilig/workpaper@latest", "--", "bilig-agent-start", "--json"]
+}
+```
+
 ## First Check: Agent Evaluator
 
 Before wiring a client, prove the published agent door with the package-owned evaluator.
@@ -196,6 +208,8 @@ If any readback step fails, report the blocker instead of claiming the workbook
 - AnythingLLM MCP setup: https://proompteng.github.io/bilig/anythingllm-workpaper-mcp.html
 - Sim MCP setup: https://proompteng.github.io/bilig/sim-workpaper-mcp.html
 - FastMCP Python client: https://proompteng.github.io/bilig/fastmcp-workpaper-client.html
+- Agno WorkPaper MCP tools: https://proompteng.github.io/bilig/agno-workpaper-mcp.html
+- Pydantic AI WorkPaper MCP tools: https://proompteng.github.io/bilig/pydantic-ai-workpaper-mcp.html
 - smolagents WorkPaper tool: https://proompteng.github.io/bilig/smolagents-workpaper-tool.html
 - Hugging Face WorkPaper Space template: https://proompteng.github.io/bilig/huggingface-workpaper-space.html
 - Windmill TypeScript script: https://proompteng.github.io/bilig/windmill-workpaper-script.html

package/bin/bilig-agent-start.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+await import('../dist/agent-start-bin.js')

package/dist/agent-start-bin.d.ts

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

package/dist/agent-start-bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runAgentStartCli } from '@bilig/headless/cli';
+process.exitCode = runAgentStartCli({
+    argv: process.argv.slice(2),
+});
+//# sourceMappingURL=agent-start-bin.js.map

package/dist/agent-start-bin.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/workpaper",
-  "version": "0.153.0",
+  "version": "0.155.0",
   "description": "WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.",
   "keywords": [
     "agent-tools",
@@ -40,6 +40,7 @@
   },
   "bin": {
     "bilig-agent-challenge": "./bin/bilig-agent-challenge.js",
+    "bilig-agent-start": "./bin/bilig-agent-start.js",
     "bilig-evaluate": "./bin/bilig-evaluate.js",
     "bilig-formula-clinic": "./bin/bilig-formula-clinic.js",
     "bilig-mcp-challenge": "./bin/bilig-mcp-challenge.js",
@@ -88,9 +89,9 @@
     "build": "pnpm --dir ../.. --filter bilig-workpaper build && rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@bilig/headless": "0.153.0",
-    "@bilig/xlsx-formula-recalc": "0.153.0",
-    "bilig-workpaper": "0.153.0"
+    "@bilig/headless": "0.155.0",
+    "@bilig/xlsx-formula-recalc": "0.155.0",
+    "bilig-workpaper": "0.155.0"
   },
   "devDependencies": {
     "ai": "6.0.182",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.proompteng/bilig-workpaper",
   "title": "Bilig WorkPaper",
   "description": "WorkPaper MCP tools, resources, and prompts for readback, edits, and JSON persistence.",
-  "version": "0.153.0",
+  "version": "0.155.0",
   "repository": {
     "url": "https://github.com/proompteng/bilig",
     "source": "github"
@@ -18,7 +18,7 @@
     {
       "registryType": "npm",
       "identifier": "@bilig/workpaper",
-      "version": "0.153.0",
+      "version": "0.155.0",
       "transport": {
         "type": "stdio"
       }