docs(cli): recommend Docker Deploy for production apps

README.md

@@ -46,10 +46,15 @@ contract.
 
 Point the CLI at any repo and it handles the rest: framework detection, build wiring, GitHub webhook setup, and live log streaming.
 
+For production app hosting, MIOSA recommends Docker Deploy. It runs apps on the
+workspace Docker Deploy runtime, which is the preferred path for teams deploying
+many apps because it gives better runtime packing and lower resource overhead
+than one-off app runtimes.
+
 ```
 $ cd ~/my-project
 $ miosa login
-$ miosa deploy
+$ miosa deploy --docker-deploy
 
   Detected: Next.js 15 (confidence 95%)
   Repo:     https://github.com/me/my-project
@@ -103,6 +108,21 @@ miosa deploy
 miosa deploy redeploy
 ```
 
+For apps built inside a sandbox, promote the sandbox workspace through Docker Deploy:
+
+```bash
+miosa sandbox publish <sandbox-id> \
+  --path /workspace \
+  --slug my-app \
+  --build-command "npm run build" \
+  --run-command "npm run start" \
+  --port 3000 \
+  --docker-deploy \
+  --wait \
+  --timeout 900 \
+  --json
+```
+
 ## Agentic sandbox app templates
 
 Agents should start from app templates instead of empty sandboxes when building common web apps. For a working Next.js starter with a public preview:
