farmos-finance

# FarmOS Finance

Forward-looking cash flow planning and cost management. Projects future cash flows based on planned costs and expected revenue.

## Data Completeness

1. **Always state totals** when reporting financial data: "Total operating costs: $892,000 across 12 categories."
2. **Cash flow projections combine multiple sources.** If the marketing revenue side fails, say so — don't present costs without revenue as a complete picture.
3. **If an endpoint returns an error**, report the failure to the user rather than presenting partial financial data. Partial financial data is worse than no data.
4. **For cost item listings**, use `/api/cost-items` with crop_year — this returns all items without pagination.

## When This Skill Triggers

- "What's our cash flow look like?"
- "Cost per acre this year?"
- "Breakeven price for corn?"
- "Monthly expense projection"
- "Show cost categories"
- "What are our biggest expenses?"

## Authentication

**ADMIN ONLY.** This skill accesses sensitive financial data. Always use admin-level auth.

```bash
TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)
```

**Role mapping:** Check `~/.clawdbot/farmos-users.json`. If the sender is not admin, respond: "Financial data is restricted to farm owners. I can't access that for your account."

## API Base

http://100.102.77.110:8010

## Integration Endpoints (No Auth — if AI access toggle is enabled)

### Cost Summary
GET /api/integration/summary?crop_year=2025

Returns: Total costs by category for the crop year.

### Cash Flow (Simplified)
GET /api/integration/cash-flow-simple?crop_year=2025

Returns: Monthly outflow projections.

### Breakeven Analysis
GET /api/integration/breakeven?crop_year=2025

Returns: Cost per acre and cost per bushel by crop and entity. This tells you the minimum price needed to cover costs.

## Authenticated Endpoints (JWT Required)

### Cost Categories
GET /api/categories
Authorization: Bearer {token}

Returns: Cost category definitions (fertilizer, seed, chemicals,...