@datarails-ai/dr-cli 0.0.1-locked → 1.6.71

package/dist/skills/dr-cli/reference/metrics.md

@@ -0,0 +1,512 @@
+# Metrics (KPIs), categories, dimensions, functions
+
+## Read
+
+- `metrics list` (`--raw --json` for the raw shape), `metrics get <id>`.
+  `--json` emits the FinanceOS `MetricItem` shape: `template_id`,
+  `date_field_id`, `value_field_id`, `dimension_fields`, `organization_id`,
+  `base_metrics`, `configuration`, `created_at`, `updated_at`. For CALC metrics
+  the formula is at **`configuration.presented_formula`** — NOT a top-level
+  field (`--json | jq '.presented_formula'` returns null; read
+  `.configuration.presented_formula`).
+- `metrics data --id <id> --scenario Actuals --from 2026-01-01 --to 2026-12-31` —
+  the KPI value over a range. `--scenario` / `--cycle` are repeatable and also
+  accept comma-separated values (e.g. `Actuals,Budget`) to pull several at once.
+  - `--period <day|month|quarter|year>` (default `month`) sets the grain of the
+    returned buckets.
+  - `--agg <DEFAULT|MTD|QTD|YTD|MTG|QTG|YTG>` (default `DEFAULT`) sets how each
+    bucket accumulates. `DEFAULT` = the bucket's own value.
+    - **`*TD` ("to date")** accumulate backward: from the start of the
+      month/quarter/year up to and including the current bucket.
+    - **`*TG` ("to go")** accumulate forward: from the current bucket
+      (**inclusive**) to the end of the month/quarter/year. So at month grain
+      `YTG` on January = the full-year total, and `MTG` = the month's own
+      value. The identity `YTD[N-1] + YTG[N] = annual total` holds.
+    - **Accumulation is clipped to the requested `--from`/`--to` window** —
+      there is no separate as-of parameter, and the server never looks outside
+      the range. A too-narrow window silently returns a smaller number rather
+      than an error, in both directions: `--from 2025-06-01` makes June's `YTD`
+      equal June alone, and `--to 2025-06-30` makes January's `YTG` equal
+      Jan–Jun. Always span the full period you're accumulating over.
+  - `--period day` is rejected for metrics whose formula uses
+    `PERIODS_IN_YEAR` — that's "not a valid question" (an annualization factor
+    has no day-grain meaning), NOT missing data. Re-query with
+    `--period month|quarter|year`. With multiple `--id`s the response reports
+    the rejection per-metric (`INVALID_PARAMS` + an actionable message); with
+    a single `--id` the endpoint collapses ANY per-metric failure into a bare
+    HTTP 404 — the CLI appends a note explaining both readings (id missing on
+    this tenant vs. metric rejected the query) and how to disambiguate.
+- `metrics drilldown --id <id> --from … --to …` — the source rows behind the
+  value ("where is this number coming from").
+
+Names, descriptions, and CALC `presented_formula` are HTML-decoded before render,
+so both `--json` and the table show clean text.
+
+## Create BASE (`metrics create base`)
+
+Required: `--name`, `--template <id>`, `--value-field <id>`, `--date-field <id>`,
+`--aggregator <agg>`.
+
+- **Aggregator is one of `SUM`, `COUNT`, `CUMULATIVE_SUM`, `CUMULATIVE_COUNT`.**
+  `AVG`/`MIN`/`MAX` are not valid for metric value fields and are rejected.
+- `--time-aggregation` is `SUM`, `EOP`, or `AVG`. A cumulative aggregator cannot
+  use `SUM` and defaults to `EOP`.
+- `--filter <field_id>=<v>` / `--exclude-filter …`; `--dimensions` is PK-validated
+  client-side.
+
+## Create CALC (`metrics create calc`)
+
+`--formula "[Revenue]-[COGS]"`:
+
+- Each referenced metric name is wrapped in `[ ]`; bare names (`revenue/cogs`)
+  are rejected. The formula must reference ≥1 metric (constants-only like
+  `5 * 12` is rejected) and `()` must balance.
+- **Time modifiers** (optional, exactly two forms):
+  - `[M].SHIFT(<year|quarter|month|day|consumption_period>, <offset≤0>)` — "N
+    periods ago". `|offset|` ≤ 1200. `consumption_period` is the **dynamic**
+    unit (UI label "Period"): it resolves to the grain of the query, so
+    `[M].SHIFT(consumption_period, -1)` reads one viewing-grain step back at
+    every grain — the opening-balance pattern on cumulative metrics. Fixed
+    units always step the named unit regardless of grain (`-1 year` viewed
+    quarterly = same quarter last year); use them for prior-year comparisons.
+  - `[M].AS_OF(<year_end|quarter_end|month_end>)` — "end of last period"
+    (requires an EOP metric, enforced server-side). Anchors are fixed only —
+    there is no dynamic AS_OF anchor.
+  - A bare `[M]` (no suffix) **is** the current period — do NOT add a modifier to
+    mean "current". Modifiers cannot be chained on one reference.
+- **Reserved tokens** resolve at runtime — write them **bare**, not bracketed,
+  and never attach a time modifier to one:
+  - `DAYS_IN_PERIOD` = days in the aggregation period:
+    `"[Revenue] / DAYS_IN_PERIOD"`.
+  - `PERIODS_IN_YEAR` = annualization factor of the query window (12 at month
+    grain, 4 at quarter, 1 at year; pro-rated for partial windows):
+    `"[Churn] * PERIODS_IN_YEAR"`. One definition annualizes correctly at every
+    grain — no per-grain ×12/×4 metric variants needed. A metric using it
+    cannot be queried at day grain (see `metrics data` above).
+- The `create calc --json` response flags dynamic-time metrics:
+  `uses_dynamic_time_units: true`, plus `unsupported_grains: ["day"]` when
+  `PERIODS_IN_YEAR` is used. The `get`/`list` reads do **not** return these
+  two fields, so record them at create time if you need them.
+- Formula length is capped at 5000 characters (server limit, checked client-side).
+- No `--time-aggregation` — a CALC rollup inherits time-aggregation from each
+  referenced BASE, so a single CALC-level value would be meaningless.
+
+## Update / delete
+
+- `metrics update <id>` — partial PATCH. Flags: `--name`, `--description`,
+  `--category`, `--dimensions`, `--hide`/`--unhide`, `--time-aggregation`,
+  `--aggregator`, `--template`, `--value-field`, `--date-field`, `--filter`,
+  `--exclude-filter`, `--clear-filters`. `--description ""` clears to `null` on
+  the wire (matching how `get` round-trips an untouched field).
+  - **No `--formula`** — CALC formulas and other create-time fields (kind,
+    template, value/date field, aggregator) are intentionally not editable in
+    place; changing them yields a different metric. To fix a formula:
+    `metrics delete <id>` then `metrics create calc`.
+- `metrics delete <ids...>` — two-step confirm. One id deletes that metric;
+  passing several ids (`metrics delete 100 200 300`) deletes them as a single
+  batch — the plan lists every target and mints ONE `--confirm-token` bound to
+  the whole set, so the confirm is two calls total, not two per id. Ids are
+  order-independent and de-duplicated. A failed id doesn't abort the batch: each
+  outcome is reported and the command exits non-zero if any delete failed.
+
+## Re-aggregate (`metrics re-aggregate`)
+
+Manually trigger the semantic-layer pipeline that rebuilds pre-aggregated
+metric values. Use after bulk data/mapping changes when metric values look
+stale. **By default a 202 means the rebuild was QUEUED in the background, not
+finished** — add `--wait` (targeted ids only) to block until it completes.
+
+- `metrics re-aggregate <id> [<id> …]` — targeted refresh (max 100 distinct
+  ids, duplicates deduped client-side; ids from `metrics list`). The server
+  **silently drops** ids the caller can't access; the CLI diffs the response
+  against the request and prints a `warning:` line listing any skipped ids —
+  check for it before assuming every requested metric was refreshed.
+- `metrics re-aggregate <id> … --wait [--timeout <seconds>]` — after queuing,
+  poll each **accepted** id's `status_info` (the same signal that drives the
+  server's completion log) until every one reaches a terminal state, then print
+  a `succeeded / completed-with-warnings / failed` summary. Default timeout is
+  300s. **Exits non-zero** if any metric fails or the wait times out (the error
+  names the still-processing ids so you can re-check rather than blindly
+  re-trigger). Only the dropped-but-accepted ids are waited on. `--wait` is
+  **not** supported with `--all` (org-wide queues per-table jobs with no
+  per-metric status to poll — trigger without `--wait`, then check
+  `metrics list`).
+- `metrics re-aggregate --all` — org-wide rebuild of **every** table (except
+  the internal `dr_metrics` table). Heavy: queues one background job per
+  table. Two-step confirm, same flow as `delete`; the confirm token is bound
+  to the `--server` it was planned against and will not validate elsewhere.
+- `--json` — without `--wait`, the raw 202 body (`status`, `metric_ids` or
+  `table_ids`, `message`) on stdout. With `--wait`, stdout is instead ONE final
+  summary object (`outcome`, `succeeded`, `completed_with_warnings`, `failed`,
+  `pending`, `waited_seconds`); either way the dropped-ids `warning:` moves to
+  **stderr** so stdout stays parseable.
+- Rejections: 403 = `semantic_layer` org feature flag off (don't retry);
+  409 = org clone in progress (retry after it completes); 404 = none of the
+  ids are visible on this tenant.
+
+## Migrate (`metrics migrate`)
+
+Run the org-wide metrics + dimensions migration: backfill `category` /
+`time_aggregation` / source-table ids on **every** metric in the org, and
+convert V1 KPI dimension fields to V2 Dimension objects. Org-admin only.
+Synchronous — the 200 response IS the result (nothing queued, nothing to
+poll), with `metrics` and `dimensions` summary blocks. The backfill
+**overwrites** `category`/`time_aggregation` with the name-derived mapping —
+hand-set values included; `source_table_ids` fills only when empty. Per-metric
+before→after is in `details[]` (`--json`), so a replaced value can be restored
+with `metrics update --category` / `--time-aggregation`.
+
+- `metrics migrate --dry-run` — free preview: the server computes the full
+  summary and rolls back every write. Runs immediately, no confirm. **Always
+  run this first.**
+- `metrics migrate` — live run; two-step confirm, token-only (Tier B — no
+  prod word gate, unlike `delete`); the confirm token is bound to the
+  `--server` it was planned against. A transaction-level failure (the 500
+  below) rolls back every write — org unchanged. Per-metric errors are
+  non-fatal: rows that succeeded commit, and the 200 reports them in
+  `metrics.errors[]` (next bullet).
+- Per-metric failures do NOT fail the request: a 200 can still carry
+  `metrics.errors[]`, which the CLI prints as a `warning:` block — check for
+  it before assuming every metric migrated. With `--json` the warning moves
+  to **stderr** so stdout stays parseable.
+- `--json` — raw 200 body (`organization_id`, `dry_run`, `metrics`,
+  `dimensions`) including the per-metric/per-KPI `details` rows the text
+  summary omits.
+- Rejections: 403 = not an org admin (switch to an admin identity; don't
+  retry as-is); 409 = org clone in progress (retry after it completes);
+  500 = migration failed and rolled back — org unchanged, reproduce with
+  `--dry-run` before retrying.
+
+## Categories
+
+- `metrics categories list`, `metrics categories get <id>`.
+- `metrics categories create --name <s>` — color is server-assigned (not a CLI
+  input).
+- `metrics categories update <id> --name <s>` — rename only; color not editable;
+  org-admin only (non-admin gets 403).
+- `metrics categories delete <id>` — two-step confirm; metrics in the category
+  are un-categorized (not deleted); org-admin only.
+
+## Dimensions
+
+- `metrics dimensions list [--search <s>] [--template <id>] [--metric <id>]`,
+  `metrics dimensions get <id>`.
+- `metrics dimensions create --name <s> --mapping <table_id>:<field_id>
+  [--mapping …] [--description <s>]` — ≥1 mapping; client-side dup-table check.
+- `metrics dimensions update <id> [--name <s>] [--description <s>]
+  [--mapping <table>:<field> …] [--clear-mappings]` — `--mapping` replaces ALL
+  mappings; `--clear-mappings` wipes them; the two are mutually exclusive.
+- `metrics dimensions delete <id>` — two-step confirm.
+- `metrics dimensions preview <id>` — unique values across the mapped tables
+  (`--limit <n>`, `--json`).
+
+## AI suggestions (`metrics suggestions`, `metrics dimensions suggestions`)
+
+Agent-generated metric/dimension proposals — the CLI surface behind the FE's
+"generate suggestions" buttons. Two parallel command groups with identical
+shapes:
+
+- `metrics suggestions list|refresh` — metric suggestions.
+- `metrics dimensions suggestions list|refresh` — dimension suggestions.
+- `metrics dimensions suggestions profile` — read-only candidate profiler.
+  Dimensions only, and the one command in this group that needs **no** Unleash
+  flag (see below).
+
+Gating: each group needs its own **Unleash** flag enabled for the org
+(`semantic_layer__ai_metric_suggestions` / `semantic_layer__ai_dimension_suggestions`)
+AND an org-admin identity. A persistent 403 means one of the two is missing —
+tenant configuration, not a CLI error.
+
+- `… suggestions list [--json]` — active suggestions (id, name, kind for
+  metrics, created date, rationale) plus the **`last_run`** block: the newest
+  generation run's `id`, `status`, `trigger_source`, `updated_at`.
+  `last_run: none` = the agent has never run for this org. Statuses:
+  `PENDING`/`RUNNING` = live (at most one live run per org), `COMPLETED` /
+  `FAILED` / `NO_DATA` = terminal (`NO_DATA` = ran fine, produced nothing).
+  Dismissed rows and full payloads are in `--json` only.
+- `… suggestions refresh [--wait] [--timeout <seconds>] [--json]` — trigger a
+  generation run. **202 = queued, not done**: the server debounces triggers
+  (15-minute window) and dispatches the agent with a ~5-minute countdown, so
+  results land minutes later — live runs measure 13-15 minutes end to end.
+  `--wait` polls `last_run` until terminal (default timeout 1200s, sized for
+  that measured pipeline) and **exits non-zero** on
+  `FAILED`/timeout/cancel; `NO_DATA` exits zero. `--json` without `--wait` is
+  the raw `{run_id}`; with `--wait`, ONE summary object (`outcome`, `run_id`,
+  `last_run`, `active_suggestions`, `dismissed_suggestions`,
+  `waited_seconds`). `outcome` is one of `completed`, `no_data`, `superseded`,
+  `failed`, `timed_out`, `cancelled` — `superseded` means a newer run started
+  before ours was observed terminal (ours must have finished; one live run per
+  org); it exits zero, check `list` for the current state.
+- Rejections: 409 = a run is already PENDING/RUNNING for the org — **not a
+  failure**; check `list` instead of re-triggering. 403 = Unleash flag off or
+  not org-admin (see gating above).
+- **Semantic-layer opening interplay**: a successful live `metrics migrate`
+  (and an org clone) auto-triggers BOTH agents, provided the Unleash flags
+  were already on at migration time. In an SL-opening flow: enable the flags
+  first, run the migration, then verify with `… suggestions list` — and expect
+  `refresh` to 409 while the auto-triggered run is live. If `last_run` is
+  `none` after a migration, the flags were off when it ran — enable them and
+  `refresh` manually.
+
+### `metrics suggestions profile`
+
+Profiles every table on the tenant and returns, per table, the facts a metric
+needs before it can be proposed. Read-only — it never writes a suggestion.
+
+```bash
+dr metrics suggestions profile -s DEV --account support@acme.com --json
+```
+
+**Run this before proposing any BASE metric.** Nothing in the templates payload
+marks which date column is the reporting axis, so a caller working from the raw
+payload falls back to "any column of type Date" — and a headcount table carries
+nine of them. Bucketing headcount by hire date instead of reporting month passes
+every validation the platform performs and the number is silently wrong. This
+command answers the question mechanically instead.
+
+- Needs only table read access — **not** the AI-suggestions Unleash flag.
+- Measured on a 43-table org: **233 requests, ~32 s**, 2729 fields examined,
+  118 measures, 31 tables with an axis.
+- Flags: `--json`, `--concurrency <n>` (1-64, default 6), `--tables <ids...>`,
+  `--sample-rows <n>` (1-1000, default 200), `--windows <n>` (1-10, default 3),
+  `--max-values <n>` (default 120), `--out <file>` (mode `0600`),
+  `--timeout <seconds>` (default 600).
+
+#### The four things to read
+
+- **`reporting_axis`** — the date column a BASE metric on this table should use
+  as `date_field`, with `chosen_by` recording which rule fired: `named` (the
+  platform's own reporting-column name — the strongest), `month_end_values`
+  (every value falls on a month boundary; a transaction date does not do that),
+  or `existing_metric` (what metrics on this table already use — weakest, but
+  it means somebody looked at this table once).
+  - **`null` is a real answer, not a gap in the run.** It means no rule fired,
+    so there is no defensible `date_field`. Do not substitute the first Date
+    column — confirm the right one with someone who knows the data. On the org
+    measured, 12 of 43 tables answered `null`.
+- **`row_grain.reads_as`** — `movements` (many rows per entity per period; a
+  journal) means `time_aggregation: SUM`. `balances` (one row per entity per
+  period; a snapshot) means `EOP`. Summing snapshots multiplies the total by
+  the number of periods, which is the most common modelling error on this
+  platform.
+  - `unknown` carries `unknown_because`: `no_entity_field`, `no_reporting_axis`,
+    `no_row_count`, or `between_thresholds` (the ratio landed between the two
+    cutoffs, where both aggregations are defensible — that is a real finding,
+    not a failed measurement).
+  - Check `entity_chosen_by`. `named` means a real entity column.
+    `lowest_cardinality` is a fallback that picks the column with the fewest
+    values, which is sometimes a status or scenario flag rather than an entity —
+    discount `rows_per_entity_period` accordingly.
+- **`measures[]`** — numeric columns that survived screening, each with a
+  `verdict` of `measure` or (rejected) `identifier_like` / `too_null`. A high
+  distinct ratio alone never condemns a column: a per-transaction amount is
+  near-unique by nature, so a key also has to be made of integers that look
+  generated.
+- **`existing_metrics`** per table, plus an org-level `library` block
+  (`metrics_count`, `unhealthy`, `tables_with_metrics`). Saves a library sweep
+  of your own and answers "which tables are analytically load-bearing".
+
+#### Every measure statistic is SAMPLED — read it as a screen
+
+The sample endpoint returns rows in **storage order, not at random**. Measured
+on a 333k-row table, a 200-row window held a single document id and a single
+month. So:
+
+- Every sampled figure is named `sampled_*`, and `summary.thresholds` records
+  the window count and size behind it.
+- `sample_disagreement: true` means the windows disagreed about that column —
+  evidence the head of the table is not representative of the rest. Common, and
+  worth knowing.
+- **There is deliberately no `sum` and no `avg`.** A total extrapolated from a
+  biased window is exactly the plausible-looking wrong number this command
+  exists to prevent. If you need an exact total for one field, ask for it
+  directly at the point you create the metric:
+  `dr templates aggregate <id> --group-by <dim> --metric "<field>:SUM"`.
+  - Note that endpoint honours **one metric per request** — extra `--metric`
+    flags are silently dropped, so ask one field at a time.
+
+#### Reading the summary
+
+`summary` distinguishes a full sweep from a thin one; read it before trusting a
+short result. `requests_issued` and `elapsed_ms` say what the run cost.
+`library_source: unavailable` means the metrics library could not be read — do
+**not** read the empty `library` as "this org has no metrics". A table that the
+tables API will not serve rejects every one of its fields as `profile_error`,
+so one unserved table can account for most of that count; `warnings` names such
+tables so the number is not misread as a widespread failure.
+
+Rejection reasons: `system_field`, `hidden_field`, `scenario_field`,
+`generated_field` (a date part — `System_Year`, `Reporting Year`, anything whose
+name ends in a singular calendar unit), `unsupported_type`,
+`field_name_unaddressable`, `profile_error`, `no_sample` (the table is empty),
+`all_null`, `too_null`, `identifier_like`, `cardinality_too_high`.
+
+#### What the caller still owns
+
+Naming, descriptions, rationale, confidence, and whether a statistically valid
+measure is a business-meaningful metric. This command reports structure, not
+meaning.
+
+### `metrics dimensions suggestions profile`
+
+Profiles every table and field on the tenant and returns scored **candidate
+dimension groups**. Read-only — it never writes a suggestion. Use it when you
+need to reason about what the org's dimensions *should* be: it answers in one
+call what would otherwise take one distinct-values call per field.
+
+```bash
+dr metrics dimensions suggestions profile -s DEV --account support@acme.com --json
+```
+
+- Needs only table read access — **not** the AI-suggestions Unleash flag. It
+  does read the dismissed-suggestion list, which is flag-gated; if that read
+  fails the command warns, reports `dismissed: []`, and carries on.
+- Flags: `--json`, `--concurrency <n>` (1-64, default 6 — measured: the
+  finance-os gateway rate-limits a large sweep at 16, and *which* requests it
+  rejects varies per run, so a higher value trades determinism for ~10% wall
+  clock; transient rejections are retried three times regardless, and the run
+  warns when more than 10% of the fan-out needed a retry),
+  `--tables <ids...>` (comma- or space-separated; default every table),
+  `--max-values <n>` (cap values echoed per field, default 120; `0` = counts
+  only), `--out <file>` (written mode `0600` — the payload carries raw tenant
+  values from every profiled column), `--suppression <file>`,
+  `--timeout <seconds>` (default 600 — the whole sweep shares one budget).
+- Output has four keys:
+  - `summary` — coverage (`tables_total` vs `tables_screened`,
+    `fields_examined` / `fields_eligible` / `fields_profiled`,
+    `profile_errors`, `table_errors`, `tables_without_row_count`),
+    `rejected_by_reason` counts, `thresholds` (every constant the run used),
+    `warnings`, `elapsed_ms`. **Read this before trusting an empty result** —
+    it distinguishes a full sweep from a thin one.
+  - `groups` — the candidates. Each has `members` (`table_id`, `table_name`,
+    `field_id`, `field_name`, `distinct_count`, `sample_values`,
+    `values_truncated`), `scope` (`cross_table` | `single_table`),
+    `pairwise` containment scores, `min_containment`, `weak_link`, and
+    `verdict`.
+  - `rejected` — every field that did not become a candidate, each with a
+    machine-readable `reason`. Runs to thousands of rows on a large org; use
+    `--out` when you only need `summary` + `groups`.
+  - `near_misses` — pairs that overlapped between 0.60 and 0.80: enough to be
+    worth a look, not enough to merge. Each carries both sides, the
+    `containment` and the shared-value count. **The 0.80 cutoff is a suggestion
+    to you, not a verdict** — a pair at 0.78 is often one dimension with a
+    coverage gap, and this is where it surfaces instead of vanishing. Pairs that
+    already merged are not repeated here; the group's own `pairwise` and
+    `weak_link` cover those.
+  - `dismissed` — names the operator already dismissed. Do not re-propose them.
+- **`--suppression <file>`** supplies `{existing_dimensions, dismissed}` from the
+  caller instead of fetching them. Use it when you already hold them — an agent
+  receives both in its trigger message — because refetching creates a second
+  source of truth that disagrees the moment a dimension is created mid-run.
+  Either key wins on its own; the other is still fetched. Shape is tolerant:
+  the list may be keyed `existing_dimensions` or `dimensions`, mappings may be
+  `mappings: [{table_id, field_id}]` or `field_mappings: [{table, field}]`, and
+  dismissed entries may be `{name}` objects or bare strings. A malformed file is
+  an error, never a silent skip — a suppression list that quietly parsed to
+  nothing would report duplicates as new. `summary.suppression_source` records
+  where each list came from (`file` / `api` / `unavailable`).
+- `verdict` decides what to do with a group: `new` = propose it;
+  `duplicate_of_existing` = the org already has a dimension covering exactly
+  these mappings, skip it; `extends_existing` = some members are already
+  mapped — **do not broaden an existing dimension from here**, skip it too.
+- `weak_link: true` means the group was merged transitively (A–B and B–C both
+  cleared the bar, A–C did not). Split it or drop it rather than trusting it.
+- Grouping is by **value overlap, never by name**: containment
+  `|A ∩ B| / min(|A|,|B|)` at 0.80 with an absolute intersection floor of 3,
+  filler values (`N/A`, `Other`, `Total`, `Unknown`, …) stripped first. So
+  `Region` / `Geo` / `Territory` group when their values agree, and two
+  columns both called `Code` do not when they don't.
+- Rejection reasons: `system_field` (the platform's `category: ["system"]`
+  flag, or a known plumbing name), `hidden_field`, `scenario_field` (scenario
+  is already a first-class Datarails axis), `not_text` (text only, by product
+  decision), `cardinality_too_low` (< 2), `cardinality_too_high` (> 100),
+  `identifier_like` (fewer than 10 rows per distinct value),
+  `no_usable_values` (every value was filler, or none came back — so there is
+  no vocabulary to compare), `field_name_unaddressable` (the name contains
+  `/`, which the by-name distinct endpoint cannot address in a URL path
+  segment — no request is issued), `empty_unverified` (see below),
+  `profile_error` (that field's distinct call failed after retries, OR it
+  succeeded while returning values that a COUNT_UNIQUE aggregation
+  contradicts; the run continues), `no_distinct_count`, and `too_many_nulls`.
+- **An empty distinct result is never taken at face value.** A genuinely empty
+  column and a silent read failure look identical, so a field that comes back
+  with zero values is re-checked with a `COUNT_UNIQUE` aggregation. Three
+  outcomes: the count agrees (`cardinality_too_low`), the count disagrees
+  (`profile_error` — the values read was wrong), or the check itself could not
+  be made (`empty_unverified`, counted in `summary.empty_unverified`). Treat
+  `empty_unverified` as unknown, not as empty: on one org 174 fields on a
+  single table all returned zero values, and the corroborating call revealed
+  the table was not served by the tables API at all.
+- **Server-side truncation is not `--max-values`.** If the server ever holds
+  back part of a value list, the retained count is not the field's cardinality
+  — a field with thousands of values truncated to 80 would otherwise pass the
+  <= 100 test and be proposed as a dimension. Such fields are rejected as
+  `cardinality_too_high` without being measured, and counted in
+  `summary.api_truncated`. This is separate from `values_truncated`, which is
+  only ever about the `--max-values` cap. Note the distinct endpoint has not
+  been seen to truncate: it returned all 121,664 values of a high-cardinality
+  field. The endpoint that does hold back rows is `.../data`, which paginates
+  and reports `metadata.pagination.has_more`; this command reads it only for
+  row counts, where `total_count` is the figure that matters.
+- `too_many_nulls` does not fire on this surface: nothing in the tables API
+  reports per-field null counts, so the screen has no input. `max_null_rate`
+  still appears in `summary.thresholds` because that block echoes every
+  constant the scorer holds — read it as the cutoff that *would* apply, not as
+  evidence that null-heavy columns were filtered out. Two tables in a row of a
+  mostly-empty column will both reach you as candidates.
+- The identifier and null-rate screens also need a row count, and some tables
+  report none (`summary.tables_without_row_count`). On those tables a
+  high-cardinality column can survive that a counted table would reject.
+- **What the caller still owns**: naming, descriptions, rationale, confidence,
+  and semantic judgment. The command reports structure, not meaning — it will
+  hand back a statistically valid but meaningless group (a two-value
+  `Heads`/`Tails` column). Deciding which groups are real dimensions, and what
+  to call them, is yours.
+- A run with zero groups exits **0**. `rejected_by_reason` says why.
+- **On repeat runs**: `groups` is byte-identical over unchanged data. That is
+  the guarantee to rely on — the candidate set does not move.
+  - The **request count** is not stable: when a table turns out to be
+    unreadable, its remaining fields are skipped, and how many get skipped
+    depends on what was already in flight. This never changes a verdict — a
+    skipped field and a failed one resolve the same way — so `elapsed_ms` and
+    the retry counts in `warnings` move while the answer does not.
+  - The **split between `empty_unverified` and `cardinality_too_low`** can move
+    by a few fields. Both are rejections, so `groups` is unaffected, but which
+    reason a zero-value field gets depends on whether its corroborating
+    `COUNT_UNIQUE` call completed. Retries make that mostly stable, not
+    perfectly: measured 188 and 221 unverified across builds on the same
+    51-table org. Read `summary.empty_unverified` as "at least this many
+    fields' emptiness is unproven", not as an exact census.
+
+## Functions (DR.GET definitions)
+
+- `functions list`, `functions get <id>` — `get` returns the **definition**,
+  **not** the live value. Live function values are computed in Excel via
+  `DR.GET(...)` through the add-in and are not exposed by this CLI.
+  - The core row is `id / name / agg / template / value_field`; below it `get`
+    prints a **FILTERS** section (one row per persisted filter: `field`, `name`,
+    `type`, `excluded`, `values`) and the **default agg date field** when set.
+    `--json` adds `filters`, `default_agg_datefield`, `default_agg_config`.
+    `list` stays compact (core columns only) — filters show on `get` alone.
+  - A **date/Report-Date filter's From/To lives inside that filter's `values`**
+    blob (owned by the add-in), shown verbatim as compact JSON — read it there
+    rather than asking the customer to re-check the UI.
+- `functions create`, `functions update`, `functions delete` (two-step confirm).
+- `functions set-filters <id> --file <json> [--confirm]` — **the only way to
+  author a function's filters** (`create`/`update` don't touch them). **FULL
+  REPLACE**: the server deletes every existing filter and recreates from the
+  file, so pass the complete desired set — an **empty array clears them all**.
+  `--file` is a JSON array (or `{"filters":[…]}`) of
+  `{field:<FlatTableField id>, values:[…], is_excluded?, show_in_graph?,
+  override_global_filter?}`; `name`/`type` are server-derived, don't send them.
+  For a **dimension** filter `values` is a plain list (`["EMEA","APAC"]`); a
+  **date** filter's `values` is the add-in's opaque From/To blob (copy it from a
+  `get` on a function that already has the filter you want). Dry-run unless
+  `--confirm`; internally a read-modify-write PUT that preserves the core fields
+  and calculated-value links.
+
+## Customer-facing docs (KB)
+
+Help Center → the **"Semantic Layer"** category. Find current articles with `dr kb search "metric KPI"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.