bkper 4.9.1 → 4.10.1

package/README.md

@@ -268,8 +268,11 @@ bkper transaction create -b abc123 --description "Office supplies"
 bkper transaction create -b abc123 --date 2025-01-15 --amount 100.50 \
   --from "Bank Account" --to "Office Supplies" --description "Printer paper"
 
-# List transactions with a query
-bkper transaction list -b abc123 -q "after:2025-01-01"
+# List transactions for a full year (on:YYYY)
+bkper transaction list -b abc123 -q "on:2025"
+
+# List transactions for a month (on:YYYY-MM)
+bkper transaction list -b abc123 -q "on:2025-01"
 
 # List with custom properties included
 bkper transaction list -b abc123 -q "account:Sales" -p
@@ -325,11 +328,11 @@ bkper transaction merge tx_123 tx_456 -b abc123
 Query account balances and group totals.
 
 ```bash
-# List balances for a query
-bkper balance list -b abc123 -q "period:2025-01"
+# List balances for a specific date (point-in-time)
+bkper balance list -b abc123 -q "on:2025-12-31"
 
-# Expand groups to see individual accounts
-bkper balance list -b abc123 -q "period:2025-01" --expanded 2
+# Monthly balance evolution of one account during 2025
+bkper balance list -b abc123 -q "account:'<accountName>' after:2025-01-01 before:2026-01-01 by:m" --expanded 2
 ```
 
 <details>
@@ -340,6 +343,28 @@ bkper balance list -b abc123 -q "period:2025-01" --expanded 2
 
 </details>
 
+### Query semantics (transactions and balances)
+
+Use the same query language across Bkper web app, CLI, and Google Sheets integrations.
+
+-   `on:` supports different granularities:
+    -   `on:2025` → full year
+    -   `on:2025-01` → full month
+    -   `on:2025-01-31` → specific day
+-   `after:` is **inclusive** and `before:` is **exclusive**.
+    -   Full year 2025: `after:2025-01-01 before:2026-01-01`
+-   For point-in-time statements (typically permanent accounts `ASSET`/`LIABILITY`), prefer `on:` or `before:`.
+-   For activity statements over a period (typically non-permanent accounts `INCOMING`/`OUTGOING`), prefer `after:` + `before:`.
+-   For statement-level analysis, prefer filtering by the report root group. Root names vary by book.
+
+```bash
+# Balance Sheet snapshot (point-in-time)
+bkper balance list -b abc123 -q "group:'<balanceSheetRootGroup>' before:2026-01-01"
+
+# P&L activity over 2025
+bkper balance list -b abc123 -q "group:'<profitAndLossRootGroup>' after:2025-01-01 before:2026-01-01"
+```
+
 ### Collections
 
 Organize books into collections.
@@ -382,11 +407,11 @@ bkper collection delete col_789
 
 All commands support three output formats via the `--format` global flag:
 
