Skill: brianppetty/farmos-marketing (version 1.0.0)

--- name: farmos-marketing description: Query grain marketing positions, contracts, delivery schedules, inventory, and revenue data. Requires authentication — manager role minimum for dashboard, admin for full access. tags: [farming, marketing, grain, contracts] --- # FarmOS Marketing Grain marketing positions, contracts, deliveries, settlements, inventory, and revenue analysis for a corn/soybean operation with 3 entities across ~4,000 acres. ## When This Skill Triggers - "What's our marketing position?" - "How much corn have we sold?" - "Show the dashboard summary" - "Any deliveries coming up?" - "What's our average corn price?" - "Bushels remaining to sell?" - "Revenue by entity" - "Show open contracts" - "Basis levels?" - "Settlement history" ## Data Completeness 1. **Dashboard endpoint truncates results.** Use `/api/integration/dashboard` for summary stats only — NOT for listing positions, deliveries, or settlements. 2. **Always state the total count** of records returned: "Found 23 open positions totaling 145,000 bushels of corn." 3. **If a query returns suspiciously few results**, say so: "I'm only seeing 3 positions — that may be incomplete." 4. **Use authenticated endpoints for complete data** — integration endpoints are for quick summaries, not full listings. 5. **If an endpoint fails**, report the failure rather than silently showing partial data. ## 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 [REDACTED_SECRET] admin) # or for manager-level access: [REDACTED_SECRET] manager) ``` **To use the token:** Include it as a Bearer token: ```bash curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8013/api/endpoint ``` **Token expiry:** Tokens last 15 minutes. If you get a 401 response, request a new token. **Role mapping:** Check the sender's role in `~/.clawdbot/farmos-users.json`. If the user is not admin or manager, tell them they don't have access to marketing data. ## API Base http://100.102.77.110:8013 ## Integration Endpoints (No Auth — for cross-module data) These provide summary data without authentication. Use for quick lookups and cron jobs. ### Dashboard Summary GET /api/integration/dashboard Returns: Contract counts, bushels sold, delivery schedule stats, recent settlements. ### Revenue Summary GET /api/integration/revenue?crop_year=2025&entity_id=1 Returns: Revenue by crop (corn/soybeans), by month, contracted vs projected. Use for cash flow analysis. ### Entities GET /api/integration/entities Returns: All farm entities with id, name, type, short_code. Use to map entity names to IDs. ### Fields with Ownership GET /api/integration/fields?entity_id=1 Returns: Fields with acres, entity ownership shares. ### Acres Summary GET /api/integration/acres-summary Returns: Total acres by entity with field counts and ownership shares. ### Settlements by Month GET /api/integration/settlements-by-month?crop_year=2025&entity_id=1 Returns: Monthly settlement amounts for cash flow timing. ### Crop Years GET /api/integration/crop-years Returns: Available crop years with current year flag. ## Authenticated Endpoints (JWT Required) ### Dashboard Summary (Full) GET /api/dashboard/summary?crop_year=2025 Authorization: Bearer {token} Requires: manager+ Returns comprehensive marketing dashboard: - Crop year settings (expected yield, expected price per crop) - Per-entity, per-crop breakdown: - total_bushels, hedged/sold/basis/hta/open bushels - percent_marketed - contracted_revenue, projected_revenue, settled_revenue - needs_bushel_transfer warnings - Totals by crop This is the primary endpoint for "how are we positioned?" questions. ### Positions (Contracts) GET /api/positions?crop_year=2025 Authorization: Bearer {token} Requires: manager+ Query params: crop_year, crop (corn|soybeans), entity_id, status (open|fulfilled|cancelled), type (Hedge|Cash Sale|Basis|HTA) Returns: List of marketing positions/contracts with: - contract_number, crop, type, entity - quantity (bushels), entry_price, basis - delivery_start, delivery_end, buyer - status, lifecycle info ### Positions Export GET /api/positions/export?crop_year=2025 Authorization: Bearer {token} Requires: manager+ Returns: CSV export of all positions. ### Deliveries (Scale Tickets) GET /api/deliveries?crop_year=2025 Authorization: Bearer {token} Returns: Delivery records with ticket numbers, dates, quantities, moisture, test weight. ### Settlements (Payments) GET /api/settlements?crop_year=2025 Authorization: Bearer {token} Returns: Settlement records — payments received from buyers. ### Inventory GET /api/inventory?crop_year=2025 Authorization: Bearer {token} Returns: Current grain inventory status — what's in bins vs sold vs delivered. ### Crop Year Settings GET /api/crop-year-settings?crop_year=2025 Authorization: Bearer {token} Returns: Expected yield and expected price per crop for the year. These drive projected revenue and percent marketed calculations. ## Key Concepts - **Position types:** Hedge (futures only), Cash Sale (flat price), Basis (basis only), HTA (futures locked, basis open) - **Percent marketed:** bushels_sold / total_expected_bushels x 100 - **Entity:** A farm legal entity (e.g., "Fields of Dreams", "ILMG"). Each has its own positions and production. - **Crop year:** The year the crop is grown (2025 = planted spring 2025, harvested fall 2025, may deliver into 2026). - **Bushel transfers (PIK):** When one entity is oversold, bushels transfer from another entity to cover. ## Cross-Module Context The team agent's marketing access is read-only and logistics-scoped. Use it to connect delivery deadlines to field operations: **Marketing → Field Ops:** - During harvest and delivery windows, check delivery schedules when discussing field work priorities. Delivery commitments determine which fields get harvested first: "There's a 5,000-bu bean delivery to ADM due next week. Priority on the bean fields." - When crew asks about harvest sequencing or field priorities, reference delivery deadlines and contract obligations. - Flag tight timelines: "Cargill delivery window closes in 10 days and you've only delivered 60% of that contract. Might want to bump those fields up." **Marketing → Equipment:** - During harvest, connect delivery deadlines to equipment availability: "You've got 3 deliveries due this week — make sure the grain cart and trucks are ready." Don't cross-reference marketing on every field ops question. This matters during harvest, delivery windows, and when logistics questions come up. Not during routine spraying or maintenance. ## Usage Notes - Always include crop_year parameter (default to current: 2025, use 2026 when appropriate). - The dashboard summary is the best "big picture" endpoint. - For specific contract questions, use positions with filters. - Revenue data from integration endpoints doesn't require auth — good for cron jobs and summaries. - When discussing positions, include the entity name, crop, type, quantity, and price. - Flag any positions marked as "needs_bushel_transfer" — this means an entity has sold more than it can produce. - The entities are: check /api/integration/entities for current list and IDs.


Security scan verdicts — ClawScan: suspicious | static analysis:  | VirusTotal: suspicious | SkillSpector: clean (LOW)