From 8b7ee89268a784d86cd118ea97f2f1726eb904b6 Mon Sep 17 00:00:00 2001
From: Ryuz <ryuzer@proton.me>
Date: Tue, 27 Oct 2026 15:42:55 +0100
Subject: [PATCH 1/5] Serve templates examples over the public examples MCP
 tool

New apps are empty branded shells; proven patterns live in examples/
in outer-templates and are served from the pinned bundle: the reader
extracts only examples/ into a per-sha cache dir (atomic create_dir
single-flight, contract enforced, bad examples skipped with a warn).
The examples tool lists (template-filtered) and returns README + files
with the 200 KB budget style. INSTRUCTIONS, create_app (template-aware,
hint built from the live list), open_app next and about point at it.
---
 crates/outer/src/examples.rs             | 801 +++++++++++++++++++++++
 crates/outer/src/lib.rs                  |   1 +
 crates/outer/src/mcp/mod.rs              |   2 +-
 crates/outer/src/mcp/registry.rs         |  18 +-
 crates/outer/src/mcp/tests.rs            |   4 +-
 crates/outer/src/mcp/tools/account.rs    |   1 +
 crates/outer/src/mcp/tools/apps.rs       |  38 +-
 crates/outer/src/mcp/tools/examples.rs   | 203 ++++++
 crates/outer/src/mcp/tools/mod.rs        |   4 +
 crates/outer/src/mcp/tools/open_app.rs   |   3 +
 crates/outer/src/templates.rs            |  11 +-
 web/docs/agents/backend/database.md      |   2 +-
 web/docs/agents/frontend/void.md         |   2 +-
 web/docs/agents/start-here/examples.md   |  38 ++
 web/docs/agents/start-here/index.md      |   4 +-
 web/docs/agents/start-here/meta.ts       |   2 +-
 web/docs/agents/start-here/quickstart.md |   2 +-
 web/docs/agents/start-here/templates.md  |  16 +-
 web/docs/backend/database.mdx            |   2 +-
 web/docs/get-started/connect.mdx         |   2 +-
 web/docs/get-started/quickstart.mdx      |   2 +-
 web/docs/get-started/templates.mdx       |  11 +-
 web/docs/reference/tools.md              |  12 +
 23 files changed, 1145 insertions(+), 36 deletions(-)
 create mode 100644 crates/outer/src/examples.rs
 create mode 100644 crates/outer/src/mcp/tools/examples.rs
 create mode 100644 web/docs/agents/start-here/examples.md

