@graphit/cli 0.2.322 → 0.2.330

package/skills/graphit/references/kb-traversal.md

@@ -1,107 +1,35 @@
-# KB Traversal - Worked Examples
+# KB Traversal
 
-Contents: Which Command (the read-command picker) - Common Queries (worked examples) - Reading the Results - Presenting KB Results (the per-command output templates).
+Load when investigating semantic reach or presenting KB results.
 
-Which `graphit kb` read command answers each question, and how to present the result. Each verb owns one role: `graphit kb list <type>` is the **inventory** (how many, and which, assets of a type exist), `graphit kb get <type> NAME` is one asset's **full definition**, and `graphit kb explore <type> NAME` is the **relationships** call - it walks the graph around one entity and returns its whole neighborhood (and, for a template, its concrete variants) in one call. `graphit kb search "<query>"` is the fallback for semantic discovery when you cannot name the entity. Explore is the primary discovery call.
+## Read roles
 
-## Which Command
-
-| Question | Command |
+| Need | Read |
 |---|---|
-| How many / which assets of a type exist (inventory) | `graphit kb list <type>` (metrics collapse to templates; `--include-variants` for the flat set) |
-| What is inside a domain or topic (the build entry point) | `graphit kb explore domain NAME` / `graphit kb explore topic NAME` |
-| What connects to X (dependencies, joins, topics, domain) | `graphit kb explore <type> NAME` |
-| A template's concrete variants | `graphit kb explore metric NAME` |
-| Get one asset's full details | `graphit kb get metric NAME` |
-| Find things like X when you cannot name it (semantic) | `graphit kb search "X"` (add `--type metric` to narrow) |
-
-`graphit kb explore` returns the whole neighborhood in one call and has no edge-type or depth flags - the response already carries dependents, joins, topics, and domain together, so read the part you need instead of chaining calls.
-
-## Common Queries
-
-### "Show me everything in the MARKETING domain"
-`graphit kb explore domain MARKETING` - returns the domain's tables and the assets on them. This is the first call when scoping a build.
-
-### "Find all revenue metrics"
-`graphit kb explore topic REVENUE` returns the assets tagged with that concept across every domain. Fall back to `graphit kb search "revenue" --type metric` only when no topic captures the concept.
-
-### "What depends on the ORDERS table?"
-`graphit kb explore table ORDERS` - returns the table's column schema (names, types, descriptions) plus `metric_count`/`dimension_count`/`rule_count` and every bound metric (collapsed to templates, each with a `variant_count`), dimension, and rule whose SQL references ORDERS. The counts include child variants; the lists stay collapsed.
-
-### "What columns does this table or data source have?" (read the schema)
-`graphit kb explore table <NAME>` (or `graphit kb get table <NAME>`) returns the column schema - names, types, descriptions - straight from the knowledge base. This is how you read a table's schema; never `DESCRIBE` it (only read-only SELECT runs through `graphit query`, so DESCRIBE/SHOW/DDL are rejected). If a data source was just created and not yet scanned, the KB has no columns for it yet - read its shape with `graphit query "SELECT * FROM <NAME> LIMIT 0" --ds <NAME>`, or run `graphit ds verify <id>` to scan it into the KB.
-
-### "What joins with MARKETING_UA_DS?"
-`graphit kb explore table MARKETING_UA_DS`, then read the relationships in the response (the documented JOINs involving that table).
-
-### "What topics does ARPU_D1 belong to?"
-`graphit kb explore metric ARPU_D1` - the response includes its topics, along with its tables, dimensions, and home domain.
-
-### "What domains do we have?" (enumerate names)
-`graphit kb list domains` - returns every domain with its description and asset count. Report all of them, including empty ones. This enumerates domain NAMES; to see what is in one, explore it. Domain is not a searchable type, so `graphit kb search` will not surface domains.
-
-## Presenting KB Results
-
-A single `graphit kb explore` call returns one entity's full neighborhood, so it usually answers the question on its own - scan the response and run a second command only if the first does not contain what you need. The user cannot see raw CLI output; render every result with these per-command templates.
-
-**After `graphit kb list <type>`** - count summary + table with bold names. The list is the **inventory**, and the response carries `total`/`truncated`: if the rows shown are fewer than `total`, the list was capped - raise `--limit` (a missing asset may be truncated, not absent). For metrics the list is **collapsed** - each row is a template or a flat metric, never a child variant; a template's `variant_count` says how many concrete variants it owns. Use `--include-variants` for the full flat set, or `graphit kb explore metric NAME` to enumerate one template's variants.
-
-~~~
-**12 metrics** (10 flat + 2 templates, 38 variants) across 3 tables:
-
-| Metric | Table | Calculation | Params | Variants |
-|---|---|---|---|---|
-| **CPI** | **MARKETING_UA** | `SUM(spend)/SUM(installs)` | - | - |
-| **ARPU** | **MARKETING_UA** | `SUM(revenue)/COUNT(...)` | DAY | 18 |
-| **RETENTION** | **PLAYER_QUALITY** | `COUNT(CASE WHEN ...)` | DAY | 20 |
-
-To use a variant, reference `{{metric:ARPU(DAY=7)}}`; to list them, explore the template.
-~~~
-
-Adapt columns per type: dimensions include semantic type, rules include constraint count, domains include asset count.
-
-**After `graphit kb get <type> <name>`** - entity heading + key-value table:
-
-~~~
-### **CPI** (metric, verified)
-
-*Cost per install*
-
-| | |
-|---:|---|
-| **Table** | **MARKETING_UA** |
-| **Calculation** | `SUM(spend) / SUM(installs)` |
-| **Parameters** | none |
-| **Topics** | ACQUISITION, SPEND |
-| **Default dims** | MEDIA_SOURCE, CAMPAIGN_NAME |
-~~~
+| Inventory roots | list semantic-model, metric, group, or rule |
+| Full root definition | get |
+| Collapsed hierarchy | tree |
+| Ranked discovery | search |
+| Entity declarations | entity |
+| Family expansion/axis resolution | family |
+| Semantic neighborhood | explore semantic-model, metric, or group |
+| Dashboard/rule impact | usage |
 
