@graphit/cli 0.2.372 → 0.2.377

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

@@ -39,6 +39,13 @@ Constraints keep their five semantics: required predicate, forbidden column, req
 5. Verify/unverify separately when intended.
 6. Inspect receipts; a degraded write may have landed and must not be retried blindly.
 
+When one task creates or changes several metrics or semantic models, send them as one `graphit kb batch` instead of one `kb create` or `kb update` each. Every item gets the same checks and its own result, and dashboards rebuild once for the whole batch instead of once per edit, so they keep serving while you author. A single edit stays `kb update`. Steps 1-2 still apply to every item; a batch changes the transport, not the patch discipline.
+
+- Shape: `{"operations": [...]}` or a bare array of `{"op": "update", "noun", "name", "patch"}` and `{"op": "create", "noun", "definition", "unverified"?}` items. Nouns are `metric` and `semantic-model` only; groups, rules and deletes keep their own verbs. Up to 50 items per batch, 20 in-app.
+- Order items so each validates against the ones before it: a semantic model before the metrics that use its measures, a metric before a derived metric over it. Use `--stop-on-error` when later items depend on earlier ones.
+- Items are not all-or-nothing: earlier items stay applied when a later one fails. Read `results` per item, fix what each `error` names, and re-send only the `failed` and `not_attempted` items as a new batch. Never replay the whole batch. An `unknown` item may have landed; read it back with `kb get` before sending it again.
+- In-app, approving the batch verifies each updated item, as approving a single update does.
+
 ## Delete
 
 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.

package/skills/graphit/references/onboarding.md

@@ -67,7 +67,7 @@ Ask whether the user wants a quick query answer or a deployed HTML dashboard. Bu
 After the first dashboard is deployed, tell the user - concisely - what they get for free on it. Keep this to the first dashboard; it never needs repeating, because onboarding stops firing once the workspace has data.
 
 - **Each graph's 3-dot (hamburger) menu**: "view details" opens a panel with the SQL, live query results, and the trust tier plus any enforced rules (the KB assets it lists open as explorable tabs).
-- **The dashboard's own hamburger** (top bar): share it, schedule a recurring email report, export to PNG or PDF, and browse version history.
+- **The dashboard's own hamburger** (top bar): share it, schedule a recurring email or Slack report (or ask Graphit to schedule it), export to PNG or PDF, and browse version history.
 - **Themes and colors** are automatic - dark and light mode, and the brand palette, with no extra work.
 
 Then continue in the normal loop; the workspace is no longer empty.

package/skills/graphit/references/query-contract.md

@@ -15,7 +15,7 @@ Keep the default SQL in `data-graphit-sql` and source in `data-graphit-ds`. Add
 </div>
 ```
 
-These are invented names; use actual accessible sources/columns and governed Metric/Dimension/Measure references where available. A variant contains only `sql` and inherits the owner's source. Cross-source alternatives need separate owners. The spec has no second default SQL, source override or variant named `default`. Unknown fields, versions, duplicate JSON keys, malformed types, undeclared placeholders and the names `__proto__`, `constructor` and `prototype` refuse the save; the refusal names the owner, and the parameter or variant when one is at fault. Save the declaration before selecting it; the backend re-reads the stored owner the page shows (the editor's draft while the page shows it). Local DOM edits are not a new stored query authority.
+These are invented names; use actual accessible sources/columns and governed Metric/Dimension/Measure references where available. A variant contains only `sql` and inherits the owner's source. Cross-source alternatives need separate owners. The spec has no second default SQL, source override or variant named `default`. Unknown fields, versions, duplicate JSON keys, malformed types, undeclared placeholders and the names `__proto__`, `constructor` and `prototype` refuse the save; the refusal names the owner, and the parameter or variant when one is at fault. Save the declaration so the save rule validates it. The SDK reads the specification from the page, picks the default or named statement and sends it as that entity's query; the server authorizes and governs it like any other query.
 
 ```js
 const result = await graphit.resolve({
@@ -32,7 +32,7 @@ Omit `variant` to select the default. Do not combine `variant` with explicit `sq
 
 **One name, one declaration.** A parameter name is one input: every owner that declares `country` declares it identically, so one control's value is valid everywhere it is sent. While authoring, keep one type table per dashboard and copy into each owner's static specification exactly the placeholders its default and variant statements use; an unused declaration refuses the save. Never build specifications in page JavaScript. When owners disagree, the shared check/save path returns a non-blocking `query_param_type_conflict` warning naming the parameter and its declarations; align them, or rename inputs that genuinely differ, and save again.
 
-Dates/as-of, search text, returned top-category arrays and cohort labels are bound values. Keep their parameter names stable across state changes; do not turn a category label into a SQL identifier. Metric/group/grain/horizon changes select authored statements, not SQL fragments passed as values. Send every binding the selected statement uses; bindings removed by the existing integer sentinel simplifier may be omitted. Declared values the selected statement does not use are ignored, so one params object can serve all of that owner's variants; a name that owner does not declare refuses.
+Dates/as-of, search text, returned top-category arrays and cohort labels are bound values. Keep their parameter names stable across state changes; do not turn a category label into a SQL identifier. Metric/group/grain/horizon changes select authored statements, not SQL fragments passed as values. Send every binding the selected statement uses; bindings removed by the existing integer sentinel simplifier may be omitted. Values the selected statement does not use are ignored, so one params object can serve all of that owner's variants.
 
 Preserve the dashboard's authored All/None/include/exclude behavior. An authored empty selection that means All stays distinct from None; do not globally translate every empty list or null. Use explicit mode values such as an enum when appropriate. The existing integer `all_x` sentinel contract remains in `filters.md`.
 

package/skills/graphit/references/scheduled-reports.md

@@ -0,0 +1,22 @@
+# Scheduled Reports
+
+Load before creating, changing, sending or troubleshooting a scheduled report: a dashboard emailed or posted to Slack on a schedule, optionally with agent commentary. A report delivers an existing dashboard, so build or pick the dashboard first. Delivery from a private source still needs Share for the source and its bound model.
+
+## Before creating
+
+- Before `report create`, check `report list --dashboard <id>` and update an existing report instead of creating a second.
+- Resolve destinations with `report destinations`: the Slack channels the bot can post to, the org's members (name and email) and its allowed email domains. Map the user's words ("#growth", "Dana") to those entries; an address outside members and allowed domains is refused.
+- Add only recipients and channels the user named. Confirm destinations, schedule and timezone in one line before `report create`; never widen delivery on your own.
+- A report and its commentary render with the creator's data access - yours when you create it. Say so when the recipients differ from who can open the dashboard.
+
+## Creating and changing
+
+- `report create` needs `--dashboard`, `--name`, `--frequency`, `--send-time` and at least one `--email` or `--slack`. Weekly takes `--day-of-week` (mon..sun), monthly `--day-of-month` (1-28); `--timezone` is IANA and defaults to UTC, so pass the user's.
+- `--filter key=value` sets a dashboard filter by its declared state key (state-contract.md): `a,b` for several values, `start..end` for a date range. `--instructions` adds agent commentary to every run.
+- `report update` changes only the flags passed. `--email`, `--slack`, `--filter` and `--state-file` REPLACE the stored value: read it with `report get` and send the full intended list or map. `--clear-filters` / `--clear-instructions` remove them.
+- Recipients, channels, instructions and filters are the creator's alone to change; pausing, rescheduling, sending, testing and deleting need the creator, a dashboard editor or an org admin. Report a refusal as that rule, not a fault.
+
+## Sending and checking
+
+- `report test` goes to the creator only; use it to check a render. `report send` goes to every recipient now: only when the user asks.
+- `report runs` shows each run's status, deliveries, error and commentary outcome; `report run <id> <run-id>` shows the commentary exchange (creator only). Report partial or failed delivery as it is: a run is not a delivery.

package/skills/graphit/references/share.md

@@ -12,7 +12,7 @@ For "publish", inspect the dashboard state and follow dashboard-create.md's publ
 |---|---|
 | a. Share a private dashboard | Resolve its private dependency closure, then share and file the same dashboard ID. |
 | b. Share definitions | Reuse or move the selected models/metrics into the agreed group; a bound source follows its model. |
-| c. Schedule or deliver from a private source | Plan the source and bound model's move to a shared group before configuring the requested schedule/report. The dashboard may stay private. |
+| c. Schedule or deliver from a private source | Plan the source and bound model's move to a shared group before scheduling per scheduled-reports.md. The dashboard may stay private. |
 | d. Author directly in a group | "Shared from the start": apply checks before each shared source/definition write. Build authors the new private dashboard; share it when complete. Keep the agreed scope. |
 | e. Repository-owned work | Apply the same decisions through repo-kb.md's repository/PR workflow on a capable surface. An in-app ownership refusal is a handoff, not permission for a direct-write replacement. |
 
@@ -24,7 +24,7 @@ Read kb-scope.md for effective permissions and exact placement, kb-discovery.md
 
 **KB-readiness gate:** before work goes live for others, confirm the required models, nested components, metrics, groups and rules exist and have the needed verification. If a business measure is missing, present its gap and proposed governed definition for approval, then author and verify the approved prerequisites. An ad-hoc business measure can be unavailable to governed-only viewers; do not silently publish it as a reusable governed answer. Compare actual binding, grain, time dimension, aggregation, filters, units and policy, not just names or SQL. A same-named conflicting asset is not equivalent: explain the difference and resolve the consequential choice. A truly equivalent accessible asset should be reused.
 
-Choose dashboard audience and folder through dashboard-create.md when sharing. Org sharing requires the dashboard owner to be an org admin/owner; team sharing requires ownership and actual membership. When needed, explain Private/ORG/named scopes via kb-scope.md; keep dashboard audience separate.
+Choose dashboard audience and folder through dashboard-create.md when sharing. Owners share their own; org admins/owners also any they can see. Org needs admin/owner; Team needs membership. When needed, explain Private/ORG/named scopes via kb-scope.md; keep dashboard audience separate.
 
 Before any share or publish, inspect the dashboard for `data-graphit-placeholder` markers. Refuse while any remain and offer "wire it" through build.md. Do not remove markers simply to make sharing pass; real resolves must replace the placeholders.
 

package/skills/graphit-build/SKILL.md

@@ -2,7 +2,7 @@
 name: graphit-build
 description: >-
   Author and verify Graphit dashboard content, private or shared, and build private reports, sources and saved metrics. Pair with graphit-share for shared dependencies, draft sessions and publication. Use graphit-explore for answers without artifacts.
-skill_version: "0.2.372"
+skill_version: "0.2.377"
 ---
 
 # Build: author and verify content
@@ -59,8 +59,10 @@ When no source exists and the user asks for a sketch, mockup, wireframe or layou
 
 Build and show sections as they become useful; continue authorized work without an approval round per chart. Check the canvas, fix `entity_sql_warnings`, and verify rendering and real resolves before calling a data-backed dashboard complete. For a preview, verify layout and marker coverage and report it specifically as a preview.
 
-Without Share's established shared scope/draft, Build writes only privately. Shared authoring stays within that authorization; Share retains checks before shared dependency writes and publication. Private sources refresh manually, in full. A schedule or Slack/email delivery request needs Share for the source and its bound model; explain that and offer it if not already requested. The dashboard may remain private. A private report or export alone does not imply scheduled delivery or a visibility change.
+Without Share's established shared scope/draft, Build writes only privately. Shared authoring stays within that authorization; Share retains checks before shared dependency writes and publication. Private sources refresh manually, in full. A schedule or Slack/email delivery request needs Share for the source and its bound model; explain that and offer it if not already requested, then schedule through ../graphit/references/scheduled-reports.md. The dashboard may remain private. A private report or export alone does not imply scheduled delivery or a visibility change.
 
 For Private first, end with the private link, verification and limitations, plus one offer to share; an offer grants no permission. When sharing/publication is already requested, continue the same artifact through Share's remaining checks and report its actual outcome. Do not repeat an answered choice; obtain approval for additional effects when required. A draft-only request stays a draft.
 
+After completing a dashboard, or when the user asks for something recurring ("every Monday", "a weekly update", "send this to the team"), offer once per session to schedule it as a report; create one only after an explicit yes.
+
 <!-- WORKFLOW:END -->

package/skills/graphit-explore/SKILL.md

@@ -2,7 +2,7 @@
 name: graphit-explore
 description: >-
   Answer, explain or diagnose business data using Graphit. Use after Graphit routing or for a direct Graphit question, including reads of shared dashboards. Does not authorize creating reusable definitions or sharing; use graphit-build to keep a private artifact and graphit-share for shared writes.
-skill_version: "0.2.372"
+skill_version: "0.2.377"
 ---
 
 # Explore: answer the question

package/skills/graphit-share/SKILL.md

@@ -2,7 +2,7 @@
 name: graphit-share
 description: >-
   Share or publish Graphit work, edit shared Graphit dashboards, or author into a shared group. Use after Graphit routing or a direct Graphit shared-scope request. Pair with graphit-build for dashboard authoring. Read-only questions belong to graphit-explore.
-skill_version: "0.2.372"
+skill_version: "0.2.377"
 ---
 
 # Share: checks at the shared write
@@ -39,7 +39,7 @@ For "publish", inspect the dashboard state and follow ../graphit/references/dash
 |---|---|
 | a. Share a private dashboard | Resolve its private dependency closure, then share and file the same dashboard ID. |
 | b. Share definitions | Reuse or move the selected models/metrics into the agreed group; a bound source follows its model. |
-| c. Schedule or deliver from a private source | Plan the source and bound model's move to a shared group before configuring the requested schedule/report. The dashboard may stay private. |
+| c. Schedule or deliver from a private source | Plan the source and bound model's move to a shared group before scheduling per ../graphit/references/scheduled-reports.md. The dashboard may stay private. |
 | d. Author directly in a group | "Shared from the start": apply checks before each shared source/definition write. Build authors the new private dashboard; share it when complete. Keep the agreed scope. |
 | e. Repository-owned work | Apply the same decisions through ../graphit/references/repo-kb.md's repository/PR workflow on a capable surface. An in-app ownership refusal is a handoff, not permission for a direct-write replacement. |
 
@@ -51,7 +51,7 @@ Read ../graphit/references/kb-scope.md for effective permissions and exact place
 
 **KB-readiness gate:** before work goes live for others, confirm the required models, nested components, metrics, groups and rules exist and have the needed verification. If a business measure is missing, present its gap and proposed governed definition for approval, then author and verify the approved prerequisites. An ad-hoc business measure can be unavailable to governed-only viewers; do not silently publish it as a reusable governed answer. Compare actual binding, grain, time dimension, aggregation, filters, units and policy, not just names or SQL. A same-named conflicting asset is not equivalent: explain the difference and resolve the consequential choice. A truly equivalent accessible asset should be reused.
 
-Choose dashboard audience and folder through ../graphit/references/dashboard-create.md when sharing. Org sharing requires the dashboard owner to be an org admin/owner; team sharing requires ownership and actual membership. When needed, explain Private/ORG/named scopes via ../graphit/references/kb-scope.md; keep dashboard audience separate.
+Choose dashboard audience and folder through ../graphit/references/dashboard-create.md when sharing. Owners share their own; org admins/owners also any they can see. Org needs admin/owner; Team needs membership. When needed, explain Private/ORG/named scopes via ../graphit/references/kb-scope.md; keep dashboard audience separate.
 
 Before any share or publish, inspect the dashboard for `data-graphit-placeholder` markers. Refuse while any remain and offer "wire it" through [graphit-build](../graphit-build/SKILL.md). Do not remove markers simply to make sharing pass; real resolves must replace the placeholders.