@graphit/cli 0.2.321 → 0.2.323

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

@@ -1,79 +1,50 @@
 # KB Discovery
 
-Consult when starting a dashboard build, or when the user references a business concept that might already exist as a KB asset. The Knowledge Base holds reusable metrics, dimensions, rules, and table schemas - using them keeps formulas consistent across dashboards and makes each new graph faster to build.
+Load before querying, authoring, or building a dashboard.
 
-## Domain-First Discovery
+## Group-first discovery
 
-Work narrow, not broad: **domain -> data source -> assets.** The first move is always to explore one domain, not to list or search the whole KB.
+1. Read visible groups and effective status.
+2. Choose a group and confirm the audience.
+3. Explore semantic models and root metrics.
+4. Read model-owned entities, dimensions, and measures.
+5. Inspect retained rules and dashboard usage.
+6. Reuse definitions before proposing a gap.
 
-1. **Scope to the domain.** Ask the user which business area this is about - present the real domains and let them pick; do not assume the domain. When a concept could span domains and you cannot name the domain, `graphit kb explore topic <NAME>` returns everything tagged with that concept across every domain - use it to land on the right domain.
-2. **Explore that domain.** `graphit kb explore domain <NAME>` returns the domain's data sources plus the metrics, dimensions, and rules defined on them, in one traversal. This is your working set, and it is the primary discovery call.
-3. **Reuse the assets.** If a metric fits, read its formula with `graphit kb get metric REVENUE` and reference it by name in SQL as `{{metric:REVENUE}}`.
-4. **Handle gaps.** If the domain's data source is missing something, check `graphit kb list relationships` for a connection to another data source you can join; if the data genuinely does not exist, propose creating the asset or a new data source (see below).
-5. **Broaden only as a fallback.** Use `graphit kb search "<concept>"` only when an exploration came up empty or the concept name is too fuzzy to match a domain or topic. Search is semantic (matches by meaning, ranked by a relevance `score`) merged with name/text matching, and capped by `--limit` - the result carries `total` and `truncated`. So an empty or unexpected result means *maybe ranked-out or truncated*, never proof an asset is absent: raise `--limit`, narrow `--type`, or confirm a specific name with `kb get` before concluding it doesn't exist. `graphit kb list` carries `total`/`truncated` too - fewer rows than `total` means the list was capped, not that assets are missing; raise `--limit`. (`graphit kb list domains` enumerates domain names when you need to pick one; it is a name lookup, not the asset-discovery path - explore the domain to see its assets.)
+The lowercase group name is the semantic label. Use the server-provided uppercase `domain_keys`/status key for data-source `--domain`.
 
-If a domain has tables but no metrics or dimensions, that is the strongest signal to propose foundational assets before building any graph - this is the KB-readiness gate the build workflow enforces. **Exception:** when a response carries `migration_incomplete: true`, the org's KB rows are mid-migration and invisible, so emptiness is not evidence of anything - report the migration state instead of proposing creation. If the user declines ("just build it", "skip KB"), respect it and work from the table schema - read its columns with `graphit kb explore table <NAME>`.
+## Choosing the object
 
-## Metric vs Dimension
+| Need | Object |
+|---|---|
+| Modeled relation, grain, joins, columns | semantic model |
+| Join identity or grain | entity inside a model |
+| Grouping/filter field | dimension inside a model |
+| Aggregation input | measure inside a model |
+| Reusable business calculation | metric |
+| Organizational placement | group |
+| Governance guidance/enforcement | rule |
+| D7/D30 or gross/net variant | concrete family member |
 
-| Property | Metric | Dimension |
-|---|---|---|
-| Formula | Aggregation required (SUM, COUNT, AVG, MIN, MAX) | Row-level only (no aggregates) |
-| Table scope | Can reference multiple tables | Exactly one table |
-| Purpose | Measures - what you count or sum | Grouping axes - how you slice |
-| Example | `SUM(ORDERS.AMOUNT)` | `DATE_TRUNC('month', EVENTS.EVENT_TS)` |
-| Invalid | `ORDERS.AMOUNT` (no aggregate) | `SUM(EVENTS.DURATION)` (has aggregate) |
+Entities replace relationship assets. Topics are metadata, not roots. Synonyms are removed; search names/descriptions and ask when wording is ambiguous.
 
