@graphit/cli 0.2.322 → 0.2.330

package/skills/graphit/references/governance.md

@@ -1,100 +1,37 @@
 # Query Governance
 
-Load this when writing or validating a governed query, working trust tiers, declaring a conditionally-enforced rule, or working the ad-hoc frontier.
+Load when writing a governed query, explaining a refusal, or reporting provenance.
 
-Governance is enforced server-side in the QueryGateway, the same across every channel. You CANNOT weaken it from the CLI: an ad-hoc business measure requires EXPLORE access across every queried scope, and rule overrides must also satisfy EXPLORE.
+## References
 
-## Reference syntax
+| Reference | Meaning |
+|---|---|
+| `{{ Metric('revenue') }}` | Reusable metric |
+| `{{ Dimension('order__channel') }}` | Qualified grouping/filter field |
+| `{{ Measure('order_total') }}` | Graphit's model-owned measure extension |
 
-Write governed queries with KB references, not inline formulas. The server compiles each to its KB expression, injects rule constraints, stamps the trust tier, and caches the result. The syntax is identical in `graphit query` and `graphit.resolve()`.
+Legacy token grammar is refused. Keep references inside complete executable SQL and canvas `data-graphit-sql`.
 
-| Syntax | Expands to | Example |
-|--------|-----------|---------|
-| `{{metric:NAME}}` | Metric calculation (aggregation) | `{{metric:CPI}}` |
-| `{{metric:NAME(K=V)}}` | Parameterized metric | `{{metric:ARPU(DAY=7)}}` |
-| `{{metric_raw:NAME}}` | Raw expression, no outer aggregate | `{{metric_raw:REVENUE}}` |
-| `{{dim:NAME}}` | Dimension expression | `{{dim:INSTALL_MONTH}}` |
-
-```bash
-graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} AS cpi FROM MARKETING_UA_DS GROUP BY 1" --ds MARKETING_UA_DS --verbose
-```
-
-`--verbose` prints the expanded SQL and trust tier, so you can confirm the reference resolved before presenting the result.
-
-## Parameterized metrics
-
-Some metrics (for example ARPU, ROAS, RETENTION) carry required parameters and cannot resolve without a value. Run `graphit kb list metric` and read the `params` column for the names a metric requires, then supply them inline as `{{metric:ARPU(DAY=7)}}`. Pre-baked variants such as `ARPU_D7` or `ROAS_D30` have the value fixed and need none. Omitting a required parameter returns a clear error naming the exact syntax, so read `params` first.
+The governed fragment path serves simple, ratio, and derived metrics. Cumulative, conversion, shifted, time-spine, and null-fill shapes are not yet supported. Use a supported decomposition or explicitly labeled free SQL.
 
 ## Trust tiers
 
