bkper 4.12.30 → 4.12.31

package/lib/docs/index.md

@@ -6,5 +6,6 @@ Reference docs for Bkper tasks. Load only the specific doc(s) relevant to the ta
 - **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: architecture (packages, client/server/events), development loop, event handlers, deployment patterns, the Bkper Platform, and self-hosted alternatives. Includes authentication patterns for web clients (`@bkper/web-auth`), event handlers (`bkper-oauth-token` headers), and local development. Load this for scaffolding apps, understanding app structure, or debugging the dev/build/deploy lifecycle.
 - **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.
 - **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 — field names and types used by the API and bkper-js.

package/lib/docs/taxes.md

@@ -0,0 +1,264 @@
+# Taxes — Deterministic Workflow
+
+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.
+
+## Deterministic first
+
+Tax reporting is a **deterministic accounting task**.
+
+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.
+
+Treat the tax route as something that should be **persisted locally** and reused.
+
+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.
+
+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.
+
+---
+
+## Step 0 — Reuse an existing local tax runner
+
+Before running ad-hoc queries, inspect the local project for a canonical deterministic tax runner.
+
+Look for artifacts such as:
+
+- `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.
+
+---
+
+## 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.
+
+---
+
+## 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:
+
+- `reports/tax-position.sh`
+- `scripts/taxes.ts`
+- `reports/taxes.json`
+- `package.json` scripts such as `report:taxes`
+
+Persist the decisions that make the tax run repeatable:
+
+- `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
+- output format
+
+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 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.
+
+---
+
+## Step 5 — Use the script for future requests
+
+Once the local tax runner exists:
+
+- 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
+
+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 |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.12.30",
+    "version": "4.12.31",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"