-## When to Propose KB Asset Creation
+## Read roles
 
-| Signal | Propose | Why |
-|---|---|---|
-| User requests a business metric (revenue, DAU, conversion rate) with no KB match | Metric | Reusable formula across dashboards |
-| User groups by a derived expression (date bucket, category mapping, JSON extraction) | Dimension | Consistent grouping logic |
-| User describes a business rule ("active = logged in within 30 days") | Rule | Applied automatically to future queries |
-| User uses a business term not in KB ("GMV", "churn", "ARPU") | Synonym | Maps colloquial terms to a defined metric |
+- `list` inventories a root noun.
+- `tree` shows the collapsed hierarchy.
+- `search` covers models, metrics, groups, and nested components; not retained rules.
+- `get` reads one exact root.
+- `entity` reads one entity across visible declaring models.
+- `family` expands/resolves concrete members.
+- `explore` accepts semantic-model, metric, or group.
+- `usage` answers dashboard placement and rule impact.
 
-Propose creation as the default path, in plain language: "Your KB has no revenue metric yet. I'd create one first - then it's reusable across every dashboard with a consistent formula, and I'll build the graph on it. Sound good?"
+A capped or empty search is not proof of absence.
 
-## Naming Conventions
+## Governed references
 
-All KB assets are UPPER_SNAKE_CASE (auto-sanitized on write):
+Use `{{ Metric('revenue') }}`, `{{ Dimension('order__channel') }}`, and `{{ Measure('order_total') }}` only for Graphit's measure extension. Legacy token grammar is refused.
 
-| Pattern | Example | Use when |
-|---|---|---|
-| `TOTAL_*` | `TOTAL_REVENUE`, `TOTAL_ORDERS` | Sum aggregations |
-| `AVG_*` | `AVG_ORDER_VALUE` | Average metrics |
-| `COUNT_*` | `COUNT_ACTIVE_USERS` | Count metrics |
-| `*_RATE` | `CONVERSION_RATE`, `CHURN_RATE` | Ratios / percentages |
+## Gap decision
 
-> `*_RATE`/ratio columns are usually 0-1 fractions. To chart them as a percent, multiply by 100 in SQL (`* 100.0`) - `"percent"` format appends `%` without scaling.
-
-## Formula Syntax
-
-Metrics reference `TABLE.COLUMN` with UPPERCASE naming:
-
-```sql
--- Metric formulas (aggregation required)
-SUM(ORDERS.AMOUNT)
-COUNT(DISTINCT EVENTS.USER_ID) WHERE EVENTS.EVENT_TS >= DATEADD(day, -30, CURRENT_DATE)
-SUM(ORDERS.REVENUE) / NULLIF(SUM(ORDERS.COST), 0)
-
--- Dimension formulas (no aggregates)
-EVENTS.PLATFORM
-DATE_TRUNC('month', EVENTS.EVENT_TS)
-CASE WHEN USERS.AGE >= 18 THEN 'adult' ELSE 'minor' END
-```
-
-Use CASE WHEN for conditionals (Snowflake has no FILTER WHERE). Always guard division with NULLIF.
-
-When creating assets, pass `--topics` to tag the business concept (check existing topic names first) and `--default-dimensions` on a metric to declare its natural grouping axes. Dimension types are auto-inferred from the column schema; override with `--type` / `--output-type` only when the inference is wrong. Full create / update / delete matrix: `kb-actions.md`.
-
-## Reuse Over Reinvention
-
-When several graphs share a concept, propose ONE KB asset instead of repeating the formula: 3 graphs using `SUM(ORDERS.AMOUNT)` become one `TOTAL_REVENUE` metric; 2 graphs grouping by `DATE_TRUNC('month', TS)` become one `MONTHLY` dimension.
-
-For the same concept on a sibling table with identical columns, **reference** it rather than duplicating: `graphit kb update metric TOTAL_REVENUE --secondary-tables "ORDERS_12M"`. This is a pointer, not a copy - edits propagate to all placements, and referenced placements show a `*` in the KB tree. Metrics and dimensions require every referenced column to exist on the target table (checked on save); rules only require the table to exist. Suggest it when the user has sibling sources (e.g. 6M and 12M windows) or asks to make a metric available on another table.
-
-**Where is a known asset already shown?** `explore` shows *where* ambiently (`presented_on` lists the dashboards); `graphit kb usage metric REVENUE` is the directed deep dive: per-chart hits - reuse them, don't rebuild. `--metric X --dimension Y` finds co-occurrence (not a proven `GROUP BY`); only governed `{{metric:}}`/`{{dim:}}` usage is indexed. `graphit kb usage rule X` lists every chart a rule is enforced on (impact analysis).
-
-For the graph model and structural questions (vertical home vs horizontal topics), see `kb-structure.md`; for read commands and result templates, see `kb-traversal.md`.
+Propose authoring only when no visible definition fits and business meaning is clear. State formula, grain, binding, group, rule impact, and verification. Ask when any is ambiguous.

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

