Add mz-deploy documentation (#37052)

Adds user-facing documentation for `mz-deploy`, the declarative SQL
project
deployment tool, under `doc/user/content/manage/mz-deploy/`.

## What's here

- **Get started** — quickstart covering project creation, connection
profiles, compile, and the deploy lifecycle.
- **Installation** — macOS/Linux tabs that download the latest release
tarball from `binaries.materialize.com` and extract it into
`/usr/local`, following the existing `mz-debug` install pattern. The
architecture is resolved at runtime via `uname -m`, so a single command
covers Apple Silicon (`arm64`) and Intel macs as well as
`x86_64`/`aarch64` Linux.
- **Project structure, infrastructure, local development, deployments,
stable APIs, profiles** — reference pages for the full workflow.
- **Editor setup** — VS Code, Neovim, and Helix integration.
- **AI agent setup** — Claude Code and Codex configuration, including a
new **Claude Code on the web** section explaining how to install
`mz-deploy` into the Anthropic-managed cloud sandbox via its Setup
script field. The sandbox is always Linux and runs as root, so the
script uses the `unknown-linux-gnu` build, resolves the architecture at
runtime, and needs no `sudo`. The section also notes the Trusted vs None
network-mode constraint and points users at committing
`.claude/settings.json` so the language server carries over to cloud
sessions.

## Notes

Documentation only — no code changes, so no Rust/Python lint or test
steps apply.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sjwiesman

doc/user/content/manage/_index.md

@@ -25,6 +25,7 @@ This section contains various resources for managing Materialize.
 |-------|-------------|
 | [Using dbt to manage Materialize](/manage/dbt/) | Guides for using dbt to manage Materialize |
 | [Using Terraform to manage Materialize](/manage/terraform/) | Guides for using Terraform to manage Materialize |
+| [Using mz-deploy to manage Materialize](/manage/mz-deploy/) | SQL-native CLI for zero-downtime blue/green deployments |
 
 ## Usage and billing
 

doc/user/content/manage/mz-deploy/_index.md

@@ -0,0 +1,87 @@
+---
+title: "Use mz-deploy to manage Materialize"
+description: "Deploy and manage Materialize objects with mz-deploy, a SQL-native CLI for zero-downtime deployments."
+disable_list: true
+menu:
+  main:
+    parent: manage
+    weight: 40
+    identifier: "manage-mz-deploy"
+    name: "Manage with mz-deploy"
+---
+
+{{< warning >}}
+`mz-deploy` is a v0.1 release and is not yet recommended for production use.
+{{< /warning >}}
+
+`mz-deploy` is a CLI that manages your Materialize deployment from plain SQL
+files in a git repository. It catches errors before they reach production, lets
+you test view logic locally, and deploys changes without downtime.
+
+## Installation
+
+On macOS and Linux, we recommend installing `mz-deploy` with
+[Homebrew](https://brew.sh/):
+
+```shell
+brew install materializeinc/materialize/mz-deploy
+```
+
+For direct downloads and other installation options, see
+[Get started](/manage/mz-deploy/get-started/#prerequisites-and-installation).
+
+## Why mz-deploy
+
+### Write plain SQL, deploy safely
+
+Everything lives in `.sql` files — one object per file, organized by database
+and schema. `mz-deploy` tracks dependencies between objects, diffs your project
+against the live environment, and deploys only what changed. Durable objects
+like secrets, connections, sources, and tables are converged in place (like
+Terraform). Views, materialized views, indexes, and sinks go through a staged
+deployment so changes can be validated before going live.
+
+### Catch errors before deploying
+
+`mz-deploy compile` type-checks every SQL statement against your dependency
+schemas — locally, with no database connection required. Inline unit tests let
+you mock dependencies and verify view logic with deterministic inputs before
+anything touches a real environment. Changes that break types or dependencies
+fail fast on your laptop or in CI, not in production.
+
+### Ship without downtime
+
+When you deploy, `mz-deploy` creates your changes in isolated staging schemas
+alongside production. Once all materialized views finish computing their initial
+results, a single atomic swap cuts traffic over to the new version. Running
+queries are never interrupted, and if something goes wrong, the staging
+deployment can be cleaned up without affecting production.
+
+## When to use it
+
+| Tool | Best for | Manages infrastructure | Zero-downtime deployments |
+|------|----------|----------------------|--------------------------|
+| **Plain SQL / psql scripts** | Manual execution. No dependency tracking, no diff, no rollback. Where most teams start. | No | No |
+| **mz-deploy** | SQL-native, git-based workflow with offline type-checking, unit tests, and staged deployments. | Yes | Yes |
+| **[dbt](/manage/dbt/)** | Teams already invested in dbt. Manages views and materialized views. | No (clusters, connections, secrets are out of scope) | Yes (via `dbt-materialize` adapter macros) |
+| **[Terraform](/manage/terraform/)** | Teams managing Materialize alongside other cloud infrastructure. | Yes | No |
+
+## Available guides
+
+{{< multilinkbox >}}
+{{< linkbox title="To get started" >}}
+[Get started with mz-deploy](/manage/mz-deploy/get-started/)
+{{</ linkbox >}}
+{{< linkbox title="Develop" >}}
+- [Project structure](/manage/mz-deploy/project-structure/)
+- [Infrastructure](/manage/mz-deploy/infrastructure/)
+- [Local development](/manage/mz-deploy/local-development/)
+- [Editor setup](/manage/mz-deploy/editor-setup/)
+- [AI agent setup](/manage/mz-deploy/agent-setup/)
+{{</ linkbox >}}
+{{< linkbox title="Deploy" >}}
+- [Deployments](/manage/mz-deploy/deployments/)
+- [Stable APIs](/manage/mz-deploy/stable-apis/)
+- [Profiles](/manage/mz-deploy/profiles/)
+{{</ linkbox >}}
+{{</ multilinkbox >}}

doc/user/content/manage/mz-deploy/agent-setup.md

@@ -0,0 +1,103 @@
+---
+title: "AI agent setup"
+description: "Configure AI coding agents like Claude Code and Codex to work with mz-deploy projects."
+menu:
+  main:
+    parent: manage-mz-deploy
+    weight: 44
+    identifier: "mz-deploy-agent-setup"
+    name: "AI agent setup"
+---
+
+`mz-deploy` was built with AI coding agents in mind. Every new project ships
+with agent-readable documentation, the CLI provides agent-optimized help, and
+the language server gives agents real-time feedback on SQL correctness.
+
+## Project skill
+
+The community [MaterializeInc/agent-skills](https://github.com/MaterializeInc/agent-skills)
+repo publishes an agent skill for `mz-deploy` that teaches agents your
+project's conventions: one object per file, file paths map to qualified
+names, how the deployment lifecycle works, unit test syntax, and how to get
+detailed help with `mz-deploy help <command>`.
+
+The skill is not installed by default. Install it in your project with:
+
+```sh
+npx -y skills add MaterializeInc/agent-skills -a universal -a claude-code --project
+```
+
+This drops the skill into `.agents/skills/mz-deploy/` and wires up a
+`.claude/skills/` symlink so Claude Code picks it up. Agents that consume
+the universal skill format (Codex and others) load it from the same
+location. You don't need to explain the project's conventions — the agent
+already knows them.
+
+Update to the latest version later with:
+
+```sh
+npx -y skills update
+```
+
+## Claude Code on the web
+
+[Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web)
+runs each session in a fresh, Anthropic-managed cloud sandbox. The sandbox
+doesn't have `mz-deploy` installed, so install it with a **setup script** — a
+Bash script that runs once, as root, before Claude Code starts.
+
+In the cloud environment settings, set the **Setup script** field to:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+ARCH=$(uname -m)
+curl -L "https://binaries.materialize.com/mz-deploy-latest-$ARCH-unknown-linux-gnu.tar.gz" \
+| tar -xzC /usr/local --strip-components=1
+```
+
+The sandbox runs Ubuntu on Linux, so this always uses the `unknown-linux-gnu`
+build and resolves the architecture (`x86_64` or `aarch64`) at runtime. The
+binary lands in `/usr/local/bin`, which is already on `PATH`. The script runs as
+root, so no `sudo` is needed. Setup scripts have network access under the
+default **Trusted** network mode; if your environment uses **None**, the
+download will fail.
+
+To configure the language server in the sandbox as well, commit the
+`.claude/settings.json` from [Configuring for Claude Code](#configuring-for-claude-code)
+to your repository — it carries over to cloud sessions automatically.
+
+## Agent-optimized help
+
+```bash
+mz-deploy help <command>    # Detailed guide for a single command
+mz-deploy help --all        # All command guides concatenated
+```
+
+Unlike `--help` (which prints brief CLI usage), `help` returns full guides
+with behavior notes, examples, error recovery steps, and related commands.
+
+## Language server
+
+The mz-deploy language server gives agents the same benefits it gives human
+editors: parse error diagnostics on every file change, go-to-definition across
+your project, and column-aware completions scoped to actual dependencies.
+
+For agents, this means fewer incorrect SQL suggestions — the agent sees real
+column names and types from your `types.lock` rather than guessing.
+
+### Configuring for Claude Code
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "lsp": {
+    "mz-deploy": {
+      "command": "mz-deploy",
+      "args": ["lsp", "-d", "."],
+      "filePatterns": ["*.sql"]
+    }
+  }
+}
+```