-Adapt fields per type. Rules: content, constraints, apply-on, plus `enforced` (Enforced = has constraints / applied to every query; Suggested = body-only / guides the AI) and `governs` (the tables it covers whole + any narrowed metric/dimension targets). Metrics and dimensions carry `governed_by` - the rules governing that asset, each tagged `enforced` and a `scope_tag` (`whole table` vs `this metric`/`this dimension`) - so reading a metric also shows what rules apply to it. Dimensions also: expression, semantic type, output type.
+`list metric` is flat. Families collapse in tree/search/family views.
 
-**After `graphit kb search`** - result count + table with type column:
+## Investigations
 
-~~~
-**5 results** for "revenue":
+- **Everything in finance:** explore group `finance`; present models, metrics/families, nested counts, and rules.
+- **How revenue is defined:** get metric `revenue`, then explore it for reached models and composition.
+- **What a model owns:** get the model and present entities, dimensions, measures, group, binding, and rules.
+- **What joins models:** inspect shared entities. Never look for a relationship asset.
+- **Where a metric is shown:** use usage.
+- **Physical columns:** use metadata discovery or model physical detail; do not explore a table noun.
 
-| Type | Name | Description |
-|---|---|---|
-| metric | **TOTAL_REVENUE** | Total revenue across all channels |
-| dimension | **REVENUE_BUCKET** | Revenue range segmentation |
-| synonym | GMV | Maps to **TOTAL_REVENUE** (metric) |
-~~~
+## Families
 
-**After `graphit kb explore`** - tree with bold names, indented by level:
+A family card is a view over concrete metrics. If axes match several members, show the open axes and ask. Never guess.
 
-~~~
-**CPI** (metric) on **MARKETING_UA**:
-- **Calculation:** `SUM(spend) / SUM(installs)`
-- **Tables:** **MARKETING_UA**, **MARKETING_UA_6MO** (secondary)
-- **Related dimensions (8):**
-  - **MEDIA_SOURCE** - `media_source` (categorical)
-  - **CAMPAIGN_NAME** - `campaign_name` (categorical)
-- **Rules:** **EXCLUDE_ORGANIC** (filters organic installs)
-- **Domain:** MARKETING
-- **Presented on:** **Marketing Command Center** (3 graphs) - offer to open or extend
-~~~
+## Presentation
 
