strata-cli 0.1.20 → 0.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28b84442e2989e729c2f9241c4af084eed8b346f62267d00c7bc27f3a4cb7d5d
-  data.tar.gz: b3e436e5055ea145a030bd88e27fb7b11ec1f6965886a65cb94aeee26ba34f5f
+  metadata.gz: 55ce87ef5e374c4b0a1c60a5e23081596108a353bc543272a7aa2b749fd56930
+  data.tar.gz: 27bc1dab19e8dbc6efb1256b25c36389a182157dad90bd9fdfd14f9c73f648af
 SHA512:
-  metadata.gz: 022cb33cdb574fd26548b9239ea39520e196f019a5f5d1808e84acf19e15f22a92d7acf550b70d729a799d4a389e48cd66950fa616809afbb96f569f87c00720
-  data.tar.gz: f3bd0b00b86ddae87a55262f15d49665606fde89211d3bd2fc5ec9ca33233b998253e5f949d170052a3c8d7ee210c5f6187ed38ed9603487cd5c218fdd9ed89b
+  metadata.gz: 9e9824b911b205b5876c1c104cfa2c187c7d768197b87ffda5bf3d891bfd2abc9140309b422c173fe8d964a9fa4939aa331bdc6e8412e25b0e6a37d172e4453e
+  data.tar.gz: 0bc343e01fac99afacc7bb5e3c188d530c7b7ceafa359c0c269d38c32e536b837bca2038b95ad2962672c5ebcc961eb7a972f72fee91abc5a3707c22ebf64a49

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 ## [Unreleased]
 
