bkper 4.16.5 → 4.16.7

package/lib/agent/system-prompt.js

@@ -98,7 +98,7 @@ Base all reasoning about Bkper data — books, accounts, groups, transactions, b
 ## Reference Routing
 
 - Read local \`AGENTS.md\`, nearby files, and existing tests first for project-specific work.
-- For any Bkper task — CLI usage, SDK code, data management, or financial reports — read the docs index and then load the specific doc(s) it points to based on the task:
+- For any Bkper task — CLI usage, SDK code, data management, financial reports, or taxes — read the docs index and then load the specific doc(s) it points to based on the task:
 
 \`\`\`
 ${indexPath}

package/lib/docs/app-building.md

@@ -539,7 +539,9 @@ See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) for de
 
 ### Properties schema
 
-The `propertiesSchema` field defines autocomplete suggestions for custom properties in the Bkper UI, helping users discover the correct property keys and values for your app:
+The `propertiesSchema` field defines autocomplete suggestions for custom properties in the Bkper UI, helping users discover the correct property keys and values for your app.
+
+Suggested keys must follow the same custom property rules as user-entered keys, including the 30-character maximum after normalization.
 
 ```yaml
 propertiesSchema:

package/lib/docs/index.md

@@ -6,6 +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: 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** — 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.
+- **taxes.md** — Deterministic tax reporting principles: trusted routes, external tax-rule loading/discovery, 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

@@ -12,6 +12,25 @@ A tax route may compute tax owed only when the applicable rules, rates, and assu
 
 Prefer existing trusted routes before creating new ones. If none exists, recommend the smallest auditable route that fits the user's context.
 
+## Loading tax rules
+
+When no trusted local tax route exists, or when the user asks to load jurisdiction rules, use external tax-rule libraries only as discovery sources. They may identify candidate rates, thresholds, deadlines, forms, classifications, and citations, but they are not a final computation route.
+
+Do not produce tax numbers from loaded rules until the rule source, tax period, assumptions, and Bkper mappings have been reviewed or approved.
+
+Preferred non-MCP OpenAccountants route:
+
+1. Resolve the jurisdiction code or name, such as `BR`, `GB`, `DE`, `US-CA`, `CA-ON`, or `brazil`.
+2. Fetch `https://www.openaccountants.com/api/bundle/<CODE_OR_NAME>`.
+3. Do not use MCP unless the user explicitly requests it.
+4. If the bundle cannot be resolved, ask the user for the exact jurisdiction or source URL instead of guessing.
+5. Record source URL, retrieval date, tax year, quality tier, verifier if present, and citations.
+6. Map rules only to user-approved Bkper Groups, Accounts, properties, or hashtags.
+
+Example: for Brazil, fetch `https://www.openaccountants.com/api/bundle/BR` or `https://www.openaccountants.com/api/bundle/brazil`, then clarify whether the scope is IRPF, Carnê-Leão, payroll, indirect tax, e-invoice compliance, or another Brazil tax area.
+
+For multi-layer jurisdictions, first determine whether the scope is national/federal-only, sub-jurisdiction-only, or both. Use a national/federal code such as `US` or `US-FED` for US federal-only rules. Use structured sub-jurisdiction codes such as `US-CA` for California or `CA-ON` for Ontario when state or provincial rules are relevant. If both layers matter, load and record each applicable bundle, and verify that the returned bundle title matches the requested layer.
+
 ## Bkper tax semantics
 
 Tax reports usually combine period activity with tax-account positions or movements.

package/package.json

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