@@ -1,23 +1,25 @@
-# KB Scope: Who Will See It
+# KB Scope
 
-Consult BEFORE creating or moving any KB asset, and whenever the user asks who can see something. A domain is not only a filing shelf, it is the access boundary, so choosing one is choosing an audience - and the choice is not freely reversible.
+Load when deciding who may see or change semantic work.
 
-| Scope | Who reads it | Use it for |
-|---|---|---|
-| The org commons | Everyone in the organization. It always exists, cannot be deleted, and is where an org-wide asset belongs | Definitions the whole company shares, and anything with no narrower home |
-| A shared business domain | Whoever has been granted it. `graphit status` shows the caller's own access, advisory only - the server decides | The normal case: work a team owns and reuses |
-| A private space | Its owner alone. Invisible to everyone else, admins included, and shown simply as "Private" | Scratch work, or data someone is not ready to share |
+## Two names, two purposes
 
-**Settle the scope with the user before creating anything.** Ask which of these the work belongs in rather than inferring it, and say plainly what the choice means: work put in a private space will not appear for their team at all. Default to a shared domain (or the commons) for anything the team should be able to use.
+- **Group name:** lowercase semantic placement, such as `finance`.
+- **Policy domain key:** uppercase access key returned by status or `domain_keys`, such as `FINANCE`. Data-source `--domain` uses this key.
 
-If a create or update response carries a `visibility` notice, the asset landed where only its author can read it. Relay the notice, and if the user meant the work for their team, treat that as the moment to fix the scope - not a detail to skip past.
+Never invent the key when the server returned it.
 
-**It is not freely reversible**, which is why the question comes first:
+## Visibility
 
-- An asset whose DEFINITION reads a private table (a metric's dependencies, a synonym's canonical target, a relationship's tables, or a table's own home) is readable by its author alone. That is by design, and it stays that way.
-- Redefining an ALREADY-SHARED asset onto a private table is refused, because it would remove a working asset from the team without telling them. Copy it into the private space instead and change the copy.
-- ATTACHING a private table to a shared asset as a placement (a secondary table, a rule target, an extra domain) is fully supported: the asset stays shared and usable, and nobody else sees the private reference. This is the safe way to enrich a team asset with something personal.
+- Org commons is a synthetic shared scope.
+- A private workspace is visible only to its owner; admins are concealed too.
+- Hidden and missing assets are the same absence.
+- Models and metrics inherit visibility from group placement.
+- Group `access` is dbt metadata and does not grant Graphit access.
+- Rules use server-owned target-derived domain keys.
 
-**When a delete is refused over someone's private dependency.** Deleting a shared asset can be blocked because another member's PRIVATE asset depends on it. The refusal names the owners to go ask - never their assets - and that attribution is the point: relay who is named and suggest asking them first. `--force` on `kb delete` proceeds anyway (it is offered only when every hidden blocker has a named owner), and every named owner is notified of what was deleted, by whom, and what of theirs broke. Treat `--force` as the user's deliberate escalation: never add it on your own to get past a refusal.
+## Writes
 
