@marcfargas/odoo-skills 0.3.0 → 0.4.1

package/.well-known/skills/index.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://pi-skills.dev/schema/v1/index.json",
+  "name": "@marcfargas/odoo-skills",
+  "description": "Battle-tested Odoo knowledge modules for AI agents — 5,200+ lines validated against Odoo v17 in CI",
+  "skills": [
+    {
+      "name": "odoo",
+      "path": "skills/SKILL.md",
+      "description": "Odoo ERP integration - connect, introspect, and automate your Odoo instance"
+    }
+  ]
+}

package/README.md

@@ -33,6 +33,7 @@ npx @marcfargas/create-odoo-skills my-odoo-skills
 | [introspection](./skills/base/introspection.md) | Discover models and fields dynamically |
 | [properties](./skills/base/properties.md) | Dynamic user-defined fields |
 | [modules](./skills/base/modules.md) | Module lifecycle management |
+| [skill-generation](./skills/base/skill-generation.md) | How to create new skills |
 
 ### Mail System
 
@@ -46,9 +47,12 @@ npx @marcfargas/create-odoo-skills my-odoo-skills
 
 | Module | Required Odoo Modules | What it teaches |
 |--------|----------------------|-----------------|
+| [accounting](./skills/modules/accounting.md) | `account` | Accounting patterns, cash discovery, reconciliation, PnL, validation |
+| [attendance](./skills/modules/attendance.md) | `hr_attendance` | Clock in/out, presence tracking |
+| [contracts](./skills/modules/contracts.md) | `contract` (OCA) | Recurring contracts, billing schedules, revenue projection |
 | [timesheets](./skills/modules/timesheets.md) | `hr_timesheet` | Time tracking on projects |
-| [accounting](./skills/modules/accounting.md) | `account` | Accounting patterns |
-| [mis-builder](./skills/oca/mis-builder.md) | `mis_builder` | OCA financial reports |
+| [mis-builder](./skills/oca/mis-builder.md) | `mis_builder` | OCA financial reports (reading, computing, exporting) |
+| [mis-builder-dev](./skills/oca/mis-builder-dev.md) | `mis_builder` | OCA financial reports (creating, editing, expression language) |
 
 ## Prerequisites
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@marcfargas/odoo-skills",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Battle-tested Odoo knowledge modules for AI agents — 5,200+ lines validated against Odoo v17 in CI",
   "files": [
     "skills",
+    ".well-known",
     "LICENSE",
     "README.md"
   ],

package/skills/SKILL.md

@@ -36,6 +36,7 @@ Domain-specific helpers are accessed via lazy getters on the client:
 |----------|-------------|-----------|
 | `client.mail.*` | Post notes & messages on chatter | `mail/chatter.md` |
 | `client.modules.*` | Install, uninstall, check modules | `base/modules.md` |
+| `client.accounting.*` | Cash discovery, reconciliation, partner resolution | `modules/accounting.md` |
 | `client.attendance.*` | Clock in/out, presence tracking | `modules/attendance.md` |
 | `client.timesheets.*` | Timer start/stop, time logging | `modules/timesheets.md` |
 
@@ -90,7 +91,8 @@ Load by reading the path shown below:
 
 | Skill | Path | Required Modules | Description |
 |-------|------|------------------|-------------|
-| accounting | `modules/accounting.md` | `account` | Accounting patterns, cashflow, reconciliation, bank statements |
+| accounting | `modules/accounting.md` | `account` | Accounting patterns, cashflow, reconciliation, PnL, validation |
+| contracts | `modules/contracts.md` | `contract` (OCA) | Recurring contracts, billing schedules, revenue projection |
 | attendance | `modules/attendance.md` | `hr_attendance` | Clock in/out, presence tracking (`client.attendance.*`) |
 | timesheets | `modules/timesheets.md` | `hr_timesheet` | Timer start/stop, time logging on projects (`client.timesheets.*`) |
 | mis-builder | `oca/mis-builder.md` | `mis_builder`, `date_range`, `report_xlsx` | MIS Builder — reading, computing, exporting reports |