-For domain exploration, show Domain > Table > Asset hierarchy as a tree, then the `presented_on` dashboards. For table exploration, list the table's columns first (`NAME - type - description`), then the metrics, dimensions, and rules defined on it.
+For metrics show type, definition, group, reached models, rules, and usage. For models show nested components. For rules show body, constraints, targets, mode, and usage. Omit concealed neighbors without hinting they exist.

package/skills/graphit/references/metric-families.md

@@ -0,0 +1,19 @@
+# Metric Families
+
+Load when the user asks for D7/D30, gross/net, payer/all, or another named metric axis.
+
+A family is a UX grouping over concrete standard metrics. There is no parameterized template, generated child engine, `$` parameter token, or call-with-arguments query syntax.
+
+Each member carries:
+
+- its own lowercase metric name and complete definition
+- `meta.graphit.family`
+- axis key/value pairs in `meta.graphit.axes`
+
+Create each concrete member with the family and repeatable axis options. Tree/search/family views collapse members; `list metric` remains flat.
+
+Use family expansion to inspect members. Supply known axes to resolve. If several candidates remain, show open axes and ask—never guess a governed metric.
+
+Reference the resolved concrete member normally with `{{ Metric('arppu_d7') }}`.
+
+Before deleting a member or family population, inspect metric usage. Dependency guards do not prove every canvas reference is absent.

package/skills/graphit/references/migration.md

@@ -42,7 +42,7 @@ name the exact branch you could not compare. That is a successful outcome, not a
 3. **Lift the complete template onto the owner.** The whole statement in `data-graphit-sql`, the data
    source in `data-graphit-ds`. Complete means executable and parameterized:
    - Keep every `:named` placeholder. Do not bake current filter values in.
-   - Keep `{{metric:NAME}}` / `{{dim:NAME}}` references as they are.
+   - Keep final `Metric`, qualified `Dimension`, and `Measure` references intact.
    - No ellipsis, no abbreviation, real table names, full WITH clause.
 4. **Preserve the rest exactly.** `params`, `deps`, the `render` callback, any branch that picks
    different SQL, and `sourceEntityId` / `targetEntityIds` attribution all stay as they were.
@@ -87,7 +87,7 @@ one statement. Everything above still applies - the hard rules, the four signals
    correct permanent end state. Stop and say so.
 2. **Lift the stabilized statement onto the entity** as `data-graphit-sql` / `data-graphit-ds`, keeping
    `:name` placeholders for everything the filters supply - never the values one run happened to use -
-   and keeping every `{{metric:}}` / `{{dim:}}` token exactly as written. Those tokens are what carry
+   and keeping every final semantic token exactly as written. Those tokens carry
    lineage once the query lives on the entity; lift a raw-expression statement and step 4 strips the
    closure off an entity that references nothing.
 3. **Prove equivalence on the four signals above,** per filter state, exactly as for a legacy migration.

package/skills/graphit/references/onboarding.md

@@ -1,6 +1,6 @@
 # First Run: From an Empty Workspace to a First Dashboard
 
-Load this when the user is signed in but the workspace is empty - `graphit kb list domains` (and `graphit ds list`) come back with nothing. That means no data is connected yet. Onboarding IS the job here, not a blocker: walk the user through it one step at a time, surfacing each result. This flow self-limits - once a data source and KB assets exist, `kb list domains` is no longer empty and you land in the normal loop instead.
+Load this when the user is signed in but visible groups/models and `graphit ds list` are empty. Onboarding is the job, not a blocker: walk through it one step at a time and surface each result. Once a source and semantic assets exist, return to the normal loop.
 
 ## The arc
 
@@ -35,11 +35,12 @@ Before creating anything, ask what business question the user wants to answer. T
 
 Explain that answering the question fast needs a cached data source over the connection, not repeated live-warehouse queries.
 
