@graphit/cli 0.2.348 → 0.2.351

package/scripts/generate-commands-doc.mjs

@@ -9,7 +9,7 @@
 //
 // Requires a prior `npm run build` (it imports the compiled registrars from dist/).
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import {
   buildProgram,
@@ -28,6 +28,23 @@ const skillPath = join(cliRoot, "skills", "graphit", "SKILL.md");
 const START = "<!-- COMMANDS:START -->";
 const END = "<!-- COMMANDS:END -->";
 
+/**
+ * Feature #814, mirroring `writeStderr` in cli/src/stderr.ts.
+ *
+ * `console.error` is asynchronous when stderr is a pipe - which is how CI and
+ * every agent runs this generator - so a `process.exit()` in the same tick
+ * discards the buffered line. The remediation banner below is the whole value of
+ * a failing check run, so it is written synchronously; the guard in
+ * cli/test/lint-write-before-exit.test.mjs covers cli/src, not cli/scripts.
+ */
+function writeStderr(message) {
+  try {
+    writeSync(2, message.endsWith("\n") ? message : `${message}\n`);
+  } catch {
+    // stderr closed or busy - a lost log line is never worth failing a build.
+  }
+}
+
 function esc(text) {
   return String(text ?? "").replace(/\r?\n/g, " ").replace(/\|/g, "\\|").trim();
 }
@@ -51,14 +68,23 @@ function renderBlock(program) {
       flags: formatFlags(verb.options),
     });
   }
