bkper 4.10.5 → 4.11.0

package/README.md

@@ -238,6 +238,16 @@ bkper group update "Cash" -b abc123 --hidden true
 bkper group delete "Cash" -b abc123
 ```
 
+### Book setup guidance (important)
+
+When setting up a full Book or starter chart of accounts, prefer a hierarchical group structure by default.
+
+Create top-level groups first, then child groups with `--parent`, then accounts with `--groups`.
+
+Verify the resulting group hierarchy and account memberships before reporting success.
+
+Avoid using the same name for a Group and an Account in the same Book.
+
 <details>
 <summary>Command reference</summary>
 
@@ -448,7 +458,7 @@ CSV is significantly more token-efficient than JSON for tabular data, and for wi
 
 ### Batch Operations & Piping
 
-Write commands (`account create`, `group create`, `transaction create`) accept JSON data piped via stdin for batch operations. The `transaction update` command also accepts stdin for batch updates. The input format follows the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts) exactly -- a single JSON object or an array of objects.
+Write commands (`account create`, `transaction create`) accept JSON data piped via stdin for batch operations. The `transaction update` command also accepts stdin for batch updates. The input format follows the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts) exactly -- a single JSON object or an array of objects.
 
 ```bash
 # Create transactions
@@ -465,15 +475,13 @@ echo '[{
 echo '[{"name":"Cash","type":"ASSET"},{"name":"Revenue","type":"INCOMING"}]' | \
   bkper account create -b abc123
 
-# Create groups
-echo '[{"name":"Fixed Costs","hidden":true}]' | \
-  bkper group create -b abc123
-
 # Pipe from a script
 python export_bank.py | bkper transaction create -b abc123
 ```
 
-The input follows the exact `bkper.Transaction`, `bkper.Account`, or `bkper.Group` type from the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts). Custom properties go inside the `properties` object.
+The input follows the exact `bkper.Transaction` or `bkper.Account` type from the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts). Custom properties go inside the `properties` object.
+
+Groups are created explicitly with `bkper group create --name` and optional `--parent` so hierarchy stays deterministic during setup.
 
 The `--property` CLI flag can override or delete properties from the stdin payload:
 
@@ -491,21 +499,17 @@ bkper account create -b abc123 < accounts.json
 
 **Piping between commands:**
 
-All JSON output is designed to be piped directly as stdin to other commands. The output of any list or batch create command can feed directly into a create or update command:
+For resources that support stdin creation, JSON output can be piped directly into create or update commands:
 
 ```bash
 # Copy all accounts from one book to another
 bkper account list -b $BOOK_A --format json | bkper account create -b $BOOK_B
 
-# Copy all groups from one book to another
-bkper group list -b $BOOK_A --format json | bkper group create -b $BOOK_B
-
 # Copy transactions matching a query
 bkper transaction list -b $BOOK_A -q "after:2025-01-01" --format json | \
   bkper transaction create -b $BOOK_B
 
-# Clone a full chart of accounts: groups, then accounts, then transactions
-bkper group list -b $SOURCE --format json | bkper group create -b $DEST
+# Clone accounts, then transactions
 bkper account list -b $SOURCE --format json | bkper account create -b $DEST
 bkper transaction list -b $SOURCE -q "after:2025-01-01" --format json | \
   bkper transaction create -b $DEST
@@ -555,15 +559,6 @@ Only the fields below are meaningful when creating or updating resources via std
 | `groups`     | `[{"name":"..."}, ...]` | Groups to assign by name or id                     |
 | `properties` | `{"key": "value", ...}` | Custom key/value properties                        |
 
-**Group** (`bkper.Group`)
-
-| Field        | Type                               | Notes                            |
-| ------------ | ---------------------------------- | -------------------------------- |
-| `name`       | `string`                           | Group name (required)            |
-| `hidden`     | `boolean`                          | Hide from transactions main menu |
-| `parent`     | `{"name":"..."}` or `{"id":"..."}` | Parent group for nesting         |
-| `properties` | `{"key": "value", ...}`            | Custom key/value properties      |
-
 </details>
 
 ---

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