-Never read a private space's stored name aloud or invent one. Refer to it as the user's private space. To target it in a command, pass `--domain Private` - the alias always resolves to the caller's OWN space, so no spelling of it can reach anyone else's.
+Read access is the ceiling. A user also needs `kb_write` for the affected key; group lifecycle is admin-only. Moving an asset requires authority over current and destination scopes.
+
+Before authoring confirm audience, group, policy key, shared/private scope, and write capability. Never name concealed groups, assets, targets, or counts.

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

@@ -1,68 +1,42 @@
-# KB Structure (Plan)
+# KB Structure
 
-This is the plan side of KB work: how the Knowledge Base is organized, so you can explain it and design what to build. The execute side - the actual `graphit kb` create / update / delete commands - lives in `kb-actions.md`. On a from-scratch KB build the two pair up: design the graph here, then run the commands there. On a normal build that reuses existing assets, you mostly read this to answer a structural question.
+Load when planning, explaining, or locating semantic assets.
 
-The KB is a labeled property graph: assets carry tags that place them in a tree, but the underlying structure is a graph with typed edges. Answer structural questions in business-friendly language, grounded in actual KB state (verify with `graphit kb get` / `graphit kb explore` when the question names a specific asset).
+## Root model
 
-## Node Types
-
-| Type | Description |
-|------|-------------|
-| metric | Aggregation formula (SUM, COUNT, AVG) that computes a business KPI |
-| dimension | Row-level SQL expression on one table, used for grouping or filtering |
-| rule | Free-text business constraint, optionally scoped to one or more tables |
-| synonym | Maps a business term to a canonical metric, dimension, or column |
-| table | Physical data location in the warehouse, with typed columns |
-| topic | Business-concept tag applied to assets (e.g., REVENUE, ACQUISITION) |
-| domain | High-level business area (e.g., MARKETING, SALES, PRODUCT), and the boundary that decides who can see what sits in it |
-| relationship | Documented JOIN pattern between two tables |
-| memory | Org-level context notes, always global scope |
-
-## Edge Types
-
-| Edge | From | To | Meaning |
-|------|------|----|---------|
-| depends_on | metric, dimension | table | Asset's SQL references columns in this table |
-| tagged_with | metric, dimension, rule, synonym | topic | Asset carries this business-concept tag |
-| in_domain | table, metric, dimension, rule, synonym | domain | A table has one home domain; assets inherit it from their primary table, plus any cross-cutting extras |
-| joins | relationship | table, table | Two tables have a documented JOIN on specific columns |
-| references | rule, synonym | table, column | Rule or synonym references a specific table or column name |
-
-## How Membership Works
-
-Two different axes organize the KB - keep them separate:
-
-- **Vertical: the home (domain -> data source -> assets).** Containment that cascades. An asset has ONE home domain, inherited from its primary table (the data source its SQL reads). Set the domain on the **table** (`graphit kb update table NAME --domain MARKETING`) and every asset on it inherits it; the asset carries no domain tag of its own. To move an asset's home, change its table's domain. Domain-first discovery walks this axis downward.
-- **Horizontal: the concept (topics).** Topics cut ACROSS domains. The same topic (e.g. RETENTION) can tag assets in different domains, grouping them by business meaning regardless of where they sit. An asset can carry several topics at once (`graphit kb update metric NAME --topics "REVENUE,RETENTION"`), and a topic never moves an asset's home. When a concept spans domains, the by-topic view is how you find everything about it.
+| Type | Meaning |
+|---|---|
+| group | Organizational placement; Graphit access still comes from profiles and policy keys |
+| semantic model | One modeled relation and the aggregate root for entities, dimensions, and measures |
+| metric | Reusable simple, ratio, or derived calculation |
+| rule | Retained Graphit governance object targeting semantic identities |
 