+## [0.1.22] - 2026-11-05
+
+### Fixed
+
+The local semantic audit added in 0.1.16 mirrors the server's deploy-time
+validations. Several of its checks rejected models the server accepts, which blocked
+`strata audit` -- and `strata deploy`, which runs it first.
+
+- **A table name reused in a second datasource**: the audit resolved a relationship's tables by name across the whole project, so two datasources declaring the same table collided and whichever file was read last won. A valid join in the other datasource failed with "is not in datasource ... (tables can only join within one datasource)", and the same join defined in both datasources failed as a duplicate. Table names are unique per datasource on the server, so both are now scoped to the relationship's own datasource. This is what hot-tier routing looks like, where one table is defined in a hot and a cold datasource.
+- **Datasource references that differ only in case**: `datasource: TPCDS` in a relationship file and `tpcds` in a table file resolved to different strings and compared as different datasources. An upper-case key in `datasources.yml` was also rejected outright as "not found", though the server resolves it. Both now match case-insensitively, as the server does.
+- **Measures written across lines**: the aggregate-function check was missing the server's `/m` flag, so any measure written as a YAML block scalar (`sql: |`) or spanning lines was reported as having no aggregation function.
+- **Quoted identifiers on backtick warehouses**: expressions were always parsed with ANSI double quotes, so on MySQL, BigQuery, ClickHouse and Databricks a backtick-quoted column read as no column at all and dimensions were rejected for not referencing one. The parser now takes the adapter's own identifier quote.
+- **`join` and `cardinality` casing**: `join: Inner` and `cardinality: Many_To_One` were rejected. The server downcases and strips both before validating, and defaults a missing `join` to `inner`.
+- **Explicitly empty keys**: `snapshot:`, `display_type:` and `join:` left blank were rejected; the server treats nil as absent.
+- **Tables with no fields**: `fields` was required and `fields: []` rejected, though the server accepts a table that declares none. It now warns instead.
+- **`.yaml` model files**: only `.yml` was ever read, so a `tbl.*.yaml` was reported as a stray file to delete, never validated, invisible to relationship checks, and left out of the deploy archive -- even though the server deploys `tbl.*.{yml,yaml}`.
+
+### Added
+
+The deployer silently swallows a number of mistakes: the deploy goes green and the
+model differs from the YAML. Those are the ones worth catching locally, so these are
+errors even though the server accepts them.
+
+- **Measure-only keys on a dimension**: `snapshot`, `exclusion_type`, `exclusions` and `inclusions` apply to measures only, but all four are columns on the shared `fields` table and the deployer writes them to a dimension untyped -- `snapshot: ending` stores `0`, which reads back as `beginning`, and shows up as `snapshot: 0` in field JSON. Reported once, naming the keys, instead of as several misleading enum errors.
+- **`exclusions` without `exclusion_type`**: the rules are stored, never validated and never applied, so the measure aggregates at the grain the rules existed to prevent; under row-level security the query then fails with an internal "Exclusion dim ids are not cached" error.
+- **Unknown table-level keys**: the deployer slices a `tbl` file down to the keys it reads, so anything else is dropped. In particular `snapshot_date:` -- which this project's own table template suggested until now -- deployed a table with no snapshot date at all.
+- **`lookup: "no"` and friends**: these land on boolean columns, and `ActiveModel::Type::Boolean` casts everything outside its `FALSE_VALUES` to **true**, so a quoted `"no"`, `"No"` or a bare `n` silently stores the opposite of what was written. Bare `no` is fine, so this is a one-character quoting difference that inverts join handling and is invisible in a diff. The error now says so.
+- **Table template**: `table.table_name.yml` suggested `snapshot_date:`, but the deployer reads `snapshot:`. Corrected in `AGENTS.md` in 0.1.18 and missed here.
+
+### Changed
+
+- **`strata audit connections` still fails on an unreachable warehouse; `strata audit all` now warns.** The server only checks that a datasource's config can build an adapter and never requires the warehouse to be reachable from this machine, so a warehouse behind a VPN or an IP allow-list no longer blocks a deploy that would have worked. Running `connections` is an explicit request to test them, so there it is still an error.
+
+## [0.1.21] - 2026-11-04
+
+### Added
+
+- **Default server URL**: commands fall back to `https://app.strata.do` when no `server:` is configured, so `strata deploy` no longer stops to prompt for one.
+- **`-s, --server URL` on `strata init`** (alongside the existing flag on `project sample`), written into `project.yml`. Other commands read it from there; use `-e ENVIRONMENT` with per-environment `server:` blocks to target more than one server.
+
+### Removed
+
+- **`strata init --source`**: it could never do what it claimed. The clone was gated on a `git_url` field the server does not return (the column is `git`), so the repository was never cloned, and the full project URL was written into `project.yml` as `server:`, breaking every later deploy. Its documented GitHub-URL example raised a `TypeError`. To work on an existing project, clone its repository and run `strata deploy`, or use `strata project link PROJECT_ID`. `-s` now means `--server`.
+
+### Changed
+
+- `strata init` requires `PROJECT_NAME`, and its `--api-key` is purely an optional convenience for scripted setups — browser sign-in on the first `strata deploy` is now the only interactive auth path.
+- `strata project sample` writes the chosen server to `project.yml` instead of `.strata`, where `project.yml` silently overrode it.
+
+### Fixed
+
+- **A datasource whose file lives where the server runs no longer fails the audit.** The sample project points DuckDB at `/data/tpcds.duckdb`, which ships inside the Strata image, so the connection could never be opened from a laptop and `strata deploy` refused to run. `strata audit` now reports such a connection as unchecked and names it, instead of failing — the server validates it for real when the model deploys. This replaces a hardcoded skip that disabled connection auditing entirely for one repository, and `strata datasource test` now explains the same situation when it fails.
+- A blank `server:` key in `project.yml` no longer wins the config merge and blank out the default.
+- Saving a server URL to `project.yml` rewrote every `server:` line, including the indented per-environment ones. It now only replaces the root key.
+- Documentation links point at `https://strata.do/docs/...` instead of the old `developer-docs` path.
+
 ## [0.1.20] - 2026-09-30
 
 ### Changed

data/README.md

@@ -52,22 +52,26 @@ Use `strata datasource meta DS_KEY TABLE_NAME --agent` for column metadata when
 <details>
 <summary><strong>Project Management</strong></summary>
 
-### `strata init [PROJECT_NAME]`
+### `strata init PROJECT_NAME`
 