@@ -1,3 +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\n\nBkper tracks resources \u2014 money, inventory, or anything countable \u2014 as movements between places. Every financial event is recorded as an amount moving **from** one Account **to** another. This from-to model replaces the traditional language of debits and credits with something intuitive: resources leave one place and arrive at another.\n\nThe system enforces a **zero-sum invariant** \u2014 the total of all records always equals zero. Nothing is created or destroyed, only transferred. This makes Bkper a double-entry bookkeeping system where every transaction automatically produces balanced entries.\n\nFor those familiar with traditional accounting, \"from\" corresponds to credit and \"to\" corresponds to debit \u2014 but the explicit flow eliminates the need to memorize these rules.\n\n## Accounts\n\n**Accounts** are the places where resources reside or flow through. An Account can represent a bank, a category, a customer, a project, or anything else that holds or transfers value. You define what each Account represents and structure them at whatever level of detail suits your needs.\n\nAn Account registers all incoming and outgoing amounts through transactions. The sum of these movements produces the account's **balance** \u2014 the net result of everything that has flowed in and out.\n\n## Account Types\n\nBkper organizes Accounts into four types that determine how an Account behaves and where it appears in your financial structure:\n\n- **Asset** (blue) \u2014 **permanent**. Real resources you own: bank accounts, cash, receivables. Balances carry forward continuously, showing your position at any point in time.\n- **Liability** (yellow) \u2014 **permanent**. Obligations you owe: credit cards, loans, supplier debts. Balances also carry forward continuously.\n- **Incoming** (green) \u2014 **non-permanent**. Revenue sources: salary, sales, interest. Balances track activity within a period and reset to zero for the next one.\n- **Outgoing** (red) \u2014 **non-permanent**. Expenses and costs: rent, supplies, payroll. Balances also track activity within a period.\n\n## Transactions\n\nA **Transaction** is the atomic unit of financial activity. It captures:\n\n- **Date** \u2014 when it happened\n- **Amount** \u2014 how much moved\n- **From Account** \u2014 where the resource came from\n- **To Account** \u2014 where it went\n- **Description** \u2014 what happened\n\nThe from-to model makes every event explicit and traceable.\n\nA transaction is nothing more than moving a resource from one place to another. When you pay a taxi for a ride, the amount that goes from your wallet to the driver represents a transaction.\n\nIf any essential element is missing, the transaction is saved as an incomplete draft.\n\n## Transaction States\n\nTransactions move through a lifecycle with four states:\n\n- **Draft** \u2014 incomplete or unposted. Does not affect balances.\n- **Unchecked** \u2014 posted and updates balances, but remains editable.\n- **Checked** \u2014 reviewed and locked for integrity.\n- **Trashed** \u2014 removed from balances, but recoverable.\n\nThis structure puts a **human in the loop** \u2014 you review and confirm before records become permanent.\n\n## Groups\n\n**Groups** organize Accounts into hierarchies for reporting and analysis. They don't change the underlying data \u2014 they provide structure for understanding it. Groups consolidate account balances, so you can see totals for categories like \"Expenses\" or \"Assets\" at a glance.\n\nGroups support hierarchies (groups of groups) and multiple perspectives \u2014 an Account can belong to different groups in different hierarchies.\n\nGroups inherit the nature of the accounts they contain:\n\n- **Asset-only group** \u2014 behaves as Asset (blue)\n- **Liability-only group** \u2014 behaves as Liability (yellow)\n- **Mixed Asset + Liability** \u2014 shows Equity (gray, net balance)\n- **Incoming-only group** \u2014 behaves as Income (green)\n- **Outgoing-only group** \u2014 behaves as Expense (red)\n- **Mixed Incoming + Outgoing** \u2014 shows Net Result (gray)\n\n## Books\n\nA **Book** is a self-contained ledger \u2014 the complete scope of an entity, whether an individual, a project, or a business. Every Account, Transaction, and Group lives within a Book, and every Book balances to zero. Books can track any countable resource using the same from-to model.\n\nThe sum of all credits and debits recorded in a Book always tallies to zero \u2014 nothing is created or destroyed, only transferred. For more complex entities, multiple Books can be organized into a Collection.\n\n## Example Flows\n\nThese examples show the same movement model in concrete situations. Some match the diagrams on this page. Others add common accrual flows that are easy to confuse.\n\nThese examples use Bkper's transaction shorthand `From >> To`, meaning the amount leaves the Account on the left and arrives at the Account on the right.\n\n| Situation | Transaction |\n| --- | --- |\n| Salary received | `Salary >> Bank Account` |\n| Investment funded | `Bank Account >> Investments` |\n| Dividends received | `Dividends >> Bank Account` |\n| Loan received | `Loan >> Bank Account` |\n| Rent paid | `Bank Account >> Rent` |\n| Transportation bought on credit card | `Credit Card >> Transportation` |\n\n**Buy on a credit card now, pay it later**\n\n| Step | Transaction |\n| --- | --- |\n| Purchase | `Credit Card >> Outgoing` |\n| Payment | `Bank Account >> Credit Card` |\n\n**Sell now and receive cash later**\n\n| Step | Transaction |\n| --- | --- |\n| Sale on credit | `Incoming >> Accounts Receivable` |\n| Interest added while unpaid | `Incoming >> Accounts Receivable` |\n| Collection | `Accounts Receivable >> Bank Account` |\n\n**Receive a supplier bill now and pay it later**\n\n| Step | Transaction |\n| --- | --- |\n| Bill received | `Accounts Payable >> Outgoing` |\n| Interest added while unpaid | `Accounts Payable >> Outgoing` |\n| Payment | `Bank Account >> Accounts Payable` |\n\n**Receive a loan now and repay principal later**\n\n| Step | Transaction |\n| --- | --- |\n| Loan proceeds | `Loan >> Bank Account` |\n| Principal repayment | `Bank Account >> Loan` |\n\nIn each case, the first movement records the position that was created \u2014 a receivable or a liability. The later movement settles that position. This keeps Incoming and Outgoing focused on activity, while Asset and Liability Accounts hold positions until they are cleared.\n\nIf a receivable or payable grows before settlement, record another movement to that same Account, then settle the total later.\n\n## Balances\n\n**Balances** are always calculated from Transactions, never stored independently. The total balance across all Accounts in a Book is always zero. Account type determines how balances behave over time:\n\n- **Permanent Accounts** (Asset & Liability) \u2014 balance **to a date**, showing cumulative position at a point in time.\n- **Non-permanent Accounts** (Incoming & Outgoing) \u2014 balance **within a period**, showing activity during a timeframe.\n\nBkper maintains a continuous ledger with no concept of closing periods \u2014 the same ledger serves all time-based queries automatically.\n\n## Custom Properties\n\n**Custom Properties** are key-value pairs attachable to any entity \u2014 Books, Accounts, Groups, Transactions, Collections, and Files. They add context, metadata, and meaning beyond core financial data.\n\nBy attaching properties like `invoice: inv123456` or `exc_code: BRL`, entities become rich with information that can drive automation and reporting \u2014 without changing the core model.\n\n## Hashtags\n\n**Hashtags** are lightweight labels on Transactions that enable multi-dimensional tracking. They complement the Account structure by adding dynamic categorization \u2014 a single transaction might carry `#team_marketing #project_alpha #q1_campaign`, enabling filtering and analysis from any perspective.\n\nUnlike Account structures, Hashtags can be added or removed as needs evolve, making them ideal for cost allocation, project tracking, and ad-hoc analysis.\n\n## Collections\n\n**Collections** group related Books for organization and consolidated views. Each Book remains self-contained and balanced \u2014 Collections simply provide navigation and structure across multiple Books. You might track resources in multiple currencies, or organize branch offices in one collection.\n\nCollections can also serve as references for automations (Bots or Apps) that work on all Books in the collection.\n\n## Events\n\nEvery action in a Book \u2014 posting a transaction, editing an account, adding a comment \u2014 generates an **Event**. Events record _who_ (a user) or _what_ (a bot, an automation) performed the action and _when_, forming a complete audit trail essential for collaboration and trust.\n\nEvents are also the foundation of Bkper's automation model. Bots and Agents listen for specific event types and react automatically \u2014 for example, calculating taxes when a transaction is posted or converting currencies when one is checked.\n\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";
+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## 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":"AASA,wBAAgB,yBAAyB,IAAI,MAAM,CAWlD;AAED,eAAO,MAAM,yBAAyB,kjTAYrC,CAAC"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAaA,wBAAgB,yBAAyB,IAAI,MAAM,CAsBlD;AAED,eAAO,MAAM,yBAAyB,0nBAUrC,CAAC"}

