From 61c17365396b792d9555e706ccabaf9fb475a884 Mon Sep 17 00:00:00 2001
From: Justin Paul <justin@jpaul.me>
Date: Fri, 29 May 2026 15:26:18 -0400
Subject: [PATCH] Add CHANGELOG for upstream tool consumers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the new basis_movement/basis_detail tools, the flexible price_history
and latest_prices signatures, and the /api/data/history commodity-optional
change, with example question→call mappings.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..67ba1a7
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,74 @@
+# Changelog
+
+Notes for clients/agents that consume the ag-bids MCP tools and the underlying
+`ag-monitor` `/api/data/*` HTTP API. Newest first.
+
+## 2026-05-29 — Flexible history + basis movement
+
+### New MCP tools
+
+- **`basis_movement(commodity?, source?, delivery?, days=30)`** — aggregated
+  basis trend, **one headline line per crop**. Averages every matching
+  (elevator × delivery) series to `avg basis first → last` over the window and
+  reports how far it moved. This is the cheap "how is basis moving overall"
+  view. All filters optional; `commodity` (if given) must be `corn`/`soy`/`wheat`.
+  - Positive move = **cash strengthened** vs futures (basis up); negative = weaker.
+  - Aggregation is intentional: divergent elevators can net to "flat". When the
+    aggregate looks flat or surprising, call `basis_detail` to see per-elevator
+    splits.
+
+- **`basis_detail(commodity?, source?, delivery?, days=30)`** — the drill-down
+  for `basis_movement`. **One row per (elevator, crop, delivery)** series with
+  basis `first → last` and the move. Same optional filters.
+
+Both tools do the aggregation **server-side (in the MCP)** and return compact
+markdown — they do not dump every raw sample — to keep token usage low. Pattern:
+call `basis_movement` first, then `basis_detail` (optionally filtered) only when
+you need the breakdown.
+
+### Changed MCP tools
+
+- **`price_history`** — `commodity` is now **optional** (was required). Omit it
+  to span every crop. Output now groups by **(elevator, crop, delivery)**,
+  surfaces **basis first → last** in each series summary, and adds a **Futures**
+  column to the raw points table. Every filter (`commodity`, `source`,
+  `delivery`, `days`) is optional and AND'd — pivot per elevator, per crop, per
+  delivery, or any combination.
+  - Raw per-row points are still only included when the window has ≤ ~60 samples;
+    wider queries return the per-series summaries only.
+
+- **`latest_prices`** — added the **`kind`** filter (`grain` | `fertilizer`) for
+  parity with the API. `commodity`, `source`, `delivery`, `kind` all optional.
+
+### API changes (`ag-monitor`)
+
+- **`GET /api/data/history`** — `commodity` query param is now **optional**.
+  When omitted, returns history across all crops. `source_id`, `delivery`, and
+  `days` (1–730, default 30) remain optional. Response shape is unchanged:
+  `{ "commodity": <str|null>, "days": <int>, "rows": [...] }`. Each row carries
+  `fetched_at, source_id, source_name, commodity, delivery, bid_cents,
+  basis_cents, futures_cents` so callers can pivot client-side.
+  - `GET /api/data/latest` already supported optional `commodity`, `source`,
+    `delivery`, `kind` — unchanged.
+
+### Conventions / gotchas
+
+- All money fields are **integer cents**. `bid_cents`/`futures_cents` render as
+  `$/bu` (4 dp) for grain and `$/ton` (2 dp) for fertilizer; `basis_cents`
+  renders as a signed dollar value (2 dp), e.g. `-0.14`.
+- Basis is only meaningful for grain — the basis tools skip non-grain rows and
+  any series with no basis on file.
+- `source` filtering is by **exact** elevator display name (e.g.
+  `"Mercer Landmark — Minster"`). Use `list_sources` to get exact names.
+
+### Example questions → tool calls
+
+| Ask | Call |
+|---|---|
+| Basis movement overall, last 7 days | `basis_movement(days=7)` |
+| Corn basis movement across all elevators | `basis_movement(commodity="corn")` |
+| Basis movement at one elevator | `basis_movement(source="Mercer Landmark — Minster")` |
+| Per-elevator basis breakdown for corn | `basis_detail(commodity="corn")` |
+| Last 7 days of history from elevator X for corn | `price_history(commodity="corn", source="…", days=7)` |
+| All-crop price history at one elevator | `price_history(source="…")` |
+| Latest grain bids only | `latest_prices(kind="grain")` |