diff --git a/crates/outer/src/examples.rs b/crates/outer/src/examples.rs
new file mode 100644
index 0000000..f1482c7
--- /dev/null
+++ b/crates/outer/src/examples.rs
@@ -0,0 +1,801 @@
+//! Copy-paste patterns served over the public `examples` MCP tool.
+//!
+//! The patterns live in `examples/` in the `outer-templates` repo, vendored
+//! into the store as a git bundle at the pinned sha (see [`crate::templates`]).
+//! [`list`] and [`get`] extract only `examples/` into a cache dir under
+//! Outer's data dir, once per sha, and serve from there. A pinned sha with no
+//! `examples/` yields an empty list. A bad example is skipped with a warn and
+//! never fails the whole list.
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+use crate::store::Store;
+use crate::templates::Template;
+
+/// One file's listing entry: path plus its line count.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct FileRef {
+    pub path: String,
+    pub lines: usize,
+}
+
+/// One row of the `examples` list: metadata plus the file listing.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct Summary {
+    pub name: String,
+    pub title: String,
+    pub summary: String,
+    pub template: String,
+    pub dependencies: BTreeMap<String, String>,
+    pub files: Vec<FileRef>,
+}
+
+/// One full example: the README plus every file's text.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExampleFile {
+    pub path: String,
+    pub text: String,
+}
+
+/// One full example: the README plus every file's text.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Example {
+    pub name: String,
+    pub title: String,
+    pub summary: String,
+    pub template: String,
+    pub dependencies: BTreeMap<String, String>,
+    pub readme: String,
+    pub files: Vec<ExampleFile>,
+}
+
+/// An example dir name: `^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$`.
+pub fn is_valid_name(name: &str) -> bool {
+    let bytes = name.as_bytes();
+    if bytes.len() < 2 || bytes.len() > 40 {
+        return false;
+    }
+    let edge = |b: u8| b.is_ascii_lowercase() || b.is_ascii_digit();
+    if !edge(bytes[0]) || !edge(bytes[bytes.len() - 1]) {
+        return false;
+    }
+    bytes
+        .iter()
+        .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || *b == b'-')
+}
+
+/// The `example.json` contract: name, title, summary, template, plus optional
+/// dependencies. Unknown fields are ignored.
+#[derive(Debug, Deserialize)]
+struct ExampleJson {
+    title: String,
+    summary: String,
+    template: String,
+    #[serde(default)]
+    dependencies: BTreeMap<String, String>,
+}
+
+/// Largest single file an example may carry (contract: 64 KiB).
+const MAX_EXAMPLE_FILE_BYTES: u64 = 64 * 1024;
+/// Most files one example may carry (contract: 30).
+const MAX_EXAMPLE_FILES: usize = 30;
+
+/// Marker written after a sha's cache dir is fully extracted.
+const READY: &str = "READY";
+/// How long a racing caller waits for the winner's `READY`.
+const EXTRACT_WAIT: Duration = Duration::from_secs(30);
+/// A non-ready cache dir older than this is a crashed extraction: take over.
+const STALE_AFTER: Duration = Duration::from_secs(600);
+
+/// The cache root: one dir per vendored sha under Outer's data dir.
+fn cache_root(data_dir: &Path) -> PathBuf {
+    data_dir.join("examples")
+}
+
+/// List the valid examples at the current pin, optionally filtered to one
+/// template. Sorted by name. No pin, or a pin with no `examples/`, is an
+/// empty list.
+pub async fn list(
+    store: &Store,
+    data_dir: &Path,
+    template: Option<Template>,
+) -> anyhow::Result<Vec<Summary>> {
+    let dir = match ensure_extracted(store, data_dir).await? {
+        None => return Ok(Vec::new()),
+        Some(dir) => dir,
+    };
+    let id = template.map(|t| t.id());
+    Ok(load_examples(&dir)
+        .into_iter()
+        .filter(|example| id.is_none_or(|id| example.template == id))
+        .map(|example| example.summary())
+        .collect())
+}
+
+/// The full example `name`, or `None` when it names no valid example.
+/// An invalid name is the caller's bug: refused before touching the fs.
+pub async fn get(store: &Store, data_dir: &Path, name: &str) -> anyhow::Result<Option<Example>> {
+    anyhow::ensure!(is_valid_name(name), "bad example name {name:?}");
+    let dir = match ensure_extracted(store, data_dir).await? {
+        None => return Ok(None),
+        Some(dir) => dir,
+    };
+    Ok(load_example(&dir.join(name), name))
+}
+
+impl Example {
+    fn summary(&self) -> Summary {
+        Summary {
+            name: self.name.clone(),
+            title: self.title.clone(),
+            summary: self.summary.clone(),
+            template: self.template.clone(),
+            dependencies: self.dependencies.clone(),
+            files: self
+                .files
+                .iter()
+                .map(|file| FileRef {
+                    path: file.path.clone(),
+                    lines: file.text.lines().count(),
+                })
+                .collect(),
+        }
+    }
+}
+
+/// Extract `examples/` for the current [`crate::templates::TemplateRef`]
+/// into the cache, once per sha. Concurrent first calls race on one atomic
+/// `create_dir`: the winner extracts, the losers wait for its `READY`.
+/// `Ok(None)` means no pin (or nothing vendored yet): serve an empty list.
+async fn ensure_extracted(store: &Store, data_dir: &Path) -> anyhow::Result<Option<PathBuf>> {
+    let Some(reference) = crate::templates::current_reference(store).await? else {
+        return Ok(None);
+    };
+    let root = cache_root(data_dir);
+    std::fs::create_dir_all(&root)?;
+    let target = root.join(&reference.sha);
+    if is_ready(&target) {
+        return Ok(Some(target));
+    }
+    if std::fs::create_dir(&target).is_ok() {
+        return extract(store, &reference, &target)
+            .await
+            .map(|()| Some(target));
+    }
+    // Someone else is extracting (or crashed doing so).
+    if wait_ready(&target, EXTRACT_WAIT).await {
+        return Ok(Some(target));
+    }
+    // A crashed extraction leaves a stale dir with no `READY`: take over.
+    if is_stale(&target) {
+        let _ = std::fs::remove_dir_all(&target);
+        if std::fs::create_dir(&target).is_ok() {
+            return extract(store, &reference, &target)
+                .await
+                .map(|()| Some(target));
+        }
+        if wait_ready(&target, EXTRACT_WAIT).await {
+            return Ok(Some(target));
+        }
+    }
+    anyhow::bail!(
+        "timed out waiting for the examples cache at {}",
+        target.display()
+    )
+}
+
+/// Clone the vendored bundle, check out the pin, and copy only `examples/`
+/// into `target` (skipping symlinks: the contract forbids them). A pin with
+/// no `examples/` leaves an empty `target`. A failure removes `target` so a
+/// racing caller can take over.
+async fn extract(
+    store: &Store,
+    reference: &crate::templates::TemplateRef,
+    target: &Path,
+) -> anyhow::Result<()> {
+    let out = extract_inner(store, reference, target).await;
+    if out.is_err() {
+        let _ = std::fs::remove_dir_all(target);
+    }
+    out
+}
+
+async fn extract_inner(
+    store: &Store,
+    reference: &crate::templates::TemplateRef,
+    target: &Path,
+) -> anyhow::Result<()> {
+    let tmp = tempfile::tempdir()?;
+    let bundle_path = tmp.path().join("templates.bundle");
+    if !store
+        .get_to_file(&reference.bundle_key, &bundle_path)
+        .await?
+    {
+        anyhow::bail!(
+            "template bundle {} is missing from the store",
+            reference.bundle_key
+        );
+    }
+    let bundle_str = bundle_path.to_string_lossy().into_owned();
+    let src = tmp.path().join("src");
+    let src_str = src.to_string_lossy().into_owned();
+    crate::templates::run_git(
+        &[
+            "clone",
+            "--no-checkout",
+            bundle_str.as_str(),
+            src_str.as_str(),
+        ],
+        None,
+        &[],
+    )
+    .await?;
+    crate::templates::run_git(
+        &["-C", src_str.as_str(), "checkout", reference.sha.as_str()],
+        None,
+        &[],
+    )
+    .await?;
+    let head = crate::templates::run_git(&["-C", src_str.as_str(), "rev-parse", "HEAD"], None, &[])
+        .await?;
+    anyhow::ensure!(
+        head.trim() == reference.sha,
+        "vendored bundle checked out {}, want {}",
+        head.trim(),
+        reference.sha
+    );
+    let examples = src.join("examples");
+    if examples.is_dir() {
+        copy_examples(&examples, target)?;
+    }
+    std::fs::write(target.join(READY), reference.sha.as_bytes())?;
+    Ok(())
+}
+
+/// Copy the extracted `examples/` tree, skipping symlinks (forbidden by the
+/// contract) rather than reproducing them.
+fn copy_examples(src: &Path, dest: &Path) -> anyhow::Result<()> {
+    for entry in std::fs::read_dir(src)? {
+        let entry = entry?;
+        let kind = entry.file_type()?;
+        if kind.is_symlink() {
+            continue;
+        }
+        let to = dest.join(entry.file_name());
+        if kind.is_dir() {
+            copy_examples_dir(&entry.path(), &to)?;
+        } else {
+            if let Some(parent) = to.parent() {
+                std::fs::create_dir_all(parent)?;
+            }
+            std::fs::copy(entry.path(), &to)?;
+        }
+    }
+    Ok(())
+}
+
+fn copy_examples_dir(src: &Path, dest: &Path) -> anyhow::Result<()> {
+    std::fs::create_dir_all(dest)?;
+    copy_examples(src, dest)
+}
+
+fn is_ready(dir: &Path) -> bool {
+    dir.join(READY).is_file()
+}
+
+async fn wait_ready(dir: &Path, wait: Duration) -> bool {
+    let start = std::time::Instant::now();
+    while start.elapsed() < wait {
+        if is_ready(dir) {
+            return true;
+        }
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+    is_ready(dir)
+}
+
+fn is_stale(dir: &Path) -> bool {
+    if is_ready(dir) {
+        return false;
+    }
+    match std::fs::metadata(dir).and_then(|meta| meta.modified()) {
+        Ok(modified) => modified.elapsed().unwrap_or(Duration::ZERO) > STALE_AFTER,
+        Err(_) => false,
+    }
+}
+
+/// Every valid example in an extracted cache dir, sorted by name. A bad
+/// example is skipped with a warn and never fails the whole list.
+fn load_examples(dir: &Path) -> Vec<Example> {
+    let mut out = Vec::new();
+    let entries = match std::fs::read_dir(dir) {
+        Ok(entries) => entries,
+        Err(_) => return out,
+    };
+    for entry in entries.flatten() {
+        if entry.file_type().is_ok_and(|kind| kind.is_symlink()) {
+            continue;
+        }
+        let path = entry.path();
+        if !path.is_dir() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if name == READY || !is_valid_name(&name) {
+            continue;
+        }
+        if let Some(example) = load_example(&path, &name) {
+            out.push(example);
+        }
+    }
+    out.sort_by(|a, b| a.name.cmp(&b.name));
+    out
+}
+
+/// One valid example, or `None` (with a warn) when it breaks the contract.
+fn load_example(dir: &Path, name: &str) -> Option<Example> {
+    let reject = |why: &str| {
+        tracing::warn!(example = name, "skipping invalid example: {why}");
+        None
+    };
+    let raw = std::fs::read(dir.join("example.json")).ok()?;
+    let meta: ExampleJson = match serde_json::from_slice(&raw) {
+        Ok(meta) => meta,
+        Err(err) => return reject(&format!("bad example.json: {err:#}")),
+    };
+    if crate::templates::Template::from_id(&meta.template).is_none() {
+        return reject(&format!("bad template {:?}", meta.template));
+    }
+    let readme = match std::fs::read_to_string(dir.join("README.md")) {
+        Ok(readme) => readme,
+        Err(_) => return reject("missing README.md"),
+    };
+    let mut files = Vec::new();
+    collect_files(dir, dir, &mut files)?;
+    if files.len() > MAX_EXAMPLE_FILES {
+        return reject(&format!(
+            "{} files, at most {MAX_EXAMPLE_FILES}",
+            files.len()
+        ));
+    }
+    let mut out = Vec::with_capacity(files.len());
+    for path in files {
+        let full = dir.join(&path);
+        let size = std::fs::metadata(&full).ok()?.len();
+        if size > MAX_EXAMPLE_FILE_BYTES {
+            return reject(&format!(
+                "{path} is {size} bytes, at most {MAX_EXAMPLE_FILE_BYTES}"
+            ));
+        }
+        match std::fs::read_to_string(&full) {
+            Ok(text) => out.push(ExampleFile { path, text }),
+            Err(_) => return reject(&format!("{path} is not UTF-8")),
+        }
+    }
+    Some(Example {
+        name: name.to_string(),
+        title: meta.title,
+        summary: meta.summary,
+        template: meta.template,
+        dependencies: meta.dependencies,
+        readme,
+        files: out,
+    })
+}
+
+/// Every regular file under an example dir as an app-relative path, sorted.
+/// `example.json` and `README.md` are metadata, not app files. Symlinks are
+/// skipped (forbidden by the contract).
+fn collect_files(dir: &Path, base: &Path, out: &mut Vec<String>) -> Option<()> {
+    let mut entries: Vec<_> = std::fs::read_dir(dir).ok()?.flatten().collect();
+    entries.sort_by_key(|entry| entry.file_name());
+    for entry in entries {
+        if entry.file_type().is_ok_and(|kind| kind.is_symlink()) {
+            tracing::warn!(
+                file = %entry.path().display(),
+                "skipping symlinked example file"
+            );
+            continue;
+        }
+        let path = entry.path();
+        if path.is_dir() {
+            collect_files(&path, base, out)?;
+        } else if path.is_file() {
+            let rel = path.strip_prefix(base).ok()?.to_string_lossy().into_owned();
+            if rel != "example.json" && rel != "README.md" {
+                out.push(rel);
+            }
+        }
+    }
+    Some(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mcp::tools::examples::{examples as examples_tool, ExamplesInput};
+    use crate::mcp::tools::Ctx;
+    use crate::mcp::McpState;
+
+    /// A live state for tool calls: memory store, temp dirs, no network.
+    async fn tool_state(store: Store) -> McpState {
+        let dir = tempfile::tempdir().unwrap();
+        let pool = crate::db::open(&dir.path().join("outer.sqlite"))
+            .await
+            .unwrap();
+        std::mem::forget(dir);
+        let (auth_cfg, _) = crate::auth::test_support::test_config();
+        let auth_state = crate::auth::AuthState {
+            pool: pool.clone(),
+            config: auth_cfg,
+        };
+        let mut state = McpState::for_tests(pool, auth_state);
+        state.store = store;
+        state
+    }
+
+    /// A templates repo with both starter folders plus `examples/`: each
+    /// entry is `(example name, [(app-relative path, body)])`, and each
+    /// symlink is `(example, link path, target)`.
+    async fn fixture(
+        store: &Store,
+        examples: &[(&str, &[(&str, &str)])],
+        symlinks: &[(&str, &str, &str)],
+    ) -> String {
+        let src = tempfile::tempdir().unwrap();
+        for template in Template::ALL {
+            let dir = src.path().join(template.dir());
+            std::fs::create_dir_all(&dir).unwrap();
+            std::fs::write(dir.join("package.json"), "{}\n").unwrap();
+        }
+        for (name, files) in examples {
+            let dir = src.path().join("examples").join(name);
+            std::fs::create_dir_all(&dir).unwrap();
+            for (rel, body) in *files {
+                let path = dir.join(rel);
+                std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+                std::fs::write(path, body).unwrap();
+            }
+        }
+        for (name, link, target) in symlinks {
+            let path = src.path().join("examples").join(name).join(link);
+            std::os::unix::fs::symlink(target, &path).unwrap();
+        }
+        let author = [
+            ("GIT_AUTHOR_NAME", "t"),
+            ("GIT_AUTHOR_EMAIL", "t@example.com"),
+            ("GIT_COMMITTER_NAME", "t"),
+            ("GIT_COMMITTER_EMAIL", "t@example.com"),
+        ];
+        crate::templates::run_git(&["init", "-b", "main"], Some(src.path()), &[])
+            .await
+            .unwrap();
+        crate::templates::run_git(&["add", "-A"], Some(src.path()), &[])
+            .await
+            .unwrap();
+        crate::templates::run_git(&["commit", "-m", "seed"], Some(src.path()), &author)
+            .await
+            .unwrap();
+        let sha = crate::templates::run_git(&["rev-parse", "HEAD"], Some(src.path()), &[])
+            .await
+            .unwrap()
+            .trim()
+            .to_string();
+        let url = format!("file://{}", src.path().to_string_lossy());
+        crate::templates::sync(store, &url, &sha).await.unwrap();
+        sha
+    }
+
+    fn example_json(template: &str, title: &str, summary: &str) -> String {
+        serde_json::json!({
+            "name": "ignored-the-dir-name-wins",
+            "title": title,
+            "summary": summary,
+            "template": template,
+            "dependencies": {"left-pad": "^1.3.0"},
+        })
+        .to_string()
+    }
+
+    async fn two_example_state() -> McpState {
+        let store = Store::memory();
+        let json = example_json(
+            "app",
+            "List form",
+            "A D1-backed list with add and complete.",
+        );
+        let blog_json = example_json("website", "Blog", "Content-collection posts.");
+        fixture(
+            &store,
+            &[
+                (
+                    "list-form",
+                    &[
+                        ("example.json", json.as_str()),
+                        ("README.md", "# List form\n\nCopy these files.\n"),
+                        ("pages/list.tsx", "export default function List() {}\n"),
+                        ("pages/list.server.ts", "export function load() {}\n"),
+                    ],
+                ),
+                (
+                    "blog",
+                    &[
+                        ("example.json", blog_json.as_str()),
+                        ("README.md", "# Blog\n\nCopy these files.\n"),
+                        ("src/content/hello.md", "# Hello\n"),
+                    ],
+                ),
+            ],
+            &[],
+        )
+        .await;
+        tool_state(store).await
+    }
+
+    #[test]
+    fn example_names_follow_the_contract() {
+        assert!(is_valid_name("list-form"));
+        assert!(is_valid_name("a0"));
+        assert!(!is_valid_name(""));
+        assert!(!is_valid_name("a"));
+        assert!(!is_valid_name("Upper"));
+        assert!(!is_valid_name("../x"));
+        assert!(!is_valid_name("-lead"));
+        assert!(!is_valid_name("trail-"));
+        assert!(!is_valid_name(&"a".repeat(41)));
+        assert!(is_valid_name(&format!("a{}b", "c".repeat(38))));
+    }
+
+    #[tokio::test]
+    async fn list_returns_valid_examples_filtered_by_template() {
+        let state = two_example_state().await;
+        let dir = &state.delete_cfg.data_dir;
+        let all = list(&state.store, dir, None).await.unwrap();
+        assert_eq!(all.len(), 2);
+        assert_eq!(all[0].name, "blog");
+        assert_eq!(all[1].name, "list-form");
+        assert_eq!(all[1].title, "List form");
+        assert_eq!(all[1].summary, "A D1-backed list with add and complete.");
+        assert_eq!(all[1].template, "app");
+        assert_eq!(
+            all[1].dependencies.get("left-pad").map(String::as_str),
+            Some("^1.3.0")
+        );
+        let paths: Vec<_> = all[1].files.iter().map(|file| file.path.as_str()).collect();
+        assert_eq!(paths, ["pages/list.server.ts", "pages/list.tsx"]);
+        assert!(all[1].files.iter().all(|file| file.lines > 0));
+        let app_only = list(&state.store, dir, Some(Template::App)).await.unwrap();
+        assert_eq!(
+            app_only
+                .iter()
+                .map(|example| example.name.as_str())
+                .collect::<Vec<_>>(),
+            ["list-form"]
+        );
+        let site_only = list(&state.store, dir, Some(Template::Website))
+            .await
+            .unwrap();
+        assert_eq!(
+            site_only
+                .iter()
+                .map(|example| example.name.as_str())
+                .collect::<Vec<_>>(),
+            ["blog"]
+        );
+    }
+
+    #[tokio::test]
+    async fn get_returns_the_readme_and_files() {
+        let state = two_example_state().await;
+        let example = get(&state.store, &state.delete_cfg.data_dir, "list-form")
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(example.readme, "# List form\n\nCopy these files.\n");
+        let paths: Vec<_> = example
+            .files
+            .iter()
+            .map(|file| file.path.as_str())
+            .collect();
+        assert_eq!(paths, ["pages/list.server.ts", "pages/list.tsx"]);
+        assert!(example
+            .files
+            .iter()
+            .any(|file| file.path == "pages/list.tsx"
+                && file.text == "export default function List() {}\n"));
+    }
+
+    #[tokio::test]
+    async fn unknown_name_lists_the_valid_names() {
+        let state = two_example_state().await;
+        let ctx = Ctx {
+            state: &state,
+            principal: None,
+            client_ip: None,
+        };
+        let err = examples_tool(
+            ExamplesInput {
+                name: Some("nope".to_string()),
+                template: None,
+            },
+            &ctx,
+        )
+        .await
+        .unwrap_err();
+        assert_eq!(err.code, "invalid_argument");
+        assert!(
+            err.message.contains("nope"),
+            "names the unknown: {}",
+            err.message
+        );
+        assert!(
+            err.message.contains("list-form") && err.message.contains("blog"),
+            "lists the valid: {}",
+            err.message
+        );
+    }
+
+    #[tokio::test]
+    async fn invalid_names_are_refused_before_touching_the_store() {
+        // The store was never vendored: anything past the name check would
+        // fail as `internal`, not `invalid_argument`.
+        let state = tool_state(Store::memory()).await;
+        let ctx = Ctx {
+            state: &state,
+            principal: None,
+            client_ip: None,
+        };
+        for bad in ["../x".to_string(), "Upper".to_string(), "a".repeat(41)] {
+            let err = examples_tool(
+                ExamplesInput {
+                    name: Some(bad.clone()),
+                    template: None,
+                },
+                &ctx,
+            )
+            .await
+            .unwrap_err();
+            assert_eq!(err.code, "invalid_argument", "for {bad:?}");
+        }
+        // A well-formed but unknown name on an empty pin stays `invalid_argument`.
+        let err = examples_tool(
+            ExamplesInput {
+                name: Some("list-form".to_string()),
+                template: None,
+            },
+            &ctx,
+        )
+        .await
+        .unwrap_err();
+        assert_eq!(err.code, "invalid_argument");
+        assert!(err.message.contains("pick one of:"), "{}", err.message);
+    }
+
+    #[tokio::test]
+    async fn a_symlinked_file_is_skipped() {
+        let store = Store::memory();
+        let json = example_json("app", "List form", "A D1-backed list.");
+        fixture(
+            &store,
+            &[(
+                "list-form",
+                &[
+                    ("example.json", json.as_str()),
+                    ("README.md", "# List form\n"),
+                    ("pages/list.tsx", "export default function List() {}\n"),
+                ],
+            )],
+            &[("list-form", "pages/evil.tsx", "../list.server.ts")],
+        )
+        .await;
+        let state = tool_state(store).await;
+        let example = get(&state.store, &state.delete_cfg.data_dir, "list-form")
+            .await
+            .unwrap()
+            .unwrap();
+        let paths: Vec<_> = example
+            .files
+            .iter()
+            .map(|file| file.path.as_str())
+            .collect();
+        assert_eq!(paths, ["pages/list.tsx"]);
+    }
+
+    #[tokio::test]
+    async fn the_output_budget_truncates() {
+        let store = Store::memory();
+        let big = "x".repeat(60 * 1024);
+        let json = example_json("app", "Big", "Four files past the budget.");
+        fixture(
+            &store,
+            &[(
+                "big",
+                &[
+                    ("example.json", json.as_str()),
+                    ("README.md", "# Big\n"),
+                    ("a.txt", big.as_str()),
+                    ("b.txt", big.as_str()),
+                    ("c.txt", big.as_str()),
+                    ("d.txt", big.as_str()),
+                ],
+            )],
+            &[],
+        )
+        .await;
+        let state = tool_state(store).await;
+        let ctx = Ctx {
+            state: &state,
+            principal: None,
+            client_ip: None,
+        };
+        let value = examples_tool(
+            ExamplesInput {
+                name: Some("big".to_string()),
+                template: None,
+            },
+            &ctx,
+        )
+        .await
+        .unwrap();
+        let structured = &value["structuredContent"];
+        assert_eq!(structured["truncated"], true);
+        assert_eq!(structured["files"].as_array().unwrap().len(), 4);
+        assert_eq!(structured["files"][3]["truncated"], true);
+        let text = value["content"][0]["text"].as_str().unwrap();
+        assert!(
+            text.contains("truncated at the 200 KB output budget"),
+            "{text}"
+        );
+        assert!(text.starts_with("# Big\n"), "{text}");
+    }
+
+    #[tokio::test]
+    async fn a_pin_without_examples_gives_an_empty_list() {
+        let store = Store::memory();
+        crate::templates::vendor_test_templates(&store, &[("package.json", "{}\n")]).await;
+        let state = tool_state(store).await;
+        let dir = &state.delete_cfg.data_dir;
+        assert!(list(&state.store, dir, None).await.unwrap().is_empty());
+        assert!(get(&state.store, dir, "list-form").await.unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn concurrent_first_calls_extract_once() {
+        let store = Store::memory();
+        let json = example_json("app", "List form", "A D1-backed list.");
+        let sha = fixture(
+            &store,
+            &[(
+                "list-form",
+                &[
+                    ("example.json", json.as_str()),
+                    ("README.md", "# List form\n"),
+                    ("pages/list.tsx", "export default function List() {}\n"),
+                ],
+            )],
+            &[],
+        )
+        .await;
+        let state = tool_state(store).await;
+        let dir = state.delete_cfg.data_dir.clone();
+        let (first, second) = tokio::join!(
+            list(&state.store, &dir, None),
+            list(&state.store, &dir, None)
+        );
+        let (first, second) = (first.unwrap(), second.unwrap());
+        assert_eq!(first, second);
+        assert_eq!(first.len(), 1);
+        let mut entries: Vec<_> = std::fs::read_dir(dir.join("examples"))
+            .unwrap()
+            .collect::<Result<_, _>>()
+            .unwrap();
+        entries.sort_by_key(|entry| entry.file_name());
+        assert_eq!(entries.len(), 1);
+        assert_eq!(entries[0].file_name().to_string_lossy(), sha.as_str());
+        assert!(entries[0].path().join("READY").is_file());
+    }
+}
diff --git a/crates/outer/src/lib.rs b/crates/outer/src/lib.rs
index a39d390..ee0f75e 100644
--- a/crates/outer/src/lib.rs
+++ b/crates/outer/src/lib.rs
@@ -17,6 +17,7 @@ pub mod cron;
 pub mod d1_backup;
 pub mod db;
 pub mod deploy;
+pub mod examples;
 pub mod fleet;
 pub mod git;
 pub mod http;
diff --git a/crates/outer/src/mcp/mod.rs b/crates/outer/src/mcp/mod.rs
index 5968238..afa3b72 100644
--- a/crates/outer/src/mcp/mod.rs
+++ b/crates/outer/src/mcp/mod.rs
@@ -44,7 +44,7 @@ pub const LATEST_PROTOCOL: &str = "2025-11-25";
 
 /// Exactly the §8.1 text (Codex reads only this much). The length test pins
 /// it at or under 512 chars.
-pub const INSTRUCTIONS: &str = "Start with `open_app` to orient. Read with `read_files` (batches), find with `search_code`, iterate with `stage` then `check` then `ship` (`commit` ships at once). Relay `user_message` verbatim. Guides: `docs {topic}` and /llms.txt.";
+pub const INSTRUCTIONS: &str = "New apps are empty branded shells: build the request, nothing to delete. Start `open_app`, read (`read_files` batches, `search_code`), copy patterns from `examples`, iterate `stage`→`check`→`ship` (`commit` ships at once). Relay `user_message` verbatim. Guides: `docs {topic}`, /llms.txt.";
 
 /// Largest `POST /mcp` body: one `commit` at the caps fits (spec §8.1).
 pub const MAX_BODY_BYTES: usize = 32 * 1024 * 1024;
diff --git a/crates/outer/src/mcp/registry.rs b/crates/outer/src/mcp/registry.rs
index a4f6c70..df4f170 100644
--- a/crates/outer/src/mcp/registry.rs
+++ b/crates/outer/src/mcp/registry.rs
@@ -7,9 +7,9 @@ use serde_json::Value;
 use crate::mcp::tools::{
     account, apps as app_inputs, backups as backup_inputs, code as code_inputs,
     collaborators as collab_inputs, data as data_inputs, domains as domain_inputs,
-    drafts as draft_inputs, export as export_inputs, look as look_inputs,
-    open_app as open_app_inputs, preview as preview_inputs, runtime as runtime_inputs,
-    secrets as secrets_inputs, NoArgs,
+    drafts as draft_inputs, examples as examples_inputs, export as export_inputs,
+    look as look_inputs, open_app as open_app_inputs, preview as preview_inputs,
+    runtime as runtime_inputs, secrets as secrets_inputs, NoArgs,
 };
 
 /// Who may call the tool. `Public` tools run without a token; anything else
@@ -92,9 +92,8 @@ pub fn hints_for(name: &str) -> Option<Hints> {
         | "get_app" | "share_app" | "look_at_app" | "open_app" | "list_files" | "read_files"
         | "search_code" | "history" | "show_commit" | "deploy_status" | "deploy_log"
         | "app_logs" | "app_errors" | "app_metrics" | "db_query" | "list_secrets"
-        | "list_collaborators" | "list_domains" | "export_code" | "list_backups" | "diff_draft" => {
-            Hints::READ
-        }
+        | "list_collaborators" | "list_domains" | "export_code" | "list_backups" | "diff_draft"
+        | "examples" => Hints::READ,
         "verify_code" | "create_api_key" | "create_app" | "commit" | "rollback" | "rename_app"
         | "set_secret" | "resolve_error" | "ignore_error" | "reopen_error" | "add_domain"
         | "backup_database" | "promote_preview" | "upgrade" | "manage_billing" | "stage"
@@ -462,6 +461,11 @@ pub fn registry() -> Vec<ToolDef> {
             "Restore an app's D1 database from a backup: {app, binding?, backup_id, confirm} with confirm equal to backup_id. Takes a fresh backup first, then replaces the live tables with the dump. Owner only.",
             Account, false,
         ),
+        tool::<examples_inputs::ExamplesInput>(
+            "examples",
+            "Copy-paste patterns for apps and sites: `examples` lists them, `examples {name}` returns the README and files to copy.",
+            Public, false,
+        ),
     ]
 }
 
@@ -488,7 +492,7 @@ mod tests {
     #[test]
     fn registry_shapes() {
         let tools = registry();
-        assert_eq!(tools.len(), 59);
+        assert_eq!(tools.len(), 60);
     }
 }
 
diff --git a/crates/outer/src/mcp/tests.rs b/crates/outer/src/mcp/tests.rs
index a9ed62c..c192d6f 100644
--- a/crates/outer/src/mcp/tests.rs
+++ b/crates/outer/src/mcp/tests.rs
@@ -305,7 +305,7 @@ async fn tools_list_filters_per_caller() {
         .iter()
         .map(|t| t["name"].as_str().unwrap().to_string())
         .collect();
-    assert_eq!(anon.len(), 59);
+    assert_eq!(anon.len(), 60);
     assert!(anon.contains(&"sign_in".to_string()));
     assert!(anon.contains(&"create_app".to_string()));
 
@@ -322,7 +322,7 @@ async fn tools_list_filters_per_caller() {
         .iter()
         .map(|t| t["name"].as_str().unwrap().to_string())
         .collect();
-    assert_eq!(authed.len(), 57);
+    assert_eq!(authed.len(), 58);
     assert!(!authed.contains(&"sign_in".to_string()));
     assert!(!authed.contains(&"verify_code".to_string()));
     assert!(authed.contains(&"upgrade".to_string()));
diff --git a/crates/outer/src/mcp/tools/account.rs b/crates/outer/src/mcp/tools/account.rs
index 2efe63c..5d92a99 100644
--- a/crates/outer/src/mcp/tools/account.rs
+++ b/crates/outer/src/mcp/tools/account.rs
@@ -71,6 +71,7 @@ pub async fn about(_input: NoArgs, _ctx: &Ctx<'_>) -> Result<Value, ToolError> {
         "rules": [
             "Call docs {topic: \"ilha\"} before writing code.",
             "create_app, then commit (prefer edits). Every code tool waits for the deploy.",
+            "New apps are empty shells: build the request, copying proven patterns from `examples`.",
             "Relay user_message to your human verbatim.",
         ],
         "plans": "Free: 2 apps, 40 code changes and 30 build minutes/day. Pro ($8/month): 20 apps, 1,000 changes and 300 build minutes/day. See docs {topic: \"limits\"}.",
diff --git a/crates/outer/src/mcp/tools/apps.rs b/crates/outer/src/mcp/tools/apps.rs
index 515a3c0..49399f9 100644
--- a/crates/outer/src/mcp/tools/apps.rs
+++ b/crates/outer/src/mcp/tools/apps.rs
@@ -240,15 +240,41 @@ pub async fn create_app(input: CreateAppInput, ctx: &Ctx<'_>) -> Result<Value, T
     // app refuses here with the quota shape, and the `?` leaves the seeded
     // app row in place — the agent retries the deploy after the reset.
     let deploy = run_deploy(ctx.state, &app, &sha, input.wait.unwrap_or(true)).await?;
-    let summary = format!(
-        "{} is live at {}. Open it with open_app to keep working.",
-        app.slug,
-        ctx.state.app_url(&app.slug)
-    );
+    // Name the ready patterns for this template from the live examples
+    // list; a missing or empty list falls back to a plain pointer. Never
+    // fails the creation: examples are a hint, not the app.
+    let hint = match crate::examples::list(
+        &ctx.state.store,
+        &ctx.state.delete_cfg.data_dir,
+        Some(template),
+    )
+    .await
+    {
+        Ok(examples) if !examples.is_empty() => {
+            let names = examples
+                .iter()
+                .map(|example| example.name.as_str())
+                .collect::<Vec<_>>()
+                .join(", ");
+            format!("For ready patterns ({names}) call examples {{name}} for the README and files to copy.")
+        }
+        _ => "For ready patterns call examples.".to_string(),
+    };
+    let url = ctx.state.app_url(&app.slug);
+    let summary = match template {
+        crate::templates::Template::App => format!(
+            "{} is live at {url}. It's an empty app shell: build what your user asked for. Pages go in pages/ (list them in pages/_nav.ts). {hint}",
+            app.slug,
+        ),
+        crate::templates::Template::Website => format!(
+            "{} is live at {url}. It's an empty website shell: build what your user asked for. Content lives in Astro pages (islands for interactive parts). {hint}",
+            app.slug,
+        ),
+    };
     let structured = json!({
         "app": {"slug": app.slug, "url": ctx.state.app_url(&app.slug), "visibility": app.visibility.as_str()},
         "deploy": deploy,
-        "next": "open_app {app} to orient, then read_files (batched ranges), search_code, commit edits",
+        "next": "open_app {app} to orient, then read_files (batched ranges), search_code, examples for ready patterns, commit edits",
     });
     Ok(super::ok_deploy(
         summary,
diff --git a/crates/outer/src/mcp/tools/examples.rs b/crates/outer/src/mcp/tools/examples.rs
new file mode 100644
index 0000000..564cc69
--- /dev/null
+++ b/crates/outer/src/mcp/tools/examples.rs
@@ -0,0 +1,203 @@
+//! The public `examples` tool: list the copy-paste patterns vendored from
+//! the templates repo, or return one pattern's README plus its files.
+//!
+//! Our own content, so no untrusted notice: agents copy the files onto a
+//! fresh template and adapt them.
+
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+use super::{internal, ok, Ctx};
+use crate::mcp::error::ToolError;
+
+/// The output budget, same shape as `read_files`: file bytes past this are
+/// cut, and the result carries `truncated`.
+pub const MAX_EXAMPLE_OUTPUT_BYTES: usize = 200 * 1024;
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct ExamplesInput {
+    /// An example name (`examples` lists them). Omit to list.
+    pub name: Option<String>,
+    /// Only examples for one template: "app" or "website". Omit for both.
+    pub template: Option<String>,
+}
+
+fn truncate_utf8(s: &str, cap: usize) -> &str {
+    let mut end = cap.min(s.len());
+    while end > 0 && !s.is_char_boundary(end) {
+        end -= 1;
+    }
+    &s[..end]
+}
+
+pub async fn examples(input: ExamplesInput, ctx: &Ctx<'_>) -> Result<Value, ToolError> {
+    let template = match input.template.as_deref() {
+        None => None,
+        Some(id) => Some(crate::templates::Template::from_id(id).ok_or_else(|| {
+            ToolError::invalid_argument(format!(
+                "unknown template {id:?}: want \"app\" or \"website\""
+            ))
+        })?),
+    };
+    match input.name {
+        None => list_examples(ctx, template).await,
+        Some(name) => get_example(ctx, template, &name).await,
+    }
+}
+
+async fn list_examples(
+    ctx: &Ctx<'_>,
+    template: Option<crate::templates::Template>,
+) -> Result<Value, ToolError> {
+    let examples =
+        crate::examples::list(&ctx.state.store, &ctx.state.delete_cfg.data_dir, template)
+            .await
+            .map_err(internal)?;
+    let rows: Vec<Value> = examples
+        .iter()
+        .map(|example| {
+            json!({
+                "name": example.name,
+                "title": example.title,
+                "summary": example.summary,
+                "template": example.template,
+                "dependencies": example.dependencies,
+                "files": example.files.iter().map(|file| {
+                    json!({"path": file.path, "lines": file.lines})
+                }).collect::<Vec<_>>(),
+            })
+        })
+        .collect();
+    let text = if rows.is_empty() {
+        "(no examples at the current templates pin)".to_string()
+    } else {
+        examples
+            .iter()
+            .map(|example| {
+                format!(
+                    "- {} ({}): {} — {}",
+                    example.name, example.template, example.title, example.summary
+                )
+            })
+            .collect::<Vec<_>>()
+            .join("\n")
+    };
+    Ok(ok(
+        text,
+        json!({
+            "examples": rows,
+            "next": "examples {name} returns the README and files to copy",
+        }),
+    ))
+}
+
+async fn get_example(
+    ctx: &Ctx<'_>,
+    template: Option<crate::templates::Template>,
+    name: &str,
+) -> Result<Value, ToolError> {
+    if !crate::examples::is_valid_name(name) {
+        return Err(ToolError::invalid_argument(format!(
+            "bad example name {name:?}: names match ^[a-z0-9][a-z0-9-]{{0,38}}[a-z0-9]$"
+        )));
+    }
+    let data_dir = &ctx.state.delete_cfg.data_dir;
+    match crate::examples::get(&ctx.state.store, data_dir, name)
+        .await
+        .map_err(internal)?
+    {
+        None => {
+            let valid = crate::examples::list(&ctx.state.store, data_dir, template)
+                .await
+                .map_err(internal)?;
+            Err(ToolError::invalid_argument(format!(
+                "unknown example {name:?}; pick one of: {}",
+                valid
+                    .iter()
+                    .map(|example| example.name.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            )))
+        }
+        Some(example) => {
+            if template.is_some_and(|template| example.template != template.id()) {
+                return Err(ToolError::invalid_argument(format!(
+                    "example {name:?} is for template {:?}, not {:?}",
+                    example.template,
+                    template.map(|template| template.id())
+                )));
+            }
+            Ok(render_example(&example))
+        }
+    }
+}
+
+/// The README, then each file as a fenced block headed by its path, cut at
+/// the output budget exactly like `read_files`.
+fn render_example(example: &crate::examples::Example) -> Value {
+    let mut used = 0usize;
+    let mut spent = false;
+    let mut truncated = false;
+    let mut files = Vec::with_capacity(example.files.len());
+    let mut blocks = Vec::with_capacity(example.files.len() + 1);
+    blocks.push(example.readme.clone());
+    for file in &example.files {
+        if spent {
+            files.push(json!({
+                "path": file.path,
+                "code": "invalid_argument",
+                "error": "skipped: the 200 KB output budget is exhausted by earlier files",
+            }));
+            blocks.push(format!(
+                "## {}\n(skipped: output budget exhausted)",
+                file.path
+            ));
+            truncated = true;
+            continue;
+        }
+        let block = format!("## {}\n```\n{}\n```", file.path, file.text);
+        if used + block.len() > MAX_EXAMPLE_OUTPUT_BYTES {
+            let room = MAX_EXAMPLE_OUTPUT_BYTES.saturating_sub(used);
+            let cut = truncate_utf8(&block, room);
+            // A file cut to nothing is an inline skip, not an empty read.
+            if cut.is_empty() {
+                files.push(json!({
+                    "path": file.path,
+                    "code": "invalid_argument",
+                    "error": "skipped: the 200 KB output budget is exhausted by earlier files",
+                }));
+                blocks.push(format!(
+                    "## {}\n(skipped: output budget exhausted)",
+                    file.path
+                ));
+            } else {
+                files.push(json!({
+                    "path": file.path,
+                    "text": cut,
+                    "truncated": true,
+                }));
+                blocks.push(format!("{cut}\n(truncated at the 200 KB output budget)"));
+            }
+            used = MAX_EXAMPLE_OUTPUT_BYTES;
+            spent = true;
+            truncated = true;
+        } else {
+            used += block.len();
+            files.push(json!({"path": file.path, "text": file.text}));
+            blocks.push(block);
+        }
+    }
+    ok(
+        blocks.join("\n\n"),
+        json!({
+            "name": example.name,
+            "title": example.title,
+            "template": example.template,
+            "dependencies": example.dependencies,
+            "readme": example.readme,
+            "files": files,
+            "truncated": truncated,
+        }),
+    )
+}
diff --git a/crates/outer/src/mcp/tools/mod.rs b/crates/outer/src/mcp/tools/mod.rs
index 91f2f0c..4b6f2f0 100644
--- a/crates/outer/src/mcp/tools/mod.rs
+++ b/crates/outer/src/mcp/tools/mod.rs
@@ -15,6 +15,7 @@ pub(crate) mod data;
 pub(crate) mod diagnostics;
 pub(crate) mod domains;
 pub(crate) mod drafts;
+pub(crate) mod examples;
 pub(crate) mod export;
 pub(crate) mod look;
 pub(crate) mod open_app;
@@ -1237,6 +1238,9 @@ pub async fn dispatch(tool: &str, args: Option<Value>, ctx: &Ctx<'_>) -> Result<
         "restore_backup" => backups::restore_backup(parse_args(args)?, ctx)
             .await
             .map_err(CallError::from),
+        "examples" => examples::examples(parse_args(args)?, ctx)
+            .await
+            .map_err(CallError::from),
         _ => Err(CallError::Rpc(-32602, format!("unknown tool {tool:?}"))),
     }
 }
diff --git a/crates/outer/src/mcp/tools/open_app.rs b/crates/outer/src/mcp/tools/open_app.rs
index c36fdc0..ec0f7b5 100644
--- a/crates/outer/src/mcp/tools/open_app.rs
+++ b/crates/outer/src/mcp/tools/open_app.rs
@@ -879,6 +879,9 @@ pub async fn open_app_impl(input: OpenAppInput, ctx: &Ctx<'_>) -> Result<Value,
     next.push(
         "app_metrics {app} shows requests, visitors, errors and latency; db_query {app, sql} reads live D1 rows (single SELECT only)".to_string(),
     );
+    next.push(
+        "examples lists ready patterns for apps and sites; examples {name} returns the README and files to copy".to_string(),
+    );
 
     let summary = format!("{} at {}.", app.slug, &head[..head.len().min(12)]);
     Ok(ok(
diff --git a/crates/outer/src/templates.rs b/crates/outer/src/templates.rs
index 725bda7..971d460 100644
--- a/crates/outer/src/templates.rs
+++ b/crates/outer/src/templates.rs
@@ -92,6 +92,15 @@ pub fn write_brand(
     crate::brand::write_brand_file(tree, &brand)
 }
 
+/// The `current.json` pointer [`sync`] vendors, if it has ever run: the
+/// commit [`materialize`] and the examples reader serve from.
+pub async fn current_reference(store: &Store) -> anyhow::Result<Option<TemplateRef>> {
+    match store.get(CURRENT_KEY).await? {
+        None => Ok(None),
+        Some(bytes) => Ok(Some(serde_json::from_slice(&bytes)?)),
+    }
+}
+
 /// Key of the vendored bundle for `sha` in the store.
 fn bundle_key(sha: &str) -> String {
     format!("outer/templates/{sha}.bundle")
@@ -111,7 +120,7 @@ pub struct TemplateRef {
 }
 
 /// Run git with a quiet, non-interactive env and a timeout.
-async fn run_git(
+pub(crate) async fn run_git(
     args: &[&str],
     cwd: Option<&Path>,
     env: &[(&str, &str)],
diff --git a/web/docs/agents/backend/database.md b/web/docs/agents/backend/database.md
index ee23aeb..cf834b6 100644
--- a/web/docs/agents/backend/database.md
+++ b/web/docs/agents/backend/database.md
@@ -44,7 +44,7 @@ await db.prepare("INSERT INTO item (text) VALUES (?)").bind(text).run();
 await db.prepare("DELETE FROM item WHERE id = ?").bind(id).run();
 ```
 
-Apps with no migration files skip the migrate step, so creating tables where you use them keeps working for tiny apps (`CREATE TABLE IF NOT EXISTS`, as the starter does).
+Apps with no migration files skip the migrate step, so creating tables where you use them keeps working for tiny apps (`CREATE TABLE IF NOT EXISTS`, as the examples do).
 
 Drizzle is optional: define tables in `db/schema.ts` with `void/schema-d1`, import them through the `@schema` alias, and query through `db` from `void/db`:
 
diff --git a/web/docs/agents/frontend/void.md b/web/docs/agents/frontend/void.md
index 389b617..a53f60b 100644
--- a/web/docs/agents/frontend/void.md
+++ b/web/docs/agents/frontend/void.md
@@ -3,7 +3,7 @@ title: Load data and handle forms with Void
 description: Write Void loaders, intent actions, forms, links, and routes.
 ---
 
-Put data loading in `pages/*.server.ts` and rendering in `pages/*.tsx`. Copy the starter shape below.
+Put data loading in `pages/*.server.ts` and rendering in `pages/*.tsx`. Copy this page-loader shape for a form:
 
 ```ts
 // pages/index.server.ts
diff --git a/web/docs/agents/start-here/examples.md b/web/docs/agents/start-here/examples.md
new file mode 100644
index 0000000..8b7b857
--- /dev/null
+++ b/web/docs/agents/start-here/examples.md
@@ -0,0 +1,38 @@
+---
+title: Examples
+description: Copy proven patterns onto the empty shell with the examples tool.
+---
+
+New apps are empty branded shells: layout, brand, settings, and nothing to
+delete. Real features live in the examples, served over MCP from the pinned
+templates repo.
+
+## List them
+
+Call `examples` with no arguments. Filter with `template: "app"` or
+`template: "website"`. Each row names the pattern, its template, its
+dependencies, and its files with line counts. The result ends with its own
+`next` step.
+
+## Copy one
+
+Call `examples {name}`. The result is the pattern's README first, then each
+file as a fenced block headed by its path. The README is written for you:
+what the pattern shows, then numbered steps. Follow them in order:
+
+1. Copy each file to the same path in the app repo.
+2. Add the page to `pages/_nav.ts`.
+3. Add any dependency to `package.json`, or any binding to `void.config.ts`.
+4. Rename the migration when the app already has migrations.
+5. Finish with the README's gotchas, then verify with `look_at_app`.
+
+Files are complete and working when copied onto a fresh copy of their
+template, and assume no other example is present. Results past the 200 KB
+output budget arrive truncated: read the rest file by file, or copy what
+arrived and fetch the remainder.
+
+## Unknown names
+
+An unknown name refuses with `invalid_argument` and lists the valid names.
+A misspelled template (`"Website"`, `"static"`) refuses the same way: only
+`"app"` and `"website"` exist.
diff --git a/web/docs/agents/start-here/index.md b/web/docs/agents/start-here/index.md
index cf97747..9af21ed 100644
--- a/web/docs/agents/start-here/index.md
+++ b/web/docs/agents/start-here/index.md
@@ -18,11 +18,13 @@ Each code tool waits for the deploy. It returns `success` with the URL, `failed`
 
 When a tool refuses something, pass its `user_message` to your person verbatim. Never improvise around it or soften the limit.
 
-## Know the starters
+## Know the shells
 
 | Build | Start with |
 | --- | --- |
 | Interactive app: accounts, live state, dashboards, more than one table | [Templates](/agents/start-here/templates) (`app`) |
 | Content site: landing page, portfolio, blog, event page | [Templates](/agents/start-here/templates) (`website`) |
 
+Both shells are empty branded shells with nothing to delete. Copy ready patterns from [Examples](/agents/start-here/examples): `examples` lists them, `examples {name}` returns the README and files.
+
 New to the loop? Work [Quickstart](/agents/start-here/quickstart) end to end. The person-facing version lives at [Quickstart](/get-started/quickstart).
diff --git a/web/docs/agents/start-here/meta.ts b/web/docs/agents/start-here/meta.ts
index 2b6542e..056807a 100644
--- a/web/docs/agents/start-here/meta.ts
+++ b/web/docs/agents/start-here/meta.ts
@@ -4,5 +4,5 @@ export default defineMeta({
   title: "Start here",
   icon: "rocket",
   order: 1,
-  pages: ["index", "quickstart", "templates"],
+  pages: ["index", "quickstart", "templates", "examples"],
 });
diff --git a/web/docs/agents/start-here/quickstart.md b/web/docs/agents/start-here/quickstart.md
index 6a54f19..2979ecc 100644
--- a/web/docs/agents/start-here/quickstart.md
+++ b/web/docs/agents/start-here/quickstart.md
@@ -20,7 +20,7 @@ Keep the first prompt to one screen: no login, no database yet.
 
 > Build a grocery list app for my family on Outer. One page: an input to add items, a list with checkboxes, a filter for bought vs. still needed. No login, no sharing yet — just the list.
 
-Before writing code, read the Ilha guide and the Void guide ([Void](/agents/frontend/void), [Ilha](/agents/frontend/ilha)). Then call `create_app` with a caller-picked slug, plus `name` and `description` so the app is branded from the first commit (see [Templates](/agents/start-here/templates)). A live app serves at `https://<slug>.outer.now` in seconds. Apps are unlisted by default: reachable by link, not indexed. For a landing page, portfolio, or blog, pass `template: "website"`. Then orient with `open_app {app}`: routes, tables, brand and rules in one call.
+Before writing code, read the Ilha guide and the Void guide ([Void](/agents/frontend/void), [Ilha](/agents/frontend/ilha)). Then call `create_app` with a caller-picked slug, plus `name` and `description` so the app is branded from the first commit (see [Templates](/agents/start-here/templates)). New apps are empty branded shells with nothing to delete: call [`examples`](/agents/start-here/examples) for ready patterns (forms + D1, passkey accounts, photo upload, blog, newsletter) and copy what the build needs. A live app serves at `https://<slug>.outer.now` in seconds. Apps are unlisted by default: reachable by link, not indexed. For a landing page, portfolio, or blog, pass `template: "website"`. Then orient with `open_app {app}`: routes, tables, brand and rules in one call.
 
 ## Make one small change
 
diff --git a/web/docs/agents/start-here/templates.md b/web/docs/agents/start-here/templates.md
index 1eb3623..11b9385 100644
--- a/web/docs/agents/start-here/templates.md
+++ b/web/docs/agents/start-here/templates.md
@@ -1,9 +1,9 @@
 ---
 title: Templates
-description: Pick the app or website starter, pass the template param, and rebuild instead of stretching.
+description: Pick the app or website shell, then copy proven patterns from the examples.
 ---
 
-Every `create_app` seeds from one of two pinned starters. The default is `app`. Pass `template: "website"` for the content-site starter. Both build with `bun run build` and deploy through the same [Pipeline](/agents/deploy/pipeline).
+Every `create_app` seeds an empty branded shell from one of two pinned minimal templates: nothing to delete, no demo to strip out. The default is `app`. Pass `template: "website"` for the content-site shell. Both build with `bun run build` and deploy through the same [Pipeline](/agents/deploy/pipeline).
 
 ## Brand the app at creation
 
@@ -11,7 +11,7 @@ Pass `name` (1–60 chars) and `description` (1–160 chars) to `create_app`: bo
 
 `brand.json` is the one place to rename or rebrand an app: edit it with `commit`, never the generated outputs.
 
-## Pick the right starter
+## Pick the right shell
 
 | Build | Template |
 | --- | --- |
@@ -23,9 +23,15 @@ Both live in [ryuzcorp/outer-templates](https://github.com/ryuzcorp/outer-templa
 
 ## Know what each ships
 
-The `app` template serves server-rendered Ilha pages in `pages/` with loaders + actions on D1 and `useForm` for mutations. Call `open_app {app}` first (it carries the `AGENTS.md` rules digest), then read the [Ilha](/agents/frontend/ilha) and [Void](/agents/frontend/void) guides before writing code.
+Both shells are minimal: layout, brand pipeline, settings, PWA shell, 404, and (for `app`) the D1 binding with an empty `db/migrations/` folder. No demo feature, no sample data.
 
-The `website` template serves mostly static, prerendered Astro pages with Ilha islands for interactive parts, at most one D1 database and one R2 bucket. Call `open_app {app}` first (it carries the `AGENTS.md` rules digest), then read [Website](/agents/frontend/website).
+The `app` shell serves server-rendered Ilha pages in `pages/` with loaders + actions on D1 and `useForm` for mutations. Call `open_app {app}` first (it carries the `AGENTS.md` rules digest), then read the [Ilha](/agents/frontend/ilha) and [Void](/agents/frontend/void) guides before writing code.
+
+The `website` shell serves mostly static, prerendered Astro pages with Ilha islands for interactive parts, at most one D1 database and one R2 bucket. Call `open_app {app}` first (it carries the `AGENTS.md` rules digest), then read [Website](/agents/frontend/website).
+
+## Copy patterns from the examples
+
+Real features live in [Examples](/agents/start-here/examples): `examples` lists them, `examples {name}` returns the README and files to copy onto the fresh shell. Copy each file to the same path, add the page to `pages/_nav.ts`, add any dependency or binding, and rename the migration when the app already has migrations.
 
 ## Rebuild, never stretch
 
diff --git a/web/docs/backend/database.mdx b/web/docs/backend/database.mdx
index 117731d..a36f153 100644
--- a/web/docs/backend/database.mdx
+++ b/web/docs/backend/database.mdx
@@ -9,7 +9,7 @@ Your app comes with its database switched on. You ask for features that need sav
 
 Your app gets one database (D1) and one file bucket. Asking for a second one fails the deploy, so keep everything in the single database.
 
-The starter list pattern, a page that reads the database plus forms that write to it, covers most needs.
+The examples' list pattern — a page that reads the database plus forms that write to it — covers most needs.
 
 ## How schema changes ship
 
diff --git a/web/docs/get-started/connect.mdx b/web/docs/get-started/connect.mdx
index 97ca963..ac6ee45 100644
--- a/web/docs/get-started/connect.mdx
+++ b/web/docs/get-started/connect.mdx
@@ -41,7 +41,7 @@ written for you. Your agent relays it word for word.
 
 ## What your agent builds
 
-One of two starters ([Pick a template](/get-started/templates)): the interactive
+One of two empty shells ([Pick a template](/get-started/templates)): the interactive
 `app` (Ilha and Void: lists, dashboards, anything with accounts), or the
 `website` (Astro content site: landing pages, portfolios, blogs). Name
 which one in your first prompt; the default is `app`.
diff --git a/web/docs/get-started/quickstart.mdx b/web/docs/get-started/quickstart.mdx
index a774dfc..89cf84e 100644
--- a/web/docs/get-started/quickstart.mdx
+++ b/web/docs/get-started/quickstart.mdx
@@ -32,7 +32,7 @@ Taken slugs are rejected, and deleted names are free to claim again immediately.
 A live Ilha + Void app serves in seconds. Unlisted by default: not indexed,
 reachable by link. Building a landing page, portfolio, or blog instead? Say so
 in the prompt. The agent passes `template: "website"` for the content-site
-starter. See [Templates](/get-started/templates).
+shell, then copies proven patterns with the `examples` tool. See [Templates](/get-started/templates).
 
 ## Make one change
 
diff --git a/web/docs/get-started/templates.mdx b/web/docs/get-started/templates.mdx
index 51b7d36..3032f4f 100644
--- a/web/docs/get-started/templates.mdx
+++ b/web/docs/get-started/templates.mdx
@@ -1,11 +1,10 @@
 ---
 title: Pick a template
-description: Pick the right starter for your idea — an interactive app or a content site.
+description: Pick the right shell for your idea — an empty interactive app or an empty content site.
 ---
 
 Your app gets its name, colour and icon automatically from what you ask for: tell your agent the app's name and what it does in your first prompt. To rename it later, ask your agent — it edits one file (`brand.json`) and everything follows.
-Every Outer app starts from one of two starters. Tell your agent which one
-you want in your first prompt. The default is `app`.
+Every Outer app starts as an empty shell from one of two minimal templates: layout, brand, settings, and nothing to delete. Real features (lists, accounts, uploads, blog, newsletter) come from proven patterns your agent copies over with the `examples` tool. Tell your agent which shell you want in your first prompt. The default is `app`.
 
 Building it? The agent reads Agents → [Templates](/agents/start-here/templates)
 for the technical details.
@@ -21,21 +20,21 @@ for the technical details.
 Ask like this: "Build a portfolio site on Outer with the website template."
 Or: "Build a grocery list app for my family on Outer."
 
-## The app starter
+## The `app` shell
 
 The `app` is an interactive app: accounts, live state,
 dashboards, anything with more than one database table. Pages read and
 write the database directly. Pick it when people
 sign in, save things, or see live updates. Every app is installable on phones: [Install on phones](/frontend/install-on-phones).
 
-## The website starter
+## The `website` shell
 
 The `website` is a content site: landing pages, portfolios, blogs, event
 pages. Pages are mostly static, prerendered HTML with Astro routing. Small
 interactive parts (like a newsletter form) run as islands. It fits at most
 one server route or two talking to D1.
 
-## When your site outgrows the website starter
+## When your site outgrows the website shell
 
 A website that needs sign-in, live collaboration, or a second database
 table has outgrown the website template. Rebuild it on `app` rather than
diff --git a/web/docs/reference/tools.md b/web/docs/reference/tools.md
index db6f05f..2e47d1b 100644
--- a/web/docs/reference/tools.md
+++ b/web/docs/reference/tools.md
@@ -721,3 +721,15 @@ Every Outer tool in `tools/list` order, rendered from the registry. Generated 
 | `binding` | string | no | The D1 binding. Omit to use the app's only declared binding. |
 | `confirm` | string | yes | Must equal `backup_id`: restoring overwrites the live database (a fresh backup is taken first, so a bad restore is itself restorable). |
 
+## `examples`
+
+- **Access:** anyone (no token needed)
+- **Description:** Copy-paste patterns for apps and sites: `examples` lists them, `examples {name}` returns the README and files to copy.
+
+**Input:**
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | no | An example name (`examples` lists them). Omit to list. |
+| `template` | string | no | Only examples for one template: "app" or "website". Omit for both. |
+

From 1e84a0db1f2d81f04ff7a440640110593e612013 Mon Sep 17 00:00:00 2001
From: Ryuz <ryuzer@proton.me>
Date: Tue, 27 Oct 2026 16:52:40 +0100
Subject: [PATCH 2/5] Pin outer-templates c03d37e: minimal shells + examples

---
 crates/outer/src/templates.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/outer/src/templates.rs b/crates/outer/src/templates.rs
index 971d460..dd4cb48 100644
--- a/crates/outer/src/templates.rs
+++ b/crates/outer/src/templates.rs
@@ -21,7 +21,7 @@ use crate::store::Store;
 pub const TEMPLATES_URL: &str = "https://github.com/ryuzcorp/outer-templates";
 /// The pinned commit `outer templates sync` vendors. Repinning is a
 /// one-line change, then `outer templates sync`.
-pub const TEMPLATES_SHA: &str = "1ae125f38bc58c1fbe3cfa8925990a761ed092a6";
+pub const TEMPLATES_SHA: &str = "c03d37e657e05c705f700e829c1938992d5d19f5";
 
 /// The store pointer to the vendored bundle.
 const CURRENT_KEY: &str = "outer/templates/current.json";

From e4f0d1543970b718a2901316489a1d34a8f7b637 Mon Sep 17 00:00:00 2001
From: Ryuz <ryuzer@proton.me>
Date: Tue, 27 Oct 2026 17:02:23 +0100
Subject: [PATCH 3/5] create_app: say live only when the first deploy succeeded

---
 crates/outer/src/mcp/tools/apps.rs | 71 ++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 4 deletions(-)

diff --git a/crates/outer/src/mcp/tools/apps.rs b/crates/outer/src/mcp/tools/apps.rs
index 49399f9..749ad21 100644
--- a/crates/outer/src/mcp/tools/apps.rs
+++ b/crates/outer/src/mcp/tools/apps.rs
@@ -261,14 +261,13 @@ pub async fn create_app(input: CreateAppInput, ctx: &Ctx<'_>) -> Result<Value, T
         _ => "For ready patterns call examples.".to_string(),
     };
     let url = ctx.state.app_url(&app.slug);
+    let lead = seed_deploy_lead(&app.slug, &url, &deploy);
     let summary = match template {
         crate::templates::Template::App => format!(
-            "{} is live at {url}. It's an empty app shell: build what your user asked for. Pages go in pages/ (list them in pages/_nav.ts). {hint}",
-            app.slug,
+            "{lead} It's an empty app shell: build what your user asked for. Pages go in pages/ (list them in pages/_nav.ts). {hint}",
         ),
         crate::templates::Template::Website => format!(
-            "{} is live at {url}. It's an empty website shell: build what your user asked for. Content lives in Astro pages (islands for interactive parts). {hint}",
-            app.slug,
+            "{lead} It's an empty website shell: build what your user asked for. Content lives in Astro pages (islands for interactive parts). {hint}",
         ),
     };
     let structured = json!({
@@ -283,6 +282,33 @@ pub async fn create_app(input: CreateAppInput, ctx: &Ctx<'_>) -> Result<Value, T
     ))
 }
 
+/// The first sentence of `create_app`'s result, true to the seed deploy:
+/// only a `success` says "live". A failed or blocked first deploy names the
+/// step and error so the agent fixes it instead of reporting a dead link;
+/// one still running (`wait: false` or the wait cap) says how to follow it.
+fn seed_deploy_lead(slug: &str, url: &str, deploy: &Value) -> String {
+    let status = deploy["status"].as_str().unwrap_or("unknown");
+    match status {
+        "success" => format!("{slug} is live at {url}."),
+        "failed" | "blocked" => {
+            let step = deploy["failed_step"]
+                .as_str()
+                .map(|step| format!(" at {step}"))
+                .unwrap_or_default();
+            let error = deploy["error"]
+                .as_str()
+                .map(|error| format!(": {error}"))
+                .unwrap_or_default();
+            format!(
+                "{slug} was created, but its first deploy {status}{step}{error}. It is not live yet: fix it and commit (deploy_log {{app}} has the full log)."
+            )
+        }
+        _ => format!(
+            "{slug} was created; its first deploy is {status}. Call deploy_status {{app, wait: true}} until it reports success at {url}."
+        ),
+    }
+}
+
 pub(crate) fn app_status(app: &App, last_status: Option<&str>) -> &'static str {
     if app.expired_at.is_some() {
         return "expired";
@@ -690,3 +716,40 @@ pub async fn rename_app(input: RenameAppInput, ctx: &Ctx<'_>) -> Result<Value, T
         None => Ok(ok(summary, structured)),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::seed_deploy_lead;
+    use serde_json::json;
+
+    const URL: &str = "https://shop.outer.test";
+
+    #[test]
+    fn only_a_successful_seed_deploy_is_reported_live() {
+        let live = seed_deploy_lead("shop", URL, &json!({"status": "success"}));
+        assert_eq!(live, "shop is live at https://shop.outer.test.");
+
+        let failed = seed_deploy_lead(
+            "shop",
+            URL,
+            &json!({
+                "status": "failed",
+                "failed_step": "deploy",
+                "error": "Error: an asset-only project cannot declare Worker bindings",
+            }),
+        );
+        assert!(!failed.contains("is live"), "{failed}");
+        assert!(
+            failed.contains("first deploy failed at deploy: Error: an asset-only project"),
+            "{failed}"
+        );
+
+        let blocked = seed_deploy_lead("shop", URL, &json!({"status": "blocked"}));
+        assert!(blocked.contains("first deploy blocked."), "{blocked}");
+        assert!(!blocked.contains("is live"), "{blocked}");
+
+        let building = seed_deploy_lead("shop", URL, &json!({"status": "building"}));
+        assert!(building.contains("deploy_status"), "{building}");
+        assert!(!building.contains("is live"), "{building}");
+    }
+}

From b8631f9116196d7b5399551fba205c1cdecad569 Mon Sep 17 00:00:00 2001
From: Ryuz <ryuzer@proton.me>
Date: Tue, 27 Oct 2026 17:18:58 +0100
Subject: [PATCH 4/5] Pin outer-templates 368cc59: static website shell, unique
 nav keys, async upload gate

---
 crates/outer/src/templates.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/outer/src/templates.rs b/crates/outer/src/templates.rs
index dd4cb48..d317446 100644
--- a/crates/outer/src/templates.rs
+++ b/crates/outer/src/templates.rs
@@ -21,7 +21,7 @@ use crate::store::Store;
 pub const TEMPLATES_URL: &str = "https://github.com/ryuzcorp/outer-templates";
 /// The pinned commit `outer templates sync` vendors. Repinning is a
 /// one-line change, then `outer templates sync`.
-pub const TEMPLATES_SHA: &str = "c03d37e657e05c705f700e829c1938992d5d19f5";
+pub const TEMPLATES_SHA: &str = "368cc59fa6704e5c3c7662ad84df83b3ae1eb24b";
 
 /// The store pointer to the vendored bundle.
 const CURRENT_KEY: &str = "outer/templates/current.json";

From 865c0bc3733f082fa26629cb6b22f8bd48c07c2b Mon Sep 17 00:00:00 2001
From: Ryuz <ryuzer@proton.me>
Date: Tue, 27 Oct 2026 17:44:50 +0100
Subject: [PATCH 5/5] Deploy: upload before migrating a database the live
 version doesn't declare

---
 crates/outer/src/deploy/manifest.rs       |  204 ++++
 crates/outer/src/deploy/migrate.rs        |   46 +-
 crates/outer/src/deploy/mod.rs            |    1 +
 crates/outer/src/deploy/pipeline.rs       | 1201 +++++++++++++++++----
 crates/outer/src/http/console_data/d1.rs  |   59 +-
 crates/outer/src/http/console_data/mod.rs |   57 +-
 crates/outer/src/mcp/mod.rs               |    8 +-
 crates/outer/src/mcp/tools/mod.rs         |    7 +-
 crates/outer/src/ops.rs                   |    9 +-
 9 files changed, 1268 insertions(+), 324 deletions(-)
 create mode 100644 crates/outer/src/deploy/manifest.rs

diff --git a/crates/outer/src/deploy/manifest.rs b/crates/outer/src/deploy/manifest.rs
new file mode 100644
index 0000000..6c9ccdd
--- /dev/null
+++ b/crates/outer/src/deploy/manifest.rs
@@ -0,0 +1,204 @@
+//! The live manifest celld publishes per upload: `deploy/current.json`
+//! carries the versioned `prefix`, and the authoritative deployed config is
+//! the manifest at `fleets/{slug}/{prefix}/manifest.json`. There is no
+//! `fleets/{slug}/wrangler.json` in the bucket, and the worktree
+//! `dist/wrangler.json` is a wipeable build artifact — so the manifest is
+//! the only source of truth. This is the ONE manifest reader for every
+//! consumer: the console data panels parse bindings out of it, and the
+//! deploy pipeline reads the live version's declared D1 databases out of it
+//! to decide the migrate/upload order. `vars` — which may carry injected
+//! secret values — is never read here and never lands in a response.
+//!
+//! A missing pointer or manifest means never-deployed (`None`); malformed
+//! JSON or an unsafe prefix is an error.
+
+use crate::deploy::migrate::{self, D1Database};
+use crate::store::Store;
+
+/// The deploy pointer's versioned prefix must stay a relative deploy path:
+/// it becomes a store key suffix, so anything absolute or escaping fails the
+/// read instead of probing an unintended key.
+pub fn validate_prefix(prefix: &str) -> anyhow::Result<()> {
+    if prefix.is_empty()
+        || prefix.starts_with('/')
+        || prefix.contains("..")
+        || prefix.contains('\\')
+        || prefix.contains('\0')
+    {
+        anyhow::bail!("deploy pointer prefix {prefix:?} is not a relative deploy path");
+    }
+    Ok(())
+}
+
+/// The live manifest for `slug`, via the scoped store. A missing pointer or
+/// manifest means never-deployed (`None`); malformed JSON or an unsafe
+/// prefix is an error.
+pub async fn deployed_manifest(
+    store: &Store,
+    slug: &str,
+) -> anyhow::Result<Option<serde_json::Value>> {
+    let pointer_key = format!("fleets/{slug}/deploy/current.json");
+    let Some(pointer) = store.get(&pointer_key).await? else {
+        return Ok(None);
+    };
+    let pointer: serde_json::Value = serde_json::from_slice(&pointer)
+        .map_err(|e| anyhow::anyhow!("parsing deploy pointer: {e:#}"))?;
+    let prefix = pointer
+        .get("prefix")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("deploy pointer has no prefix"))?;
+    validate_prefix(prefix)?;
+    let key = format!("fleets/{slug}/{prefix}/manifest.json");
+    let Some(manifest) = store.get(&key).await? else {
+        return Ok(None);
+    };
+    let manifest: serde_json::Value = serde_json::from_slice(&manifest)
+        .map_err(|e| anyhow::anyhow!("parsing deployed manifest: {e:#}"))?;
+    Ok(Some(manifest))
+}
+
+/// The live manifest's declared D1 databases, from `raw_metadata.bindings`:
+/// `type: "d1"` entries map `name` → binding and
+/// `database_name`/`database_id` → identity. Other binding types are ignored.
+/// `vars` — which may carry injected secret values — is never read here and
+/// never lands in the synthesized cwd config, so secrets can't leak through
+/// the materialized project dir or the fake-celld-style logs that read it.
+///
+/// An asset-only live version (no `main_module`) declares nothing: celld
+/// serves it without a worker, so there is no live code that could reach a
+/// database, and migrations must not wait on it.
+pub fn manifest_dbs(manifest: &serde_json::Value) -> anyhow::Result<Vec<D1Database>> {
+    if manifest
+        .get("main_module")
+        .and_then(|v| v.as_str())
+        .is_none()
+    {
+        return Ok(Vec::new());
+    }
+    let Some(bindings) = manifest.pointer("/raw_metadata/bindings") else {
+        return Ok(Vec::new());
+    };
+    let bindings = bindings.as_array().ok_or_else(|| {
+        anyhow::anyhow!("deployed manifest raw_metadata.bindings must be an array")
+    })?;
+    let mut dbs = Vec::new();
+    for (i, entry) in bindings.iter().enumerate() {
+        let obj = entry
+            .as_object()
+            .ok_or_else(|| anyhow::anyhow!("deployed manifest bindings[{i}] must be an object"))?;
+        let kind = obj.get("type").and_then(|v| v.as_str()).ok_or_else(|| {
+            anyhow::anyhow!("deployed manifest bindings[{i}] needs a string type")
+        })?;
+        if kind != "d1" {
+            continue;
+        }
+        let binding = obj.get("name").and_then(|v| v.as_str()).ok_or_else(|| {
+            anyhow::anyhow!("deployed manifest bindings[{i}] needs a string name")
+        })?;
+        let database_name = obj
+            .get("database_name")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| {
+                anyhow::anyhow!("deployed manifest bindings[{i}] needs a string database_name")
+            })?;
+        let database_id = match obj.get("database_id") {
+            None => None,
+            Some(v) => {
+                let id = v.as_str().ok_or_else(|| {
+                    anyhow::anyhow!("deployed manifest bindings[{i}] needs a string database_id")
+                })?;
+                migrate::validate_database_id(id)
+                    .map_err(|e| anyhow::anyhow!("deployed manifest bindings[{i}]: {e:#}"))?;
+                Some(id.to_string())
+            }
+        };
+        migrate::validate_database_name(database_name)
+            .map_err(|e| anyhow::anyhow!("deployed manifest bindings[{i}]: {e:#}"))?;
+        dbs.push(D1Database {
+            binding: binding.to_string(),
+            database_name: database_name.to_string(),
+            database_id,
+            migrations_dir: None,
+        });
+    }
+    Ok(dbs)
+}
+
+/// The `database_name`s in `wanted` the live version does not declare, by
+/// name. The pipeline migrates by name (that is what reaches celld's argv),
+/// so the order decision is by name too: any name here means the live fleet
+/// cannot reach that database and the upload must go first.
+pub fn missing_from_live(live: &[D1Database], wanted: &[String]) -> Vec<String> {
+    wanted
+        .iter()
+        .filter(|name| !live.iter().any(|db| &db.database_name == *name))
+        .cloned()
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn manifest_with(main: Option<&str>, bindings: serde_json::Value) -> serde_json::Value {
+        let mut manifest = serde_json::json!({
+            "schema_version": 2,
+            "script_name": "outer-app",
+            "raw_metadata": {
+                "bindings": bindings,
+                "compatibility_date": "2026-09-01",
+            }
+        });
+        if let Some(main) = main {
+            manifest["main_module"] = serde_json::Value::String(main.to_string());
+        }
+        manifest
+    }
+
+    #[test]
+    fn asset_only_live_manifest_declares_nothing() {
+        // A static site's manifest has no worker: even with d1-shaped
+        // bindings present, there is no live code that could reach a
+        // database, so the pipeline must treat every database as missing.
+        let dbs = manifest_dbs(&manifest_with(
+            None,
+            serde_json::json!([{"type": "d1", "name": "DB", "database_name": "site-db"}]),
+        ))
+        .unwrap();
+        assert!(dbs.is_empty());
+        let bare = serde_json::json!({"schema_version": 2, "script_name": "x"});
+        assert!(manifest_dbs(&bare).unwrap().is_empty());
+    }
+
+    #[test]
+    fn worker_manifest_maps_d1_bindings() {
+        let dbs = manifest_dbs(&manifest_with(
+            Some("index.js"),
+            serde_json::json!([
+                {"type": "d1", "name": "DB", "database_name": "app-db", "database_id": "abc-123"},
+                {"type": "kv_namespace", "name": "CACHE", "namespace_id": "kv-1"},
+            ]),
+        ))
+        .unwrap();
+        assert_eq!(dbs.len(), 1);
+        assert_eq!(dbs[0].binding, "DB");
+        assert_eq!(dbs[0].effective_identity(), "abc-123");
+    }
+
+    #[test]
+    fn missing_from_live_reports_undeclared_names() {
+        let live = manifest_dbs(&manifest_with(
+            Some("index.js"),
+            serde_json::json!([{"type": "d1", "name": "DB", "database_name": "app-db"}]),
+        ))
+        .unwrap();
+        assert!(
+            missing_from_live(&live, &["app-db".to_string()]).is_empty(),
+            "a declared database needs no upload-first"
+        );
+        assert_eq!(
+            missing_from_live(&live, &["app-db".to_string(), "site-db".to_string()]),
+            vec!["site-db".to_string()]
+        );
+    }
+}
diff --git a/crates/outer/src/deploy/migrate.rs b/crates/outer/src/deploy/migrate.rs
index cf3c818..9d0648a 100644
--- a/crates/outer/src/deploy/migrate.rs
+++ b/crates/outer/src/deploy/migrate.rs
@@ -2,24 +2,34 @@
 //!
 //! After the gate passes, the pipeline applies pending
 //! `NNNN_description.sql` files with `celld d1 migrations apply` under the
-//! app's scoped credentials. For an app with a live version the apply runs
-//! BEFORE the `celld deploy` upload: celld offers no staged upload (the
-//! upload publishes `deploy/current.json` and every fleet adopts it on its
-//! own poll), so ordering is the only gate — when the new pointer becomes
-//! visible the schema is already ready, and a migrate failure uploads
-//! nothing, so no fleet can ever serve new code against an unmigrated
-//! schema. For a first deploy the order reverses: the apply needs a running
-//! node (found through the bucket's node leases) and nothing is published
-//! yet, so the upload goes first, the fleet wakes, and the migrations apply
-//! after — and only a migrate success marks the app live. The proxy refuses
-//! to forward for an app with no successful deploy, so the uploaded-but-
-//! unmigrated code is never served. celld reads the files relative to the
-//! deploy root, orders them by numeric prefix, and records applied
-//! files by name in the app's own `d1_migrations` table (the same table and
-//! columns `wrangler d1 migrations` uses, so the two never re-apply each
-//! other's files). Outer additionally pins the sha256 it saw in
-//! `d1_migration`, so a file edited after it was applied fails the deploy
-//! instead of silently drifting from what the database runs.
+//! app's scoped credentials. When the live version declares every database
+//! being migrated, the apply runs BEFORE the `celld deploy` upload: celld
+//! offers no staged upload (the upload publishes `deploy/current.json` and
+//! every fleet adopts it on its own poll), so ordering is the only gate —
+//! when the new pointer becomes visible the schema is already ready, and a
+//! migrate failure uploads nothing, so no fleet can ever serve new code
+//! against an unmigrated schema. The old code keeps serving during the
+//! migration (expand-first for destructive changes).
+//!
+//! Otherwise the order reverses: the upload goes first, then the wake, then
+//! the migrations. That is the first-deploy case (the apply needs a running
+//! node, found through the bucket's node leases, and nothing is published
+//! yet, so the fleet must be started by the upload) and the
+//! live-lacks-the-database case (the live manifest declares no D1 database
+//! being migrated — an asset-only live version, a first D1, a renamed
+//! database — so the woken live fleet cannot run the migration at all). The
+//! proxy refuses to forward for an app with no successful deploy, so an
+//! uploaded-but-unmigrated first deploy is never served; an uploaded-but-
+//! unmigrated existing app IS served (the pointer moved), so the deploy
+//! fails at `migrate` with an error that says the new version is live
+//! without the migrations, and the app's live pointer moves anyway.
+//! celld reads the files relative to the deploy root, orders them by
+//! numeric prefix, and records applied files by name in the app's own
+//! `d1_migrations` table (the same table and columns `wrangler d1
+//! migrations` uses, so the two never re-apply each other's files). Outer
+//! additionally pins the sha256 it saw in `d1_migration`, so a file edited
+//! after it was applied fails the deploy instead of silently drifting from
+//! what the database runs.
 //!
 //! Security model: everything celld reads or Outer copies here is
 //! attacker-influenced (the app's built config and build output are written
diff --git a/crates/outer/src/deploy/mod.rs b/crates/outer/src/deploy/mod.rs
index 848fa75..7341fc5 100644
--- a/crates/outer/src/deploy/mod.rs
+++ b/crates/outer/src/deploy/mod.rs
@@ -5,6 +5,7 @@
 //! module owns everything under `src/deploy/`.
 
 pub mod check;
+pub mod manifest;
 pub mod migrate;
 pub mod pipeline;
 
diff --git a/crates/outer/src/deploy/pipeline.rs b/crates/outer/src/deploy/pipeline.rs
index 3bc70b9..67e1d20 100644
--- a/crates/outer/src/deploy/pipeline.rs
+++ b/crates/outer/src/deploy/pipeline.rs
@@ -12,11 +12,15 @@
 //! Concurrency: a global semaphore bounds simultaneous builds and a per-app
 //! mutex serializes deploys of the same app. The `deploy` row is inserted as
 //! are held, and to `deploying` before the migrate/upload steps run. The
-//! migrate step runs under the same `deploying` status, before the upload
-//! for an existing app and after it for a first deploy: a blocked deploy
-//! (gate) never touches app data, a failed migration on an existing app
-//! leaves the previous version serving, and a failed first-deploy migration
-//! leaves the app not-live.
+//! migrate step runs under the same `deploying` status: before the upload
+//! when the live version declares every database being migrated (so a
+//! migrate failure uploads nothing and the previous version keeps serving),
+//! after the upload when there is no live version yet or the live version
+//! does not declare a database being migrated (the old code cannot reach
+//! that database, so nothing old depends on it). A failed migration after
+//! the upload means the new version is already published: the deploy still
+//! fails at `migrate`, with an error that says so, but the app's live
+//! pointer moves to the new version.
 
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
@@ -30,6 +34,7 @@ use tokio::sync::{Mutex as AsyncMutex, Semaphore};
 
 use crate::apps::{self, App};
 use crate::cron;
+use crate::deploy::manifest as live_manifest;
 use crate::deploy::migrate;
 use crate::fleet::cgroups;
 use crate::fleet::manager::FleetStorage;
@@ -37,6 +42,7 @@ use crate::fleet::sandbox::{self, Sandbox};
 use crate::git::manifest::{self, GitConfig};
 use crate::moderation::gate;
 use crate::moderation::jev::JevClient;
+use crate::store::Store;
 
 /// What the pipeline needs: dirs, tool paths, storage creds, timeouts.
 #[derive(Clone)]
@@ -352,6 +358,27 @@ impl DeployKind {
         matches!(self, DeployKind::Preview)
     }
 }
+/// Where the D1 migrate step runs relative to the `celld deploy` upload.
+/// For an app with a live version the default is before the upload: when
+/// the new pointer becomes visible the schema is already ready, and a
+/// migrate failure uploads nothing. The upload goes first when there is no
+/// live fleet that could apply the migrations — no live version yet, or a
+/// live version that does not declare a database being migrated (asset-only
+/// sites, a first D1, a renamed database): the old code cannot reach that
+/// database anyway. A migrate failure after the upload still fails the
+/// deploy, but the new version is already published (see `StepFailed`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum MigrateOrder {
+    /// Migrate before uploading; a failure uploads nothing.
+    BeforeUpload,
+    /// First deploy: upload, wake the fleet, then migrate. Only a migrate
+    /// success marks the app live.
+    AfterUploadFirstDeploy,
+    /// The live version does not declare a database being migrated: upload,
+    /// wake, then migrate. A migrate failure still publishes the new
+    /// version, without the migrations.
+    AfterUploadLiveLacksDb,
+}
 pub struct Deployer {
     settings: DeploySettings,
     semaphore: Arc<Semaphore>,
@@ -657,6 +684,7 @@ impl Deployer {
     pub async fn deploy(
         &self,
         pool: &SqlitePool,
+        store: &Store,
         git: &GitConfig,
         app: &App,
         sha: &str,
@@ -666,7 +694,7 @@ impl Deployer {
         self.egress()
             .gate(&format!("build {} for {}", sha, app.slug))?;
         let slug = app.slug.clone();
-        self.deploy_inner(pool, git, app, &slug, DeployKind::Main, sha)
+        self.deploy_inner(pool, store, git, app, &slug, DeployKind::Main, sha)
             .await
     }
 
@@ -679,6 +707,7 @@ impl Deployer {
     pub async fn deploy_preview(
         &self,
         pool: &SqlitePool,
+        store: &Store,
         git: &GitConfig,
         app: &App,
         sha: &str,
@@ -690,13 +719,26 @@ impl Deployer {
         let Some(preview) = crate::preview::preview_app(app) else {
             anyhow::bail!("no preview fleet for {}", app.slug);
         };
-        self.deploy_inner(pool, git, &preview, &app.slug, DeployKind::Preview, sha)
-            .await
+        self.deploy_inner(
+            pool,
+            store,
+            git,
+            &preview,
+            &app.slug,
+            DeployKind::Preview,
+            sha,
+        )
+        .await
     }
 
+    // Eight params: the run identity (store, fleet app, mirror slug, kind)
+    // rides alongside the deploy identity. Splitting the struct would
+    // obscure the step order below, so the count stays.
+    #[allow(clippy::too_many_arguments)]
     async fn deploy_inner(
         &self,
         pool: &SqlitePool,
+        store: &Store,
         git: &GitConfig,
         app: &App,
         git_slug: &str,
@@ -723,6 +765,7 @@ impl Deployer {
         let result = self
             .run_steps(
                 pool,
+                store,
                 &deploy_id,
                 git,
                 app,
@@ -803,6 +846,42 @@ impl Deployer {
                 let log_tail = tail_cap(&log);
                 let steps_json = steps_json(&steps);
                 finish_failed(pool, &deploy_id, &failed.error, &steps_json, &log_tail).await?;
+                // The migrate step ran after the upload and failed: the new
+                // version is already published, so the app's live state moves
+                // exactly as on success — `last_deploy_sha` names what the
+                // fleet actually serves (the proxy forwards on it), the new
+                // version's crons go live, and the edge cache purges — while
+                // the deploy row (and `app_status`, which reads the latest
+                // row) still reports the migrate failure so the fix happens.
+                // A retry then sees a live version that declares the
+                // database and migrates before uploading again.
+                let reloaded = if failed.uploaded {
+                    // Same validated config the success path syncs: the
+                    // worktree still holds this sha's tree (only a failed
+                    // build wipes it, which never uploads first).
+                    let crons = self
+                        .deploy_root(app)
+                        .map(|(_, crons, _)| crons)
+                        .unwrap_or_default();
+                    match kind {
+                        DeployKind::Main => {
+                            apps::set_last_deploy(pool, &app.id, sha).await?;
+                            cron::sync_app_crons(pool, &app.id, &crons, apps::now_ms()).await?;
+                            let reloaded = reload_if_awake(app).await;
+                            self.spawn_edge_purge(pool, &app.id, &app.slug, kind);
+                            reloaded
+                        }
+                        DeployKind::Preview => {
+                            let _ =
+                                crate::preview::touch_preview(pool, &app.id, apps::now_ms()).await;
+                            let reloaded = reload_if_awake(app).await;
+                            self.spawn_edge_purge(pool, &app.id, &app.slug, kind);
+                            reloaded
+                        }
+                    }
+                } else {
+                    false
+                };
                 Ok(DeployOutcome {
                     deploy_id,
                     sha: sha.to_string(),
@@ -815,7 +894,7 @@ impl Deployer {
                     steps,
                     log_tail,
                     version: None,
-                    reloaded: false,
+                    reloaded,
                 })
             }
         }
@@ -870,17 +949,20 @@ impl Deployer {
     /// the celld version and the validated cron schedules on success. The
     /// review runs before `deploy-root`, and before migrations, so a blocked
     /// deploy never touches the app's data or uploads anything. For an app
-    /// with a live version migrations run before the upload, so no fleet can
-    /// ever serve new code against an unmigrated schema; for a first deploy
-    /// (no successful deploy yet) the upload runs first because `celld d1`
-    /// needs a running fleet and there is nothing to start one from yet.
-    // Nine params: the run identity (fleet app, mirror slug, kind) rides
+    /// whose live version declares every database being migrated, migrations
+    /// run before the upload, so no fleet can ever serve new code against an
+    /// unmigrated schema; otherwise the upload runs first because `celld d1`
+    /// needs a running fleet and there is nothing to start one from yet
+    /// (first deploy) or the live fleet cannot reach the database (the live
+    /// version does not declare it).
+    // Ten params: the run identity (fleet app, mirror slug, kind, store) rides
     // alongside the deploy identity. Splitting the struct would obscure
     // the step order below, so the count stays.
     #[allow(clippy::too_many_arguments)]
     async fn run_steps(
         &self,
         pool: &SqlitePool,
+        store: &Store,
         deploy_id: &str,
         git: &GitConfig,
         app: &App,
@@ -1005,84 +1087,142 @@ impl Deployer {
             }
         };
 
-        // 6+7. D1 migrations and the `celld deploy` upload. For an app with
-        // a live version the migrate step runs before the upload: celld
-        // offers no staged or invisible upload (the upload publishes
-        // `deploy/current.json` and every fleet adopts it on its own poll),
-        // so ordering is the only gate: when the new pointer becomes visible
-        // the schema is already ready, and a migrate failure uploads
-        // nothing, so the previous version keeps serving. The old code keeps
-        // serving during the migration (expand-first for destructive
-        // changes).
+        // 6+7. D1 migrations and the `celld deploy` upload. For an app whose
+        // live version declares every database being migrated, the migrate
+        // step runs before the upload: celld offers no staged or invisible
+        // upload (the upload publishes `deploy/current.json` and every fleet
+        // adopts it on its own poll), so ordering is the only gate: when the
+        // new pointer becomes visible the schema is already ready, and a
+        // migrate failure uploads nothing, so the previous version keeps
+        // serving. The old code keeps serving during the migration
+        // (expand-first for destructive changes).
         //
-        // A first deploy (`last_deploy_sha` is NULL: no successful deploy
-        // yet) reverses the order. `celld d1 migrations apply` finds its
-        // node through the bucket's node leases, and a first deploy has
-        // published nothing yet, so no fleet can start and the wake before
-        // the migrate step times out. The upload goes first, then the wake
-        // (now possible), then the migrations — and only a migrate success
-        // marks the deploy successful. Nothing is served before that: the
-        // proxy refuses to forward for an app with no successful deploy, so
-        // no fleet can serve the new code unmigrated.
+        // Otherwise the upload goes first, then the wake (now possible),
+        // then the migrations. That is the first-deploy case
+        // (`last_deploy_sha` is NULL: no successful deploy yet, so
+        // `celld d1 migrations apply` has no fleet to reach through the
+        // bucket's node leases), and the live-lacks-the-database case: the
+        // live manifest does not declare a database this deploy migrates
+        // (an asset-only live version, a first D1, a renamed database), so
+        // the woken live fleet cannot run the migration — retrying would
+        // fail forever and the site could never gain the database. The old
+        // live code cannot reach that database anyway, so nothing old
+        // depends on the new schema.
         //
         // The live-version signal comes from the row, not the caller's
         // snapshot: a previous deploy may have succeeded after the caller
         // loaded the app (the per-app lock serializes deploys, so the row
         // is current). `last_deploy_sha` NULL means no successful deploy yet.
-        // A preview deploy reads the preview signal instead: the first
-        // preview deploy (no successful preview run yet) uploads before
+        // A preview deploy reads the preview signal (and the preview
+        // manifest) instead: the first preview deploy uploads before
         // migrating for the same lease reason, against the preview fleet.
-        let is_first_deploy = match kind {
-            DeployKind::Main => last_deploy_sha(pool, &app.id)
-                .await
-                .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?
-                .is_none(),
-            DeployKind::Preview => last_preview_success(pool, &app.id)
-                .await
-                .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?
-                .is_none(),
-        };
+        // A missing live manifest keeps the old order (migrate first): with
+        // no signal about the live version, the deploy fails exactly where
+        // it used to instead of guessing.
+        let order = self
+            .migrate_order(pool, store, app, kind, &deploy_root)
+            .await?;
         set_status_blocking(pool, deploy_id)
             .await
             .map_err(StepEnd::Failed)?;
-        if is_first_deploy {
+        if order == MigrateOrder::BeforeUpload {
+            self.migrate_step(pool, app, deploy_id, &deploy_root, order, kind, journal)
+                .await?;
             let version = self
                 .deploy_step(pool, app, deploy_id, &deploy_root, journal)
                 .await?;
-            self.migrate_step(
-                pool,
-                app,
-                deploy_id,
-                &deploy_root,
-                is_first_deploy,
-                kind,
-                journal,
-            )
-            .await?;
             Ok((version, crons))
         } else {
-            self.migrate_step(
-                pool,
-                app,
-                deploy_id,
-                &deploy_root,
-                is_first_deploy,
-                kind,
-                journal,
-            )
-            .await?;
             let version = self
                 .deploy_step(pool, app, deploy_id, &deploy_root, journal)
                 .await?;
+            // A first deploy that fails here leaves the app not-live exactly
+            // as before: the proxy still refuses to forward (it gates on
+            // `last_deploy_sha`), so only a live app's upload-first failure
+            // marks the error published — the fleet already serves the new
+            // version, and the failure path moves the live pointer to it.
+            self.migrate_step(pool, app, deploy_id, &deploy_root, order, kind, journal)
+                .await
+                .map_err(|e| match e {
+                    StepEnd::Failed(mut failed) => {
+                        if order == MigrateOrder::AfterUploadLiveLacksDb {
+                            failed.uploaded = true;
+                        }
+                        StepEnd::Failed(failed)
+                    }
+                    StepEnd::Blocked(blocked) => StepEnd::Blocked(blocked),
+                })?;
             Ok((version, crons))
         }
     }
 
-    /// The `celld deploy <root> ... --json` upload step; returns the version.
+    /// Where the migrate step runs: before the upload when the live version
+    /// declares every database the new config migrates, after the upload
+    /// when there is no live fleet that could apply them. Reads the live
+    /// manifest through the shared `deploy::manifest` reader (the same
+    /// source the console data panels use); for a preview deploy `app` is
+    /// the preview identity, so this reads the preview fleet's manifest. A
+    /// missing manifest keeps `BeforeUpload`; an unreadable store or
+    /// manifest fails the deploy at the migrate step before anything
+    /// uploads.
+    async fn migrate_order(
+        &self,
+        pool: &SqlitePool,
+        store: &Store,
+        app: &App,
+        kind: DeployKind,
+        deploy_root: &DeployRoot,
+    ) -> Result<MigrateOrder, StepEnd> {
+        let is_first_deploy = match kind {
+            DeployKind::Main => last_deploy_sha(pool, &app.id)
+                .await
+                .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?
+                .is_none(),
+            DeployKind::Preview => last_preview_success(pool, &app.id)
+                .await
+                .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?
+                .is_none(),
+        };
+        if is_first_deploy {
+            return Ok(MigrateOrder::AfterUploadFirstDeploy);
+        }
+        // The new config this deploy migrates: the same file the migrate
+        // step reads, so the order and the apply can never disagree. A
+        // config that fails to parse here fails again in the migrate step,
+        // before any upload.
+        let parsed = read_config_file(&deploy_root.config)
+            .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?;
+        let databases = migrate::d1_databases(&parsed)
+            .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?;
+        if databases.is_empty() {
+            return Ok(MigrateOrder::BeforeUpload);
+        }
+        let wanted: Vec<String> = databases
+            .iter()
+            .map(|db| db.database_name.clone())
+            .collect();
+        let live = live_manifest::deployed_manifest(store, &app.slug)
+            .await
+            .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?;
+        let Some(live) = live else {
+            return Ok(MigrateOrder::BeforeUpload);
+        };
+        let live_dbs = live_manifest::manifest_dbs(&live)
+            .map_err(|e| StepEnd::Failed(StepFailed::plain("migrate", &e)))?;
+        if live_manifest::missing_from_live(&live_dbs, &wanted).is_empty() {
+            Ok(MigrateOrder::BeforeUpload)
+        } else {
+            Ok(MigrateOrder::AfterUploadLiveLacksDb)
+        }
+    }
+
+    /// The `celld deploy <root> ... --json` upload; returns the version.
     /// The upload publishes `deploy/current.json`, which every fleet adopts
-    /// on its own poll — so for an existing app it runs after the migrate
-    /// step (a migrate failure uploads nothing at all), while for a first
-    /// deploy it runs first (nothing to start a fleet from otherwise).
+    /// on its own poll — so it runs after the migrate step when the live
+    /// version declares every database being migrated (a migrate failure
+    /// uploads nothing at all), and first when no live fleet could apply the
+    /// migrations (first deploy, or a live version that lacks a database
+    /// being migrated).
     async fn deploy_step(
         &self,
         pool: &SqlitePool,
@@ -1121,10 +1261,11 @@ impl Deployer {
 
     /// The D1 migrations step: pending `NNNN_*.sql` files for the built
     /// config's `d1_databases`, applied with the app's scoped credentials.
-    /// For an existing app this runs before the upload makes the new code
-    /// visible to any fleet; for a first deploy it runs after the upload
-    /// (which is what lets the woken fleet exist at all). No files (or no
-    /// D1) skips the step without waking a sleeping fleet.
+    /// This runs before the upload makes the new code visible to any fleet
+    /// when the live version declares every database being migrated; after
+    /// the upload when there is no live fleet that could apply them (first
+    /// deploy, or a live version that lacks a database being migrated).
+    /// No files (or no D1) skips the step without waking a sleeping fleet.
     // The kind rides along for the wake target and the pin-record switch.
     #[allow(clippy::too_many_arguments)]
     async fn migrate_step(
@@ -1133,14 +1274,14 @@ impl Deployer {
         app: &App,
         deploy_id: &str,
         deploy_root: &DeployRoot,
-        is_first_deploy: bool,
+        order: MigrateOrder,
         kind: DeployKind,
         journal: &mut Journal,
     ) -> Result<(), StepEnd> {
         let Journal { steps, log } = journal;
         let started = Instant::now();
         match self
-            .migrate(pool, app, deploy_id, deploy_root, is_first_deploy, kind)
+            .migrate(pool, app, deploy_id, deploy_root, order, kind)
             .await
         {
             Ok((skipped, out)) => {
@@ -1502,18 +1643,19 @@ impl Deployer {
     /// credentials, and every file present is recorded in `d1_migration` so
     /// a later edit of an applied file fails the deploy instead of drifting.
     /// A failure names the migration file when celld's output identifies it
-    /// and carries an agent-facing line; the fleet is never reloaded, so an
-    /// existing app keeps serving its previous version while a first deploy
-    /// leaves the app not-live (the proxy forwards only after a success).
-    /// `is_first_deploy` selects that wording and the operator-CLI hint
-    /// below; the caller derives it from `last_deploy_sha` being NULL.
+    /// and carries an agent-facing line. When the step runs before the
+    /// upload, the fleet is never reloaded and an existing app keeps serving
+    /// its previous version; when it runs after the upload, the new version
+    /// is already published, so the error says the new version is live
+    /// without the migrations. `order` selects that wording and the
+    /// operator-CLI hint below (which only applies to a first deploy).
     async fn migrate(
         &self,
         pool: &SqlitePool,
         app: &App,
         deploy_id: &str,
         deploy_root: &DeployRoot,
-        is_first_deploy: bool,
+        order: MigrateOrder,
         kind: DeployKind,
     ) -> Result<(bool, String), StepFailed> {
         let root = &deploy_root.root;
@@ -1566,9 +1708,17 @@ impl Deployer {
         // to wake a sleeping fleet.
         // A first deploy that never went live has no previous version: say
         // the app isn't live yet instead of naming one that keeps serving.
+        // After the upload, the migrate failure does not roll the publish
+        // back, so the message must not claim the previous version keeps
+        // serving: it names the new version as live without the migrations.
+        // (Preview keeps its own line: the live app is untouched in every
+        // preview case, matching the first-preview-deploy failure.)
+        let published = kind == DeployKind::Main && order == MigrateOrder::AfterUploadLiveLacksDb;
         let live_line = if kind.is_preview() {
             "Your live app is untouched; only the preview failed to update."
-        } else if is_first_deploy {
+        } else if published {
+            "The new version is live without them — fix the migration and commit again."
+        } else if order == MigrateOrder::AfterUploadFirstDeploy {
             "Your app isn't live yet."
         } else {
             "Your app still shows the previous version."
@@ -1582,17 +1732,40 @@ impl Deployer {
                         .map_err(|e| StepFailed::plain("migrate", &e))?;
                 match recorded {
                     Some(sha) if sha != file.sha256 => {
-                        let error = format!(
-                            "migration {} for database {} was edited after it was applied; \
-                              write a new migration instead",
-                            file.name, db.database_name
-                        );
-                        let user_message = format!(
-                            "Outer couldn't publish this change because migration {} was edited \
-                              after it was already applied to database {}. {live_line} Write a \
-                              new migration file instead of editing an applied one.",
-                            file.name, db.database_name
-                        );
+                        // After the upload the refusal still means the new
+                        // version is live: celld never ran, so it serves
+                        // without this deploy's migration content.
+                        let (error, user_message) = if published {
+                            (
+                                format!(
+                                    "migration {} for database {} was edited after it was applied; \
+                                      the new version is live without it — write a new migration \
+                                      instead and commit again",
+                                    file.name, db.database_name
+                                ),
+                                format!(
+                                    "Outer published this change, but migration {} was edited \
+                                      after it was already applied to database {}. The new version \
+                                      is live without it — write a new migration instead and \
+                                      commit again.",
+                                    file.name, db.database_name
+                                ),
+                            )
+                        } else {
+                            (
+                                format!(
+                                    "migration {} for database {} was edited after it was applied; \
+                                      write a new migration instead",
+                                    file.name, db.database_name
+                                ),
+                                format!(
+                                    "Outer couldn't publish this change because migration {} was edited \
+                                      after it was already applied to database {}. {live_line} Write a \
+                                      new migration file instead of editing an applied one.",
+                                    file.name, db.database_name
+                                ),
+                            )
+                        };
                         return Err(StepFailed::migration(error, user_message));
                     }
                     Some(_) => {}
@@ -1643,7 +1816,10 @@ impl Deployer {
                     // instead of surfacing celld's lease internals. (With a
                     // fleet manager the wake above runs first, so a lease
                     // error there is a real failure, not this hint.)
-                    if is_first_deploy && self.settings.wake.is_none() && text.contains("no node leases") {
+                    if order == MigrateOrder::AfterUploadFirstDeploy
+                        && self.settings.wake.is_none()
+                        && text.contains("no node leases")
+                    {
                         return StepFailed::migration(
                             format!(
                                 "first deploy with D1 migrations needs the server; deploy through MCP \
@@ -1658,6 +1834,10 @@ impl Deployer {
                         );
                     }
                     let failed = migrate::failing_file(&text);
+                    // After the upload the failure still means the new
+                    // version is live, so the message pairs the file with
+                    // that fact instead of claiming the previous version
+                    // keeps serving.
                     let error = match &failed {
                         Some(name) => format!(
                             "migration {name} for database {} failed: {}",
@@ -1670,7 +1850,25 @@ impl Deployer {
                             first_output_line(&text)
                         ),
                     };
+                    let error = if published {
+                        format!("{error}; the new version is live without them — fix the migration and commit again")
+                    } else {
+                        error
+                    };
                     let user_message = match &failed {
+                        Some(name) if published => format!(
+                            "Outer published this change, but migration {name} failed to apply \
+                             to database {}: {}. The new version is live without them — fix \
+                             the migration and commit again.",
+                            db.database_name,
+                            error_detail(&text, Some(name))
+                        ),
+                        None if published => format!(
+                            "Outer published this change, but the database migrations failed \
+                             to apply: {}. The new version is live without them — fix the \
+                             migration and commit again.",
+                            first_output_line(&text)
+                        ),
                         Some(name) => format!(
                             "Outer couldn't publish this change because migration {name} failed \
                              to apply to database {}: {}. {live_line}",
@@ -1954,11 +2152,17 @@ struct BlockedInfo {
 
 /// A step that failed: its name, the first meaningful output line, and an
 /// optional agent-facing line (the gate sets one for `review_unavailable`,
-/// migrate for file-specific failures).
+/// migrate for file-specific failures). `uploaded` is true when the failure
+/// came after an upload a live fleet already serves (an existing app's
+/// upload-first migrate failure): the failure path still moves the app's
+/// live pointer even though the deploy row records the failure. A first
+/// deploy's upload is never served (the proxy gates on `last_deploy_sha`),
+/// so its migrate failures leave `uploaded` false and the app not-live.
 struct StepFailed {
     step: &'static str,
     error: String,
     user_message: Option<String>,
+    uploaded: bool,
 }
 
 impl StepFailed {
@@ -1976,6 +2180,7 @@ impl StepFailed {
             step,
             error: cap_error(error),
             user_message: None,
+            uploaded: false,
         }
     }
 
@@ -1991,6 +2196,7 @@ impl StepFailed {
             step,
             error: cap_error(error),
             user_message: None,
+            uploaded: false,
         }
     }
 
@@ -2001,18 +2207,22 @@ impl StepFailed {
             step,
             error: "review_unavailable".to_string(),
             user_message: Some(user_message),
+            uploaded: false,
         }
     }
 
     /// For a failed migration: names the file when identifiable, with an
-    /// agent-facing line. The fleet is never reloaded, so an existing app
-    /// keeps serving its previous version while a first deploy stays
-    /// not-live.
+    /// agent-facing line. When the migrate step runs before the upload, the
+    /// fleet is never reloaded and an existing app keeps serving its
+    /// previous version; when it runs after the upload (`uploaded` is set
+    /// by the caller), the new version is already published and the error
+    /// says so.
     fn migration(error: String, user_message: String) -> Self {
         Self {
             step: "migrate",
             error: cap_error(&error),
             user_message: Some(user_message),
+            uploaded: false,
         }
     }
 
@@ -2023,6 +2233,7 @@ impl StepFailed {
             step,
             error: cap_error(&user_message),
             user_message: Some(user_message),
+            uploaded: false,
         }
     }
 }
@@ -3510,7 +3721,7 @@ mod tests {
 
     #[tokio::test]
     async fn failed_deploy_writes_row_and_leaves_last_deploy_sha() {
-        let (_mdir, cfg, _store, _sync, _sha_a, sha_b) = seed_mirror("grocery").await;
+        let (_mdir, cfg, store, _sync, _sha_a, sha_b) = seed_mirror("grocery").await;
         let (_ddir, pool) = test_pool().await;
         let app = test_app(10001);
         sqlx::query(
@@ -3529,7 +3740,10 @@ mod tests {
         // No package.json, no wrangler config: fails at deploy-root.
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(test_settings(data.path().to_path_buf()), 2);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha_b).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("deploy-root"));
         assert!(
@@ -3639,7 +3853,7 @@ mod tests {
 
     #[tokio::test]
     async fn failed_deploy_issues_no_purge() {
-        let (_mdir, cfg, _store, _sync, _sha_a, sha_b) = seed_mirror("grocery").await;
+        let (_mdir, cfg, store, _sync, _sha_a, sha_b) = seed_mirror("grocery").await;
         let (_ddir, pool) = test_pool().await;
         let app = test_app(10001);
         sqlx::query(
@@ -3657,7 +3871,10 @@ mod tests {
         let purge = crate::cloudflare::fake::FakePurge::start().await;
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(purge_settings(&data, &purge), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha_b).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         // No spawn happens on the failure path at all; the settle wait only
         // guards against a stray detached task.
@@ -3734,7 +3951,10 @@ mod tests {
         settings.celld_bin = "/nonexistent/celld-binary".to_string();
         settings.jev = Some(jev_client(&fake.base_url));
         let deployer = Deployer::new(settings, 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "blocked");
         tokio::time::sleep(std::time::Duration::from_millis(300)).await;
         assert_eq!(
@@ -3816,7 +4036,10 @@ mod tests {
         settings.celld_bin = "/nonexistent/celld-binary".to_string();
         settings.jev = Some(jev_client(&fake.base_url));
         let deployer = Deployer::new(settings, 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "blocked");
         assert_eq!(outcome.failed_step.as_deref(), Some("gate"));
         assert_eq!(outcome.reason.as_deref(), Some("profanity"));
@@ -3936,7 +4159,10 @@ mod tests {
         settings.celld_bin = "/nonexistent/celld-binary".to_string();
         settings.jev = Some(jev_client(&fake.base_url));
         let deployer = Deployer::new(settings, 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("gate"));
         assert_eq!(outcome.error.as_deref(), Some("review_unavailable"));
@@ -4225,7 +4451,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
         // A first deploy (`last_deploy_sha` NULL) uploads before it
         // migrates: `celld d1` needs a running fleet and nothing is
@@ -4343,7 +4572,10 @@ exit 0
         let mut settings = migrate_settings(&data, state.path(), &script);
         settings.bun_bin = bun.to_string_lossy().into_owned();
         let deployer = Deployer::new(settings, 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
         // The uploaded config carries the decrypted values: the fresh var,
         // the overwrite winning over code, and the untouched code var.
@@ -4680,7 +4912,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let first = deployer.deploy(&pool, &cfg, &app, &sha_a).await.unwrap();
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
         assert_eq!(first.status, "success", "error: {:?}", first.error);
         // The first deploy has no live version yet, so it uploads before it
         // migrates.
@@ -4723,7 +4958,10 @@ exit 0
         )
         .await
         .unwrap();
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha_b).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
         let names: Vec<&str> = outcome.steps.iter().map(|s| s.name.as_str()).collect();
         assert_eq!(
@@ -4781,7 +5019,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let first = deployer.deploy(&pool, &cfg, &app, &sha_a).await.unwrap();
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
         assert_eq!(first.status, "success", "error: {:?}", first.error);
         assert_eq!(upload_calls(state.path()), 1);
 
@@ -4810,7 +5051,10 @@ exit 0
         )
         .await
         .unwrap();
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha_b).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("migrate"));
         assert_eq!(
@@ -4849,8 +5093,38 @@ exit 0
         assert_eq!(count, 1, "a failed apply records nothing new");
     }
 
+    /// The live manifest celld published for `slug`: `deploy/current.json`
+    /// pointing at a versioned prefix plus the manifest there, in the layout
+    /// `deploy::manifest::deployed_manifest` reads. The fake celld never
+    /// writes these (it has no store handle), so tests seed them directly.
+    async fn seed_live_manifest(store: &Store, slug: &str, manifest: serde_json::Value) {
+        let prefix = "deploy/outer-app/abcd1234";
+        store
+            .put(
+                &format!("fleets/{slug}/deploy/current.json"),
+                format!(
+                    "{{\"script_name\":\"{slug}\",\"version\":\"abcd1234\",\"prefix\":\"{prefix}\"}}"
+                )
+                .into_bytes(),
+            )
+            .await
+            .unwrap();
+        store
+            .put(
+                &format!("fleets/{slug}/{prefix}/manifest.json"),
+                serde_json::to_vec(&manifest).unwrap(),
+            )
+            .await
+            .unwrap();
+    }
+
     #[tokio::test]
-    async fn migrate_skips_when_everything_is_already_applied() {
+    async fn migrate_uploads_first_when_live_manifest_lacks_the_database() {
+        // The live repro: a static site deploys first (no worker, no D1),
+        // then a tree adds the worker, the `d1_databases` binding and its
+        // first migration. The live manifest declares nothing, so the woken
+        // live fleet could never run the apply — retrying would fail forever
+        // and the site could never gain the database. The upload goes first.
         let dir = tempfile::tempdir().unwrap();
         let cfg = GitConfig::new(dir.path().join("git"), None);
         let store = Store::memory();
@@ -4858,48 +5132,128 @@ exit 0
         manifest::init_repo(&store, &cfg, &sync, "grocery")
             .await
             .unwrap();
-        let sha = commit_tree(
-            &cfg,
+        let sha_a = commit::commit(
             &store,
+            &cfg,
             &sync,
             "grocery",
-            vec![write(
-                "db/migrations/0001_init.sql",
-                "CREATE TABLE item (id INTEGER);",
-            )],
+            CommitRequest {
+                message: "static site".to_string(),
+                base: None,
+                changes: commit::CommitChanges {
+                    writes: vec![
+                        write(
+                            "dist/wrangler.json",
+                            r#"{"name":"t","compatibility_date":"2026-01-01"}"#,
+                        ),
+                        write("pages/index.tsx", "export default () => <h1>hi</h1>;"),
+                    ],
+                    edits: vec![],
+                    deletes: vec![],
+                    moves: vec![],
+                    ..Default::default()
+                },
+                author: author(),
+            },
         )
-        .await;
+        .await
+        .unwrap();
 
         let (_ddir, pool) = test_pool().await;
-        let app = test_app(10102);
+        let app = test_app(10120);
         insert_test_app(&pool, &app).await;
         let state = tempfile::tempdir().unwrap();
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let first = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
         assert_eq!(first.status, "success", "error: {:?}", first.error);
-        assert_eq!(apply_calls(state.path()), 1);
 
-        // Same tree again: nothing pending, no second apply, no wake.
-        let second = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
-        assert_eq!(second.status, "success", "error: {:?}", second.error);
-        let migrate = second
-            .steps
-            .iter()
-            .find(|s| s.name == "migrate")
-            .expect("the migrate step is journaled");
-        assert!(migrate.skipped, "all files recorded: {migrate:?}");
+        // The live version celld published: an asset-only manifest with no
+        // worker module and no bindings declares nothing.
+        seed_live_manifest(
+            &store,
+            "grocery",
+            serde_json::json!({
+                "schema_version": 2,
+                "script_name": "grocery",
+                "raw_metadata": {"bindings": []},
+            }),
+        )
+        .await;
+
+        // The newsletter copy: an API route makes it a worker, the binding
+        // appears, and the first migration lands.
+        let sha_b = commit::commit(
+            &store,
+            &cfg,
+            &sync,
+            "grocery",
+            CommitRequest {
+                message: "add newsletter".to_string(),
+                base: Some(sha_a.clone()),
+                changes: commit::CommitChanges {
+                    writes: vec![
+                        write(
+                            "dist/wrangler.json",
+                            r#"{"name":"t","main":"index.js","compatibility_date":"2026-01-01","d1_databases":[{"binding":"DB","database_name":"site-db"}]}"#,
+                        ),
+                        write(
+                            "db/migrations/0001_newsletter.sql",
+                            "CREATE TABLE subscriber (id INTEGER);",
+                        ),
+                    ],
+                    edits: vec![],
+                    deletes: vec![],
+                    moves: vec![],
+                    ..Default::default()
+                },
+                author: author(),
+            },
+        )
+        .await
+        .unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
+        assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
+        let names: Vec<&str> = outcome.steps.iter().map(|s| s.name.as_str()).collect();
         assert_eq!(
-            apply_calls(state.path()),
-            1,
-            "no celld call when nothing is pending"
+            names,
+            [
+                "worktree",
+                "install",
+                "build",
+                "gate",
+                "deploy-root",
+                "deploy",
+                "migrate"
+            ]
         );
+        assert_eq!(
+            call_kinds(state.path()),
+            ["deploy", "deploy", "apply"],
+            "the first deploy uploads, then the D1 deploy uploads before it migrates"
+        );
+        let (last_sha,): (Option<String>,) =
+            sqlx::query_as("SELECT last_deploy_sha FROM app WHERE id = ?1")
+                .bind(&app.id)
+                .fetch_one(&pool)
+                .await
+                .unwrap();
+        assert_eq!(last_sha.as_deref(), Some(sha_b.as_str()));
     }
 
     #[tokio::test]
-    async fn migrate_skips_without_d1_or_files() {
-        // No `d1_databases` declared: the step skips without touching celld.
+    async fn migrate_failure_after_upload_first_is_failed_but_live() {
+        // Same setup, but the first migration is broken: the deploy fails at
+        // `migrate` with an honest error, yet the new version is already
+        // published — so `last_deploy_sha` moves to it instead of pinning
+        // the old version while the fleet serves the new one.
         let dir = tempfile::tempdir().unwrap();
         let cfg = GitConfig::new(dir.path().join("git"), None);
         let store = Store::memory();
@@ -4907,19 +5261,19 @@ exit 0
         manifest::init_repo(&store, &cfg, &sync, "grocery")
             .await
             .unwrap();
-        let sha = commit::commit(
+        let sha_a = commit::commit(
             &store,
             &cfg,
             &sync,
             "grocery",
             CommitRequest {
-                message: "no d1".to_string(),
+                message: "static site".to_string(),
                 base: None,
-                changes: crate::git::commit::CommitChanges {
+                changes: commit::CommitChanges {
                     writes: vec![
                         write(
                             "dist/wrangler.json",
-                            r#"{"name":"t","main":"index.js","compatibility_date":"2026-01-01"}"#,
+                            r#"{"name":"t","compatibility_date":"2026-01-01"}"#,
                         ),
                         write("pages/index.tsx", "export default () => <h1>hi</h1>;"),
                     ],
@@ -4935,50 +5289,474 @@ exit 0
         .unwrap();
 
         let (_ddir, pool) = test_pool().await;
-        let app = test_app(10103);
+        let app = test_app(10121);
         insert_test_app(&pool, &app).await;
         let state = tempfile::tempdir().unwrap();
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
-        assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
-        let migrate = outcome
-            .steps
-            .iter()
-            .find(|s| s.name == "migrate")
-            .expect("the migrate step is journaled");
-        assert!(migrate.skipped);
-        assert!(
-            outcome.log_tail.contains("no d1_databases"),
-            "the journal says why: {}",
-            outcome.log_tail
-        );
-        assert_eq!(apply_calls(state.path()), 0, "celld never runs");
-    }
-
-    #[tokio::test]
-    async fn migrate_skips_with_d1_but_no_files() {
-        let dir = tempfile::tempdir().unwrap();
-        let cfg = GitConfig::new(dir.path().join("git"), None);
-        let store = Store::memory();
-        let sync = GitSync::default();
-        manifest::init_repo(&store, &cfg, &sync, "grocery")
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
             .await
             .unwrap();
-        let sha = commit_tree(&cfg, &store, &sync, "grocery", vec![]).await;
+        assert_eq!(first.status, "success", "error: {:?}", first.error);
+        seed_live_manifest(
+            &store,
+            "grocery",
+            serde_json::json!({
+                "schema_version": 2,
+                "script_name": "grocery",
+                "raw_metadata": {"bindings": []},
+            }),
+        )
+        .await;
 
-        let (_ddir, pool) = test_pool().await;
-        let app = test_app(10104);
-        insert_test_app(&pool, &app).await;
-        let state = tempfile::tempdir().unwrap();
-        let script = install_fake_celld(state.path());
-        let data = tempfile::tempdir().unwrap();
-        let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
-        assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
-        let migrate = outcome
-            .steps
+        let sha_b = commit::commit(
+            &store,
+            &cfg,
+            &sync,
+            "grocery",
+            CommitRequest {
+                message: "broken newsletter migration".to_string(),
+                base: Some(sha_a.clone()),
+                changes: commit::CommitChanges {
+                    writes: vec![
+                        write(
+                            "dist/wrangler.json",
+                            r#"{"name":"t","main":"index.js","compatibility_date":"2026-01-01","d1_databases":[{"binding":"DB","database_name":"site-db"}]}"#,
+                        ),
+                        write(
+                            "db/migrations/0001_newsletter.sql",
+                            "CREATE TABLE oops (;",
+                        ),
+                        write("dist/.fake-fail", "0001_newsletter.sql"),
+                    ],
+                    edits: vec![],
+                    deletes: vec![],
+                    moves: vec![],
+                    ..Default::default()
+                },
+                author: author(),
+            },
+        )
+        .await
+        .unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
+        assert_eq!(outcome.status, "failed");
+        assert_eq!(outcome.failed_step.as_deref(), Some("migrate"));
+        let error = outcome.error.as_deref().unwrap_or("");
+        assert!(
+            error.contains("0001_newsletter.sql") && error.contains("live without them"),
+            "the error names the file and says the new version is live: {error}"
+        );
+        let message = outcome.user_message.as_deref().unwrap_or("");
+        assert!(
+            message.contains("published") && message.contains("live without them"),
+            "the agent learns the version published and the migration did not: {message}"
+        );
+        assert!(
+            outcome.log_tail.contains("0001_newsletter.sql"),
+            "the migration error is in the log tail"
+        );
+        let names: Vec<&str> = outcome.steps.iter().map(|s| s.name.as_str()).collect();
+        assert_eq!(
+            names,
+            [
+                "worktree",
+                "install",
+                "build",
+                "gate",
+                "deploy-root",
+                "deploy",
+                "migrate"
+            ],
+            "the upload ran before the failing migrate"
+        );
+        assert_eq!(
+            call_kinds(state.path()),
+            ["deploy", "deploy", "apply"],
+            "the second deploy uploaded before its migrate failed"
+        );
+        assert_eq!(upload_calls(state.path()), 2);
+        // The new version is what the fleet serves, so the live pointer
+        // moves to it even though the deploy failed; a retry then sees a
+        // live version that declares the database and migrates first.
+        let (last_sha,): (Option<String>,) =
+            sqlx::query_as("SELECT last_deploy_sha FROM app WHERE id = ?1")
+                .bind(&app.id)
+                .fetch_one(&pool)
+                .await
+                .unwrap();
+        assert_eq!(last_sha.as_deref(), Some(sha_b.as_str()));
+        let (count,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM d1_migration")
+            .fetch_one(&pool)
+            .await
+            .unwrap();
+        assert_eq!(count, 0, "a failed apply records nothing");
+    }
+
+    #[tokio::test]
+    async fn migrate_stays_first_when_live_manifest_declares_the_database() {
+        // The positive path, pinned explicitly: the live manifest declares
+        // the database being migrated, so the migrate step still runs before
+        // the upload — and a migrate failure would upload nothing.
+        let dir = tempfile::tempdir().unwrap();
+        let cfg = GitConfig::new(dir.path().join("git"), None);
+        let store = Store::memory();
+        let sync = GitSync::default();
+        manifest::init_repo(&store, &cfg, &sync, "grocery")
+            .await
+            .unwrap();
+        let sha_a = commit_tree(
+            &cfg,
+            &store,
+            &sync,
+            "grocery",
+            vec![write(
+                "db/migrations/0001_init.sql",
+                "CREATE TABLE item (id INTEGER);",
+            )],
+        )
+        .await;
+
+        let (_ddir, pool) = test_pool().await;
+        let app = test_app(10122);
+        insert_test_app(&pool, &app).await;
+        let state = tempfile::tempdir().unwrap();
+        let script = install_fake_celld(state.path());
+        let data = tempfile::tempdir().unwrap();
+        let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
+        assert_eq!(first.status, "success", "error: {:?}", first.error);
+        seed_live_manifest(
+            &store,
+            "grocery",
+            serde_json::json!({
+                "schema_version": 2,
+                "script_name": "grocery",
+                "main_module": "index.js",
+                "raw_metadata": {"bindings": [
+                    {"type": "d1", "name": "DB", "database_name": "app-db"},
+                ]},
+            }),
+        )
+        .await;
+
+        let sha_b = commit::commit(
+            &store,
+            &cfg,
+            &sync,
+            "grocery",
+            CommitRequest {
+                message: "second migration".to_string(),
+                base: Some(sha_a.clone()),
+                changes: commit::CommitChanges {
+                    writes: vec![write(
+                        "db/migrations/0002_add_owner.sql",
+                        "ALTER TABLE item ADD COLUMN owner TEXT;",
+                    )],
+                    edits: vec![],
+                    deletes: vec![],
+                    moves: vec![],
+                    ..Default::default()
+                },
+                author: author(),
+            },
+        )
+        .await
+        .unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
+        assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
+        let names: Vec<&str> = outcome.steps.iter().map(|s| s.name.as_str()).collect();
+        assert_eq!(
+            names,
+            [
+                "worktree",
+                "install",
+                "build",
+                "gate",
+                "deploy-root",
+                "migrate",
+                "deploy"
+            ]
+        );
+        assert_eq!(
+            call_kinds(state.path()),
+            ["deploy", "apply", "apply", "deploy"],
+            "a live version that declares the database migrates before it uploads"
+        );
+        let (last_sha,): (Option<String>,) =
+            sqlx::query_as("SELECT last_deploy_sha FROM app WHERE id = ?1")
+                .bind(&app.id)
+                .fetch_one(&pool)
+                .await
+                .unwrap();
+        assert_eq!(last_sha.as_deref(), Some(sha_b.as_str()));
+    }
+
+    #[tokio::test]
+    async fn migrate_uploads_first_when_the_database_is_renamed() {
+        // The live version declares `app-db`; the new tree renames it to
+        // `site-db`. By name the live version lacks the database being
+        // migrated, so the upload goes first: the old fleet only knows the
+        // old name.
+        let dir = tempfile::tempdir().unwrap();
+        let cfg = GitConfig::new(dir.path().join("git"), None);
+        let store = Store::memory();
+        let sync = GitSync::default();
+        manifest::init_repo(&store, &cfg, &sync, "grocery")
+            .await
+            .unwrap();
+        let sha_a = commit_tree(
+            &cfg,
+            &store,
+            &sync,
+            "grocery",
+            vec![write(
+                "db/migrations/0001_init.sql",
+                "CREATE TABLE item (id INTEGER);",
+            )],
+        )
+        .await;
+
+        let (_ddir, pool) = test_pool().await;
+        let app = test_app(10123);
+        insert_test_app(&pool, &app).await;
+        let state = tempfile::tempdir().unwrap();
+        let script = install_fake_celld(state.path());
+        let data = tempfile::tempdir().unwrap();
+        let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
+        assert_eq!(first.status, "success", "error: {:?}", first.error);
+        seed_live_manifest(
+            &store,
+            "grocery",
+            serde_json::json!({
+                "schema_version": 2,
+                "script_name": "grocery",
+                "main_module": "index.js",
+                "raw_metadata": {"bindings": [
+                    {"type": "d1", "name": "DB", "database_name": "app-db"},
+                ]},
+            }),
+        )
+        .await;
+
+        let sha_b = commit::commit(
+            &store,
+            &cfg,
+            &sync,
+            "grocery",
+            CommitRequest {
+                message: "rename database".to_string(),
+                base: Some(sha_a.clone()),
+                changes: commit::CommitChanges {
+                    writes: vec![
+                        write(
+                            "dist/wrangler.json",
+                            r#"{"name":"t","main":"index.js","compatibility_date":"2026-01-01","d1_databases":[{"binding":"DB","database_name":"site-db"}]}"#,
+                        ),
+                        write(
+                            "db/migrations/0002_add_owner.sql",
+                            "ALTER TABLE item ADD COLUMN owner TEXT;",
+                        ),
+                    ],
+                    edits: vec![],
+                    deletes: vec![],
+                    moves: vec![],
+                    ..Default::default()
+                },
+                author: author(),
+            },
+        )
+        .await
+        .unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
+        assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
+        let names: Vec<&str> = outcome.steps.iter().map(|s| s.name.as_str()).collect();
+        assert_eq!(
+            names,
+            [
+                "worktree",
+                "install",
+                "build",
+                "gate",
+                "deploy-root",
+                "deploy",
+                "migrate"
+            ]
+        );
+        assert_eq!(
+            call_kinds(state.path()),
+            ["deploy", "apply", "deploy", "apply"],
+            "a renamed database uploads before it migrates"
+        );
+        let (last_sha,): (Option<String>,) =
+            sqlx::query_as("SELECT last_deploy_sha FROM app WHERE id = ?1")
+                .bind(&app.id)
+                .fetch_one(&pool)
+                .await
+                .unwrap();
+        assert_eq!(last_sha.as_deref(), Some(sha_b.as_str()));
+    }
+
+    #[tokio::test]
+    async fn migrate_skips_when_everything_is_already_applied() {
+        let dir = tempfile::tempdir().unwrap();
+        let cfg = GitConfig::new(dir.path().join("git"), None);
+        let store = Store::memory();
+        let sync = GitSync::default();
+        manifest::init_repo(&store, &cfg, &sync, "grocery")
+            .await
+            .unwrap();
+        let sha = commit_tree(
+            &cfg,
+            &store,
+            &sync,
+            "grocery",
+            vec![write(
+                "db/migrations/0001_init.sql",
+                "CREATE TABLE item (id INTEGER);",
+            )],
+        )
+        .await;
+
+        let (_ddir, pool) = test_pool().await;
+        let app = test_app(10102);
+        insert_test_app(&pool, &app).await;
+        let state = tempfile::tempdir().unwrap();
+        let script = install_fake_celld(state.path());
+        let data = tempfile::tempdir().unwrap();
+        let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
+        assert_eq!(first.status, "success", "error: {:?}", first.error);
+        assert_eq!(apply_calls(state.path()), 1);
+
+        // Same tree again: nothing pending, no second apply, no wake.
+        let second = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
+        assert_eq!(second.status, "success", "error: {:?}", second.error);
+        let migrate = second
+            .steps
+            .iter()
+            .find(|s| s.name == "migrate")
+            .expect("the migrate step is journaled");
+        assert!(migrate.skipped, "all files recorded: {migrate:?}");
+        assert_eq!(
+            apply_calls(state.path()),
+            1,
+            "no celld call when nothing is pending"
+        );
+    }
+
+    #[tokio::test]
+    async fn migrate_skips_without_d1_or_files() {
+        // No `d1_databases` declared: the step skips without touching celld.
+        let dir = tempfile::tempdir().unwrap();
+        let cfg = GitConfig::new(dir.path().join("git"), None);
+        let store = Store::memory();
+        let sync = GitSync::default();
+        manifest::init_repo(&store, &cfg, &sync, "grocery")
+            .await
+            .unwrap();
+        let sha = commit::commit(
+            &store,
+            &cfg,
+            &sync,
+            "grocery",
+            CommitRequest {
+                message: "no d1".to_string(),
+                base: None,
+                changes: crate::git::commit::CommitChanges {
+                    writes: vec![
+                        write(
+                            "dist/wrangler.json",
+                            r#"{"name":"t","main":"index.js","compatibility_date":"2026-01-01"}"#,
+                        ),
+                        write("pages/index.tsx", "export default () => <h1>hi</h1>;"),
+                    ],
+                    edits: vec![],
+                    deletes: vec![],
+                    moves: vec![],
+                    ..Default::default()
+                },
+                author: author(),
+            },
+        )
+        .await
+        .unwrap();
+
+        let (_ddir, pool) = test_pool().await;
+        let app = test_app(10103);
+        insert_test_app(&pool, &app).await;
+        let state = tempfile::tempdir().unwrap();
+        let script = install_fake_celld(state.path());
+        let data = tempfile::tempdir().unwrap();
+        let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
+        assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
+        let migrate = outcome
+            .steps
+            .iter()
+            .find(|s| s.name == "migrate")
+            .expect("the migrate step is journaled");
+        assert!(migrate.skipped);
+        assert!(
+            outcome.log_tail.contains("no d1_databases"),
+            "the journal says why: {}",
+            outcome.log_tail
+        );
+        assert_eq!(apply_calls(state.path()), 0, "celld never runs");
+    }
+
+    #[tokio::test]
+    async fn migrate_skips_with_d1_but_no_files() {
+        let dir = tempfile::tempdir().unwrap();
+        let cfg = GitConfig::new(dir.path().join("git"), None);
+        let store = Store::memory();
+        let sync = GitSync::default();
+        manifest::init_repo(&store, &cfg, &sync, "grocery")
+            .await
+            .unwrap();
+        let sha = commit_tree(&cfg, &store, &sync, "grocery", vec![]).await;
+
+        let (_ddir, pool) = test_pool().await;
+        let app = test_app(10104);
+        insert_test_app(&pool, &app).await;
+        let state = tempfile::tempdir().unwrap();
+        let script = install_fake_celld(state.path());
+        let data = tempfile::tempdir().unwrap();
+        let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
+        assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
+        let migrate = outcome
+            .steps
             .iter()
             .find(|s| s.name == "migrate")
             .expect("the migrate step is journaled");
@@ -5018,7 +5796,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("migrate"));
         let error = outcome.error.as_deref().unwrap_or("");
@@ -5103,7 +5884,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let failed = deployer.deploy(&pool, &cfg, &app, &sha_a).await.unwrap();
+        let failed = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
         assert_eq!(failed.status, "failed");
         assert_eq!(failed.failed_step.as_deref(), Some("migrate"));
         // Still no successful deploy, so the retry is a first deploy too:
@@ -5136,7 +5920,10 @@ exit 0
         )
         .await
         .unwrap();
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha_b).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
         let names: Vec<&str> = outcome.steps.iter().map(|s| s.name.as_str()).collect();
         assert_eq!(
@@ -5193,7 +5980,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let first = deployer.deploy(&pool, &cfg, &app, &sha_a).await.unwrap();
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
         assert_eq!(first.status, "success", "error: {:?}", first.error);
         assert_eq!(apply_calls(state.path()), 1);
 
@@ -5224,7 +6014,10 @@ exit 0
         )
         .await
         .unwrap();
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha_b).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("migrate"));
         let error = outcome.error.as_deref().unwrap_or("");
@@ -5296,7 +6089,10 @@ exit 0
         settings.bun_bin = "/bin/true".to_string();
         settings.jev = Some(jev_client(&fake.base_url));
         let deployer = Deployer::new(settings, 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "blocked");
         assert_eq!(
             apply_calls(state.path()),
@@ -5346,7 +6142,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
         assert_eq!(apply_calls(state.path()), 1, "one apply for the database");
         let calls = std::fs::read_to_string(state.path().join("calls.log")).unwrap();
@@ -5416,7 +6215,10 @@ exit 0
         let script = install_fake_celld(state.path());
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(migrate_settings(&data, state.path(), &script), 1);
-        let first = deployer.deploy(&pool, &cfg, &app, &sha_a).await.unwrap();
+        let first = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_a)
+            .await
+            .unwrap();
         assert_eq!(first.status, "success", "error: {:?}", first.error);
         assert_eq!(apply_calls(state.path()), 1);
 
@@ -5442,7 +6244,10 @@ exit 0
         )
         .await
         .unwrap();
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha_b).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha_b)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
         assert_eq!(apply_calls(state.path()), 2, "the new identity re-applies");
         let mut identities: Vec<(String,)> =
@@ -5618,7 +6423,10 @@ exit 0
         // bad cron stops the deploy at deploy-root, before celld runs.
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(test_settings(data.path().to_path_buf()), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("deploy-root"));
         assert!(
@@ -5682,7 +6490,10 @@ exit 0
         // message, before migrations or celld run.
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(test_settings(data.path().to_path_buf()), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("deploy-root"));
         assert_eq!(outcome.error.as_deref(), Some(BINDING_CAP_MESSAGE));
@@ -5730,7 +6541,10 @@ exit 0
 
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(test_settings(data.path().to_path_buf()), 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "failed");
         assert_eq!(outcome.failed_step.as_deref(), Some("deploy-root"));
         assert_eq!(outcome.error.as_deref(), Some(BINDING_CAP_MESSAGE));
@@ -5739,7 +6553,7 @@ exit 0
 
     #[tokio::test]
     async fn queued_row_is_visible_while_waiting_for_permits() {
-        let (_mdir, cfg, _store, _sync, _sha_a, sha_b) = seed_mirror("grocery").await;
+        let (_mdir, cfg, store, _sync, _sha_a, sha_b) = seed_mirror("grocery").await;
         let (_ddir, pool) = test_pool().await;
         let app = test_app(10002);
         sqlx::query(
@@ -5754,7 +6568,9 @@ exit 0
         let data = tempfile::tempdir().unwrap();
         let deployer = Deployer::new(test_settings(data.path().to_path_buf()), 0);
         let pool2 = pool.clone();
-        let handle = tokio::spawn(async move { deployer.deploy(&pool2, &cfg, &app, &sha_b).await });
+        let store2 = store.clone();
+        let handle =
+            tokio::spawn(async move { deployer.deploy(&pool2, &store2, &cfg, &app, &sha_b).await });
         tokio::time::sleep(Duration::from_millis(300)).await;
         let (status,): (String,) =
             sqlx::query_as("SELECT status FROM deploy WHERE app_id = 'app1'")
@@ -5870,7 +6686,10 @@ exit 0
             secrets_key: crate::secrets::SecretsKey::test_key(),
         };
         let deployer = Deployer::new(settings, 1);
-        let outcome = deployer.deploy(&pool, &cfg, &app, &sha).await.unwrap();
+        let outcome = deployer
+            .deploy(&pool, &store, &cfg, &app, &sha)
+            .await
+            .unwrap();
         assert_eq!(outcome.status, "success", "error: {:?}", outcome.error);
         assert!(
             outcome.version.is_some(),
diff --git a/crates/outer/src/http/console_data/d1.rs b/crates/outer/src/http/console_data/d1.rs
index d7fd111..60587c3 100644
--- a/crates/outer/src/http/console_data/d1.rs
+++ b/crates/outer/src/http/console_data/d1.rs
@@ -21,7 +21,8 @@ use serde_json::json;
 use sqlx::SqlitePool;
 
 use super::owner_app;
-use crate::deploy::migrate::{self, D1Database};
+use crate::deploy::manifest::manifest_dbs;
+use crate::deploy::migrate::D1Database;
 use crate::fleet::manager::{FleetManager, FleetStorage};
 use crate::http::console::guard;
 use crate::store::Store;
@@ -643,62 +644,6 @@ fn bad_err(err: anyhow::Error) -> D1Error {
     D1Error::BadQuery(format!("{err:#}"))
 }
 
-/// The live manifest's declared D1 databases, from `raw_metadata.bindings`:
-/// `type: "d1"` entries map `name` → binding and
-/// `database_name`/`database_id` → identity. Other binding types are ignored.
-/// `vars` — which may carry injected secret values — is never read here and
-/// never lands in the synthesized cwd config, so secrets can't leak through
-/// the materialized project dir or the fake-celld-style logs that read it.
-fn manifest_dbs(manifest: &serde_json::Value) -> anyhow::Result<Vec<D1Database>> {
-    let Some(bindings) = manifest.pointer("/raw_metadata/bindings") else {
-        return Ok(Vec::new());
-    };
-    let bindings = bindings.as_array().ok_or_else(|| {
-        anyhow::anyhow!("deployed manifest raw_metadata.bindings must be an array")
-    })?;
-    let mut dbs = Vec::new();
-    for (i, entry) in bindings.iter().enumerate() {
-        let obj = entry
-            .as_object()
-            .ok_or_else(|| anyhow::anyhow!("deployed manifest bindings[{i}] must be an object"))?;
-        let kind = obj.get("type").and_then(|v| v.as_str()).ok_or_else(|| {
-            anyhow::anyhow!("deployed manifest bindings[{i}] needs a string type")
-        })?;
-        if kind != "d1" {
-            continue;
-        }
-        let binding = obj.get("name").and_then(|v| v.as_str()).ok_or_else(|| {
-            anyhow::anyhow!("deployed manifest bindings[{i}] needs a string name")
-        })?;
-        let database_name = obj
-            .get("database_name")
-            .and_then(|v| v.as_str())
-            .ok_or_else(|| {
-                anyhow::anyhow!("deployed manifest bindings[{i}] needs a string database_name")
-            })?;
-        let database_id = match obj.get("database_id") {
-            None => None,
-            Some(v) => {
-                let id = v.as_str().ok_or_else(|| {
-                    anyhow::anyhow!("deployed manifest bindings[{i}] needs a string database_id")
-                })?;
-                migrate::validate_database_id(id)
-                    .map_err(|e| anyhow::anyhow!("deployed manifest bindings[{i}]: {e:#}"))?;
-                Some(id.to_string())
-            }
-        };
-        migrate::validate_database_name(database_name)
-            .map_err(|e| anyhow::anyhow!("deployed manifest bindings[{i}]: {e:#}"))?;
-        dbs.push(D1Database {
-            binding: binding.to_string(),
-            database_name: database_name.to_string(),
-            database_id,
-            migrations_dir: None,
-        });
-    }
-    Ok(dbs)
-}
-
 /// The minimal wrangler.json synthesized for the `celld d1 execute` cwd: only
 /// name (script_name), main, compatibility_date/flags, and `d1_databases`
 /// [{binding, database_name, database_id?}]. No vars, nothing else — celld
diff --git a/crates/outer/src/http/console_data/mod.rs b/crates/outer/src/http/console_data/mod.rs
index cef3ef5..6b71204 100644
--- a/crates/outer/src/http/console_data/mod.rs
+++ b/crates/outer/src/http/console_data/mod.rs
@@ -184,58 +184,11 @@ pub(crate) fn deploy_settings(
         .ok_or_else(|| anyhow::anyhow!("storage panels are unavailable in this build"))
 }
 
-/// The deploy pointer celld publishes per upload: `deploy/current.json`
-/// carries the versioned `prefix`, and the authoritative deployed config is
-/// the manifest at `fleets/{slug}/{prefix}/manifest.json`. There is no
-/// `fleets/{slug}/wrangler.json` in the bucket, and the worktree
-/// `dist/wrangler.json` is a wipeable build artifact — so the manifest is
-/// the only source of truth. This is the ONE manifest reader for every
-/// data panel: D1 parses `raw_metadata.bindings` type-d1 entries out of
-/// it, R2 parses `r2_bucket` entries, DO parses top-level
-/// `do_classes`/`sqlite_classes`. `vars` — which may carry injected secret
-/// values — is never read here and never lands in a response.
-///
-/// A missing pointer or manifest means never-deployed (`None`: D1 answers
-/// `NoConfig`, R2/DO fall back to the local build artifact); malformed JSON
-/// or an unsafe prefix is an error.
-pub(crate) async fn deployed_manifest(
-    store: &crate::store::Store,
-    slug: &str,
-) -> anyhow::Result<Option<serde_json::Value>> {
-    let pointer_key = format!("fleets/{slug}/deploy/current.json");
-    let Some(pointer) = store.get(&pointer_key).await? else {
-        return Ok(None);
-    };
-    let pointer: serde_json::Value = serde_json::from_slice(&pointer)
-        .map_err(|e| anyhow::anyhow!("parsing deploy pointer: {e:#}"))?;
-    let prefix = pointer
-        .get("prefix")
-        .and_then(|v| v.as_str())
-        .ok_or_else(|| anyhow::anyhow!("deploy pointer has no prefix"))?;
-    validate_prefix(prefix)?;
-    let key = format!("fleets/{slug}/{prefix}/manifest.json");
-    let Some(manifest) = store.get(&key).await? else {
-        return Ok(None);
-    };
-    let manifest: serde_json::Value = serde_json::from_slice(&manifest)
-        .map_err(|e| anyhow::anyhow!("parsing deployed manifest: {e:#}"))?;
-    Ok(Some(manifest))
-}
-
-/// The deploy pointer's versioned prefix must stay a relative deploy path:
-/// it becomes a store key suffix, so anything absolute or escaping fails the
-/// read instead of probing an unintended key.
-pub(crate) fn validate_prefix(prefix: &str) -> anyhow::Result<()> {
-    if prefix.is_empty()
-        || prefix.starts_with('/')
-        || prefix.contains("..")
-        || prefix.contains('\\')
-        || prefix.contains('\0')
-    {
-        anyhow::bail!("deploy pointer prefix {prefix:?} is not a relative deploy path");
-    }
-    Ok(())
-}
+/// The single live-manifest reader (see `deploy::manifest`): the deploy
+/// pointer celld publishes per upload plus the manifest it points at. R2, DO
+/// and D1 parse their own binding sections out of it; the pipeline reads the
+/// live D1 declarations out of it for the migrate/upload order.
+pub(crate) use crate::deploy::manifest::deployed_manifest;
 
 /// The deploy work dir the built wrangler config is read from at request
 /// time: `dist/wrangler.json`, then `wrangler.jsonc`, then `wrangler.json`
diff --git a/crates/outer/src/mcp/mod.rs b/crates/outer/src/mcp/mod.rs
index afa3b72..860bb39 100644
--- a/crates/outer/src/mcp/mod.rs
+++ b/crates/outer/src/mcp/mod.rs
@@ -138,12 +138,13 @@ impl Deploys {
     pub async fn deploy(
         &self,
         pool: &SqlitePool,
+        store: &Store,
         git: &GitConfig,
         app: &App,
         sha: &str,
     ) -> anyhow::Result<DeployOutcome> {
         match &*self.inner {
-            DeploysInner::Live(deployer) => deployer.deploy(pool, git, app, sha).await,
+            DeploysInner::Live(deployer) => deployer.deploy(pool, store, git, app, sha).await,
             #[cfg(test)]
             DeploysInner::Fake(fake) => fake.deploy(pool, app, sha).await,
         }
@@ -172,12 +173,15 @@ impl Deploys {
     pub async fn deploy_preview(
         &self,
         pool: &SqlitePool,
+        store: &Store,
         git: &GitConfig,
         app: &App,
         sha: &str,
     ) -> anyhow::Result<DeployOutcome> {
         match &*self.inner {
-            DeploysInner::Live(deployer) => deployer.deploy_preview(pool, git, app, sha).await,
+            DeploysInner::Live(deployer) => {
+                deployer.deploy_preview(pool, store, git, app, sha).await
+            }
             #[cfg(test)]
             DeploysInner::Fake(fake) => fake.deploy_preview(pool, app, sha).await,
         }
diff --git a/crates/outer/src/mcp/tools/mod.rs b/crates/outer/src/mcp/tools/mod.rs
index 4b6f2f0..90822fb 100644
--- a/crates/outer/src/mcp/tools/mod.rs
+++ b/crates/outer/src/mcp/tools/mod.rs
@@ -862,6 +862,7 @@ async fn run_deploy_inner(
     check_storage_writable(&state.pool, &state.billing, app).await?;
     let deploys = state.deploys.clone();
     let pool = state.pool.clone();
+    let store = state.store.clone();
     let git = state.git.clone();
     let app_owned = app.clone();
     let sha_owned = sha.to_string();
@@ -882,11 +883,13 @@ async fn run_deploy_inner(
     let handle = tokio::spawn(async move {
         let outcome = match kind {
             crate::deploy::DeployKind::Main => {
-                deploys.deploy(&pool, &git, &app_owned, &sha_owned).await
+                deploys
+                    .deploy(&pool, &store, &git, &app_owned, &sha_owned)
+                    .await
             }
             crate::deploy::DeployKind::Preview => {
                 deploys
-                    .deploy_preview(&pool, &git, &app_owned, &sha_owned)
+                    .deploy_preview(&pool, &store, &git, &app_owned, &sha_owned)
                     .await
             }
         };
diff --git a/crates/outer/src/ops.rs b/crates/outer/src/ops.rs
index 326dc5e..3340731 100644
--- a/crates/outer/src/ops.rs
+++ b/crates/outer/src/ops.rs
@@ -130,7 +130,10 @@ pub async fn create_app(
     // The uid set changed: reinstall at once (best-effort; the sweep tick
     // is the backstop).
     p.egress.refresh(&p.pool).await;
-    let outcome = p.deployer.deploy(&p.pool, &p.git, &app, &sha).await?;
+    let outcome = p
+        .deployer
+        .deploy(&p.pool, &p.store, &p.git, &app, &sha)
+        .await?;
     Ok((app, outcome))
 }
 
@@ -143,7 +146,9 @@ pub async fn deploy_app(p: &Platform, slug: &str) -> anyhow::Result<DeployOutcom
     let sha = manifest::head_of(&bare)
         .await?
         .with_context(|| format!("{slug} has no commits on main"))?;
-    p.deployer.deploy(&p.pool, &p.git, &app, &sha).await
+    p.deployer
+        .deploy(&p.pool, &p.store, &p.git, &app, &sha)
+        .await
 }
 
 /// Delete `slug`: the operator CLI's path to the same core the MCP