@graphit/cli 0.2.322 → 0.2.323

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

@@ -1,97 +1,44 @@
-# KB Actions (Execute)
+# KB Actions
 
-The execute side of KB work: run approved create / update / delete through the `graphit kb` commands. The plan side - what a domain or topic is, why an asset sits where it does - lives in `kb-structure.md`.
+Load when an approved gap must be authored or an existing semantic asset changed.
 
-Create only after the user approves the gap plan below. Names are stored UPPER_SNAKE_CASE. Run `graphit kb create <type> --help` for the exact flag spelling - this file teaches the recipes and policy, the CLI owns the syntax.
+## Approval gate
 
-## Gap Plan (present before creating anything)
+Before writing, present the missing concept, proposed root, exact definition, group/access scope, and verification state. Do not write until the user approves.
 
-When the KB-readiness gate finds the dashboard needs assets that do not exist, present a compact plan and get one approval before any write. Show, per missing asset: name, type, formula or expression, the table and topics it lands on, and any rule that applies. Then ask once.
+## Authoring contract
 
-~~~
-**KB gap - 3 assets missing for this Marketing dashboard:**
+- Create semantic models, metrics, groups, and retained rules from JSON.
+- Use exactly one of `--file` or `--json`.
+- Names are lowercase snake case; reserve `__` for qualified dimensions.
+- Entities, dimensions, and measures mutate only through semantic-model update.
+- A supplied nested list replaces the stored list whole. Read first and include every sibling that must remain.
+- Explicit `meta` replaces author metadata whole. Preserve family, axes, topics, and other author fields.
+- Use dedicated verify/unverify actions. Never patch metadata merely to change verification.
 
-| Asset | Type | Definition | Table | Topics |
-|---|---|---|---|---|
-| **ROAS_D7** | metric | `SUM(revenue_d7) / NULLIF(SUM(cost), 0)` | MARKETING_UA | ATTRIBUTION |
-| **CPI** | metric | `SUM(cost) / NULLIF(SUM(installs), 0)` | MARKETING_UA | ACQUISITION |
-| **MEDIA_SOURCE** | dimension | `media_source` | MARKETING_UA | ACQUISITION |
+Read `semantic-authoring.md` for model/metric shapes and `metric-families.md` for concrete variants.
 
-Rule to apply: **EXCLUDE_ORGANIC** already exists and will filter these.
-Create these so the dashboard runs on governed references? (Approve / adjust.)
-~~~
+## Rules
 
-Present the plan, then stop. Do not create until the user approves.
+Rules remain Graphit objects. Create them from JSON with body/constraints plus `apply_on` targets. Final targets are model, entity, dimension, metric, or group identities. A rule without targets is refused.
 
-## Create
+Constraints keep their five semantics: required predicate, forbidden column, required filter, required aggregation, and value restriction. Use declared semantic identities and typed values.
 
-| Asset | Command shape |
-|---|---|
-| Metric | `graphit kb create metric --name X --sql "<expr>" --table T` (optional `--topics "A,B"`, `--default-dimensions "D1,D2"`, `--parameters`/`--parameters-file` for templates, `--skip-validate`) |
-| Dimension | `graphit kb create dimension --name X --expr "<expr>" --table T` (type auto-inferred; override with `--type` / `--output-type`; `--skip-validate`) |
-| Rule | `graphit kb create rule --name X --sql "<text>" --table T` (optional `--constraint`, `--apply-on`, `--topics`, `--skip-validate`) |
-| Synonym | `graphit kb create synonym --term X --canonical Y --type metric` |
-| Domain | `graphit kb create domain --name X` (optional `--color "#4DB6AC"`) |
-| Topic | `graphit kb create topic --name X` |
-| Relationship | `graphit kb create relationship --name X --primary-table T --primary-column C --related-table T2 --related-column C2` |
+## Update
 
-## Enforceable Rule Flags
+1. Read the target through the current principal.
+2. Preserve complete nested and metadata structures.
+3. Apply the smallest patch.
+4. Re-read immediately.
+5. Verify/unverify separately when intended.
+6. Inspect receipts; a degraded write may have landed and must not be retried blindly.
 
-A plain rule is documentation. To make it enforced server-side at query time, pass typed constraints on `graphit kb create rule` / `graphit kb update rule`:
+## Delete
 
-- `--constraint <spec...>` - one or more typed constraints, each written `type:value`. Types: `required_where:"<predicate>"`, `forbidden_column:<col>`, `required_filter:<col>`, `required_aggregation:<col>`, `value_restriction:<col>:<in|not_in>:<v1,v2>`. On update the supplied list REPLACES the rule's existing constraints.
+Confirm with the user and inspect usage first. The server checks known definition dependencies, not every canvas reference. A green guard is not exhaustive impact proof.
 
