/categories flows: the Flow view, level markers, state strip and the week in words

[mspinola]

PR 3 of the plan in cotmetrics docs/design/cot-flows.md (mspinola/cotmetrics#51): the state strip, the level markers and the week in words, on /categories. Stacked on #140 (base claude/cot-flows-heatmap-panel), and like it a draft until mspinola/cotmetrics#52 merges, because it reads columns cotmetrics 0.15.0 adds; the cotmetrics half of this PR is the third commit on #52. The view computes none of what it draws.

What it adds

• The Flow view, a third Layout choice beside Overlay and Small multiples, which is the Cowork mockup (cotmetrics docs/analysis/2026-09-26-cot-view-proposed-gold.png): price with open interest, every selected cohort's flow z with the counterparty row and the level markers, and every cohort's positioning index shaded above 80 and below 20 (the triangles' cutoffs, shaded here only), as three full-width panels on one time axis. The plot selector and Cols grey out while it is chosen. The plan had claimed small multiples already gave this layout; it did not, and that is corrected in the plan.
• Level markers. A triangle on each flow cell whose active flow (|z| > 1) left the top of the range (up, prior week's index above 80) or the bottom (down, below 20), from cotmetrics' Flow Level Mark. The level is the page's own range index one week earlier, so it is the level the Positioning Index panel draws; the marked cell's hover adds "from level 86 of the 26-week range". Context for reading a cell only: the cutoffs are the Cowork mockup's, unsearched, and the level x flow cells behind them were descriptive and on gold alone.
• Small multiples, flow column: the counterparty directly under the cohorts. Where it is one cohort already drawn (DOW and most TFF markets, the report defaults) that row is titled "(counterparty)" instead of being repeated; a multi-member composite (Gold) gets its own one-row heatmap. Then, on state-eligible markets, a three-lane strip of the opinion cohorts' signs, with a tick lane above it on the split weeks (all three active, not all agreeing). TFF equities, rates and crypto get no strip row rather than an empty one.
• The week in words (components/flow_copy.py, store-free) under the graph: positions as of the weekday and date, each opinion cohort's net change with both legs and its z, the marked level, the counterparty always (members, and whether measured for the market or the report default), the cohorts on neither side, the sum-to-zero line, and the state as "a vocabulary label, not a signal" or why there is none (ADR-0005, via state_eligible).

Copy rules, held by tests over every week of the test frame: none of the Home board's ranking words, nothing about what follows a state or a flow from an extreme (the state's pre-registered test failed the gauntlet in mspinola/cotmetrics#50), "signal" only as "not a signal", no em dash, and no release date (the resolved one lives in cotdata's vintage store; the derived one is wrong on holiday weeks).

What the running app decided (recorded in the plan): the plan's line-only box around a split week is the whole cell at one to two pixels a week and painted solid bars over the lanes, so it became a tick lane above them; and plotly.js draws only subplots some trace references, so the empty cells beside the flow column lost their axes, their row label and the bottom row's dates until each got a trace with no points.

Review (one independent pass over both repos, verified on 13 real markets): the prior-week level aligns exactly and sum-to-zero is exact on every week. Fixed from it: the caption contradicted its own sum-to-zero line where a cohort is measured into both sides (Other Reportable on silver, copper, orange juice), now said explicitly; the clientside autoscale flipped the strip on a zoom to the start of history, now it leaves heatmap axes alone; z and level rounding could contradict the words at the cutoffs; level_marks in cotmetrics aligned mismatched indexes to all NA, now it raises; the strip hover lost its redundant date line (about half a megabyte on gold); plus wording by roles source, no ADR citation in public copy, and tests that could pass vacuously.

Verification

• Suite 956 passed (916 on /categories: the Flow view, price, weekly cohort flow and positioning index on one axis #140), ruff clean, run as CI runs it (PYTHONPATH on the Raise the cotmetrics floor to the version /exposure needs #52 tree, empty stores). 40 new tests across test_category_traces.py and the new test_flow_copy.py, including a render of the page callback with a stub indexer.
• Looked at in the running app on Gold (Flow view; facet with Net Positions, Positioning Index and the flow panel; 375 px phone), S&P 500 and DOW (TFF, no state). The caption's net changes sum to zero on both weeks read.
• check_dep_floors stays red until Raise the cotmetrics floor to the version /exposure needs #52 merges, as on /categories: the Flow view, price, weekly cohort flow and positioning index on one axis #140.

Merge order: cotmetrics #51, #52, then #140, then this one (retarget to main after #140 squash-merges).

🤖 Generated with Claude Code

[mspinola]

Superseded by #140. The scope was cut back to PR 1 and PR 2 of cotmetrics docs/design/cot-flows.md (the handoff's "Scope, restated" block): the Flow view now lives on #140 with cotmetrics' collapsed rows and the mockup's decile markers; the state strip, the week-in-words caption and the small-multiples flow rows are out of scope.