bkper 4.16.3 → 4.16.4

package/lib/agent/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAiGA,wBAAgB,yBAAyB,IAAI,MAAM,CAgDlD;AAED,eAAO,MAAM,yBAAyB,QAqBrC,CAAC"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAiGA,wBAAgB,yBAAyB,IAAI,MAAM,CAgDlD;AAED,eAAO,MAAM,yBAAyB,QAsBrC,CAAC"}

package/lib/agent/system-prompt.js

@@ -142,6 +142,7 @@ ${buildToolPromptSection()}
 - If a question can be answered by exploring the codebase, explore the codebase instead.
 - Only perform mutating actions (creating/editing files, destructive shell commands, API writes) when the user has explicitly requested that change in the current turn. When exploring, debugging, or unsure, propose the change and wait for confirmation instead of acting.
 - Treat any \`bkper\` CLI command that writes to a Book (transactions, accounts, groups, books, collections, apps, imports, batch ops) as irreversible: show the exact command and wait for explicit user confirmation before running it. Read-only commands (list, get, balances, search, export) need no confirmation.
+- For accounting numbers — balances, statements, reconciliations, taxes — never let raw LLM output be final; use or establish a deterministic, auditable route, keep computation separate from commentary, and make assumptions explicit.
 - Think in resources, movements, and balances — not debits and credits.
 - Extend meaning with properties before adding structural complexity.
 - Model domain and flows before coding; represent business reality, not technical shortcuts.

package/lib/agent/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"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"}

package/lib/docs/bkper-api-types.md

@@ -96,8 +96,8 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 - `logoUrl?`: `string` — The App logo url
 - `logoUrlDark?`: `string` — The App logo url in dark mode
 - `menuOpenMode?`: `"SIDEBAR" | "EXPANDED" | "NEW_TAB"` — How the app menu opens. Default to SIDEBAR
-- `menuPopupHeight?`: `string` — The menu popup window height
-- `menuPopupWidth?`: `string` — The menu popup window width
+- `menuPopupHeight?`: `string` — Deprecated
+- `menuPopupWidth?`: `string` — Deprecated
 - `menuText?`: `string` — The contex menu text - default to the App name
 - `menuUrl?`: `string` — The context menu url
 - `menuUrlDev?`: `string` — The context menu url in dev mode
@@ -360,6 +360,13 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 - `updatedAt?`: `string` — The last update timestamp, in milliseconds
 - `url?`: `string` — The file serving url
 
+### FileList
+
+**Properties:**
+
+- `cursor?`: `string` — The cursor, for pagination
+- `items?`: `bkper.File[]` — List items
+
 ### Group
 
 **Properties:**

package/lib/docs/bkper-js.md

@@ -631,9 +631,10 @@ It contains all `Accounts` where `Transactions` are recorded/posted;
 - `getTransaction(id: string)` → `Promise<Transaction | undefined>` — Retrieve a transaction by id.
 - `getVisibility()` / `setVisibility(visibility: Visibility)` → `Visibility` — Gets the visibility of the book.
 - `json()` → `bkper.Book` — Gets an immutable copy of the JSON payload for this resource.
-- `listEvents(afterDate: string | null, beforeDate: string | null, onError: boolean, resourceId: string | null, limit: number, cursor?: string)` → `Promise<EventList>` — Lists events in the Book based on the provided parameters.
+- `listEvents(afterDate: string | null, beforeDate: string | null, onError: boolean | null, resourceId: string | null, limit: number, cursor?: string)` → `Promise<EventList>` — Lists events in the Book based on the provided parameters.
+- `listFiles(limit?: number, cursor?: string)` → `Promise<FileList>` — Lists files in the Book, for pagination.
 - `listTransactions(query?: string, limit?: number, cursor?: string)` → `Promise<TransactionList>` — Lists transactions in the Book based on the provided query, limit, and cursor, for pagination.
-- `mergeTransactions(transaction1: Transaction, transaction2: Transaction)` → `Promise<Transaction>` — Merge two `Transactions` into a single new canonical transaction.
+- `mergeTransactions(transaction1: string | bkper.Transaction | Transaction, transaction2: string | bkper.Transaction | Transaction)` → `Promise<Transaction>` — Merge two `Transactions` into a single new canonical transaction.
 - `parseDate(date: string)` → `Date` — Parse a date string according to date pattern and timezone of the Book. Also parse ISO yyyy-mm-dd format.
 - `parseValue(value: string)` → `Amount | undefined` — Parse a value string according to `DecimalSeparator` and fraction digits of the Book.
 - `remove()` → `Promise<Book>` — Warning!
@@ -909,6 +910,19 @@ A File can be attached to a `Transaction` or used to import data.
 
 *Standard property methods (deleteProperty, getProperties, getProperty, getPropertyKeys, getVisibleProperties, setProperties, setProperty, setVisibleProperties, setVisibleProperty) — see Account.*
 
+### FileList
+
+A list associated with a file query.
+
+**Constructor:** `new FileList(book: Book, payload: bkper.FileList)`
+
+**Methods:**
+
+- `getCursor()` → `string | undefined` — Gets the cursor associated with the query for pagination.
+- `getFirst()` → `File | undefined` — Gets the first File in the list.
+- `getItems()` → `File[]` — Gets the files in the list.
+- `size()` → `number` — Gets the total number of files in the list.
+
 ### Group *(extends ResourceProperty<bkper.Group>)*
 
 This class defines a Group of `Accounts`.
@@ -1284,6 +1298,12 @@ Use your own API key for dedicated quota limits and project-level usage tracking
 API keys are for project identification only, not for authentication or agent attribution.
 Agent attribution is handled separately via the `agentIdProvider`.
 
+**oauthTokenProvider**
+
+If omitted or if it returns undefined, requests are sent without an Authorization header.
+This supports environments where authentication is injected outside bkper-js, such as
+Bkper Platform outbound for server-side app routes.
+
 **requestRetryHandler**
 
 This function is called when a request fails and needs to be retried.
@@ -1330,6 +1350,8 @@ Enum that represents event types.
 - `ACCOUNT_CREATED`
 - `ACCOUNT_DELETED`
 - `ACCOUNT_UPDATED`
+- `BOOK_AUDITED`
+- `BOOK_CREATED`
 - `BOOK_DELETED`
 - `BOOK_UPDATED`
 - `COLLABORATOR_ADDED`

package/lib/docs/financial-statements.md

@@ -1,225 +1,78 @@
-# Financial Statements — Deterministic Workflow
+# Financial Statements — Deterministic Reporting
 
-Use this guide when a user asks for a balance sheet, P&L, income statement, profit and loss, or any other ledger-derived financial report from a Bkper book.
+Use this guide when a user asks for a balance sheet, P&L, income statement, profit and loss, or another ledger-derived financial report from a Bkper Book.
 
-## Deterministic first
+## Principle
 
-Financial statements are **deterministic accounting tasks**.
+Financial statements are deterministic accounting work. For the same Book snapshot, statement type, period, and reporting assumptions, the same inputs must produce the same numbers.
 
-For the same book snapshot, statement type, period, and report settings, the agent should be able to run the same local code/config and obtain the same result every time. Use non-deterministic reasoning only for tasks whose nature is interpretive — such as suspicious transaction analysis, commentary, or general insights — not for deciding how the statement itself is computed.
+Do not make raw LLM reasoning the final source of statement values. Use or establish a deterministic, auditable reporting route, then keep optional AI commentary separate from the computed statement.
 
-Treat the reporting route as something that should be **persisted locally** and reused.
+Prefer existing trusted routes before creating new ones. A trusted route may be a script, CLI pipeline, platform app, bot, report config, template, or another project-standard artifact that the user already relies on.
 
----
+If none exists, recommend the smallest auditable route that fits the user's context.
 
-## Step 0 — Reuse an existing local statement runner
+## Bkper statement semantics
 
-Before running ad-hoc balance queries, inspect the local project for a canonical deterministic route for financial statements.
+Statements come from balances calculated from Transactions and organized by Groups.
 
-Look for artifacts such as:
+| Statement | Accounts | Time basis | Query pattern |
+| --- | --- | --- | --- |
+| Balance Sheet | Asset and/or Liability | Position at a point in time | `group:'<root>' before:<date>` |
+| P&L / Income Statement | Incoming and/or Outgoing | Activity during a period | `group:'<root>' after:<start> before:<end>` |
 
-- `reports/`
-- `scripts/`
-- `package.json` scripts
-- local config/spec files
-- `AGENTS.md`
-
-If a local statement runner already exists:
-
-- Use it as the default route
-- Pass explicit parameters for book, statement type, and dates/period
-- Return the result produced by that runner
-- Do **not** rediscover groups or rebuild fresh balance queries unless the user explicitly asks to update or rebuild the reporting logic
-
-Once a deterministic route exists, prefer it over live ad-hoc querying.
-
----
-
-## Step 1 — If none exists, bootstrap one
-
-If no deterministic runner exists yet, do **not** treat a live one-off balance query as the canonical solution.
-
-Instead:
-
-1. Explain briefly that financial statements should be generated by repeatable local code/config
-2. Offer to create that local statement runner for the project
-3. Ask approval before writing files
-4. Use live Bkper queries only as **bootstrap/discovery steps** to build the deterministic route correctly
-
-If the request is ambiguous (for example, “run a financial statement”), clarify whether the user wants:
-
-- Balance Sheet
-- Profit & Loss / Income Statement
-- Both
-
-During bootstrap, it is acceptable to create either:
-
-- a small shell script that runs fixed CLI queries and formats the output, or
-- a `bkper-js` script that resolves dates, loads groups, and renders the statement in a stable format
-
-Prefer the smallest boring solution that is easy to rerun and inspect.
-
----
-
-## Step 2 — Discover the correct root groups
-
-Use these commands during bootstrap to identify the correct statement roots.
-
-```bash
-bkper group list -b <bookId> --format csv
-```
-
-Inspect the output and identify **top-level groups** (no parent). Root group names vary by book — common examples: `Total Equity`, `Balance Sheet`, `Profit & Loss`, `Results`, `Net Worth`.
-
-Identify each root group by the account types it contains:
-
-| Root group contains                | Statement                    |
-| ---------------------------------- | ---------------------------- |
-| ASSET and/or LIABILITY accounts    | Balance Sheet                |
-| INCOMING and/or OUTGOING accounts  | Profit & Loss / Income Statement |
-
-When you discover the correct roots, persist them for future runs.
-
-Prefer storing the **group ID** in the local report config/script. If the execution route also needs the group name for a query string, persist the name as well.
-
-### If the book has no usable statement hierarchy
-
-If Step 2 does **not** reveal clear statement roots, treat that as a modeling gap, not as permission to improvise one silently.
-
-In that case:
+Rules:
 
-- explain that the book is **not yet statement-ready** for deterministic reporting
-- do **not** invent arbitrary roots from subgroup names or partial account matches
-- inspect the existing account names, language, and reporting style already present in the book
-- propose the **smallest** hierarchy that fits the user's actual use case and local standards
-- ask approval before creating groups, moving accounts, or persisting the proposed roots
-- once approved, validate the hierarchy with live balance queries and then persist it in the local runner/config
+- Use the relevant **root reporting group**. Do not silently substitute subgroups such as `Assets`, `Liabilities`, `Revenue`, or `Expenses` when the Book has a higher reporting root.
+- Balance Sheet uses `before:` because permanent Accounts accumulate continuously.
+- P&L uses `after:` + `before:` because non-permanent Accounts report activity within a period.
+- `after:` is inclusive and `before:` is exclusive.
+- Do not query the whole Book without a reporting group or account filter.
 
-When relevant, clarify whether the user wants:
+Date examples:
 
-- internal management reporting
-- local/statutory reporting
-- a simplified starter structure to evolve later
+| Request | Balance Sheet | P&L |
+| --- | --- | --- |
+| Current month | `before:$m` | `after:$m-1 before:$m` |
+| Current year | `before:$y` | `after:$y-1 before:$y` |
+| Full year 2024 | `before:2025-01-01` | `after:2024-01-01 before:2025-01-01` |
 
-If the user only wants a quick answer for now, you may still provide an **exploratory / provisional** result, but state clearly that the book still needs an approved reporting hierarchy for future deterministic statements.
+`$m` and `$y` are Bkper query date variables for current month-end and current year-end. In shell commands, wrap queries containing `$` variables in single quotes to prevent shell expansion.
 
----
+## Working route
 
-## Step 3 — Fetch balances to validate and implement the runner
+Before computing a statement, inspect local project context for an existing reporting route:
 
-Use these commands during bootstrap to validate the accounting logic and to implement the deterministic runner.
-
-**Balance Sheet** — permanent accounts, cumulative position at a point in time:
-
-```bash
-bkper balance list -b <bookId> \
-  -q "group:'<rootGroup>' before:<date>" \
-  --format csv --expanded 2
-```
-
-**Profit & Loss / Income Statement** — non-permanent accounts, activity within a period:
-
-```bash
-bkper balance list -b <bookId> \
-  -q "group:'<rootGroup>' after:<start> before:<end>" \
-  --format csv --expanded 2
-```
-
-Use the output to confirm the correct hierarchy, totals, and period semantics before persisting the script/spec.
-
----
-
-## Step 4 — Persist the deterministic route locally
-
-After discovery and validation, create or update local artifacts so future requests reuse the same route.
-
-Typical artifacts:
+- `AGENTS.md`
+- `reports/`
+- `scripts/`
+- package scripts
+- report config/spec files
+- platform app or bot code
 
-- `reports/balance-sheet.sh`
-- `reports/profit-and-loss.sh`
-- `scripts/financial-statements.ts`
-- `reports/financial-statements.json`
-- `package.json` scripts such as `report:balance-sheet` and `report:pl`
+If a route exists, use it and pass explicit Book, statement, and date parameters. Do not rediscover groups or rebuild the report unless the user asks to change the reporting logic.
 
-Persist the decisions that make the report repeatable:
+If no route exists, use read-only Bkper queries only for discovery and validation, then propose a repeatable route. Persist the decisions that make the report reproducible:
 
-- `bookId`
+- Book ID
 - statement type
-- root group ID
-- root group name if needed by the chosen execution path
-- timezone, if relevant to date boundaries
-- expanded depth / output detail level
-- exact date semantics for each statement type
+- root group IDs and names
+- date boundaries and timezone, when relevant
 - output format
+- detail/expansion level
+- any local reporting assumptions
 
-The canonical runner should produce a stable output shape, such as structured JSON, Markdown, or CSV with clear sections, totals, and period labels.
-
-If helpful, also create or update a local `AGENTS.md` note telling future agent sessions to use the canonical financial statement script. `AGENTS.md` is **optional persistence**, not a prerequisite for the first request.
-
----
-
-## Step 5 — Use the script for future requests
-
-Once the local statement runner exists:
-
-- Use it as the default route for balance sheet and P&L requests
-- Resolve relative periods like “last year” into explicit date boundaries in code/config
-- Keep deterministic statement generation separate from optional AI commentary
-- If the reporting logic must change, update the script/config instead of improvising a fresh one-off route
-
-Do not re-decide the accounting method on every request.
-
----
-
-## One-off exploratory fallback
-
-If the user explicitly does **not** want to create the script now and only wants a quick one-off answer, you may run live balance queries directly.
-
-In that case:
-
-- Clearly label the result as **exploratory / provisional**
-- State that it is **not yet** the canonical deterministic reporting route for the project
-- Recommend persisting a local script/config if the user wants repeatable accounting output in future requests
-
----
-
-## Date patterns
-
-Use these patterns when validating or implementing the deterministic runner.
-
-| Request        | Balance Sheet              | Profit & Loss                  |
-| -------------- | -------------------------- | ------------------------------ |
-| Current month  | `before:$m`                | `after:$m-1 before:$m`         |
-| Current year   | `before:$y`                | `after:$y-1 before:$y`         |
-| Full year 2024 | `before:2025-01-01`        | `after:2024-01-01 before:2025-01-01` |
-
-- `after:` is **inclusive**, `before:` is **exclusive**
-- `$d` = today, `$m` = current month-end, `$y` = current year-end
-- In shell, wrap queries containing `$` variables in **single quotes** to prevent shell expansion
+If the Book has no clear reporting hierarchy, treat that as a modeling gap. Do not invent a hierarchy silently. Inspect the Book's existing language and structure, propose the smallest hierarchy that fits the user's goal, and ask before changing Accounts or Groups.
 
----
+## Examples & Patterns
 
-## Key rules
+Use the implementation style that matches the user's context:
 
-- **Always use the ROOT group** — never subgroups like `Assets`, `Liabilities`, `Revenue`, `Expenses`
-- **Balance Sheet** uses `before:` only — permanent accounts accumulate continuously
-- **P&L** uses `after:` + `before:` — non-permanent accounts track period activity
-- **Use `--format csv`** for token efficiency when loading bootstrap results into an LLM context
-- **Use `--expanded 2`** to see meaningful sub-totals in the hierarchy
-- Once a canonical local report route exists, **reuse it instead of rediscovering the logic**
-- Prefer persisting reporting decisions in code/config rather than relying on session memory
+- **Scripts & CLI** — best for local, inspectable, repeatable reports and lightweight project workflows.
+- **Platform Apps / Bots** — best for shared, durable, event-driven, or operational reporting workflows.
 
----
+Existing trusted reports or templates may be reused when they are already the user's accepted reporting route, but they are not required by this guide.
 
-## Common mistakes
+## Provisional answers
 
-| Wrong | Right |
-| --- | --- |
-| Immediately running ad-hoc balance queries as the default response to a first statement request | First look for a local runner; if none exists, propose creating one and use queries only for bootstrap |
-| Assuming `AGENTS.md` must already exist | `AGENTS.md` can be created or updated during bootstrap to route future requests |
-| `group:'Assets' before:2025-01-01` | `group:'Total Equity' before:2025-01-01` — use root group, not subgroup |
-| Inventing a new statement hierarchy silently because no roots were found | Explain that the book is not yet statement-ready, propose a minimal hierarchy aligned with the user's language and local standards, and ask approval before changing structure |
-| `before:$m` for P&L | `after:$m-1 before:$m` — P&L needs a period, not just an end date |
-| `after:$y-1 before:$d` | `after:$y-1 before:$y` — use consistent date basis on both ends |
-| `-q 'before:2025-01-01'` without group filter | `-q "group:'<rootGroup>' before:2025-01-01"` — always filter by group |
-| Re-interpreting “last year” differently each time | Resolve relative periods into explicit dates inside the canonical script/config |
+If the user explicitly wants a quick answer and does not want to establish a route, live read-only balance queries are acceptable. Label the result as **exploratory / provisional** and recommend a deterministic route for future repeatability.

package/lib/docs/index.md

@@ -5,7 +5,7 @@ Reference docs for Bkper tasks. Load only the specific doc(s) relevant to the ta
 - **data-management.md** — CLI reference for managing financial data and files: books, accounts, groups, files, transactions, per-account balance queries, query operators (on:, after:, before:, account:, group:), output formats (table/json/csv), batch operations via stdin/piping, collections.
 - **app-management.md** — CLI reference for building and deploying Bkper apps: dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
 - **app-building.md** — Full app-building reference: single Worker app architecture (`client/` + `server/`), development loop, `/api/*` routes, `/events` handlers, deployment patterns, the Bkper Platform, and self-hosted alternatives. Includes authentication patterns for web clients (`@bkper/web-auth`), server API routes (`Authorization: Bearer` on `/api/*` with outbound auth injection), platform event handlers (`new Bkper()` with outbound auth injection), and local development.
-- **financial-statements.md** — Step-by-step workflow for aggregate financial reports (balance sheet, P&L): root group discovery, query patterns, date semantics (before: vs after:+before:), common mistakes to avoid.
-- **taxes.md** — Deterministic workflow for tax position and filing summaries: discovering tax-relevant groups, period-based balance queries, persisting a local tax runner. Jurisdiction-agnostic — outputs raw period balances, leaving rate/application to the user.
+- **financial-statements.md** — Deterministic reporting principles and Bkper query semantics for balance sheet and P&L: trusted routes, root reporting groups, permanent vs period date rules, and provisional query patterns.
+- **taxes.md** — Deterministic tax reporting principles: trusted routes, user-approved tax-relevant groups/accounts, period activity queries, explicit jurisdiction assumptions, and provisional query patterns.
 - **bkper-js.md** — bkper-js Node.js/browser SDK: Bkper, Book, Account, Transaction, Group, Balance classes, all methods, getBalancesReport, OAuth configuration, library setup.
 - **bkper-api-types.md** — Bkper REST API TypeScript interfaces: Book, Account, Transaction, Group, Balance, Collection, File — field names and types used by the API and bkper-js.

package/lib/docs/taxes.md

@@ -1,264 +1,80 @@
-# Taxes — Deterministic Workflow
+# Taxes — Deterministic Reporting
 
-Use this guide when a user asks to "do my taxes", compute a tax position, generate a tax filing summary, or derive any period-based tax report from a Bkper book.
+Use this guide when a user asks to do taxes, compute a tax position, prepare a filing summary, or reconcile tax-related balances from a Bkper Book.
 
-## Deterministic first
+## Principle
 
-Tax reporting is a **deterministic accounting task**.
+Tax reporting is deterministic accounting work, but tax law is jurisdiction-specific. Do not invent rates, deductions, filing rules, or tax categories from general knowledge.
 
-For the same book snapshot, tax period, and set of tax-relevant groups, the agent should be able to run the same local code/config and obtain the same tax position every time. Use non-deterministic reasoning only for interpretive tasks — such as flagging unusual transactions, commenting on trends, or explaining variances — not for deciding how the tax position itself is computed.
+Do not make raw LLM reasoning the final source of tax numbers. Use or establish a deterministic, auditable route, then keep optional AI commentary separate from computed values.
 
-Treat the tax route as something that should be **persisted locally** and reused.
+A tax route may compute tax owed only when the applicable rules, rates, and assumptions are supplied by the user or encoded in a reviewed deterministic artifact. Otherwise, produce raw period data or a filing worksheet for the user or their advisor to apply local rules.
 
-Jurisdiction-specific tax rules (rates, deductions, allowances, filing formats) vary widely and change over time. This workflow intentionally stays **agnostic about those rules**. It provides the deterministic scaffold: discovering tax-relevant account groupings, querying period data, producing a repeatable tax position through a local runner, and persisting that route. The user applies their local tax knowledge to interpret the output.
+Prefer existing trusted routes before creating new ones. If none exists, recommend the smallest auditable route that fits the user's context.
 
-The agent does **not** compute tax owed directly. It builds or reuses a **local tax generation engine** (a script, config, or small program) that queries the book deterministically and outputs raw period data. The engine is the canonical source of truth; the agent merely orchestrates, validates, and persists it.
+## Bkper tax semantics
 
----
+Tax reports usually combine period activity with tax-account positions or movements.
 
-## Step 0 — Reuse an existing local tax runner
+| Need | Time basis | Query pattern |
+| --- | --- | --- |
+| Revenue / income activity | Period activity | `group:'<revenueRoot>' after:<start> before:<end>` |
+| Deductible cost / expense activity | Period activity | `group:'<expenseRoot>' after:<start> before:<end>` |
+| Tax account movements | Period activity | `account:'<taxAccount>' after:<start> before:<end>` |
+| Tax liability / credit balance | Position at period end | `account:'<taxAccount>' before:<end>` |
 
-Before running ad-hoc queries, inspect the local project for a canonical deterministic tax runner.
+Rules:
 
-Look for artifacts such as:
+- Use user-approved tax-relevant Groups and Accounts. Do not assume standard names such as `Revenue`, `VAT`, `Taxes`, or `Deductible Expenses` are correct for the Book.
+- Period activity uses `after:` + `before:`.
+- Tax liability or credit Accounts may need either period movements or an end balance, depending on the question.
+- `after:` is inclusive and `before:` is exclusive.
+- Do not query the whole Book without a tax-relevant group or account filter.
 
-- `reports/`
-- `scripts/`
-- `package.json` scripts
-- local config/spec files
-- `AGENTS.md`
-
-If a local tax runner already exists:
-
-- Use it as the default route
-- Pass explicit parameters for book, period, and any tax-relevant overrides
-- Return the result produced by that runner
-- Do **not** rediscover groups or rebuild fresh queries unless the user explicitly asks to update or rebuild the tax logic
-
-Once a deterministic route exists, prefer it over live ad-hoc querying.
-
----
-
-## Step 1 — If none exists, bootstrap one
-
-If no deterministic runner exists yet, do **not** treat a live one-off query as the canonical solution.
-
-Instead:
-
-1. Explain briefly that tax positions should be generated by a repeatable local engine
-2. Offer to create that tax runner for the project
-3. Ask approval before writing files
-4. Use live Bkper queries only as **bootstrap/discovery steps** to build the deterministic route correctly
-
-If the request is ambiguous (for example, "do my taxes"), clarify what the user wants:
-
-- Tax position for a specific period (e.g., quarterly VAT, annual income tax)
-- Tax filing summary / worksheet for their jurisdiction
-- Reconciliation of tax-related balances
-
-During bootstrap, it is acceptable to create either:
-
-- a small shell script that runs fixed CLI queries and formats the output, or
-- a `bkper-js` script that resolves dates, loads groups, and renders the tax position in a stable format
-
-Prefer the smallest boring solution that is easy to rerun and inspect.
-
----
-
-## Step 2 — Discover the tax-relevant groups
-
-Tax positions are usually derived from **period activity** — revenue, deductible expenses, and tax liability accounts. The specific groups that matter depend on the user's jurisdiction and how they have structured their book.
-
-The deterministic engine can work from **aggregated balances** or from **individual transactions**, depending on what the user needs:
-
-- **Balance-level** — faster, gives period totals per group/account. Good for computing a tax position or filing summary.
-- **Transaction-level** — slower, gives itemized detail. Good for audit trails, per-transaction deductions, or reconciling tax-account movements.
-
-During bootstrap, ask the user which level they need, or default to balance-level and note that transaction-level detail can be added later.
-
-Use these commands during bootstrap to identify candidate tax-relevant roots:
-
-```bash
-bkper group list -b <bookId> --format csv
-bkper account list -b <bookId> --format csv
-```
-
-Inspect the output and look for groups or accounts that the user already treats as tax-related. Common patterns include:
-
-- A root group or account for **revenue / income** (often INCOMING type)
-- A root group or account for **deductible expenses** (often OUTGOING type)
-- Accounts or groups that track **tax liabilities** or **tax credits** (often LIABILITY or ASSET type)
-
-Do **not** assume standard names. Root group names vary by book — examples: `Revenue`, `Income`, `Sales`, `Deductible Expenses`, `Operating Costs`, `Taxes`, `VAT`, `Income Tax`.
-
-Ask the user which groups represent their **tax-relevant activity** for the period in question. If they are unsure, propose the smallest set of top-level groups that cover:
-
-1. **Gross revenue or income** for the period
-2. **Deductible costs or expenses** for the period
-3. Any **tax liability or credit accounts** already in use
-
-When you discover the correct groups, persist them for future runs.
-
-Prefer storing the **group IDs** in the local tax config/script. If the execution route also needs group names for query strings, persist the names as well.
-
-### If the book has no usable tax-relevant grouping
-
-If Step 2 does not reveal clear tax-relevant roots, treat that as a modeling gap, not as permission to improvise one silently.
-
-In that case:
-
-- explain that the book is **not yet tax-ready** for deterministic reporting
-- do **not** invent arbitrary tax categories from subgroup names or partial account matches
-- inspect the existing account names, language, and reporting style already present in the book
-- propose the **smallest** grouping that fits the user's actual use case and local standards
-- ask approval before creating groups, moving accounts, or persisting the proposed roots
-- once approved, validate the grouping with live queries and then persist it in the local runner/config
-
-If the user only wants a quick answer for now, you may still provide an **exploratory / provisional** result, but state clearly that the book still needs an approved tax-relevant hierarchy for future deterministic tax runs.
+Date examples:
 
----
-
-## Step 3 — Fetch data to validate and implement the runner
-
-Use these commands during bootstrap to validate the accounting logic and to implement the deterministic runner.
-
-Tax positions are period-based — query **activity within a period**, not cumulative position.
-
-### Balance-level bootstrap (aggregated)
-
-```bash
-# Revenue / income activity for the period
-bkper balance list -b <bookId> \
-  -q "group:'<revenueRoot>' after:<start> before:<end>" \
-  --format csv --expanded 2
-
-# Deductible expense activity for the period
-bkper balance list -b <bookId> \
-  -q "group:'<expenseRoot>' after:<start> before:<end>" \
-  --format csv --expanded 2
-
-# Tax liability or credit balance at period end (optional)
-bkper balance list -b <bookId> \
-  -q "account:'<taxLiabilityAccount>' before:<end>" \
-  --format csv --expanded 2
-```
-
-### Transaction-level bootstrap (itemized)
-
-```bash
-# Revenue / income transactions for the period
-bkper transaction list -b <bookId> \
-  -q "group:'<revenueRoot>' after:<start> before:<end>" \
-  --format csv
-
-# Deductible expense transactions for the period
-bkper transaction list -b <bookId> \
-  -q "group:'<expenseRoot>' after:<start> before:<end>" \
-  --format csv
-
-# Tax-account movements for the period (optional)
-bkper transaction list -b <bookId> \
-  -q "account:'<taxLiabilityAccount>' after:<start> before:<end>" \
-  --format csv
-```
-
-> **Bootstrap-only flags:** `--format csv` and `--expanded <level>` are conveniences for the discovery phase. CSV is compact for loading into an LLM context to inspect hierarchy structure; `--expanded <level>` reveals sub-totals so you can confirm the group tree is correct. The canonical runner you persist should output whatever format the user actually needs — structured JSON, Markdown tables, plain CSV, or rendered CLI tables — not necessarily the raw CLI dump.
-
-Use the output to confirm the correct groups, period totals, and hierarchy before persisting the script/spec.
-
-**Do not compute tax owed in the agent's reasoning.** The deterministic runner should output raw period data. The user (or a jurisdiction-specific layer they add later) applies rates, deductions, and rules.
+| Request | Period activity query |
+| --- | --- |
+| Current month | `after:$m-1 before:$m` |
+| Current year | `after:$y-1 before:$y` |
+| Full year 2024 | `after:2024-01-01 before:2025-01-01` |
+| Last quarter | Resolve to explicit `after:<start> before:<end>` boundaries |
 
----
+`$m` and `$y` are Bkper query date variables for current month-end and current year-end. In shell commands, wrap queries containing `$` variables in single quotes to prevent shell expansion.
 
-## Step 4 — Persist the deterministic route locally
+## Working route
 
-After discovery and validation, create or update local artifacts so future requests reuse the same route.
+Before computing a tax position, inspect local project context for an existing tax route:
 
-Typical artifacts:
+- `AGENTS.md`
+- `reports/`
+- `scripts/`
+- package scripts
+- tax config/spec files
+- platform app or bot code
 
-- `reports/tax-position.sh`
-- `scripts/taxes.ts`
-- `reports/taxes.json`
-- `package.json` scripts such as `report:taxes`
+If a route exists, use it and pass explicit Book, period, and supported override parameters. Do not rediscover tax Groups or rebuild the logic unless the user asks to change it.
 
-Persist the decisions that make the tax run repeatable:
+If no route exists, clarify the user's goal and recommend a repeatable route. Persist the decisions that make the tax run reproducible:
 
-- `bookId`
-- tax-relevant group IDs and names
-- query level (balance or transaction)
-- period semantics (e.g., calendar quarter, fiscal year)
-- timezone, if relevant to date boundaries
-- expanded depth for balance queries, if used
+- Book ID
+- tax period and timezone, when relevant
+- tax-relevant Group and Account IDs and names
+- balance-level or transaction-level detail
 - output format
+- jurisdiction-specific rules, rates, and assumptions, if supplied
 
-The canonical runner should produce a stable output shape using programmatic formatting — structured JSON, Markdown, rendered tables, or CSV — with clear sections, period labels, and raw totals. Build the report in code (via `bkper-js`, table builders, or the CLI's own render utilities) rather than passing through raw CLI query output. Keep the output **pre-calculation** — expose revenue, expenses, and any tax-account balances so the user can apply their local rules.
+If the Book has no clear tax-relevant grouping, treat that as a modeling gap. Do not invent tax categories silently. Inspect the Book's existing language and structure, propose the smallest grouping that fits the user's goal, and ask before changing Accounts or Groups.
 
-If helpful, also create or update a local `AGENTS.md` note telling future agent sessions to use the canonical tax script. `AGENTS.md` is **optional persistence**, not a prerequisite for the first request.
+## Examples & Patterns
 
----
+Use the implementation style that matches the user's context:
 
-## Step 5 — Use the script for future requests
+- **Scripts & CLI** — best for local, inspectable tax worksheets, reconciliations, and lightweight repeatable summaries.
+- **Platform Apps / Bots** — best for shared, durable, event-driven tax automation such as applying configured tax rules when Transactions are posted.
 
-Once the local tax runner exists:
+Existing trusted reports or templates may be reused when they are already the user's accepted tax route, but they are not required by this guide.
 
-- Use it as the default route for tax position and filing summary requests
-- Resolve relative periods like "last quarter" or "last year" into explicit date boundaries in code/config
-- Keep deterministic tax generation separate from optional AI commentary or filing advice
-- If the tax logic must change (new groups, different period boundaries), update the script/config instead of improvising a fresh one-off route
+## Provisional answers
 
-Do not re-decide which groups are tax-relevant on every request.
-
----
-
-## One-off exploratory fallback
-
-If the user explicitly does **not** want to create the script now and only wants a quick one-off answer, you may run live queries directly.
-
-In that case:
-
-- Clearly label the result as **exploratory / provisional**
-- State that it is **not yet** the canonical deterministic tax route for the project
-- Recommend persisting a local script/config if the user wants repeatable tax output in future requests
-
----
-
-## Date patterns
-
-Use these patterns when validating or implementing the deterministic runner.
-
-| Request        | Period activity query                          |
-| -------------- | ---------------------------------------------- |
-| Current month  | `after:$m-1 before:$m`                         |
-| Current year   | `after:$y-1 before:$y`                         |
-| Full year 2024 | `after:2024-01-01 before:2025-01-01`           |
-| Last quarter   | Resolve to explicit `after:<start> before:<end>` in script |
-
-- `after:` is **inclusive**, `before:` is **exclusive**
-- `$d` = today, `$m` = current month-end, `$y` = current year-end
-- In shell, wrap queries containing `$` variables in **single quotes** to prevent shell expansion
-
----
-
-## Key rules
-
-- **The agent orchestrates the engine; the engine produces the output** — the canonical runner is what generates the tax report, not the agent's direct reasoning
-- **Tax positions are period-based** — use `after:` + `before:` for revenue and expense activity, not `before:` alone
-- **Always query by group or account** — never run unfiltered queries across the whole book
-- **Output raw data, not computed tax owed** — the deterministic runner exposes totals; jurisdiction-specific calculation is a user concern
-- **Bootstrap queries** may use `--format csv` and `--expanded <level>` to inspect hierarchy structure efficiently; the canonical runner should use programmatic formatting suited to the end user
-- Once a canonical local tax route exists, **reuse it instead of rediscovering the logic**
-- Prefer persisting tax-relevant group decisions in code/config rather than relying on session memory
-
----
-
-## Common mistakes
-
-| Wrong | Right |
-| --- | --- |
-| The agent computing tax owed directly from queried data using guessed rates or rules | The agent building or reusing a local runner that outputs raw data; the user applies jurisdiction-specific rules |
-| Immediately running ad-hoc queries as the default response to a first tax request | First look for a local runner; if none exists, propose creating one and use queries only for bootstrap |
-| Assuming `AGENTS.md` must already exist | `AGENTS.md` can be created or updated during bootstrap to route future requests |
-| Using `before:` only for tax-relevant queries | Use `after:` + `before:` for period-based activity (revenue, expenses) |
-| Inventing a new tax hierarchy silently because no roots were found | Explain that the book is not yet tax-ready, propose a minimal grouping aligned with the user's language and local standards, and ask approval before changing structure |
-| Re-interpreting "last quarter" differently each time | Resolve relative periods into explicit dates inside the canonical script/config |
-| Mixing tax-bot specifics into the generic tax workflow | Keep this workflow independent of any bot or automation; it works from plain balances and transactions |
+If the user explicitly wants a quick answer and does not want to establish a route, live read-only queries are acceptable. Label the result as **exploratory / provisional** and avoid applying unsupplied tax law.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.16.3",
+    "version": "4.16.4",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"
@@ -51,7 +51,7 @@
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest"
     },
     "dependencies": {
-        "@earendil-works/pi-coding-agent": "0.79.0",
+        "@earendil-works/pi-coding-agent": "0.79.1",
         "bkper-js": "^2.35.2",
         "commander": "^13.1.0",
         "dotenv": "^8.2.0",