@graphit/cli 0.2.355 → 0.2.356

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Graphit CLI plugin for AI coding assistants",
-    "version": "0.2.355"
+    "version": "0.2.356"
   },
   "plugins": [
     {
@@ -16,9 +16,9 @@
       "source": {
         "source": "npm",
         "package": "@graphit/cli",
-        "version": "0.2.355"
+        "version": "0.2.356"
       },
-      "version": "0.2.355",
+      "version": "0.2.356",
       "category": "data-visualization",
       "tags": [
         "bi",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.2.355",
+  "version": "0.2.356",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.2.355",
+  "version": "0.2.356",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/bin/graphit

@@ -14,7 +14,7 @@ if [ -z "${GRAPHIT_PLUGIN_ROOT:-}" ]; then
 fi
 
 # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
-FLOOR_VERSION="0.2.355"
+FLOOR_VERSION="0.2.356"
 
 PACKAGE_NAME="@graphit/cli"
 # Strict semver: anything else is rejected so a tampered cache cannot inject.

package/bin/graphit.ps1

@@ -7,7 +7,7 @@ if (-not $env:GRAPHIT_PLUGIN_ROOT) {
 }
 
 # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
-$FloorVersion = "0.2.355"
+$FloorVersion = "0.2.356"
 
 $PackageName = "@graphit/cli"
 # Strict semver: anything else is rejected so a tampered cache cannot inject.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.2.355",
+  "version": "0.2.356",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "repository": {
     "type": "git",

package/skills/graphit/SKILL.md

@@ -2,7 +2,7 @@
 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.355"
+skill_version: "0.2.356"
 ---
 
 <!-- SIZE EXEMPTION (SKILL.md): hard limit 12,288 chars, exempted ceiling 34,048. Reviewed 2026-09-10. 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. -->
@@ -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 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.
+- Keep scratch files together. In repository-owned workflows `.graphit/` is durable source, never scratch: read repo-preparation.md before authoring it; 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.
 
@@ -145,7 +145,8 @@ Load only the relevant reference. Check `graphit <command> --help` for flags.
 | 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 |
+| connecting a repository as KB owner: bind, PR, identities, CI tokens | references/repo-setup.md |
+| a bound repository-owned (`manual`) org: verify, refusals, Data Sources via PR | references/repo-kb.md |
 | building or curating semantic assets (the gate) | kb-structure.md, kb-scope.md, kb-actions.md, semantic-authoring.md, metric-families.md |
 | a business-knowledge, schema, ERD, or data-dictionary document should inform semantic definitions | attached-docs.md |
 | data-source refresh modes, incremental settings, or reconciliation | data-source-refresh.md |
@@ -164,7 +165,7 @@ 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.355 <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.356 <command>`; pin a version for reproducibility. The table is generated from the CLI; check command help for exact flags.
 
 <!-- COMMANDS:START -->
 

package/skills/graphit/VERSION.json

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

package/skills/graphit/references/onboarding.md

@@ -1,6 +1,6 @@
 # First Run: From an Empty Workspace to a First Dashboard
 
-Load this when the user is signed in but visible groups/models and `graphit ds list` are empty. Onboarding is the job, not a blocker: walk through it one step at a time and surface each result. Once a source and semantic assets exist, return to the normal loop.
+Load this when the user is signed in but visible groups/models and `graphit ds list` are empty. If a repository is to own the Knowledge Base instead, that first run is `repo-setup.md`. Onboarding is the job, not a blocker: walk through it one step at a time and surface each result. Once a source and semantic assets exist, return to the normal loop.
 
 ## The arc
 

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

@@ -2,7 +2,9 @@
 
 Load when: `graphit kb repo show` reports `ownership_mode: manual` or `migrating`, a
 `.graphit/` tree exists, a shared KB or Data Source change was refused as repository-owned,
-or the user asks to set up, verify or sync the repository. A `managed` org never loads this.
+or the user asks to verify or sync the repository. Connecting a repository for the first
+time (no binding, no PR, no CI tokens, no import yet) is `repo-setup.md`, step by step;
+this reference is the contract once it is bound. A `managed` org never loads this.
 
 ## Contract
 
@@ -18,14 +20,11 @@ Run `graphit kb repo show` first.
 
 - `managed`: this reference does not apply. Use the ordinary KB and Data Source verbs.
 - `manual` with a bound repository: the procedures below.
-- `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 --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.
+- `manual` with no binding, or bound with `last_imported_sha` null: follow `repo-setup.md`
+  state by state. It scaffolds per `repo-preparation.md`, verifies with
+  `graphit kb repo verify --path . --allow-dirty`, and hands each admin step over one at a
+  time (`graphit kb repo bind`, `kb repo link-identity`, `kb repo token mint`); you never
+  run those yourself.
 
 ## A Data Source through a PR
 
@@ -68,11 +67,14 @@ Typed `{code, message}`; read the code, never the prose.
 | `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_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 |
+| `identity_unlinked`, `member_removed`, `pr_author_unavailable`, `provider_identity_mismatch`, `author_closure_uncovered`, `write_closure_uncovered` | the PR author must be a linked, current member whose KB write covers every touched group; reviewers are the provider's process. Fix the link or the permission, then verify again |
+| `premerge_verification_required`, `pr_base_moved`, `pr_base_stale`, `pr_target_mismatch`, `pr_source_repository_unproven` | the PR must be open, from a branch in the bound repository, targeting the bound branch, its destination unchanged since verify; update it and verify again |
+| `migration_required` | routine sync on a `managed` org: switch to `manual` first (repo-setup.md, state 0) |
 | `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`
+Operation status `failed_retryable`: retry once, then report. `component_rejected`: the
+write contract refused one asset; fix its file and verify again. `refused` or a `fail`
 verdict: never retry unchanged or route around it.
 
 ## Refusals inside the app
@@ -90,15 +92,12 @@ Report drafted, verified (local-only or provider), PR opened, merged and applied
 distinct states. Claim an apply only when you saw the operation reach terminal `succeeded`;
 quote the operation id, the plan id and the verdict. Queued or timed out is not done.
 
-## CI in one paragraph
-
-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.
+## CI
+
+The two jobs, the token recipe and the provider differences live in `repo-setup.md`. Both
+jobs authorize on the PR author alone: a linked, current member whose KB write covers every
+touched group; reviewers and the merger are the provider's process.
+Apply revalidates the actual merged commit, including squash merges. CI always passes
+`--sha`; flagless interactive verify resolves and reports the bound branch head. Tokens
+(`graphit kb repo token mint`, `token list`, `token revoke <id>`) authorize calls, never
+replace reviewers.

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

@@ -0,0 +1,103 @@
+# Connect a Repository as the Knowledge Base Owner
+
+Load when: the user wants a repository to own the shared Knowledge Base, or
+`graphit kb repo show` reports `ownership_mode: manual` with `repo: null`, or a
+binding exists and `last_imported_sha` is null. Skip it once `last_imported_sha`
+is set: routine work follows repo-kb.md. Git providers: `github`, `bitbucket`;
+the procedure is the same, the differences are in the last table.
+
+## How to guide
+
+One step at a time. Name the state the user is in, say in one or two plain
+sentences what the step does and why it exists, say who runs it, do your part,
+show the result, then the next step. For an admin step hand over exactly one
+command and wait; never run `mode`, `bind`, `link-identity` or `token mint`
+yourself, never touch a key or a token value, never merge or apply.
+
+The split, when the user asks why so much is manual: an org admin's own login
+establishes trust once (who owns the KB, which accounts count, which tokens may
+act). CI then repeats the mechanical part forever: verify every pull request
+head, apply every merged commit. CI cannot bind because its tokens are minted
+for the binding, and a token authorizes calls, it never replaces a reviewer.
+
+## Find the state
+
+Read `graphit kb repo show`, `graphit connector list`, `graphit kb repo
+identities`, `graphit kb repo token list` and the branch, then match the first
+row that fits.
+
+| State | You see | Next step | Who |
+|---|---|---|---|
+| 0 managed | `show`: `ownership_mode: managed` | empty shared KB: `graphit kb repo export-datasources --out .graphit/datasources`, commit, then `graphit kb repo mode manual`; `shared_kb_not_empty` means the protected migration: ask the Graphit team, never route around it | admin |
+| 1 no warehouse | `connector list` has no warehouse entry | add it in the Sources Hub or `graphit connector add`; the key never passes through you | admin |
+| 2 no definitions | `.graphit/` missing or empty | author it (repo-preparation.md), then `graphit kb repo verify --path . --allow-dirty` until it passes | you |
+| 3 not bound | `show`: `repo: null` | `graphit kb repo bind --repo <owner/name> --branch <base>` | admin |
+| 4 no pull request | tree committed, no PR | commit on a branch, push, open the PR with the user's tooling; ask for its number | you, user |
+| 5 author unlinked | `verify --sha <head> --pr <n>` refuses `identity_unlinked`; `identities` shows `seen` | `graphit kb repo link-identity <provider> <account_id> <member-email>` | admin |
+| 6 no CI tokens | `token list` empty, or CI says the token is not recognized | mint and store both tokens (below) | admin |
+| 7 verified | provider verify: `pass`, `applyable: true` | approve and merge | user |
+| 8 merged | the merge job runs `apply` | wait for it; `show` reports the merged sha as `last_imported_sha` | CI |
+
+## What to say at each step
+
+- State 2: with no warehouse connection a local verify passes without compiling
+  the metrics. Report it as "pass, not compiled" and expect compile findings
+  once state 1 is done. A local plan is never applyable; that is by design.
+- State 2: a provenance shard's `content_hash` must equal the cited document's
+  bytes at that commit, or verify refuses `source_drift`: fix the shard, never
+  the document. `derived_without_source` cannot fire before the first import;
+  there is no earlier apply to differ from.
+- State 3: the connection resolves from the repository. On
+  `connection_ambiguous` add `--connection <id>` from the `id` column of
+  `graphit connector list`, never the token fingerprint on the Sources Hub card.
+- State 5: the first provider verify refuses here on purpose: an account
+  becomes linkable only after a verify has seen it. Any member may plan, so run
+  `graphit kb repo verify --sha <head> --pr <n>` with the user's login before CI
+  has tokens; `identities` then shows the author as `seen`. Use `account_id`
+  from it (logins may contain spaces). `unlinked` means an admin unlinked that
+  account; relink it by id. The linked author with KB write on every touched
+  group is the whole authority; reviewers are the provider's own process.
+- State 6: mint to the clipboard, never to the screen. Wrapped or quoted
+  terminal output is why CI reports "the machine token is not recognized".
+
+  ```bash
+  graphit kb repo token mint --scope kb:verify | python3 -c "import sys,json; print(json.load(sys.stdin)['token'], end='')" | pbcopy
+  ```
+
+  `pbcopy` is macOS: `xclip -selection clipboard` on Linux, `clip` on Windows.
+  Paste it as `GRAPHIT_VERIFY_TOKEN`, repeat with `kb:apply` for
+  `GRAPHIT_APPLY_TOKEN`. Tokens never expire: one that reached a chat, a log or
+  a wrapped paste is revoked (`graphit kb repo token revoke <id>`) and minted
+  again. After the next run `token list` shows `last_used_at`; that is the
+  proof CI used it. "must be a machine token" with an empty value means the
+  variable is not visible to that job (see the provider table).
+- Token refusals: `token_invalid`, `token_revoked`, `token_scope`,
+  `token_repo_mismatch`: mint a fresh one, with the right scope, for this
+  repository.
+- State 7: Graphit checks the PR author, never the approvals; approving and
+  merging follow the provider's own rules.
+
+## CI: two jobs, two tokens, one pinned CLI
+
+Export `GRAPHIT_TOKEN` from the secret in the job environment, never as
+`--token` or in a shell trace. Run every job command through the pinned CLI,
+`npx -y @graphit/cli@<version> kb repo ...` (or `npm install -g` that version once
+per job). The PR job runs `kb repo verify --sha <head> --pr <number>` with the
+`kb:verify` token and is the required check; the merge job on the base branch
+runs `kb repo apply --sha <merged sha>` with `kb:apply` and re-verifies the
+merged commit itself. Exit codes: 0 pass, 1 failed, 2 refused or failing
+verdict, 3 stopped waiting (poll the operation id, do not resubmit).
+
+| | github | bitbucket |
+|---|---|---|
+| pipeline file | `.github/workflows/*.yml`, jobs on `pull_request` and `push` to the base branch | `bitbucket-pipelines.yml`, `pull-requests:` and `branches: <base>:` steps |
+| head, PR id, merged sha | `github.event.pull_request.head.sha`, `github.event.pull_request.number`, `github.sha` | `$BITBUCKET_COMMIT`, `$BITBUCKET_PR_ID`, `$BITBUCKET_COMMIT` on the base branch |
+| where both secrets live | Settings > Secrets and variables > Actions, repository secrets | Repository settings > Pipelines > Repository variables, Secured; a deployment-environment variable reaches only a step that declares `deployment:` |
+| approval | a review with Approve on the head commit | Approve on the PR page; self-approval is allowed |
+
+## Receipts
+
+Drafted, verified (local-only or provider), PR opened, merged and applied are
+five different states; say which one is true. Applied means `graphit kb repo
+show` reports the merged sha as `last_imported_sha`; a green pipeline is not
+that. From then on repo-kb.md is the reference.