@graphit/cli 0.1.51 → 0.1.106

package/skills/graphit/references/runtime.md

@@ -0,0 +1,172 @@
+<!--
+SIZE EXEMPTION (reference file)
+Hard limit: 7,168 chars | Exempted ceiling: 14,336 chars
+Current: 12,478 chars (content) - intentionally over the base reference limit.
+Rationale: runtime.md is the consolidated build-time data + entity contract. Its core - the live-data API, the data-graphit-* entity contract, the first-paint loading state, the helper index, and the canonical example - is a single co-load unit: building one live element needs all of it together, so by the co-load test (split a reference only where the agent needs one part without the other) it cannot be split without creating refs that always load together, which the test forbids. The one use-case-clean seam (cache-friendly resolve SQL + the rate-limit budget, needed only for interactive or large dashboards) was deliberately kept inline to preserve the single authoritative contract. This ref loads only on HTML-deliverable turns (just-in-time, not every turn), so the cache cost is bounded.
+Reviewed: 2026-06-17
+Next review: 2026-09-17
+-->
+# Canvas Runtime: Live Data and the Entity Contract
+
+Consult when authoring the dashboard HTML and wiring its data. This is the build-time contract: how the iframe fetches live data, how every visible element becomes a platform entity, how the page paints before data arrives, and how to shape resolve SQL so filter changes stay instant. Design-system tokens and layout CSS live in `graphit-style.md`; this file owns the data wiring.
+
+## Contents
+
+- The live-data API (`graphit.resolve`)
+- The entity contract (`data-graphit-*`)
+- First-paint loading state
+- Cache-friendly resolve SQL
+- Rate-limit budget
+- Helper index (chart / table / kpi / presentation / filters)
+- Canonical entity with live data
+
+## The live-data API
+
+The iframe provides `graphit.resolve()` to fetch live data from cached data sources on every page load. This is how the HTML gets its data. NEVER embed query results as static JS variables (`const data = [...]`) - that freezes a snapshot that never refreshes and breaks provenance.
+
+```js
+const result = await graphit.resolve({
+  sql: "SELECT region, SUM(revenue) AS rev FROM ORDERS_DS GROUP BY region",
+  dataSourceId: "ds_abc123",
+  target: "#chart-container",
+  maxRows: 10000
+});
+// Returns: { columns: string[], data: object[], rowCount: number, truncated: boolean }
+```
+
+- `dataSourceId` is the ID from `graphit ds list`.
+- `target` (optional, a CSS selector or element) shows a blur and spinner overlay while loading and removes it on completion.
+- `maxRows` (optional) defaults to **10,000 rows** and may be raised up to a cap of **50,000 rows**. A dashboard query should aggregate to a chartable grain well under the default; reach for a higher value only for a genuine row-level export, and never above the cap.
+- `result.data` is an array of row objects you render however you want.
+
+CRITICAL: use KB reference syntax (`{{metric:NAME}}`, `{{dim:NAME}}`) inside the resolve `sql` whenever a KB asset exists - the server expands it at query time, which produces the governed trust tier. See `governance.md` for the syntax and trust tiers. The canonical example at the end of this file shows a resolve call with reference syntax in context.
+
+Error handling: `graphit.resolve()` rejects on timeout (120s), bad SQL, or an invalid data source ID. Wrap calls in try/catch and show a user-visible error message in the target element on failure. Verify the SQL returns data via the CLI before embedding it in HTML.
+
+## The entity contract
+
+Every visible element - chart, KPI card, table, text section - must be wrapped so the platform can see it. Without `data-graphit-*` attributes the element is invisible to the platform: no click info, no @ mentions, no KB provenance. Each wrapped element needs ALL FOUR attributes:
+
+```html
+<div data-graphit-id="revenue-trend"
+     data-graphit-label="Revenue Trend"
+     data-graphit-sql="SELECT {{dim:REGION}} AS region, {{metric:REVENUE}} AS revenue FROM ORDERS_DS GROUP BY region"
+     data-graphit-ds="ds_abc123">
+  <!-- chart, KPI, or table content here -->
+</div>
+```
+
+| Attribute | Format | Example |
+|-----------|--------|---------|
+| `data-graphit-id` | Unique kebab-case | `"spend-by-source"` |
+| `data-graphit-label` | Human-readable name | `"Ad Spend by Source"` |
+| `data-graphit-sql` | Executable SQL (HTML-encode the characters `<`, `>`, `&`, `"`) | `"SELECT ..."` |
+| `data-graphit-ds` | Data source ID from `graphit ds list` | `"ds_abc123"` |
+
+KB asset references are derived automatically from `{{metric:X}}` / `{{dim:X}}` templates in the SQL; the governance compiler resolves these and shows KB asset chips in the entity details panel. Missing any one attribute breaks the entity; missing the wrapper entirely makes the element invisible to the platform.
+
+**SQL must be complete and executable.** The platform runs `data-graphit-sql` against the data source when a user opens the entity's details panel. Write the full query from the `graphit.resolve()` call. NEVER abbreviate, truncate, or use placeholders (`FROM ...`, `SELECT ...`, three dots). Use the real DS table name and only columns that exist in the DS - never an invented summary column, a CTE alias, a JS variable name, or prose. If the resolve call uses a CTE, store the full WITH query. If JS builds the SQL dynamically, store one representative executable variant (for example, the default date range).
+
+- **Wrong:** `data-graphit-sql="SELECT INSTALL_TIME, ROIAP_D0 FROM UA_DS"` when the DS has no `ROIAP_D0` column (the chart computes it via CASE) - the details panel errors.
+- **Right:** `data-graphit-sql="SELECT INSTALL_TIME, SUM(CASE WHEN SENIORITY=0 THEN TOTAL_IAP END)/NULLIF(SUM(COST),0) AS ROIAP_D0 FROM UA_DS GROUP BY 1"` - the same derivation the chart runs.
+
+**Label equals the visible title.** The `data-graphit-label` MUST match the card's visible heading exactly. Users find their chart by that label in @ mention dropdowns and entity panels - a mismatch means they cannot find it.
+
+## First-paint loading state
+
+The dashboard HTML paints before the SDK connects (iframe load plus handshake), so the SDK's own spinner cannot cover the first moments. Bake a pure-CSS overlay into the HTML so every chart shows a spinner from the first frame; the SDK adopts that overlay and removes it when the element's `graphit.resolve()` settles (success or error).
+
+Add once to the page `<style>`:
+
+```css
+@keyframes gh-spin{to{transform:rotate(360deg)}}
+.gh-loading{position:relative;min-height:120px}
+.gh-loading-overlay{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;z-index:9998;backdrop-filter:blur(3px);-webkit-backdrop-filter:blur(3px);background:color-mix(in srgb,var(--graphit-surface-raised,#fff) 50%,transparent);border-radius:inherit}
+.gh-loading-spin{animation:gh-spin .7s linear infinite}
+```
+
+Add the overlay inside EVERY element passed as `target:` to `graphit.resolve()` - and ONLY those elements. A static text or title section with no resolve call would spin forever.
+
+```html
+<div id="spend-chart" class="gh-loading">
+  <div class="gh-loading-overlay"><svg class="gh-loading-spin" width="24" height="24" viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="10" stroke="var(--graphit-border,#e5e5e5)" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="var(--graphit-accent,#4DB6AC)" stroke-width="2.5" stroke-linecap="round"/></svg></div>
+</div>
+```
+
+The class names are a contract with the SDK (`gh-loading`, `gh-loading-overlay`, `gh-loading-spin`, `gh-spin`) - keep them exactly as shown or the SDK cannot adopt and remove the overlay. NEVER write text placeholders ("Loading", "Fetching data") - they never animate and make slow loads look stuck.
+
+## Cache-friendly resolve SQL
+
+A resolve query that follows these shapes serves from a semantic cache in roughly 10ms on filter changes instead of a full DuckDB recompute (5 to 37 seconds on wide data sources). Write resolve SQL in this style by default.
+
+**Shapes that hit the cache:**
+
+- Single table (no JOIN or UNION).
+- WHERE as a flat AND of `column = literal`, `column IN (...)`, `column BETWEEN ... AND ...` conjuncts.
+- Bare aggregates only: `SUM(col)`, `COUNT(*)`, `MIN(col)`, `MAX(col)`. No wrapping functions (`ROUND(SUM(x))`), no aggregate arithmetic (`SUM(a)/NULLIF(SUM(b),0)`), no `AVG`.
+- Literal dates (`>= '2026-01-01'`), never `CURRENT_DATE` expressions.
+- GROUP BY column names or ordinals; ORDER BY and LIMIT allowed (outer query only).
+- CTEs are fine when the CTE body follows the same rules.
+- Top-N rank queries: project the sort metric in SELECT (`SELECT dim, SUM(metric) AS rv ... ORDER BY rv DESC LIMIT N`), not only in ORDER BY.
+
+**Shapes that skip the cache** (they still run correctly, just slower):
+
+- `COUNT(DISTINCT x)`, window functions, HAVING, QUALIFY.
+- `OR` or `NOT` in WHERE.
+- Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves. To display a ratio as a percent, multiply by 100 in SQL (`* 100.0 ... AS x_pct`): the `"percent"` format only appends `%`, it does not scale, so a 0-to-1 ratio would otherwise show as `0.42%`, not `42%`.
+- `CURRENT_DATE`-relative predicates.
+- Top-N with the aggregate only in ORDER BY (`... GROUP BY dim ORDER BY SUM(metric) DESC LIMIT N` with no decomposable aggregate in SELECT).
+
+## Rate-limit budget
+
+`graphit.resolve()` is rate-limited to 120 requests per minute per user per dashboard. Each call counts as one request. Design for that budget:
+
+- **Single refresh function.** Put all queries in ONE `Promise.all` inside one `refresh()` function so they share the same time window. NEVER scatter `graphit.resolve()` across independent event handlers or timeouts - that turns one user action into several bursts.
+- **Count queries per interaction.** 6 charts is 6 requests per filter change, about 20 changes per minute of budget; 12 charts is about 10 changes per minute. With 10 or more charts and 3 or more filters, debounce filter changes (300ms) so rapid clicks do not each trigger a full refresh.
+- **Reuse trend data for KPIs.** If you already fetch a weekly time series, derive the KPI total and its sparkline from that result in JS instead of running a separate aggregate query - one query serves both.
+- **Avoid redundant refreshes.** If a filter affects only some charts, split into targeted refresh functions (`refreshKPIs()`, `refreshCharts()`) so unchanged sections do not re-query.
+- **No polling.** NEVER use `setInterval(refresh, ...)`. Data sources update on their own schedule; a polling dashboard burns the entire budget.
+
+If you hit the limit, the API returns a "Too many requests" error with a retry-after hint.
+
+## Helper index
+
+You have full creative freedom: build charts with inline SVG, CSS, and HTML tables for full control. The iframe also provides convenience helpers for quick standard output. These are shortcuts, not requirements.
+
+| Helper | What it renders | Depth |
+|---|---|---|
+| `graphit.chart(el, {type, data, x, y, ...})` | A native chart of the given `type` | `chart-patterns.md` (per-type config) |
+| `graphit.table(el, {data, columns?, columnFormats?})` | A styled HTML table; `columnFormats` maps a column name to `"currency"` / `"percent"` / `"number"` | `chart-patterns.md` |
+| `graphit.kpi(el, {value, label?, format?})` | A KPI card with an optional delta | `chart-patterns.md` |
+| `graphit.presentation(el)` | A full-screen slide deck builder | `presentations.md` |
+| `graphit.filter / param / dateRange / cascade / bind` | Headless interactivity (zero imposed markup) | `filters.md`, `filters-advanced.md` |
+
+**Native `graphit.chart` types:** `"bar"`, `"horizontal-bar"` (alias `"hbar"` - use when category labels are long), `"line"`, `"area"`, `"donut"`, `"pie"` (alias of `donut`), `"scatter"` (alias `"bubble"`), `"stacked-bar"` (alias `"stacked"`), `"heatmap"`, `"funnel"`, `"gauge"`, `"sparkline"`. The full per-type config (axes, dual axis, `valueFormat`, the non-scaling percent rule, and the hand-rolled shapes such as treemap and sankey) lives in `chart-patterns.md`. Saved org templates register as types too.
+
+**Logic versus styling.** `filter`, `param`, `bind`, `dateRange`, `cascade` are headless logic with zero imposed styling - you own the markup. `chart`, `table`, `kpi`, `presentation` render a fixed house style. Two trade-offs to surface to the user: a control persists to saved views ONLY when registered with `graphit.filter` / `param` / `dateRange` (a hand-rolled `<select>` will not save), and `graphit.chart` cannot be deeply restyled - hand-draw with SVG and CSS for a custom look while still fetching data via `graphit.resolve`.
+
+## Canonical entity with live data
+
+```html
+<div data-graphit-id="spend-by-source"
+     data-graphit-label="Ad Spend by Source"
+     data-graphit-sql="SELECT {{dim:MEDIA_SOURCE_DIMENSION}} AS source, {{metric:TOTAL_AD_SPEND}} AS spend FROM MARKETING_UA_DS GROUP BY source ORDER BY spend DESC"
+     data-graphit-ds="ds_abc123">
+  <div id="spend-chart" class="gh-loading">
+    <!-- gh-loading-overlay spinner from the First-paint section -->
+  </div>
+</div>
+<script>
+(async function() {
+  var r = await graphit.resolve({
+    sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) AS spend FROM MARKETING_UA_DS GROUP BY MEDIA_SOURCE ORDER BY spend DESC",
+    dataSourceId: "ds_abc123",
+    target: "#spend-chart"
+  });
+  graphit.chart("#spend-chart", {
+    type: "bar", data: r.data, x: "MEDIA_SOURCE", y: "spend",
+    title: "Ad Spend by Source", valueFormat: "currency"
+  });
+})();
+</script>
+```