-| Format | Flag                       | Best for                                |
-| ------ | -------------------------- | --------------------------------------- |
-| Table  | `--format table` (default) | Human reading in the terminal           |
-| JSON   | `--format json`            | Programmatic access, single-item detail |
-| CSV    | `--format csv`             | Spreadsheets, AI agents, data pipelines |
+| Format | Flag                       | Best for                                    |
+| ------ | -------------------------- | ------------------------------------------- |
+| Table  | `--format table` (default) | Human reading in the terminal               |
+| JSON   | `--format json`            | Programmatic access, single-item detail     |
+| CSV    | `--format csv`             | LLM consumption, spreadsheets, list reports |
 
 ```bash
 # Table output (default)
@@ -406,13 +431,20 @@ bkper account list -b abc123 --format csv
 -   **Raw values** -- dates stay in ISO format, numbers are unformatted (no locale formatting)
 -   **Single-item commands** (e.g. `account get`, `transaction create`) fall back to JSON since CSV adds no value for non-tabular data
 
-**AI agent guidance:**
+**LLM-first output guidance (important):**
+
+When command output will be loaded into an LLM context (chat, prompt, memory, or agent reasoning), prefer:
+
+-   **`--format csv` for list commands** (`balance list`, `transaction list`, `account list`, etc.).
+-   **`--format json` for single-item commands** (`get`, `create`, `update`) and CLI-to-CLI pipelines.
+
+CSV is significantly more token-efficient than JSON for tabular data, and for wide balance outputs it can reduce token usage by up to **95%**.
 
-When using the CLI from an AI agent, LLM, or automated script:
+**Quick rule:**
 
--   **Use `--format csv` for list commands.** CSV is dramatically more token-efficient than JSON for tabular data -- typically 3-5x fewer tokens for the same information.
--   **Use `--format json` for single-item commands** (`get`, `create`, `update`) where you need structured field access.
--   **Pipe data in via stdin** for batch operations (see below).
+-   **LLM consumption of lists/reports** → CSV
+-   **Programmatic processing / pipelines** → JSON
+-   **Human terminal reading** → Table
 
 ### Batch Operations & Piping
 

package/lib/agent/run-agent-mode.js

@@ -8,11 +8,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { createAgentSession, DefaultResourceLoader, InteractiveMode, } from '@mariozechner/pi-coding-agent';
-import { BKPER_AGENT_SYSTEM_PROMPT } from './system-prompt.js';
+import { getBkperAgentSystemPrompt } from './system-prompt.js';
 function createDefaultDependencies() {
     return {
         createResourceLoader: () => new DefaultResourceLoader({
-            systemPromptOverride: () => BKPER_AGENT_SYSTEM_PROMPT,
+            systemPromptOverride: () => getBkperAgentSystemPrompt(),
             appendSystemPromptOverride: () => [],
             extensionFactories: [
                 (pi) => {

package/lib/agent/run-agent-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-agent-mode.js","sourceRoot":"","sources":["../../src/agent/run-agent-mode.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EACH,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,GAGlB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAsB/D,SAAS,yBAAyB;IAC9B,OAAO;QACH,oBAAoB,EAAE,GAAG,EAAE,CACvB,IAAI,qBAAqB,CAAC;YACtB,oBAAoB,EAAE,GAAG,EAAE,CAAC,yBAAyB;YACrD,0BAA0B,EAAE,GAAG,EAAE,CAAC,EAAE;YACpC,kBAAkB,EAAE;gBAChB,CAAC,EAAgB,EAAE,EAAE;oBACjB,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAO,MAAM,EAAE,GAAG,EAAE,EAAE;wBACzC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;oBAChD,CAAC,CAAA,CAAC,CAAC;gBACP,CAAC;aACJ;SACJ,CAAC;QACN,aAAa,EAAE,KAA2B,EAAE,0CAAtB,EAAE,cAAc,EAAE;YACpC,OAAA,kBAAkB,CAAC;gBACf,cAAc,EACV,cAA0E;aACjF,CAAC,CAAA;UAAA;QACN,qBAAqB,EAAE,CAAC,OAAO,EAAE,oBAAoB,EAAE,EAAE,CACrD,IAAI,eAAe,CAAC,OAA2D,EAAE;YAC7E,oBAAoB;SACvB,CAAC;KACT,CAAC;AACN,CAAC;AAED,MAAM,UAAgB,YAAY;yDAC9B,eAAsC,yBAAyB,EAAE;;;QAEjE,YAAA,OAAO,CAAC,GAAG,EAAC,qBAAqB,uCAArB,qBAAqB,GAAK,GAAG,EAAC;QAE1C,MAAM,cAAc,GAAG,YAAY,CAAC,oBAAoB,EAAE,CAAC;QAC3D,MAAM,cAAc,CAAC,MAAM,EAAE,CAAC;QAE9B,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,YAAY,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;QAC/F,MAAM,IAAI,GAAG,YAAY,CAAC,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QAE/E,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;IACrB,CAAC;CAAA"}
+{"version":3,"file":"run-agent-mode.js","sourceRoot":"","sources":["../../src/agent/run-agent-mode.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EACH,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,GAGlB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAsB/D,SAAS,yBAAyB;IAC9B,OAAO;QACH,oBAAoB,EAAE,GAAG,EAAE,CACvB,IAAI,qBAAqB,CAAC;YACtB,oBAAoB,EAAE,GAAG,EAAE,CAAC,yBAAyB,EAAE;YACvD,0BAA0B,EAAE,GAAG,EAAE,CAAC,EAAE;YACpC,kBAAkB,EAAE;gBAChB,CAAC,EAAgB,EAAE,EAAE;oBACjB,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAO,MAAM,EAAE,GAAG,EAAE,EAAE;wBACzC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;oBAChD,CAAC,CAAA,CAAC,CAAC;gBACP,CAAC;aACJ;SACJ,CAAC;QACN,aAAa,EAAE,KAA2B,EAAE,0CAAtB,EAAE,cAAc,EAAE;YACpC,OAAA,kBAAkB,CAAC;gBACf,cAAc,EACV,cAA0E;aACjF,CAAC,CAAA;UAAA;QACN,qBAAqB,EAAE,CAAC,OAAO,EAAE,oBAAoB,EAAE,EAAE,CACrD,IAAI,eAAe,CAAC,OAA2D,EAAE;YAC7E,oBAAoB;SACvB,CAAC;KACT,CAAC;AACN,CAAC;AAED,MAAM,UAAgB,YAAY;yDAC9B,eAAsC,yBAAyB,EAAE;;;QAEjE,YAAA,OAAO,CAAC,GAAG,EAAC,qBAAqB,uCAArB,qBAAqB,GAAK,GAAG,EAAC;QAE1C,MAAM,cAAc,GAAG,YAAY,CAAC,oBAAoB,EAAE,CAAC;QAC3D,MAAM,cAAc,CAAC,MAAM,EAAE,CAAC;QAE9B,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,YAAY,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;QAC/F,MAAM,IAAI,GAAG,YAAY,CAAC,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QAE/E,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;IACrB,CAAC;CAAA"}

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

@@ -1,2 +1,3 @@
+export declare function getBkperAgentSystemPrompt(): string;
 export declare const BKPER_AGENT_SYSTEM_PROMPT = "# You are a Bkper team member\n\nYou think in resources, movements, and balances \u2014 not debits and credits. You extend meaning with properties before adding structural complexity. You protect the zero-sum invariant above all else.\n\n## Core Concepts Canon\n\n- Bkper tracks resources as movements **from one Account to another**.\n- The system enforces a strict **zero-sum invariant** at Book level: nothing is created or destroyed, only transferred.\n- A **Transaction** is the atomic event with date, amount, from Account, to Account, and description.\n- Transaction states define balance impact: **Draft** does not impact balances; **Unchecked** and **Checked** impact balances; **Trashed** removes impact but preserves auditability.\n- Account types govern balance behavior:\n  - **Asset** and **Liability** are permanent (cumulative position to a date).\n  - **Incoming** and **Outgoing** are non-permanent (activity within a period).\n- **Groups** organize and aggregate Accounts for analysis; they do not alter ledger truth.\n- **Custom Properties** (`key=value`) are first-class semantic bindings across Books, Accounts, Groups, Transactions, Collections, and Files.\n- Use Custom Properties to map core concepts to higher-level domains (invoice, project, tax, SKU, cost center) without changing the core model.\n- Prefer adding meaning with properties before introducing structural complexity.\n- **Balances** are derived from Transactions, never an independent source of truth.\n- A **Book** is a self-contained ledger that always balances to zero.\n- **Collections** organize multiple Books; each Book remains independently balanced.\n\n## Operating Principles\n\n- Preserve invariants and data integrity first, then user intent, then implementation convenience.\n- Model domain and flows before coding; represent business reality, not technical shortcuts.\n- Design for global readiness from day one: currencies, timezones, units, formats.\n- For conceptual questions, answer directly and concisely before reaching for tools.\n";
 //# sourceMappingURL=system-prompt.d.ts.map

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":"AAAA,eAAO,MAAM,yBAAyB,igEA2BrC,CAAC"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAQA,wBAAgB,yBAAyB,IAAI,MAAM,CAWlD;AAED,eAAO,MAAM,yBAAyB,igEA2BrC,CAAC"}

package/lib/agent/system-prompt.js

@@ -1,3 +1,21 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+function resolveCliReferencePath() {
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(thisDir, '..', 'docs', 'cli-reference.md');
+}
+export function getBkperAgentSystemPrompt() {
+    const cliRefPath = resolveCliReferencePath();
+    return `${BKPER_AGENT_SYSTEM_PROMPT}
+## Bkper CLI Usage
+
+Before executing \`bkper\` CLI commands, **read the full CLI reference** at:
+
+\`\`\`
+${cliRefPath}
+\`\`\`
+`;
+}
 export const BKPER_AGENT_SYSTEM_PROMPT = `# You are a Bkper team member
 
 You think in resources, movements, and balances — not debits and credits. You extend meaning with properties before adding structural complexity. You protect the zero-sum invariant above all else.

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

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BxC,CAAC"}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,SAAS,uBAAuB;IAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,yBAAyB;IACrC,MAAM,UAAU,GAAG,uBAAuB,EAAE,CAAC;IAC7C,OAAO,GAAG,yBAAyB;;;;;;EAMrC,UAAU;;CAEX,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BxC,CAAC"}

package/lib/commands/agent-command.js

@@ -8,7 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { main as runPiMain } from '@mariozechner/pi-coding-agent';
-import { BKPER_AGENT_SYSTEM_PROMPT } from '../agent/system-prompt.js';
+import { getBkperAgentSystemPrompt } from '../agent/system-prompt.js';
 function createDefaultDependencies() {
     return {
         runPi: (args) => runPiMain(args),
@@ -21,7 +21,7 @@ function buildPiArgs(args) {
     if (hasSystemPromptArg(args)) {
         return args;
     }
-    return ['--system-prompt', BKPER_AGENT_SYSTEM_PROMPT, ...args];
+    return ['--system-prompt', getBkperAgentSystemPrompt(), ...args];
 }
 export function registerAgentCommands(program, dependencies = createDefaultDependencies()) {
     program

package/lib/commands/agent-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-command.js","sourceRoot":"","sources":["../../src/commands/agent-command.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAMtE,SAAS,yBAAyB;IAC9B,OAAO;QACH,KAAK,EAAE,CAAC,IAAc,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;KAC7C,CAAC;AACN,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,iBAAiB,IAAI,GAAG,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,WAAW,CAAC,IAAc;IAC/B,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,CAAC,iBAAiB,EAAE,yBAAyB,EAAE,GAAG,IAAI,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,qBAAqB,CACjC,OAAgB,EAChB,eAAyC,yBAAyB,EAAE;IAEpE,OAAO;SACF,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,8CAA8C,CAAC;SAC3D,kBAAkB,CAAC,IAAI,CAAC;SACxB,oBAAoB,CAAC,IAAI,CAAC;SAC1B,MAAM,CAAC,YAA8B,EAAE,iDAAzB,SAAmB,EAAE;QAChC,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;YACjC,MAAM,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACL,CAAC,CAAA,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"agent-command.js","sourceRoot":"","sources":["../../src/commands/agent-command.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAMtE,SAAS,yBAAyB;IAC9B,OAAO;QACH,KAAK,EAAE,CAAC,IAAc,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;KAC7C,CAAC;AACN,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,iBAAiB,IAAI,GAAG,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,WAAW,CAAC,IAAc;IAC/B,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,CAAC,iBAAiB,EAAE,yBAAyB,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,qBAAqB,CACjC,OAAgB,EAChB,eAAyC,yBAAyB,EAAE;IAEpE,OAAO;SACF,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,8CAA8C,CAAC;SAC3D,kBAAkB,CAAC,IAAI,CAAC;SACxB,oBAAoB,CAAC,IAAI,CAAC;SAC1B,MAAM,CAAC,YAA8B,EAAE,iDAAzB,SAAmB,EAAE;QAChC,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;YACjC,MAAM,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACL,CAAC,CAAA,CAAC,CAAC;AACX,CAAC"}