+  // The prose above the markers in SKILL.md already says the table is generated
+  // and to check `--help` for flags; this line only marks the block as generated.
   const lines = [
     "",
-    "_Generated from the CLI by `npm run gen:commands` - do not hand-edit between the markers. Run `graphit <cmd> --help` for exact flag values and descriptions._",
+    "_Generated by `npm run gen:commands`; do not hand-edit between the markers._",
     "",
   ];
   for (const name of groups.keys()) {
     const { description, rows } = groups.get(name);
-    lines.push(`**${name}**${description ? ` - ${esc(description)}` : ""}`);
+    // A self-invocable group (`status`, `query`, `setup`) is its own single row,
+    // and Commander gives the group and the row the same description. Print it
+    // once, on the row - the row is what the tests pin and what an agent reads.
+    // SKILL.md is always-loaded and sits on a hard size ceiling, so a repeated
+    // description is paid for on every turn.
+    const groupDescription =
+      rows.length === 1 && rows[0].description === description ? "" : description;
+    lines.push(`**${name}**${groupDescription ? ` - ${esc(groupDescription)}` : ""}`);
     for (const row of rows) {
       const parts = [`- \`${row.command}\``];
       if (row.description) parts.push(esc(row.description));
@@ -90,27 +116,23 @@ const program = await buildProgram();
 const block = renderBlock(program);
 
 if (toStdout) {
+  // No process.exit() after this write: on a pipe, exiting before stdout drains
+  // truncates the block, and callers diff it whole.
   process.stdout.write(block);
-  process.exit(0);
-}
-
-// Normalize CRLF before compare so Windows checkouts don't report perpetual drift.
-const current = existsSync(skillPath)
-  ? readFileSync(skillPath, "utf-8").replace(/\r\n/g, "\n")
-  : "";
-const next = injectBetweenMarkers(current, block);
+} else {
+  // Normalize CRLF before compare so Windows checkouts don't report perpetual drift.
+  const current = existsSync(skillPath)
+    ? readFileSync(skillPath, "utf-8").replace(/\r\n/g, "\n")
+    : "";
+  const next = injectBetweenMarkers(current, block);
 
-if (current === next) {
-  console.error("Command table in SKILL.md is in sync.");
-  process.exit(0);
-}
-
-if (checkOnly) {
-  console.error(
-    "SKILL.md command table is stale - run: npm run gen:commands",
-  );
-  process.exit(1);
+  if (current === next) {
+    writeStderr("Command table in SKILL.md is in sync.");
+  } else if (checkOnly) {
+    writeStderr("SKILL.md command table is stale - run: npm run gen:commands");
+    process.exitCode = 1;
+  } else {
+    writeFileSync(skillPath, next, "utf-8");
+    writeStderr(`Updated command table in ${skillPath}`);
+  }
 }
-
-writeFileSync(skillPath, next, "utf-8");
-console.error(`Updated command table in ${skillPath}`);

package/scripts/generate-tool-manifest.mjs

@@ -18,7 +18,7 @@
 //   - it never emits an org/user identity parameter. Tenancy is bound from the
 //     authenticated session at construction, never from a model-supplied value.
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { buildProgram, cliRoot, collectVerbs } from "./commander-walk.mjs";
 
@@ -81,11 +81,29 @@ const APP_PARAM_TYPES = new Set(["string", "integer", "boolean"]);
 const errors = [];
 const fail = (msg) => errors.push(msg);
 
+/**
+ * Feature #814, mirroring `writeStderr` in cli/src/stderr.ts.
+ *
+ * `console.error` is asynchronous when stderr is a pipe - which is how CI and
+ * every agent runs this generator - so a `process.exit()` in the same tick
+ * discards the buffered lines. The gate failures below are the whole value of a
+ * failing run, so they are written synchronously; the guard in
+ * cli/test/lint-write-before-exit.test.mjs covers cli/src, not cli/scripts.
+ */
+function writeStderr(message) {
+  try {
+    writeSync(2, message.endsWith("\n") ? message : `${message}\n`);
+  } catch {
+    // stderr closed or busy - a lost log line is never worth failing a build.
+  }
+}
+
 /** Nothing is written while a single gate is unsatisfied. */
 function exitOnErrors() {
   if (!errors.length) return;
-  console.error("Tool manifest generation failed:");
-  for (const e of errors) console.error(`  - ${e}`);
+  writeStderr(
+    ["Tool manifest generation failed:", ...errors.map((e) => `  - ${e}`)].join("\n"),
+  );
   process.exit(1);
 }
 
@@ -599,10 +617,10 @@ if (toStdout) {
   if (current.manifest === nextManifest && current.policy === nextPolicy) {
     console.error("Tool manifest and verb policy are in sync.");
   } else if (checkOnly) {
-    console.error(
+    writeStderr(
       "Generated tool manifest / verb policy is stale - run: npm --prefix cli run gen:commands",
     );
-    process.exit(1);
+    process.exitCode = 1;
   } else {
     writeFileSync(manifestPath, nextManifest, "utf-8");
     writeFileSync(policyOutPath, nextPolicy, "utf-8");

package/scripts/verb-policy-source.json

@@ -67,6 +67,14 @@
       "requires_approval": false,
       "silent_retry_exempt": false
     },
+    "kb source": {
+      "surface": "both",
+      "noun": "kb_read",
+      "is_read_only": true,
+      "mutation_class": "none",
+      "requires_approval": false,
+      "silent_retry_exempt": false
+    },
     "kb get": {
       "surface": "both",
       "noun": "kb_read",
@@ -137,7 +145,7 @@
       "mutation_class": "none",
       "requires_approval": false,
       "silent_retry_exempt": true,
-      "reason": "A CI/shell verb: --path walks a local checkout the app has no filesystem for, and --sha is the pipeline's job on a pull request. An in-app turn reads the synced KB through the kb_read noun; it has no commit to verify."
+      "reason": "A CI/shell verb: --path walks a local checkout the app has no filesystem for, --sha is the pipeline's job on a pull request, and with neither flag it plans the head of the bound branch - the admin's pre-merge check from a shell. An in-app turn reads the synced KB through the kb_read noun; it has no commit to verify, and the app's own read-only scan of the branch head is the Settings panel's, not an agent's."
     },
     "kb repo apply": {
       "surface": "cli_only",
@@ -147,6 +155,22 @@
       "silent_retry_exempt": true,
       "reason": "The merge job's verb: it applies a provider-verified commit to the shared KB under the repository binding's apply lease. Shared-KB authorship in a repository-owned org happens through a pull request, never an in-app turn, so the app must not advertise it."
     },
+    "kb repo status": {
+      "surface": "cli_only",
+      "is_read_only": true,
+      "mutation_class": "none",
+      "requires_approval": false,
+      "silent_retry_exempt": true,
+      "reason": "Reads the durable operation created by the CLI-only verify/apply workflow. The caller supplies its operation id from a shell or CI job; in-app turns do not create those operations."
+    },
+    "kb repo cancel": {
+      "surface": "cli_only",
+      "is_read_only": false,
+      "mutation_class": "kb",
+      "requires_approval": true,
+      "silent_retry_exempt": true,
+      "reason": "An org admin explicitly stops a saved repository apply task from a shell. This changes the CLI-only apply workflow and is not an in-app shared-KB authoring action."
+    },
     "kb repo show": {
       "surface": "cli_only",
       "is_read_only": true,
@@ -177,7 +201,7 @@
       "mutation_class": "kb_config",
       "requires_approval": true,
       "silent_retry_exempt": true,
-      "reason": "Binds a provider connection and repository to the org (org admin). The connection ids and repository slug come from the admin's own tooling; an in-app turn has neither."
+      "reason": "Binds a provider connection and repository to the org (org admin): the one-time configuration step that decides who owns the shared KB. The admin does it deliberately from a shell alongside the repository checkout they are about to hand the org, and the app's surface for it is the Settings panel's binding form, never an agent turn. Reviewed 2026-09-06 (Issue #921): the earlier reason claimed the connection ids came from the admin's own tooling. They did not - no verb produced one on any surface, which is the gap `connector list` now closes."
     },
     "kb repo identities": {
       "surface": "cli_only",
@@ -572,7 +596,7 @@
       "mutation_class": "none",
       "requires_approval": false,
       "silent_retry_exempt": false,
-      "reason": "Connection lifecycle remains CLI-only, but connection enumeration already exists in-app through the gated `list_warehouse_metadata` overlay tool. A ninth generated noun would duplicate that read surface and spend tool-window budget, so the Commander verb stays excluded while the platform replacement remains available."
+      "reason": "Connection lifecycle remains CLI-only, and warehouse enumeration already exists in-app through the gated `list_warehouse_metadata` overlay tool. A ninth generated noun would duplicate that read surface and spend tool-window budget, so the Commander verb stays excluded while the platform replacement remains available. Reviewed 2026-09-06 (Issue #921): the verb now also lists Slack and repository connections, which the overlay does not - that is deliberate. Those ids are consumed only by verbs that are themselves cli_only (`kb repo bind`, the Slack setup done in the web app), so an in-app turn has nothing to spend them on."
     },
     "connector add snowflake-keypair": {
       "surface": "cli_only",

package/skills/graphit/SKILL.md

@@ -2,10 +2,10 @@
 name: graphit
 description: >-
   Use Graphit for ANY question about the user's business or product data: metrics, KPIs, revenue, retention, spend, users, cohorts, funnels, trends, comparisons, "why did X change", "how are we doing on Y", analysis, reports, or dashboards. Activate even when the user does not say "Graphit" or name any tool: if someone wants to understand their numbers, this is the tool. Graphit answers through a governed semantic layer (computed the team's way, reusable and safe to share) and delivers the answer as a fast cached-data query or a hand-authored interactive HTML dashboard, and can create the metrics, dimensions, and rules an answer needs. Prefer Graphit over hand-rolled one-off analysis whenever the data is, or could be, the user's business data. Skip only for pure software tasks (code, logs, config, infra) or data with nothing to do with the user's business.
-skill_version: "0.2.348"
+skill_version: "0.2.351"
 ---
 
-<!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 32,000. Always-loaded: the collaboration/pace spine, hard constraints + scope gate, the loop, and the generated command table (COMMANDS markers, scripts/generate-commands-doc.mjs) - needed every turn, cannot defer to a reference. Marker sits after the frontmatter so the loader and sync-plugin-version.mjs parse it. Reviewed 2026-08-02. Raised from 29,952 on 2026-08-07 (founder-directed): a domain is now an access boundary, so loop step 2 must say that picking one decides who ever sees the work - load-bearing before any reference load can be relied on. Raised from 30,592 on 2026-08-13 (founder-directed): the living-context MUST bullet - explore placements answer path + pre-create fork. SIZING.md rules raises pay only for command-table growth; both raises are deliberate exceptions. Raised from 31,232 on 2026-08-16: the generated table gained `dashboard check` and its flags - table growth, the sanctioned kind - plus that verb's one router row. -->
+<!-- SIZE EXEMPTION (SKILL.md): hard limit 12,288 chars, exempted ceiling 32,000. Reviewed 2026-09-06. Always-loaded: the collaboration/pace spine, hard constraints + scope gate, the loop, and the generated command table (COMMANDS markers; cli/scripts/generate-commands-doc.mjs) - needed every turn, not deferrable. Marker sits after the frontmatter so the loader and sync-plugin-version.mjs parse it. Raises pay only for command-table growth; each is recorded in docs/knowledge/prompt-engineering/sizing/SIZING.md, prose changes in docs/workflow/prompt-changes/INDEX.md. -->
 
 # Graphit CLI
 
@@ -92,7 +92,7 @@ Soft narration is what "just build it" drops. These hard stops hold even then: c
 ### Handoffs, failure, truthful reporting
 
 - Name the handoffs. Some actions live on the platform, not the CLI: visiting a data source's verification link, deleting a source from the Sources Hub. Say when a step hands control back to the user, and move between building the dashboard and building the knowledge base through the gate.
-- Keep local files ephemeral. Any file you create - scratch HTML, an export, throwaway SQL - goes in one `./.graphit/` working dir, never scattered in the repo. When the work is done, offer to remove it. Mechanics: operations.md.
+- Keep scratch files together. In repository-owned workflows, `.graphit/` holds durable KB definitions: never ignore or delete it as scratch. Read repo-preparation.md before authoring those files; other local artifacts follow operations.md.
 - On failure: retry once if it looks transient (timeout, rate limit); on a real error (missing column, permission, validation) stop, say what failed and the next step, never a bare "something went wrong".
 - Report truthfully: what worked, what did not, what you are unsure of. If only part succeeded, say which part and why the rest did not. Done means the answer is delivered and every dashboard element resolves on real data with no entity_sql_warnings.
 
@@ -142,6 +142,7 @@ Load only the relevant reference. Check `graphit <command> --help` for flags.
 
 | Situation | Read |
 |---|---|
+| preparing a repository-owned KB from repository docs | repo-preparation.md |
 | a brand-new or empty workspace, nothing connected yet | onboarding.md |
 | scoping to a domain, data source, and assets | kb-discovery.md, kb-traversal.md, data-sources.md |
 | a repository-owned (`manual`) org: verify, CI tokens, Data Sources via PR | references/repo-kb.md |
@@ -162,30 +163,32 @@ Load only the relevant reference. Check `graphit <command> --help` for flags.
 
 ## Commands
 
-Claude Code supplies the `graphit` wrapper. On Codex, Cursor, terminals and CI, use `npx -y @graphit/cli@0.2.348 <command>`; pin a version for reproducibility. The table is generated from the CLI; check command help for exact flags.
+Claude Code supplies the `graphit` wrapper. On Codex, Cursor, terminals and CI, use `npx -y @graphit/cli@0.2.351 <command>`; pin a version for reproducibility. The table is generated from the CLI; check command help for exact flags.
 
 <!-- COMMANDS:START -->
 
-_Generated from the CLI by `npm run gen:commands` - do not hand-edit between the markers. Run `graphit <cmd> --help` for exact flag values and descriptions._
+_Generated by `npm run gen:commands`; do not hand-edit between the markers._
 
 **auth** - Authentication commands
 - `auth login` - Log in to Graphit via browser
 - `auth status` - Show current authentication status
 - `auth logout` - Log out and clear stored credentials
 
-**status** - Show your effective permissions per domain (advisory; the server re-authorizes every operation)
+**status**
 - `status` - Show your effective permissions per domain (advisory; the server re-authorizes every operation)
 
 **kb** - dbt-native Knowledge Base - semantic models with nested components, concrete metrics/families, groups, and retained rules
-- `kb repo verify` - Compute the plan for a .graphit/ tree: identity + access, their semantic layer through provenance, validity + completeness, and the KB/DS/dashboard actions. Any refusal exits 2 (a CI check fails). --sha pulls the commit from the bound provider (CI); --path uploads a local checkout and yields a local-only plan that can never be applied - `--sha --pr --path --allow-dirty --kind --token --poll-interval-ms --timeout-ms`
+- `kb repo verify` - Plan a .graphit/ tree: identity + access, semantic layer via provenance, validity + completeness, KB/DS/dashboard actions. Any refusal exits 2 (CI fails). --sha pulls that commit from the bound provider (CI); --path uploads a checkout for a local-only plan that can never be applied; neither plans the bound branch head - `--sha --pr --path --allow-dirty --kind --token --poll-interval-ms --timeout-ms`
 - `kb repo show` - Show the repository binding: ownership mode, bound repository, branch, connection, last applied commit
 - `kb repo mode <mode>` - Set KB ownership (org admin): managed = direct writes; manual = the repository owns shared KB assets and Data Source definitions (changes via pull request). A non-empty managed KB refuses manual
-- `kb repo bind` - Bind the owning repository to a provider connection (org admin); the connection must name that repository - `--connection --repo --branch --approved-sha`
+- `kb repo bind` - Bind the owning repository (org admin); --repo resolves the provider connection naming it unless several healthy ones match - `--connection --repo --branch --approved-sha`
 - `kb repo identities` - List git identities (org admin): linked, unlinked, and accounts the last plans could not link
 - `kb repo link-identity <provider> <account> <member-email>` - Link a provider account (login or account id) to the member with that email (org admin)
 - `kb repo unlink-identity <provider> <account>` - Unlink a provider account from its member (org admin); leaves a tombstone the silent email match cannot cross
 - `kb repo export-datasources` - Write the live Data Source definitions as datasources/<name>.ds.yml + <name>.sql (org admin): the mirror an org commits before entering manual mode; byte-identical when nothing differs - `--out`
 - `kb repo apply` - Apply a plan (org admin). --plan applies a saved plan id; --sha re-verifies the commit and applies the fresh plan in one call (the merge job). Refuses a stale plan, a changed tree, a failing verdict or a local-only plan; a concurrent apply on the same repository waits - `--plan --sha --pr --kind --token --poll-interval-ms --timeout-ms`
+- `kb repo status <operation-id>` - Read a repository operation once by id; accepts the login or GRAPHIT_TOKEN
+- `kb repo cancel` - Request cancellation of a saved plan (org admin login); already applied changes remain - `--plan`
 - `kb repo token mint` - Mint a display-once CI machine token (org admin); scope kb:verify or kb:apply - `--scope`
 - `kb repo token list` - List CI machine tokens: metadata only, never the secret
 - `kb repo token revoke <token-id>` - Revoke a CI machine token (org admin)
@@ -200,8 +203,9 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 - `kb create rule` - Create a retained Graphit governance rule from JSON. Targets use model:, entity:, dimension:, metric: or group: identities - `--file --json`
 - `kb update <noun> <name>` - Update an asset with a JSON patch. On semantic-model, a provided entities/dimensions/measures list replaces the stored list whole; explicit meta replaces author metadata whole - `--file --json`
 - `kb delete <noun> <name>` - Delete an asset (requires --yes). Checks known definition dependencies; inspect usage separately for canvas impact - `--yes`
+- `kb source <noun> <name>` - Read recorded definition files at the applied repository commit, with numbered lines and drift evidence - `--document --context`
 - `kb get <noun> <name>` - Fetch one asset. Metrics include their family and sibling variants
-- `kb list <noun>` - List all visible assets of one noun
+- `kb list <noun>` - List visible full definitions; opt into paged metric summaries for discovery - `--summary --limit --cursor`
 - `kb tree` - The whole visible semantic layer: group -> semantic model -> assets, metric families collapsed to one card each
 - `kb search <query>` - Search semantic models, metrics, groups and nested components - `--limit`
 - `kb entity <name>` - One entity across every visible semantic model that declares it
@@ -211,7 +215,7 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 - `kb verify <noun> <name>` - Verify a Knowledge Base asset
 - `kb unverify <noun> <name>` - Unverify a Knowledge Base asset
 
-**query** - Run SQL against a cached data source or a live warehouse (Snowflake / BigQuery). Check truncated before concluding
+**query**
 - `query <sql>` - Run SQL against a cached data source or a live warehouse (Snowflake / BigQuery). Check truncated before concluding - `--ds --warehouse --connection --limit --override-rules --verbose --adhoc-reason --apply-conditional --skip-conditional --timeout`
 
 **metadata** - Warehouse metadata (Snowflake schemas / BigQuery datasets)
@@ -247,7 +251,7 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 - `dashboard delete <id>` - Delete a custom dashboard (requires --yes) - `--yes`
 
 **connector** - Connection management. OAuth and GitHub connections are set up in the Graphit web app.
-- `connector list` - List active connections (Snowflake, BigQuery, Slack)
+- `connector list` - List connections (Snowflake, BigQuery, Slack, GitHub/Bitbucket)
 - `connector add snowflake-keypair` - Add Snowflake via keypair auth - `--account --user --key --name --warehouse --role --database`
 - `connector add bigquery-serviceaccount` - Add BigQuery via a service-account key (org admin only) - `--key-file --project --dataset --location --name --max-bytes-billed`
 - `connector test <id>` - Test a connection
@@ -263,7 +267,7 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 **plugin** - Inspect Graphit assistant plugin status
 - `plugin status` - Check plugin/package/skill version health - `--json --quiet --skip-network --repair`
 
-**setup** - Install legacy copied Graphit assistant files for Cursor or fallback setups
+**setup**
 - `setup` - Install legacy copied Graphit assistant files for Cursor or fallback setups - `--editor --project --update --legacy-copy --remove-legacy-copies --dry-run`
 
 <!-- COMMANDS:END -->

package/skills/graphit/VERSION.json

@@ -1,5 +1,5 @@
 {
   "package": "@graphit/cli",
-  "version": "0.2.348",
+  "version": "0.2.351",
   "source": "cli/package.json"
 }

package/skills/graphit/references/governance.md

@@ -8,7 +8,7 @@ Load when writing a governed query, explaining a refusal, or reporting provenanc
 |---|---|
 | `{{ Metric('revenue') }}` | Reusable metric |
 | `{{ Dimension('order__channel') }}` | Qualified grouping/filter field |
-| `{{ Measure('order_total') }}` | Graphit's model-owned measure extension |
+| `{{ Measure('order_total') }}` / `{{ Measure('order__order_total') }}` | Graphit's model-owned measure extension; the bare form resolves only when the name is unique across shared models, the `entity__name` form pins the owning model like a Dimension path |
 
 Legacy token grammar is refused. Keep references inside complete executable SQL and canvas `data-graphit-sql`.
 

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

@@ -26,6 +26,8 @@ Read `semantic-authoring.md` for model/metric shapes and `metric-families.md` fo
 
 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.
 
+Target grammar, live and in a repository tree alike: `model:`, `entity:` and `group:` names are lowercase snake; `metric:` and `dimension:` names are UPPER (`metric:REVENUE_USD`). In a `.graphit/rules/*.rule.yml` file every target must name something the tree declares, including assets the same sync creates; a bare model name or the model's fully qualified `DATABASE.SCHEMA.TABLE` relation also resolves. `table:` targets are retired - target the semantic model. A rule's dbt-style `groups:` key is not imported; placement comes from `apply_on`.
+
 Constraints keep their five semantics: required predicate, forbidden column, required filter, required aggregation, and value restriction. Use declared semantic identities and typed values.
 
 ## Update

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

@@ -4,12 +4,12 @@ Load before querying, authoring, or building a dashboard.
 
 ## Group-first discovery
 
-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. Read visible groups and effective status. Present the groups related to the question and agree on the starting group and audience with the user; carry forward a choice they already made.
+2. Investigate that group in stages. First inventory its relevant models, metrics, dimensions, measures, entities, families and rules; then read the definitions needed to understand what already exists. Use bounded discovery and continuation rather than loading every full definition at once.
+3. Alongside that focused investigation, run semantic search for the question and related concepts across other accessible groups. A related definition may live elsewhere. Inspect promising matches in full and explain their group and relevance; finding a match does not silently change the agreed data or authoring scope.
+4. Look for existing dashboards using dashboard listing and metric usage. Inspect the relevant accessible dashboards before proposing a duplicate. KB search does not search dashboards or retained rules; use their own reads.
+5. After each meaningful research stage, show what you found and recommend the next step. Let the user choose at real forks; do not silently research everything, build the result and leave them behind.
+6. Before authoring, bring back the existing definitions and dashboards that answer the question, any reusable pieces, and the specific remaining gap. Recommend reuse, extension or new work and agree on that choice with the user before creating anything. Do not repeat a decision or approval they already supplied.
 
 The lowercase group name is the semantic label. Use the server-provided uppercase `domain_keys`/status key for data-source `--domain`.
 
@@ -30,21 +30,21 @@ Entities replace relationship assets. Topics are metadata, not roots. Synonyms a
 
 ## Read roles
 
-- `list` inventories a root noun.
+- `list` inventories a root noun. For metric candidates, enable `summary`; set `limit` for the page size and pass `next_cursor` as `cursor` to continue. The CLI flags are `--summary`, `--limit`, and `--cursor`.
 - `tree` shows the collapsed hierarchy.
 - `search` covers models, metrics, groups, and nested components; not retained rules.
-- `get` reads one exact root.
+- `get` reads one exact root in full. Inspect candidate metrics and their owning models before deciding that inputs are equivalent; summaries cannot establish reuse.
 - `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.
 
-A capped or empty search is not proof of absence.
+A capped or empty search is not proof of absence. A summary page is also incomplete while `truncated` is true: follow `next_cursor` before declaring a gap. Report returned items against `total`; totals describe visible scope. If `migration_incomplete` is true, report an incomplete catalog instead of proposing missing assets. Summary descriptions are excerpts; full definitions remain available through `get`.
 
 ## Governed references
 
-Use `{{ Metric('revenue') }}`, `{{ Dimension('order__channel') }}`, and `{{ Measure('order_total') }}` only for Graphit's measure extension. Legacy token grammar is refused.
+Use `{{ Metric('revenue') }}`, `{{ Dimension('order__channel') }}`, and `{{ Measure('order_total') }}` only for Graphit's measure extension. A bare `Measure('name')` must be unique across shared models; write `Measure('entity__name')` to pin the owner. Legacy token grammar is refused.
 
 ## Gap decision
 
-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.
+Research first, then recommend. Show which existing definitions or dashboards already cover the request, what can be reused or extended, and what is still missing. Propose authoring only for that agreed gap, with formula, grain, binding, group, rule impact and verification. Ask when a choice is unresolved; do not treat a request to investigate as permission to build.

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

@@ -6,7 +6,7 @@ Load when investigating semantic reach or presenting KB results.
 
 | Need | Read |
 |---|---|
-| Inventory roots | list semantic-model, metric, group, or rule |
+| Inventory roots | list semantic-model, metric, group, or rule; enable `summary` for metric candidates |
 | Full root definition | get |
 | Collapsed hierarchy | tree |
 | Ranked discovery | search |
@@ -15,7 +15,7 @@ Load when investigating semantic reach or presenting KB results.
 | Semantic neighborhood | explore semantic-model, metric, or group |
 | Dashboard/rule impact | usage |
 
-`list metric` is flat. Families collapse in tree/search/family views.
+`list metric` is flat. Families collapse in tree/search/family views. Metric summaries are candidates, not full definitions: use `get` for semantics and model/source binding before reuse. Continue with `next_cursor` while `truncated` is true; a partial page does not establish absence. Omitting `summary` preserves the existing full-definition listing.
 
 ## Investigations
 

package/skills/graphit/references/operations.md

@@ -58,6 +58,6 @@ Commands write only the result payload to stdout; all decoration (progress, tabl
 
 ## Working artifacts
 
-Keep every local file you create in one place: a `./.graphit/` directory in the working dir (distinct from the `~/.graphit/` credential store). Scratch HTML written before `graphit dashboard update-html <id> --file`, output redirected from `graphit dashboard get-html`, exported PNG/PDF, throwaway SQL - all under `.graphit/`, never scattered across the user's repo. `graphit dashboard export` already defaults its output there (no `--output` needed) and drops a self-ignoring `.gitignore`, so the dir is never committed.
+For ordinary dashboard work, keep scratch HTML, exports and throwaway SQL together in `./.graphit/` (distinct from `~/.graphit/` credentials). Exception: in a repository-owned KB workflow that directory is durable, committed source. Load repo-preparation.md and keep scratch exports elsewhere; never make the definition tree self-ignoring.
 
-These are ephemeral. The platform dashboard is the source of truth and the durable artifact; anything local re-materializes on demand (`graphit dashboard get-html <id>` for the HTML, `graphit dashboard export <id> --format png|pdf` for a rendered image). When you finish a piece of work, offer to remove `.graphit/` - nothing of value is lost. Keep it a soft suggestion, not a forced step.
+Dashboard scratch is ephemeral and can be regenerated through the CLI. Offer cleanup only for artifacts known to be scratch. Never offer to remove a repository-owned `.graphit/` tree or an existing directory whose contents you have not classified.

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

@@ -21,9 +21,11 @@ Run `graphit kb repo show` first.
 - `manual` with no binding: initialize. Scaffold `.graphit/` per `repo-preparation.md`,
   run `graphit kb repo verify --path . --allow-dirty` (a `local_only` plan, never
   applyable; an uncommitted `.graphit/` is refused without the flag), fix findings until
-  the verdict passes, commit on a branch, open the PR with the user's own tooling. Then tell an org admin to bind (`graphit kb repo bind --connection <id>
-  --repo <owner/name> --branch main`), link reviewers (`kb repo link-identity`) and mint
-  the CI tokens (below). Those are admin actions you never run yourself.
+  the verdict passes, commit on a branch, open the PR with the user's own tooling. Then tell an org admin to bind (`graphit kb repo bind --repo <owner/name> --branch main`;
+  the connection resolves from the repository; on `connection_ambiguous` pass
+  `--connection <id>` from `graphit connector list`'s `id` column, never the card's token
+  fingerprint), link reviewers (`kb repo link-identity`) and mint the CI tokens
+  (below). Those are admin actions you never run yourself.
 
 ## A Data Source through a PR
 
@@ -34,9 +36,10 @@ Run `graphit kb repo show` first.
 3. Branch, commit, open the PR with the user's tooling and report the PR link. CI verifies
    the PR head and applies the merged commit; you never merge or apply.
 
-A `.sql` change through a PR rebuilds the source with the same `ds_id`; a deleted file
-tombstones it; removing a source something still references refuses at plan time
-(`removal_referenced`).
+A `.sql` change through a PR rebuilds the source with the same `ds_id`. A deleted file
+tombstones it from the second apply on; the first apply keeps the source as `noop` with
+the warning `ds_first_apply_retained` naming the file to commit. Removing a source
+something still references refuses at plan time (`removal_referenced`).
 
 ## Both sides
 
@@ -63,11 +66,15 @@ Typed `{code, message}`; read the code, never the prose.
 | `binding_incomplete`, `local_only`, `config_revision_moved` | bind first; apply reads the provider, not an upload; reload the binding and verify again |
 | `plan_stale`, `tree_mismatch`, `action_digest_mismatch`, `plan_not_found`, `verdict_failed` | the plan no longer matches the org or the tree: verify again and apply the fresh plan |
 | `apply_in_progress`, `migration_in_progress` | an apply or a migration holds the lease: wait, never cancel |
-| `not_on_base_branch`, `not_descendant_of_last_import`, `pr_head_mismatch`, `pull_request_not_found`, `pull_request_list_unavailable` | wrong commit or PR: use the merged SHA on the bound branch |
-| `approvals_unavailable`, `no_head_bound_approvals`, `identity_unlinked`, `identity_unverified`, `member_removed`, `approver_closure_uncovered`, `write_closure_uncovered` | a linked approver holding every written domain must approve the current head; an admin links identities |
+| `not_on_base_branch`, `not_descendant_of_last_import`, `pr_head_mismatch`, `pull_request_not_merged`, `merged_commit_mismatch`, `pr_base_branch_mismatch` | verify the PR head; apply only its merged commit on the bound branch |
+| `pull_request_not_found`, `pull_request_list_unavailable` | no PR resolved for that commit, or the index is still warming: pass `--pr <id>` naming the merged PR; if unavailable, retry later |
+| `approvals_unavailable`, `no_head_bound_approvals`, `approval_head_binding_unprovable`, `identity_unlinked`, `identity_unverified`, `member_removed`, `approver_closure_uncovered`, `write_closure_uncovered` | check native PR approval, reviewer linkage and current Graphit permissions; incomplete or moved provider evidence refuses. Fix the cause, then verify again |
 | `certificate_not_applyable`, `migration_requires_plan`, `migration_requires_commit`, `migration_mode_invalid`, `approved_sha_missing`, `approved_sha_mismatch` | migration only: the pre-delete `--kind migration` verify is a certificate; after the delete a fresh `--kind migration` verify yields the plan for `apply --plan <id>`; the SHA must match `bind --approved-sha` |
 | `token_invalid`, `token_revoked`, `token_scope`, `token_repo_mismatch` | CI token: mint a fresh one, use the right scope, mint for this repository |
 
+Operation status `failed_retryable`: retry once, then report. `refused` or a `fail`
+verdict: never retry unchanged or route around it.
+
 ## Refusals inside the app
 
 In a manual org the in-app agent and UI refuse shared writes with "the Knowledge Base is
@@ -77,11 +84,6 @@ its SQL in", "change its refresh contract in" or "remove it by deleting"
 `datasources/{name}.sql` "and open a pull request". Private sandboxes and operational verbs
 (refresh, rebuild, pause) stay direct. The fix is the file and a PR, never a workaround.
 
-## Failures
-
-Operation status `failed_retryable`: retry once, then report. `refused` or a `fail`
-verdict: never retry; report the finding and its next step. Never route around a refusal.
-
 ## Truthful receipts
 
 Report drafted, verified (local-only or provider), PR opened, merged and applied as
@@ -90,12 +92,13 @@ quote the operation id, the plan id and the verdict. Queued or timed out is not
 
 ## CI in one paragraph
 
-Two jobs, two tokens, one pinned CLI version. The job exports the token as `GRAPHIT_TOKEN`
-in its environment, never as a `--token` argument (argv is visible in process listings and
-shell traces; `--token` is the interactive form). On the PR, with the `kb:verify` token:
-`graphit kb repo verify --sha $HEAD --pr $PR` (verify and status only), a required check on
-the bound branch. On merge, with the `kb:apply` token: `graphit kb repo apply --sha
-$MERGED_SHA`, which re-verifies the merged commit (a squash changes the SHA) and applies.
-Tokens: `graphit kb repo token mint --scope kb:verify|kb:apply` (admin, shown once, `gkb.`
-prefix), `token list`, `token revoke <id>`. The token is CI's authority to call; the PR's
-head-bound approvers still hold the write closure, and a token never stands in for them.
+Two jobs, two tokens, one pinned CLI version. Export `GRAPHIT_TOKEN` in the job
+environment, never as `--token` in argv or shell traces. The required PR check uses
+`kb:verify`: `graphit kb repo verify --sha $HEAD --pr $PR` (verify/status only).
+After the customer merges, the protected `kb:apply` job runs
+`graphit kb repo apply --sha $MERGED_SHA`. Both check native reviewers' current
+Graphit permissions; the merger is audit context. Apply revalidates the actual
+merged commit, including squash merges. CI always passes `--sha`; flagless
+interactive verify resolves and reports the bound branch head. Admin commands:
+`graphit kb repo token mint --scope kb:verify|kb:apply` (shown once, `gkb.` prefix),
+`token list`, `token revoke <id>`. Tokens authorize calls, never replace reviewers.