package/skills/graphit/references/sql-reference.md

@@ -111,34 +111,13 @@ SELECT UNNEST(generate_series(
 
 The outer SELECT can ONLY reference columns the subquery exposes (its aliases). Base-table columns aggregated away in the subquery do NOT exist at the outer level.
 
-## Cache-Friendly SQL (Canvas Resolve)
+## Cache-friendly resolve SQL
 
-Canvas `graphit.resolve()` queries that follow these shapes serve from a semantic cache in ~10ms on filter changes instead of a full DuckDB recompute (5-37s on wide data sources). Write resolve SQL in this style by default.
+When the query feeds a canvas `graphit.resolve()` call, write it in the cache-friendly shape so filter changes stay instant. The shape rules and the shapes that skip the cache live in `runtime.md`.
 
-**Shape rules:**
-- Single table (no JOIN/UNION)
-- WHERE as flat AND of `column = literal`, `column IN (...)`, `column BETWEEN ... AND ...` conjuncts
-- Bare aggregates only: `SUM(col)`, `COUNT(*)`, `MIN(col)`, `MAX(col)` - no wrapping functions (`ROUND(SUM(x))`), no aggregate arithmetic (`SUM(a)/NULLIF(SUM(b),0)`), no `AVG` (v2)
-- Literal dates (`>= '2026-01-01'`), never `CURRENT_DATE` expressions
-- GROUP BY column names or ordinals; ORDER BY / LIMIT allowed (outer only)
-- CTEs are fine when the CTE body follows the same rules
-- Top-N rank queries: project the sort metric in SELECT (`SELECT dim, SUM(metric) AS rv ... ORDER BY rv DESC LIMIT N`), not only in ORDER BY
+## Data source routing
 
-**Shapes that skip the cache** (fall back to normal execution, still correct):
-- `COUNT(DISTINCT x)`, window functions, HAVING, QUALIFY
-- OR / NOT in WHERE
-- Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves. To display as a percent, multiply by 100 (`* 100.0 ... AS x_pct`): the `"percent"` format only appends `%`, it does not scale (a 0-1 ratio would show as `0.42%`, not `42%`).
-- `CURRENT_DATE`-relative predicates
-- Top-N with aggregate only in ORDER BY (`SELECT dim FROM t GROUP BY dim ORDER BY SUM(metric) DESC LIMIT N` - no decomposable aggregate in SELECT)
-
-## Data Source Routing
-
-| Situation | Command | Speed |
-|---|---|---|
-| Table has a cached data source | `graphit query "SQL" --ds <id>` | ~100ms, DuckDB |
-| No data source | `graphit query "SQL" --warehouse --connection <id>` | ~10s, Snowflake |
-
-Always prefer cached data sources. Check with `graphit ds list`. If no data source covers the table, suggest creating one for future speed.
+Always prefer a cached data source (`graphit query "SQL" --ds <id>`, roughly 100ms via DuckDB) over a live warehouse query (`graphit query "SQL" --warehouse --connection <id>`, roughly 10s via Snowflake). The full routing table, the `ds list` output template, and the source-shape guidance live in `data-sources.md`.
 
 ## Presenting Query Results
 
@@ -210,20 +189,4 @@ For ad-hoc queries, suggest the KB reference equivalent when one exists. This nu
 
 Zero rows: explain what you checked and hypothesize why (wrong date range, filter too strict, table empty).
 
-## Presenting Data Source Results
-
-After `graphit ds list`:
-
-~~~
-**3 data sources:**
-
-| Name | ID | Rows | Status | Governed |
-|---|---|---:|---|---|
-| **MARKETING_UA_DS** | ds_abc123 | 1,247,832 | active | yes |
-| **PLAYER_QUALITY** | ds_def456 | 892,104 | active | no |
-| **REVENUE_EVENTS** | ds_ghi789 | 3,412,006 | stale | yes |
-
-Using **MARKETING_UA_DS** (ds_abc123) which covers spend, installs, and ROAS columns.
-~~~
-
-End with a recommendation of which DS to use, or note if none covers the needed table.
+The `graphit ds list` output template lives in `data-sources.md`.

package/skills/graphit/references/domain-lenses.md

@@ -1,116 +0,0 @@
-# Domain Lenses
-
-Consult when the user's data signals match a specific business domain. Each lens provides domain-specific metrics, chart types, and anti-patterns that make dashboards feel expert-built.
-
-Detect the domain from column names and user intent. Apply universal planning rules first (see dashboard-planning.md), then layer domain-specific patterns.
-
-Several high-value lens charts - **waterfall** (P&L / ARR bridges), **bullet** (KPI vs target), **Lorenz** (revenue concentration), and **histogram** (attainment distribution) - are NOT native `graphit.chart()` types, so `graphit.chart()` throws on those names. Build them as hand-rolled SVG (see `chart-selection.md` for the native-vs-hand-rolled split). The native lens charts (line, bar, stacked-bar, heatmap, funnel, KPI, sparkline) render through `graphit.chart` / `graphit.kpi`.
-
----
-
-## Marketing & Attribution
-
-**Signals:** utm_*, channel, creative_id, spend, cpi, impressions, clicks, roas, cac, ltv, attribution_*, skan_*, conversions, ctr.
-
-**Key metrics:**
-
-| Metric | Formula pattern | Chart |
-|---|---|---|
-| Blended CAC / Paid CAC | spend / new_customers | bar/KPI, target + YoY |
-| ROAS D7/D30/D90 | revenue_D0-N / spend | cumulative cohort line + 100% breakeven |
-| MER | revenue / marketing_spend | KPI |
-| LTV:CAC Ratio | LTV / CAC | bar, floor 3:1 |
-| Payback Period | days to recoup CAC | cumulative line |
-
-**Must-have charts:** Cumulative cohort ROAS curve with 100% breakeven line. Channel-mix sorted bar (never pie for 6+). Creative scorecard table. Attribution model comparison stacked bar.
-
-**Anti-patterns:** Mismatched attribution windows across channels (7d vs 30d = 30% artifact). ROAS without payback context. Summing self-reported channel conversions without dedup (totals 110-180%). Spend without incrementality context. Creative table without refresh ratio.
-
-**Clarify first:** Attribution model + window? ROAS gross or margin-adjusted?
-
----
-
-## Financial / Executive
-
-**Signals:** revenue, mrr, arr, cogs, gross_margin, opex, ebitda, budget, forecast, actual, variance, runway, burn, cash_balance, gl_account.
-
-**Key metrics:**
-
-| Metric | Formula pattern | Chart |
-|---|---|---|
-| P&L Cascade | Rev->COGS->GP->Opex->EBITDA->Net | waterfall |
-| Variance $/% | Actual-Plan, sign-aware per line type | semantic-color bar |
-| GM% by segment | (Rev-COGS)/Rev per product/cohort | line + small multiples |
-| Burn Multiple | net_burn / net_new_ARR | KPI + trend |
-| Runway Months | Cash / abs(Net Burn) | KPI color-banded |
-| Rule of 40 | Growth% + EBITDA margin% | KPI + trend |
-
-**Must-have charts:** Waterfall (P&L, variance bridge, ARR bridge). Bullet chart for KPI vs target. Plan vs Forecast vs Actual (3 series, never 2). Variance bars with semantic color (green=favorable, red=unfavorable regardless of direction).
-
-**Anti-patterns:** Direction-based green/red instead of favorable/unfavorable. Blended GM hiding AI inference cost compression. YTD comparison in Jan/Dec (use TTM). Cash burn without runway. Revenue without ASC 606 distinction. "Three-line" missing Forecast (Plan vs Actual vs Forecast = 3).
-
-**Clarify first:** Revenue = bookings, ARR, or GAAP recognized?
-
----
-
-## Product / Growth
-
-**Signals:** install_date, signup_at, cohort_*, retention_d*, dau, mau, activation_*, payer_*, funnel_step, session_*, ltv, arpu, arpdau.
-
-**Key metrics:**
-
-| Metric | Formula pattern | Chart |
-|---|---|---|
-| D1/D7/D30 Retention | active_dN / cohort_size | heatmap or overlay |
-| Stickiness | DAU/MAU | line + ref bands |
-| ARPDAU | revenue_day / DAU_day | line + 7d MA |
-| Payer Conversion D7 | first_payers_d7 / cohort | cumulative line |
-| Whale Share | sum(rev) top-X% / total_rev | Lorenz / decile bar |
-| Activation Rate | reached_aha / signups | cohort heatmap |
-
-**Must-have charts:** Cohort retention heatmap (X=days since signup, Y=cohort, color=retention%). Cumulative cohort overlay (max 6 series). Lorenz/decile bar for revenue concentration. FTUE funnel with per-cohort drift.
-
-**Anti-patterns:** Period retention instead of cohort retention. Bare ARPU without distribution (whales break every mean). Mean on heavy-tailed metrics (use median + p90). LTV without cohort horizon day. Vanity cumulative tiles.
-
----
-
-## Operational Monitoring
-
-**Signals:** latency, p50/p95/p99, error_rate, slo, uptime, mttr, throughput, oee, cycle_time, otif, fill_rate, stockout, deployment_frequency.
-
-**Key metrics:**
-
-| Metric | Formula pattern | Chart |
-|---|---|---|
-| Latency p50/p95/p99 | percentile buckets | multi-percentile line + SLO |
-| Error Budget | 100% - (errors/total) rolling 28d | bullet chart |
-| DORA Quartet | deploy freq, lead time, CFR, recovery | 4-tile KPI |
-| OEE | Availability x Performance x Quality | KPI + 3-tile decomp |
-| OTIF | on-time AND in-full | trend + decomp stacked bar |
-
-**Must-have charts:** Multi-percentile line + SLO threshold band. Bullet chart (not gauge). Latency heatmap. Error sources Pareto.
-
-**Anti-patterns:** Averages without percentiles. KPI without threshold band. Vanity uptime % (use error-budget framing). Aggregating across segments (global 0.4% hides a region at 8%).
-
----
-
-## Sales / Pipeline
-
-**Signals:** opp_id, stage, amount, close_date, forecast_category, mql, sql, arr, acv, tcv, quota, attainment, loss_reason, expansion_arr.
-
-**Key metrics:**
-
-| Metric | Formula pattern | Chart |
-|---|---|---|
-| Pipeline Coverage | open_pipe / quota_remaining | KPI, target=1/win_rate |
-| Sales Velocity | (opps x win_rate x avg_acv) / cycle_days | KPI + trend |
-| Win Rate by ACV | won / (won+lost) per band | sorted bar, min-N 30 |
-| Quota Attainment | closed_won / quota | histogram (bimodal!) |
-| Net New ARR | new + expansion - contraction - churn | waterfall |
-| Forecast MAPE | mean(abs(actual-forecast)/actual) | line + target |
-
-**Must-have charts:** Net New ARR waterfall (start + new + expansion - contraction - churn = end). Forecast convergence curve (13 weeks). Coverage curve by quarter-week. Win rate by ACV band.
-
-**Anti-patterns:** Fixed 3x coverage instead of 1/win_rate per segment. ACV/ARR/TCV/bookings conflated. Quota attainment as bare mean (bimodal - use histogram). Stage-weighted pipe using CRM defaults (30-50% overstate). "No decision" lumped (40-60% of B2B - split it).
-
-**Clarify first:** MQL/SQL definitions (same column = 13-40% conversion depending on org). Revenue = bookings vs ARR vs GAAP. Coverage target: derive from historical win rate per segment, not fixed multiple.