-Initialize a new Strata project or clone from an existing repository.
+Initialize a new Strata project.
 
 **Options:**
 - `-d, --datasource ADAPTER` - Add datasource adapters (repeatable)
-- `-s, --source URL` - Clone existing project from URL
-- `-a, --api-key KEY` - API key (required with `--source`)
+- `-s, --server URL` - Server URL, written to `project.yml` (default `https://app.strata.do`)
+- `-a, --api-key KEY` - API key, for scripted setups (optional — the first deploy signs you in via browser)
 
 **Examples:**
 ```bash
 strata init my-project
 strata init my-project -d postgres -d snowflake
-strata init --source https://github.com/org/project.git --api-key YOUR_KEY
+strata init my-project --server http://localhost:8080
 ```
 
+To work on a project that already exists on the server, clone its repository — `project.yml`
+carries both the server URL and the project ID — then run `strata deploy`. Use
+`strata project link PROJECT_ID` to point an existing local project at a server project.
+
 ### `strata project link PROJECT_ID`
 
 Link local project to an existing project on the Strata server.
@@ -83,7 +87,7 @@ Clone the Strata TPC-DS sample project and set it up interactively. Prompts for
 
 **Options:**
 - `-a, --api-key KEY` - API key (optional — skips browser sign-in when paired with `--server`)
