The stale 119 was the least of it. A parallel audit of the repo against the live API found
defects that would make an agent following this playbook produce wrong answers or 403s.
Counts and the glossary:
- 120 metrics, not 119; 122 physical, not 121; quality is 11 physical / 9 sold, not 10/8.
- `baseAsset` was MISSING from a glossary that claims to list every metric — undocumented
from the day migration 007 added it. Wording taken from the live catalog entry.
- Reconciled in both directions: 0 documented keys that do not exist, 0 live keys missing.
- The "(declared `ratio`)" note on the two DepthReachPct rows is gone — that unit fix shipped.
Playbook errors, each verified against api/src:
- `/v1/latest` buckets at the CALLER'S PLAN granularity, not 5m (free 1d, pro 1h). A free
key's "latest" can be a day old and nothing in the response says so. The file said 5m.
- `5m` is max/ultra only and asking finer than the plan floor 403s, so the default advice
("hours to a few days -> 5m") failed for every free and pro key. Also removed a reference
to `1m` granularity: no such interval exists, the set is 5m/1h/1d.
- FIVE columns 400 the whole request if named in `columns=` (bookSynced, missingTrades,
quoteAsset, baseAsset, enrichmentTs) — the file warned about one and framed the two
harmless internal ones as the danger. Nothing in the catalog marks them.
- There is NO spread metric. The catalog has bestBid/bestAsk and a spread must be derived.
A worked example asked to chart one, and "spread" was mapped to depth keys, which are
resting size, not the distance between the sides.
- History depth is clamped silently and unheadered. Added the rule, because the natural
narration of a short series is "only N days of data" — retention framing, and retention
is infinite.
Also: bybit's maintainedDepth is 1,000 not 200 (the callout contradicted its own 12.5x,
which comes from okx's 400); the Units list was missing `percent` and `seconds`; cmc
liquidity/volume are per-pair, not market-wide; `BLACKFORGE_BASE_URL` is the ORIGIN and
setting it to the documented `/v1` base makes every request 404; only the column gate
degrades silently while venues and intervals 403; and the dashboard nav has no "Keys" —
API keys are on the API screen.
Adds scripts/check-catalog-sync.mjs: glossary completeness both ways, per-row unit and min
plan, per-family counts, and every prose count, against the PUBLIC catalog — no key, no
sibling checkout, and non-zero exit when the catalog cannot be read rather than a false
pass. All five failure modes proven by breaking them on purpose. It documents what it
cannot check: queryability is not exposed on the catalog at all.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Thin orchestration + interpretation layer over the BlackForge MCP tools
(blackforge_catalog/symbols/latest/series/usage) and the `blackforge` CLI.
Teaches the discover -> pick -> call -> interpret playbook, frames every
returned column as a measurement (never a signal/trade call), and handles
plan-based column omission gracefully.
- SKILL.md: measurement-framed trigger description + playbook
- references/metrics-glossary.md: all 103 catalog metrics by family
- references/setup.md: MCP config + CLI install + where to get a key
- scripts/latest-json.sh: optional CLI wrapper
- evals/trigger-eval.json: trigger eval set
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Marc