@graphit/cli 0.2.259 → 0.2.270

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

@@ -12,7 +12,7 @@ Work narrow, not broad: **domain -> data source -> assets.** The first move is a
 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.)
 
-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. If the user declines ("just build it", "skip KB"), respect it and work from the table schema - read it with `graphit kb explore table <NAME>`, which returns the columns (names, types, descriptions).
+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>`.
 
 ## Metric vs Dimension
 

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

@@ -0,0 +1,23 @@
+# KB Scope: Who Will See It
+
+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.
+
+| 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 |
+
+**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.
+
+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.
+
+**It is not freely reversible**, which is why the question comes first:
+
+- 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.
+
+**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.
+
+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.

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

@@ -14,7 +14,7 @@ The KB is a labeled property graph: assets carry tags that place them in a tree,
 | 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) |
+| 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 |
 
@@ -42,6 +42,8 @@ Other placements layered on top:
 
 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.
 
+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.
+
 ## Tree Rendering Order
 
 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.

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

@@ -37,11 +37,8 @@ Which `graphit kb` read command answers each question, and how to present the re
 ### "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's left uncategorized?"
-`graphit kb explore domain Uncategorized` - returns the tables with no home domain and their assets.
-
 ### "What domains do we have?" (enumerate names)
-`graphit kb list domains` - returns every domain with its description and asset count, plus an "Uncategorized" entry when tables have no domain. 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.
+`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
 

package/skills/graphit/references/onboarding.md

@@ -23,7 +23,7 @@ Two ways in. Lead with the warehouse; offer the file as the lighter path.
 - Snowflake keypair from the CLI: `graphit connector add snowflake-keypair` needs `--account --user --key --warehouse --role --database` (all required), plus optional `--name` for a friendly label (it defaults to `Snowflake (<account>)`). It validates the connection before saving, so a success really did connect.
 - OAuth and GitHub connections are set up in the Graphit web app, not the CLI - name that handoff when it applies.
 
-**File (lighter).** For a quick start with no warehouse, `graphit ds create --file ./data.csv` uploads a CSV or Excel file and creates a data source directly - no connector needed.
+**File (lighter).** For a quick start with no warehouse, `graphit ds create --file ./data.csv --domain <NAME>` uploads a CSV or Excel file and creates a data source directly - no connector needed.
 
 Present the outcome: which connection is live, or the exact web-app / admin step the user has to finish.
 
@@ -33,10 +33,19 @@ Before creating anything, ask what business question the user wants to answer. T
 
 ## 3. Create the data source
 
-Explain that answering the question fast needs a cached data source over the connection, not repeated live-warehouse queries. Create it, then activate it:
+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:
+
+```bash
+graphit kb list domains
+graphit kb create domain --name MARKETING --description "Acquisition and spend"
+```
+
+Then create the source and activate it:
 
 ```bash
-graphit ds create --name "MY_DS" --sql "SELECT ..." --connection <id>
+graphit ds create --name "MY_DS" --domain MARKETING --sql "SELECT ..." --connection <id>
 graphit ds verify <id> --accept-schema
 ```