package/skills/modules/accounting.md

@@ -4,6 +4,8 @@ Hard-won knowledge from building accounting dashboards and cashflow tools agains
 
 **Required modules**: `account` (Invoicing/Accounting)
 
+**Optional modules**: `account_loan` (loan management), `contract` (recurring contracts — see `contracts.md`)
+
 ## Critical API Gotchas
 
 ### searchRead Default Limit is 100
@@ -68,6 +70,86 @@ const lines = await client.searchRead('account.loan.line',
 );
 ```
 
+## Account Move Fundamentals
+
+### Move Types
+
+`account.move` uses `move_type` to distinguish document types:
+
+| `move_type` | Description |
+|-------------|-------------|
+| `out_invoice` | Customer invoice |
+| `out_refund` | Customer credit note |
+| `in_invoice` | Supplier invoice |
+| `in_refund` | Supplier credit note |
+| `entry` | General journal entry (payroll, depreciation, closing, adjustments, bank statements) |
+
+### Always Filter Posted State
+
+Draft and cancelled entries must be excluded from all financial analysis. **This is the single most common mistake.**
+
+```typescript
+// ✅ On account.move — filter by state
+const moves = await client.searchRead('account.move',
+  [['state', '=', 'posted'], ['date', '>=', '2025-01-01']],
+  { fields: ['name', 'date', 'amount_total'], limit: 0 }
+);
+
+// ✅ On account.move.line — filter by parent_state
+const lines = await client.searchRead('account.move.line',
+  [['parent_state', '=', 'posted'], ['date', '>=', '2025-01-01']],
+  { fields: ['account_id', 'debit', 'credit', 'balance'], limit: 0 }
+);
+```
+
+### Sign Convention for PnL Analysis
+
+`balance = debit - credit` uses natural debit sign. For PnL analysis this is counterintuitive because income accounts (7xx, credit balances) appear negative.
+
+```typescript
+// ✅ Invert sign for PnL: income → positive, expenses → negative
+// Then SUM naturally gives EBITDA / operating result
+const pnlLines = lines.map(l => ({
+  ...l,
+  pnl_amount: -(l.debit - l.credit),  // or equivalently: l.credit - l.debit
+}));
+
+// SUM(pnl_amount) where account 7xx → positive (income)
+// SUM(pnl_amount) where account 6xx → negative (expenses)
+// Total SUM → operating result
+```
+
+### amount_untaxed vs balance Aggregation
+
+Two valid approaches — pick one, never mix:
+
+| Approach | Source | Use for |
+|----------|--------|---------|
+| `account.move.amount_untaxed` | Invoice header | Invoice-level analysis, quick totals |
+| `SUM(account.move.line.balance)` on 6xx/7xx | Journal items | Per-line, per-partner, per-account granularity |
+
+### Detecting Year-End Closing Entries
+
+`move_type='entry'` includes operational entries (payroll, depreciation) AND year-end closing entries. Closing entries distort operational PnL.
+
+```typescript
+// Detect closing entries: any sibling line on account 129x (resultado del ejercicio)
+async function isClosingEntry(client: OdooClient, moveId: number): Promise<boolean> {
+  const lines = await client.searchRead('account.move.line',
+    [['move_id', '=', moveId]],
+    { fields: ['account_id'], limit: 0 }
+  );
+  return lines.some(l => {
+    const code = Array.isArray(l.account_id) ? l.account_id[1] : String(l.account_id);
+    return /^129/.test(code);
+  });
+}
+
+// When querying PnL, exclude closing entries
+// Option 1: Pre-filter move IDs
+// Option 2: Exclude account 129x lines and check remaining moves
+```
+
 ## Cash Account Discovery
 
 ### Use Journals, Not Account Code Prefixes
@@ -86,6 +168,37 @@ const cashAccountIds = journals
   .filter(Boolean);
 ```
 
