Edit/cleanup recent docs changes (#292)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: mtoy-googly-moogly

src/blog/2026-01-13-context-md-convention/index.malloynb

@@ -10,7 +10,7 @@ This is based on our experience. We're sharing it to start a conversation. We ho
 
 ## The Malloy Experience
 
-Starting from zero experience with LLMs we discovered that if you fill a conversation context with all information about the Malloy repository, the result is a context with very little room for exploration and problem solving. In our experience, the results of LLM assisted coding are much better when carefully feeding the LLM a context focused on the problem at hand. Over time we found there were particular areas of the code where it made sense to gather the information the LLM gleaned, and some guidance from a human who is very familiar with the code, into a context-unit which would be re-usable and shareable.
+Starting from zero experience with LLMs, we discovered that filling a conversation context with all information about the Malloy repository leaves very little room for exploration and problem solving. Results are much better when you carefully feed the LLM context focused on the problem at hand. Over time, we found it made sense to gather the information the LLM gleaned — along with guidance from a human familiar with the code — into reusable, shareable context units.
 
 As we review pull requests, we continue to update our contexts, and this is gradually making pull request reviews cleaner. If our scheme of `CONTEXT.md` maintenance were generally known and recognized by the LLMs used by contributors, it would make it easier for external contributors to make solid contributions to our repository.
 
@@ -22,11 +22,11 @@ We distribute `CONTEXT.md` files throughout the repository tree. Each file descr
 
   - Our main repository is a monorepo, with multiple sub-components (Compiler, Renderer, API, etc.) so
     a single context file doesn't make sense for these individual components.
-  - Keeps individual context files smaller, allows an LLM assisted activity to read the appropriate context
+  - Keeps individual context files smaller. Allows an LLM-assisted activity to read the appropriate context
     to finish a task without reading all documentation for the project. Scales well to larger projects.
   - Keeps the naming/location of these files LLM-agnostic
   - Humans and LLMs are always pair programming, so both humans and LLMs need to be able to
-    both review code changes, and update and maintain context files for the code.
+    review code changes and update and maintain context files for the code.
 
 In our repository it looks something like this:
 

src/blog/2026-02-25-persistence/index.malloynb

@@ -43,7 +43,7 @@ The `#@ persist` annotation is metadata, not a language keyword. It lives in Mal
 
 ### Inheritance
 
-Persistence flows through `extend`. If the base data is worth persisting, derived versions usually are too:
+Persistence flows through `extend`. When you extend a persistent source, the extension reads from the same pre-built table — it just adds computed fields on top:
 
 ```malloy
 #@ persist name=by_carrier
@@ -52,12 +52,12 @@ source: by_carrier is flights -> {
   aggregate: flight_count is count()
 }
 
-// Also persistent — inherits from by_carrier
+// Reads from the pre-built by_carrier table, adds a computed field
 source: enriched is by_carrier extend {
   dimension: upper_carrier is upper(carrier)
 }
 
-// Break the chain when you need to
+// Opt out: recomputes the query instead of using the pre-built table
 #@ -persist
 source: scratch is by_carrier extend { ... }
 ```
@@ -116,7 +116,7 @@ To verify it's working, compile a query without running it and check the SQL. Yo
 
 Many connections work with no configuration at all — if a connection name matches a registered database type, Malloy creates one with default settings. For persistence, the main thing you need to decide is where the manifest lives:
 
-- **Global config** (simplest): The CLI reads `~/.config/malloy/malloy-config.json` by default and writes the manifest next to it. Point VS Code's `malloy.globalConfigDirectory` at the same directory, and both tools share the same manifest. No flags needed.
+- **Global config** (simplest): The CLI reads `~/.config/malloy/malloy-config.json` by default and writes the manifest next to it. Point VS Code's `malloy.globalConfigDirectory` at the same directory, and both tools share the same manifest. No flags needed. If you're just getting started, this is the easiest path.
 
 - **Project config**: Put a `malloy-config.json` in your project root (it can be as minimal as `{}`) to anchor the manifest to your project. VS Code finds it automatically; the CLI needs `--config .`.
 
@@ -144,7 +144,7 @@ Because the manifest is optional, persistence supports very different experience
 
 **Partial manifest (incremental builds):** Some sources are pre-built, others expand inline. The compiler doesn't care which sources are in the manifest and which aren't. This lets a builder do incremental work — build what's missing, skip what's fresh.
 
-**Full manifest with `strict` mode (production):** When a manifest has `strict: true`, the compiler fails if any persistent source is *missing* from the manifest. This catches configuration errors — if a table should have been built but wasn't, you find out at compile time rather than by accidentally running an expensive query in production. The builder sets `strict` in the manifest file; an application can override it with `manifest.strict = false` if needed.
+**Full manifest with `strict` mode (production):** When a manifest has `strict: true`, the compiler fails if any persistent source is *missing* from the manifest. This catches configuration errors — if a table should have been built but wasn't, you find out at compile time rather than by accidentally running an expensive query in production. The builder sets `strict` in the manifest file; an application using the API can override this programmatically if needed.
 
 ## Building a Sophisticated Persistence Application
 

src/documentation/experiments/experiments.malloynb

@@ -1,11 +1,11 @@
 >>>markdown
 # Experimental Features
 
-Before releasing language features, we like to get a feel for how they work when used in programs.  We often find bugs or language problems.  We like when people use these features with the understanding that they might changed in their final form or never be released.  
+Before releasing language features, we like to get a feel for how they work when used in programs.  We often find bugs or language problems. We like when people use these features with the understanding that they might change in their final form or never be released.  
 
 We value feedback during the experimental phase.  Please make sure you let us know what you think.
 
-Below is a list of currently running experiements and how to turn them on.
+Below is a list of currently running experiments and how to turn them on.
 
 * `##! experimental.join_types` - [Additional Join Type](joins.malloynb)
 * `## renderer_next` - [New table and visualization Rendering](renderer.malloynb)

src/documentation/experiments/persistence.malloynb

@@ -35,15 +35,15 @@ source: by_origin is flights -> {
 }
 ```
 
-Persistence is inherited when you `extend` a persistent source. The child keeps the same table name unless you override it. Use `#@ -persist` to opt out:
+When you `extend` a persistent source, the extension still reads from the same pre-built table — the extension just adds computed fields on top. Use `#@ -persist` to opt out and force the underlying query to be recomputed instead:
 
 ```malloy
-// Inherits persistence from by_carrier
+// Reads from the pre-built by_carrier table, adds a computed field
 source: enriched is by_carrier extend {
   dimension: upper_carrier is upper(carrier)
 }
 
-// Opt out of persistence
+// Opt out: recomputes the query instead of using the pre-built table
 #@ -persist
 source: temporary is by_carrier extend { ... }
 ```
@@ -91,7 +91,7 @@ malloy-cli --config . build models/
 
 ### Building
 
-The builder compiles `.malloy` files, finds `#@ persist` sources, and creates the database tables:
+The builder compiles `.malloy` files (or all files in a directory), finds `#@ persist` sources, and creates the database tables:
 
 ```bash
 # Build all .malloy files in the current directory (recursive)
@@ -159,7 +159,7 @@ If VS Code and the builder are reading different config files, they'll have diff
 
 By default, if a `#@ persist` source is missing from the manifest (e.g., it hasn't been built yet), queries fall through to computing the result inline — the same as if no manifest existed. This is convenient during development but risky in production, where an unbuilt table might mean an unexpectedly expensive query.
 
-The builder creates manifests with `strict` mode enabled. When strict mode is on, a missing manifest entry for a `#@ persist` source causes an error instead of falling through. This catches configuration problems early — if a table should have been built but wasn't, you find out at compile time.
+The builder creates manifests with `strict` mode enabled by default. When strict mode is on, a missing manifest entry for a `#@ persist` source causes an error instead of falling through. This catches configuration problems early — if a table should have been built but wasn't, you find out at compile time.
 
 If you need to disable strict mode (e.g., during development when only some tables are built), you can edit `malloy-manifest.json` and set `"strict": false`. The builder will not overwrite this setting on subsequent builds.
 >>>markdown

src/documentation/language/connections.malloynb

@@ -17,7 +17,7 @@ There are currently two connection methods, `.table()` and `.sql()`.
 
 ## Table Connection Method
 
-The `.table()` connection method is used to reference a table or view in a database. It accepts a single string representing a table. The exact semantics of how that string is resolved into a table schema depend on the database and application. 
+The `.table()` connection method is used to reference a table or view in a database. It accepts a single string representing a table. The exact semantics of how that string is resolved depend on the database and application. 
 
 In the official Malloy connection implementations, the behavior is as follows:
 
@@ -31,7 +31,7 @@ In Databricks, the string passed to the `.table()` connection method can be a on
 
 ### DuckDB
 
-In DuckDB, the `.table()` method accepts the path (relative to the Malloy file) of CSV, JSON, or Parquet file containing the table data, e.g. `duckdb.table('data/users.csv')` or `duckdb.table('../../users.parquet')`. URLs to such files (or APIs) are also allowed: see [an example here](../patterns/apijson.malloynb).
+In DuckDB, the `.table()` method accepts the path (relative to the Malloy file) of a CSV, JSON, or Parquet file containing the table data, e.g. `duckdb.table('data/users.csv')` or `duckdb.table('../../users.parquet')`. URLs to such files (or APIs) are also allowed: see [an example here](../patterns/apijson.malloynb).
 
 ### Postgres
 

src/documentation/language/dialect/databricks.malloynb

@@ -44,7 +44,7 @@ source: orders is databricks.table('my_catalog.analytics.orders')
 
 ## Limitations
 
-- **`string_agg` ordering**: Databricks does not support `ORDER BY` inside `COLLECT_LIST`/`COLLECT_SET`, so `string_agg` and `string_agg_distinct` do not support the `order_by` modifier.
+- **`string_agg` ordering**: Databricks does not support ordering within aggregate collection functions, so `string_agg` and `string_agg_distinct` do not support the `order_by` modifier.
 - **`TIMESTAMP_NTZ`**: Databricks' `TIMESTAMP_NTZ` (timestamp without timezone) maps to `sql native` in Malloy. Use explicit casting to `timestamp` when needed.
 
 # Functions

src/documentation/language/dialect/mssql-via-duckdb.malloynb

@@ -34,7 +34,7 @@ and `setupSQL` ATTACHes to your SQL Server and sets the default catalog and sche
 ```
 
 The `setupSQL` runs once per session. The `USE` must include both catalog and
-schema (e.g., `mydb.dbo`) — `USE mydb` alone is not sufficient.
+schema (e.g., `mydb.dbo`) so that DuckDB can resolve unqualified table names. `USE mydb` alone sets only the catalog, leaving the schema ambiguous.
 
 See [Configuration](../../setup/config.malloynb) for more details on `malloy-config.json`.
 

src/documentation/malloy_cli/index.malloynb

@@ -1,7 +1,7 @@
 >>>markdown
 # About the Malloy CLI
 
-The [Malloy CLI](https://github.com/malloydata/malloy-cli) is a command-line interface for running `.malloysql` and `.malloy` files. It can be used to automate transformations, build simple pipelines, or even integrate compiled Malloy SQL into other applications.
+The [Malloy CLI](https://github.com/malloydata/malloy-cli) is a command-line interface for running `.malloysql` and `.malloy` files and building persistent tables. It can be used to automate transformations, build simple pipelines, or even integrate compiled Malloy SQL into other applications.
 
 ## Installation
 
@@ -25,7 +25,7 @@ If a connection name in your model matches a registered database type (DuckDB, B
 
 ## Usage
 
-The main commands of the CLI are `run` and `compile` — `run` executes queries and returns results, whereas `compile` returns SQL for a query or many queries.
+The main commands of the CLI are `run`, `compile`, and `build` — `run` executes queries and returns results, `compile` returns SQL for a query or many queries, and `build` creates persistent tables from `#@ persist` sources.
 
 The CLI has detailed usage information for each command. You can get general help with `malloy-cli --help`, and command-specific help and options with `malloy-cli {command} --help`
 

src/documentation/setup/cli.malloynb

@@ -1,5 +1,5 @@
 >>>markdown
-# Installing the CLI
+# CLI Setup
 
 The [Malloy CLI](https://github.com/malloydata/malloy-cli) is a command-line interface for running `.malloysql` and `.malloy` files. Use it to automate transformations, build pipelines, or compile Malloy queries to SQL.
 

src/documentation/setup/config.malloynb

@@ -146,14 +146,14 @@ All connection types support a `setupSQL` parameter. This is a multi-line text f
 
 Each statement must end with `;` at the end of a line. Statements can span multiple lines. Only one statement-ending `;` is allowed per line.
 
-**Legal** — each statement ends with `;` on its own line:
+**Correct** — each statement ends with `;` on its own line:
 ```
 SET search_path TO analytics;
 CREATE TEMP TABLE foo
   AS SELECT 1;
 ```
 
-**Illegal** — two statements on the same line:
+**Incorrect** — two statements on the same line:
 ```
 SET search_path TO analytics; CREATE TEMP TABLE foo AS SELECT 1;
 ```