diff --git a/.gitignore b/.gitignore
index 7efa7c2..e0f681d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,4 +28,4 @@ dump.rdb
 .shopify.lock
 
 # Local debug output (can contain bearer tokens from --verbose CLI runs)
-dev-log.txt
+dev-log*.txt
diff --git a/README.md b/README.md
index c7360c8..2d6f7e5 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,16 @@ Dev uses Postgres, same as prod, since the schema relies on Prisma enums and
 (from Phase 5 on) array fields that SQLite can't express. `npm run worker`
 runs the BullMQ worker (jobs/worker.ts) once Phase 4 makes it do anything.
 
+**`shopify.web.toml` at the repo root is required** — it tells `shopify app
+dev` how to run this project's Remix app (`[commands] dev = "npm exec remix
+vite:dev"`) and lets the CLI wire that local dev server into its reverse
+proxy/tunnel. Without it, `dev` still runs the extensions fine but never
+starts the actual admin app, and the embedded app will show Shopify's
+generic "Find this app in the pages where you work" fallback with no
+useful error — `application_url`/`redirect_urls` in `shopify.app.toml` are
+placeholders that `dev` overwrites live on Shopify's servers each session
+once this file exists; don't hand-edit them.
+
 ## Commands
 
 | Command | Purpose |
diff --git a/extensions/checkout-datetime/shopify.extension.toml b/extensions/checkout-datetime/shopify.extension.toml
index 98303cf..d3eaa22 100644
--- a/extensions/checkout-datetime/shopify.extension.toml
+++ b/extensions/checkout-datetime/shopify.extension.toml
@@ -39,5 +39,11 @@ api_access = true
 # Gives your extension access to make external network calls, using the
 # JavaScript `fetch()` API. Required — this extension calls our own
 # backend (checkout.scheduling.availability/hold) to share the same
-# capacity pool as every other surface.
+# capacity pool as every other surface. Shopify requires this capability
+# to be reviewed/approved before a version using it can be RELEASED (not
+# just created) — deploys will show "created, but not released" until
+# that approval is granted, which is fine for local dev/testing; it only
+# matters before public launch. (The embedded admin app failing to load
+# was a red herring here — the real cause was a missing shopify.web.toml,
+# see that file's comment.)
 network_access = true
diff --git a/shopify.app.toml b/shopify.app.toml
index c604d5e..f39b410 100644
--- a/shopify.app.toml
+++ b/shopify.app.toml
@@ -1,8 +1,16 @@
 # Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration
 
-client_id = "890f611da9f31c1a8e3183b5300b2f53"
+client_id = "fd503f515942a32aa8b811c1ab8c89d0"
 name = "Metatron-delivery"
-application_url = "https://shopify.dev/apps/default-app-home"
+# Placeholder — `shopify app dev` overwrites this on Shopify's live app
+# record automatically each session (via automatically_update_urls_on_dev
+# below), it does NOT rewrite this file. That auto-update only works
+# because shopify.web.toml exists at the repo root telling the CLI how to
+# run this project's Remix app; without it, the CLI has no local dev-server
+# port to build a tunnel URL from and silently keeps using whatever's here
+# — which is exactly what caused the embedded admin app to never load
+# during initial setup (see shopify.web.toml's own comment).
+application_url = "https://replace-with-your-tunnel-url.example.com"
 embedded = true
 
 [access_scopes]
@@ -17,7 +25,7 @@ embedded = true
 scopes = "read_locales,read_locations,read_markets,read_metaobjects,read_orders,read_products,write_cart_transforms,write_delivery_customizations,write_metaobjects,write_orders,write_payment_customizations"
 
 [auth]
-redirect_urls = [ "https://shopify.dev/apps/default-app-home/api/auth" ]
+redirect_urls = [ "https://replace-with-your-tunnel-url.example.com/auth/callback" ]
 
 [webhooks]
 api_version = "2025-01"
@@ -110,5 +118,4 @@ subpath = "scheduling"
 prefix = "apps"
 
 [build]
-include_config_on_deploy = true
 automatically_update_urls_on_dev = true
diff --git a/shopify.web.toml b/shopify.web.toml
new file mode 100644
index 0000000..4edfbf8
--- /dev/null
+++ b/shopify.web.toml
@@ -0,0 +1,8 @@
+# Tells `shopify app dev` how to run this project's web/admin app (the
+# Remix server everything in app/ belongs to) and lets it wire its local
+# dev server into the CLI's reverse proxy + tunnel. Without this file,
+# `shopify app dev` never starts the Remix app at all — it only runs the
+# theme/function/UI-extension dev servers — which is why the embedded
+# admin app home never loaded no matter what URL configuration was tried.
+[commands]
+dev = "npm exec remix vite:dev"