@marcfargas/odoo-skills 0.2.0 → 0.4.0

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,6 +1,6 @@
 {
   "name": "@marcfargas/odoo-skills",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Battle-tested Odoo knowledge modules for AI agents — 5,200+ lines validated against Odoo v17 in CI",
   "files": [
     "skills",

package/skills/SKILL.md

@@ -36,6 +36,9 @@ 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` |
 
 Core CRUD (`searchRead`, `create`, `write`, `unlink`, etc.) stays directly on `client`.
 
@@ -88,8 +91,10 @@ Load by reading the path shown below:
 
 | Skill | Path | Required Modules | Description |
 |-------|------|------------------|-------------|
-| accounting | `modules/accounting.md` | `account` | Accounting patterns, cashflow, reconciliation, bank statements |
-| timesheets | `modules/timesheets.md` | `hr_timesheet` | Track employee time on projects and tasks |
+| 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 |
 | mis-builder-dev | `oca/mis-builder-dev.md` | `mis_builder`, `date_range`, `report_xlsx` | MIS Builder — creating & editing report templates, expression language, styling |
 

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/attendance.md

@@ -0,0 +1,185 @@
+# Attendance (hr_attendance)
+
+Track employee presence with clock-in/clock-out using Odoo's attendance system.
+
+## Overview
+
+The `hr_attendance` module tracks when employees are physically present (in the office, on-site, etc.). Each attendance record has a `check_in` time and optionally a `check_out` time. Odoo enforces that an employee can only have one open (no `check_out`) attendance at a time.
+
+## Prerequisites
+
+- Authenticated OdooClient connection
+- Module: **hr_attendance** (must be installed)
+- Depends on: **hr**
+
+## Key Models
+
+| Model | Description |
+|-------|-------------|
+| `hr.attendance` | Attendance records (clock in/out) |
+| `hr.employee` | Employees who clock in/out |
+
+## Service Accessor
+
+Access attendance operations via `client.attendance`:
+
+```typescript
+const client = await createClient();
+
+// Clock in
+const record = await client.attendance.clockIn();
+
+// Check status
+const status = await client.attendance.getStatus();
+
+// Clock out
+const closed = await client.attendance.clockOut();
+```
+
+All methods accept an optional `employeeId` parameter. When omitted, the current user's linked `hr.employee` record is used automatically.
+
+## Field Reference
+
+### hr.attendance
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `employee_id` | Many2one → hr.employee | Yes | Employee who is present |
+| `check_in` | Datetime | Yes | When the employee clocked in |
+| `check_out` | Datetime | No | When the employee clocked out (false = still present) |
+| `worked_hours` | Float | Computed | Hours between check_in and check_out |
+
+## Checking Module Installation
+
+```typescript testable id="attendance-check-module" needs="client" expect="result.installed === true"
+const installed = await client.modules.isModuleInstalled('hr_attendance');
+return { installed };
+```
+
+## Clock In
+
+```typescript testable id="attendance-clock-in" needs="client" creates="hr.attendance" expect="result.success === true"
+// Clock in (uses current user's employee)
+const record = await client.attendance.clockIn();
+trackRecord('hr.attendance', record.id);
+
+// Check the record
+const checkInTime = record.check_in;  // UTC datetime string
+const isOpen = !record.check_out;     // true — still clocked in
+
+// Clock out to clean up
+await client.attendance.clockOut();
+
+return {
+  success: true,
+  attendanceId: record.id,
+  checkIn: checkInTime,
+  wasOpen: isOpen
+};
+```
+
+## Clock Out
+
+```typescript testable id="attendance-clock-out" needs="client" creates="hr.attendance" expect="result.success === true"
+// Must be clocked in first
+await client.attendance.clockIn();
+
+// Clock out
+const record = await client.attendance.clockOut();
+trackRecord('hr.attendance', record.id);
+
+return {
+  success: true,
+  attendanceId: record.id,
+  checkIn: record.check_in,
+  checkOut: record.check_out,
+  workedHours: record.worked_hours
+};
+```
+
+## Check Status
+
+```typescript testable id="attendance-status" needs="client" expect="result.success === true"
+const status = await client.attendance.getStatus();
+
+if (status.checkedIn) {
+  const att = status.currentAttendance!;
+  // Employee is in the office since att.check_in
+} else {
+  // Employee is not in the office
+}
+
+return {
+  success: true,
+  checkedIn: status.checkedIn,
+  employeeName: status.employee[1]
+};
+```
+
+## List Attendance Records
+
+```typescript testable id="attendance-list" needs="client" expect="result.success === true"
+const today = new Date().toISOString().split('T')[0];
+
+const records = await client.attendance.list({
+  dateFrom: today,
+  dateTo: today,
+  limit: 20,
+});
+
+const totalHours = records.reduce((sum, r) => sum + (r.worked_hours || 0), 0);
+
+return {
+  success: true,
+  count: records.length,
+  totalHours
+};
+```
+
+### Filter by Employee
+
+```typescript
+// Get attendance for a specific employee
+const records = await client.attendance.list({
+  employeeId: 42,
+  dateFrom: '2026-02-01',
+  dateTo: '2026-02-28',
+});
+```
+
+## Standalone Functions
+
+For advanced composition, standalone functions are also exported:
+
+```typescript
+import { clockIn, clockOut, getStatus, listAttendances } from '@marcfargas/odoo-client';
+
+const record = await clockIn(client, employeeId);
+const closed = await clockOut(client, employeeId);
+const status = await getStatus(client, employeeId);
+const list = await listAttendances(client, { employeeId: 42, limit: 10 });
+```
+
+## Important Notes
+
+### One Open Attendance Per Employee
+
+Odoo enforces via `_check_validity` constraint that an employee can only have **one open attendance** (no `check_out`) at a time. Attempting to clock in when already clocked in will throw an `OdooValidationError`.
+
+### Employee ↔ User Relationship
+
+- `employee_id` links to `hr.employee`
+- Each employee has a `user_id` linking to `res.users`
+- The service auto-resolves the current user's employee when `employeeId` is omitted
+
+### Datetime Handling
+
+- `check_in` and `check_out` are stored in **UTC** as `YYYY-MM-DD HH:MM:SS`
+- Odoo applies the user's timezone for display in the UI
+- `worked_hours` is computed as `(check_out - check_in)` in hours
+
+## Related Documents
+
+- [timesheets.md](./timesheets.md) — Time tracking on projects (different from attendance)
+- [../base/crud.md](../base/crud.md) — CRUD operations
+- [../base/modules.md](../base/modules.md) — Module management

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/modules/timesheets.md

@@ -6,6 +6,10 @@ Track employee time on projects and tasks using Odoo's timesheet system.
 
 The `hr_timesheet` module allows employees to log time spent on projects and tasks. Time entries are stored in `account.analytic.line` with project/task context.
 
+Two workflows:
+1. **Timer-based**: Start a timer → work → stop the timer (duration auto-computed)
+2. **Manual**: Log completed work with known hours
+
 ## Prerequisites
 
 - Authenticated OdooClient connection
@@ -21,6 +25,39 @@ The `hr_timesheet` module allows employees to log time spent on projects and tas
 | `project.task` | Tasks within projects |
 | `hr.employee` | Employees who log time |
 
+## Service Accessor
+
+Access timesheet operations via `client.timesheets`:
+
+```typescript
+const client = await createClient();
+
+// Timer workflow
+const entry = await client.timesheets.startTimer({
+  description: 'Feature development',
+  projectId: 5,
+  taskId: 42,
+});
+// ... work ...
+const stopped = await client.timesheets.stopTimer(entry.id);
+console.log(`Logged ${stopped.unit_amount.toFixed(2)} hours`);
+
+// Manual logging
+await client.timesheets.logTime({
+  description: 'Code review',
+  projectId: 5,
+  hours: 1.5,
+});
+
+// Check running timers (entries with unit_amount = 0)
+const running = await client.timesheets.getRunningTimers();
+
+// List entries
+const entries = await client.timesheets.list({ projectId: 5 });
+```
+
+All methods accept an optional `employeeId`. When omitted, the current user's linked `hr.employee` record is used automatically.
+
 ## Field Reference
 
 ### account.analytic.line (Timesheet Entry)
@@ -36,6 +73,7 @@ The `hr_timesheet` module allows employees to log time spent on projects and tas
 | `company_id` | Many2one → res.company | Yes | Company (defaults to current) |
 | `amount` | Monetary | Yes | Cost amount (auto-calculated from hourly cost) |
 | `user_id` | Many2one → res.users | No | Related user |
+| `create_date` | Datetime | Auto | Record creation time (used to compute elapsed time for timers) |
 
 ## Checking Module Installation
 
@@ -362,8 +400,151 @@ The `amount` field is calculated based on:
 - `unit_amount` (hours) x employee's `hourly_cost`
 - Set hourly cost on `hr.employee.hourly_cost`
 
+## Timer Operations (via service accessor)
+
+### Start a Timer
+
+```typescript testable id="timesheets-start-timer" needs="client" creates="account.analytic.line" expect="result.success === true"
+// Find a project with timesheets enabled
+const [project] = await client.searchRead('project.project', [
+  ['allow_timesheets', '=', true]
+], { fields: ['id', 'name'], limit: 1 });
+
+if (!project) {
+  throw new Error('No project with timesheets enabled');
+}
+
+// Start a timer
+const entry = await client.timesheets.startTimer({
+  description: 'Working on feature X',
+  projectId: project.id,
+});
+trackRecord('account.analytic.line', entry.id);
+
+// Timer is now running — unit_amount = 0
+const isRunning = entry.unit_amount === 0;
+
+// Stop it to clean up
+await client.timesheets.stopTimer(entry.id);
+
+return { success: true, entryId: entry.id, wasRunning: isRunning };
+```
+
+### Stop a Timer
+
+```typescript testable id="timesheets-stop-timer" needs="client" creates="account.analytic.line" expect="result.success === true"
+const [project] = await client.searchRead('project.project', [
+  ['allow_timesheets', '=', true]
+], { fields: ['id'], limit: 1 });
+
+// Start then stop
+const entry = await client.timesheets.startTimer({
+  description: 'Timer to stop',
+  projectId: project.id,
+});
+trackRecord('account.analytic.line', entry.id);
+
+// Wait briefly so there's measurable time
+await new Promise(resolve => setTimeout(resolve, 500));
+
+const stopped = await client.timesheets.stopTimer(entry.id);
+
+return {
+  success: true,
+  hoursLogged: stopped.unit_amount,
+  timerStopped: stopped.unit_amount > 0
+};
+```
+
+### Find Running Timers
+
+```typescript testable id="timesheets-running-timers" needs="client" expect="result.success === true"
+const running = await client.timesheets.getRunningTimers();
+
+return {
+  success: true,
+  runningCount: running.length,
+  entries: running.map(e => ({
+    id: e.id,
+    description: e.name,
+    createdAt: e.create_date
+  }))
+};
+```
+
+### Log Completed Time (No Timer)
+
+```typescript testable id="timesheets-log-time" needs="client" creates="account.analytic.line" expect="result.success === true"
+const [project] = await client.searchRead('project.project', [
+  ['allow_timesheets', '=', true]
+], { fields: ['id'], limit: 1 });
+
+const entry = await client.timesheets.logTime({
+  description: 'Completed code review',
+  projectId: project.id,
+  hours: 1.5,
+});
+trackRecord('account.analytic.line', entry.id);
+
+return {
+  success: true,
+  entryId: entry.id,
+  hours: entry.unit_amount,
+  description: entry.name
+};
+```
+
+### List Timesheet Entries
+
+```typescript testable id="timesheets-list" needs="client" expect="result.success === true"
+const entries = await client.timesheets.list({
+  limit: 10,
+});
+
+const totalHours = entries.reduce((sum, e) => sum + (e.unit_amount || 0), 0);
+
+return {
+  success: true,
+  count: entries.length,
+  totalHours
+};
+```
+
+## Timer Architecture
+
+The timer concept is simple — it's just the `unit_amount` field:
+
+- **Running clock** = `unit_amount = 0` (entry without duration)
+- **Closed entry** = `unit_amount > 0` (duration filled)
+
+This is standard `hr_timesheet` behavior. No extra modules needed. The OCA module
+[`project_timesheet_time_control`](https://github.com/OCA/project/tree/17.0/project_timesheet_time_control)
+adds UI buttons (Start/Stop/Resume) for this workflow, but the data model is the same.
+
+The `client.timesheets` service wraps this into a clean API:
+- `startTimer()` → creates entry with `unit_amount = 0`
+- `stopTimer()` → computes elapsed time from `create_date`, writes `unit_amount`
+- `getRunningTimers()` → searches for entries with `unit_amount = 0`
+
+## Standalone Functions
+
+For advanced composition, standalone functions are also exported:
+
+```typescript
+import {
+  startTimer, stopTimer, getRunningTimers, logTime, listTimesheets
+} from '@marcfargas/odoo-client';
+
+const entry = await startTimer(client, { description: 'Work', projectId: 5 });
+const stopped = await stopTimer(client, entry.id);
+const running = await getRunningTimers(client, employeeId);
+const logged = await logTime(client, { description: 'Review', projectId: 5, hours: 2 });
+const list = await listTimesheets(client, { projectId: 5 });
+```
+
 ## Related Documents
 
+- [attendance.md](./attendance.md) - Clock in/out (physical presence, separate from time tracking)
 - [crud.md](../base/crud.md) - CRUD operations
 - [search.md](../base/search.md) - Search patterns
 - [domains.md](../base/domains.md) - Domain filters

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