@graphit/cli 0.2.260 → 0.2.306

package/skills/graphit/references/data-sources.md

@@ -41,17 +41,19 @@ A wide or raw source is sometimes the right call - row-level drill-down/export,
 
 ## Creating data sources
 
-`graphit ds create` auto-chains: create -> poll until ready -> scan schema -> print verification link. To activate for KB use, either the user reviews and activates via the link on the platform, or - after you show them the scanned schema and they accept it - run `graphit ds verify <id> --accept-schema` to activate from the CLI.
+`graphit ds create` auto-chains: create -> poll until ready -> scan schema -> print verification link. Activating it for KB use is the `ds verify` step below.
 
 ```bash
 # Create with auto-scan (recommended)
-graphit ds create --name "MY_DS" --sql "SELECT ..." --connection <id>
+graphit ds create --name "MY_DS" --domain <DOMAIN> --sql "SELECT ..." --connection <id>
 
 # Create without auto-scan (for special cases)
-graphit ds create --name "MY_DS" --sql "SELECT ..." --skip-scan
+graphit ds create --name "MY_DS" --domain <DOMAIN> --sql "SELECT ..." --skip-scan
 ```
 
-**From a local file (Excel/CSV):** `graphit ds create --file <path>` uploads the file and creates one data source. Optional: `--name` (defaults to the file name), `--sheet <name>` (multi-sheet workbooks), `--domain <NAME>` (attach to an existing KB domain - create it first if needed). `--file` and `--sql` are mutually exclusive; same auto-scan + verification flow as above.
+**`--domain` is REQUIRED, in both modes.** It files the scanned table under an existing KB domain and decides who can see the source; there is no uncategorized fallback. `graphit kb list domains`, confirm the choice with the user, and `graphit kb create domain --name <NAME>` if none fits.
+
+**From a local file (Excel/CSV):** `graphit ds create --file <path> --domain <NAME>` uploads the file and creates one data source. Optional: `--name` (defaults to the file name), `--sheet <name>` (multi-sheet workbooks). `--file` and `--sql` are mutually exclusive; same flow as above.
 
 **Warehouse connection.** `--connection` names the warehouse a `--sql` source reads from. Add BigQuery with `graphit connector add bigquery-serviceaccount --key-file <path> [--project --dataset --location]` (org admin; project defaults from the key). The pipeline routes by connection type - the same `ds create` works for either warehouse.
 
@@ -59,7 +61,7 @@ For existing unverified sources, `graphit ds verify <id>` scans and shows the sc
 
 ## Refreshing data sources
 
-Data sources cache a snapshot of the warehouse query result. Refresh when you need current data. **File-upload sources can't be refreshed (no query to re-run) - update them by re-uploading with `graphit ds create --file <path>`.**
+Data sources cache a snapshot of the warehouse query result. Refresh when you need current data. **File-upload sources can't be refreshed - update them by re-uploading with `graphit ds create --file <path> --domain <NAME>`.**
 
 On BigQuery a refresh scans billed bytes, so keep the shape tight and prefer incremental/partition-pruned refresh over full re-scans; a per-connection scan cap (max bytes billed) fails an oversized query fast rather than running up a bill.
 
@@ -106,7 +108,7 @@ Only early-filter when an incremental source is slow for this reason; the defaul
 
 ## What needs write access
 
-Querying a source, listing sources, reading schema or refresh history, and an ordinary `graphit ds refresh` are reads - any member who can read that source's domain can run them, and a source in a domain they cannot read returns the same uniform 404 as one that does not exist. These need `data_source_write` in the source's domain: `ds create`, editing its SQL, `ds refresh-config`, a `--force` refresh or accepting a schema, `ds verify`, scanning, per-source governance settings, and deletion. Moving a source to another domain needs write in both the old and the new domain, and `ds create` must name a domain the caller can write to.
+Querying a source, listing sources, reading schema or refresh history, and an ordinary `graphit ds refresh` are reads - any member who can read that source's domain can run them, and a source in a domain they cannot read returns the same uniform 404 as one that does not exist. These need `data_source_write` in the source's domain: `ds create`, editing its SQL, `ds refresh-config`, a `--force` refresh or accepting a schema, `ds verify`, scanning, per-source governance settings, and deletion. Moving a source to another domain needs write in both the old and the new domain.
 
 Check `graphit status` for those domains before proposing a create or a config change. It is advisory - the server authorizes each operation when it runs, and a denial with `retryable: false` is a stop, not a retry (`operations.md`).
 

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
 ```