-Every result is stamped with a tier, shown to the user as a badge on graphs and canvas entities - your honest signal of how trustworthy the number is.
-
-| Tier | Meaning | Badge |
-|------|---------|-------|
-| `governed` | Query used `{{metric:X}}` / `{{dim:X}}` references | Teal dot |
-| `verified` | Raw SQL whose expressions match KB definitions | Amber dot |
-| `ad_hoc` | Inline formulas with no KB match | Gray dot |
-
-Prefer the governed tier. The server may upgrade matching raw SQL to verified, but reach for references first so the result is governed by intent.
-
-## The ad-hoc gate
-
-This is the hard frontier - the rules below are what the QueryGateway does.
-
-A query lands at the `ad_hoc` tier when it uses no `{{metric:NAME}}` / `{{dim:NAME}}` reference and its raw expressions match no KB definition. On the CLI (`graphit query`, cached `--ds` or `--warehouse`), **every** ad-hoc query must be justified - business measures (an aggregate or `GROUP BY`) and plain exploration alike (`SELECT *`, `COUNT(*)`, `DISTINCT` peeks). Governed and verified results are exempt.
-
-- **EXPLORE access is a hard prerequisite for ad-hoc business measures.** If the user lacks EXPLORE access to any queried table scope, the server blocks that measure. An ad-hoc reason cannot bypass that denial.
-- **Justification floor.** The ad-hoc query is withheld and asks for a justification. Preferred path first: rewrite with `{{metric:NAME}}` / `{{dim:NAME}}` references - genuinely search the KB (`graphit kb explore`, `graphit kb list metric`, `graphit kb list dimension`), and if the metric or dimension you need does not exist, CREATE it first. A filter's value list belongs in a `{{dim:NAME}}`, not a raw `SELECT DISTINCT` peek. Only if nothing fits and the user needs the raw run, pass `--adhoc-reason "<text>"` stating what you searched, what you found, and why it does not fit - pass it on the first call when you already know the query is ad-hoc. A trivial or empty reason is rejected server-side and recorded in the audit log, so it must be honest.
-
-When the gate fires, do not narrate around it or pretend the query ran. Report truthfully: it was blocked or needs approval, name the governed rewrite, and let the user decide.
-
-## Enforceable rules and overrides
-
-Rules with typed constraints are enforced automatically, rewriting the SQL before it runs:
-
-| Type | What it does |
-|------|-------------|
-| `required_where` | Injects a WHERE predicate |
-| `forbidden_column` | NULLifies a column in SELECT |
-| `value_restriction` | Restricts a column to allowed values |
-| `required_filter` | Validates a column appears in WHERE |
-| `required_aggregation` | Validates GROUP BY includes a column |
-
-User-context variables (`${user.team_id}`, `${user.email}`) resolve server-side for row-level security. Override a rule only when the user explicitly asks; the server honors it only if the user holds EXPLORE on every queried scope. A rule that masks a column (a `forbidden_column` constraint) can never be overridden. Every override is logged. Pass several names to override more than one.
-
-```bash
-graphit query "SELECT * FROM EVENTS" --ds EVENTS --override-rules EXCLUDE_RETARGETING
-```
-
-## Conditionally-enforced rules
-
-A rule's mode is Advisory (guidance), Always (every query), or **Conditional** - fires only when its plain-language body (the condition) holds for the query you wrote. No server classifier decides that; you do. Read a table's rules first (`graphit kb explore table <name>`), judge your query against each conditional rule's body, and declare it up front:
-
-- `--apply-conditional RULE` - enforce it for this query.
-- `--skip-conditional RULE:"reason"` - skip it; a reason is required and audit-logged.
-
-Declare up front so a clean query never stalls. An undeclared conditional returns a retryable prompt naming each unresolved rule and its condition - read it, decide, re-run. A saved tile stores your decision and replays it every refresh.
-
-## Data-source row caps
-
-An admin can set a `max_rows` cap per data source. A cap limits the result set; it does not change authorization, trust-tier classification, or the ad-hoc justification floor.
+- **governed:** verified semantic references compiled through the gateway.
+- **verified:** known safe stored query without semantic references.
+- **ad hoc:** raw SQL at the frontier.
 
-## Presenting governance results
+Prefer governed. Never present ad-hoc SQL as the team's definition.
 
-The user CANNOT see raw CLI output. Render every result as markdown.
+## Rules
 
-**After a governed query**, append a provenance footer so the trust signal travels with the number: tier, KB references used, row cap if applied. Because a governed query may be rewritten before it runs, read `provenance.injection_summary` and report which rules changed it and how (each rule, its outcome, and why), not just a count. An ungoverned query reports no rules applied. For an ad-hoc result, state the tier honestly and offer the governed `{{metric:NAME}}` / `{{dim:NAME}}` rewrite.
+Rules target model, entity, dimension, metric, or group identities. Verified constraints enforce; verified body-only rules guide; drafts do nothing. Modes and EXPLORE behavior remain server-owned.
 
-~~~
-**Trust tier:** governed - 2 KB refs, 1 rule enforced (**EXCLUDE_INTERNAL**), max rows 10000
-~~~
+The gateway runs before caches, injects constraints, verifies resolved SQL, and returns a transparency receipt. Do not claim a rule applied merely because it exists.
 
-**After `graphit governance status`**, show the 7-day conformance counts (governed / verified / ad-hoc / total) as a small markdown table.
+## Ad-hoc gate
 
-**When a gate or rule blocks a query**, explain it and the path forward, no raw dump:
+Search the KB genuinely, explain why visible definitions do not fit, and prefer an approved reusable supported definition. Use a truthful ad-hoc reason only for a real one-off. Never use it to bypass a rule.
 
-~~~
-**Blocked by governance.**
+## Reporting
 
-Rule **EXCLUDE_ORGANIC** is enforced; overriding it requires EXPLORE access on every queried scope. Rewrite the query to include the required filter, or ask an admin for EXPLORE access.
-~~~
+Report tier, semantic references, row cap, visible rules that changed the query, and any refusal or override. Read the receipt rather than inferring. A blocked or partial result is not success.

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.