@sdelsad/commodity-desk-daily 1.0.17 → 1.13.2

package/ep04.md

@@ -0,0 +1,192 @@
+# Soft Commodity Trading — Ep 4
+## The Physical Chain, End to End
+
+---
+
+## Market pulse
+
+**The August WASDE was friendly — and the Black Sea turned violent again the same night.**
+
+| Contract | Close (Wed) | Change |
+|---|---|---|
+| Corn, December | $4.80¾ /bu | +20¼¢ (two-week high) |
+| Soybeans, November | $11.83¼ /bu | +14½¢ |
+| Wheat, Chicago September | $6.52¾ /bu | +22½¢ |
+| Wheat, Kansas City September | $7.20¾ /bu | +21½¢ |
+
+USDA cut its corn yield to **180.7 bu/acre** — below the 182.5 average trade guess and near the bottom of the 180–185 range of estimates. New-crop corn ending stocks fell from 1.79 to **1.653 billion bushels**. Soybeans were the odd one out: production came in 44 million bushels *above* July and 41 above the trade — a bearish supply line — yet November beans closed higher, because USDA raised crush by 30 million bushels and corn pulled the whole floor up. The lesson of the day's tape: the market trades the whole balance sheet, not one row of it.
+
+```chart
+{"type":"line","mode":"index","unit":"Mon 10 Aug = 100","title":"WASDE week on the board",
+ "caption":"Two sessions of defensive drift, one report: corn jumped to a two-week high and wheat ended above where Monday left it.",
+ "source":"CME settlements 10-12 Aug 2026 (episode pulses; Pro Farmer)",
+ "x":["Mon 10","Tue 11","Wed 12"],
+ "series":[{"name":"Dec corn","values":[465,460.5,480.75]},
+           {"name":"Nov soybeans","values":[1182,1168.75,1183.25]},
+           {"name":"Sep Chicago wheat","values":[651,630.25,652.75]}]}
+```
+
+**The geopolitical read.** Tuesday's rumour of safe-passage talks died overnight: Ukrainian drones struck Novorossiysk and idled its two big grain terminals — the Demetra-controlled Novorossiysk Grain Terminal (~8.5 Mt/yr) and the NKHP terminal (~7.1 Mt/yr), together more than 15.5 Mt of annual export capacity. On Tuesday the market priced trapped grain getting *out*; on Wednesday it priced Russian loading capacity going *dark* — the same transmission mechanism, running in reverse. Russia's August wheat exports were already estimated at only 3.0–3.4 Mt. Turkey is floating a plan for two protected corridors, one along each coast; nothing is signed. And every vessel anchored off Novorossiysk is now on a clock that is denominated in dollars per day — which is today's subject.
+
+---
+
+### Key takeaways
+
+- **Incoterms** are the trade's risk-allocation vocabulary. **FOB**: seller delivers over the ship's rail; buyer charters, insures, owns the voyage. **CFR**: seller also pays the freight. **CIF**: seller pays freight *and* insurance.
+- The trap: in all three, **risk passes at the load port**. On a CIF cargo the seller pays freight to destination and buys the insurance — yet the voyage runs at the *buyer's* risk, and the buyer claims on the policy the seller bought. **Cost and risk travel separately.**
+- Execution is a clock: **laycan** (loading window) → **nomination** of the vessel → **notice of readiness** (NOR starts the clock) → **laytime** (allowed loading time, counted in weather working days) → **demurrage** if exceeded, **despatch** (customarily half the demurrage rate) if beaten.
+- Worked example: 60,000 t FOB Santos, laytime 6 days at 10,000 t/day, port queue makes loading take 9. Demurrage $24,000/day × 3 = **$72,000** — 11% of the $660k margin — while financing the $26M cargo costs another ~$4,300/day. Nothing moved on the screen.
+- Demurrage claims cascade through the contract string and are fought on the **statement of facts**. Missing a **laycan** lets the counterparty cancel — a one-day slip can put the entire flat-price move on your book.
+- At loading the cargo becomes paper: **draft survey** for weight, load-port **quality certificate that is final**, and the **bill of lading** — receipt, contract of carriage and document of title in one. Backdating a B/L is fraud, and it has sunk trading houses.
+- Execution desks are a **profit centre**: they win claims, earn despatch, and save the days traders give away.
+
+### Vocabulary of the day
+
+| Term | Meaning |
+|---|---|
+| Incoterms | Standard three-letter trade terms allocating cost and risk between buyer and seller |
+| FOB / CFR / CIF | Free on board / cost and freight / cost, insurance and freight — risk passes at loading in all three |
+| Charter party | The contract hiring the vessel, between charterer and shipowner |
+| Nomination | Formally naming the performing vessel under a cargo contract |
+| Notice of readiness (NOR) | The master's declaration that the vessel has arrived and is ready — starts laytime |
+| Laytime | The contractually allowed time to load or discharge before demurrage begins |
+| Weather working day | A laytime day that counts only when weather permits cargo work |
+| Despatch | Reward for loading faster than laytime, customarily half the demurrage rate |
+| Statement of facts | The port log of events both sides use to fight laytime claims |
+| Draft survey | Weighing the cargo by the ship's displacement, before and after loading |
+| Bill of lading (B/L) | Receipt, contract of carriage and document of title in one — holder owns the cargo |
+| Cancelling date | The last day of the laycan, after which the counterparty may cancel |
+
+---
+
+## Quiz — Day 4
+
+**J-0 — Episode 4: The physical chain, end to end**
+
+**Q1.** You sold 60,000 t of soybeans CIF Qingdao. Mid-ocean, the vessel takes on water and the cargo is ruined. The buyer emails: "Your ship, your freight, your insurance — send a replacement cargo." Are they right? Who bears the loss, who claims on the insurance, and what exactly does the buyer still have to do under the contract?
+
+**Q2.** A Supramax loads 48,000 t of corn at a rate of 8,000 t per weather working day. She tenders NOR on the 3rd; loading actually takes 10 calendar days, but the statement of facts shows 2 full days of rain during which no work was possible. Demurrage is $18,500/day, despatch half. Who owes whom, and how much? What single document decides the argument?
+
+**Q3.** You are the FOB seller. Laycan is 15–25 November; on the 24th your cargo is still 20,000 t short because your up-country supplier defaulted. The buyer's vessel has been at anchor since the 18th, and December futures have rallied 40¢ since you signed. Describe your three exposures, in dollars where possible (cargo 60,000 t ≈ 2.2 M bu, demurrage $24,000/day), and rank them.
+
+**J-1 — Episode 3: Futures plumbing and the shape of the curve**
+
+**Q4.** Your desk is short 80 September wheat lots hedging inventory, and needs the hedge in December. The broker quotes "Sep-Dec fifteen, Dec over." When you roll, do you pay the fifteen cents or receive it? And what does that answer tell you about what a carry market does to the economics of hedged storage?
+
+**Q5.** Wednesday's WASDE moved December corn up 20¼¢. A merchant was short 100 lots as a hedge against bought physical. (a) How much variation margin left the account, and when? (b) The physical gained roughly the same — so why does the CFO still care? (c) Name the ep-3 rule this illustrates.
+
+**J-3 — Episode 1: The units and the language of the desk**
+
+**Q6.** A colleague says: "We're long fifty lots of Matif wheat and short fifty lots of Chicago wheat — flat, more or less." How many tonnes is each leg? Is the book flat? Give the sizes and name every mismatch you can see.
+
+**Q7.** Decode this broker line word by word: "He's bid four eighty for fifty December, offered at four eighty and a half — the half's workable." What is being bought and sold, what size, at what prices, and what does "workable" change?
+
+---
+
+<br><br>
+
+## ▼ SOLUTIONS (spoilers) — scroll only after answering ▼
+
+<br><br>
+
+**A1.** The buyer is wrong. Under **CIF, risk passes at the load port** — the seller's obligations are to ship a conforming cargo, pay freight to Qingdao, procure insurance for the buyer's benefit, and tender clean documents. The mid-ocean loss is the **buyer's risk**; the **buyer claims on the policy the seller bought** (the policy is assigned with the documents). And the sting: CIF is a *documents* trade — if the seller tenders a clean bill of lading, load-port quality certificate and insurance policy, the buyer must **pay against documents in full**, then recover from underwriters. No replacement cargo is owed. The trap: assuming that whoever pays for the voyage carries its risk — cost and risk travel separately.
+
+**A2.** Allowed laytime = 48,000 ÷ 8,000 = **6 weather working days**. Ten calendar days minus 2 rain days = **8 laytime days used** — rain days don't count against the charterer. So she is **2 days over: charterer owes the owner 2 × $18,500 = $37,000 demurrage**. (Had the rain not been excluded, the bill would have read 4 days = $74,000 — the weather clause is worth $37,000 here.) The deciding document is the **statement of facts**, the port's signed log of NOR, berthing, work and stoppages. Demurrage disputes are won and lost on it, line by line.
+
+**A3.** Ranked by size: **(1) Cancellation into a rallied market** — if you cannot load by the cancelling date, the buyer can cancel and buy replacement. You are left owning ~40,000 t while your sale disappears; if your purchases were hedged with short futures, those shorts are 40¢ against you on the missing 20,000 t you now must buy at post-rally differentials — and a default/washout settlement would reference the market having moved ≈ 40¢ × 2.2 M bu ≈ **$880,000** on the full cargo if the whole contract fails. **(2) Demurrage** — the vessel has waited since the 18th; every day beyond laytime at $24,000 accrues to your account because the delay is cargo-side: a week is **$168,000**. **(3) Carrying and replacement costs** on the 40,000 t you do hold (~$17.4M financed ≈ $2,900/day). The lesson: the flat-price move you thought you had hedged away comes back through the execution failure — that is how a date becomes a liability.
+
+**A4.** You are short September; rolling means **buying September back and selling December**. December is 15¢ *above* — you re-sell higher than you buy back: you **receive** (capture) the 15 cents. That is the mechanics behind ep 3's store-or-sell rule: in a carry market, a short hedge *earns the spread* every roll, which is precisely the market paying you for storing hedged inventory. (In an inverse the same roll bleeds — same plumbing, opposite sign.)
+
+**A5.** (a) 100 lots × 5,000 bu × $0.2025 = **$101,250 of variation margin, wired same day**. (b) Because the physical gain is unrealized — it arrives when the grain is sold — while the margin call is cash *today*; funding cost is real, and volatile markets also bring initial-margin increases. (c) **A hedge converts price risk into liquidity risk** — the position is fine, the cash flow is not.
+
+**A6.** Matif wheat is **50 t per lot**: 50 lots = **2,500 t**. Chicago is **5,000 bu per lot**: 50 lots = 250,000 bu ≈ **6,800 t** (÷36.7). The book is nowhere near flat: the Chicago leg is ~2.7× the Matif leg in tonnage. And even at equal tonnage it wouldn't be flat: different wheats (SRW vs EU milling), different currencies (¢/bu vs €/t), different delivery points — an inter-exchange *spread*, not a hedge. "Fifty lots" is not a size until you know the contract.
+
+**A7.** Someone **bids $4.80/bu for 50 lots (250,000 bu) of December corn futures** and simultaneously **offers at $4.80½**. "The half's workable" means the offer at 4.80½ is negotiable — the seller would likely trade inside it (say 4.80¼) if firm interest shows. Nothing has traded yet: "done" is the word that seals it. The half-cent between them is 50 lots × 5,000 bu × $0.005 = **$1,250** — small words, real money.
+
+---
+
+## The episode, in writing
+
+### The tape: a friendly report, and a port gone dark
+
+The August WASDE cut the US corn yield to **180.7 bu/acre** — below the average trade guess of 182.5 and near the bottom of the 180–185 range — and took new-crop ending stocks from 1.79 down to 1.653 billion bushels. December corn jumped 20¼¢ to $4.80¾, a two-week high.
+
+Soybeans printed the opposite supply story — production 44 million bushels above July, 41 above the trade — and *still* closed up 14½¢ at $11.83¼: USDA raised crush by 30 million bushels, and corn dragged the floor higher. The market trades the whole balance sheet, not one row.
+
+Wheat rose 22½¢ in Chicago — half report, half Black Sea. Tuesday's safe-passage rumour died overnight when drones idled Novorossiysk's two big grain terminals (15.5+ Mt/yr combined capacity). Tuesday priced trapped grain getting out; Wednesday priced Russian loading capacity going dark. Same mechanism, reverse gear. Meanwhile a queue of vessels sits at anchor off the port — each one on a clock denominated in dollars per day. That clock is this episode.
+
+### Three letters that allocate a trade
+
+Strip a physical trade to its skeleton and three questions remain: who arranges the ship, who insures the cargo, and at what exact moment it stops being the seller's problem. **Incoterms** — the standard vocabulary kept by the International Chamber of Commerce — answer all three in three letters.
+
+| Term | Freight | Insurance | Risk passes |
+|---|---|---|---|
+| **FOB** — free on board | Buyer | Buyer | At loading |
+| **CFR** — cost and freight | **Seller** | Buyer | At loading |
+| **CIF** — cost, insurance, freight | **Seller** | **Seller** (for buyer's benefit) | At loading |
+
+Read the last column. It is the same in all three rows, and it is the detail that catches every newcomer: on a CIF cargo the seller pays the freight to Qingdao and buys the insurance — yet the voyage runs at the **buyer's risk**. If the ship founders mid-ocean, the loss is the buyer's, and the buyer claims on the very policy the seller bought. **Cost and risk travel separately.** The letters tell you who pays; they also tell you, quietly, who is exposed.
+
+Why would anyone buy FOB rather than CIF? Control, and freight. An importer with its own chartering desk buys FOB and keeps the freight economics; a buyer without one pays up for CIF and outsources the problem. Freight is a market of its own, and whoever fixes the ship carries that market's risk — episode 10's subject.
+
+### The clock: one cargo, from fixture to demurrage
+
+Take the episode-2 cargo one step further down the pipe: **60,000 t of soybeans, FOB Santos**, sold at a differential against November. At Wednesday's board (~$434/t), that is a **$26 million object**.
+
+The execution chain is a sequence of dated, contractual events:
+
+| Step | What happens | The clock |
+|---|---|---|
+| Laycan | Loading window agreed: 15–25 Nov | Vessel must present inside it |
+| Nomination | Buyer names the performing vessel | — |
+| Arrival | Vessel arrives the 18th, master tenders **NOR** | Clock armed |
+| Laytime | 10,000 t per weather working day → 6 days allowed | Clock running |
+| The queue | Santos line-up: loading takes 9 days | 3 days over |
+| Demurrage | Charter party rate $24,000/day | **$72,000** |
+
+Rain matters: laytime is counted in **weather working days**, so a rain-stopped day does not tick. And the clock runs both ways — beat laytime and the owner pays **despatch**, customarily half the demurrage rate.
+
+Now set the delay against the economics of the trade:
+
+```chart
+{"type":"waterfall","unit":"$ thousand","title":"Three days on the clock, one Panamax of beans",
+ "caption":"The board didn't move and the differential didn't move - the margin still lost 13%.",
+ "source":"Worked example, episodes 2 and 4 (beans at Wed close ~$434/t)",
+ "steps":[{"label":"Trading margin (30c/bu)","value":660,"kind":"base"},
+          {"label":"Demurrage 3 x $24k","value":-72},
+          {"label":"Interest, 3 days","value":-13},
+          {"label":"What's left","kind":"total"}]}
+```
+
+Financing alone — $26M at 6% — runs over **$4,000 a day** whether anything goes wrong or not. The meter never stops.
+
+On the desk, those three days sound like this:
+
+> **OPS:** She tendered NOR at 06:00. Terminal gives us a berth Saturday.
+> **TRADER:** When does the clock start?
+> **OPS:** It's already running. Turn time expired at noon.
+> **TRADER:** What did we fix her at?
+> **OPS:** Twenty-four a day. Line-up says three over if the queue doesn't move.
+> **TRADER:** That's seventy-two. Send me the line-up and get on to the terminal.
+
+Nobody mentioned the cargo or the price. "Twenty-four a day" is $24,000 of demurrage; "three over" is three days beyond laytime. The conversation is entirely about time, because time is the only thing still moving.
+
+### Who pays, and how a date becomes a liability
+
+Under FOB the buyer holds the charter, so the shipowner invoices the buyer — but if the delay was cargo-side, the claim gets passed up the sales contract. Demurrage claims cascade through whole strings of contracts and are fought line by line, months later, on the **statement of facts**, the port's log of everything that happened and when.
+
+The sharper edge is the **laycan** itself. Miss it as the buyer — vessel presents on the 26th — and the seller can cancel and resell. Miss it as the seller — cargo not ready when the ship is — and you pay the ship to wait, or face a cancelled contract in a market that has moved against you. If the board rallied 40¢ while you fumbled, a one-day slip puts the whole flat-price move on your book, unhedged. Execution failures become contractual liabilities not through drama, but through a date.
+
+### The cargo becomes paper
+
+At loading, three documents replace the physical:
+
+- **Draft survey** — the cargo is weighed by reading the ship's displacement before and after loading; the difference is the cargo.
+- **Quality certificate** — issued at the load port, and in most grain contracts **final**: if discharge finds something different, the load-port certificate still governs.
+- **Bill of lading** — receipt, contract of carriage and **document of title** in one. Whoever holds it owns the cargo: $26 million moving at the speed of a courier envelope.
+
+The date on a bill of lading proves shipment inside the contract window. Backdating one by a single day is not sloppiness — it is fraud, and it has sunk trading houses.
+
+That, finally, is why execution desks are a profit centre and not admin: a good operator wins the demurrage claim, earns the despatch, and saves the day the trader gave away in the negotiation. None of it shows on a screen — which is exactly why the margin lives there.
+
+**Tomorrow:** wheat — the map and the screens. Why two wheats at the same flat price are not the same wheat, and why it takes three exchanges to price one grain.

package/ep04.script.txt

@@ -0,0 +1,69 @@
+Here is a number the screen never shows you. Twenty-four thousand dollars. ||| 0.4
+That is what one idle ship can cost. Per day. While everyone stands around waiting. ||| 0.6
+This is Soft Commodity Trading, episode four. The physical chain, end to end. Who owns the cargo, who owns the risk, and how three quiet days at a port become a six-figure invoice. ||| 0.8
+First, the tape. Yesterday had two stories, and they landed on the same wheat contract. ||| 0.5
+The August W A S D E was friendly. The U S D A cut its corn yield to one hundred eighty point seven bushels an acre. The trade had guessed one eighty-two and a half. The standing number was one eighty-three. ||| 0.4
+Ending stocks fell from one point seven nine billion bushels to one point six five. December corn jumped twenty and a quarter cents, to four eighty and three quarters. A two-week high. ||| 0.5
+Soybeans were the strange one. The report made the crop bigger. Production came in forty-four million bushels above July, forty-one million above the trade guess. ||| 0.35
+And November beans still closed up fourteen and a half, at eleven eighty-three and a quarter. The U S D A raised crush by thirty million bushels, and corn pulled the whole floor higher. ||| 0.4
+A bearish supply line and a friendly close. You trade the whole balance sheet, not one row of it. ||| 0.6
+Then wheat. Up twenty-two and a half cents in Chicago, to six fifty-two and three quarters. Kansas City up twenty-one and a half. Half of that is the report. The other half is the Black Sea. ||| 0.5
+Tuesday's rumour of safe-passage talks died overnight. Ukrainian drones hit Novorossiysk and idled its two big grain terminals. Combined capacity, more than fifteen million tonnes a year. ||| 0.4
+On Tuesday the market priced trapped grain getting out. On Wednesday it priced Russian loading capacity going dark. Same mechanism we walked through yesterday. Running in reverse. ||| 0.5
+Turkey is floating a plan for two protected corridors, one for each coast. Nobody has signed anything. ||| 0.5
+And think about the ships. Every vessel anchored off Novorossiysk this morning is on a clock. The clock is contractual, and it is denominated in dollars per day. ||| 0.4
+That clock is today's subject. ||| 0.8
+Strip a physical trade down to its skeleton and three questions are left. Who arranges the ship. Who insures the cargo. And at what exact moment it stops being the seller's problem. ||| 0.5
+The trade answers all three with three letters. Incoterms. A standard vocabulary of risk allocation, kept by the International Chamber of Commerce. ||| 0.5
+F O B, free on board, you know from episode two. The seller delivers the cargo over the ship's rail at the load port. From that moment it travels at the buyer's risk. The buyer charters the vessel. The buyer insures. The buyer owns the voyage. ||| 0.5
+C F R is cost and freight. Now the seller pays for the voyage. They charter the ship and deliver it to a named destination port. ||| 0.35
+And C I F adds one word. Cost, insurance, freight. The seller also buys the marine insurance. ||| 0.6
+Now the detail that catches every newcomer. In all three terms, risk passes at the load port. ||| 0.4
+Sit with that. On a C I F cargo, the seller pays the freight all the way to Qingdao. The seller buys the insurance. And the cargo still travels at the buyer's risk. ||| 0.4
+If the ship founders mid-ocean, that is the buyer's loss. The buyer claims on the very policy the seller bought. ||| 0.4
+Cost and risk travel separately. The letters tell you who pays. They also tell you, quietly, who is exposed. ||| 0.7
+So why would anyone buy F O B instead of C I F? Control, and freight. ||| 0.35
+An importer with its own chartering desk buys F O B and keeps the freight economics for itself. A buyer with no shipping desk pays up for C I F and outsources the problem. Freight is a market of its own, and whoever fixes the ship carries that market's risk. More on that in episode ten. ||| 0.7
+Now put a real cargo through the chain. Sixty thousand tonnes of soybeans, F O B Santos, sold at a differential against November. The episode two cargo, one step further down the pipe. ||| 0.5
+At yesterday's board, beans are worth about four hundred thirty-four dollars a tonne. So this is a twenty-six million dollar object. Hold that number. ||| 0.6
+The contract gives a laycan, the loading window. Fifteenth to the twenty-fifth of November. ||| 0.35
+The buyer nominates a vessel. Names her to the seller, and she must present inside that window. ||| 0.4
+She arrives on the eighteenth. The master tenders notice of readiness. N O R. The formal declaration, I have arrived, and I am ready to load. ||| 0.4
+That piece of paper starts the clock. ||| 0.6
+The clock is called laytime, the time the contract allows for loading. Say ten thousand tonnes per weather working day. A day that counts only if the weather lets you work. Rain stops the work, and rain stops the clock. ||| 0.4
+Sixty thousand tonnes at ten thousand a day. Six days of allowed laytime. ||| 0.5
+But Santos has a queue. Remember the line-up from episode two, the list of vessels waiting for a berth. Loading takes nine days instead of six. ||| 0.5
+Three days over. The charter party, the contract hiring the ship itself, fixes demurrage at twenty-four thousand dollars a day. Demurrage, the penalty for holding a vessel beyond her laytime. ||| 0.4
+Three days. Seventy-two thousand dollars. ||| 0.7
+Here is how those three days sound on the desk. ||| 0.5
+OPS: She tendered N O R at oh six hundred. Terminal gives us a berth Saturday. ||| 0.25
+TRADER: When does the clock start? ||| 0.25
+OPS: It's already running. Turn time expired at noon. ||| 0.25
+TRADER: What did we fix her at? ||| 0.25
+OPS: Twenty-four a day. Line-up says three over if the queue doesn't move. ||| 0.25
+TRADER: That's seventy-two. Send me the line-up and get on to the terminal. ||| 0.6
+Notice what was not said. Nobody mentioned the cargo, or the price. Twenty-four a day is twenty-four thousand dollars of demurrage. Three over is three days beyond laytime. The whole conversation is about time, because time is the only thing still moving. ||| 0.7
+Now set seventy-two thousand against the trade. ||| 0.4
+Episode two's margin on this cargo was thirty cents a bushel. Six hundred sixty thousand dollars. The market has not moved. The differential has not moved. And eleven percent of the margin is gone. ||| 0.5
+And underneath, the quiet cost. Twenty-six million dollars of beans, financed at six percent, is over four thousand dollars a day of interest. That meter never stops at all. ||| 0.6
+It cuts the other way too. Load faster than laytime and the shipowner pays you despatch. Customarily half the demurrage rate. ||| 0.4
+A terminal that turns the ship around in four days earns real money for the charterer. Which is why an execution desk is a profit centre, not admin. A good operator wins the demurrage claim, earns the despatch, and saves the day the trader gave away in the negotiation. ||| 0.7
+So who actually pays the seventy-two thousand? Under F O B, the buyer holds the charter, so the shipowner invoices the buyer. ||| 0.4
+But if the delay was the seller's fault, cargo not ready, documents late, the buyer passes the claim up the sales contract. Demurrage claims cascade through a whole string of contracts. They are fought line by line, months later, and the battlefield is a document called the statement of facts, the port's log of everything that happened and when. ||| 0.7
+The sharper edge is the laycan itself. ||| 0.4
+Miss it as the buyer, your nominated vessel shows up on the twenty-sixth, and the seller can walk. Cancel, and resell the cargo. ||| 0.4
+Miss it as the seller, cargo not ready when the ship is, and you are paying that ship to sit, or facing a cancelled contract in a market that moved against you. ||| 0.4
+If the board rallied forty cents while you fumbled, a one-day slip just put the whole flat-price move on your book, unhedged. That is how a small execution failure becomes a contractual liability. Not through drama. Through a date. ||| 0.8
+One more layer. The paper. ||| 0.5
+At loading, the cargo becomes documents. A draft survey fixes the weight, read the ship's displacement before loading and after, the difference is the cargo. ||| 0.4
+A quality certificate is issued at the load port, and in most grain contracts that certificate is final. If discharge finds something different, the load-port certificate still governs. ||| 0.5
+And the bill of lading. Receipt for the goods, contract of carriage, and document of title, all in one piece of paper. Whoever holds the bill owns the cargo. ||| 0.4
+Twenty-six million dollars, moving at the speed of a courier envelope. ||| 0.6
+The date on that bill is sacred. It proves the cargo shipped inside the contract window. Backdating a bill of lading by one day is not sloppiness. It is fraud, and it has sunk trading houses. ||| 0.8
+So what to keep from today. ||| 0.5
+Three letters allocate the trade. F O B, C F R, C I F. And they allocate cost and risk separately. Risk passes at the ship's rail even when the seller is paying the freight. ||| 0.5
+Execution is a clock. Laycan, nomination, notice of readiness, laytime, then demurrage or despatch. Every tick of it is contractual money. ||| 0.5
+And the cargo is its paper. Draft survey for weight. Certificate final at load for quality. The bill of lading for title. ||| 0.5
+None of this shows on a screen. Which is exactly why the margin lives here. ||| 0.7
+Tomorrow, wheat. The map and the screens. Why two wheats at the same flat price are not the same wheat, and why it takes three exchanges to price one grain. ||| 0.5
+The quiz is in the notes and the email. Three days on the clock, and a laycan question with teeth. This was Soft Commodity Trading. See you tomorrow. ||| 0.5

package/fetch_context.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+Soft Commodity Trading - continuity fetcher.
+
+Pulls what the show has already aired into the working directory, so today's
+episode builds on real history instead of guessing:
+
+  covered.md      running log of every episode aired and what it covered
+  prev_epNN.md    notes for the J-1 and J-3 episodes, for the quiz
+
+Notes for older episodes live in the npm versions that published them, so this
+walks back through published versions until it finds each one.
+
+Usage:
+    python3 fetch_context.py --episode 12 --outdir .
+
+Exit code is always 0: missing history is normal early on and must never block
+an episode. Prints FETCHED= / MISSING= lines so the caller knows what it got.
+"""
+import argparse
+import json
+import os
+import sys
+import tarfile
+import tempfile
+import urllib.request
+
+PKG = "@sdelsad/commodity-desk-daily"
+REGISTRY = "https://registry.npmjs.org"
+
+
+def registry_meta():
+    try:
+        with urllib.request.urlopen(f"{REGISTRY}/{PKG.replace('/', '%2f')}", timeout=30) as r:
+            return json.load(r)
+    except Exception as exc:
+        print(f"  ! registry unreachable ({exc})")
+        return None
+
+
+def sort_versions(versions):
+    def key(v):
+        try:
+            return tuple(int(x) for x in v.split("."))
+        except ValueError:
+            return (0, 0, 0)
+    return sorted(versions, key=key, reverse=True)
+
+
+def extract_from(version, wanted, outdir, workdir):
+    """Extract any of `wanted` filenames present in this version's tarball."""
+    name = PKG.split("/")[-1]
+    url = f"{REGISTRY}/{PKG}/-/{name}-{version}.tgz"
+    tgz = os.path.join(workdir, f"{version}.tgz")
+    found = {}
+    try:
+        urllib.request.urlretrieve(url, tgz)
+        with tarfile.open(tgz) as tar:
+            for member in tar.getmembers():
+                base = os.path.basename(member.name)
+                if base in wanted and base not in found:
+                    fh = tar.extractfile(member)
+                    if fh:
+                        found[base] = fh.read()
+    except Exception:
+        pass
+    finally:
+        if os.path.exists(tgz):
+            os.unlink(tgz)
+    return found
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--episode", type=int, required=True)
+    ap.add_argument("--outdir", default=".")
+    ap.add_argument("--max-versions", type=int, default=25,
+                    help="how far back to walk through published versions")
+    args = ap.parse_args()
+
+    os.makedirs(args.outdir, exist_ok=True)
+    meta = registry_meta()
+    if not meta:
+        print("MISSING=covered.md")
+        return 0
+
+    versions = sort_versions(list(meta.get("versions", {}).keys()))[: args.max_versions]
+
+    # which episode notes we still want
+    targets = {}
+    for offset in (1, 3):
+        n = args.episode - offset
+        if n >= 1:
+            targets[f"ep{n:02d}.md"] = f"prev_ep{n:02d}.md"
+
+    want = set(targets) | {"covered.md", "glossary.md"}
+    got = {}
+
+    workdir = tempfile.mkdtemp(prefix="cdd-ctx-")
+    try:
+        for version in versions:
+            if not want - set(got):
+                break
+            for base, blob in extract_from(version, want - set(got), args.outdir, workdir).items():
+                got[base] = blob
+    finally:
+        import shutil
+        shutil.rmtree(workdir, ignore_errors=True)
+
+    for base, blob in got.items():
+        outname = targets.get(base, base)
+        path = os.path.join(args.outdir, outname)
+        with open(path, "wb") as fh:
+            fh.write(blob)
+        print(f"FETCHED={outname} ({len(blob):,} bytes)")
+
+    for base in want - set(got):
+        print(f"MISSING={targets.get(base, base)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/generate_audio.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Soft Commodity Trading - audio generator.
+
+Turns a segmented spoken script into a podcast-ready mp3, with calibrated
+pauses between segments so the narration breathes like a human reading.
+
+Script format: one segment per line,
+    TEXT ||| PAUSE_SECONDS
+Blank lines and lines starting with '#' are ignored. A line with no '|||'
+gets DEFAULT_PAUSE.
+
+Usage:
+    python3 generate_audio.py script.txt ep02.mp3 [--voice am_michael] [--speed 0.97]
+
+Exit codes: 0 ok, 1 usage/IO error, 2 synthesis error.
+"""
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+
+DEFAULT_PAUSE = 0.4
+MAX_PAUSE = 3.0
+
+
+def parse_script(path):
+    """Return [(text, pause_seconds), ...] from a segmented script file."""
+    segments = []
+    with open(path, encoding="utf-8") as fh:
+        for lineno, raw in enumerate(fh, 1):
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "|||" in line:
+                text, _, pause_str = line.rpartition("|||")
+                text = text.strip()
+                try:
+                    pause = float(pause_str.strip())
+                except ValueError:
+                    print(f"  ! line {lineno}: bad pause {pause_str!r}, using default")
+                    pause = DEFAULT_PAUSE
+            else:
+                text, pause = line, DEFAULT_PAUSE
+            if not text:
+                continue
+            segments.append((text, max(0.0, min(pause, MAX_PAUSE))))
+    return segments
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("script")
+    ap.add_argument("output", help="output .mp3 path")
+    ap.add_argument("--voice", default="am_michael")
+    ap.add_argument("--speed", type=float, default=0.97)
+    ap.add_argument("--bitrate", default="96k")
+    ap.add_argument("--kokoro-dir", default=os.path.expanduser("~/kokoro"))
+    args = ap.parse_args()
+
+    try:
+        import numpy as np
+        import soundfile as sf
+        from kokoro_onnx import Kokoro
+    except ImportError as exc:
+        print(f"Missing dependency ({exc}). Run setup.sh first.", file=sys.stderr)
+        return 1
+
+    segments = parse_script(args.script)
+    if not segments:
+        print(f"No usable segments in {args.script}", file=sys.stderr)
+        return 1
+    words = sum(len(t.split()) for t, _ in segments)
+    print(f"[audio] {len(segments)} segments, {words} words, voice={args.voice}")
+
+    model = os.path.join(args.kokoro_dir, "kokoro-v1.0.onnx")
+    voices = os.path.join(args.kokoro_dir, "voices-v1.0.bin")
+    for path in (model, voices):
+        if not os.path.exists(path):
+            print(f"Missing model file {path}. Run setup.sh first.", file=sys.stderr)
+            return 1
+
+    kokoro = Kokoro(model, voices)
+    chunks, rate, failures = [], 24000, 0
+    for i, (text, pause) in enumerate(segments, 1):
+        try:
+            samples, rate = kokoro.create(text, voice=args.voice, speed=args.speed)
+            chunks.append(samples)
+        except Exception as exc:  # one bad segment must not kill the episode
+            failures += 1
+            print(f"  ! segment {i} failed ({exc}); skipping")
+        chunks.append(np.zeros(int(rate * pause), dtype="float32"))
+        if i % 10 == 0 or i == len(segments):
+            print(f"  .. {i}/{len(segments)}")
+
+    if failures == len(segments):
+        print("All segments failed.", file=sys.stderr)
+        return 2
+
+    audio = np.concatenate(chunks)
+    minutes = len(audio) / rate / 60
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
+        wav = tmp.name
+    sf.write(wav, audio, rate)
+    subprocess.run(
+        ["ffmpeg", "-y", "-loglevel", "error", "-i", wav, "-b:a", args.bitrate, args.output],
+        check=True,
+    )
+    os.unlink(wav)
+
+    size = os.path.getsize(args.output)
+    print(f"[audio] {args.output} | {minutes:.1f} min | {size:,} bytes | {failures} failed segment(s)")
+    print(f"DURATION_SECONDS={int(len(audio) / rate)}")
+    print(f"SIZE_BYTES={size}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,12 +1,12 @@
-{
-  "name": "@sdelsad/commodity-desk-daily",
-  "version": "1.0.17",
-  "description": "Soft Commodity Trading - Ep 5: Wheat: The Map and the Screens",
-  "license": "CC-BY-4.0",
-  "keywords": [
-    "podcast",
-    "commodities",
-    "trading",
-    "education"
-  ]
-}
+{
+  "name": "@sdelsad/commodity-desk-daily",
+  "version": "1.13.2",
+  "description": "Soft Commodity Trading - Ep 5: Wheat: The Map and the Screens",
+  "license": "CC-BY-4.0",
+  "keywords": [
+    "podcast",
+    "commodities",
+    "trading",
+    "education"
+  ]
+}