@sdelsad/commodity-desk-daily 1.0.17 → 1.13.2

package/STYLE.md

@@ -0,0 +1,439 @@
+# Soft Commodity Trading — show bible
+
+Read this before writing any episode. It defines what the show is and how it
+sounds. The daily prompt tells you *which* episode to make; this file tells you
+*how* to make it.
+
+## The one rule about output
+
+**Write `epNN.md`. Do not hand-write the page or the e-mail.**
+
+`build_page.py` and `build_email.py` both render that one file. The e-mail used
+to be improvised each morning against a section spec, and it drifted — so the
+spec now lives in code:
+
+```bash
+python3 package/build_email.py --notes epNN.md --number N --title "..." \
+  --dek "..." --audio-url URL --page-url URL --duration 739 --date "..." \
+  --charts URL1,URL2,URL3 --glossary glossary_final.md \
+  --drill-index 5 --drill-file conversions.md --out epNN_email.html
+```
+
+It emits the eight sections in their fixed order and the plain-text
+alternative beside them. The conversion drill is pulled from `conversions.md`
+by index, so it no longer has to be retyped; what still has to be *written* is
+the one fresh exercise for the drill (put it in the quiz area and its answer
+with the solutions), because the point is different numbers every cycle.
+
+Everything below is about the substance that goes into `epNN.md`. Getting that
+right is the whole job; the presentation is already handled.
+
+## What the show is
+
+A daily ~10-minute briefing on the physical commodity trading business, for
+anyone learning how it actually works: aspiring traders, analysts, students,
+people newly on a desk. It is a **public show**, freely shared.
+
+Assume the listener is a strong quantitative graduate who has studied
+derivatives — futures, options, hedging are known ground. Do not re-teach
+pricing theory. Teach at **desk level**: how traders talk, what they watch, what
+they actually do with these instruments between 7am and 6pm.
+
+## Density — the rule that matters most
+
+The listener understands a clean explanation in three minutes. An episode that
+spends ten minutes on one such concept is padding, and padding is the fastest
+way to lose them.
+
+- Every episode carries **two substantive concepts**, or **one concept taken to
+  real depth** — mechanics, edge cases, failure modes, second-order effects.
+  Never one idea stretched across ten minutes.
+- State the concept cleanly, work one concrete numerical example, then **go
+  somewhere they could not have gone alone**: what breaks, what the desk argues
+  about, why the obvious move is wrong.
+- Say each thing **once**. No "as we said earlier", no restating the definition
+  in three different ways, no summary that repeats the body verbatim. The
+  takeaway names what to remember — it does not re-explain it.
+- Cut every sentence that only announces what you are about to say.
+- If you finish the brief with time left, do not stretch — add depth: a second
+  worked example with different numbers, a failure case, a subtlety
+  practitioners get wrong.
+
+Test before writing: *what does this episode teach that an intelligent person
+could not have worked out from the definition alone?* If the answer is thin,
+the episode is too thin.
+
+## Framing rules — non-negotiable
+
+- Never address a specific individual. No names. No references to a listener's
+  employer, job, internship, start date, or plans. Nothing like "your new
+  employer", "when you start in September", "on your first day".
+- "You" is allowed **only** in the generic teaching sense: "say you're long
+  fifty thousand tons", "you're hedged — so what's left?".
+- Trading houses (ADM, Bunge, Cargill, Louis Dreyfus, COFCO, Olam, Viterra,
+  Glencore) appear as concrete examples and in history segments. Keep it light
+  and factual, never promotional, and **rotate** which one you use so no single
+  firm dominates the show.
+- Everything published — audio, written edition, quiz, solutions, notes file —
+  must stand alone as a show anybody could learn from.
+
+## How it sounds
+
+Written for the ear, not the page.
+
+- Most sentences under 15 words. One idea per sentence.
+- Oral beats and deliberate fragments: "Space. Time. Form."
+- Direct address in the generic sense. Rhetorical questions to open a section.
+- Repeat key terms on purpose — the listener cannot scroll back.
+- Always at least one **worked number**: a margin, a spread, a cargo P&L.
+  Abstractions do not survive audio.
+- Signposting: "Three things move basis. Here's the first."
+- Never read a list aloud as a list. Turn it into a sequence with beats.
+
+Avoid: corporate filler, throat-clearing intros ("In today's episode we will
+explore..."), stacked subordinate clauses, and any sentence you could not say
+out loud in one breath.
+
+## Structure of every episode
+
+1. **Cold open** (2–3 segments): a hook — a surprising claim, a question, a
+   number. Name the show, the episode number and the topic inside it, not
+   before it. The spoken identifier is exactly: *"This is Soft Commodity
+   Trading, episode N."* Never any other name — the show was previously called
+   *Commodity Desk Daily* and that name must not appear anywhere any more.
+2. **Market pulse** (150–250 words): today's real moves, researched live.
+   Concrete figures only if sourced today. Never invent a price. **It must
+   build, not repeat** — see below.
+3. **The lesson** (the bulk): story-driven, desk-level, one worked example
+   carried through. Callbacks to earlier episodes only when they were genuinely
+   covered — check the context files.
+4. **Takeaway** (3–4 segments): what to actually remember, in plain terms.
+5. **Trail** (1–2 segments): tomorrow's topic, and a pointer to the quiz.
+
+## Teaching the language of the desk
+
+Concepts can be read anywhere. How a desk actually *talks* cannot — this is one
+of the show's most valuable products. Treat units, conventions and market
+speech as first-class content, not decoration.
+
+### The unit moment (15–20 seconds, every time a unit or convention first appears)
+
+Three beats, then move on:
+
+1. **What it measures** — "a bushel is a volume measure, not a weight."
+2. **The number that matters** — "sixty pounds for soybeans and wheat,
+   fifty-six for corn, so the tonne conversion differs by commodity. A Chicago
+   contract is five thousand bushels, quoted in cents per bushel."
+3. **One sentence of why** — "it comes from the English grain trade, where
+   grain was measured by volume before it was weighed; the U S kept it, the rest
+   of the world moved to dollars per tonne — which is why a trader converts
+   between the two all day."
+
+Do this for: bushels, cents/bushel, lots and contract sizes, dollars per tonne,
+cwt, metric vs short tons, points and ticks, differentials ("plus eighty"),
+laycan, and any quoting convention the episode uses. Never let a unit go by
+unexplained the first time — and never explain it twice.
+
+### Desk dialogue
+
+When a quoting convention or a piece of market language has just been
+introduced, and the topic is one where the language genuinely matters (basis,
+differentials, spreads, tenders, market color, chartering), stage a short
+exchange — 20–30 seconds, four to six lines — then spend ten seconds unpacking
+what just happened.
+
+Write dialogue lines with an uppercase speaker label; the audio pipeline renders
+them with two distinct voices, separate from the narrator:
+
+```
+Here is how that trade actually gets quoted. ||| 0.5
+BUYER: November Santos, what have you got? ||| 0.25
+SELLER: I make you plus eighty-five. ||| 0.25
+BUYER: That's rich. Last one I saw trade was plus seventy-eight. ||| 0.25
+SELLER: On prompt, yes. You're asking me for November. ||| 0.6
+Notice what just happened. Neither of them said a price. ||| 0.4
+```
+
+Use at most two speakers per exchange, and keep labels short and consistent
+(BUYER / SELLER, TRADER / BROKER, DESK / EXECUTION). Make the exchange
+*realistic*: clipped, elliptical, no full sentences, no politeness rituals. The
+value is that it sounds like an actual squawk, not a textbook illustration.
+
+No quota: if the day's topic is risk limits or trade finance and a dialogue
+would be forced, skip it. Better none than a fake one.
+
+### Ramp-up (episodes 1 to 4 only)
+
+Early listeners have no vocabulary yet. In the first four episodes, briefly
+re-anchor terms introduced in previous episodes when they reappear — half a
+sentence, in passing ("the differential, the plus-or-minus against futures").
+From episode 5 onward, assume the vocabulary is owned and stop re-explaining.
+
+The audio never dumbs down: the listener should be slightly stretched. The
+written glossary carries the safety net.
+
+### The glossary
+
+Every episode passes its new terms at publish time via `--glossary`, formatted
+`term = definition; term2 = definition2`. Definitions must not contain
+semicolons. The toolkit keeps a cumulative, deduplicated `glossary.md` (first
+definition wins, tagged with the episode that introduced it). Both the e-mail
+and the episode page carry it — collapsed and filterable on the page, in full
+at the foot of the e-mail — so nothing heard in the audio is unrecoverable, and
+the term the reader half-remembers is one search box away on any episode.
+
+This makes the glossary line at publish time load-bearing rather than
+housekeeping. Pass every term the episode introduced, and write the definition
+so it stands alone months later, out of context.
+
+## The market pulse: how to write it
+
+The pulse is a **briefing for a reader**, not notes about the show. Two failures
+to avoid absolutely.
+
+**Never write about the episode.** No "today we go one level deeper than
+yesterday", no "as we'll see later". The listener does not care how the show is
+constructed. Say what the market did.
+
+**Never chain a mechanism through punctuation.** This is unreadable:
+
+> *yield × harvested acres → production; + carry-in → supply; − feed, exports,
+> ethanol and food → ending stocks; ÷ total use → stocks-to-use*
+
+If a mechanism has steps, either walk it in real sentences (fine in audio,
+where it unfolds slowly) or lay it out as a short list or table (in the written
+edition). Never as a run-on of semicolons and arrows.
+
+### The written pulse
+
+- Open with the single thing that matters today, in a short bold line.
+- Give levels in a small **table** — commodity, contract month, price — rather
+  than burying three numbers in a sentence.
+- **Head the move column `Change`.** The renderer colours that column — a
+  restrained green up, red down — and prints the sign explicitly, so `0.6` in a
+  change column becomes `+0.6`. Write the moves the way you would say them
+  (`−0.6%`, `+21½¢`, `~unchanged`); the sign and the hue are added for you.
+  Numeric columns are detected and right-aligned on their own.
+- Then 60–120 words of plain prose: what moved, why, and what to watch.
+- Include the geopolitical read (see below) — acute if there is news, structural
+  otherwise.
+- One idea per sentence. Any term not already in `glossary.md` gets three words
+  of explanation, or is not used.
+- Prefer the concrete over the technical: "a full vessel queue at Santos" beats
+  "elevated origin basis pressure".
+
+### The geopolitical read — every day, without exception
+
+Agricultural markets are moved as much by governments and conflict as by
+weather. The pulse must carry a geopolitical dimension **every episode**, not
+only when something explodes.
+
+Two modes:
+
+- **Acute** — something happened: strikes on port or energy infrastructure, a
+  new sanction or its enforcement, an export ban or tax, a tender cancelled, a
+  shipping lane rerouted, an insurance market repricing war risk. Cover it, and
+  above all give the **transmission mechanism to price**.
+- **Structural** — on quiet days, take one background theme and explain a piece
+  of it. These are slow forces that set the map everyone trades on.
+
+**Always name the mechanism.** "War, so prices up" is not analysis. The chains
+that actually matter:
+
+- **Export capacity** — damaged loading infrastructure, mined or blocked
+  waters, closed corridors: supply exists but cannot leave.
+- **Freight and insurance** — war-risk premium on hulls, longer routings,
+  bunker cost. This lands on the arb before it lands on the flat price.
+- **Flow substitution** — buyers switch origin, which widens the basis at the
+  new origin and collapses it at the old one. Often the biggest P&L effect.
+- **Policy retaliation** — tariffs, quotas, licence regimes, retaliatory
+  buying bans that redirect entire trade axes.
+- **Inputs** — sanctions or gas prices hitting fertiliser, which shows up two
+  seasons later in planted acres and yields.
+- **Currency and payment** — devaluation changing farmer selling behaviour,
+  payment channels and settlement currency shifting who can transact.
+
+Standing structural themes to rotate through on quiet days: the Black Sea's
+permanent reshaping of wheat flows and the corridor economics that followed;
+Red Sea routing and its cost on Asia-Europe freight; the China–Brazil soybean
+axis and what it did to US export share; India's on-again-off-again rice and
+sugar export policy; fertiliser supply and the gas price; state reserve
+building as a form of insurance; sanctions regimes and the shipping and
+insurance workarounds that grow around them.
+
+**Tone: analytic, never partisan.** Describe flows, capacity, costs and policy
+as market facts and explain how they reach a price. Do not take sides in a
+conflict, do not speculate about military outcomes, do not editorialise about
+who is right. If a fact is contested, say that it is contested and give the
+market's reaction rather than adjudicating it. Never invent an event: if the
+research turned up nothing acute today, use a structural theme instead.
+
+Keep it to 40–80 words inside the pulse. Episode 26 treats the Black Sea and
+policy shocks in depth — the daily read is a briefing, not that lesson.
+
+### Connect the pulse to the lesson
+
+The pulse and the lesson must not be two strangers stapled together.
+
+- **When a real link exists, use it as the bridge into the lesson.** A WASDE day
+  leads naturally into balance sheets; a freight spike leads into the arb; a
+  Brazilian frost leads into volatility. Say the link in one sentence and move
+  on — do not force it into a theme.
+- **When there is no honest link, do not invent one.** Close the pulse cleanly
+  ("that's the tape — now to today's subject") and start the lesson.
+- Best of all: pick the *example* in the lesson from what is live in the market
+  that morning. If wheat is the mover, use wheat numbers in the worked example.
+  The lesson stays on curriculum; only its illustration follows the news.
+
+## The market pulse must escalate, never repeat
+
+`covered.md` records the pulse topics of previous episodes. Read it first.
+
+Recurring events — a WASDE, a crop tour, a policy deadline, an ongoing weather
+story — are worth several mentions across days, but **each mention must go
+deeper than the last**. Prices are refreshed daily and that is fine; the
+*commentary* is what must not loop.
+
+Worked example, a week with WASDE on Wednesday:
+
+- **Monday** — name it: there is a WASDE on Wednesday, this is what the report
+  is and roughly why the market cares. One or two sentences.
+- **Tuesday** — assume it is known, and go into the mechanics: what the trade
+  expects for yield, where the range of estimates sits, why positioning ahead of
+  it looks the way it does.
+- **Wednesday** — the print itself: the surprise versus expectation, and the
+  reaction.
+- **Thursday** — the aftermath: what the number did to the balance sheet, what
+  it means for basis and spreads over the coming weeks.
+
+If a topic genuinely has nothing new, drop it and cover something else — a
+different commodity, a different exchange, a flow story. Repeating yesterday's
+sentence with today's price is the one thing the pulse must never do.
+
+Record what you covered: the `--covered` line you pass at publish time must end
+with `Pulse: <topics touched, one clause each>` so tomorrow's episode can build
+on it.
+
+## The spoken script format
+
+One segment per line: `TEXT ||| PAUSE`, pause in seconds *after* the segment.
+
+- `0.3` — mid-thought, sentences that flow together
+- `0.5` — after a completed idea
+- `0.7`–`0.8` — after a punchline, or at a section break
+
+Segments are 1–3 short sentences. Total 1400–1600 words of speech ≈ 10 minutes.
+
+TTS constraints: no markdown symbols, no bullet characters. Spell out acronyms
+that are read letter by letter — `U S D A`, `C M E`, `F O B`. Write prices in
+words: "four dollars sixty four", "futures minus twenty".
+
+## The written edition
+
+A genuine article, not a transcript. Flowing paragraphs, normal punctuation and
+spellings (USDA, CME, $4.64), markdown subheadings, a cleanly laid-out worked
+example. Same substance and order as the audio, recomposed for the eye. Someone
+who cannot listen should get the full lesson from it.
+
+Readability rules, since the page and the email are read rather than heard:
+
+- **No semicolon chains and no arrow soup.** Anything with more than two steps
+  becomes a list or a table.
+- **Put numbers in tables**, not in the middle of sentences. A four-line P&L
+  table is read in two seconds; the same figures in prose are read twice and
+  still not retained.
+- **One idea per sentence**, and no sentence longer than about 25 words.
+- **Never describe the show itself** — no "as we said yesterday", no "this
+  episode covers". Write the substance directly.
+- Bold the term being defined, not whole clauses. If everything is bold,
+  nothing is.
+
+## Charts — two or three in every episode
+
+A number is a point. A chart is a shape, and the shape is what the listener
+actually needs: a trend, a spread, a decomposition, a before-and-after. Every
+episode carries **two to three charts**, and they are not decoration.
+
+Where they go: **one in the market pulse**, always, whenever there are figures
+worth a shape. **One or two in the lesson**, illustrating the mechanism being
+taught. A chart that only repeats a sentence should be cut.
+
+Write them as fenced `chart` blocks inside `epNN.md`. `build_page.py` turns each
+one into an inline SVG on the page and, with `--charts-prefix`, into a PNG for
+the e-mail. Three shapes cover almost everything:
+
+| Type | Use it for |
+|---|---|
+| `line` | anything through time, and the forward curve (contract months on the x axis) |
+| `bar` | like-for-like comparison: costs, origins, before and after |
+| `waterfall` | any economics decomposition: the arb, the crush, the carry, a P&L bridge |
+
+Set `"mode": "index"` on a line chart to rebase every series to 100 at the first
+point. Use it whenever two markets trade at different levels, otherwise the
+cheaper one flatlines at the bottom and the chart says nothing.
+
+Rules:
+
+- **Never invent a number.** Every point comes from something researched today,
+  or from the worked example the episode is teaching. If the series is not
+  sourced, there is no chart.
+- **Always give `unit`, `source` and a `caption`.** The caption states the
+  takeaway, not the contents: "Corn led the fall, and the spread went with it",
+  never "Corn and wheat prices over time".
+- **Keep `title` to about six words.** It sets in large type on both outputs.
+  Captions and sources wrap onto as many lines as they need, so they can be
+  full sentences — the caption is doing the teaching, and in an e-mail with
+  images turned off it is the only thing the reader gets.
+- **Keep x-axis labels short.** They share the width between them: eight date
+  labels are fine, three long phrases are the practical limit on a bar chart.
+- Use `null` for a missing print. It draws a gap, which is honest. A zero is a
+  lie.
+- Two or three series at most. Beyond that it is a table.
+- **The audio must never depend on a chart.** No "as you can see", no "look at
+  the chart". The spoken version says the number and its meaning out loud, and
+  may point at the e-mail once, at most.
+
+Example, the arb decomposed:
+
+```chart
+{"type":"waterfall","unit":"c/bu","title":"Santos to Shandong, one Panamax",
+ "caption":"A dollar of flat price nets to zero. Ten cents of basis is a third of the trade.",
+ "source":"Worked example, episode 2",
+ "steps":[{"label":"Gross spread","value":100,"kind":"base"},
+          {"label":"Freight","value":-60},
+          {"label":"Finance, insurance, port","value":-10},
+          {"label":"Margin","kind":"total"}]}
+```
+
+## The quiz
+
+Three blocks: today (J-0), the previous episode (J-1), three episodes back
+(J-3) — 2–3 questions each, skipping blocks whose episode number is below 1.
+
+Base J-1 and J-3 questions on what those episodes **actually said** — their
+notes are fetched into the working directory. Never quiz on material the show
+has not covered.
+
+Questions must require application and reasoning. Good: "You're long 60,000 t
+of physical beans hedged with futures. Freight rallies twenty dollars before
+you fix the vessel. Where does that show up in your P&L, and was your hedge
+wrong?" Bad: "What does FOB stand for?"
+
+Write full model solutions: the reasoning, the numbers, and the trap the
+question was testing.
+
+**Number them `**Q1.**` and `**A1.**`, one paragraph opener each.** The page
+turns every answer into its own reveal, matched to its question by that number,
+so a reader can check Q1 without seeing Q2. Answers that are not numbered, or
+numbered differently from their questions, fall back to a single lump.
+
+## Continuity
+
+Before writing, read the context files fetched into the working directory:
+
+- `covered.md` — a running log of every episode aired and what it covered.
+  Use it to avoid repeating material and to make callbacks that are real.
+- `prev_epNN.md` — the notes for J-1 and J-3, for the quiz.
+
+If a concept was already explained in depth, reference it in one line and move
+on. The show should feel like it is building, not resetting every morning.