-**A domain comes first.** Every data source is created inside a KB domain - it is what makes the source findable and grantable, and there is no uncategorized fallback. A brand-new workspace has only the org-wide commons, so check with `graphit kb list domains` and, if the user's work deserves its own area, agree a name and create it before the source:
+**Scope comes first.** A semantic group organizes assets, while data-source `--domain` takes the uppercase policy key returned by `graphit status` or a group's `domain_keys`. A brand-new workspace starts with org commons. Agree the audience and group before creating the source:
 
 ```bash
-graphit kb list domains
-graphit kb create domain --name MARKETING --description "Acquisition and spend"
+graphit kb list group
+graphit status --json
+graphit kb create group --name marketing --description "Acquisition and spend"
 ```
 
 **Read the table before you write its SQL.** You cannot author a source SELECT without knowing the columns, and guessing them wastes a round trip. Read them straight off the warehouse:

package/skills/graphit/references/presentations.md

@@ -77,7 +77,7 @@ deck.slide({
   html: `
     <h2>Live Data</h2>
     <div data-graphit-id="spend-chart" data-graphit-label="Ad Spend"
-         data-graphit-sql="SELECT {{dim:MEDIA_SOURCE_DIMENSION}} AS source, {{metric:TOTAL_AD_SPEND}} AS spend FROM MARKETING_UA_DS GROUP BY 1 ORDER BY spend DESC LIMIT 6"
+         data-graphit-sql="SELECT {{ Dimension('campaign__media_source') }} AS source, {{ Metric('total_ad_spend') }} AS spend FROM MARKETING_UA_DS GROUP BY 1 ORDER BY spend DESC LIMIT 6"
          data-graphit-ds="MARKETING_UA_DS">
       <div id="chart1" 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="#e5e5e5" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="#4DB6AC" stroke-width="2.5" stroke-linecap="round"/></svg></div>

package/skills/graphit/references/runtime.md

@@ -30,7 +30,7 @@ const result = await graphit.resolve({
 
 MUST: every resolve feeding a rendered graph, KPI, or table carries attribution - `target` (the entity wrapper or an element inside it), or `sourceEntityId` plus `targetEntityIds` when one result feeds several graphs. Attribution records the live filtered query behind that entity's details panel; unattributed, the panel shows `data-graphit-sql` as an unrun example, so a user changing a filter sees the SQL never move. Saving a page with filters or params and zero attributed resolves returns an `unattributed_resolves` warning. Queries feeding page chrome need no attribution and no entity, but belong on the primitives - `graphit.cascade` for option lists, `graphit.dataBounds` for a column's min/max, `graphit.rank` for top-N (`filters-advanced.md`) - never hand-written entity-less SQL.
 
-CRITICAL: use KB reference syntax (`{{metric:NAME}}`, `{{dim:NAME}}`) inside the entity's `data-graphit-sql` whenever a KB asset exists - the server expands it at query time, producing the governed trust tier. Syntax and trust tiers: `governance.md`.
+CRITICAL: use `{{ Metric('name') }}`, `{{ Dimension('entity__name') }}`, or Graphit's `{{ Measure('name') }}` extension inside `data-graphit-sql` whenever the semantic asset exists. The server expands it into the governed tier. See `governance.md`.
 
 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 in the target element on failure. Verify the SQL returns data via the CLI before embedding it.
 
@@ -41,7 +41,7 @@ Every visible element - chart, KPI card, table, text section - must be wrapped s
 ```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-sql="SELECT {{ Dimension('order__region') }} AS region, {{ Metric('revenue') }} AS revenue FROM ORDERS_DS GROUP BY region"
      data-graphit-ds="ORDERS_DS">
   <!-- chart, KPI, or table content here -->
 </div>
@@ -55,7 +55,7 @@ Every visible element - chart, KPI card, table, text section - must be wrapped s
 | `data-graphit-ds` | Data source name (same as the FROM table) or id | `"ORDERS_DS"` |
 | `data-graphit-state` | Not an entity attribute - a SIBLING wrapper around a user-changeable control, naming the state key saved views capture (`filters.md`) | `"country"` |
 
-KB asset references are derived automatically from `{{metric:X}}` / `{{dim:X}}` in the SQL; the governance compiler resolves these and shows KB asset chips in the details panel. Missing any one attribute breaks the entity; missing the wrapper makes the element invisible to the platform.
+Semantic references are derived automatically from the final grammar; the compiler resolves them and shows asset chips in the details panel. Missing any one attribute breaks the entity; missing the wrapper makes the element invisible to the platform.
 
 **JavaScript may populate an entity, never create one.** Every entity - including on hidden tabs, collapsed panels, and lazily-shown views - exists as static markup in the HTML you save; JavaScript fills its chart host, wires listeners, and toggles visibility. Nothing server-side runs your JavaScript, so a card built at render time (`host.innerHTML = charts.map(...)`) does not exist for governance, lineage, the KB graph, `list-entities`, or a later `get-entity`. A save whose `data-graphit-id`s are reachable only by running your JavaScript is REFUSED and the error names them. A dynamic **query** is supported - the attribute carries the canonical template; a dynamic **entity** is not.
 
@@ -74,14 +74,14 @@ A filtered entity uses `graphit.bind(el, { params, deps, render })` (`filters.md
 
 ```html
 <div data-graphit-id="explorer" data-graphit-label="Metric Explorer" data-graphit-ds="UA_DS"
-     data-graphit-sql="SELECT day, {{metric:ROAS}} AS roas FROM UA_DS GROUP BY 1"
-     data-graphit-vocab="metric:REV*,metric:ROAS,dim:COUNTRY"></div>
+     data-graphit-sql="SELECT day, {{ Metric('roas') }} AS roas FROM UA_DS GROUP BY 1"
+     data-graphit-vocab="metric:revenue,metric:roas,dimension:campaign__country"></div>
 ```
 ```js
 graphit.resolve({ sql: buildSql(picked), dataSourceId: "UA_DS", runtimeComposed: true, sourceEntityId: "explorer" });
 ```
 
-`metric:NAME` / `dim:NAME`, UPPER_SNAKE_CASE, one optional trailing `*` per family; a space instead of a comma is one malformed entry. Declare the family, not today's SQL - but every name must exist (an unknown name, a wildcard matching nothing, or a bare `metric:*` refuses), and wildcards alone add no lineage. Undeclared inline SQL is invisible to lineage and governance; a save that ADDS one is refused, and existing ones are not a defect to fix - move a query onto its entity only when asked (`migration.md`).
+Use comma-separated lowercase declarations such as `metric:revenue`, `dimension:order__region`, and `measure:order_total`. Every declared name must exist; unknown names and wildcards refuse. Undeclared inline SQL is invisible to lineage and governance. Existing runtime-composed queries are first-class, not debt; migrate query ownership only when asked (`migration.md`).
 
 **Label equals the visible title.** `data-graphit-label` MUST match the card's visible heading exactly - users find their chart by that label in @ mention dropdowns and entity panels, and a mismatch means they cannot find it.
 

package/skills/graphit/references/semantic-authoring.md

@@ -0,0 +1,81 @@
+# Semantic Authoring
+
+Load when creating or changing semantic models or metrics.
+
+## Syntax boundary
+
+Graphit accepts the MetricFlow 0.211 execution shape: semantic models contain
+entities, dimensions, and measures; metrics are top-level objects with `type`
+and `type_params`. Do not emit newer measureless/Fusion authoring syntax, dbt
+project YAML, Jinja, `ref()` expressions, or source declarations on this
+surface. Those belong to dbt project import/export, not Graphit authoring.
+
+Public dbt/MetricFlow concepts:
+
+- semantic model, entity, dimension, measure, metric, and group
+- simple, ratio, and derived metric composition
+- entity-qualified dimension paths
+
+Graphit extensions and assets:
+
+- `meta.graphit.family` and `axes` group concrete metric variants
+- topics are curated Graphit metadata, deliberately not dbt `tags`
+- rules are separate Graphit objects targeting semantic identities by name;
+  never embed them in dbt metadata
+- verification attribution, provenance, and data-source bindings are
+  server-owned; use dedicated actions instead of hand-authoring them
+
+Do not expose or depend on storage collection names, revision fields, feature
+flags, cache keys, or compiler implementation details.
+
+## Semantic model
+
+A semantic model owns:
+
+- lowercase name and physical model/binding
+- group placement
+- primary grain/entity
+- entities for joins
+- dimensions for grouping/filtering
+- measures for aggregation input
+- defaults such as aggregation time dimension
+
+Measure-bearing models need a valid aggregation time dimension. Primary/unique entity claims require grain evidence; never guess uniqueness. Time-aware shapes require the platform time-spine prerequisite.
+
+Nested lists replace whole lists on update. Read the model and preserve every sibling.
+
+## Metrics
+
+Only these shapes are served by the shipping fragment path:
+
+- **simple:** one measure object
+- **ratio:** numerator and denominator metric objects
+- **derived:** expression over declared metric inputs or aliases
+
+Metric-level and per-input filters must resolve through declared semantic identities. Bare strings where an input object is required are refused.
+
+Cumulative, conversion, shifted inputs, time-spine joins, and null-fill are not yet supported. Use a supported decomposition or clearly labeled free SQL; do not create an unusable governed definition.
+
+## Aggregation safety
+
+| Class | Across dimensions | Across time | Examples |
+|---|---|---|---|
+| Fully additive | Sum | Sum | revenue, clicks, units |
+| Semi-additive | Sum | Last/period-end snapshot | cash, MRR, headcount |
+| Non-additive | Recompute | Recompute | rates, ratios, distinct counts |
+
+Never sum or average a rate/ratio - recompute from additive components at the requested grain, guard zero denominators, and examine mix shift before interpreting rollups.
+
+Measure `agg` accepts: sum, count, count_distinct, average, min, max, median, percentile, sum_boolean. A simple metric references a declared measure, never a raw column; a ratio references numerator/denominator metrics, never measures directly; every identifier in a derived expression must match an input name or alias exactly.
+
+## Plan ordering
+
+When authoring several definitions, sequence prerequisites first: group, then data sources, then semantic models with nested components, then simple metrics, then ratio/derived metrics that reference them, then rules after their targets exist. Execute one item at a time; do not start the next before the current receipt is terminal.
+
+## Verification
+
+Create defaults to verified on human-driven CLI paths; `--unverified` creates a draft. Promote or demote with dedicated verify/unverify actions. Never replace `meta` only to toggle verification.
+
+## Final check
+
+Re-read the root, verify nested completeness, inspect group/binding, and use the returned receipt. A degraded freshness result may mean the write landed; do not retry blindly.

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

@@ -1,6 +1,6 @@
 # SQL Reference
 
-Consult when writing queries. Data source queries (`graphit query --ds`) always run DuckDB. Warehouse queries (`graphit query --warehouse`) run the connected warehouse - Snowflake or BigQuery - and the dialect follows the connection type; governance parses your SQL in that dialect. You MUST use the correct dialect. To read a table's columns, use `graphit kb explore table <NAME>` - never `DESCRIBE`/DDL (`graphit query` runs SELECT only).
+Consult when writing queries. Data-source queries run DuckDB. Warehouse queries run the connected Snowflake or BigQuery dialect. Governance parses the same dialect. Read physical columns through metadata discovery or semantic-model physical detail; never use DDL through the SELECT-only query surface.
 
 ## DuckDB vs Snowflake Translation
 
@@ -49,6 +49,15 @@ NEVER use `->>`  in Snowflake or `:field::STRING` in DuckDB.
 - Snowflake does NOT support `FILTER (WHERE)` - use `CASE WHEN` instead
 - `COUNT_IF` MUST receive a boolean expression, not a raw INT column. Use `COUNT_IF(is_active = 1)`, not `COUNT_IF(is_active)`
 - String matching: prefer `ILIKE` (case-insensitive) over `LIKE`
+- No `DISTINCT ON` (use `ROW_NUMBER()`); no negative array indices
+- Geospatial: `ST_MAKEPOINT(lon, lat)` - lon FIRST; `ST_DISTANCE` returns meters
+
+## Null / Join Safety
+
+- `COUNT(column)` drops nulls; `COUNT(*)` does not
+- Never `NOT IN` on nullable values (one null matches nothing); use `NOT EXISTS`
+- One-to-many joins multiply measures unless the many side is pre-aggregated
+- DuckDB JSON array check: `json_array_length(...)`, never `->0 IS NOT NULL`
 
 ## BigQuery Standard SQL Notes
 
@@ -138,22 +147,20 @@ The canvas `percent` format only appends `%` (it does not multiply by 100), so m
 
 ## Presenting Query Results
 
-After every `graphit query`, present results grounded in the KB. Always show which KB assets were used - this is what makes governed queries valuable.
-
-**When using KB reference syntax** (`{{metric:X}}`, `{{dim:X}}`), show all five sections:
+After every query, show all five sections below. Use `--verbose` to obtain the resolved SQL. Executable SQL uses semantic references; narration uses backticked exact asset names so Graphit can render clickable KB pills.
 
 ~~~
-**KB Assets:** dimension **CAMPAIGN_CATEGORY**, metric **TOTAL_INSTALLS**, metric **CPI**, table **MARKETING_UA_DS**
+**KB Assets:** dimension `campaign__category`, metrics `total_installs` and `cpi`, semantic model `marketing_ua`
 
 **Query:**
 ```sql
 SELECT
-    {{dim:CAMPAIGN_CATEGORY}} AS category,
-    {{metric:TOTAL_INSTALLS}} AS installs,
-    {{metric:CPI}} AS cpi
+    {{ Dimension('campaign__category') }} AS category,
+    {{ Metric('total_installs') }} AS installs,
+    {{ Metric('cpi') }} AS cpi
 FROM MARKETING_UA_DS
 WHERE ACTIVITY_TIME >= '2026-01-01'
-GROUP BY {{dim:CAMPAIGN_CATEGORY}}
+GROUP BY {{ Dimension('campaign__category') }}
 ORDER BY installs DESC
 ```
 
@@ -179,17 +186,9 @@ ORDER BY installs DESC
 | Retargeting | 12,300 | $1.24 |
 | Connected TV | 3,100 | $2.80 |
 
-**Governance:** governed - 3 KB refs, 2 rules enforced (**EXCLUDE_ORGANIC**, **MIN_SPEND**). Max rows: 1,000.
-~~~
-
-**When using inline SQL** (no `{{metric:X}}`), present it the same way (query + results + governance), but the footer states the ad-hoc tier and offers the governed rewrite:
-
+**Governance:** governed - 3 semantic refs; 2 rules enforced (`exclude_organic`, `min_spend`). Max rows: 1,000.
 ~~~
-**Governance:** ad-hoc - 0 KB refs. Consider using `{{metric:TOTAL_SPEND}}` for governed tier.
-~~~
-
-Any ad-hoc query on the CLI is withheld until you justify it (full rules in governance.md): prefer a `{{metric:X}}` / `{{dim:X}}` rewrite, creating the metric or dimension first if it is missing, and pass `--adhoc-reason` only when nothing governed fits.
 
-**Always use `--verbose`** to get the resolved SQL; if the user didn't pass it, re-run with it.
+For inline SQL, use the same sections but state the ad-hoc tier and offer a governed rewrite, for example: **Governance:** ad-hoc - 0 semantic refs. Consider `{{ Metric('total_spend') }}`. Author a supported root definition first when needed; provide an ad-hoc reason only when nothing governed fits.
 
-Zero rows: explain what you checked and hypothesize why (wrong date range, filter too strict, table empty).
+For zero rows, explain the checks performed and likely cause, such as date range, filter, or empty source.

package/dist/commands/kb-constraints.d.ts

@@ -1,14 +0,0 @@
-/**
- * Pure parsers for `graphit kb create/update rule` --constraint / --apply-on flags.
- *
- * Extracted from kb.ts so they are unit-testable without Commander or the API
- * client (mirrors query-timeout.ts). Issue #548: the required_where quote
- * stripper used to remove ANY leading/trailing quote, so a predicate ending in
- * a SQL string literal lost its closing quote
- * (`MEDIA_SOURCE != 'organic'` -> `MEDIA_SOURCE != 'organic`), producing
- * unparseable SQL that the backend rejected - the constraint never persisted.
- */
-/** Strip wrapping quotes only when the value is wrapped in a matched pair. */
-export declare function unwrapQuotes(value: string): string;
-export declare function parseConstraintFlags(specs: string[]): Record<string, unknown>[];
-export declare function parseApplyOnFlags(specs: string[]): Record<string, string>[];

package/dist/commands/kb-constraints.js

@@ -1,53 +0,0 @@
-/**
- * Pure parsers for `graphit kb create/update rule` --constraint / --apply-on flags.
- *
- * Extracted from kb.ts so they are unit-testable without Commander or the API
- * client (mirrors query-timeout.ts). Issue #548: the required_where quote
- * stripper used to remove ANY leading/trailing quote, so a predicate ending in
- * a SQL string literal lost its closing quote
- * (`MEDIA_SOURCE != 'organic'` -> `MEDIA_SOURCE != 'organic`), producing
- * unparseable SQL that the backend rejected - the constraint never persisted.
- */
-/** Strip wrapping quotes only when the value is wrapped in a matched pair. */
-export function unwrapQuotes(value) {
-    const first = value[0];
-    if (value.length >= 2 &&
-        (first === '"' || first === "'") &&
-        value[value.length - 1] === first) {
-        return value.slice(1, -1);
-    }
-    return value;
-}
-export function parseConstraintFlags(specs) {
-    return specs.map((spec) => {
-        const colonIdx = spec.indexOf(":");
-        if (colonIdx < 0)
-            throw new Error(`Invalid constraint: "${spec}". Use type:value (e.g., forbidden_column:email)`);
-        const type = spec.slice(0, colonIdx);
-        const value = spec.slice(colonIdx + 1);
-        switch (type) {
-            case "required_where":
-                return { type, predicate: unwrapQuotes(value) };
-            case "forbidden_column":
-            case "required_filter":
-            case "required_aggregation":
-                return { type, column: value };
-            case "value_restriction": {
-                const [col, op, ...valueParts] = value.split(":");
-                const operator = op === "not_in" ? "not_in" : "in";
-                return { type, column: col, values: valueParts.join(":").split(","), operator };
-            }
-            default:
-                throw new Error(`Unknown constraint type: "${type}"`);
-        }
-    });
-}
-export function parseApplyOnFlags(specs) {
-    return specs.map((spec) => {
-        const colonIdx = spec.indexOf(":");
-        if (colonIdx < 0)
-            throw new Error(`Invalid apply-on: "${spec}". Use type:NAME (e.g., table:USERS)`);
-        return { type: spec.slice(0, colonIdx), name: spec.slice(colonIdx + 1) };
-    });
-}
-//# sourceMappingURL=kb-constraints.js.map

package/dist/commands/kb-constraints.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"kb-constraints.js","sourceRoot":"","sources":["../../src/commands/kb-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IACE,KAAK,CAAC,MAAM,IAAI,CAAC;QACjB,CAAC,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC;QAChC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,KAAK,EACjC,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAe;IAClD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,kDAAkD,CAAC,CAAC;QAClH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;QACvC,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,gBAAgB;gBACnB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,KAAK,kBAAkB,CAAC;YACxB,KAAK,iBAAiB,CAAC;YACvB,KAAK,sBAAsB;gBACzB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACjC,KAAK,mBAAmB,CAAC,CAAC,CAAC;gBACzB,MAAM,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,UAAU,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAClD,MAAM,QAAQ,GAAG,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;gBACnD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC;YAClF,CAAC;YACD;gBACE,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,GAAG,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAe;IAC/C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,sCAAsC,CAAC,CAAC;QACpG,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;IAC3E,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/kb-create.d.ts

@@ -1,2 +0,0 @@
-import { Command } from "commander";
-export declare function addKBCreateCommands(kb: Command): void;