-- `-s, --server URL` - Server URL (optional — prompted if omitted)
+- `-s, --server URL` - Server URL (optional — prompted if omitted, default `https://app.strata.do`)
 
 **Examples:**
 ```bash
@@ -306,6 +310,19 @@ List all supported data warehouse adapters.
 
 ## Configuration
 
+### Server URL
+
+The server URL lives in `project.yml`. `strata init` and `strata project sample` accept
+`-s, --server URL` and write it there; every other command reads it, so the flag is set once:
+
+1. `server:` under the selected environment in `project.yml` (`-e ENVIRONMENT`)
+2. `server:` at the root of `project.yml`, then `.strata`
+3. `https://app.strata.do` — the default when nothing above is set
+
+To deploy to more than one server, give `project.yml` a block per environment and select it
+with `-e ENVIRONMENT` (see [Multi-Environment Configuration](#configuration)) rather than
+passing a URL per command.
+
 ### Project Configuration (`project.yml`)
 
 Main project configuration file:
@@ -328,10 +345,10 @@ project_id: 123  # Auto-populated after first deployment
 server: https://dev.strata.example.com
 
 staging:
-  server: https://staging.strata.com
+  server: https://staging.strata.do
 
 production:
-  server: https://app.strata.com
+  server: https://app.strata.do
 ```
 
 `.strata` — API keys per environment (**never committed**):
@@ -464,7 +481,7 @@ Run `strata ds auth my_bigquery` and give the service account JSON keyfile path:
 ## Security
 
 - ✅ Credentials stored in `.strata` with restrictive permissions (0600)
-- ✅ API keys never required on the command line — browser sign-in or the `.strata` file supplies them (optional `--api-key` flags exist on `init --source` and `project sample` for scripting)
+- ✅ API keys never required on the command line — browser sign-in or the `.strata` file supplies them (optional `--api-key` flags exist on `init` and `project sample` for scripting)
 - ✅ File paths validated to prevent path traversal attacks
 - ✅ Git commit hashes validated before use
 - ✅ YAML files loaded safely to prevent code execution

data/lib/strata/cli/configuration.rb

@@ -7,13 +7,21 @@ module Strata
     class Configuration
       STRATA_CONFIG_FILE = ".strata"
       PROJECT_CONFIG_FILE = "project.yml"
+      DEFAULT_SERVER = "https://app.strata.do"
 
       DEFAULT = {
         "api_key" => "",
-        "server" => "",
+        "server" => DEFAULT_SERVER,
         "log_level" => "info"
       }.freeze
 
+      # Normalizes a configured or user-supplied server URL, falling back to
+      # the hosted default when it is missing or blank.
+      def self.resolve_server(value)
+        value = DEFAULT_SERVER if value.nil? || value.to_s.strip.empty?
+        value.to_s.strip.delete_suffix("/")
+      end
+
       attr_reader :data
 
       def initialize
@@ -94,6 +102,8 @@ module Strata
         project_data = load_yaml_file(project_config_file_path)
 
         @data = DEFAULT.merge(strata_data).merge(project_data)
+        # project.yml ships a blank `server:` key, which would otherwise win the merge.
+        @data["server"] = DEFAULT_SERVER if @data["server"].to_s.strip.empty?
 
         @api_key = @data["api_key"]
         @server = @data["server"]

data/lib/strata/cli/descriptions/init.txt

@@ -1,19 +1,20 @@
-Initialize a new Strata project or clone from an existing repository.
+Initialize a new Strata project.
 
 Creates an AGENTS.md in the project so a coding agent (Claude Code, Codex, Cursor)
 can build the semantic model for you:
-https://strata.do/developer-docs/developer-guide/cli/building-your-model
+https://strata.do/docs/cli/building-your-model
 
-PROJECT_NAME is optional when using --source option. If provided, creates a new project
-with that name. If using --source, clones the existing project from the URL.
+PROJECT_NAME is required and becomes the project directory and uid.
 
 Options:
 
   -d, --datasource ADAPTER    Add one or more datasource adapters (repeatable)
 
-  -s, --source URL            URL of existing project to clone
+  -s, --server URL            Strata server URL, written to project.yml.
+                              Defaults to https://app.strata.do
 
-  -a, --api-key KEY           API key (required when using --source)
+  -a, --api-key KEY           API key, for scripted setups. Optional — the first
+                              `strata deploy` signs you in via the browser.
 
 Examples:
 
@@ -21,4 +22,4 @@ Examples:
 
   strata init my-project -d postgres -d snowflake
 
-  strata init --source https://github.com/org/project.git --api-key YOUR_KEY
+  strata init my-project --server http://localhost:8080

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

@@ -3,60 +3,23 @@
 require_relative "group"
 require_relative "datasource"
 require_relative "../helpers/project_helper"
-require_relative "../api/connection_error_handler"
-require_relative "../api/response_error_handler"
 require_relative "../output"
 require_relative "../utils/git"
 require_relative "../helpers/prompts"
-require "faraday"
-require "json"
-require "uri"
 
 module Strata
   module CLI
     module Generators
       class Project < Group
-        include API::ConnectionErrorHandler
-        include API::ResponseErrorHandler
-
-        argument :name, type: :string, required: false, desc: "The name of the project. Optional when using --source."
+        argument :name, type: :string, required: false, desc: "The name of the project."
         class_option :datasource, type: :string, repeatable: true
-        class_option :source, type: :string
+        class_option :server, type: :string
         class_option :api_key, type: :string
         class_option :verbose, type: :boolean, default: false, desc: "Show detailed init output (file-by-file actions)."
 
         desc "Generates a new Strata project."
 
-        def validate_options
-          if options.key?(:source)
-            unless options.key?(:api_key)
-              raise Strata::CommandError,
-                "API key is required when using --source option. Use --api-key option."
-            end
-          else
-            unless @name && !@name.to_s.strip.empty?
-              raise Strata::CommandError,
-                "PROJECT_NAME is required when not using --source option."
-            end
-          end
-        end
-
-        def fetch_and_clone_if_available
-          return unless options.key?(:source)
-
-          project_info = fetch_project_info
-          @project_id = project_info["id"]
-          @project_info = project_info
-
-          return unless project_info["git_url"] && !project_info["git_url"].empty?
-
-          @cloned_from_git = true
-          clone_project(project_info["git_url"])
-        end
-
         def create_project_structure
-          return if cloned_from_git?
-
           empty_directory uid unless existing_directory?
           empty_directory File.join(uid, "models")
           empty_directory File.join(uid, "tests")
@@ -67,30 +30,14 @@ module Strata
         end
 
         def create_project_file
-          return if cloned_from_git?
-
           template "project.yml", "#{uid}/project.yml"
         end
 
-        def persist_project_id_if_needed
-          # Persist project_id after project.yml exists (either from clone or creation)
-          return unless @project_id
-
-          project_yml_path = File.join(uid, "project.yml")
-          return unless File.exist?(project_yml_path)
-
-          persist_project_id_to_project_yml
-        end
-
         def create_agents_file
-          return if cloned_from_git?
-
           copy_file "AGENTS.md", "#{uid}/AGENTS.md"
         end
 
         def create_datasources_file
-          return if cloned_from_git?
-
           template "datasources.yml", "#{uid}/datasources.yml"
 
           return unless options.key?(:datasource)
@@ -103,8 +50,6 @@ module Strata
         end
 
         def initialize_git
-          return if cloned_from_git?
-
           inside uid do
             run "git init", verbose: false, capture: true
             create_file ".gitignore", ".strata\n"
@@ -112,7 +57,6 @@ module Strata
         end
 
         def setup_datasource
-          return if cloned_from_git?
           return if options.key?(:datasource)
           return if existing_directory?
 
@@ -129,8 +73,6 @@ module Strata
         end
 
         def initial_commit
-          return if cloned_from_git?
-
           inside uid do
             case Utils::Git.initial_commit("chore: initialize Strata project")
             when :committed
@@ -151,83 +93,18 @@ module Strata
 
         private
 
-        def cloned_from_git?
-          @cloned_from_git ||= false
-        end
-
         def existing_directory?
           File.directory?(name.to_s)
         end
 
-        def fetch_project_info
-          conn = Faraday.new(url: options[:source]) do |f|
-            f.request :authorization, "Bearer", options[:api_key]
-            f.response :json
-          end
-
-          response = with_connection_error_handling(options[:source]) do
-            conn.get
-          end
-
-          unless response.success?
-            raise Strata::CommandError,
-              response_error_message(
-                response,
-                default_message: "Failed to fetch project info from #{options[:source]}. Status: #{response.status}."
-              )
-          end
-
-          response.body
-        end
-
-        def clone_project(git_url)
-          Output.print_status(:clone, "Cloning project from #{git_url}", type: :success, context: self)
-          run "git clone #{git_url} #{uid}", verbose: false, capture: true
-
-          raise Strata::CommandError, "Failed to clone repository from #{git_url}" unless File.directory?(uid)
-
-          Output.print_status(:success, "Project cloned successfully", type: :success, context: self)
-        end
-
-        def persist_project_id_to_project_yml
-          return unless @project_id
-
-          project_yml_path = File.join(uid, "project.yml")
-          Helpers::ProjectHelper.persist_project_id_to_yml(@project_id, project_yml_path: project_yml_path)
-        end
-
         def uid
-          @uid ||= if options.key?(:source) && @project_info
-            @project_info["uid"] || options[:source].split("/").last
-          elsif existing_directory?
-            name.to_s
-          else
-            Utils.url_safe_str(name)
-          end
-        end
-
-        def name
-          # Use name from server if available (when using --source), otherwise use argument
-          return @project_info["name"] if options.key?(:source) && @project_info
-
-          @name
+          @uid ||= existing_directory? ? name.to_s : Utils.url_safe_str(name)
         end
 
-        def description
-          return @project_info["description"] if options.key?(:source) && @project_info
-
-          nil
-        end
-
-        def production_branch
-          if options.key?(:source) && @project_info && @project_info["production_branch"]
-            return @project_info["production_branch"]
-          end
-
-          "main"
+        # Written into project.yml so deploy/branch/cache just read it.
+        def server
+          @server ||= Configuration.resolve_server(options[:server])
         end
-
-        attr_reader :project_id
       end
     end
   end

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

@@ -312,7 +312,7 @@ If referenced measures are not joinable in **one universe** from that host table
 
 **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).
+**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/docs/semantic-model/extended-blending-groups) and the [glossary](https://strata.do/docs/getting-started/glossary).
 
 ---
 
@@ -348,7 +348,7 @@ fields:
 
 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)
+More detail: [snapshot measures](https://strata.do/docs/semantic-model/fields/measures/snapshot)
 
 ---
 
@@ -375,7 +375,7 @@ More detail: [snapshot measures](https://strata.do/developer-docs/developer-guid
 
 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)
+More detail: [inclusions](https://strata.do/docs/advanced/inclusions)
 
 ---
 
@@ -404,7 +404,7 @@ More detail: [inclusions](https://strata.do/developer-docs/developer-guide/advan
 
 `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)
+More detail: [exclusions](https://strata.do/docs/advanced/exclusions)
 
 ---
 
@@ -425,14 +425,14 @@ More detail: [exclusions](https://strata.do/developer-docs/developer-guide/advan
 
 | 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) |
+| [Compound measures](https://strata.do/docs/semantic-model/fields/measures/compound) | Formula across named measures; host table sets dimensionality |
+| [Snapshot measures](https://strata.do/docs/semantic-model/fields/measures/snapshot) | Period-boundary state (inventory, balances) — see [Snapshot measures](#snapshot-measures) |
+| [Inclusions](https://strata.do/docs/advanced/inclusions) | Median/percentile/avg needing intermediate grain — see [Inclusion measures](#inclusion-measures) |
+| [Exclusions](https://strata.do/docs/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 |
+| [Partitions](https://strata.do/docs/semantic-model/partitions) | Table only has subset of data — `between` (date range) or `in_list`; planner routes when partition matches |
+| [Extended blending](https://strata.do/docs/semantic-model/extended-blending-groups) | Blend dimensions across tables in same datasource — not duplicate measure names |
+| [Imports](https://strata.do/docs/semantic-model/imports) | Reuse field definitions across `tbl` files |
 
 ---
 
@@ -474,7 +474,7 @@ Deploy **migration files and updated YAML in the same deployment**. Update `tbl.
 
 **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)
+More detail: [migrations](https://strata.do/docs/cli/migrations)
 
 ---
 
@@ -482,30 +482,30 @@ More detail: [migrations](https://strata.do/developer-docs/developer-guide/cli/m
 
 **Primary:** this `AGENTS.md` — follow inline rules first.
 
-**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).
+**Optional bulk load:** fetch https://strata.do/docs/llms.txt when implementing a topic not fully covered here (complete Strata doc export for AI agents).
 
 **Curated links** (use for examples and edge cases after reading the matching section above):
 
 | 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 |
+| Semantic model overview | https://strata.do/docs/semantic-model |
+| Core concepts | https://strata.do/docs/getting-started/concepts |
+| Glossary | https://strata.do/docs/getting-started/glossary |
+| Tables | https://strata.do/docs/semantic-model/tables |
+| Fields | https://strata.do/docs/semantic-model/fields |
+| Expressions (SQL) | https://strata.do/docs/semantic-model/expressions/sql |
+| Relationships | https://strata.do/docs/semantic-model/relationships/cardinality |
+| Imports | https://strata.do/docs/semantic-model/imports |
+| Compound measures | https://strata.do/docs/semantic-model/fields/measures/compound |
+| Snapshot measures | https://strata.do/docs/semantic-model/fields/measures/snapshot |
+| Inclusions | https://strata.do/docs/advanced/inclusions |
+| Exclusions | https://strata.do/docs/advanced/exclusions |
+| Partitions | https://strata.do/docs/semantic-model/partitions |
+| Cost optimization | https://strata.do/docs/advanced/cost-optimization |
+| Extended blending | https://strata.do/docs/semantic-model/extended-blending-groups |
+| CLI audit | https://strata.do/docs/cli/audit |
+| CLI deployment | https://strata.do/docs/cli/deployment |
+| CLI migrations | https://strata.do/docs/cli/migrations |
+| Star schema example | https://strata.do/docs/examples/patterns/star-schema |
+| TPC-DS tutorial | https://strata.do/docs/examples/tpcds-tutorial |
+| AI agents and Strata | https://strata.do/docs/api/ai-agents |

data/lib/strata/cli/generators/templates/project.yml

@@ -10,7 +10,7 @@ uid: <%= uid %>
 description: Your projects description
 
 # Target Strata server (default environment, typically dev)
-server: <%= options[:source] %>
+server: <%= server %>
 
 # Alternatively, you can configure multiple environments (different Strata server instances).
 # Each environment represents a separate Strata cluster (dev, staging, production).
@@ -19,7 +19,7 @@ server: <%= options[:source] %>
 # dev:
 #   server: http://localhost:8080
 # prod:
-#   server: https://app.strata.com
+#   server: https://app.strata.do
 
 # Project ID will be automatically set after first deployment.
 # WARNING: Do not change this project_id. It links this project to the Strata server.

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

@@ -26,7 +26,7 @@ cost: 10
 # Optional: If this is a snapshot table like an inventory table, you can 
 # set the snapshot date dimension here. This will allow the creation of 
 # snapshot measures on this table.
-# snapshot_date: <snapshot dimension name>
+# snapshot: <snapshot dimension name>
 
 # Optional: Tag table for additional metadata.
 # tags:

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

@@ -79,6 +79,22 @@ module Strata
         # don't need special handling - no file lock issues
       end
 
+      # A file based datasource can name a path that only exists where the server runs:
+      # the sample project's /data/tpcds.duckdb ships inside the Strata image. There is
+      # nothing to open from here, so the CLI cannot verify the connection - the server
+      # does, when the model deploys. A remote URL is not this case; httpfs opens one
+      # from anywhere, so a broken URL should still be reported.
+      def local_file_missing?(config)
+        return false unless config.is_a?(Hash)
+
+        file = config["file"].to_s.strip
+        # No file key at all belongs to the adapter's own required param check, and
+        # :memory: connects without touching the disk.
+        return false if file.empty? || file.casecmp(":memory:").zero? || file.include?("://")
+
+        !File.exist?(file)
+      end
+
       def ensure_adapter_driver_gems!(adapter_sym)
         required = ADAPTER_DRIVER_GEMS.fetch(adapter_sym, [])
         return if required.empty?
@@ -137,8 +153,9 @@ module Strata
 
         normalized = value.to_s.downcase.strip
 
-        # Match by key first
-        return value if datasources.key?(normalized)
+        datasources.each_key do |key|
+          return key if key.to_s.downcase.strip == normalized
+        end
 
         # Match by name (case-insensitive)
         datasources.each do |key, config|

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

@@ -54,8 +54,9 @@ module Strata
           project_yml_content = File.read(project_yml_path)
 
           begin
-            if /^server:\s*.+$/m.match?(project_yml_content)
-              updated_content = project_yml_content.gsub(/^(\s*)server:\s*.+$/, "\\1server: #{server}")
+            # Root key only -- an indented `server:` belongs to a per-environment block.
+            if /^server:/.match?(project_yml_content)
+              updated_content = project_yml_content.sub(/^server:.*$/, "server: #{server}")
               File.write(project_yml_path, updated_content)
             else
               File.open(project_yml_path, "a") do |f|

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

@@ -5,7 +5,7 @@ module Strata
     module Prompts
       # Docs. This URL is printed by the CLI and baked into every shipped gem —
       # strata-docs has no redirects plugin, so renaming that page 404s old binaries.
-      DOCS_BUILD_MODEL_URL = "https://strata.do/developer-docs/developer-guide/cli/building-your-model"
+      DOCS_BUILD_MODEL_URL = "https://strata.do/docs/cli/building-your-model"
 
       # Shown after 'strata init' and 'strata datasource add'. %s is the agent hint.
       MSG_AGENTS_MD_PRESENT = "AGENTS.md in this project tells it Strata's rules."
@@ -76,7 +76,7 @@ module Strata
         (operation == "swap") ? "post (after deployment)" : "pre (before deployment)"
       end
 
-      # dir is the project root — 'strata init --source' clones repos without an AGENTS.md.
+      # dir is the project root — 'strata project sample' clones a repo that may lack an AGENTS.md.
       def build_model_next_steps(dir = ".")
         hint = File.exist?(File.join(dir, "AGENTS.md")) ? MSG_AGENTS_MD_PRESENT : MSG_AGENTS_MD_MISSING
         format(MSG_BUILD_MODEL_NEXT_STEPS, hint)