+### Exclude Transit and Third-Party Accounts
+
+Not everything in bank journals is your money:
+
+| Account | Description | Include in cash? |
+|---------|-------------|------------------|
+| 57x | Bank/cash accounts | ✅ Yes |
+| 5201x | Credit line drawdowns | ✅ Yes — drawn credit is liquid |
+| 5200x | Short-term loan reclassifications | ❌ No — accounting reclassification, not cash |
+| 555 | Transient / pending application | ❌ No — not the company's money |
+| 561 | Client provisions (suplidos) | ❌ No — third-party funds held temporarily |
+
+### Cash Balance from GL, Not from Movements
+
+Summing cash movements within a date range misses prior history and opening balances. True cash balance = cumulative GL balance:
+
+```typescript
+// ✅ CORRECT: Cash balance at a point in time from GL
+const cashBalance = await client.searchRead('account.move.line',
+  [
+    ['account_id', 'in', cashAccountIds],
+    ['parent_state', '=', 'posted'],
+    ['date', '<=', '2025-06-30'],
+  ],
+  { fields: ['balance'], limit: 0 }
+);
+const totalCash = cashBalance.reduce((sum, l) => sum + l.balance, 0);
+
+// ❌ WRONG: Only summing movements in a period misses opening balance
+```
+
 ## Bank Statement Patterns
 
 ### Partner Is on the Counterpart Line, Not the Bank Line
