farmos-land-portfolio

# FarmOS Land Portfolio Track owned and leased land, lease terms, landlord relationships, payments, and annual land costs. ## CRITICAL: Data Completeness Rules **NEVER use partial or truncated data. These rules are non-negotiable:** 1. **NEVER use `/api/integration/dashboard`** — it truncates results to 5 items. Partial payment data is worse than no data because it creates a false sense of completeness. 2. **ALWAYS use the `/all` endpoints** listed below for complete data. 3. **If an endpoint returns an error or empty results, REPORT THE FAILURE to the user.** Do not silently fall back to a different endpoint or present partial data. 4. **ALWAYS state the total count** of records returned so the user knows the data is complete. Example: "Found 11 payments due in March totaling $175,058." 5. **If you cannot get complete data, say so explicitly.** "I was unable to retrieve complete payment data" is infinitely better than showing 5 of 11 payments. ## When This Skill Triggers - "When do our leases expire?" - "What's the rent on the Smith ground?" - "Total land costs this year?" - "Show overdue payments" - "Landlord contact info" - "Cost per acre by parcel" - "List all leased parcels" - "What payments are due in March?" - "Cash requirements for next month" - "Mark payment [X] as paid" - "Mark all March payments paid" - "Renew the Smith lease" - "Preview lease renewals" ## Access Control Lease terms, rent amounts, and landlord info are sensitive business data. Restrict to admin or manager roles only. **Role mapping:** Check the sender's role in `~/.openclaw/farmos-users.json`. If the user is not admin or manager, tell them they don't have access to land portfolio data. ## API Base http://100.102.77.110:8009 ## Integration Endpoints (No Auth Required) — READ OPERATIONS ONLY **IMPORTANT: Use auth endpoints for WRITE operations (mark-paid, renewals). Use integration `/all` endpoints for READ operations (listing payments, leases, landlords).** ### Payments (FULL — use this, not dashboard) GET /api/integration/payments/all - Returns ALL payments with full details — parcel names, landlord names, overdue status - Query parameters: - `status` — pending, paid, overdue, scheduled - `payment_type` — rent, mortgage, property_tax, insurance, improvement, other - `parcel_id` — filter by specific parcel - `due_date_from` — YYYY-MM-DD range start - `due_date_to` — YYYY-MM-DD range end - `crop_year` — filter by crop year - Examples: - All overdue: `/api/integration/payments/all?status=overdue` - March 2026 payments: `/api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31` - All rent payments: `/api/integration/payments/all?payment_type=rent` ### Upcoming Payments (next N days) GET /api/integration/payments/upcoming?days=30 - Returns ALL upcoming payments within N days (no truncation) - Use `days=60` or `days=90` for longer lookahead ### Leases (FULL) GET /api/integration/leases/all - Returns ALL leases with landlord contact info, rent terms, expiration status - Query parameters: - `status` — active, expired - `landlord_id` — filter by landlord ### Expiring Leases GET /api/integration/leases/expiring?days=90 - Returns ALL leases expiring within N days ### Landlords (FULL) GET /api/integration/landlords/all - Returns ALL landlords with contact info, active lease count, total acres, total rent ### Parcels GET /api/integration/parcels - Returns ALL parcels with ownership type, acres, county - Query parameter: `ownership_type` — owned, leased ### Summary Stats GET /api/integration/summary - Total acres, owned/leased breakdown, parcel/lease/landlord counts, annual cost ### Annual Land Costs (by month and entity) GET /api/integration/finance/costs?year=2026 - Monthly cost breakdown by category (rent, mortgage, tax, insurance) - Entity breakdown - Query parameters: `year`, `entity_id` ### Cost Per Field (for P&L) GET /api/integration/finance/cost-per-field?year=2026 - Land costs allocated to production fields - Query parameters: `year`, `entity_id` ### Overdue Items GET /api/integration/tasks/overdue - All overdue payments and reminders — high priority items ### Actionable Items GET /api/integration/tasks/actionable?days_ahead=30 - Upcoming payments, expiring leases, pending reminders ## Authenticated Endpoints — WRITE OPERATIONS These require JWT auth. See Authentication section below. ### Authentication This skill accesses protected FarmOS endpoints that require a JWT token. **To get a token:** Run the auth helper with the appropriate role: ```bash TOKEN=$(~/clawd/scripts/farmos-auth.sh admin) ``` **To use the token:** Include it as a Bearer token: ```bash curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint ``` **Token expiry:** Tokens last 15 minutes. If you get a 401 response, request a new token. ### Mark Single Payment Paid POST /api/payments/{id}/mark-paid Authorization: Bearer {token} Content-Type: application/json Body: ```json { "paid_date": "2026-02-15", "notes": "Check #1234" } ``` ### Mark Multiple Payments Paid (Bulk) POST /api/payments/bulk/mark-paid Authorization: Bearer {token} Content-Type: application/json Body: ```json { "payment_ids": [12, 34, 56], "paid_date": "2026-02-15", "notes": "Batch check run" } ``` ### Mark Payments Paid by Date Range POST /api/payments/bulk/mark-paid-by-date Authorization: Bearer {token} Content-Type: application/json Body: ```json { "due_date_from": "2026-03-01", "due_date_to": "2026-03-31", "paid_date": "2026-02-15", "payment_type": "rent", "notes": "March rent payments" } ``` Use this when the user says "mark all March payments as paid" or similar bulk date-based operations. ### Preview Lease Renewal POST /api/leases/renewal-preview Authorization: Bearer {token} Content-Type: application/json Body: ```json { "lease_ids": [5, 12], "new_start_date": "2027-03-01", "rent_increase_percent": 3.0 } ``` Returns: Preview of what the renewed leases would look like, including new payment schedules. Use this BEFORE executing bulk renewals so the user can confirm. ### Execute Bulk Lease Renewal POST /api/leases/bulk-renew Authorization: Bearer {token} Content-Type: application/json Body: ```json { "lease_ids": [5, 12], "new_start_date": "2027-03-01", "new_end_date": "2028-02-28", "new_rent_amount": 52000.00, "rent_increase_percent": 3.0, "notes": "Annual renewal with 3% increase" } ``` **IMPORTANT:** Always preview first, confirm with user, then execute. ### Year-End Rollover Preview POST /api/payments/year-end-rollover/preview Authorization: Bearer {token} Content-Type: application/json Body: ```json { "from_year": 2026, "to_year": 2027 } ``` Returns: Preview of payment schedules that would be created for the new crop year. ### Year-End Rollover Execute POST /api/payments/year-end-rollover/execute Authorization: Bearer {token} Content-Type: application/json Body: ```json { "from_year": 2026, "to_year": 2027, "apply_rent_increase": true, "rent_increase_percent": 2.5 } ``` **IMPORTANT:** This creates next year's payment schedules based on current year leases. Always preview first. ## FORBIDDEN Endpoints — Do NOT Use | Endpoint | Why | |----------|-----| | `GET /api/integration/dashboard` | **Truncates to 5 items. NEVER use this.** | ## Key Concepts - **Parcel:** A land unit — either owned or leased. - **Lease types:** Cash rent, crop share, flex rent. - **Lease expiration:** Critical to track — approaching expirations need proactive attention. - **Land payments:** Rent, mortgage, property tax, insurance — each with due dates. ## Usage Notes - Lease expiration tracking is the highest-value query — always flag leases expiring within 6 months. - Payment status (due/overdue) is critical — flag overdue payments immediately. - Cost per acre analysis helps compare owned vs leased economics. - Landlord contact info is private — never share outside admin/manager channels. - When asked about "cash requirements" or "what do we owe", always use `/api/integration/payments/all` with date filtering to get the COMPLETE picture. - For financial planning questions, combine `/api/integration/payments/all` with `/api/integration/finance/costs` for the full view. - **Write operations:** Always use authenticated endpoints for marking payments paid or renewing leases. Preview first when doing bulk operations. - **Bulk payment marking:** When user says "mark all March payments paid", use the bulk-by-date endpoint rather than individual calls.