@@ -249,6 +269,7 @@ Precedence: CLI flags > environment variables > config file > interactive prompt
 Deploy a GitHub repo. See the [Deploy section](#deploy--60-seconds-to-first-deploy) above for the full flow.
 
 ```bash
+miosa deploy --docker-deploy             # Recommended production deploy
 miosa deploy                             # First deploy or redeploy from .miosa.json
 miosa deploy list [--json]               # List all deployments
 miosa deploy logs [id]                   # Tail live build logs

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miosa/cli",
-  "version": "1.0.49",
+  "version": "1.0.50",
   "description": "MIOSA platform CLI — projects, sandboxes, deploys, databases, more",
   "type": "module",
   "bin": {

src/bin/miosa.ts

@@ -99,6 +99,7 @@ Examples:
   miosa up                                      Smart launch (auto-detects context)
   miosa up --computer --os ubuntu               Create a desktop computer
   miosa up --sandbox --image python-3.12        Create a sandbox
+  miosa deploy --docker-deploy                  Recommended production deploy
   miosa deploy                                  Deploy a GitHub repo (60s)
   miosa update                                  Update @miosa/cli to latest
   miosa status                                  Show auth and account info

src/commands/capabilities.ts

@@ -162,8 +162,8 @@ const manifest: CapabilitiesManifest = {
         "For app templates, prefer --template <id> --auto-start --publish-port <port> --wait --json.",
         "Next.js starter template: miosa sandbox create --template nextjs --auto-start --publish-port 3000 --wait --json.",
         "Use sandbox deploy for preview readiness.",
-        "Use sandbox publish to promote to durable app hosting.",
-        "Use sandbox publish --docker-deploy to promote a sandbox-built app through the workspace Docker Deploy runtime.",
+        "Use sandbox publish --docker-deploy to promote a sandbox-built app through the recommended workspace Docker Deploy runtime.",
+        "Use sandbox publish without --docker-deploy only when you explicitly need the standard MIOSA Deploy runtime.",
         "Use sandbox env and sandbox db attach for durable encrypted runtime env; do not hand-write .env files.",
         "Use miosa sandbox ports <sandbox-id> --json before previewing to detect port conflicts.",
         "Use miosa sandbox metrics <sandbox-id> --json for readiness, timeout, and resource diagnostics.",
@@ -191,10 +191,11 @@ const manifest: CapabilitiesManifest = {
         "Durable hosted app with default URL, releases, env vars, logs, rollback, and domains.",
       status: "beta",
       list: "miosa apps list --json",
-      create: "miosa deploy --json",
+      create: "miosa deploy --docker-deploy --json",
       show: "miosa apps show <app-id-or-slug> --json",
       delete: "miosa apps destroy <app-id-or-slug> --force --json",
       notes: [
+        "Prefer Docker Deploy for production apps: miosa deploy --docker-deploy --json.",
         "Default URL should work independently of custom-domain DNS state.",
         "Use miosa deploy metrics <app-id> --json to inspect runtime instances, health timestamps, restarts, and usage.",
       ],
@@ -391,17 +392,17 @@ const manifest: CapabilitiesManifest = {
         },
         {
           command:
-            "miosa sandbox publish <sandbox-id> --path /workspace --slug <slug> --build-command \"npm run build\" --run-command \"npm run start\" --port 3000 --wait --timeout 900 --json",
+            "miosa sandbox publish <sandbox-id> --path /workspace --slug <slug> --build-command \"npm run build\" --run-command \"npm run start\" --port 3000 --docker-deploy --wait --timeout 900 --json",
           purpose:
-            "Promote the working Next.js sandbox into durable app hosting.",
+            "Recommended: promote the working Next.js sandbox into the workspace Docker Deploy runtime.",
           json: true,
           wait: true,
         },
         {
           command:
-            "miosa sandbox publish <sandbox-id> --path /workspace --slug <slug> --build-command \"npm run build\" --run-command \"npm run start\" --port 3000 --docker-deploy --wait --timeout 900 --json",
+            "miosa sandbox publish <sandbox-id> --path /workspace --slug <slug> --build-command \"npm run build\" --run-command \"npm run start\" --port 3000 --wait --timeout 900 --json",
           purpose:
-            "Promote the same sandbox-built app through the workspace Docker Deploy runtime.",
+            "Use standard MIOSA Deploy only when Docker Deploy is not desired for this app.",
           json: true,
           wait: true,
         },
@@ -513,8 +514,9 @@ const manifest: CapabilitiesManifest = {
       steps: [
         {
           command:
-            "miosa sandbox publish <sandbox-id> --path /workspace --slug <slug> --wait --json",
-          purpose: "Create or update durable app release from sandbox files.",
+            "miosa sandbox publish <sandbox-id> --path /workspace --slug <slug> --docker-deploy --wait --json",
+          purpose:
+            "Recommended: create or update a durable app release from sandbox files on Docker Deploy.",
           json: true,
           wait: true,
         },

src/commands/deploy.ts

@@ -338,7 +338,7 @@ export function register(program: Command): void {
   const deploy = program
     .command("deploy")
     .alias("launch")
-    .description("Deploy a GitHub repo to MIOSA Deploy")
+    .description("Deploy a GitHub repo; use --docker-deploy for the recommended production runtime")
     .option(
       "--docker-deploy",
       "Create the deployment on this workspace's dedicated Docker Deploy runtime",
@@ -347,8 +347,8 @@ export function register(program: Command): void {
       "after",
       `
 Examples:
+  miosa deploy --docker-deploy       Recommended: deploy current directory to Docker Deploy
   miosa deploy                       Deploy current directory (auto-detects framework)
-  miosa deploy --docker-deploy       Deploy current directory to Docker Deploy
   miosa deploy list                  List all deployments
   miosa deploy logs                  Tail build logs for this project
   miosa deploy redeploy              Trigger a new build

src/commands/new.ts

@@ -95,7 +95,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
     ],
     next: [
       "miosa sandbox deploy . --wait",
-      "miosa sandbox publish <sandbox-id> --slug my-app --wait",
+      "miosa sandbox publish <sandbox-id> --slug my-app --docker-deploy --wait",
     ],
   },
   "nextjs-postgres": {
@@ -171,7 +171,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
     next: [
       "miosa databases create --engine postgres --wait",
       "miosa sandbox deploy . --template nextjs-postgres --wait",
-      "miosa sandbox publish <sandbox-id> --database existing:<db-id> --slug my-app --wait",
+      "miosa sandbox publish <sandbox-id> --database existing:<db-id> --slug my-app --docker-deploy --wait",
     ],
   },
   "vite-react": {