strict mode and other updates (#289)

Author: mtoy-googly-moogly

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

@@ -132,7 +132,7 @@ Because the BuildID is content-addressed, incremental builds fall out naturally.
 
 ### Manifests: The Bridge Between Builder and Runtime
 
-The manifest is a simple data structure: a map from BuildID to information about the built table (connection, table name, when it was built). A builder writes it. The runtime reads it. That's the entire contract.
+The manifest is a simple data structure: a map from BuildID to table name, plus an optional `strict` flag that controls error behavior when entries are missing. A builder writes it. The runtime reads it. That's the entire contract.
 
 This simplicity is the point. The manifest is just a JSON file. How it's stored and shared is up to you — it could be a file on disk, a blob in cloud storage, a row in a database. The runtime doesn't care where it came from.
 
@@ -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 `strictPersist` (production):** The `strictPersist` option tells the compiler to fail 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.
+**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.
 
 ## Building a Sophisticated Persistence Application
 

src/documentation/experiments/persistence.malloynb

@@ -149,10 +149,18 @@ Since the builder is a command-line tool, you can schedule refreshes however you
 
 ### Using persisted tables in VS Code
 
-Once the builder has written the manifest, VS Code picks it up automatically — no restart needed. Queries against persistent sources use the persisted tables instead of recomputing.
+Once the builder has written the manifest, VS Code picks it up on the next compile — no restart needed. Queries against persistent sources use the persisted tables instead of recomputing.
 
 To verify, compile a query (without running it) and check the generated SQL. With a manifest, you'll see `FROM by_carrier` instead of an inlined subquery.
 
 If VS Code and the builder are reading different config files, they'll have different manifests. Make sure both point at the same `malloy-config.json` (see [Setup](#setup) above).
+
+### Strict mode
+
+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.
+
+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/malloy_cli/index.malloynb

@@ -29,3 +29,11 @@ The main commands of the CLI are `run` and `compile` — `run` executes queries
 
 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`
 
+## Using the CLI with VS Code
+
+When using `malloy-cli build` alongside the Malloy VS Code extension, both tools need to share the same config file so they read and write the same manifest. There are two ways to set this up:
+
+**Global config (simplest):** The CLI uses `~/.config/malloy/malloy-config.json` by default — no flags needed. Point VS Code's `malloy.globalConfigDirectory` setting at `~/.config/malloy`. Both tools share the manifest at `~/.config/malloy/MANIFESTS/malloy-manifest.json`.
+
+**Project config:** Put `malloy-config.json` at your project root. VS Code finds it automatically. Pass `--config .` (or `--config <project-dir>`) to the CLI. Both tools share the manifest at `<project>/MANIFESTS/malloy-manifest.json`. This keeps everything project-local.
+

src/documentation/setup/extension.malloynb

@@ -66,7 +66,12 @@ Click any connection to open the connection editor, or use the **+** button to c
 
 Place a `malloy-config.json` file in the root of your project (workspace root). The extension detects it automatically and picks up changes whenever you save. In multi-root workspaces, each workspace root can have its own file with independent connection namespaces.
 
-The extension also reads [persistence manifests](../experiments/persistence.malloynb) from the config's `manifestPath` directory. When the builder (`malloy-cli build`) writes a manifest, VS Code picks it up automatically — no restart needed.
+The extension also reads [persistence manifests](../experiments/persistence.malloynb) from the config's `manifestPath` directory. When the builder (`malloy-cli build`) writes a manifest, VS Code picks it up on the next compile — no restart needed.
+
+**Using with `malloy-cli build`:** Both tools need to share the same config file so they read and write the same manifest. There are two ways to set this up:
+
+- **Global config (simplest):** Point the `malloy.globalConfigDirectory` setting at `~/.config/malloy` (or your platform's config directory). The CLI uses this location by default — no flags needed. Both tools share the manifest automatically.
+- **Project config:** Put `malloy-config.json` at your project root. The extension finds it automatically. Pass `--config .` to the CLI. Both tools share the project-local manifest.
 
 See **[Configuration](config.malloynb)** for the full config file format, connection type properties, manifest path, setup SQL, and environment variables.