-What each constraint type does at query time, plus the override flow, lives in `governance.md`. Example: a rule that always scopes verified purchases -
+## Permissions
 
-```bash
-graphit kb create rule --name FILTER_VERIFIED_PURCHASES --sql "Only count verified purchases" --table ORDERS --constraint required_where:"is_verified = true"
-```
+Read access is the ceiling for writes. `kb_write` comes from the effective policy key. Group lifecycle is admin-only. Hidden and missing targets return the same absence.
 
-## Rule Targeting - what a rule governs
-
-Every rule must apply to at least one asset; a targetless rule is rejected. `--table` is required, and without `--apply-on` the rule governs that **whole table** - which cascades to every metric and dimension on it (it fires on any query touching the table). To narrow instead, pass `--apply-on metric:NAME` / `--apply-on dimension:NAME` so the rule applies only when that asset is used. The two are mutually exclusive: never mix a table target with metric/dimension targets on one rule. To govern several tables, list each: `--apply-on table:A table:B`.
-
-```bash
-# Whole table - cascades to every metric/dimension on ORDERS
-graphit kb create rule --name ORDERS_ACTIVE_ONLY --sql "Exclude cancelled orders" --table ORDERS
-# Narrowed - applies only when the ARPU metric is used
-graphit kb create rule --name ARPU_TRIM --sql "Cap ARPU outliers" --table USERS --apply-on metric:ARPU
-```
-
-## Pre-Creation Validation
-
-Metric, dimension, and rule creates validate the formula against real data before writing; the response carries a `validation` object (status `pass` / `skipped` / `fail`). Surface it to the user - per-type result templates are in `kb-traversal.md`. A `fail` returns HTTP 422 and the asset is NOT created: show the error and failing SQL, fix the formula, retry. Validation is skipped (asset still created) for `${PARAM:X}` templates, constraint-based rules, and tables with no ready data source. Pass `--skip-validate` to bypass it on bulk creates.
-
-## Update and Delete
-
-- Update a field: `graphit kb update <type> NAME --<field> value` (e.g. `--sql`, `--expr`, `--description`, `--table`).
-- Delete: `graphit kb delete <type> NAME --yes`. Deleting a parameterized parent cascades to all its children - confirm the blast radius first (see `parameterized-metrics.md`).
-
-## Lists REPLACE - read before you write
-
-`--topics`, `--secondary-tables`, `--default-dimensions`, and `--constraint` REPLACE the existing list, they do not append. To change one value, read the current list first (`graphit kb get metric NAME`), then write the full intended list: add a topic with `--topics "EXISTING1,EXISTING2,NEW"`; remove one by writing the list minus that value.
-
-Reference a **metric or dimension** onto another table with `graphit kb update metric NAME --secondary-tables "OTHER_TABLE"` (also dimension). This is a read-only pointer marked `*` in the tree; every referenced column must exist on the target. For **rules**, govern several tables by listing them in `--apply-on` (`--apply-on table:A table:B`), not `--secondary-tables`. Topics are horizontal - one topic can tag assets across many domains (see `kb-structure.md`).
-
-## Domain home (set on the table, cascades)
-
-Domain is set on the TABLE, never per asset, and cascades to every asset on it (model in `kb-structure.md`). To re-home a whole table at once: `graphit kb update table NAME --domain MARKETING`. Change it once on the table, never asset by asset.
-
-## Who can write what
-
-Reads are open to every member; writes are scoped by the caller's data access profile. Check `graphit status` before presenting a gap plan, so the plan is one they can execute.
-
-| Write | Needs |
-|---|---|
-| Metric, dimension, rule, synonym, relationship, table | `kb_write` in the asset's domain |
-| Moving an asset or table to another domain | `kb_write` in BOTH domains - the one it leaves and the one it enters |
-| Domain and topic create / update / delete | Org admin; a profile never grants it |
-| Template create / update / delete | Org admin, OR `kb_write` in any one domain - never a per-template or per-domain grant |
-
-Every member can read and use templates. Status is advisory; a denial with `retryable: false` is a stop, not a retry (`operations.md`).
-
-To find what exists and how it connects, use the read recipes in `kb-traversal.md`.
-
-## UI-Only (no CLI command)
-
-Platform-UI state, not KB data the CLI changes: view mode (Tree / By Topic / By Table / Flat), filter dropdowns, expand / collapse, drag-drop onto a topic, and a synonym's cross-cutting domains (extra relevance beyond its home domain has no CLI flag yet).
+Group `access` is stored dbt metadata; it does not grant Graphit visibility.

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: