@revos/cli 0.3.2 → 0.3.5

package/dist/adapters/oclif/commands/table-views/create.mjs

@@ -1,4 +1,4 @@
-import { t as createCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { t as createCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/table-views/create.ts
 var create_default = createCommand({
 	resource: "tableViews",

package/dist/adapters/oclif/commands/table-views/delete.mjs

@@ -1,4 +1,4 @@
-import { n as deleteCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { n as deleteCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/table-views/delete.ts
 var delete_default = deleteCommand({
 	resource: "tableViews",

package/dist/adapters/oclif/commands/table-views/list.mjs

@@ -1,4 +1,4 @@
-import { i as listCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { i as listCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/table-views/list.ts
 var list_default = listCommand({
 	resource: "tableViews",

package/dist/adapters/oclif/commands/table-views/update.mjs

@@ -1,4 +1,4 @@
-import { a as updateCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { a as updateCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/table-views/update.ts
 var update_default = updateCommand({
 	resource: "tableViews",

package/dist/adapters/oclif/commands/tables/create.mjs

@@ -1,4 +1,4 @@
-import { t as createCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { t as createCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/tables/create.ts
 var create_default = createCommand({
 	resource: "tables",

package/dist/adapters/oclif/commands/tables/delete.mjs

@@ -1,4 +1,4 @@
-import { n as deleteCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { n as deleteCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/tables/delete.ts
 var delete_default = deleteCommand({
 	resource: "tables",

package/dist/adapters/oclif/commands/tables/get.mjs

@@ -1,4 +1,4 @@
-import { r as getCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { r as getCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/tables/get.ts
 var get_default = getCommand({
 	resource: "tables",

package/dist/adapters/oclif/commands/tables/list.mjs

@@ -1,4 +1,4 @@
-import { i as listCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { i as listCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/tables/list.ts
 var list_default = listCommand({
 	resource: "tables",

package/dist/adapters/oclif/commands/tables/update.mjs

@@ -1,4 +1,4 @@
-import { a as updateCommand } from "../../../../presets-mJzFGMhG.mjs";
+import { a as updateCommand } from "../../../../presets-Blw7i6BW.mjs";
 //#region src/adapters/oclif/commands/tables/update.ts
 var update_default = updateCommand({
 	resource: "tables",

package/dist/{base.command-CnVb4RG6.mjs → base.command-CWGrSq73.mjs}

@@ -1,4 +1,4 @@
-import { G as ApiError, I as setAuthConfig, U as loadCredentials, i as formatEnvMismatchError, l as resolveProjectContext, o as formatProjectOrgFlagError, r as formatCredentialsMismatchWarning, u as validateEnvAgainstProject } from "./core-CY9pC37x.mjs";
+import { G as ApiError, I as setAuthConfig, U as loadCredentials, i as formatEnvMismatchError, l as resolveProjectContext, o as formatProjectOrgFlagError, r as formatCredentialsMismatchWarning, u as validateEnvAgainstProject } from "./core-CChCxudp.mjs";
 import { Command, Flags } from "@oclif/core";
 import { makeTable } from "@oclif/table";
 //#region src/adapters/oclif/base.command.ts

package/dist/{core-CY9pC37x.mjs → core-CChCxudp.mjs}

@@ -2254,6 +2254,7 @@ var InitService = class InitService {
 		".claude/skills/create-dbt-transformations",
 		".claude/skills/create-dbt-transformations/references",
 		".claude/skills/load-sample-data",
+		".claude/skills/query-semantic-model",
 		".claude/skills/visualize-semantic-model",
 		".claude/skills/visualize-semantic-model/scripts",
 		"dbt/models/bronze",
@@ -2292,6 +2293,7 @@ var InitService = class InitService {
 		".claude/skills/create-dbt-transformations/references/schema-conventions.md",
 		".claude/skills/create-dbt-transformations/references/edge-cases.md",
 		".claude/skills/load-sample-data/SKILL.md",
+		".claude/skills/query-semantic-model/SKILL.md",
 		".claude/skills/visualize-semantic-model/SKILL.md",
 		".claude/skills/visualize-semantic-model/scripts/render_graph.py",
 		"dbt/models/bronze/.gitkeep",
@@ -2474,6 +2476,7 @@ var InitService = class InitService {
 			".claude/skills/create-dbt-transformations/references/schema-conventions.md": this.renderTemplate("skills/create-dbt-transformations/references/schema-conventions.md", {}),
 			".claude/skills/create-dbt-transformations/references/edge-cases.md": this.renderTemplate("skills/create-dbt-transformations/references/edge-cases.md", {}),
 			".claude/skills/load-sample-data/SKILL.md": this.renderTemplate("skills/load-sample-data/SKILL.md", {}),
+			".claude/skills/query-semantic-model/SKILL.md": this.renderTemplate("skills/query-semantic-model/SKILL.md", {}),
 			".claude/skills/visualize-semantic-model/SKILL.md": this.renderTemplate("skills/visualize-semantic-model/SKILL.md", {}),
 			".claude/skills/visualize-semantic-model/scripts/render_graph.py": this.renderTemplate("skills/visualize-semantic-model/scripts/render_graph.py", {}),
 			"dbt/models/bronze/.gitkeep": "",

package/dist/{factory-DTqayaCF.mjs → factory-SazXfu26.mjs}

@@ -1,5 +1,5 @@
-import { E as getConfig, b as createApiClient } from "./core-CY9pC37x.mjs";
-import { t as BaseCommand } from "./base.command-CnVb4RG6.mjs";
+import { E as getConfig, b as createApiClient } from "./core-CChCxudp.mjs";
+import { t as BaseCommand } from "./base.command-CWGrSq73.mjs";
 import * as fs from "fs";
 import * as path from "path";
 import chalk from "chalk";

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { A as buildAuthorizationUrl, B as deleteCredentials, C as formatError, D as resolveApiUrl, E as getConfig, F as refreshAccessToken, G as ApiError, H as isTokenExpired, I as setAuthConfig, L as setAuthEnv, M as generatePKCEChallenge, N as getActiveAuthConfig, O as performOAuthLogin, P as getUserInfo, R as tokenResponseToCredentials, S as resolveAppUrl, T as DEFAULT_API_URL, U as loadCredentials, V as getCredentialsPath, W as saveCredentials, a as formatInProjectSwitchWarning, b as createApiClient, c as isInsideProject, d as iac_exports, i as formatEnvMismatchError, j as exchangeCodeForTokens, k as AUTH_ENVS, l as resolveProjectContext, o as formatProjectOrgFlagError, r as formatCredentialsMismatchWarning, s as renderProjectContextLine, t as InitService, u as validateEnvAgainstProject, w as sanitizeFileName, x as unwrap, z as startOAuthServer } from "./core-CY9pC37x.mjs";
+import { A as buildAuthorizationUrl, B as deleteCredentials, C as formatError, D as resolveApiUrl, E as getConfig, F as refreshAccessToken, G as ApiError, H as isTokenExpired, I as setAuthConfig, L as setAuthEnv, M as generatePKCEChallenge, N as getActiveAuthConfig, O as performOAuthLogin, P as getUserInfo, R as tokenResponseToCredentials, S as resolveAppUrl, T as DEFAULT_API_URL, U as loadCredentials, V as getCredentialsPath, W as saveCredentials, a as formatInProjectSwitchWarning, b as createApiClient, c as isInsideProject, d as iac_exports, i as formatEnvMismatchError, j as exchangeCodeForTokens, k as AUTH_ENVS, l as resolveProjectContext, o as formatProjectOrgFlagError, r as formatCredentialsMismatchWarning, s as renderProjectContextLine, t as InitService, u as validateEnvAgainstProject, w as sanitizeFileName, x as unwrap, z as startOAuthServer } from "./core-CChCxudp.mjs";
 export { AUTH_ENVS, ApiError, DEFAULT_API_URL, InitService, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, formatCredentialsMismatchWarning, formatEnvMismatchError, formatError, formatInProjectSwitchWarning, formatProjectOrgFlagError, generatePKCEChallenge, getActiveAuthConfig, getConfig, getCredentialsPath, getUserInfo, iac_exports as iac, isInsideProject, isTokenExpired, loadCredentials, performOAuthLogin, refreshAccessToken, renderProjectContextLine, resolveApiUrl, resolveAppUrl, resolveProjectContext, sanitizeFileName, saveCredentials, setAuthConfig, setAuthEnv, startOAuthServer, tokenResponseToCredentials, unwrap, validateEnvAgainstProject };

package/dist/{presets-mJzFGMhG.mjs → presets-Blw7i6BW.mjs}

@@ -1,5 +1,5 @@
-import { x as unwrap } from "./core-CY9pC37x.mjs";
-import { n as createListRender, r as defineApiCommand, t as bodyFlag } from "./factory-DTqayaCF.mjs";
+import { x as unwrap } from "./core-CChCxudp.mjs";
+import { n as createListRender, r as defineApiCommand, t as bodyFlag } from "./factory-SazXfu26.mjs";
 import { Args, Flags } from "@oclif/core";
 //#region src/adapters/oclif/presets.ts
 function camelToKebab(s) {

package/dist/templates/README.md

@@ -69,6 +69,7 @@ This project ships pre-installed Claude skills under `.claude/skills/` for the c
 - **`create-cubes`** — build Cube.dev semantic models from gold-layer tables.
 - **`create-dbt-transformations`** — write bronze→silver→gold dbt models.
 - **`load-sample-data`** — seed BigQuery with example data when the warehouse is empty.
+- **`query-semantic-model`** — run a Cube.js query and render the result inline in chat as a table + ASCII bar chart.
 - **`visualize-semantic-model`** — render the cube graph as an image.
 
 Inside the container, ask Claude things like _"create a Connection for our Stripe source"_ or _"build a silver model for the orders table"_ and it will use the matching skill.

package/dist/templates/skills/create-connections/SKILL.md

@@ -21,7 +21,7 @@ The hard part is **stream selection** and **sync-mode choice**, not the YAML sha
 
 ## Prerequisites
 
-- The Source already exists on the server (you'll get its `id` via `revos sources list`). If the user wants to ingest from a source that isn't created yet, stop and tell them to run `revos sources create` first — source configuration (connector picker, credentials, OAuth) lives in the RevOS UI.
+- The Source already exists on the server (you'll get its `id` via `revos sources list`). If the user wants to ingest from a source that isn't created yet, stop and tell them to run `revos sources create` first — source configuration (connector picker, credentials, OAuth) lives in the RevOS UI. Once the user confirms they've returned from the UI, **re-run `revos connections list --json` and `revos sources list --json` before continuing** — the UI may have auto-created a connection for the new source. If a matching connection already exists, offer to pull it with `revos pull` rather than authoring a duplicate.
 - `revos auth status` shows authenticated. If not, ask the user to run `revos auth login`.
 
 ---
@@ -44,7 +44,9 @@ After deriving sync mode + cursor + primary key for each selected stream, presen
 
 ## Phase 1: Identify the Source
 
-Run `revos sources list --json` and match on the server-side `name` (or run `revos sources list` for a scannable table). Record the source's `id` — that goes into the Connection YAML as `spec.source.id`.
+First, run `revos connections list --json` to see what connections already exist. If the user just returned from the web UI, this re-fetch is essential — the UI may have created a connection automatically. If you find a connection that matches the user's stated goal, surface it before proceeding so you don't create a duplicate.
+
+Then run `revos sources list --json` and match on the server-side `name` (or run `revos sources list` for a scannable table). Record the source's `id` — that goes into the Connection YAML as `spec.source.id`.
 
 If no source was named, ask the user which one. Don't proceed without an id.
 

package/dist/templates/skills/create-cubes/SKILL.md

@@ -247,6 +247,9 @@ Key rules:
 6. Every cube **must** include a SQL-based `refresh_key`. Use `SELECT MAX(<timestamp_col>)` with columns in this priority: `_airbyte_extracted_at` (present on all Airbyte sources), `updated_at`/`modified_at` (CDC streams), `created_at` (insert-only facts). Only use `every: <interval>` as absolute last resort when **no timestamp column exists in the table** — add a YAML comment explaining why (e.g. `# no timestamp column available`).
 7. `refresh_key.sql` references the same table as `sql_table`.
 8. Tag unvalidated joins with `# UNVALIDATED: <reason>`.
+9. For cubes derived from data ingested by a Connection (i.e. the gold model traces back to bronze tables produced by `revos apply` on a `Connection`), set `meta.abConnectionId: <connection-id>`. This groups cubes by their originating connection in the UI. Resolve the connection id with `revos connections list --json` — match by `spec.prefix` against the bronze table prefix the gold model reads from. Bridge / junction cubes built on top of connection-sourced models inherit the same `abConnectionId`. Cubes derived from purely local data (e.g. hand-written silver/gold models with no upstream connection) omit `abConnectionId`.
+10. For cubes whose rows have a natural human-readable label (companies, contacts, deals, tickets, users, projects, …), set `meta.nameDimension: <short-dimension-name>`. The value is the **short** dimension key (no `${CUBE}.` prefix and no cube-name prefix) — e.g. `properties_name`, `displayName`, `dealname`. The frontend uses this to pick the column shown as the entity's name when the cube is added as a table (see `useCubeFromMeta` in the frontend). Pick the dimension that a user would recognize as "the name of this thing"; if no such single column exists (pure join / bridge cubes, fact tables, event logs), omit `nameDimension`. The dimension must exist on this cube under `dimensions:`.
+11. `meta` is closed: only `abConnectionId` and `nameDimension` are allowed today. Omit the whole `meta` block if neither applies.
 
 See [references/cube-examples.md](references/cube-examples.md) for canonical standard cube, bridge cube, join direction examples, and refresh key variants.
 

package/dist/templates/skills/create-cubes/references/cube-examples.md

@@ -19,6 +19,10 @@
 name: hubspot_companies
 sql_table: "`revos_1737556292084.gold_hubspot_companies`"
 
+meta:
+  abConnectionId: conn_01HZX7K9P6QABCD
+  nameDimension: properties_name
+
 joins:
   companies_deals:
     sql: "${CUBE}.id = ${companies_deals}.company_id"
@@ -38,6 +42,10 @@ dimensions:
     type: string
     primary_key: true
 
+  properties_name:
+    sql: "${CUBE}.properties_name"
+    type: string
+
   airbyte_extracted_at:
     sql: "${CUBE}._airbyte_extracted_at"
     type: time
@@ -53,6 +61,8 @@ Notes:
 3. The join references `${companies_deals}` — the cube name of a bridge cube defined in `cubes/companies_deals.yml`.
 4. Only `_airbyte_extracted_at` is exposed from Airbyte metadata, as `airbyte_extracted_at`.
 5. `refresh_key.sql` uses the same fully qualified table name as `sql_table`.
+6. `meta.abConnectionId` ties this cube back to the Connection that ingests its raw data — get the id from `revos connections list --json`. Omit it for cubes built on purely local models with no upstream connection.
+7. `meta.nameDimension` is the **short** name of the dimension that represents this entity's human-readable label — here `properties_name`, referenced as `${CUBE}.properties_name`. The dimension must exist under `dimensions:`. The frontend reads `meta.nameDimension` to pick the "name" column when this cube is added as a table. Omit `nameDimension` for cubes that don't have a single natural label (bridges, fact tables, event logs). `meta` currently allows only `abConnectionId` and `nameDimension`; omit the whole `meta` block if neither applies.
 
 ---
 
@@ -63,6 +73,9 @@ name: companies_deals
 sql_table: "`revos_1737556292084.gold_companies_deals`"
 public: false
 
+meta:
+  abConnectionId: conn_01HZX7K9P6QABCD
+
 joins:
   hubspot_companies:
     relationship: many_to_one

package/dist/templates/skills/query-semantic-model/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: query-semantic-model
+description: >
+  Run a Cube.js query against the semantic model and show the result inline in chat as
+  an ASCII table and (where it makes sense) an ASCII bar chart. Use whenever the user
+  asks a business question that can be answered from the cubes — "how many orders…",
+  "top N…", "revenue by…", "trend over time", "compare X to Y" — or explicitly asks to
+  "query the semantic model", "run a cube query", "show me a chart", "plot…", "graph…".
+  Discovers measures and dimensions via `revos cubes meta`, executes the query with
+  `revos cubes query`, and renders the results without leaving the chat.
+---
+
+# Query Semantic Model
+
+Answer business questions by querying the org's semantic model and rendering the result
+directly in the chat — no notebook, no UI hop. The CLI already exposes everything you
+need: `revos cubes meta` lists the available cubes / measures / dimensions, and
+`revos cubes query` runs a Cube.js query and returns the rows.
+
+This skill is the "last mile" after Bronze → Silver → Gold → Cubes have been built and
+applied. It turns the semantic model into something you can actually look at.
+
+---
+
+## Step 1: Discover what's queryable
+
+Before guessing member names, list what the org's semantic model actually exposes:
+
+```bash
+revos cubes meta --json
+```
+
+The response carries an array of cubes, each with `measures`, `dimensions`, `segments`,
+and a `name`. Cube members are addressed as `<CubeName>.<member>` — for example
+`gold_order_items_enriched.count` or `gold_order_items_enriched.order_date`.
+
+Pick the cube and members that match the user's question. If the question can't be
+answered from the available members, say so — don't invent member names.
+
+### Map the join graph from the local cube files
+
+`revos cubes meta` tells you which members exist; the local `cubes/` folder tells you
+**how cubes are connected**. Read every `*.yml` file in `cubes/` and pull out each
+cube's `joins:` block — that's how the user-defined part of the semantic model is
+wired up. Example:
+
+```yaml
+# cubes/gold_order_items_enriched.yml
+spec:
+  definition:
+    name: gold_order_items_enriched
+    joins:
+      gold_users_with_order_stats:
+        relationship: many_to_one
+        sql: "${CUBE}.user_id = ${gold_users_with_order_stats}.user_id"
+      gold_product_performance:
+        relationship: many_to_one
+        sql: "${CUBE}.product_id = ${gold_product_performance}.product_id"
+```
+
+From this you can compute, for any pair of cubes, how many distinct join paths exist
+between them. That's what lets you pick the right path in Step 2 instead of letting
+Cube.js guess one for you.
+
+**Caveat — system cubes are not in `cubes/`.** RevOS generates a handful of cubes
+server-side (scoring, segments, model overlays, pre-aggregation overlays). Those
+never appear as YAML in the project. The full member list is only visible through
+`revos cubes meta`. So:
+
+- Use the `cubes/` folder to **see the user-defined join graph**.
+- Use `revos cubes meta` to **see every member that can actually be queried**,
+  including system cubes.
+
+When the user's question touches a system cube (e.g. "show me users by segment",
+"top scoring entities"), the join graph from `cubes/` will be incomplete. Don't
+assume there's no path — list the meta and look for it there.
+
+---
+
+## Step 2: Build the query — and pin the join path when it matters
+
+A Cube.js query is a JSON object. The shapes you'll use most often:
+
+```json
+{ "measures": ["gold_order_items_enriched.count"] }
+```
+
+```json
+{
+  "measures": ["gold_order_items_enriched.count"],
+  "dimensions": ["gold_order_items_enriched.traffic_source"],
+  "order": { "gold_order_items_enriched.count": "desc" },
+  "limit": 10
+}
+```
+
+Time series (the chart-friendliest shape):
+
+```json
+{
+  "measures": ["gold_order_items_enriched.revenue"],
+  "timeDimensions": [
+    {
+      "dimension": "gold_order_items_enriched.order_date",
+      "granularity": "month",
+      "dateRange": "last 12 months"
+    }
+  ]
+}
+```
+
+Rules of thumb:
+
+- One measure + one dimension → bar chart by category.
+- One measure + one `timeDimensions` with `granularity` → bar chart over time.
+- Multiple measures or multiple dimensions → render as an ASCII table only; don't try
+  to draw a chart.
+- Always cap with `limit` (default 20) so a stray query can't return a million rows.
+
+### Join paths — and how to pin them with a hint
+
+Cube.js infers the join path from the cubes that appear in `measures` /
+`dimensions` / `filters`. **When more than one path connects them, Cube.js picks
+one for you — and the answer changes depending on which.** This is the single
+biggest source of "the number looks wrong" bugs in a semantic-model query.
+
+You spell the path out by prefixing the member with the cubes you want Cube.js to
+walk through, dot-separated. The last segment is the actual member; everything
+before it is the join hint. Examples:
+
+```text
+# no hint — Cube.js picks a path
+gold_users_with_order_stats.lifetime_revenue
+
+# hint: reach lifetime_revenue via the fact spine, then the users mart
+gold_order_items_enriched.gold_users_with_order_stats.lifetime_revenue
+```
+
+The hint syntax works the same on measures, dimensions, and filter members.
+
+**When you need a hint (red flags):**
+
+1. Two cubes in the query are connected by **more than one path** in `cubes/`.
+   Common shape: a fact spine joins to two dimension cubes, and one of the dimension
+   cubes _also_ joins to the other (e.g. orders → users, orders → products,
+   products → users via `last_purchaser_id`). Without a hint, Cube.js may pick the
+   non-obvious path and quietly double- or under-count.
+2. The user's question implicitly names the path ("revenue **per order item** by
+   user country" vs "revenue **per user** by user country") — different grains,
+   different paths, different numbers.
+3. Counts come back smaller than the smallest cube would allow, or larger than the
+   largest fact would allow. That's a sign Cube.js fanned out through the wrong
+   join.
+4. The cube has a many-to-many relationship in the chain. Always pin it.
+5. You added a measure and the number changed dramatically (more than ~10%) without
+   the dimension set changing — Cube.js probably re-routed the join.
+
+**Worked example — same question, two answers.**
+
+Cubes (from `cubes/`):
+
+```text
+gold_order_items_enriched  ──many_to_one──▶  gold_users_with_order_stats
+gold_order_items_enriched  ──many_to_one──▶  gold_product_performance
+gold_product_performance   ──many_to_one──▶  gold_users_with_order_stats   (last_purchaser_id)
+```
+
+Question: "Total revenue by user country."
+
+```json
+// Path A — order items → users directly (CORRECT for per-item revenue)
+{
+  "measures": ["gold_order_items_enriched.revenue"],
+  "dimensions": [
+    "gold_order_items_enriched.gold_users_with_order_stats.country"
+  ]
+}
+```
+
+```json
+// Path B — order items → product → last_purchaser (WRONG: revenue gets
+// attributed to the last buyer's country, not the actual buyer's)
+{
+  "measures": ["gold_order_items_enriched.revenue"],
+  "dimensions": [
+    "gold_order_items_enriched.gold_product_performance.gold_users_with_order_stats.country"
+  ]
+}
+```
+
+The two queries return wildly different numbers. Always state which path you used
+and **why** in the explanation underneath the chart so the user can spot a wrong
+choice.
+
+**Worked example — filter via a specific path.**
+
+```json
+{
+  "measures": ["gold_order_items_enriched.revenue"],
+  "dimensions": ["gold_order_items_enriched.traffic_source"],
+  "filters": [
+    {
+      "member": "gold_order_items_enriched.gold_users_with_order_stats.country",
+      "operator": "equals",
+      "values": ["DE"]
+    }
+  ]
+}
+```
+
+**Rules for choosing a path:**
+
+- Default to the **shortest** path that goes through the **fact spine** the
+  question is naturally grained on (revenue per order → spine =
+  `gold_order_items_enriched`; users with X → spine = `gold_users_with_order_stats`).
+- Never silently take the alternate path. If two paths are plausible, ask the user
+  which grain they meant before running the query.
+- If `revos cubes meta` returns a member name that already contains dots (e.g.
+  `cubeA.cubeB.foo`), that **is** the qualified form — paste it through verbatim,
+  don't strip the prefix.
+
+---
+
+## Step 3: Run the query
+
+```bash
+revos cubes query --query '<INLINE_JSON>' --json
+```
+
+For anything longer than a one-liner, write the JSON to a temp file and pass it with
+`@`:
+
+```bash
+cat > /tmp/q.json <<'EOF'
+{
+  "measures": ["gold_order_items_enriched.revenue"],
+  "timeDimensions": [
+    {
+      "dimension": "gold_order_items_enriched.order_date",
+      "granularity": "month",
+      "dateRange": "last 12 months"
+    }
+  ]
+}
+EOF
+revos cubes query --query @/tmp/q.json --json
+```
+
+The response is the raw Cube.js payload — `data` is the array of rows, each row is a
+flat object keyed by the same member names used in the query.
+
+If the API returns an error, surface the message verbatim. Common causes: a member
+name typo (re-check `revos cubes meta`), a cube that hasn't been applied yet
+(`revos status` / `revos apply`), or a `dateRange` against a column that isn't a time
+dimension.
+
+---
+
+## Step 4: Render the result in chat
+
+Print **two** blocks in the assistant's reply, both as fenced code so they render
+monospaced:
+
+### 4a. ASCII table — always
+
+Show every returned row. Right-align numeric columns, left-align everything else.
+Format numbers with thousands separators; round to 2 decimals when not integral.
+Truncate long string values to 32 chars with a trailing `…`.
+
+```
+traffic_source       count
+─────────────────  ───────
+Search             142,318
+Organic             88,204
+Email               41,907
+Facebook            22,015
+Display              9,471
+```
+
+### 4b. ASCII bar chart — when the shape allows
+
+If the query returned exactly one measure plus exactly one dimension (categorical or
+time), draw a horizontal bar chart underneath the table. Scale bars to a width of
+**40 characters** based on the largest value in the result set; use the `█` block
+character for filled cells and a single trailing space.
+
+```
+Search        ████████████████████████████████████████  142,318
+Organic       ████████████████████████▊                  88,204
+Email         ███████████▊                               41,907
+Facebook      ██████▏                                    22,015
+Display       ██▋                                         9,471
+```
+
+Time-series example (oldest → newest, top-to-bottom):
+
+```
+2025-06  ███████████▊                                   €  41,200
+2025-07  █████████████████▏                             €  59,800
+2025-08  ████████████████████▋                          €  72,400
+…
+```
+
+Skip the chart (table only) when:
+
+- The result set is empty.
+- The query has 2+ measures, 2+ dimensions, or a single scalar value (no dimension).
+- All measure values are zero or null.
+
+For a single scalar answer (one row, one column), just say the number in prose
+followed by the one-line table — no chart.
+
+---
+
+## Step 5: Explain the result briefly
+
+After the rendered output, add 1–3 short sentences in plain English: what was
+measured, the highest / lowest bucket, and any obvious anomaly (e.g. a missing month,
+a single category dominating the total). Keep it to facts that are visible in the
+table — don't speculate about causes.
+
+If the user is likely to want to drill in, suggest **one** concrete follow-up query
+they can ask for next ("Want the same broken down by country?"). Don't list more than
+one — keep the chat tight.
+
+---
+
+## Rules
+
+- Never hardcode cube or member names. Always confirm them via `revos cubes meta`
+  before composing the query.
+- Before composing a multi-cube query, scan the `joins:` blocks in `cubes/*.yml`. If
+  the cubes you need are connected by more than one path, **pick one explicitly with
+  a dotted join hint** instead of letting Cube.js guess.
+- Remember that system cubes (scoring, segments, model overlays) live only in
+  `revos cubes meta`, not in `cubes/`. Their joins aren't visible in the YAML —
+  only in the meta output.
+- Always render the table; render the chart only when the data shape supports it.
+- Keep `limit` set (default 20). For "top N" questions, set `limit` to N and add
+  `order` on the measure.
+- Quote query JSON safely on the shell — prefer a temp file with `@/tmp/q.json` over
+  a long inline string with embedded quotes.
+- Don't write the query result to disk or invoke a Python plotter — this skill is
+  in-chat only. For static PNG visualizations of the cube graph itself, use
+  `visualize-semantic-model`.
+- If `revos cubes meta` returns no cubes, stop and tell the user to run `revos apply`
+  first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revos/cli",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "RevOS CLI for managing RevOS platform resources",
   "license": "MIT",
   "type": "module",