-Other placements layered on top:
-- **Multiple tables**: a metric or dimension can depend on several tables (a JOIN across ORDERS and CUSTOMERS) and appears under each. Table dependency is structural, derived from the SQL, never tagged manually.
-- **Referencing (`secondary_tables`)**: an asset can be referenced onto extra tables; it shows under the target with a `*` suffix, links back to the original, and stays editable only from its home table. Table-backed assets derive domain membership from all their tables (primary plus `secondary_tables`).
-- **Cross-cutting domains**: synonyms can carry extra domains in `extra_domain_ids` for relevance beyond their home, without moving the asset in the tree.
+Nested components are not independent CRUD roots:
 
-Domains are coarse and few (broad business areas); topics are finer and more numerous. A single domain like MARKETING typically spans topics such as ACQUISITION, ATTRIBUTION, and CAMPAIGN_PERFORMANCE.
+- **Entity:** join/grain identity. Primary or unique entities prove the keyed side; foreign entities connect models.
+- **Dimension:** model-owned grouping/filter field. Address cross-model dimensions as `entity__dimension`.
+- **Measure:** model-owned aggregation input used by simple metrics.
 
-A domain is also the access boundary: it decides who can see what sits in it. Settle that with the user before creating anything - see kb-scope.md.
+A metric family is a set of concrete metrics carrying the same family name plus axis values. It is not a template asset.
 
-## Tree Rendering Order
+## Relationships
 
-The default tree renders Domain > Table > Topic > Asset, with each table under its one home domain. This is a visualization choice; the model also supports Topic > Table or a flat list. When the user asks "where is X?", an asset lives under its primary table's home domain - report that, plus any domains from its `secondary_tables` placements and its topics.
+- A group's models and metrics are placed by their `group` field.
+- A semantic model owns all nested components.
+- Metrics reach models through referenced measures and metrics.
+- Models join through shared entities. There is no relationship asset.
+- Rules may target a model, entity, dimension, metric, or group.
+- Topics remain metadata in `meta.graphit`; they are not roots.
+- Dashboard usage is a reverse lookup, not a stored placement.
 
-## Answering Structural Questions (Tier 1)
+## Names and visibility
 
-Structural questions have direct answers - give them in business terms:
+Semantic names are lowercase snake case. Double underscore is reserved for qualified dimensions. A group name is displayed lowercase; data-access status exposes the uppercase policy key used by data-source `--domain`.
 
-| Question | Answer pattern |
-|---|---|
-| What is a topic / domain / table / relationship? | Use the Node Types descriptions above, in plain language |
-| Why is [metric] under [table]? | Its SQL depends on that table's columns (or it is referenced there via `secondary_tables`, shown as `*`) |
-| Why is [asset] in [topic]? | Someone tagged it - topics are manual, not derived. Check its topics list |
-| Why is [asset] in [domain]? | Its primary table's domain cascades to it; it was not tagged directly |
-| What is a relationship? | A documented JOIN between two tables (which columns, which join type) used to build correct cross-table SQL |
-| What is memory? | Org-level context notes (goals, terminology, conventions), global scope, shown at the tree root |
+Concealment is absence. A hidden asset is exactly like a missing one. Private workspaces are visible only to their owner, including from admins.
 
-Verify against actual KB state when the question names a specific asset (`graphit kb get`, `graphit kb explore`).
+## Tree and graph
 
-## Semantic Questions (Tier 2 - Different Handling)
+Tree order is group → semantic model → nested components, with root metrics and rules alongside. Families collapse in tree/search/family views; `list metric` returns concrete metrics.
 
-Questions about what a concept MEANS at this org ("what does revenue mean for us?", "how do we define an active user?") are semantic, not structural. Search the KB for the relevant metric or rule, read its description and calculation, and present what the KB says - do not interpret or extend it from general knowledge. The KB is the source of truth for this org's definitions.
+Graph edges show group placement, model ownership, entity joins, metric composition, governance, and dashboard usage. Use exploration for semantic reach and usage for reverse dashboard impact.

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,65 @@
+# 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 unavailable until Project #289. Use a supported decomposition or clearly labeled free SQL; do not create an unusable governed definition.
+
+## 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.