{"skill":{"slug":"farmos-marketing","displayName":"Farmos Marketing","summary":"Query grain marketing positions, contracts, delivery schedules, inventory, and revenue data. Requires authentication — manager role minimum for dashboard, ad...","description":"---\nname: farmos-marketing\ndescription: Query grain marketing positions, contracts, delivery schedules, inventory, and revenue data. Requires authentication — manager role minimum for dashboard, admin for full access.\ntags: [farming, marketing, grain, contracts]\n---\n\n# FarmOS Marketing\n\nGrain marketing positions, contracts, deliveries, settlements, inventory, and revenue analysis for a corn/soybean operation with 3 entities across ~4,000 acres.\n\n## When This Skill Triggers\n\n- \"What's our marketing position?\"\n- \"How much corn have we sold?\"\n- \"Show the dashboard summary\"\n- \"Any deliveries coming up?\"\n- \"What's our average corn price?\"\n- \"Bushels remaining to sell?\"\n- \"Revenue by entity\"\n- \"Show open contracts\"\n- \"Basis levels?\"\n- \"Settlement history\"\n\n## Data Completeness\n\n1. **Dashboard endpoint truncates results.** Use `/api/integration/dashboard` for summary stats only — NOT for listing positions, deliveries, or settlements.\n2. **Always state the total count** of records returned: \"Found 23 open positions totaling 145,000 bushels of corn.\"\n3. **If a query returns suspiciously few results**, say so: \"I'm only seeing 3 positions — that may be incomplete.\"\n4. **Use authenticated endpoints for complete data** — integration endpoints are for quick summaries, not full listings.\n5. **If an endpoint fails**, report the failure rather than silently showing partial data.\n\n## Authentication\n\nThis skill accesses protected FarmOS endpoints that require a JWT token.\n\n**To get a token:** Run the auth helper with the appropriate role:\n```bash\nTOKEN=$(~/clawd/scripts/farmos-auth.sh admin)\n# or for manager-level access:\nTOKEN=$(~/clawd/scripts/farmos-auth.sh manager)\n```\n\n**To use the token:** Include it as a Bearer token:\n```bash\ncurl -H \"Authorization: Bearer $TOKEN\" http://100.102.77.110:8013/api/endpoint\n```\n\n**Token expiry:** Tokens last 15 minutes. If you get a 401 response, request a new token.\n\n**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.\n\n## API Base\n\nhttp://100.102.77.110:8013\n\n## Integration Endpoints (No Auth — for cross-module data)\n\nThese provide summary data without authentication. Use for quick lookups and cron jobs.\n\n### Dashboard Summary\nGET /api/integration/dashboard\n\nReturns: Contract counts, bushels sold, delivery schedule stats, recent settlements.\n\n### Revenue Summary\nGET /api/integration/revenue?crop_year=2025&entity_id=1\n\nReturns: Revenue by crop (corn/soybeans), by month, contracted vs projected. Use for cash flow analysis.\n\n### Entities\nGET /api/integration/entities\n\nReturns: All farm entities with id, name, type, short_code. Use to map entity names to IDs.\n\n### Fields with Ownership\nGET /api/integration/fields?entity_id=1\n\nReturns: Fields with acres, entity ownership shares.\n\n### Acres Summary\nGET /api/integration/acres-summary\n\nReturns: Total acres by entity with field counts and ownership shares.\n\n### Settlements by Month\nGET /api/integration/settlements-by-month?crop_year=2025&entity_id=1\n\nReturns: Monthly settlement amounts for cash flow timing.\n\n### Crop Years\nGET /api/integration/crop-years\n\nReturns: Available crop years with current year flag.\n\n## Authenticated Endpoints (JWT Required)\n\n### Dashboard Summary (Full)\nGET /api/dashboard/summary?crop_year=2025\nAuthorization: Bearer {token}\nRequires: manager+\n\nReturns comprehensive marketing dashboard:\n- Crop year settings (expected yield, expected price per crop)\n- Per-entity, per-crop breakdown:\n  - total_bushels, hedged/sold/basis/hta/open bushels\n  - percent_marketed\n  - contracted_revenue, projected_revenue, settled_revenue\n  - needs_bushel_transfer warnings\n- Totals by crop\n\nThis is the primary endpoint for \"how are we positioned?\" questions.\n\n### Positions (Contracts)\nGET /api/positions?crop_year=2025\nAuthorization: Bearer {token}\nRequires: manager+\n\nQuery params: crop_year, crop (corn|soybeans), entity_id, status (open|fulfilled|cancelled), type (Hedge|Cash Sale|Basis|HTA)\n\nReturns: List of marketing positions/contracts with:\n- contract_number, crop, type, entity\n- quantity (bushels), entry_price, basis\n- delivery_start, delivery_end, buyer\n- status, lifecycle info\n\n### Positions Export\nGET /api/positions/export?crop_year=2025\nAuthorization: Bearer {token}\nRequires: manager+\n\nReturns: CSV export of all positions.\n\n### Deliveries (Scale Tickets)\nGET /api/deliveries?crop_year=2025\nAuthorization: Bearer {token}\n\nReturns: Delivery records with ticket numbers, dates, quantities, moisture, test weight.\n\n### Settlements (Payments)\nGET /api/settlements?crop_year=2025\nAuthorization: Bearer {token}\n\nReturns: Settlement records — payments received from buyers.\n\n### Inventory\nGET /api/inventory?crop_year=2025\nAuthorization: Bearer {token}\n\nReturns: Current grain inventory status — what's in bins vs sold vs delivered.\n\n### Crop Year Settings\nGET /api/crop-year-settings?crop_year=2025\nAuthorization: Bearer {token}\n\nReturns: Expected yield and expected price per crop for the year. These drive projected revenue and percent marketed calculations.\n\n## Key Concepts\n\n- **Position types:** Hedge (futures only), Cash Sale (flat price), Basis (basis only), HTA (futures locked, basis open)\n- **Percent marketed:** bushels_sold / total_expected_bushels x 100\n- **Entity:** A farm legal entity (e.g., \"Fields of Dreams\", \"ILMG\"). Each has its own positions and production.\n- **Crop year:** The year the crop is grown (2025 = planted spring 2025, harvested fall 2025, may deliver into 2026).\n- **Bushel transfers (PIK):** When one entity is oversold, bushels transfer from another entity to cover.\n\n## Cross-Module Context\n\nThe team agent's marketing access is read-only and logistics-scoped. Use it to connect delivery deadlines to field operations:\n\n**Marketing → Field Ops:**\n- 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.\"\n- When crew asks about harvest sequencing or field priorities, reference delivery deadlines and contract obligations.\n- 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.\"\n\n**Marketing → Equipment:**\n- 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.\"\n\nDon'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.\n\n## Usage Notes\n\n- Always include crop_year parameter (default to current: 2025, use 2026 when appropriate).\n- The dashboard summary is the best \"big picture\" endpoint.\n- For specific contract questions, use positions with filters.\n- Revenue data from integration endpoints doesn't require auth — good for cron jobs and summaries.\n- When discussing positions, include the entity name, crop, type, quantity, and price.\n- Flag any positions marked as \"needs_bushel_transfer\" — this means an entity has sold more than it can produce.\n- The entities are: check /api/integration/entities for current list and IDs.\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":335,"installsAllTime":2,"installsCurrent":2,"stars":0,"versions":1},"createdAt":1771750840447,"updatedAt":1778992314393},"latestVersion":{"version":"1.0.0","createdAt":1771750840447,"changelog":"- Initial release: enables querying of grain marketing positions, contracts, delivery schedules, inventory, and revenue data for multi-entity corn/soybean operations.\n- Dashboard, positions, deliveries, settlements, inventory, and crop-year-specific queries supported.\n- Auth required: manager role minimum for dashboard, admin for full API access; includes clear guidance on authentication and role management.\n- Integration endpoints provide fast, summary-level data without authentication for cross-module and cron job use.\n- Includes built-in safeguards: always state record counts, flag incomplete data, and report endpoint failures.\n- Contextual guidance for relating marketing info to harvest logistics and field operations.","license":null},"metadata":null,"owner":{"handle":"brianppetty","userId":"s17ayv2vrvdycq58dkjx8wpbg9885kes","displayName":"brianppetty","image":"https://avatars.githubusercontent.com/u/26852668?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779949001701}}