strata-cli 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31a0327b1b8df2f7a982ece6c882cf019322cdf6e649b8cafdf035132424a705
-  data.tar.gz: 16dbe764a144c7098574900d54fdad599727a65dbfc82fef531b6f63a59e39a7
+  metadata.gz: 4995c9ab5a77b99effe743f6518204ffe8c2417e06f2f3acac57efe5f82cd041
+  data.tar.gz: 89c9a32ddf48ac1e4e68a92aa0f6f8acf6f37fbc9267a0134fddc3a34a859ed0
 SHA512:
-  metadata.gz: 2fa33f77c3082a06a9a7e3e52cbeebd5b12ed4195b621011380ed2c39d124f3ebcd28b1962f8cf1565a999e101c8df7db15ea864dafed4d778211272a5c3f250
-  data.tar.gz: b1b1250691596a599af3b3193220242fe36f50eb4c7cab83eaac18d3a59795979b4b861c11799a65588e6a077594b2ac396e45a54c4aa216421aaf6846896146
+  metadata.gz: ca85facb30bebc4b5ec05ca79b15e3e94434fa10122400baadab6b923700fa4117b39b5cc06fddb1ccbf791ee1d772d755e1618159a5957d761ac1851ead083f
+  data.tar.gz: 07e20501e723d426b03044996bd2a20748e4bd322fa71e43f6c193be8d0516a49672e0ed7acd94f81a451cc99c0c8b48b087b02af8f334b10e50157518df520e

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.1.10] - 2026-05-22
+
+### Added
+
+- **Agent mode (`--agent`)**: Structured JSON output for automation and agent workflows on read-only commands (`datasource tables`, `datasource meta`, `version`, and others). Interactive `create` flows return machine-readable errors with stable codes when agent mode is requested.
+- **Audit field validation**: Model audit checks allowed field keys, expression shape (string shortcut or mapping with `sql`), and `format` types (string shortcuts and hash forms).
+- **Audit import resolution**: Model checks resolve YAML imports via `YamlImportResolver` before validating table and relationship definitions.
+
+### Changed
+
+- **AGENTS.md template**: Updated project init template with semantic-model authoring guidance and `--agent` command usage.
+
 ## [0.1.9] - 2026-05-13
 
 ### Added

data/README.md

@@ -25,6 +25,30 @@ gem install strata-cli
 
 > 💡 **Tip:** Run `strata COMMAND --help` for detailed help, options, and examples on any command. The CLI help system provides comprehensive documentation for each command.
 
+## Agent mode (`--agent`)
+
+Pass `--agent` on any command for structured JSON output and no interactive prompts (where the command supports it).
+
+**Supported examples:**
+
+```bash
+strata datasource list --agent
+strata datasource tables my_db --agent
+strata datasource meta my_db orders --agent
+strata table list --agent
+strata audit all --agent
+strata deploy --yes --agent
+```
+
+**Not supported** — these commands are interactive generators; write YAML directly instead:
+
+```bash
+strata create table [TABLE_PATH]      # → models/tbl.*.yml
+strata create relation RELATION_PATH  # → models/rel.*.yml
+```
+
+Use `strata datasource meta DS_KEY TABLE_NAME --agent` for column metadata when authoring table models.
+
 <details>
 <summary><strong>Project Management</strong></summary>
 
@@ -127,7 +151,7 @@ strata datasource exec my_db -f queries/analysis.sql
 <summary><strong>Model Creation</strong></summary>
 
 ### `strata create table [TABLE_PATH]`
-Create a semantic table model from a datasource table.
+Create a semantic table model from a datasource table. **Not available with `--agent`** — write `models/tbl.*.yml` directly or use `strata datasource meta` for schema metadata.
 
 **Options:** `-d, --datasource DS_KEY`
 
@@ -142,7 +166,7 @@ strata create table contact/dse.call_center_d  # With schema
 **Process:** Checks table existence → Fetches metadata → AI suggests fields → Interactive editor → Generates model file
 
 ### `strata create relation RELATION_PATH`
-Create a relation (join) definition file.
+Create a relation (join) definition file. **Not available with `--agent`** — write `models/rel.*.yml` directly.
 
 **Options:** `-d, --datasource DS_KEY`
 

data/lib/strata/cli/agent_mode.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "agent_output"
+
+module Strata
+  module CLI
+    module AgentMode
+      def self.included(base)
+        base.class_option :agent, type: :boolean, default: false,
+          desc: "Agent mode: structured output, no interactive prompts"
+      end
+
+      def agent_mode?
+        value = options[:agent]
+        value = options["agent"] if value.nil?
+        value == true
+      end
+
+      def reject_agent_mode!(message, code: "agent_mode_unsupported")
+        return unless agent_mode?
+
+        AgentOutput.emit_error(message, code: code)
+      end
+    end
+  end
+end

data/lib/strata/cli/agent_output.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Strata
+  module CLI
+    module AgentOutput
+      module_function
+
+      def emit_json(data)
+        $stdout.puts(JSON.generate(data))
+      end
+
+      def emit_error(message, code: "agent_mode_unsupported", **metadata)
+        payload = {error: message, code: code}.merge(metadata)
+        warn(JSON.generate(payload))
+        exit(1)
+      end
+    end
+  end
+end

data/lib/strata/cli/generators/templates/AGENTS.md

@@ -1,136 +1,505 @@
 # Strata Semantic Model Project
 
-This is a **Strata** semantic model project. It defines the dimensions, measures, and relationships that the Strata BI platform exposes to end users for querying and reporting.
+You are authoring a **semantic model** — version-controlled YAML in this repo (`models/tbl.*.yml`, `models/rel.*.yml`, datasources). That is not one-off SQL, warehouse ETL, or a standalone script.
 
-## Project Structure
+| Term | Meaning in Strata |
+|------|-------------------|
+| **Semantic model** | What you edit in git — tables, fields, relationships, migrations |
+| **Semantic layer** | What exists on the server **after deploy** — the governed dimensions, measures, and joins users query |
 
