bkper 4.10.4 → 4.10.5

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

@@ -1,4 +1,2 @@
-export declare const CORE_CONCEPTS_CANONICAL_URL = "https://bkper.com/docs/core-concepts.md";
-export declare function validateCoreConceptsMarkdown(markdown: string): void;
-export declare function renderCoreConceptsModule(markdown: string): string;
+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 +1 @@
-{"version":3,"file":"core-concepts.d.ts","sourceRoot":"","sources":["../../src/agent/core-concepts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,4CAA4C,CAAC;AASrF,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUnE;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIjE"}
+{"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

@@ -1,22 +1,156 @@
-export const CORE_CONCEPTS_CANONICAL_URL = 'https://bkper.com/docs/core-concepts.md';
-const REQUIRED_CORE_CONCEPTS_HEADINGS = [
-    '# Core Concepts',
-    '## Accounts',
-    '## Transactions',
-    '## Books',
-];
-export function validateCoreConceptsMarkdown(markdown) {
-    if (!markdown.trim()) {
-        throw new Error('Core concepts markdown is empty.');
-    }
-    for (const heading of REQUIRED_CORE_CONCEPTS_HEADINGS) {
-        if (!markdown.includes(heading)) {
-            throw new Error(`Core concepts markdown is missing required heading: ${heading}`);
-        }
-    }
-}
-export function renderCoreConceptsModule(markdown) {
-    validateCoreConceptsMarkdown(markdown);
-    return `// AUTO-GENERATED FILE. DO NOT EDIT.\n// Source: ${CORE_CONCEPTS_CANONICAL_URL}\n\nexport const CORE_CONCEPTS_MARKDOWN = ${JSON.stringify(markdown)};\n`;
-}
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: https://bkper.com/docs/core-concepts.md
+export const CORE_CONCEPTS_MARKDOWN = `# 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.
+
+The system enforces a **zero-sum invariant** — 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.
+
+For those familiar with traditional accounting, "from" corresponds to credit and "to" corresponds to debit — but the explicit flow eliminates the need to memorize these rules.
+
+## Accounts
+
+**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.
+
+An Account registers all incoming and outgoing amounts through transactions. The sum of these movements produces the account's **balance** — the net result of everything that has flowed in and out.
+
+## Account Types
+
+Bkper organizes Accounts into four types that determine how an Account behaves and where it appears in your financial structure:
+
+- **Asset** (blue) — **permanent**. Real resources you own: bank accounts, cash, receivables. Balances carry forward continuously, showing your position at any point in time.
+- **Liability** (yellow) — **permanent**. Obligations you owe: credit cards, loans, supplier debts. Balances also carry forward continuously.
+- **Incoming** (green) — **non-permanent**. Revenue sources: salary, sales, interest. Balances track activity within a period and reset to zero for the next one.
+- **Outgoing** (red) — **non-permanent**. Expenses and costs: rent, supplies, payroll. Balances also track activity within a period.
+
+## Transactions
+
+A **Transaction** is the atomic unit of financial activity. It captures:
+
+- **Date** — when it happened
+- **Amount** — how much moved
+- **From Account** — where the resource came from
+- **To Account** — where it went
+- **Description** — what happened
+
+The from-to model makes every event explicit and traceable.
+
+A 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.
+
+If any essential element is missing, the transaction is saved as an incomplete draft.
+
+## Transaction States
+
+Transactions move through a lifecycle with four states:
+
+- **Draft** — incomplete or unposted. Does not affect balances.
+- **Unchecked** — posted and updates balances, but remains editable.
+- **Checked** — reviewed and locked for integrity.
+- **Trashed** — removed from balances, but recoverable.
+
+This structure puts a **human in the loop** — you review and confirm before records become permanent.
+
+## Groups
+
+**Groups** organize Accounts into hierarchies for reporting and analysis. They don't change the underlying data — they provide structure for understanding it. Groups consolidate account balances, so you can see totals for categories like "Expenses" or "Assets" at a glance.
+
+Groups support hierarchies (groups of groups) and multiple perspectives — an Account can belong to different groups in different hierarchies.
+
+Groups inherit the nature of the accounts they contain:
+
+- **Asset-only group** — behaves as Asset (blue)
+- **Liability-only group** — behaves as Liability (yellow)
+- **Mixed Asset + Liability** — shows Equity (gray, net balance)
+- **Incoming-only group** — behaves as Income (green)
+- **Outgoing-only group** — behaves as Expense (red)
+- **Mixed Incoming + Outgoing** — shows Net Result (gray)
+
+## Books
+
+A **Book** is a self-contained ledger — 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.
+
+The sum of all credits and debits recorded in a Book always tallies to zero — nothing is created or destroyed, only transferred. For more complex entities, multiple Books can be organized into a Collection.
+
+## Example Flows
+
+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.
+
+| 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\` |
+
+**Buy on a credit card now, pay it later**
+
+| Step | Transaction |
+| --- | --- |
+| 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\` |
+
+**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\` |
+
+**Receive a loan now and repay principal later**
+
+| Step | Transaction |
+| --- | --- |
+| 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.
+
+If a receivable or payable grows before settlement, record another movement to that same Account, then settle the total later.
+
+## Balances
+
+**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:
+
+- **Permanent Accounts** (Asset & Liability) — balance **to a date**, showing cumulative position at a point in time.
+- **Non-permanent Accounts** (Incoming & Outgoing) — balance **within a period**, showing activity during a timeframe.
+
+Bkper maintains a continuous ledger with no concept of closing periods — the same ledger serves all time-based queries automatically.
+
+## Custom Properties
+
+**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.
+
+## 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.
+
+Unlike Account structures, Hashtags can be added or removed as needs evolve, making them ideal for cost allocation, project tracking, and ad-hoc analysis.
+
+## Collections
+
+**Collections** group related Books for organization and consolidated views. Each Book remains self-contained and balanced — Collections simply provide navigation and structure across multiple Books. You might track resources in multiple currencies, or organize branch offices in one collection.
+
+Collections can also serve as references for automations (Bots or Apps) that work on all Books in the collection.
+
+## Events
+
+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/agent/core-concepts.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-concepts.js","sourceRoot":"","sources":["../../src/agent/core-concepts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,2BAA2B,GAAG,yCAAyC,CAAC;AAErF,MAAM,+BAA+B,GAAG;IACpC,iBAAiB;IACjB,aAAa;IACb,iBAAiB;IACjB,UAAU;CACJ,CAAC;AAEX,MAAM,UAAU,4BAA4B,CAAC,QAAgB;IACzD,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,+BAA+B,EAAE,CAAC;QACpD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,uDAAuD,OAAO,EAAE,CAAC,CAAC;QACtF,CAAC;IACL,CAAC;AACL,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,QAAgB;IACrD,4BAA4B,CAAC,QAAQ,CAAC,CAAC;IAEvC,OAAO,oDAAoD,2BAA2B,6CAA6C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC;AACrK,CAAC"}
+{"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/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## 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## Next Steps\n\nReady to put these concepts into practice? Start here:\n\n- Create your first Book\n- Accounts guide\n- Transactions guide\n- Groups guide\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# 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";
 //# 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,iwPAYrC,CAAC"}
+{"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"}

package/lib/agent/system-prompt.js

@@ -1,6 +1,6 @@
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { CORE_CONCEPTS_MARKDOWN } from './generated/core-concepts.js';
+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');

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,8BAA8B,CAAC;AAEpE,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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.10.4",
+    "version": "4.10.5",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"
@@ -26,11 +26,10 @@
     ],
     "scripts": {
         "clean": "rm -rf ./lib & rm -rf ./node_modules & wait",
-        "prepare:core-concepts": "bun ./scripts/fetch-core-concepts.ts",
+        "sync:core-concepts": "bun ./scripts/fetch-core-concepts.ts",
         "prebuild": "bun install",
-        "build": "run-s build:clean build:prepare-core-concepts build:compile build:copy-docs",
+        "build": "run-s build:clean build:compile build:copy-docs",
         "build:clean": "gts clean && rimraf temp",
-        "build:prepare-core-concepts": "bun run prepare:core-concepts",
         "build:compile": "tsc",
         "api:platform": "openapi-typescript https://platform.bkper.app/openapi.json -o src/platform/types.d.ts",
         "api:platform:local": "openapi-typescript http://localhost:8790/openapi.json -o src/platform/types.d.ts",
@@ -38,9 +37,9 @@
         "predev": "bun run build",
         "dev": "tsc -w",
         "ports": "devpod ssh ../ -L 6274",
-        "test": "bun run prepare:core-concepts && TS_NODE_PROJECT=tsconfig.test.json mocha",
-        "test:unit": "bun run prepare:core-concepts && TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.json",
-        "test:integration": "bun run prepare:core-concepts && BKPER_API_URL=${BKPER_API_URL:-http://localhost:8081/_ah/api/bkper} TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.integration.json",
+        "test": "TS_NODE_PROJECT=tsconfig.test.json mocha",
+        "test:unit": "TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.json",
+        "test:integration": "BKPER_API_URL=${BKPER_API_URL:-http://localhost:8081/_ah/api/bkper} TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.integration.json",
         "test:deploy": "BKPER_PLATFORM_URL=http://localhost:8790 BKPER_API_URL=https://api-dev.bkper.app TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.deploy.json",
         "test:all": "bun run test:unit && bun run test:integration",
         "docs:compliance": "TS_NODE_PROJECT=tsconfig.test.json node --loader ts-node/esm ./test/tools/docs-compliance/check.ts",

package/lib/agent/generated/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## 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## Next Steps\n\nReady to put these concepts into practice? Start here:\n\n- Create your first Book\n- Accounts guide\n- Transactions guide\n- Groups guide\n";
-//# sourceMappingURL=core-concepts.d.ts.map

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

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

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

@@ -1,4 +0,0 @@
-// AUTO-GENERATED FILE. DO NOT EDIT.
-// Source: https://bkper.com/docs/core-concepts.md
-export const CORE_CONCEPTS_MARKDOWN = "# Core Concepts\n\nBkper 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.\n\nThe system enforces a **zero-sum invariant** — 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 — 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** — 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) — **permanent**. Real resources you own: bank accounts, cash, receivables. Balances carry forward continuously, showing your position at any point in time.\n- **Liability** (yellow) — **permanent**. Obligations you owe: credit cards, loans, supplier debts. Balances also carry forward continuously.\n- **Incoming** (green) — **non-permanent**. Revenue sources: salary, sales, interest. Balances track activity within a period and reset to zero for the next one.\n- **Outgoing** (red) — **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** — when it happened\n- **Amount** — how much moved\n- **From Account** — where the resource came from\n- **To Account** — where it went\n- **Description** — 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** — incomplete or unposted. Does not affect balances.\n- **Unchecked** — posted and updates balances, but remains editable.\n- **Checked** — reviewed and locked for integrity.\n- **Trashed** — removed from balances, but recoverable.\n\nThis structure puts a **human in the loop** — 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 — 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 — 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** — behaves as Asset (blue)\n- **Liability-only group** — behaves as Liability (yellow)\n- **Mixed Asset + Liability** — shows Equity (gray, net balance)\n- **Incoming-only group** — behaves as Income (green)\n- **Outgoing-only group** — behaves as Expense (red)\n- **Mixed Incoming + Outgoing** — shows Net Result (gray)\n\n## Books\n\nA **Book** is a self-contained ledger — 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 — nothing is created or destroyed, only transferred. For more complex entities, multiple Books can be organized into a Collection.\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) — balance **to a date**, showing cumulative position at a point in time.\n- **Non-permanent Accounts** (Incoming & Outgoing) — balance **within a period**, showing activity during a timeframe.\n\nBkper maintains a continuous ledger with no concept of closing periods — 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 — 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 — 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 — 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 — 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 — 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.\n\nEvents 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.\n\n## Next Steps\n\nReady to put these concepts into practice? Start here:\n\n- Create your first Book\n- Accounts guide\n- Transactions guide\n- Groups guide\n";
-//# sourceMappingURL=core-concepts.js.map

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

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