package/lib/agent/system-prompt.js

@@ -1,28 +1,40 @@
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { CORE_CONCEPTS_MARKDOWN } from './core-concepts.js';
 function resolveCliReferencePath() {
     const thisDir = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(thisDir, '..', 'docs', 'cli-reference.md');
 }
+function resolveCoreConceptsPath() {
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(thisDir, '..', 'docs', 'core-concepts.md');
+}
 export function getBkperAgentSystemPrompt() {
     const cliRefPath = resolveCliReferencePath();
+    const coreConceptsPath = resolveCoreConceptsPath();
     return `${BKPER_AGENT_SYSTEM_PROMPT}
-## Bkper CLI Usage
+## Reference Loading Rules
 
-Before executing \`bkper\` CLI commands, **read the full CLI reference** at:
+If the task touches Bkper accounting semantics or data modeling — such as Accounts, Transactions, balances, account types, groups, books, or mapping real-world flows into Bkper — read:
+
+\`\`\`
+${coreConceptsPath}
+\`\`\`
+
+If the task involves using or executing \`bkper\` CLI commands, read:
 
 \`\`\`
 ${cliRefPath}
 \`\`\`
+
+For generic engineering work, you may proceed without loading either reference unless those semantics become relevant.
+
+When in doubt, read first.
 `;
 }
 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.
 
-${CORE_CONCEPTS_MARKDOWN}
-
 ## Operating Principles
 
 - Preserve invariants and data integrity first, then user intent, then implementation convenience.

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,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAC,sBAAsB,EAAC,MAAM,oBAAoB,CAAC;AAE1D,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;;;;EAIvC,sBAAsB;;;;;;;;CAQvB,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,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,MAAM,gBAAgB,GAAG,uBAAuB,EAAE,CAAC;IACnD,OAAO,GAAG,yBAAyB;;;;;;EAMrC,gBAAgB;;;;;;EAMhB,UAAU;;;;;;CAMX,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;CAUxC,CAAC"}

package/lib/commands/groups/index.d.ts

@@ -3,5 +3,4 @@ export { getGroup } from './get.js';
 export { createGroup, CreateGroupOptions } from './create.js';
 export { updateGroup, UpdateGroupOptions } from './update.js';
 export { deleteGroup } from './delete.js';
-export { batchCreateGroups } from './batch-create.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/commands/groups/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/groups/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/groups/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/lib/commands/groups/index.js

@@ -3,5 +3,4 @@ export { getGroup } from './get.js';
 export { createGroup } from './create.js';
 export { updateGroup } from './update.js';
 export { deleteGroup } from './delete.js';
-export { batchCreateGroups } from './batch-create.js';
 //# sourceMappingURL=index.js.map

package/lib/commands/groups/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/groups/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/groups/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/lib/commands/groups/register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/commands/groups/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8F5D"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/commands/groups/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmF5D"}

package/lib/commands/groups/register.js

