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. 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)

• - Returns ALL payments with full details — parcel names, landlord names, overdue status
• Query parameters:

• - Examples:

Upcoming Payments (next N days)

• - Returns ALL upcoming payments within N days (no truncation)
• Use days=60 or days=90 for longer lookahead

Leases (FULL)

• - Returns ALL leases with landlord contact info, rent terms, expiration status
• Query parameters:

Expiring Leases

• - Returns ALL leases expiring within N days

Landlords (FULL)

• - Returns ALL landlords with contact info, active lease count, total acres, total rent

Parcels

• - Returns ALL parcels with ownership type, acres, county
• Query parameter: ownership_type — owned, leased

Summary Stats

• - Total acres, owned/leased breakdown, parcel/lease/landlord counts, annual cost

Annual Land Costs (by month and entity)

• - Monthly cost breakdown by category (rent, mortgage, tax, insurance)
• Entity breakdown
• Query parameters: year, INLINECODE19

Cost Per Field (for P&L)

• - Land costs allocated to production fields
• Query parameters: year, INLINECODE21

Overdue Items

• - All overdue payments and reminders — high priority items

Actionable Items

• - 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:
CODEBLOCK0

To use the token: Include it as a Bearer token:
CODEBLOCK1

Token expiry: Tokens last 15 minutes. If you get a 401 response, request a new token.

Mark Single Payment Paid

Body:
CODEBLOCK2

Mark Multiple Payments Paid (Bulk)

Body:
CODEBLOCK3

Mark Payments Paid by Date Range

Body:
CODEBLOCK4

Use this when the user says "mark all March payments as paid" or similar bulk date-based operations.

Preview Lease Renewal

Body:
CODEBLOCK5

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

Body:
CODEBLOCK6

IMPORTANT: Always preview first, confirm with user, then execute.

Year-End Rollover Preview

Body:
CODEBLOCK7

Returns: Preview of payment schedules that would be created for the new crop year.

Year-End Rollover Execute

Body:
CODEBLOCK8

IMPORTANT: This creates next year's payment schedules based on current year leases. Always preview first.

FORBIDDEN Endpoints — Do NOT Use

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.