@@ -160,6 +273,47 @@ if (reconcileId) {
 }
 ```
 
+### Days-to-Pay Calculation
+
+Use `full_reconcile_id` to calculate how long an invoice takes to get paid:
+
+```typescript
+async function calculateDaysToPay(
+  client: OdooClient, invoiceId: number
+): Promise<number | null> {
+  // Get receivable/payable lines from the invoice
+  const invoiceLines = await client.searchRead('account.move.line',
+    [
+      ['move_id', '=', invoiceId],
+      ['full_reconcile_id', '!=', false],
+      ['account_id.account_type', 'in', ['asset_receivable', 'liability_payable']],
+    ],
+    { fields: ['full_reconcile_id', 'date'], limit: 0 }
+  );
+  if (!invoiceLines.length) return null;
+
+  const reconcileId = Array.isArray(invoiceLines[0].full_reconcile_id)
+    ? invoiceLines[0].full_reconcile_id[0]
+    : invoiceLines[0].full_reconcile_id;
+  const invoiceDate = invoiceLines[0].date;
+
+  // Find all lines in the reconciliation group — the latest date is the payment
+  const allReconLines = await client.searchRead('account.move.line',
+    [['full_reconcile_id', '=', reconcileId]],
+    { fields: ['date'], limit: 0 }
+  );
+
+  const paymentDate = allReconLines.reduce((max, l) =>
+    l.date > max ? l.date : max, allReconLines[0].date
+  );
+
+  const msPerDay = 86_400_000;
+  return Math.round(
+    (new Date(paymentDate).getTime() - new Date(invoiceDate).getTime()) / msPerDay
+  );
+}
+```
+
 ## Loan Accounting
 
 ### Loan Moves Don't Touch Cash
@@ -169,6 +323,42 @@ if (reconcileId) {
 - Use `account.loan` for: outstanding balances, payment schedules, projections
 - Do NOT use for: cashflow classification (the actual cash movement is a separate bank entry)
 
+### Bank Loans vs Tax Deferrals
+
+The `account.loan` module handles both bank loans and tax payment deferrals. Distinguish by the short-term account:
+
+| `short_term_loan_account_id` | Type | Cashflow Category |
+|-------------------------------|------|-------------------|
+| 475x (Hacienda Pública) | Tax deferral (APLAZ) | Operating — tax payments |
+| 520x / 170x (Deudas) | Bank loan | Financing — debt repayment |
+
+```typescript
+const loans = await client.searchRead('account.loan',
+  [],
+  { fields: ['name', 'short_term_loan_account_id', 'long_term_loan_account_id'], limit: 0 }
+);
+
+for (const loan of loans) {
+  const stAccount = Array.isArray(loan.short_term_loan_account_id)
+    ? loan.short_term_loan_account_id[1] : '';
+  const isBank = /^(520|170)/.test(stAccount);
+  const isTaxDeferral = /^475/.test(stAccount);
+  console.log(`${loan.name}: ${isBank ? 'BANK LOAN' : isTaxDeferral ? 'TAX DEFERRAL' : 'OTHER'}`);
+}
+```
+
+### Loan Lines Link to Accounting Entries
+
+Each `account.loan.line` has a `move_ids` field linking to the journal entries it generated. Use this to tag bank movements as loan repayments:
+
+```typescript
+const loanLines = await client.searchRead('account.loan.line',
+  [['loan_id', '=', loanId], ['move_ids', '!=', false]],
+  { fields: ['date', 'payment_amount', 'move_ids'], limit: 0 }
+);
+// move_ids links to account.move records — these are the loan accounting entries
+```
+
 ### Loan Repayments Go Through Payables
 
 Loan payments typically flow: 520/170 → 410/411 → bank. Look for patterns in the move reference:
@@ -191,8 +381,140 @@ const isLoanRepayment = loanPattern.test(line.name || '') || loanPattern.test(li
 | 555 | Transient/pending | Not the company's money |
 | 57x | Bank/cash | Discover via journals, not code prefix |
 
+## PnL & Cash Flow Structure (Spanish GAAP / PGC)
+
+### Account Code Ranges
+
+Spanish Plan General Contable maps 3-digit prefixes to PnL categories:
+
+| Range | Category | Examples |
+|-------|----------|----------|
+| 600-609 | Purchases / COGS | 600 Compras mercaderías, 607 Subcontratas |
+| 620-629 | External services | 621 Arrendamientos, 623 Servicios profesionales |
+| 630-639 | Taxes | 631 Otros tributos |
+| 640-649 | Personnel costs | 640 Sueldos y salarios, 642 SS empresa |
+| 650-659 | Other operating expenses | |
+| 660-669 | Financial expenses | 662 Intereses deudas, 663 Pérdidas valores |
+| 680-689 | Depreciation / amortization | 681 Amortización inmovilizado |
+| 690-699 | Provisions | |
+| 700-709 | Sales | 700 Ventas, 705 Prestaciones servicios |
+| 740-749 | Subsidies / grants | |
+| 760-769 | Financial income | 763 Beneficios valores |
+| 790-797 | Provision reversals | |
+
+### Non-Cash Items
+
+These accounts represent non-cash movements — exclude from cashflow analysis:
+
+- **680-689**: Depreciation / amortization
+- **690-699**: Provisions (dotaciones)
+- **790-797**: Provision reversals
+- **663/763**: Fair value gains/losses on financial instruments
+
+### Cash Flow Statement (EFE) Sections
+
+Per PGC, the Estado de Flujos de Efectivo has three sections:
+
+| Section | Description | Typical Accounts |
+|---------|-------------|------------------|
+| Explotación | Operating activities | 6xx/7xx (PnL) + working capital changes (430, 410, 475) |
+| Inversión | Investing activities | 2xx (fixed assets), 25x (financial investments) |
+| Financiación | Financing activities | 17x/52x (debt), 1x (equity) |
+
+Working capital changes (movement in receivables, payables, tax accounts) go under Operating.
+
+## Validation Patterns for Financial Data
+
+### Total Invariance
+
+When reclassifying, splitting, or transforming financial amounts, the total must NEVER change:
+
+```typescript
+function validateTotalInvariance(
+  before: number[], after: number[], tolerance = 0.01
+): void {
+  const sumBefore = before.reduce((a, b) => a + b, 0);
+  const sumAfter = after.reduce((a, b) => a + b, 0);
+  if (Math.abs(sumBefore - sumAfter) > tolerance) {
+    throw new Error(
+      `Total invariance violated: before=${sumBefore.toFixed(2)}, after=${sumAfter.toFixed(2)}, ` +
+      `diff=${(sumAfter - sumBefore).toFixed(2)}`
+    );
+  }
+}
+```
+
+### Floating-Point Tolerance
+
+Rounding differences are inevitable in accounting. Use €0.01 tolerance:
+
+```typescript
+// ✅ Accounting equality check
+const isEqual = (a: number, b: number) => Math.abs(a - b) <= 0.01;
+
+// ❌ Never use strict equality for monetary amounts
+// if (total === expected) { ... }
+```
+
+### Strict Mode: Fail on Bad Data
+
+Don't continue processing with validation errors. Log, save, and throw:
+
+```typescript
+if (!isEqual(computedTotal, expectedTotal)) {
+  console.error(`Validation failed: computed=${computedTotal}, expected=${expectedTotal}`);
+  // Save partial results for debugging, then throw
+  throw new Error('Financial validation failed — see logs');
+}
+```
+
+## Service Accessor (`client.accounting.*`)
+
+Most patterns in this document are available as programmatic helpers via the accounting service:
+
+```typescript
+import { createClient } from '@marcfargas/odoo-client';
+const client = await createClient();
+
+// Cash account discovery
+const cashAccounts = await client.accounting.discoverCashAccounts();
+const cashIds = await client.accounting.getCashAccountIds();
+
+// Cash balance from GL (not movements)
+const balance = await client.accounting.getCashBalance(cashIds, '2025-06-30');
+
+// Partner resolution from bank statement counterparts
+const partner = await client.accounting.resolvePartnerFromMove(moveId, cashIds);
+if (partner.isBatchPayment) {
+  console.log('Batch payment to:', partner.allPartnerIds);
+}
+
+// Reconciliation tracing
+const trace = await client.accounting.traceReconciliation(fullReconcileId);
+
+// Closing entry detection
+if (await client.accounting.isClosingEntry(moveId)) { /* skip */ }
+
+// Days-to-pay calculation
+const result = await client.accounting.calculateDaysToPay(invoiceId);
+if (result) console.log(`Paid in ${result.days} days`);
+
+// Query posted move lines (parent_state='posted' auto-applied, limit defaults to all)
+const pnlLines = await client.accounting.getPostedMoveLines(
+  [['account_id.code', '=like', '7%'], ['date', '>=', '2025-01-01']],
+  { fields: ['account_id', 'debit', 'credit', 'balance'] }
+);
+```
+
+Standalone functions are also exported for advanced composition:
+
+```typescript
+import { discoverCashAccounts, getPostedMoveLines } from '@marcfargas/odoo-client';
+```
+
 ## Related Documents
 
 - [connection.md](../base/connection.md) - Authentication
+- [contracts.md](./contracts.md) - Recurring contracts and billing
 - [domains.md](../base/domains.md) - Query filters (especially date ranges, dot notation)
 - [search.md](../base/search.md) - Search patterns

package/skills/modules/contracts.md

@@ -0,0 +1,180 @@
+# OCA Contracts — Recurring Invoicing
+
+Patterns for working with the OCA `contract` module for recurring billing, revenue projection, and subscription-style invoicing.
+
+**Required modules**: `contract` (from [OCA/contract](https://github.com/OCA/contract))
+
+## Key Models
+
+| Model | Description |
+|-------|-------------|
+| `contract.contract` | Contract header — partner, journal, billing schedule |
+| `contract.line` | Individual contract lines — product, price, recurrence |
+
+## Reading Contracts
+
+### Include Archived/Ended Contracts
+
+Ended and cancelled contracts are archived (`active=False`). Use `active_test: false` to see them:
+
+```typescript
+// ✅ All contracts, including ended/cancelled
+const contracts = await client.searchRead('contract.contract',
+  [],
+  {
+    fields: [
+      'name', 'partner_id', 'active', 'recurring_next_date',
+      'date_start', 'date_end', 'contract_line_ids',
+    ],
+    context: { active_test: false },
+    limit: 0,
+  }
+);
+```
+
+### Reading Contract Lines
+
+```typescript
+const lines = await client.searchRead('contract.line',
+  [['contract_id', '=', contractId]],
+  {
+    fields: [
+      'name', 'product_id', 'quantity', 'price_unit', 'price_subtotal',
+      'recurring_rule_type', 'recurring_interval', 'recurring_next_date',
+      'date_start', 'date_end', 'is_canceled',
+    ],
+    limit: 0,
+  }
+);
+```
+
+## Billing Schedule
+
+### Recurrence Fields
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `recurring_rule_type` | `daily`, `weekly`, `monthly`, `monthlylastday`, `quarterly`, `semesterly`, `yearly` | Billing frequency unit |
+| `recurring_interval` | integer | How many units between billings |
+| `recurring_next_date` | date | Next scheduled billing date |
+
+### Price Is Per Billing Cycle, NOT Monthly
+
+**Critical**: `contract.line.price_subtotal` is the amount per billing event. A yearly contract billed annually has ONE payment for the full amount — not twelve monthly portions.
+
+```typescript
+// ❌ WRONG — dividing yearly price by 12 gives wrong monthly amount
+//    if the contract actually bills once a year
+const monthlyRevenue = line.price_subtotal / 12;
+
+// ✅ CORRECT — respect the billing schedule
+const billingCycleDays = {
+  daily: 1 * line.recurring_interval,
+  weekly: 7 * line.recurring_interval,
+  monthly: 30 * line.recurring_interval,
+  quarterly: 90 * line.recurring_interval,
+  semesterly: 180 * line.recurring_interval,
+  yearly: 365 * line.recurring_interval,
+};
+
+const cycleDays = billingCycleDays[line.recurring_rule_type] ?? 30;
+const dailyRate = line.price_subtotal / cycleDays;
+```
+
+## Revenue Projection
+
+### Event-Based Projection
+
+Generate one billing event per contract line per billing date. This matches how Odoo actually generates invoices:
+
+```typescript
+interface BillingEvent {
+  contractId: number;
+  lineId: number;
+  date: string;
+  amount: number;
+  partnerId: number;
+}
+
+function projectBillingEvents(
+  line: any,
+  contract: any,
+  fromDate: string,
+  toDate: string,
+): BillingEvent[] {
+  const events: BillingEvent[] = [];
+  let nextDate = new Date(line.recurring_next_date || fromDate);
+  const end = new Date(toDate);
+  const contractEnd = line.date_end ? new Date(line.date_end) : null;
+
+  while (nextDate <= end) {
+    if (contractEnd && nextDate > contractEnd) break;
+    if (nextDate >= new Date(fromDate)) {
+      events.push({
+        contractId: Array.isArray(contract.id) ? contract.id[0] : contract.id,
+        lineId: line.id,
+        date: nextDate.toISOString().slice(0, 10),
+        amount: line.price_subtotal,
+        partnerId: Array.isArray(contract.partner_id)
+          ? contract.partner_id[0] : contract.partner_id,
+      });
+    }
+
+    // Advance by recurring_interval × recurring_rule_type
+    switch (line.recurring_rule_type) {
+      case 'daily':
+        nextDate.setDate(nextDate.getDate() + line.recurring_interval);
+        break;
+      case 'weekly':
+        nextDate.setDate(nextDate.getDate() + 7 * line.recurring_interval);
+        break;
+      case 'monthly':
+      case 'monthlylastday':
+        nextDate.setMonth(nextDate.getMonth() + line.recurring_interval);
+        break;
+      case 'quarterly':
+        nextDate.setMonth(nextDate.getMonth() + 3 * line.recurring_interval);
+        break;
+      case 'semesterly':
+        nextDate.setMonth(nextDate.getMonth() + 6 * line.recurring_interval);
+        break;
+      case 'yearly':
+        nextDate.setFullYear(nextDate.getFullYear() + line.recurring_interval);
+        break;
+      default:
+        nextDate.setMonth(nextDate.getMonth() + line.recurring_interval);
+    }
+  }
+
+  return events;
+}
+```
+
+### `recurring_next_date` Can Be Far in the Future
+
+The contract module can pre-generate invoices ahead of schedule. When computing reference dates or filtering, don't use `MAX(recurring_next_date)` without a reasonable cap:
+
+```typescript
+// ❌ Dangerous — could be years ahead
+const maxDate = contracts.reduce((max, c) =>
+  c.recurring_next_date > max ? c.recurring_next_date : max, '');
+
+// ✅ Cap to a reasonable horizon
+const horizon = new Date();
+horizon.setFullYear(horizon.getFullYear() + 1);
+const maxDate = horizon.toISOString().slice(0, 10);
+```
+
+## Common Account Patterns
+
+| Account Range | Typical Contract Use |
+|---------------|---------------------|
+| 700 | Sales of goods (product contracts) |
+| 705 | Service revenue (service contracts) |
+| 759 | Other operating income |
+
+## Related Documents
+
+- [accounting.md](./accounting.md) - Accounting patterns, cashflow, reconciliation
+- [../base/domains.md](../base/domains.md) - Query filter syntax
+- [../base/search.md](../base/search.md) - Search patterns

package/skills/oca/mis-builder.md

@@ -299,6 +299,67 @@ These templates use Spanish PGCE 2008 account codes (7XX for income, 6XX for exp
 | `currency_id` | many2one | No | Target currency |
 | `landscape_pdf` | boolean | No | PDF orientation |
 
+## Gotchas
+
+### Archived Budgets Need `active_test: false`
+
+MIS budgets (`mis.budget`) are often archived after the period ends. Without the context flag, they become invisible — easy to miss because "it worked last month."
+
+```typescript
+// ✅ Include archived budgets
+const budgets = await client.searchRead('mis.budget',
+  [],
+  { fields: ['name', 'active'], context: { active_test: false }, limit: 0 }
+);
+```
+
+### `mis.report.instance` Has NO `active` Field
+
+Don't filter by `active` — the field doesn't exist and will cause an error:
+
+```typescript
+// ❌ WRONG — will error
+const instances = await client.searchRead('mis.report.instance',
+  [['active', '=', true]], { fields: ['name'] }
+);
+
+// ✅ CORRECT — no active field, just query directly
+const instances = await client.searchRead('mis.report.instance',
+  [], { fields: ['name'] }
+);
+```
+
+### `mis.report.instance.period` Has NO `company_id` Field
+
+Company filtering is on the **instance** (`mis.report.instance`), not on individual periods. Don't try to filter periods by company.
+
+```typescript
+// ❌ WRONG — company_id doesn't exist on periods
+const periods = await client.searchRead('mis.report.instance.period',
+  [['company_id', '=', 1]], { fields: ['name'] }
+);
+
+// ✅ CORRECT — filter at the instance level
+const instances = await client.searchRead('mis.report.instance',
+  [['company_id', '=', 1]],
+  { fields: ['name', 'period_ids'] }
+);
+```
+
+### Budget Account Codes Differ from Actual Accounting
+
+Budgets often use different account codes than the general ledger. Example: a person budgeted as "employee" (account 640) but actually paid as "subcontractor" (account 607).
+
+**Solution**: Build an explicit equivalence table mapping budget codes to actual codes. Always adjust the budget side — the actual accounting entries are correct.
+
+```typescript
+// Equivalence table: budget code → actual code(s)
+const budgetEquivalences: Record<string, string[]> = {
+  '640': ['640', '607'],  // Budget "employees" includes some subcontractors
+  '621': ['621', '622'],  // Budget "leases" includes both rent types
+};
+```
+
 ## Error Handling
 
 ```typescript