@@ -11,8 +11,7 @@ import { withAction } from '../action.js';
 import { collectProperty } from '../cli-helpers.js';
 import { renderListResult, renderItem } from '../../render/index.js';
 import { validateRequiredOptions, throwIfErrors } from '../../utils/validation.js';
-import { parseStdinItems } from '../../input/index.js';
-import { listGroupsFormatted, getGroup, createGroup, updateGroup, deleteGroup, batchCreateGroups, } from './index.js';
+import { listGroupsFormatted, getGroup, createGroup, updateGroup, deleteGroup } from './index.js';
 export function registerGroupCommands(program) {
     const groupCommand = program.command('group').description('Manage Groups');
     groupCommand
@@ -42,27 +41,17 @@ export function registerGroupCommands(program) {
         .option('--hidden', 'Hide the group')
         .option('-p, --property <key=value>', 'Set a property (repeatable)', collectProperty)
         .action(options => withAction('creating group', (format) => __awaiter(this, void 0, void 0, function* () {
-        const stdinData = !process.stdin.isTTY ? yield parseStdinItems() : null;
-        if (stdinData && stdinData.items.length > 0) {
-            throwIfErrors(validateRequiredOptions(options, [{ name: 'book', flag: '--book' }]));
-            yield batchCreateGroups(options.book, stdinData.items, options.property);
-        }
-        else if (stdinData && stdinData.items.length === 0) {
-            console.log(JSON.stringify([], null, 2));
-        }
-        else {
-            throwIfErrors(validateRequiredOptions(options, [
-                { name: 'book', flag: '--book' },
-                { name: 'name', flag: '--name' },
-            ]));
-            const group = yield createGroup(options.book, {
-                name: options.name,
-                parent: options.parent,
-                hidden: options.hidden,
-                property: options.property,
-            });
-            renderItem(group.json(), format);
-        }
+        throwIfErrors(validateRequiredOptions(options, [
+            { name: 'book', flag: '--book' },
+            { name: 'name', flag: '--name' },
+        ]));
+        const group = yield createGroup(options.book, {
+            name: options.name,
+            parent: options.parent,
+            hidden: options.hidden,
+            property: options.property,
+        });
+        renderItem(group.json(), format);
     }))());
     groupCommand
         .command('update <idOrName>')

package/lib/commands/groups/register.js.map

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

package/lib/docs/cli-reference.md

@@ -238,6 +238,16 @@ bkper group update "Cash" -b abc123 --hidden true
 bkper group delete "Cash" -b abc123
 ```
 
+### Book setup guidance (important)
+
+When setting up a full Book or starter chart of accounts, prefer a hierarchical group structure by default.
+
+Create top-level groups first, then child groups with `--parent`, then accounts with `--groups`.
+
+Verify the resulting group hierarchy and account memberships before reporting success.
+
+Avoid using the same name for a Group and an Account in the same Book.
+
 <details>
 <summary>Command reference</summary>
 
@@ -448,7 +458,7 @@ CSV is significantly more token-efficient than JSON for tabular data, and for wi
 
 ### Batch Operations & Piping
 
-Write commands (`account create`, `group create`, `transaction create`) accept JSON data piped via stdin for batch operations. The `transaction update` command also accepts stdin for batch updates. The input format follows the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts) exactly -- a single JSON object or an array of objects.
+Write commands (`account create`, `transaction create`) accept JSON data piped via stdin for batch operations. The `transaction update` command also accepts stdin for batch updates. The input format follows the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts) exactly -- a single JSON object or an array of objects.
 
 ```bash
 # Create transactions
@@ -465,15 +475,13 @@ echo '[{
 echo '[{"name":"Cash","type":"ASSET"},{"name":"Revenue","type":"INCOMING"}]' | \
   bkper account create -b abc123
 
-# Create groups
-echo '[{"name":"Fixed Costs","hidden":true}]' | \
-  bkper group create -b abc123
-
 # Pipe from a script
 python export_bank.py | bkper transaction create -b abc123
 ```
 
-The input follows the exact `bkper.Transaction`, `bkper.Account`, or `bkper.Group` type from the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts). Custom properties go inside the `properties` object.
+The input follows the exact `bkper.Transaction` or `bkper.Account` type from the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts). Custom properties go inside the `properties` object.
+
+Groups are created explicitly with `bkper group create --name` and optional `--parent` so hierarchy stays deterministic during setup.
 
 The `--property` CLI flag can override or delete properties from the stdin payload:
 
@@ -491,21 +499,17 @@ bkper account create -b abc123 < accounts.json
 
 **Piping between commands:**
 
-All JSON output is designed to be piped directly as stdin to other commands. The output of any list or batch create command can feed directly into a create or update command:
+For resources that support stdin creation, JSON output can be piped directly into create or update commands:
 
 ```bash
 # Copy all accounts from one book to another
 bkper account list -b $BOOK_A --format json | bkper account create -b $BOOK_B
 
-# Copy all groups from one book to another
-bkper group list -b $BOOK_A --format json | bkper group create -b $BOOK_B
-
 # Copy transactions matching a query
 bkper transaction list -b $BOOK_A -q "after:2025-01-01" --format json | \
   bkper transaction create -b $BOOK_B
 
-# Clone a full chart of accounts: groups, then accounts, then transactions
-bkper group list -b $SOURCE --format json | bkper group create -b $DEST
+# Clone accounts, then transactions
 bkper account list -b $SOURCE --format json | bkper account create -b $DEST
 bkper transaction list -b $SOURCE -q "after:2025-01-01" --format json | \
   bkper transaction create -b $DEST
@@ -555,15 +559,6 @@ Only the fields below are meaningful when creating or updating resources via std
 | `groups`     | `[{"name":"..."}, ...]` | Groups to assign by name or id                     |
 | `properties` | `{"key": "value", ...}` | Custom key/value properties                        |
 
-**Group** (`bkper.Group`)
-
-| Field        | Type                               | Notes                            |
-| ------------ | ---------------------------------- | -------------------------------- |
-| `name`       | `string`                           | Group name (required)            |
-| `hidden`     | `boolean`                          | Hide from transactions main menu |
-| `parent`     | `{"name":"..."}` or `{"id":"..."}` | Parent group for nesting         |
-| `properties` | `{"key": "value", ...}`            | Custom key/value properties      |
-
 </details>
 
 ---

package/lib/{agent/core-concepts.js → docs/core-concepts.md}

@@ -1,6 +1,4 @@
-// AUTO-GENERATED FILE. DO NOT EDIT.
-// Source: https://bkper.com/docs/core-concepts.md
-export const CORE_CONCEPTS_MARKDOWN = `# Core Concepts
+# Core Concepts
 
 Bkper tracks resources — money, inventory, or anything countable — as movements between places. Every financial event is recorded as an amount moving **from** one Account **to** another. This from-to model replaces the traditional language of debits and credits with something intuitive: resources leave one place and arrive at another.
 
@@ -75,46 +73,46 @@ The sum of all credits and debits recorded in a Book always tallies to zero —
 
 These examples show the same movement model in concrete situations. Some match the diagrams on this page. Others add common accrual flows that are easy to confuse.
 
-These examples use Bkper's transaction shorthand \`From >> To\`, meaning the amount leaves the Account on the left and arrives at the Account on the right.
+These examples use Bkper's transaction shorthand `From >> To`, meaning the amount leaves the Account on the left and arrives at the Account on the right.
 
 | Situation | Transaction |
 | --- | --- |
-| Salary received | \`Salary >> Bank Account\` |
-| Investment funded | \`Bank Account >> Investments\` |
-| Dividends received | \`Dividends >> Bank Account\` |
-| Loan received | \`Loan >> Bank Account\` |
-| Rent paid | \`Bank Account >> Rent\` |
-| Transportation bought on credit card | \`Credit Card >> Transportation\` |
+| Salary received | `Salary >> Bank Account` |
+| Investment funded | `Bank Account >> Investments` |
+| Dividends received | `Dividends >> Bank Account` |
+| Loan received | `Loan >> Bank Account` |
+| Rent paid | `Bank Account >> Rent` |
+| Transportation bought on credit card | `Credit Card >> Transportation` |
 
 **Buy on a credit card now, pay it later**
 
 | Step | Transaction |
 | --- | --- |
-| Purchase | \`Credit Card >> Outgoing\` |
-| Payment | \`Bank Account >> Credit Card\` |
+| Purchase | `Credit Card >> Outgoing` |
+| Payment | `Bank Account >> Credit Card` |
 
 **Sell now and receive cash later**
 
 | Step | Transaction |
 | --- | --- |
-| Sale on credit | \`Incoming >> Accounts Receivable\` |
-| Interest added while unpaid | \`Incoming >> Accounts Receivable\` |
-| Collection | \`Accounts Receivable >> Bank Account\` |
+| Sale on credit | `Incoming >> Accounts Receivable` |
+| Interest added while unpaid | `Incoming >> Accounts Receivable` |
+| Collection | `Accounts Receivable >> Bank Account` |
 
 **Receive a supplier bill now and pay it later**
 
 | Step | Transaction |
 | --- | --- |
-| Bill received | \`Accounts Payable >> Outgoing\` |
-| Interest added while unpaid | \`Accounts Payable >> Outgoing\` |
-| Payment | \`Bank Account >> Accounts Payable\` |
+| Bill received | `Accounts Payable >> Outgoing` |
+| Interest added while unpaid | `Accounts Payable >> Outgoing` |
+| Payment | `Bank Account >> Accounts Payable` |
 
 **Receive a loan now and repay principal later**
 
 | Step | Transaction |
 | --- | --- |
-| Loan proceeds | \`Loan >> Bank Account\` |
-| Principal repayment | \`Bank Account >> Loan\` |
+| Loan proceeds | `Loan >> Bank Account` |
+| Principal repayment | `Bank Account >> Loan` |
 
 In each case, the first movement records the position that was created — a receivable or a liability. The later movement settles that position. This keeps Incoming and Outgoing focused on activity, while Asset and Liability Accounts hold positions until they are cleared.
 
@@ -133,11 +131,11 @@ Bkper maintains a continuous ledger with no concept of closing periods — the s
 
 **Custom Properties** are key-value pairs attachable to any entity — Books, Accounts, Groups, Transactions, Collections, and Files. They add context, metadata, and meaning beyond core financial data.
 
-By attaching properties like \`invoice: inv123456\` or \`exc_code: BRL\`, entities become rich with information that can drive automation and reporting — without changing the core model.
+By attaching properties like `invoice: inv123456` or `exc_code: BRL`, entities become rich with information that can drive automation and reporting — without changing the core model.
 
 ## Hashtags
 
-**Hashtags** are lightweight labels on Transactions that enable multi-dimensional tracking. They complement the Account structure by adding dynamic categorization — a single transaction might carry \`#team_marketing #project_alpha #q1_campaign\`, enabling filtering and analysis from any perspective.
+**Hashtags** are lightweight labels on Transactions that enable multi-dimensional tracking. They complement the Account structure by adding dynamic categorization — a single transaction might carry `#team_marketing #project_alpha #q1_campaign`, enabling filtering and analysis from any perspective.
 
 Unlike Account structures, Hashtags can be added or removed as needs evolve, making them ideal for cost allocation, project tracking, and ad-hoc analysis.
 
@@ -152,5 +150,3 @@ Collections can also serve as references for automations (Bots or Apps) that wor
 Every action in a Book — posting a transaction, editing an account, adding a comment — generates an **Event**. Events record _who_ (a user) or _what_ (a bot, an automation) performed the action and _when_, forming a complete audit trail essential for collaboration and trust.
 
 Events are also the foundation of Bkper's automation model. Bots and Agents listen for specific event types and react automatically — for example, calculating taxes when a transaction is posted or converting currencies when one is checked.
-`;
-//# sourceMappingURL=core-concepts.js.map

package/lib/docs-compliance/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/rules.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B;AA4BD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA8E1E"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/rules.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B;AA4BD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAsI1E"}

package/lib/docs-compliance/rules.js

@@ -39,6 +39,24 @@ export function evaluateReadmeCompliance(content) {
             line: getLineNumber(content, periodMatch.index),
         });
     }
+    if (!content.includes('### Book setup guidance (important)')) {
+        errors.push({
+            code: 'missing-book-setup-guidance-title',
+            message: 'Missing `Book setup guidance (important)` section.',
+        });
+    }
+    if (!content.includes('Create top-level groups first, then child groups with `--parent`, then accounts with `--groups`.')) {
+        errors.push({
+            code: 'missing-book-setup-order-guidance',
+            message: 'Missing guidance to create top-level groups first, then child groups, then accounts.',
+        });
+    }
+    if (!content.includes('Verify the resulting group hierarchy and account memberships before reporting success.')) {
+        errors.push({
+            code: 'missing-book-setup-verification-guidance',
+            message: 'Missing guidance to verify hierarchy and account memberships before success.',
+        });
+    }
     if (!content.includes('LLM-first output guidance (important):')) {
         errors.push({
             code: 'missing-llm-guidance-title',
@@ -69,6 +87,25 @@ export function evaluateReadmeCompliance(content) {
             message: 'Missing explicit semantics for `after:` and `before:`.',
         });
     }
+    if (content.includes('Write commands (`account create`, `group create`, `transaction create`) accept JSON data piped via stdin')) {
+        errors.push({
+            code: 'group-create-stdin-documented',
+            message: 'README should not document stdin batch creation for `group create`.',
+        });
+    }
+    const groupPipePattern = /bkper\s+group\s+list\b.*\|\s*bkper\s+group\s+create\b/;
+    if (groupPipePattern.test(content)) {
+        errors.push({
+            code: 'group-create-pipe-documented',
+            message: 'README should not document piping group JSON into `group create`.',
+        });
+    }
+    if (content.includes('**Group** (`bkper.Group`)')) {
+        errors.push({
+            code: 'group-stdin-fields-documented',
+            message: 'README should not document stdin writable fields for `bkper.Group`.',
+        });
+    }
     return { errors };
 }
 //# sourceMappingURL=rules.js.map

package/lib/docs-compliance/rules.js.map

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

package/package.json

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

package/lib/agent/core-concepts.d.ts

@@ -1,2 +0,0 @@
-export declare const CORE_CONCEPTS_MARKDOWN = "# Core Concepts\n\nBkper tracks resources \u2014 money, inventory, or anything countable \u2014 as movements between places. Every financial event is recorded as an amount moving **from** one Account **to** another. This from-to model replaces the traditional language of debits and credits with something intuitive: resources leave one place and arrive at another.\n\nThe system enforces a **zero-sum invariant** \u2014 the total of all records always equals zero. Nothing is created or destroyed, only transferred. This makes Bkper a double-entry bookkeeping system where every transaction automatically produces balanced entries.\n\nFor those familiar with traditional accounting, \"from\" corresponds to credit and \"to\" corresponds to debit \u2014 but the explicit flow eliminates the need to memorize these rules.\n\n## Accounts\n\n**Accounts** are the places where resources reside or flow through. An Account can represent a bank, a category, a customer, a project, or anything else that holds or transfers value. You define what each Account represents and structure them at whatever level of detail suits your needs.\n\nAn Account registers all incoming and outgoing amounts through transactions. The sum of these movements produces the account's **balance** \u2014 the net result of everything that has flowed in and out.\n\n## Account Types\n\nBkper organizes Accounts into four types that determine how an Account behaves and where it appears in your financial structure:\n\n- **Asset** (blue) \u2014 **permanent**. Real resources you own: bank accounts, cash, receivables. Balances carry forward continuously, showing your position at any point in time.\n- **Liability** (yellow) \u2014 **permanent**. Obligations you owe: credit cards, loans, supplier debts. Balances also carry forward continuously.\n- **Incoming** (green) \u2014 **non-permanent**. Revenue sources: salary, sales, interest. Balances track activity within a period and reset to zero for the next one.\n- **Outgoing** (red) \u2014 **non-permanent**. Expenses and costs: rent, supplies, payroll. Balances also track activity within a period.\n\n## Transactions\n\nA **Transaction** is the atomic unit of financial activity. It captures:\n\n- **Date** \u2014 when it happened\n- **Amount** \u2014 how much moved\n- **From Account** \u2014 where the resource came from\n- **To Account** \u2014 where it went\n- **Description** \u2014 what happened\n\nThe from-to model makes every event explicit and traceable.\n\nA transaction is nothing more than moving a resource from one place to another. When you pay a taxi for a ride, the amount that goes from your wallet to the driver represents a transaction.\n\nIf any essential element is missing, the transaction is saved as an incomplete draft.\n\n## Transaction States\n\nTransactions move through a lifecycle with four states:\n\n- **Draft** \u2014 incomplete or unposted. Does not affect balances.\n- **Unchecked** \u2014 posted and updates balances, but remains editable.\n- **Checked** \u2014 reviewed and locked for integrity.\n- **Trashed** \u2014 removed from balances, but recoverable.\n\nThis structure puts a **human in the loop** \u2014 you review and confirm before records become permanent.\n\n## Groups\n\n**Groups** organize Accounts into hierarchies for reporting and analysis. They don't change the underlying data \u2014 they provide structure for understanding it. Groups consolidate account balances, so you can see totals for categories like \"Expenses\" or \"Assets\" at a glance.\n\nGroups support hierarchies (groups of groups) and multiple perspectives \u2014 an Account can belong to different groups in different hierarchies.\n\nGroups inherit the nature of the accounts they contain:\n\n- **Asset-only group** \u2014 behaves as Asset (blue)\n- **Liability-only group** \u2014 behaves as Liability (yellow)\n- **Mixed Asset + Liability** \u2014 shows Equity (gray, net balance)\n- **Incoming-only group** \u2014 behaves as Income (green)\n- **Outgoing-only group** \u2014 behaves as Expense (red)\n- **Mixed Incoming + Outgoing** \u2014 shows Net Result (gray)\n\n## Books\n\nA **Book** is a self-contained ledger \u2014 the complete scope of an entity, whether an individual, a project, or a business. Every Account, Transaction, and Group lives within a Book, and every Book balances to zero. Books can track any countable resource using the same from-to model.\n\nThe sum of all credits and debits recorded in a Book always tallies to zero \u2014 nothing is created or destroyed, only transferred. For more complex entities, multiple Books can be organized into a Collection.\n\n## Example Flows\n\nThese examples show the same movement model in concrete situations. Some match the diagrams on this page. Others add common accrual flows that are easy to confuse.\n\nThese examples use Bkper's transaction shorthand `From >> To`, meaning the amount leaves the Account on the left and arrives at the Account on the right.\n\n| Situation | Transaction |\n| --- | --- |\n| Salary received | `Salary >> Bank Account` |\n| Investment funded | `Bank Account >> Investments` |\n| Dividends received | `Dividends >> Bank Account` |\n| Loan received | `Loan >> Bank Account` |\n| Rent paid | `Bank Account >> Rent` |\n| Transportation bought on credit card | `Credit Card >> Transportation` |\n\n**Buy on a credit card now, pay it later**\n\n| Step | Transaction |\n| --- | --- |\n| Purchase | `Credit Card >> Outgoing` |\n| Payment | `Bank Account >> Credit Card` |\n\n**Sell now and receive cash later**\n\n| Step | Transaction |\n| --- | --- |\n| Sale on credit | `Incoming >> Accounts Receivable` |\n| Interest added while unpaid | `Incoming >> Accounts Receivable` |\n| Collection | `Accounts Receivable >> Bank Account` |\n\n**Receive a supplier bill now and pay it later**\n\n| Step | Transaction |\n| --- | --- |\n| Bill received | `Accounts Payable >> Outgoing` |\n| Interest added while unpaid | `Accounts Payable >> Outgoing` |\n| Payment | `Bank Account >> Accounts Payable` |\n\n**Receive a loan now and repay principal later**\n\n| Step | Transaction |\n| --- | --- |\n| Loan proceeds | `Loan >> Bank Account` |\n| Principal repayment | `Bank Account >> Loan` |\n\nIn each case, the first movement records the position that was created \u2014 a receivable or a liability. The later movement settles that position. This keeps Incoming and Outgoing focused on activity, while Asset and Liability Accounts hold positions until they are cleared.\n\nIf a receivable or payable grows before settlement, record another movement to that same Account, then settle the total later.\n\n## Balances\n\n**Balances** are always calculated from Transactions, never stored independently. The total balance across all Accounts in a Book is always zero. Account type determines how balances behave over time:\n\n- **Permanent Accounts** (Asset & Liability) \u2014 balance **to a date**, showing cumulative position at a point in time.\n- **Non-permanent Accounts** (Incoming & Outgoing) \u2014 balance **within a period**, showing activity during a timeframe.\n\nBkper maintains a continuous ledger with no concept of closing periods \u2014 the same ledger serves all time-based queries automatically.\n\n## Custom Properties\n\n**Custom Properties** are key-value pairs attachable to any entity \u2014 Books, Accounts, Groups, Transactions, Collections, and Files. They add context, metadata, and meaning beyond core financial data.\n\nBy attaching properties like `invoice: inv123456` or `exc_code: BRL`, entities become rich with information that can drive automation and reporting \u2014 without changing the core model.\n\n## Hashtags\n\n**Hashtags** are lightweight labels on Transactions that enable multi-dimensional tracking. They complement the Account structure by adding dynamic categorization \u2014 a single transaction might carry `#team_marketing #project_alpha #q1_campaign`, enabling filtering and analysis from any perspective.\n\nUnlike Account structures, Hashtags can be added or removed as needs evolve, making them ideal for cost allocation, project tracking, and ad-hoc analysis.\n\n## Collections\n\n**Collections** group related Books for organization and consolidated views. Each Book remains self-contained and balanced \u2014 Collections simply provide navigation and structure across multiple Books. You might track resources in multiple currencies, or organize branch offices in one collection.\n\nCollections can also serve as references for automations (Bots or Apps) that work on all Books in the collection.\n\n## Events\n\nEvery action in a Book \u2014 posting a transaction, editing an account, adding a comment \u2014 generates an **Event**. Events record _who_ (a user) or _what_ (a bot, an automation) performed the action and _when_, forming a complete audit trail essential for collaboration and trust.\n\nEvents are also the foundation of Bkper's automation model. Bots and Agents listen for specific event types and react automatically \u2014 for example, calculating taxes when a transaction is posted or converting currencies when one is checked.\n";
-//# sourceMappingURL=core-concepts.d.ts.map

package/lib/agent/core-concepts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"core-concepts.d.ts","sourceRoot":"","sources":["../../src/agent/core-concepts.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,sBAAsB,y7RAwJlC,CAAC"}

package/lib/agent/core-concepts.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"core-concepts.js","sourceRoot":"","sources":["../../src/agent/core-concepts.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,kDAAkD;AAElD,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwJrC,CAAC"}

package/lib/commands/groups/batch-create.d.ts

@@ -1,12 +0,0 @@
-/**
- * Creates multiple groups from stdin items using the batch API.
- * Outputs a flat JSON array of all created groups.
- *
- * Stdin items must follow the bkper.Group format exactly.
- *
- * @param bookId - Target book ID
- * @param items - Parsed stdin items as bkper.Group payloads
- * @param propertyOverrides - CLI --property flags that override stdin properties
- */
-export declare function batchCreateGroups(bookId: string, items: Record<string, unknown>[], propertyOverrides?: string[]): Promise<void>;
-//# sourceMappingURL=batch-create.d.ts.map

package/lib/commands/groups/batch-create.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-create.d.ts","sourceRoot":"","sources":["../../../src/commands/groups/batch-create.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAChC,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/lib/commands/groups/batch-create.js

@@ -1,49 +0,0 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { getBkperInstance } from '../../bkper-factory.js';
-import { Group } from 'bkper-js';
-import { parsePropertyFlag } from '../../utils/properties.js';
-/**
- * Creates multiple groups from stdin items using the batch API.
- * Outputs a flat JSON array of all created groups.
- *
- * Stdin items must follow the bkper.Group format exactly.
- *
- * @param bookId - Target book ID
- * @param items - Parsed stdin items as bkper.Group payloads
- * @param propertyOverrides - CLI --property flags that override stdin properties
- */
-export function batchCreateGroups(bookId, items, propertyOverrides) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const bkper = getBkperInstance();
-        const book = yield bkper.getBook(bookId);
-        const groups = [];
-        for (const item of items) {
-            const group = new Group(book, item);
-            // CLI --property flags override stdin properties
-            if (propertyOverrides) {
-                for (const raw of propertyOverrides) {
-                    const [key, value] = parsePropertyFlag(raw);
-                    if (value === '') {
-                        group.deleteProperty(key);
-                    }
-                    else {
-                        group.setProperty(key, value);
-                    }
-                }
-            }
-            groups.push(group);
-        }
-        const results = yield book.batchCreateGroups(groups);
-        const allResults = results.map(result => result.json());
-        console.log(JSON.stringify(allResults, null, 2));
-    });
-}
-//# sourceMappingURL=batch-create.js.map

package/lib/commands/groups/batch-create.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-create.js","sourceRoot":"","sources":["../../../src/commands/groups/batch-create.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,UAAgB,iBAAiB,CACnC,MAAc,EACd,KAAgC,EAChC,iBAA4B;;QAE5B,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEzC,MAAM,MAAM,GAAY,EAAE,CAAC;QAE3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,IAAmB,CAAC,CAAC;YAEnD,iDAAiD;YACjD,IAAI,iBAAiB,EAAE,CAAC;gBACpB,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;oBAClC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;oBAC5C,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;wBACf,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;oBAC9B,CAAC;yBAAM,CAAC;wBACJ,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;oBAClC,CAAC;gBACL,CAAC;YACL,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAExD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;CAAA"}