+After **`strata deploy`**, this project’s model becomes (or updates) the **semantic layer** on the Strata server for that branch. The **Strata web app** charts and reports run against that layer, not against raw warehouse tables.
+
+## What this model powers (end-to-end)
+
+| Stage | What happens |
+|-------|----------------|
+| **You (agent + human)** | Edit the **semantic model** in `models/`; run `strata audit` |
+| **Human** | `strata deploy` publishes the model to the **Strata server** (per git branch) |
+| **Strata server** | Builds join universes, plans queries, runs SQL against datasources |
+| **Strata web app** | Analysts query the deployed **semantic layer** — charting, reporting, filters, exploration by field **name** |
+
+Field and table **names**, joins, and measure definitions affect **live dashboards and saved reports**, not only CLI or git. Breaking naming, duplicates, or joins can break production content after deploy. YAML is consumed by deploy on the server — it is **not** ad-hoc warehouse SQL run in isolation.
+
+Read this file end-to-end before creating or editing `models/**/*.yml`. Do not mirror warehouse DDL or ad-hoc SQL style; follow the contracts below.
+
+**Do not infer Strata behavior from warehouse SQL or generic BI tools.** Rules in this file are authoritative. Use the [official documentation index](#official-documentation) only when you need depth beyond what is inlined here.
+
+## Critical rules
+
+These are non-negotiable. Violations break deploy, query planning, or production reports.
+
+1. **Every field `name` is unique project-wide** — one name = one dimension or measure entity across all `tbl.*.yml` files. Strata has no `table.field` namespaces; bracket references like `[Total Revenue]` resolve by name alone.
+2. **`many_to_many` join cardinality is not supported.** Use a junction/bridge table with two relationships (`one_to_many` + `many_to_one`) instead.
+3. **Measures on unrelated detail facts must have distinct names** — e.g. `Store Gross Sales`, `Catalog Gross Sales`, not one `Gross Sales` on three channel facts. See [Naming conventions](#naming-conventions).
+4. **Dimensions may share names** when the business role is the same; Strata picks among tables at query time. **Measures do not combine that way** — duplicate measure names attach more SQL to the same measure entity (double-count risk).
+5. **Cross-fact totals use compound measures or blending** — not the same measure name on multiple facts. See [Combined metrics across facts](#combined-metrics-across-facts).
+
+## Unsupported or impossible requirements
+
+**If the user asks for something Strata does not support, say so clearly and do not edit `models/**/*.yml` to approximate it.** A broken or misleading semantic model is worse than no change.
+
+### Before writing YAML
+
+1. **Classify the request:** supported in Strata · supported with a different pattern · unsupported · unknown.
+2. **If unsupported or unknown:** explain the limitation, why a workaround would fail (deploy, double-count, invalid cardinality, invented keys), and offer **compliant alternatives** if any exist.
+3. **Wait for the user to choose** a supported approach (or to change the requirement) before proposing file changes.
+4. **Never ship “best effort” YAML** that you expect `audit` or deploy to reject, or that violates [Critical rules](#critical-rules) — fix the design in conversation first.
+
+### What to tell the user
+
+Use plain language, for example:
+
+- “Strata does not support X. Doing Y in YAML would not work because …”
+- “Supported alternative: … (trade-off: …)”
+- “I’m not sure Strata supports X; I won’t change the model until we confirm — see [official documentation](#official-documentation) or your Strata admin.”
+
+### Do not do these when blocked
+
+- Invent YAML keys or properties not in Strata’s schema (`custom_join`, `blend_measures`, etc.).
+- Use duplicate measure names, fake dimensions, or `many_to_many` joins as workarounds.
+- Paste full ad-hoc report SQL into `expression.sql` and call it a semantic model.
+- Rename or migrate entities to “make” an unsupported shape fit.
+- Silently implement something that only works in raw warehouse SQL, not in Strata’s planner.
+
+### Common unsupported asks → response pattern
+
+| User ask | Why it fails | Compliant direction (if any) |
+|----------|--------------|------------------------------|
+| `many_to_many` join between two tables | Not supported | Junction table + two `rel` entries |
+| One measure name on store + catalog + web facts | One measure entity, double-count risk | Distinct measures + [compound measure](#combined-metrics-across-facts) |
+| “Combine metrics by reusing the same name” | Not how Strata merges facts | Compound measure or blending on shared dimensions |
+| Cross-datasource compound measure | Same datasource required | Model per datasource or separate metrics |
+| Datasource swap migration | Not supported | Rename datasource; human migration plan |
+| Snapshot-style metric on a flow fact without `snapshot_date` | Wrong measure type | Normal additive measure, or proper snapshot table setup |
+| Requirement needs engine feature you cannot verify | Risk of invalid model | Stop; cite docs or ask human — do not guess |
+
+When `strata audit all --agent` reports errors you cannot resolve within Strata’s rules, **stop and report the errors to the user** — do not keep patching YAML until the model drifts further from a valid design.
+
+## Order of operations for agents
+
+Follow this sequence. Do not skip steps or reorder deploy before audit.
+
+| Step | Who | Action |
+|------|-----|--------|
+| 1 | Agent | `strata datasource list --agent` → `tables` → `meta` (discovery) |
+| 2 | Agent | `strata table list --agent` (existing models, if any) |
+| 3 | Agent | Classify tables; check request is [supported](#unsupported-or-impossible-requirements); propose field names and joins (or explain why not) |
+| 4 | Human | Approve proposal (required before any file writes) |
+| 5 | Agent | Write `models/**/*.yml` (and `migrations/*.yml` if renaming — see [Renames and swaps](#renames-swaps-and-production-branch)) |
+| 6 | Agent | `strata audit all --agent` — **required after every model change** |
+| 7 | Human | `strata deploy` on the intended git branch (deploy runs audits again) |
+
+**Agents must not run:** `strata deploy`, `strata datasource add`, interactive `strata create table` / `strata create relation` / `strata create migration`, or writing secrets into `.strata`.
+
+**Branches:** Model on feature branches; deploy to the matching Strata server branch for staging. Production deploys typically use `production_branch` in `project.yml` (default `main`). Renames and swaps that affect production query names should happen on the production branch — see [Renames and swaps](#renames-swaps-and-production-branch).
+
+## How the semantic layer maps to the warehouse
+
+| Concept | In your YAML | Not the same as |
+|--------|----------------|-----------------|
+| Table users query | `name` in `tbl.*.yml` | `physical_name` (warehouse table) |
+| Column in a table | `expression.sql` on each field | Bare column string or `physical_name.column` |
+| Join endpoints | `left` / `right` (logical table names) | Table names inside join `sql` |
+| Join condition | `sql` using `left.` and `right.` | `store_sales.col = date_dim.col` |
+| Second FK to same dimension | New logical `tbl` (role-playing) + join to that name | Two `rel` entries with same `left` + `right` |
+
+## Deploy contracts (required on every change)
+
+Every `tbl` field and every `rel` join must satisfy **all** of these before deploy will succeed:
+
+1. **Field `expression`** is a non-empty SQL string shortcut (`expression: order_id`, `expression: sum(amount)`) or a mapping with non-empty `sql`. Use the mapping form when you need `lookup`, `primary_key`, or `array`.
+2. **Join `sql` uses only `left.` and `right.`** — column names from field definitions on those tables. Never warehouse prefixes (`orders.`, `date_dim.`, `store_sales.`).
+3. **At most one join per logical table pair** in a branch. If a fact has two FKs to the same physical dimension (e.g. sold date and ship date both → `date_dim`), create **separate logical tables** (role-playing dimensions) and join to each distinct `name`.
+4. **`left` / `right` in rel files match `name` in `tbl.*.yml` exactly** (same spelling and casing as the table model).
+
+Run `strata audit all --agent` after edits; a human runs `strata deploy`.
+
+## CLI for agents
+
+Append `--agent` to every `strata` command (structured output, no prompts):
+
+```bash
+strata datasource list --agent
+strata datasource tables MY_DS --agent
+strata datasource meta MY_DS TABLE_NAME --agent
+strata table list --agent
+strata audit all --agent
 ```
-project.yml          # Project config (server URL, project ID, production branch)
-datasources.yml      # Data warehouse connection config (no credentials)
-.strata              # Local credentials and API keys — gitignored, never commit
-models/              # Semantic model definitions
-  tbl.*.yml          # Table models (dimensions + measures)
-  rel.*.yml          # Relationship/join definitions
-tests/               # Model tests
+
+**Do not run:** `strata create table`, `strata create relation` (interactive generators). Write `models/tbl.*.yml` and `models/rel.*.yml` directly instead.
+
+If multiple datasources exist, pass `DS_KEY` on `tables` and `meta`.
+
+## Datasources — human-in-the-loop (secrets)
+
+If the CLI returns `no_datasources`, ask the user to run `strata datasource add [ADAPTER]` in a terminal. Do not create `datasources.yml` entries or fill `.strata` credentials yourself.
+
+## Human-in-the-loop before file writes
+
+Do **not** silently bulk-write model files. Before any `models/**/*.yml` change:
+
+0. **If the request is unsupported** — follow [Unsupported or impossible requirements](#unsupported-or-impossible-requirements); do not proceed to file writes until the user picks a supported approach.
+1. **Describe intent** — tables, fields, joins, and role-playing tables if needed (e.g. separate **Catalog Ship Date** when catalog sales has both sold-date and ship-date FKs).
+2. **Explain semantic impact** — which **dimension** names are intentionally shared vs which **measure** names stay **distinct per fact**; new join paths; any proposed **compound measures** (including **which host table** defines dimensionality); any **migrations** (renames/swaps) and whether work is on **production branch**; which logical tables are created vs updated.
+3. **Wait for explicit approval**, then write files and run `strata audit all --agent`.
+
+## Workflow
+
+Same steps as [Order of operations for agents](#order-of-operations-for-agents). In the proposal (step 3–4), include:
+
+- Table classification: **fact**, **dimension**, or **aggregate/summary**
+- **Unique measure name per unrelated detail fact**; shared dimension names only where the role matches
+- `tbl.*.yml` and `rel.*.yml` drafts that satisfy [Deploy contracts](#deploy-contracts-required-on-every-change) and naming rules below
+
+---
+
+## Table models — `models/tbl.<name>.yml`
+
+```yaml
+datasource: "<datasource_key_or_name>"
+name: "<logical_name>"              # Required — used in rel left/right and queries
+physical_name: "<warehouse_table>"  # Required — actual table in the database
+cost: 10
+
+fields:
+  - type: dimension
+    name: "Order ID"
+    data_type: bigint
+    expression:
+      sql: order_id                 # Column or expression fragment for this table
+      lookup: true                  # Typical for filterable dimensions
+      primary_key: true             # Optional — business/surrogate key
+
+  - type: measure
+    name: "Store Revenue"           # Unique per fact — not reused on other fact tables
+    data_type: decimal
+    expression:
+      sql: sum(ss_sales_price)      # Aggregation required for measures
 ```
 
-## CLI Reference
+**Field rules**
 
-Use the `strata` CLI to manage this project. All commands should be run from the project root.
+- `data_type`: `string`, `integer`, `bigint`, `decimal`, `date`, `date_time`, `boolean` (map from `normalized_data_type` in `datasource meta`).
+- `expression` keys: `sql` (required), `lookup`, `primary_key`, `array` (optional booleans).
+- Optional: `description`, `grains` (date/time), `format`, `synonyms`, `imports` of other tbl files.
 
-### Inspect
+**Date/time grains** (optional):
 
-```bash
-strata table list                          # List all defined semantic tables
-strata datasource list                     # List configured datasources
-strata datasource tables [DS_KEY]          # Browse physical tables in a datasource
-strata datasource meta DS_KEY TABLE_NAME   # Show columns for a physical table
+```yaml
+grains: [day, week, month, quarter, year]
 ```
 
-### Create
+---
 
-```bash
-strata create table [TABLE_PATH]           # AI-assisted semantic table creation
-# TABLE_PATH examples:
-#   orders                    → models/tbl.orders.yml
-#   sales/orders              → models/sales/tbl.orders.yml
-#   dw.fact_orders            → models/tbl.dw.fact_orders.yml (schema-prefixed)
+## Relationship models — `models/rel.<name>.yml`
+
+```yaml
+datasource: "<datasource_key_or_name>"
 
-strata create relation RELATION_NAME       # Create a join definition (rel.*.yml)
+orders_to_customers:
+  left: "Orders"                    # Must match tbl name — many side for many_to_one
+  right: "Customers"                # Must match tbl name — one side
+  sql: "left.customer_id = right.id"
+  cardinality: many_to_one
 ```
 
-`strata create table` fetches column metadata from the datasource, generates field definitions via AI, then opens an interactive editor to review and confirm before writing the YAML file.
+**Join rules**
 
-### Validate & Deploy
+- YAML `left` / `right`: logical table `name` values from `tbl.*.yml`.
+- `sql`: equality using **`left.<column>`** and **`right.<column>`** only — use the same column names as in each table’s field `expression.sql`.
+- `cardinality`: `many_to_one`, `one_to_many`, or `one_to_one` (as appropriate).
+- Optional: `join: inner` (default) or `left` / `right`.
 
-```bash
-strata audit all                           # Run all validation checks
-strata audit syntax                        # Validate YAML syntax only
-strata audit models                        # Validate model structure and references
-strata audit connections                   # Test all datasource connections
-
-strata deploy                              # Deploy to Strata server
-strata deploy -e production                # Deploy to a specific environment
-strata deploy status                       # Check current deployment status
+### Role-playing dimensions (multiple FKs to one physical table)
+
+When one fact table has **more than one foreign key** to the same physical dimension (common with `date_dim`: sold date, ship date, etc.), you need **one logical table per role**, each with its own join:
+
+| Wrong | Right |
+|-------|--------|
+| Two rel entries: `Catalog Sales` → `Date` (sold) and `Catalog Sales` → `Date` (ship) | `Catalog Sales` → `Date` (sold) and `Catalog Sales` → `Catalog Ship Date` (ship) |
+| Single `tbl.date.yml` reused for both roles without planning | Add `tbl.catalog_ship_date.yml` with `name: Catalog Ship Date`, same `physical_name: date_dim`, fields aligned to date role |
+
+Example pattern:
+
+```yaml
+# tbl — two logical tables, one physical date_dim
+# tbl.date.yml          → name: Date
+# tbl.catalog_ship_date.yml → name: Catalog Ship Date, physical_name: date_dim
+
+# rel — distinct right table per FK
+catalog_sales_sold_date:
+  left: "Catalog Sales"
+  right: "Date"
+  sql: "left.cs_sold_date_sk = right.d_date_sk"
+  cardinality: many_to_one
+
+catalog_sales_ship_date:
+  left: "Catalog Sales"
+  right: "Catalog Ship Date"
+  sql: "left.cs_ship_date_sk = right.d_date_sk"
+  cardinality: many_to_one
+```
+
+Before adding rel entries, list each fact’s FKs and confirm **no duplicate `(left, right)` pairs**. If ship and sold both target `Date`, add a role-playing tbl first.
+
+---
+
+## Naming conventions
+
+### Dimensions (global — reuse when the role is the same)
+
+- **Dimension names are global** across the project — same name on multiple tables = same concept; Strata picks the best table at query time.
+- **Reuse consistent names** for shared dimensions (e.g. "Customer ID", "Date") where the role is the same.
+- **Prefix role-specific dimensions** when the same physical column means different things (e.g. "Catalog Ship Date" vs "Date").
+- **Prefix ambiguous attributes** on dimension tables (e.g. "Item Color" not "Color" on an item dimension).
+
+### Measures (unique — do not treat like dimensions)
+
+- **Project-wide uniqueness:** every measure `name` must be unique across the entire semantic layer (same rule as dimensions). There is only one `Semantic::Field` per name per branch; deploy reuses it when the same name appears in another `tbl.*.yml`.
+- **Default:** one measure name per **unrelated detail fact**. Example (wrong): `Gross Sales` on `store_sales`, `catalog_sales`, and `web_sales`. Example (right): `Store Gross Sales Amount`, `Catalog Gross Sales Amount`, `Web Gross Sales Amount`.
+- **One measure name = one measure entity.** Putting the same name on another fact table adds that table’s SQL to the **same** measure — it does **not** create a second metric and can cause **double counting** or ambiguous routing.
+- **Exception — aggregate/summary tables only:** reusing a measure name is appropriate when the second table is an **alternate physical representation** of the **same** metric (rollup / pre-aggregate), routed via table **`cost`** and/or **`partitions`** — not when modeling three separate channel facts. Do **not** put the same additive flow measure on both a detail fact and a rollup fact without that routing design.
+- **Similar warehouse column names do not imply one shared measure.** `ss_sales_price` and `cs_ext_sales_price` are different facts unless you have explicit rollup routing as above.
+- **Prefix or qualify by fact/table** (`Store …`, `Catalog …`, `Web …`) or use distinct business names (`order_revenue` vs `subscription_revenue`).
+- **Do not “fix” duplicate measure names with rename migrations** — use distinct names or a [compound measure](#combined-metrics-across-facts) instead.
+
+---
+
+## Multi-fact warehouses (star schema)
+
+Typical warehouses (e.g. TPC-DS on Athena) have **many fact tables** and shared dimensions. Before naming fields:
+
+1. **Inventory tables** — label each as fact, dimension, or aggregate/summary (pre-aggregated rollups).
+2. **One grain per fact** — e.g. `store_sales` = store channel transactions; do not model the same additive flow metric on both a **detail** fact and a **rollup** fact unless the rollup is explicitly non-additive or routed via table `cost` / `partitions` (see advanced links below).
+3. **Do not copy a synthetic dimension onto every fact** (e.g. "Sales Channel" on store, catalog, and web facts) to justify reusing one measure name — that does **not** fix measure uniqueness or double-count risk. Put channel only where that fact’s grain truly includes channel.
+
+---
+
+## Combined metrics across facts
+
+| Wrong | Right |
+|-------|--------|
+| Same measure name on `store_sales`, `catalog_sales`, `web_sales` | Distinct measure per fact |
+| Expect Strata to auto-sum identical names | Explicit **compound measure** (or blending via shared **dimensions**, not duplicate measure names) |
+
+To report a **total across channels/facts**, define separate measures per fact, then optionally one compound measure:
+
+```yaml
+# On one table (or where the compound is defined), same datasource:
+- type: measure
+  name: Total Gross Sales
+  data_type: decimal
+  expression:
+    sql: ([Store Gross Sales Amount] + [Catalog Gross Sales Amount] + [Web Gross Sales Amount])
 ```
 
-## Semantic Model Files
+Bracket names must match deployed measure names exactly. Compound measures are resolved at query time; all referenced measures must be in the **same datasource** and reachable in a valid universe. No circular references (`A` → `B` → `A`).
+
+### Host table and dimensionality
+
+Define compound measures on the **`tbl.*.yml` whose universe should govern the metric**:
+
+- Which **dimensions** can group the compound measure
+- How **automatic data blending** applies when referenced measures live on different tables in the same datasource
+
+If referenced measures are not joinable in **one universe** from that host table, query planning fails. Propose the host table with the human reviewer (e.g. compound on **Store Sales** exposes store-centric join paths; compound on a shared dimension table exposes different dimensions).
+
+**Use calculations (compound measures), not shared measure names** across unrelated facts.
+
+**Automatic data blending** merges results on shared **dimensions** (often via `extended_blend_group`) — not by reusing the same measure name on multiple fact tables. See [extended blending](https://strata.do/developer-docs/developer-guide/semantic-model/expressions/extended-blending) and the [glossary](https://strata.do/developer-docs/developer-guide/getting-started/glossary).
 
-### Table model — `models/tbl.<name>.yml`
+---
+
+## Snapshot measures
+
+**Use for** point-in-time **state** — inventory on hand, account balances, membership counts at period boundaries. **Not for** additive flows over time (revenue, units sold) — use normal measures with `sum(...)`.
+
+**Requirements:**
+
+1. Table sets `snapshot_date: <Date dimension name>` (dimension on same table or unambiguous in the table’s universe).
+2. Measure sets `snapshot: ending` (value at end of period) or `snapshot: beginning` (value at start).
 
 ```yaml
-datasource: "<datasource_key_or_name>"   # Required
-name: "<logical_name>"                   # Required — unique within datasource
-physical_name: "<db_table_name>"         # Required — physical table in the warehouse
-cost: 10                                 # Lower = preferred when multiple tables can answer a query
-
-# Optional
-description: ""
-snapshot_date: "<dimension_name>"        # For snapshot/inventory tables only
-tags: []
-imports:                                 # Inherit fields from other YAML files
-  - "../shared/common_fields.yml"
+name: Inventory
+physical_name: inventory
+datasource: warehouse
+snapshot_date: Date
 
 fields:
-  - type: dimension           # "dimension" (categorical) or "measure" (numeric aggregate)
-    name: "Order ID"          # Required — human-friendly name; MUST be consistent across tables
-    description: ""
-    data_type: bigint         # See supported types below
-    expression: order_id      # SQL column name, or object form (see below)
-    synonyms: []              # 0–3 alternative names for AI search
+  - type: dimension
+    name: Date
+    data_type: date
+    expression:
+      sql: snapshot_date
 
   - type: measure
-    name: "Total Revenue"
-    data_type: decimal
-    expression: "sum(amount)" # Measures use SQL aggregation expressions
+    name: Ending Inventory
+    data_type: integer
+    snapshot: ending
+    expression:
+      sql: sum(quantity)
 ```
 
-**Supported `data_type` values:** `string`, `integer`, `bigint`, `decimal`, `date`, `date_time`, `boolean`
+When users group by a time period, the engine picks the last (`ending`) or first (`beginning`) snapshot in each bucket — not a sum of every row in the period.
+
+More detail: [snapshot measures](https://strata.do/developer-docs/developer-guide/semantic-model/fields/measures/snapshot)
+
+---
+
+## Inclusion measures
 
-No precision or scale — just the base type.
+**Problem:** medians and averages are wrong when the stored grain is finer than the statistic you need — e.g. `median(hours)` over `(day, account, title)` rows is not “median account hours per day.”
+
+**Pattern:** two-step aggregation — inner `expression.sql`, extra dimensions in `inclusions.dimensions`, outer `inclusions.aggregation`.
+
+**Use when:** medians, percentiles, or averages that need an **intermediate grain** (e.g. per account per day) before rolling up to the query grain.
 
-**Complex `expression` form:**
 ```yaml
-expression:
-  sql: my_column
-  primary_key: true    # optional
-  lookup: true         # optional
-  array: true          # optional
+- type: measure
+  name: Daily Median Account View Hours
+  data_type: decimal
+  inclusions:
+    filter: apply
+    aggregation: percentile_cont(0.5) WITHIN GROUP (ORDER BY @exp)
+    dimensions:
+      - Account ID
+  expression:
+    sql: sum(hours)
 ```
 
-**Date/time grains** (optional, for `date`/`date_time` fields):
+Inner: `sum(hours)` per `(day, account)`. Outer: median of those account totals per `day`.
+
+More detail: [inclusions](https://strata.do/developer-docs/developer-guide/advanced/inclusions)
+
+---
+
+## Exclusion measures
+
+**Two independent controls:**
+
+- **`exclusion_type`** — which dimensions may **group** the measure (`exclude`, `exclude_all_except`, `exclude_all`).
+- **`filter` on each exclusion entry** — how **filters** on those entities apply (`apply`, `ignore`, `only`).
+
+**Use when:** grand totals, metrics that must not break down by certain dimensions, or revenue that should ignore a dimension for grouping while still filtering normally.
+
 ```yaml
-grains: [day, week, month, quarter, year]
+- type: measure
+  name: Revenue Excluding Return Status
+  data_type: decimal
+  exclusion_type: exclude
+  exclusions:
+    - type: dimension
+      filter: apply
+      entities:
+        - Return Status
+  expression:
+    sql: sum(amount)
 ```
 
-### Relationship model — `models/rel.<name>.yml`
+`Return Status` will not appear in the grouping set for this measure even if the user adds it to the query; other dimensions still group normally.
+
+More detail: [exclusions](https://strata.do/developer-docs/developer-guide/advanced/exclusions)
+
+---
+
+## Common mistakes (anti-patterns)
+
+| Anti-pattern | Why it fails |
+|--------------|----------------|
+| `Gross Sales` on store + catalog + web facts | One measure entity, multiple fact SQLs → double-count / ambiguous routing |
+| "Sales Channel" dimension added to every fact | Does not replace unique measure names per fact |
+| Identical column labels in the warehouse → one measure name | Warehouse naming ≠ one Strata metric |
+| Assuming global dimension rules apply to measures | Dimensions are shared by name; measures are **not** |
+| Rename/swap on a feature branch without team coordination | Production saved queries still reference old names; branch may not match production entities |
+| Renaming to deduplicate measure names across facts | Use distinct names or compound measures — migrations are for intentional renames, not modeling fixes |
+
+---
+
+## Advanced features (quick reference)
+
+| Feature | Use when |
+|---------|----------|
+| [Compound measures](https://strata.do/developer-docs/developer-guide/semantic-model/fields/measures/compound) | Formula across named measures; host table sets dimensionality |
+| [Snapshot measures](https://strata.do/developer-docs/developer-guide/semantic-model/fields/measures/snapshot) | Period-boundary state (inventory, balances) — see [Snapshot measures](#snapshot-measures) |
+| [Inclusions](https://strata.do/developer-docs/developer-guide/advanced/inclusions) | Median/percentile/avg needing intermediate grain — see [Inclusion measures](#inclusion-measures) |
+| [Exclusions](https://strata.do/developer-docs/developer-guide/advanced/exclusions) | Control grouping and filters per dimension — see [Exclusion measures](#exclusion-measures) |
+| Table `cost` | Lower cost = preferred table when multiple tables can answer; use for rollup vs detail routing |
+| [Partitions](https://strata.do/developer-docs/developer-guide/advanced/partitions) | Table only has subset of data — `between` (date range) or `in_list`; planner routes when partition matches |
+| [Extended blending](https://strata.do/developer-docs/developer-guide/semantic-model/expressions/extended-blending) | Blend dimensions across tables in same datasource — not duplicate measure names |
+| [Imports](https://strata.do/developer-docs/developer-guide/semantic-model/imports) | Reuse field definitions across `tbl` files |
+
+---
+
+## Renames, swaps, and production branch
+
+Saved reports and dashboards reference field and table **names**. Renaming without a migration breaks production queryables.
+
+### Rename (`type: rename`, `hook: pre`)
+
+Runs **before** YAML is processed. Old name is rewritten to new name; deploy updates saved references.
 
 ```yaml
-datasource: "<datasource_key_or_name>"
+- type: rename
+  hook: pre
+  entity: measure
+  from: Old Revenue
+  to: Store Revenue
+```
+
+Supported entities: `dimension`, `measure`, `table`, `datasource`.
 
-order_customer:                          # Relationship name (any key)
-  left: "Orders"                         # Table on the "many" side
-  right: "Customers"                     # Table on the "one" side
-  sql: "orders.customer_id = customers.id"
-  cardinality: many_to_one               # one_to_one | one_to_many | many_to_one | many_to_many
+### Swap (`type: swap`, `hook: post`)
+
+Runs **after** all definitions load. Replaces references from entity A to entity B when **both** exist. Datasource swap is not supported.
+
+```yaml
+- type: swap
+  hook: post
+  entity: measure
+  from: Legacy Revenue
+  to: Store Revenue
 ```
 
-## Important Naming Rules
+### Production branch rule
 
-- **Dimension names are global.** When the same dimension name appears on multiple tables, Strata treats them as the same concept and picks the best table at query time.
-- **Use consistent names** for shared dimensions (e.g., "Customer ID", "Order Date") across all table models.
-- **Prefix ambiguous dimensions** from dimension tables: a `color` column on an `item_dim` table should be named `Item Color`, not `Color`.
+**Only rename or swap on `production_branch`** (in `project.yml`, usually `main`) when the change must align with production queryables. On other branches, production may still reference old names that do not exist on your branch.
 
-## Workflow
+Deploy **migration files and updated YAML in the same deployment**. Update `tbl.*.yml` references to match renames in the same change.
+
+**Agents:** propose migration YAML under `migrations/` and matching model edits; do **not** run interactive `strata create migration`. Flag renames for human review and confirm branch strategy.
+
+More detail: [migrations](https://strata.do/developer-docs/developer-guide/cli/migrations)
+
+---
+
+## Official documentation
 
-1. `strata datasource tables DS_KEY` — explore available physical tables
-2. `strata create table <path>` — generate and review a semantic model
-3. Edit the generated `tbl.*.yml` directly for fine-tuning
-4. `strata audit all` — validate before deploying
-5. `strata deploy` — push to Strata server
+**Primary:** this `AGENTS.md` — follow inline rules first.
 
-## Further Reading
+**Optional bulk load:** fetch https://strata.do/developer-docs/llms.txt when implementing a topic not fully covered here (complete Strata doc export for AI agents).
 
-For advanced semantic model concepts (partitioning, inclusions, exclusions, snapshot measures, display types, formatters, and more), refer to the Strata developer docs:
+**Curated links** (use for examples and edge cases after reading the matching section above):
 
-https://strata.do/developer-docs/developer-guide/semantic-model
+| Topic | URL |
+|-------|-----|
+| Semantic model overview | https://strata.do/developer-docs/developer-guide/semantic-model |
+| Core concepts | https://strata.do/developer-docs/developer-guide/getting-started/concepts |
+| Glossary | https://strata.do/developer-docs/developer-guide/getting-started/glossary |
+| Tables | https://strata.do/developer-docs/developer-guide/semantic-model/tables |
+| Fields | https://strata.do/developer-docs/developer-guide/semantic-model/fields |
+| Expressions (SQL) | https://strata.do/developer-docs/developer-guide/semantic-model/expressions/sql |
+| Relationships | https://strata.do/developer-docs/developer-guide/semantic-model/relationships/cardinality |
+| Imports | https://strata.do/developer-docs/developer-guide/semantic-model/imports |
+| Compound measures | https://strata.do/developer-docs/developer-guide/semantic-model/fields/measures/compound |
+| Snapshot measures | https://strata.do/developer-docs/developer-guide/semantic-model/fields/measures/snapshot |
+| Inclusions | https://strata.do/developer-docs/developer-guide/advanced/inclusions |
+| Exclusions | https://strata.do/developer-docs/developer-guide/advanced/exclusions |
+| Partitions | https://strata.do/developer-docs/developer-guide/advanced/partitions |
+| Cost optimization | https://strata.do/developer-docs/developer-guide/advanced/cost-optimization |
+| Extended blending | https://strata.do/developer-docs/developer-guide/semantic-model/expressions/extended-blending |
+| CLI audit | https://strata.do/developer-docs/developer-guide/cli/audit |
+| CLI deployment | https://strata.do/developer-docs/developer-guide/cli/deployment |
+| CLI migrations | https://strata.do/developer-docs/developer-guide/cli/migrations |
+| Star schema example | https://strata.do/developer-docs/developer-guide/examples/patterns/star-schema |
+| TPC-DS tutorial | https://strata.do/developer-docs/developer-guide/examples/tpcds-tutorial |
+| AI agents and Strata | https://strata.do/developer-docs/developer-guide/api/ai-agents |

data/lib/strata/cli/generators/templates/table.table_name.yml

@@ -70,8 +70,13 @@ fields:
   #   # Optional: UI rendering of the field  
   #   display_type: default|html|url|email|phone_number|image  
   #
-  #   # Optional: Specific formatting to be applied (will supercede display_type)
-  #   formatter: currency_usd|percent|thousands|millions|billions|(custom js function using numeraljs/momentjs)
+  #   # Optional: value formatting (shortcut string or hash with type)
+  #   format: currency:2
+  #   # format:
+  #   #   type: percent
+  #   #   precision: 1
+  #   # Types: number, currency, percent, date, datetime, html, javascript
+  #   # Shortcuts: number:2, number:2:abbreviate, currency:2, percent:1, date:short, datetime:iso
   #
   #   # Optional: disable listing individual elements (dimension only). Good to do that for 
   #   # high cardinality columns like account_id

data/lib/strata/cli/helpers/datasource_helper.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../agent_output"
+
 module Strata
   module CLI
     module DatasourceHelper
@@ -24,6 +26,19 @@ module Strata
         # 3. Check available datasources
         ds_keys = datasources.keys
 
+        if agent_mode?
+          if ds_keys.empty?
+            agent_emit_no_datasources!
+          elsif ds_keys.length == 1
+            return ds_keys.first
+          else
+            AgentOutput.emit_error(
+              "Datasource key required. Available: #{ds_keys.join(", ")}",
+              code: "datasource_key_required"
+            )
+          end
+        end
+
         if ds_keys.empty?
           say "No datasources configured. Run 'strata datasource add' first.", :red
           nil
@@ -134,6 +149,17 @@ module Strata
 
       private
 
+      def agent_emit_no_datasources!
+        AgentOutput.emit_error(
+          "No datasources configured in datasources.yml. Ask the user to add one interactively — " \
+          "do not create datasources or write credentials yourself (secrets belong in .strata via CLI prompts). " \
+          "User command: strata datasource add [ADAPTER] (e.g. strata datasource add postgres, strata datasource add duckdb).",
+          code: "no_datasources",
+          user_action_required: true,
+          suggested_command: "strata datasource add [ADAPTER]"
+        )
+      end
+
       def validate_datasource(ds_key)
         unless datasources[ds_key]
           say "Error: Datasource '#{ds_key}' not found in datasources.yml", :red

data/lib/strata/cli/main.rb

@@ -9,6 +9,7 @@ require_relative "sub_commands/table"
 require_relative "sub_commands/create"
 require_relative "sub_commands/audit"
 require_relative "helpers/description_helper"
+require_relative "agent_mode"
 require_relative "output"
 
 module Strata
@@ -16,6 +17,7 @@ module Strata
     class Main < Thor
       include Guard
       include Output
+      include AgentMode
       extend Helpers::DescriptionHelper
 
       def self.exit_on_failure?
@@ -60,11 +62,6 @@ module Strata
       desc "table", "Manage semantic tables"
       subcommand "table", SubCommands::Table
 
-      desc "tables", "List all semantic models in the project"
-      def tables
-        SubCommands::Table.start(["list"])
-      end
-
       desc "audit", "Audit project configuration and models"
       subcommand "audit", SubCommands::Audit
 

data/lib/strata/cli/sub_commands/audit.rb

@@ -5,6 +5,7 @@ require_relative "../terminal"
 require_relative "../credentials"
 require_relative "../output"
 require_relative "../helpers/datasource_helper"
+require_relative "../agent_mode"
 require_relative "../utils/yaml_import_resolver"
 require_relative "../utils/import_manager"
 require "yaml"
@@ -19,11 +20,20 @@ module Strata
         include Terminal
         include Output
         include DatasourceHelper
+        include AgentMode
 
         REQUIRED_KEYS_FOR_TABLE_MODEL = %w[name physical_name fields datasource].freeze
         REQUIRED_KEYS_FOR_RELATIONSHIP_MODEL = ["datasource"].freeze
         REQUIRED_KEYS_FOR_RELATIONSHIP_DEFINITION = %w[left right sql cardinality].freeze
         RELATIONSHIP_CARDINALITIES = %w[one_to_one one_to_many many_to_one many_to_many].freeze
+        VALID_FORMAT_TYPES = %w[raw number currency percent date datetime html javascript].freeze
+        ALLOWED_FIELD_KEYS = %w[
+          type name description hidden grains data_type display_type format
+          secure disable_listing value_list_size snapshot exclusion_type
+          exclusions inclusions extended_blend_group synonyms expression
+        ].freeze
+        ALLOWED_EXPRESSION_KEYS = %w[sql array lookup primary_key].freeze
+        EXPRESSION_BOOLEAN_KEYS = %w[array lookup primary_key].freeze
 
         # Set default command so `strata audit` still works as `strata audit all`
         default_command :all
@@ -99,8 +109,8 @@ module Strata
         def audit_models
           failures = []
           Dir.glob("models/**/*.yml").each do |file|
-            audit_model_file(file, failures)
             audit_imports(file, failures)
+            audit_model_file(file, failures)
           end
           failures
         end
@@ -109,17 +119,21 @@ module Strata
           content = YAML.safe_load_file(file, permitted_classes: [Date, Time], aliases: true) || {}
           return unless content.is_a?(Hash)
 
-          validate_structure(content, file, failures)
-
           case model_type(file)
           when :table
-            validate_table_model(content, file, failures)
+            resolved = Utils::YamlImportResolver.resolve(file, Dir.pwd)
+            return unless resolved.is_a?(Hash)
+
+            validate_structure(resolved, file, failures)
+            validate_table_model(resolved, file, failures)
           when :relationship
+            validate_structure(content, file, failures)
             validate_relationship_model(content, file, failures)
           end
-        rescue
-          # Ignore errors here, they are handled in audit_yaml_syntax if needed
-          # or simply skipped if the file is unreadable
+        rescue Strata::ImportError => e
+          failures << {file: file, message: e.message}
+        rescue Psych::SyntaxError
+          # Handled by audit_yaml_syntax when run
         end
 
         def model_type(file)
@@ -140,7 +154,7 @@ module Strata
         def validate_table_model(content, file, failures)
           validate_required_keys(content, file, REQUIRED_KEYS_FOR_TABLE_MODEL, failures)
           validate_datasource_reference(content, file, failures)
-          validate_table_fields(content["fields"], file, failures) if content.key?("fields")
+          validate_table_fields(content["fields"], file, failures)
         end
 
         def validate_relationship_model(content, file, failures)
@@ -172,10 +186,119 @@ module Strata
             return
           end
 
+          if fields.empty?
+            failures << {file: file, message: "'fields' must not be empty"}
+            return
+          end
+
           fields.each_with_index do |field, idx|
             unless field.is_a?(Hash) && field.key?("name")
               failures << {file: file, message: "Field at index #{idx} missing 'name'"}
+              next
+            end
+
+            validate_field_definition(field, file, idx, failures)
+          end
+        end
+
+        def validate_field_definition(field, file, idx, failures)
+          field_name = field["name"] || "index #{idx}"
+
+          unknown_keys = field.keys.map(&:to_s) - ALLOWED_FIELD_KEYS
+          if unknown_keys.any?
+            failures << {
+              file: file,
+              message: "Field '#{field_name}' has unknown #{(unknown_keys.size == 1) ? "key" : "keys"}: #{unknown_keys.sort.join(", ")}"
+            }
+          end
+
+          validate_field_expression(field_name, field["expression"], file, failures)
+
+          return unless field.key?("format")
+
+          validate_field_format(field_name, field["format"], file, failures)
+        end
+
+        def validate_field_expression(field_name, expression, file, failures)
+          if expression.nil?
+            failures << {file: file, message: "Field '#{field_name}' missing required 'expression'"}
+            return
+          end
+
+          if expression.is_a?(String)
+            if expression.strip.empty?
+              failures << {file: file, message: "Field '#{field_name}' expression must not be empty"}
+            end
+            return
+          end
+
+          unless expression.is_a?(Hash)
+            type_name = expression.class.name
+            failures << {
+              file: file,
+              message: "Field '#{field_name}' expression must be a string shortcut or a mapping (got #{type_name})"
+            }
+            return
+          end
+
+          unknown_keys = expression.keys.map(&:to_s) - ALLOWED_EXPRESSION_KEYS
+          if unknown_keys.any?
+            failures << {
+              file: file,
+              message: "Field '#{field_name}' expression has unknown #{(unknown_keys.size == 1) ? "key" : "keys"}: " \
+                "#{unknown_keys.sort.join(", ")}"
+            }
+          end
+
+          sql = expression["sql"] || expression[:sql]
+          if sql.nil? || sql.to_s.strip.empty?
+            failures << {file: file, message: "Field '#{field_name}' expression must include non-empty 'sql'"}
+          end
+
+          EXPRESSION_BOOLEAN_KEYS.each do |key|
+            next unless expression.key?(key) || expression.key?(key.to_sym)
+
+            value = expression[key] || expression[key.to_sym]
+            next if value == true || value == false
+
+            failures << {
+              file: file,
+              message: "Field '#{field_name}' expression.#{key} must be true or false"
+            }
+          end
+        end
+
+        def validate_field_format(field_name, format_value, file, failures)
+          case format_value
+          when String
+            shortcut = format_value.strip
+            if shortcut.empty?
+              failures << {file: file, message: "Field '#{field_name}' format must not be empty"}
+              return
+            end
+
+            type = shortcut.split(":", 2).first
+            unless VALID_FORMAT_TYPES.include?(type)
+              failures << {
+                file: file,
+                message: "Field '#{field_name}' format shortcut has invalid type '#{type}' (expected one of: #{VALID_FORMAT_TYPES.join(", ")})"
+              }
+            end
+          when Hash
+            type = format_value["type"] || format_value[:type]
+            if type.nil? || type.to_s.strip.empty?
+              failures << {file: file, message: "Field '#{field_name}' format hash must include type"}
+            elsif !VALID_FORMAT_TYPES.include?(type.to_s)
+              failures << {
+                file: file,
+                message: "Field '#{field_name}' format hash has invalid type '#{type}' (expected one of: #{VALID_FORMAT_TYPES.join(", ")})"
+              }
             end
+          else
+            failures << {
+              file: file,
+              message: "Field '#{field_name}' format must be a string shortcut or a hash with type"
+            }
           end
         end
 
@@ -254,13 +377,9 @@ module Strata
             imported_content = YAML.safe_load_file(resolved_path, permitted_classes: [Date, Time], aliases: true) || {}
 
             unless imported_content.is_a?(Hash)
-              failures << {file: file, message: "Imported file '#{import_path}' does not contain valid YAML hash"}
+              failures << {file: file, message: "Imported file '#{import_path}' does not contain valid YAML"}
               next
             end
-
-            if model_type(file) == :table && imported_content["fields"]
-              validate_table_fields(imported_content["fields"], file, failures)
-            end
           rescue Strata::InvalidImportPathError => e
             failures << {file: file, message: e.message}
           rescue Strata::MissingImportError

data/lib/strata/cli/sub_commands/branch.rb

@@ -6,6 +6,7 @@ require_relative "../api/client"
 require_relative "../utils/git"
 require "time"
 require "tty-prompt"
+require_relative "../agent_mode"
 
 module Strata
   module CLI
@@ -13,6 +14,7 @@ module Strata
       class Branch < Thor
         include Guard
         include Output
+        include AgentMode
 
         default_command :list
         class_option :environment, aliases: ["e"], type: :string

data/lib/strata/cli/sub_commands/create.rb

@@ -10,6 +10,7 @@ require_relative "../ai/services/table_generator"
 require_relative "../helpers/prompts"
 require_relative "../helpers/description_helper"
 require_relative "../helpers/command_context"
+require_relative "../agent_mode"
 require "tty-prompt"
 require "tty-spinner"
 require "yaml"
@@ -25,6 +26,7 @@ module Strata
         include Prompts
         include Thor::Actions
         include Helpers::CommandContext
+        include AgentMode
         extend Helpers::DescriptionHelper
 
         desc "table TABLE_PATH", "Create a semantic table model"
@@ -34,6 +36,11 @@ module Strata
           desc: "Datasource key from datasources.yml"
 
         def table(table_path = nil)
+          reject_agent_mode!(
+            "Agent mode: write models/tbl.*.yml directly. Use: strata datasource meta DS_KEY TABLE_NAME --agent",
+            code: "use_yaml_files"
+          )
+
           return unless datasource_key
 
           # If table_path provided, skip search for speed
@@ -51,6 +58,11 @@ module Strata
           desc: "Datasource key from datasources.yml"
 
         def relation(relation_path)
+          reject_agent_mode!(
+            "Agent mode: write models/rel.*.yml directly.",
+            code: "use_yaml_files"
+          )
+
           return unless datasource_key
 
           create_relation_file(relation_path)

data/lib/strata/cli/sub_commands/datasource.rb

@@ -8,6 +8,7 @@ require_relative "../utils/git"
 require "tty-prompt"
 require_relative "../helpers/datasource_helper"
 require_relative "../helpers/description_helper"
+require_relative "../agent_mode"
 
 module Strata
   module CLI
@@ -18,6 +19,7 @@ module Strata
         include Terminal
         include Output
         include DatasourceHelper
+        include AgentMode
         extend Helpers::DescriptionHelper
 
         desc "adapters", "Lists supported data warehouse adapters"
@@ -52,7 +54,7 @@ module Strata
             return
           end
 
-          names = ds.keys.map { "#{it} => #{ds[it]["name"]}" }
+          names = ds.keys.map { "Key: #{it} | Name: #{ds[it]["name"]}" }
           out = "\n  #{names.join("\n  ")}"
           say out, :magenta
         end
@@ -184,11 +186,17 @@ module Strata
           ds_key = resolve_datasource(ds_key, prompt: prompt)
           return unless ds_key
 
-          say "\nListing #{ds_key} tables...\n\n", :yellow
           adapter = create_adapter(ds_key)
           tables = adapter.tables(**options)
           tables = tables.select { it =~ /#{options[:pattern]}/ } if options[:pattern]
 
+          if agent_mode?
+            AgentOutput.emit_json({datasource: ds_key, tables: tables})
+            return
+          end
+
+          say "\nListing #{ds_key} tables...\n\n", :yellow
+
           if tables.empty?
             say "No tables found.", :yellow
             return
@@ -205,10 +213,18 @@ module Strata
         method_option :catalog, aliases: "c", type: :string, desc: "Change the catalog from the configured one."
         method_option :schema, aliases: "s", type: :string, desc: "Change the schema from the configured one."
         def meta(ds_key, table_name)
-          say "\n● Schema for table: #{table_name} (#{ds_key}):\n", :yellow
           adapter = create_adapter(ds_key)
           md = adapter.metadata(table_name, **options.transform_keys(&:to_sym))
 
+          if agent_mode?
+            columns = md.columns.map do |column|
+              column.to_h.merge(normalized_data_type: column.normalized_data_type)
+            end
+            AgentOutput.emit_json({datasource: ds_key, table: table_name, columns: columns})
+            return
+          end
+
+          say "\n● Schema for table: #{table_name} (#{ds_key}):\n", :yellow
           headings = md.columns.first.to_h.keys
           rows = md.columns.map(&:to_h).map(&:values)
 

data/lib/strata/cli/sub_commands/deploy.rb

@@ -5,6 +5,7 @@ require_relative "../terminal"
 require_relative "../output"
 require_relative "../helpers/project_helper"
 require_relative "../helpers/description_helper"
+require_relative "../agent_mode"
 require_relative "../api/client"
 require_relative "../credentials"
 require_relative "../utils"
@@ -23,6 +24,7 @@ module Strata
         include Guard
         include Terminal
         include Output
+        include AgentMode
         extend Helpers::DescriptionHelper
 
         default_command :deploy

data/lib/strata/cli/sub_commands/project.rb

@@ -4,6 +4,7 @@ require_relative "../guard"
 require_relative "../terminal"
 require_relative "../output"
 require_relative "../helpers/project_helper"
+require_relative "../agent_mode"
 require_relative "../api/client"
 require "yaml"
 
@@ -14,6 +15,7 @@ module Strata
         include Guard
         include Terminal
         include Output
+        include AgentMode
 
         desc "link PROJECT_ID", "Link local project to an existing project on the server"
         def link(project_id)

data/lib/strata/cli/sub_commands/table.rb

@@ -2,6 +2,7 @@
 
 require_relative "../helpers/prompts"
 require_relative "../helpers/command_context"
+require_relative "../agent_mode"
 require_relative "../output"
 
 module Strata
@@ -14,6 +15,7 @@ module Strata
         include Prompts
         include Thor::Actions
         include Helpers::CommandContext
+        include AgentMode
         extend Helpers::DescriptionHelper
 
         desc "list", "List all semantic models in the project"

data/lib/strata/cli/version.rb

@@ -2,6 +2,6 @@
 
 module Strata
   module CLI
-    VERSION = "0.1.9"
+    VERSION = "0.1.10"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strata-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Ajo Abraham
@@ -242,6 +242,8 @@ files:
 - Rakefile
 - exe/strata
 - lib/strata/cli.rb
+- lib/strata/cli/agent_mode.rb
+- lib/strata/cli/agent_output.rb
 - lib/strata/cli/ai/client.rb
 - lib/strata/cli/ai/configuration.rb
 - lib/strata/cli/ai/services/table_generator.rb